feat(sync): configurable sync direction (spec.sync.direction: bi|up|down)

A single bidirectional folder carries both inputs (code, local->pod) and
outputs (results, pod->local), so a bad local write can clobber
pod-generated data. Per-path direction inside one folder is impossible
in Syncthing (.stignore lives in the directory; per-path folder types
were rejected upstream), so the direction is a per-folder setting:

- spec.sync.direction: bi (default) | up (local sendonly, pod
  receiveonly) | down (pod sendonly, local receiveonly — a local write
  can never clobber pod results).
- `okdev sync --mode` now defaults to the configured direction; an
  explicit flag still wins. Mode values are validated.
- `okdev up` starts sync in the configured direction and skips the
  two-phase bootstrap for directional folders (one side is already
  sendonly, so the final folder types are safe from the first start).
  Direction is part of the sync config hash, so editing it takes effect
  on the next up; explicit "bi" hashes like the legacy default to avoid
  a restart on upgrade.
- `up --reset-workspace` and `sync reset-remote` are rejected with
  direction "down": they reseed the remote from local, which would sync
  back as deletions over the pod's data.
- `status --details` shows the direction; docs cover choosing a
  direction and keeping generated outputs out of the synced path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: acmore

docs/command-reference.md

@@ -304,6 +304,7 @@ agents can react without launching a diagnostic chain on every blip:
 ### `okdev sync [--mode up|down|bi] [--foreground] [--reset] [--dry-run]`
 
 - Advanced command. Starts detached background sync by default; use `--foreground` for sync debugging, or explicit one-way sync (`up`/`down`).
+- `--mode` defaults to `spec.sync.direction` from the config (falling back to `bi`); an explicit flag overrides it for that invocation. See `spec.sync.direction` in the config manifest for choosing a persistent direction — `down` makes the pod the authority so local writes can never clobber pod-generated results.
 - For default `--mode bi`, no-op when background sync is already active for the session.
 - `--background`: explicitly request detached background mode.
 - `--reset`: check local-to-hub sync and mesh receiver health, then reset only what is broken. Skips the local sync teardown when the primary sync is already healthy. For sessions with mesh receivers, probes each receiver and re-runs mesh setup only when broken or disconnected receivers are found.

docs/config-manifest.md

@@ -233,6 +233,7 @@ spec:
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `engine` | `string` | — | Sync engine (currently only `syncthing`) |
+| `direction` | `string` | `bi` | Sync direction for the local↔pod folder: `bi` (bidirectional), `up` (local is the authority: local sendonly, pod receiveonly), `down` (pod is the authority: pod sendonly, local receiveonly) |
 | `paths` | `[]string` | — | Mappings in `local:remote` format (max 1 entry) |
 | `syncthing.version` | `string` | `v1.29.7` | Local Syncthing binary version |
 | `syncthing.autoInstall` | `bool` | `true` | Auto-install local Syncthing |
@@ -242,7 +243,15 @@ spec:
 | `syncthing.compression` | `bool` | `false` | Use Syncthing `always` compression for peer connections instead of the default `metadata` mode |
 | `syncthing.versioningDays` | `int` | `30` | Keep files overwritten or deleted by sync in `.stversions` for this many days (staggered versioning, both sides); `0` disables |
 
