feat: overlay mount with local linkspan origin

Add SFTP subsystem to SSH server, start SSH at boot, forward both
ports through devtunnel. Parse port map from devtunnel connect output.
Add mount.setup_overlay workflow action (sshfs + fuse-overlayfs).
Add in-memory metadata store API. Read CS_LOCAL_* env vars for overlay
workflow variables. Remove vscode.create_session action (SSH is always-on).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yasithdev

go.mod

@@ -24,6 +24,7 @@ require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.6 // indirect
 	github.com/klauspost/reedsolomon v1.12.0 // indirect
+	github.com/kr/fs v0.1.0 // indirect
 	github.com/kr/text v0.2.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.0 // indirect
 	github.com/pion/dtls/v2 v2.2.7 // indirect
@@ -33,6 +34,7 @@ require (
 	github.com/pion/transport/v3 v3.0.1 // indirect
 	github.com/pires/go-proxyproto v0.7.0 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pkg/sftp v1.13.10 // indirect
 	github.com/quic-go/quic-go v0.55.0 // indirect
 	github.com/rodaine/table v1.2.0 // indirect
 	github.com/rogpeppe/go-internal v1.12.0 // indirect

go.sum

@@ -63,6 +63,8 @@ github.com/klauspost/cpuid/v2 v2.2.6 h1:ndNyv040zDGIDh8thGkXYjnFtiN02M1PVVF+JE/4
 github.com/klauspost/cpuid/v2 v2.2.6/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws=
 github.com/klauspost/reedsolomon v1.12.0 h1:I5FEp3xSwVCcEh3F5A7dofEfhXdF/bWhQWPH+XwBFno=
 github.com/klauspost/reedsolomon v1.12.0/go.mod h1:EPLZJeh4l27pUGC3aXOjheaoh1I9yut7xTURiW3LQ9Y=
+github.com/kr/fs v0.1.0 h1:Jskdu9ieNAYnjxsi0LbQp1ulIKZV1LAFgK1tWhpZgl8=
+github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -87,6 +89,8 @@ github.com/pires/go-proxyproto v0.7.0 h1:IukmRewDQFWC7kfnb66CSomk2q/seBuilHBYFwy
 github.com/pires/go-proxyproto v0.7.0/go.mod h1:Vz/1JPY/OACxWGQNIRY2BeyDmpoaWmEP40O9LbuiFR4=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/sftp v1.13.10 h1:+5FbKNTe5Z9aspU88DPIKJ9z2KZoaGCu6Sr6kKR/5mU=
+github.com/pkg/sftp v1.13.10/go.mod h1:bJ1a7uDhrX/4OII+agvy28lzRvQrmIQuaHrcI1HbeGA=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=

internal/workflow/actions.go

@@ -4,42 +4,22 @@ import (
 	"fmt"
 	"log"
 	"os/exec"
+	"strconv"
 	"strings"
 
+	"github.com/cyber-shuttle/linkspan/subsystems/mount"
 	tunnel "github.com/cyber-shuttle/linkspan/subsystems/tunnel"
-	vscode "github.com/cyber-shuttle/linkspan/subsystems/vscode"
-	utils "github.com/cyber-shuttle/linkspan/utils"
 )
 
 // registerBuiltinActions populates a Registry with all built-in action wrappers.
 func registerBuiltinActions(r *Registry) {
-	r.Register("vscode.create_session", actionVSCodeCreateSession)
 	r.Register("tunnel.devtunnel_create", actionDevTunnelCreate)
 	r.Register("tunnel.devtunnel_forward", actionDevTunnelForward)
 	r.Register("tunnel.devtunnel_delete", actionDevTunnelDelete)
 	r.Register("tunnel.devtunnel_connect", actionDevTunnelConnect)
 	r.Register("tunnel.frp_proxy_create", actionFrpProxyCreate)
 	r.Register("shell.exec", actionShellExec)
-}
-
-// --- vscode.create_session ---
-
-func actionVSCodeCreateSession(params map[string]any) (*ActionResult, error) {
-	port, err := utils.GetAvailablePort()
-	if err != nil {
-		return nil, fmt.Errorf("get available port: %w", err)
-	}
-
-	sessionID := fmt.Sprintf("wf-%d", port)
-	addr := fmt.Sprintf(":%d", port)
-
-	vscode.StartSSHServerForVSCodeConnection(sessionID, addr)
-
-	result := ActionResult{
-		"session_id": sessionID,
-		"bind_port":  port,
-	}
-	return &result, nil
+	r.Register("mount.setup_overlay", actionSetupOverlay)
 }
 
 // --- tunnel.devtunnel_create ---
@@ -58,8 +38,9 @@ func actionDevTunnelCreate(params map[string]any) (*ActionResult, error) {
 		return nil, fmt.Errorf("tunnel.devtunnel_create: auth_token is required")
 	}
 	serverPort := toInt(params["server_port"])
+	sshPort := toInt(params["ssh_port"])
 
-	conn, err := tunnel.DevTunnelCreate(tunnelName, expiration, authToken, serverPort)
+	conn, err := tunnel.DevTunnelCreate(tunnelName, expiration, authToken, serverPort, sshPort)
 	if err != nil {
 		return nil, err
 	}
@@ -69,6 +50,7 @@ func actionDevTunnelCreate(params map[string]any) (*ActionResult, error) {
 		"tunnel_name":    conn.DevTunnelInfo.TunnelName,
 		"connection_url": conn.ConnectionURL,
 		"token":          conn.Token,
+		"ssh_port":       sshPort,
 	}
 	return &result, nil
 }