-**Validation:** `engine` must be `syncthing`; each `paths[]` entry must be `local:remote`; `versioningDays` must be `>= 0`.
+**Validation:** `engine` must be `syncthing`; `direction` must be `bi`, `up`, or `down`; each `paths[]` entry must be `local:remote`; `versioningDays` must be `>= 0`.
+
+**Sync direction.** `direction` applies to the whole synced folder — per-path direction inside one folder is impossible with Syncthing (ignore rules live in the directory itself; per-path folder types were rejected upstream). Pick the direction by what the folder carries:
+
+- `bi` (default): source code you edit on both sides. Either side can overwrite the other, so **keep generated outputs (results, checkpoints, logs) out of the synced path** — write them to a non-synced location and fetch with `okdev cp` or `okdev jobs logs`. Versioning (`.stversions/`) is the safety net, not the design.
+- `up`: the folder is a code drop. Nothing the pod writes can ever touch local files; pod-side writes into the folder are flagged by Syncthing but not propagated.
+- `down`: the folder carries pod-generated results. A stray local write (for example an empty file from a failed redirect) can never clobber the pod's data. `okdev up --reset-workspace` and `okdev sync reset-remote` are rejected in this direction because they reseed the remote from local.
+
+An explicit `okdev sync --mode` overrides the configured direction for that invocation. Changing `direction` takes effect on the next `okdev up` (it restarts sync with the new folder types). Mesh receiver pods are always receiveonly regardless of direction.
 
 Local ignore rules come from the synced workspace's `.stignore`. `okdev init` writes a starter `.stignore` for built-in templates, and `okdev up` creates one with default patterns if the local sync root does not already have one. Editing `.stignore` takes effect automatically as Syncthing notices the change, but it does not remove files that were already synced to the remote workspace. For faster initial syncs, consider ignoring large generated build outputs or local test artifacts such as `debug/`, `release/`, caches, and dataset directories when they do not need to exist remotely.
 
@@ -254,6 +263,7 @@ The `syncthing.version` field controls the local binary on your machine. The Syn
 spec:
   sync:
     engine: syncthing
+    direction: bi
     syncthing:
       version: v1.29.7
       autoInstall: true

internal/cli/status_details.go