@@ -123,13 +105,20 @@ func actionDevTunnelConnect(params map[string]any) (*ActionResult, error) {
 		return nil, fmt.Errorf("tunnel.devtunnel_connect: access_token is required")
 	}
 
-	cmdID, err := tunnel.DevTunnelConnect(tunnelID, accessToken)
+	cmdID, portMap, err := tunnel.DevTunnelConnect(tunnelID, accessToken)
 	if err != nil {
 		return nil, err
 	}
 
+	// Convert port map to string-keyed map for template access
+	portMapStr := make(map[string]any)
+	for remote, local := range portMap {
+		portMapStr[strconv.Itoa(remote)] = local
+	}
+
 	result := ActionResult{
 		"command_id": cmdID,
+		"port_map":   portMapStr,
 	}
 	return &result, nil
 }
@@ -183,6 +172,35 @@ func actionShellExec(params map[string]any) (*ActionResult, error) {
 	return &result, nil
 }
 
+// --- mount.setup_overlay ---
+
+func actionSetupOverlay(params map[string]any) (*ActionResult, error) {
+	sessionID, _ := params["session_id"].(string)
+	if sessionID == "" {
+		return nil, fmt.Errorf("mount.setup_overlay: session_id is required")
+	}
+	localWorkspace, _ := params["local_workspace"].(string)
+	if localWorkspace == "" {
+		return nil, fmt.Errorf("mount.setup_overlay: local_workspace is required")
+	}
+	localSshPort := toInt(params["local_ssh_port"])
+	if localSshPort == 0 {
+		return nil, fmt.Errorf("mount.setup_overlay: local_ssh_port is required")
+	}
+
+	overlay, err := mount.SetupOverlay(sessionID, localSshPort, localWorkspace)
+	if err != nil {
+		return nil, fmt.Errorf("mount.setup_overlay: %w", err)
+	}
+
+	result := ActionResult{
+		"merged_path": overlay.MergedDir,
+		"cache_path":  overlay.CacheDir,
+		"source_path": overlay.SourceDir,
+	}
+	return &result, nil
+}
+
 // --- helpers ---
 
 // toInt converts a param value to int, handling YAML's default float64/int types.

main.go