@@ -114,6 +114,7 @@ type detailedStatusSSH struct {
 
 type detailedStatusSync struct {
 	Engine             string             `json:"engine"`
+	Direction          string             `json:"direction,omitempty"`
 	Health             string             `json:"health,omitempty"`
 	HealthDetail       string             `json:"healthDetail,omitempty"`
 	ConfiguredPaths    []string           `json:"configuredPaths,omitempty"`
@@ -422,6 +423,7 @@ func buildDetailedSync(sessionName string, cfg *config.DevEnvironment, cfgPath s
 	}
 	detail := detailedStatusSync{
 		Engine:          engine,
+		Direction:       cfg.Spec.Sync.EffectiveDirection(),
 		ConfiguredPaths: summarizeConfiguredSyncPaths(cfg, cfgPath),
 	}
 	if engine != "syncthing" {
@@ -593,6 +595,9 @@ func printDetailedStatus(w io.Writer, detail detailedStatus) {
 
 	fmt.Fprintln(w, "\nSync:")
 	fmt.Fprintf(w, "- engine: %s\n", detail.Sync.Engine)
+	if detail.Sync.Direction != "" {
+		fmt.Fprintf(w, "- direction: %s (%s)\n", detail.Sync.Direction, modeSymbol(detail.Sync.Direction))
+	}
 	if detail.Sync.BackgroundStatus != "" {
 		status := detail.Sync.BackgroundStatus
 		if detail.Sync.BackgroundPID > 0 {

internal/cli/status_details_test.go

@@ -347,6 +347,7 @@ func TestPrintDetailedStatusIncludesSections(t *testing.T) {
 		},
 		Sync: detailedStatusSync{
 			Engine:             "syncthing",
+			Direction:          "down",
 			BackgroundStatus:   "running",
 			BackgroundPID:      123,
 			ConfiguredPaths:    []string{"/tmp/repo -> /workspace"},
@@ -391,6 +392,7 @@ func TestPrintDetailedStatusIncludesSections(t *testing.T) {
 		"SSH:",
 		"managed forward: running",
 		"Sync:",
+		"direction: down (<-)",
 		"background: running (pid 123)",
 		"conflicts: 2",
 		"./a.sync-conflict-1",

internal/cli/sync.go

@@ -16,6 +16,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/acmore/okdev/internal/config"
 	"github.com/acmore/okdev/internal/kube"
 	"github.com/acmore/okdev/internal/logx"
 	"github.com/acmore/okdev/internal/session"
@@ -72,6 +73,10 @@ func newSyncCmd(opts *Options) *cobra.Command {
 			if engine != "syncthing" {
 				return fmt.Errorf("unsupported sync engine %q (only syncthing is supported)", engine)
 			}
+			mode = resolveSyncMode(cmd.Flags().Changed("mode"), mode, cc.cfg.Spec.Sync.EffectiveDirection())
+			if err := validateSyncMode(mode); err != nil {
+				return err
+			}
 			if foreground && cmd.Flags().Changed("background") {
 				return fmt.Errorf("--background and --foreground cannot be used together")
 			}
@@ -166,7 +171,7 @@ func newSyncCmd(opts *Options) *cobra.Command {
 		},
 	}
 
-	cmd.Flags().StringVar(&mode, "mode", "bi", "Sync mode: up|down|bi")
+	cmd.Flags().StringVar(&mode, "mode", "bi", "Sync mode: up|down|bi (default: spec.sync.direction, or bi)")
 	cmd.Flags().BoolVar(&background, "background", true, "Run syncthing sync as a detached background process")
 	cmd.Flags().BoolVar(&foreground, "foreground", false, "Run syncthing sync in the foreground for troubleshooting")
 	cmd.Flags().BoolVar(&reset, "reset", false, "Check sync health and reset broken components")
@@ -179,6 +184,26 @@ func newSyncCmd(opts *Options) *cobra.Command {
 	return cmd
 }
 
+// resolveSyncMode picks the effective sync mode: an explicit --mode always
+// wins; otherwise the configured spec.sync.direction applies.
+func resolveSyncMode(flagSet bool, flagMode, configDirection string) string {
+	if flagSet {
+		return flagMode
+	}
+	return configDirection
+}
+
+// validateSyncMode accepts the documented modes plus the internal
+// "two-phase" bootstrap mode that `okdev up` spawns for fresh sessions.
+func validateSyncMode(mode string) error {
+	switch mode {
+	case "up", "down", "bi", "two-phase":
+		return nil
+	default:
+		return fmt.Errorf("invalid sync mode %q: must be one of up, down, bi", mode)
+	}
+}
+
 func newSyncResetRemoteCmd(opts *Options) *cobra.Command {
 	return &cobra.Command{
 		Use:   "reset-remote",
@@ -197,6 +222,12 @@ synced workspace subtree is cleared.`,
 			if err := ensureExistingSessionOwnership(cc.opts, cc.kube, cc.namespace, cc.sessionName); err != nil {
 				return err
 			}
+			if cc.cfg.Spec.Sync.EffectiveDirection() == config.SyncDirectionDown {
+				// reset-remote clears the remote and reseeds it from local;
+				// with direction "down" the pod is the authority and local
+				// is receiveonly — the wipe would sync back as deletions.
+				return fmt.Errorf("sync reset-remote conflicts with spec.sync.direction: down (the pod is the sync authority)")
+			}
 			pairs, err := syncengine.ParsePairs(cc.cfg.Spec.Sync.Paths, cc.cfg.EffectiveWorkspaceMountPath(cc.cfgPath))
 			if err != nil {
 				return fmt.Errorf("parse sync paths: %w", err)

internal/cli/sync_test.go

@@ -417,6 +417,47 @@ func TestSyncthingSessionConfigHashTracksSyncSettings(t *testing.T) {
 	}
 }
 
+func TestSyncthingSessionConfigHashTracksDirection(t *testing.T) {
+	cfg := &config.DevEnvironment{}
+	cfg.SetDefaults()
+	base := syncthingSessionConfigHash(cfg, "/tmp/local", "/workspace")
+
+	// Explicit "bi" hashes identically to the legacy empty value so
+	// upgrading okdev (or spelling out the default) does not force a sync
+	// restart on existing sessions.
+	cfg.Spec.Sync.Direction = "bi"
+	if got := syncthingSessionConfigHash(cfg, "/tmp/local", "/workspace"); got != base {
+		t.Fatal("explicit bi direction must hash like the legacy default")
+	}
+
+	cfg.Spec.Sync.Direction = "down"
+	if got := syncthingSessionConfigHash(cfg, "/tmp/local", "/workspace"); got == base {
+		t.Fatal("expected direction change to affect sync config hash")
+	}
+}
+
+func TestResolveSyncMode(t *testing.T) {
+	// Explicit --mode wins over the configured direction.
+	if got := resolveSyncMode(true, "up", "down"); got != "up" {
+		t.Fatalf("explicit flag must win, got %q", got)
+	}
+	// Without the flag, spec.sync.direction applies.
+	if got := resolveSyncMode(false, "bi", "down"); got != "down" {
+		t.Fatalf("config direction must apply, got %q", got)
+	}
+}
+
+func TestValidateSyncMode(t *testing.T) {
+	for _, ok := range []string{"up", "down", "bi", "two-phase"} {
+		if err := validateSyncMode(ok); err != nil {
+			t.Fatalf("mode %q should validate, got %v", ok, err)
+		}
+	}
+	if err := validateSyncMode("push"); err == nil {
+		t.Fatal("expected invalid mode to be rejected")
+	}
+}
+
 func TestProcStatIsZombie(t *testing.T) {
 	if !procStatIsZombie([]byte("123 (okdev) Z 1 2 3")) {
 		t.Fatal("expected zombie proc stat to be detected")

internal/cli/syncthing.go

@@ -2465,9 +2465,14 @@ func resetRemoteWorkspace(ctx context.Context, k interface {
 }
 
 type syncthingSessionConfigState struct {
-	Engine                string `json:"engine"`
-	LocalPath             string `json:"localPath"`
-	RemotePath            string `json:"remotePath"`
+	Engine     string `json:"engine"`
+	LocalPath  string `json:"localPath"`
+	RemotePath string `json:"remotePath"`
+	// Direction is part of the hash so editing spec.sync.direction makes
+	// the next `okdev up` restart sync with the new folder types. The
+	// default "bi" is hashed as the empty legacy value to avoid a
+	// restart on upgrade for existing sessions.
+	Direction             string `json:"direction,omitempty"`
 	WatcherDelaySeconds   int    `json:"watcherDelaySeconds,omitempty"`
 	RescanIntervalSeconds int    `json:"rescanIntervalSeconds,omitempty"`
 	RelaysEnabled         bool   `json:"relaysEnabled,omitempty"`
@@ -2479,10 +2484,15 @@ func syncthingSessionConfigHash(cfg *config.DevEnvironment, localPath, remotePat
 	if cfg == nil {
 		return ""
 	}
+	direction := cfg.Spec.Sync.EffectiveDirection()
+	if direction == config.SyncDirectionBi {
+		direction = ""
+	}
 	state := syncthingSessionConfigState{
 		Engine:                strings.TrimSpace(cfg.Spec.Sync.Engine),
 		LocalPath:             localPath,
 		RemotePath:            remotePath,
+		Direction:             direction,
 		WatcherDelaySeconds:   cfg.Spec.Sync.Syncthing.WatcherDelaySeconds,
 		RescanIntervalSeconds: cfg.Spec.Sync.Syncthing.RescanIntervalSeconds,
 		RelaysEnabled:         cfg.Spec.Sync.Syncthing.RelaysEnabled,

internal/cli/up.go

@@ -156,6 +156,13 @@ func upValidate(cmd *cobra.Command, opts *Options, flags upOptions) (*upState, e
 	if cmd.Flags().Changed("tmux") && cmd.Flags().Changed("no-tmux") {
 		return nil, fmt.Errorf("--tmux and --no-tmux cannot be used together")
 	}
+	if flags.resetWorkspace && cc.cfg.Spec.Sync.EffectiveDirection() == config.SyncDirectionDown {
+		// reset-workspace clears the remote and reseeds it from local; with
+		// direction "down" the pod is the authority and local is
+		// receiveonly, so the combination would wipe the remote and then
+		// pull the deletions back over the local files.
+		return nil, fmt.Errorf("--reset-workspace conflicts with spec.sync.direction: down (the pod is the sync authority); remove the flag or switch direction")
+	}
 	enableTmux := cc.cfg.Spec.SSH.PersistentSessionEnabled()
 	if cmd.Flags().Changed("tmux") {
 		enableTmux = flags.tmux
@@ -1092,12 +1099,15 @@ func upSetupSync(state *upState, target workload.TargetRef) (string, string, str
 		}
 		configChanged = changed
 	}
+	direction := state.command.cfg.Spec.Sync.EffectiveDirection()
 	active := syncthingSessionActive(state.command.sessionName)
 	restartRequired := state.flags.resetWorkspace || configChanged || !active
-	startMode = syncStartMode(state.flags.resetWorkspace, targetReset, hasConfigState, configChanged, active)
+	startMode = syncStartMode(direction, state.flags.resetWorkspace, targetReset, hasConfigState, configChanged, active)
 	// Signal waitForInitialSync to probe the remote folder type for an
-	// incomplete bootstrap, reusing the port-forward it already opens.
-	bootstrapResume = len(state.syncPairs) == 1 && hasConfigState && !state.flags.resetWorkspace && !targetReset
+	// incomplete bootstrap, reusing the port-forward it already opens. Only
+	// meaningful for bi: directional folders never run the two-phase
+	// bootstrap, so there is nothing to resume.
+	bootstrapResume = len(state.syncPairs) == 1 && hasConfigState && !state.flags.resetWorkspace && !targetReset && direction == config.SyncDirectionBi
 	if restartRequired {
 		if err := refreshSyncthingSessionProcesses(state.command.sessionName); err != nil {
 			return "", "", "", false, fmt.Errorf("refresh local syncthing session state: %w", err)
@@ -1832,7 +1842,15 @@ func modeSymbol(mode string) string {
 	}
 }
 
-func syncStartMode(resetWorkspace, targetReset, hasConfigState, configChanged, active bool) string {
+func syncStartMode(direction string, resetWorkspace, targetReset, hasConfigState, configChanged, active bool) string {
+	// A directional folder never needs the two-phase bootstrap: that
+	// protocol exists to protect the remote from the local side's initial
+	// emptiness before flipping both sides to sendreceive. With up/down one
+	// side is already sendonly, so the final folder types are safe from the
+	// first start.
+	if direction == config.SyncDirectionUp || direction == config.SyncDirectionDown {
+		return direction
+	}
 	switch {
 	case resetWorkspace:
 		return "two-phase"

internal/cli/up_ui_test.go

@@ -119,23 +119,31 @@ func TestSyncHelpers(t *testing.T) {
 func TestSyncStartMode(t *testing.T) {
 	cases := []struct {
 		name           string
+		direction      string
 		resetWorkspace bool
 		targetReset    bool
 		hasConfigState bool
 		configChanged  bool
 		active         bool
 		want           string
 	}{
-		{name: "first bootstrap", hasConfigState: false, active: false, want: "two-phase"},
-		{name: "explicit reset", resetWorkspace: true, hasConfigState: true, configChanged: true, active: true, want: "two-phase"},
-		{name: "target recreated", targetReset: true, hasConfigState: true, active: false, want: "two-phase"},
-		{name: "config changed on active session", hasConfigState: true, configChanged: true, active: true, want: "bi"},
-		{name: "daemon recovery", hasConfigState: true, active: false, want: "bi"},
-		{name: "steady state", hasConfigState: true, active: true, want: "bi"},
+		{name: "first bootstrap", direction: "bi", hasConfigState: false, active: false, want: "two-phase"},
+		{name: "explicit reset", direction: "bi", resetWorkspace: true, hasConfigState: true, configChanged: true, active: true, want: "two-phase"},
+		{name: "target recreated", direction: "bi", targetReset: true, hasConfigState: true, active: false, want: "two-phase"},
+		{name: "config changed on active session", direction: "bi", hasConfigState: true, configChanged: true, active: true, want: "bi"},
+		{name: "daemon recovery", direction: "bi", hasConfigState: true, active: false, want: "bi"},
+		{name: "steady state", direction: "bi", hasConfigState: true, active: true, want: "bi"},
+		// Directional folders skip the two-phase bootstrap entirely: one
+		// side is already sendonly, so the final types are safe from the
+		// first start.
+		{name: "up direction fresh", direction: "up", hasConfigState: false, active: false, want: "up"},
+		{name: "up direction target reset", direction: "up", targetReset: true, hasConfigState: true, active: false, want: "up"},
+		{name: "down direction fresh", direction: "down", hasConfigState: false, active: false, want: "down"},
+		{name: "down direction steady", direction: "down", hasConfigState: true, active: true, want: "down"},
 	}
 
 	for _, tc := range cases {
-		if got := syncStartMode(tc.resetWorkspace, tc.targetReset, tc.hasConfigState, tc.configChanged, tc.active); got != tc.want {
+		if got := syncStartMode(tc.direction, tc.resetWorkspace, tc.targetReset, tc.hasConfigState, tc.configChanged, tc.active); got != tc.want {
 			t.Fatalf("%s: got %q want %q", tc.name, got, tc.want)
 		}
 	}

internal/config/config.go

@@ -140,11 +140,39 @@ type MetadataMap struct {
 	Labels map[string]string `yaml:"labels"`
 }
 
+// Sync directions; see SyncSpec.Direction.
+const (
+	SyncDirectionBi   = "bi"
+	SyncDirectionUp   = "up"
+	SyncDirectionDown = "down"
+)
+
 type SyncSpec struct {
-	Paths         []string      `yaml:"paths"`
-	PreservePaths []string      `yaml:"preservePaths"`
-	Engine        string        `yaml:"engine"`
-	Syncthing     SyncthingSpec `yaml:"syncthing"`
+	Paths         []string `yaml:"paths"`
+	PreservePaths []string `yaml:"preservePaths"`
+	Engine        string   `yaml:"engine"`
+	// Direction sets the syncthing folder types on the local<->pod edge:
+	//   bi   — both sides sendreceive (default; either side can overwrite
+	//          the other — keep generated outputs out of the synced path)
+	//   up   — local sendonly, pod receiveonly: code push-only; nothing on
+	//          the pod can alter local files
+	//   down — local receiveonly, pod sendonly: the pod is the authority;
+	//          a local write can never clobber pod-side results
+	// Direction is per-folder by necessity: syncthing stores .stignore in
+	// the directory itself, so per-path direction inside one folder is
+	// impossible (per-path folder types were rejected upstream,
+	// syncthing/syncthing#8061). Mesh receivers stay receiveonly regardless.
+	Direction string        `yaml:"direction,omitempty"`
+	Syncthing SyncthingSpec `yaml:"syncthing"`
+}
+
+// EffectiveDirection resolves Direction, defaulting to bidirectional.
+func (s SyncSpec) EffectiveDirection() string {
+	d := strings.TrimSpace(s.Direction)
+	if d == "" {
+		return SyncDirectionBi
+	}
+	return d
 }
 
 type SyncthingSpec struct {
@@ -359,6 +387,11 @@ func (d *DevEnvironment) Validate() error {
 	if d.Spec.Sync.Syncthing.VersioningDays != nil && *d.Spec.Sync.Syncthing.VersioningDays < 0 {
 		return errors.New("spec.sync.syncthing.versioningDays must be >= 0")
 	}
+	switch strings.TrimSpace(d.Spec.Sync.Direction) {
+	case "", SyncDirectionBi, SyncDirectionUp, SyncDirectionDown:
+	default:
+		return fmt.Errorf("spec.sync.direction must be one of %s, %s, %s", SyncDirectionBi, SyncDirectionUp, SyncDirectionDown)
+	}
 	if err := validateSyncPaths(d.Spec.Sync.Paths); err != nil {
 		return err
 	}