@@ -5,12 +5,14 @@ import (
 	"encoding/json"
 	"flag"
 	"fmt"
+	"io"
 	"log"
 	"net"
 	"net/http"
 	"os"
 	"os/signal"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 
@@ -20,6 +22,7 @@ import (
 	tunnel "github.com/cyber-shuttle/linkspan/subsystems/tunnel"
 	"github.com/cyber-shuttle/linkspan/subsystems/vfs"
 	vscode "github.com/cyber-shuttle/linkspan/subsystems/vscode"
+	utils "github.com/cyber-shuttle/linkspan/utils"
 	"github.com/gorilla/mux"
 )
 
@@ -29,6 +32,12 @@ var (
 	vfsMountProvider *vfs.MountProvider
 )
 
+// In-memory metadata store (key → arbitrary JSON value).
+var (
+	metadataStore = make(map[string]json.RawMessage)
+	metadataMu    sync.RWMutex
+)
+
 func main() {
 
 	// parse CLI flags
@@ -136,6 +145,45 @@ func main() {
 		json.NewEncoder(w).Encode(workflowEngine.Status())
 	}).Methods("GET")
 
+	// Metadata store — in-memory key-value for shared state
+	api.HandleFunc("/metadata", func(w http.ResponseWriter, r *http.Request) {
+		metadataMu.RLock()
+		defer metadataMu.RUnlock()
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(metadataStore)
+	}).Methods("GET")
+
+	api.HandleFunc("/metadata/{key:.+}", func(w http.ResponseWriter, r *http.Request) {
+		key := mux.Vars(r)["key"]
+		switch r.Method {
+		case "GET":
+			metadataMu.RLock()
+			val, ok := metadataStore[key]
+			metadataMu.RUnlock()
+			if !ok {
+				http.NotFound(w, r)
+				return
+			}
+			w.Header().Set("Content-Type", "application/json")
+			w.Write(val)
+		case "PUT":
+			body, err := io.ReadAll(r.Body)
+			if err != nil {
+				http.Error(w, err.Error(), http.StatusBadRequest)
+				return
+			}
+			metadataMu.Lock()
+			metadataStore[key] = json.RawMessage(body)
+			metadataMu.Unlock()
+			w.WriteHeader(http.StatusNoContent)
+		case "DELETE":
+			metadataMu.Lock()
+			delete(metadataStore, key)
+			metadataMu.Unlock()
+			w.WriteHeader(http.StatusNoContent)
+		}
+	}).Methods("GET", "PUT", "DELETE")
+
 	// Use the configured server host and port from CLI flags.
 	// Port 0 means "let the OS pick a free port".
 	serverPort := *serverPortFlag
@@ -163,6 +211,16 @@ func main() {
 	}
 	log.Printf("listening on %s:%d", serverHost, serverPort)
 
+	// Start SSH daemon on a random port
+	sshPort, err := utils.GetAvailablePort()
+	if err != nil {
+		log.Fatalf("failed to get available port for SSH: %v", err)
+	}
+	sshAddr := fmt.Sprintf("0.0.0.0:%d", sshPort)
+	sshSessionID := fmt.Sprintf("main-%d", sshPort)
+	vscode.StartSSHServerForVSCodeConnection(sshSessionID, sshAddr)
+	log.Printf("SSH server listening on %s", sshAddr)
+
 	// Run workflow if specified. Use "-" to read from stdin.
 	if *workflowFile != "" {
 		var wf *workflow.WorkflowConfig
@@ -176,10 +234,16 @@ func main() {
 			log.Fatalf("workflow: %v", err)
 		}
 		workflowEngine = workflow.NewEngine(workflow.DefaultRegistry(), map[string]any{
-			"Timestamp":       time.Now().Unix(),
-			"ServerPort":      serverPort,
-			"ServerHost":      serverHost,
-			"TunnelAuthToken": *tunnelAuthToken,
+			"Timestamp":        time.Now().Unix(),
+			"ServerPort":       serverPort,
+			"SshPort":          sshPort,
+			"ServerHost":       serverHost,
+			"TunnelAuthToken":  *tunnelAuthToken,
+			"LocalTunnelID":    os.Getenv("CS_LOCAL_TUNNEL_ID"),
+			"LocalTunnelToken": os.Getenv("CS_LOCAL_TUNNEL_TOKEN"),
+			"LocalSshPort":     os.Getenv("CS_LOCAL_SSH_PORT"),
+			"LocalWorkspace":   os.Getenv("CS_LOCAL_WORKSPACE"),
+			"SessionID":        os.Getenv("CS_SESSION_ID"),
 		})
 		go func() {
 			if err := workflowEngine.Run(wf); err != nil {
@@ -218,7 +282,7 @@ func main() {
 
 				ch := make(chan error, 1)
 				go func() {
-					conn, err := tunnel.DevTunnelCreate(tunnelName, "1d", authToken, serverPort)
+					conn, err := tunnel.DevTunnelCreate(tunnelName, "1d", authToken, serverPort, sshPort)
 					if err != nil {
 						ch <- err
 						return

subsystems/mount/overlay.go

@@ -0,0 +1,101 @@
+package mount
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"os/exec"
+	"path/filepath"
+
+	pm "github.com/cyber-shuttle/linkspan/internal/process"
+)
+
+// OverlayMount holds the state for a single overlay filesystem setup.
+type OverlayMount struct {
+	SessionID    string
+	SourceDir    string // sshfs mount of local workspace (lower)
+	CacheDir     string // mutagen-warmed cache (upper)
+	WorkDir      string // overlayfs workdir
+	MergedDir    string // final merged view
+	SshfsCmdID   string // process manager ID for sshfs
+	OverlayCmdID string // process manager ID for fuse-overlayfs
+}
+
+// SetupOverlay creates the overlay filesystem:
+// 1. sshfs mounts the local workspace via tunnel
+// 2. fuse-overlayfs merges lower (sshfs) + upper (cache)
+func SetupOverlay(sessionID string, localSshPort int, localWorkspace string) (*OverlayMount, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return nil, fmt.Errorf("overlay: get home dir: %w", err)
+	}
+
+	m := &OverlayMount{
+		SessionID: sessionID,
+		SourceDir: filepath.Join(os.TempDir(), fmt.Sprintf("cs-source-%s", sessionID)),
+		CacheDir:  filepath.Join(home, "sessions", sessionID),
+		WorkDir:   filepath.Join(home, "sessions", sessionID, ".overlay-work"),
+		MergedDir: filepath.Join(home, "overlay", sessionID),
+	}
+
+	// Create all directories
+	for _, dir := range []string{m.SourceDir, m.CacheDir, m.WorkDir, m.MergedDir} {
+		if err := os.MkdirAll(dir, 0755); err != nil {
+			return nil, fmt.Errorf("overlay: mkdir %s: %w", dir, err)
+		}
+	}
+
+	// 1. sshfs mount local workspace via tunnel
+	sshfsArgs := []string{
+		fmt.Sprintf("localhost:%s", localWorkspace),
+		m.SourceDir,
+		"-p", fmt.Sprintf("%d", localSshPort),
+		"-o", "StrictHostKeyChecking=no",
+		"-o", "UserKnownHostsFile=/dev/null",
+		"-o", "reconnect",
+		"-o", "ServerAliveInterval=15",
+		"-o", "ServerAliveCountMax=3",
+	}
+
+	sshfsCmd := exec.Command("sshfs", sshfsArgs...)
+	sshfsCmdID, err := pm.GlobalProcessManager.Start(sshfsCmd)
+	if err != nil {
+		return nil, fmt.Errorf("overlay: start sshfs: %w", err)
+	}
+	m.SshfsCmdID = sshfsCmdID
+	log.Printf("[overlay] sshfs mounted %s on port %d → %s", localWorkspace, localSshPort, m.SourceDir)
+
+	// 2. fuse-overlayfs
+	overlayArgs := []string{
+		"-o", fmt.Sprintf("lowerdir=%s,upperdir=%s,workdir=%s", m.SourceDir, m.CacheDir, m.WorkDir),
+		m.MergedDir,
+	}
+
+	overlayCmd := exec.Command("fuse-overlayfs", overlayArgs...)
+	overlayCmdID, err := pm.GlobalProcessManager.Start(overlayCmd)
+	if err != nil {
+		// Clean up sshfs on failure
+		_ = pm.GlobalProcessManager.Kill(sshfsCmdID)
+		return nil, fmt.Errorf("overlay: start fuse-overlayfs: %w", err)
+	}
+	m.OverlayCmdID = overlayCmdID
+	log.Printf("[overlay] fuse-overlayfs merged at %s (lower=%s, upper=%s)", m.MergedDir, m.SourceDir, m.CacheDir)
+
+	return m, nil
+}
+
+// Teardown unmounts the overlay and sshfs.
+func (m *OverlayMount) Teardown() {
+	if m.OverlayCmdID != "" {
+		_ = pm.GlobalProcessManager.Kill(m.OverlayCmdID)
+		log.Printf("[overlay] stopped fuse-overlayfs for %s", m.SessionID)
+	}
+	// fusermount -u to cleanly unmount
+	_ = exec.Command("fusermount", "-u", m.MergedDir).Run()
+	_ = exec.Command("fusermount", "-u", m.SourceDir).Run()
+
+	if m.SshfsCmdID != "" {
+		_ = pm.GlobalProcessManager.Kill(m.SshfsCmdID)
+		log.Printf("[overlay] stopped sshfs for %s", m.SessionID)
+	}
+}

subsystems/tunnel/api.go

@@ -88,7 +88,7 @@ func CreateDevTunnel(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	conn, err := DevTunnelCreate(req.TunnelName, req.Expiration, req.AuthToken, req.ServerPort)
+	conn, err := DevTunnelCreate(req.TunnelName, req.Expiration, req.AuthToken, req.ServerPort, 0)
 	if err != nil {
 		utils.RespondJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
 		return