npm - @openchambery/web - Versions diffs - 1.18.2-beta.2 → 1.18.2-beta.21 - Mend

@openchambery/web 1.18.2-beta.2 → 1.18.2-beta.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (148) hide show

package/dist/index.html CHANGED Viewed

@@ -552,7 +552,7 @@
         opacity: 0.72;
       }
     </style>
-    <script type="module" crossorigin src="/assets/main-CO6z5yRB.js"></script>
+    <script type="module" crossorigin src="/assets/main-CEqSDnE2.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-base-ui-CnHfUmDN.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-zustand-B4dlGEM2.js">
@@ -560,15 +560,15 @@
     <link rel="modulepreload" crossorigin href="/assets/vendor-pathe-vBmvQE8f.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-DLPElpoQ.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-tanstack-query-core-BWz0ose6.js">
-    <link rel="modulepreload" crossorigin href="/assets/persistence-DPNMIbF5.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-CBoBpJ1Z.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-l2R9muux.js">
+    <link rel="modulepreload" crossorigin href="/assets/persistence-D1lIuyqO.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-ZK_vkdzL.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-CewM6-g5.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-opencode-sdk-C07HQypa.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-aparajita-capacitor-secure-storage-CjQdwfjS.js">
-    <link rel="modulepreload" crossorigin href="/assets/gitApiHttp-D8j1qRH4.js">
-    <link rel="modulepreload" crossorigin href="/assets/terminalApi-tB3qLcfa.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BtWi74Pm.js">
-    <link rel="stylesheet" crossorigin href="/assets/src-oHrYIqHF.css">
+    <link rel="modulepreload" crossorigin href="/assets/gitApiHttp-BxGAFLTf.js">
+    <link rel="modulepreload" crossorigin href="/assets/terminalApi-DpiAJlil.js">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BXCt7ZsQ.js">
+    <link rel="stylesheet" crossorigin href="/assets/src-8kQFmtjw.css">
   </head>
   <body class="h-full bg-background text-foreground">
     <!-- Keep the startup layer outside #root. React replaces every child of

package/dist/mini-chat.html CHANGED Viewed

@@ -74,7 +74,7 @@
       }
     </style>
-    <script type="module" crossorigin src="/assets/miniChat-BZQwTZpx.js"></script>
+    <script type="module" crossorigin src="/assets/miniChat-CKucSAhg.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-base-ui-CnHfUmDN.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-zustand-B4dlGEM2.js">
@@ -82,15 +82,15 @@
     <link rel="modulepreload" crossorigin href="/assets/vendor-pathe-vBmvQE8f.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-DLPElpoQ.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-tanstack-query-core-BWz0ose6.js">
-    <link rel="modulepreload" crossorigin href="/assets/persistence-DPNMIbF5.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-CBoBpJ1Z.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-l2R9muux.js">
+    <link rel="modulepreload" crossorigin href="/assets/persistence-D1lIuyqO.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-ZK_vkdzL.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-CewM6-g5.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-opencode-sdk-C07HQypa.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-aparajita-capacitor-secure-storage-CjQdwfjS.js">
-    <link rel="modulepreload" crossorigin href="/assets/gitApiHttp-D8j1qRH4.js">
-    <link rel="modulepreload" crossorigin href="/assets/terminalApi-tB3qLcfa.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BtWi74Pm.js">
-    <link rel="stylesheet" crossorigin href="/assets/src-oHrYIqHF.css">
+    <link rel="modulepreload" crossorigin href="/assets/gitApiHttp-BxGAFLTf.js">
+    <link rel="modulepreload" crossorigin href="/assets/terminalApi-DpiAJlil.js">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BXCt7ZsQ.js">
+    <link rel="stylesheet" crossorigin href="/assets/src-8kQFmtjw.css">
   </head>
   <body class="h-full bg-background text-foreground">
     <div id="root" class="h-full">

package/dist/mobile.html CHANGED Viewed

@@ -63,7 +63,7 @@
       })();
     </script>
-    <script type="module" crossorigin src="/assets/mobile-BktO3_4R.js"></script>
+    <script type="module" crossorigin src="/assets/mobile-C4bTWKry.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-base-ui-CnHfUmDN.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-zustand-B4dlGEM2.js">
@@ -71,15 +71,15 @@
     <link rel="modulepreload" crossorigin href="/assets/vendor-pathe-vBmvQE8f.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-DLPElpoQ.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-tanstack-query-core-BWz0ose6.js">
-    <link rel="modulepreload" crossorigin href="/assets/persistence-DPNMIbF5.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-CBoBpJ1Z.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-l2R9muux.js">
+    <link rel="modulepreload" crossorigin href="/assets/persistence-D1lIuyqO.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-ZK_vkdzL.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-CewM6-g5.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-opencode-sdk-C07HQypa.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-aparajita-capacitor-secure-storage-CjQdwfjS.js">
-    <link rel="modulepreload" crossorigin href="/assets/gitApiHttp-D8j1qRH4.js">
-    <link rel="modulepreload" crossorigin href="/assets/terminalApi-tB3qLcfa.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BtWi74Pm.js">
-    <link rel="stylesheet" crossorigin href="/assets/src-oHrYIqHF.css">
+    <link rel="modulepreload" crossorigin href="/assets/gitApiHttp-BxGAFLTf.js">
+    <link rel="modulepreload" crossorigin href="/assets/terminalApi-DpiAJlil.js">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BXCt7ZsQ.js">
+    <link rel="stylesheet" crossorigin href="/assets/src-8kQFmtjw.css">
   </head>
   <body class="h-full bg-background text-foreground">
     <div id="root" class="h-full"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@openchambery/web",
-  "version": "1.18.2-beta.2",
+  "version": "1.18.2-beta.21",
   "private": false,
   "type": "module",
   "main": "./server/index.js",

package/server/index.d.ts CHANGED Viewed

@@ -25,6 +25,12 @@ export interface StartWebUiServerOptions {
   getSshRoutingTable?: () => { id: string; localPort: number }[];
   /** Mint a stored SSH host clientToken for a ready session (Electron). */
   mintSshHostToken?: (hostId: string) => Promise<string>;
+  /**
+   * Optional process-local lock for settings persistence (Electron in-process).
+   * When provided, every settings write/migrate joins this exclusive chain so
+   * concurrent desktop writers cannot clobber sibling fields in settings.json.
+   */
+  settingsPersistLock?: <T>(work: () => Promise<T> | T) => Promise<T>;
 }
 export declare function startWebUiServer(

package/server/index.js CHANGED Viewed

@@ -1240,6 +1240,11 @@ async function main(options = {}) {
   if (typeof options.getIsWindowFocused === 'function') {
     notificationTriggerRuntime.setGetIsWindowFocused(options.getIsWindowFocused);
   }
+  // Electron in-process: join the desktop settings mutation chain so web
+  // persistSettings cannot race main/ssh-manager writers on settings.json.
+  if (typeof options.settingsPersistLock === 'function') {
+    settingsRuntime.setRunExclusivePersist(options.settingsPersistLock);
+  }
   const getDesktopRuntimeConfig = typeof options.getDesktopRuntimeConfig === 'function'
     ? options.getDesktopRuntimeConfig
     : null;
@@ -1441,6 +1446,7 @@ async function main(options = {}) {
     // is not an instance identity — one machine can run several servers.
     getServerLabel: () => 'OpenChamber',
     readSettingsFromDiskMigrated,
+    persistSettings,
     normalizeTunnelSessionTtlMs,
     authorizeManagedOpenCodeBridgeRequest: managedCapabilitiesRuntime.authorizeManagedOpenCodeBridgeRequest,
     sayTTSCapability,
@@ -1708,6 +1714,13 @@ async function main(options = {}) {
       } catch {
         // best-effort shutdown of the dictation worker
       }
+      try {
+        if (smallModelServiceInstance?.stop) {
+          await smallModelServiceInstance.stop();
+        }
+      } catch {
+        // best-effort cleanup of the small-model temp OpenCode directory
+      }
       return gracefulShutdown({
         exitProcess: shutdownOptions.exitProcess ?? false,
         forceCloseConnections: shutdownOptions.forceCloseConnections === true,

package/server/lib/config-sync/DOCUMENTATION.md ADDED Viewed

@@ -0,0 +1,70 @@
+# Config Sync Module
+## Purpose
+Own the direction-agnostic OpenCode config sync contract: allowlist planning on the source, target identity/capabilities, POSIX prepare/probe/finalize scripts, tar collection, selection filtering, local/remote generational backups, and apply orchestration. Electron's managed SSH push **and pull** paths are the first executors; non-SSH targets reuse the same shapes.
+## Entrypoints
+| File | Role |
+|------|------|
+| `index.js` | Public re-exports |
+| `constants.js` | Allowlist, backup roots, size limits, direction constants, generation retention (`N=5`) |
+| `contract.js` | `SyncTarget`, capabilities, `TargetExecutor` typedefs, capability asserts |
+| `plan.js` | `planOpenCodeConfigSync` / `planOpenCodeConfigSyncFromInventory` |
+| `selections.js` | Default/normalize/filter whitelist selections |
+| `scripts.js` | Probe / inventory / generational prepare / finalize / remote tar scripts |
+| `local-backup.js` | Local (pull destination) generational backup + tar extract |
+| `tar.js` | `collectLocalTarBuffer` (buffered) |
+| `engine.js` | `applyConfigSyncPlan` orchestration for **push** (prepare → putTar* → finalize) |
+| `credential-auth.js` | Credential grant enforcement helpers |
+| `target-id.js` | `ssh:<instanceId>` namespace helper |
+## Contract shape
+- **SyncTarget**: `{ id, kind, capabilities: { posixShell, tarExtract, authFileWrite } }`
+- **TargetExecutor**: `{ probe(plan), prepare(plan, { syncRunId }), putTar({ kind, payload }), finalize(plan, { syncRunId }) }`
+  - `payload`: `Buffer | Uint8Array` — all executors currently buffer; reintroduce streaming only when a transport needs it.
+- **Plan** (source-computed): `{ direction: 'push' | 'pull', syncRunId?, sourceTargetId?, targetId?, files, directories, agentsRoot, authFile, deletes, totalBytes, selections? }`
+- **Selections**: `{ fileGroups: boolean[], singleFiles: boolean[], directories: boolean[], agentsRoot: boolean, authFile: boolean }`
+  - Preview and apply must share one selections snapshot so the confirmed scope cannot drift.
+## Direction flow
+| Direction | Source plan | Destination mutate |
+|-----------|-------------|--------------------|
+| `push` | Local home walk (`planOpenCodeConfigSync`) | Remote prepare + putTar + finalize |
+| `pull` | Remote inventory script → `planOpenCodeConfigSyncFromInventory` | Local `prepareLocalSyncDestination` + extract + finalize |
+Switching direction in the wizard **must** discard the previous preview and re-call preview IPC (no client-side flip of an old plan).
+## Invariants
+- Plan is computed on the source filesystem/inventory snapshot; destination executors never re-walk the source.
+- Managed SSH readiness is gated by `posixShell` (and `tarExtract` / `authFileWrite` as needed).
+- Prepare (remote or local) writes generational backups under `<backupRoot>/<syncRunId>/` and prunes older than `OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS`. Failed runs keep their scene until pruned.
+- Finalize confirms the run's backup directory exists.
+- Run records (Electron `sync-run-store`) persist `direction` alongside `syncRunId` / summary; they are not stored in `settings.json`.
+- **Credential sync:** target reachability ≠ credential transfer. `auth.json` is omitted unless the SSH target has an explicit grant. Push and pull reuse the same grant. Unauthorized credential plans fail with `code: credential_sync_unauthorized`.
+## HTTP receive protocol (direct / later relay)
+Routes under `/api/openchamber/config-sync/*` (global `/api` auth gate: session or clientToken bearer):
+| Method | Path | Role |
+|--------|------|------|
+| POST | `/probe` | Inventory + existence vs plan; reports `inboundCredentialAuthorized` |
+| POST | `/prepare` | Generational local backup + deletes; one inflight `syncRunId` |
+| PUT | `/put/:kind?syncRunId=` | Stream tar.gz (`config` \| `agents` \| `auth`) |
+| GET | `/download/:kind` | Stream tar.gz for pull source |
+| POST | `/finalize` | Confirm backup generation + success receipt |
+| POST | `/abort` | Clear inflight |
+| GET/PUT | `/credential-auth` | Host inbound credential grant (`configSyncInboundCredentialAuthorized`) |
+`auth` put/download requires inbound credential authorization (`credential_sync_unauthorized`). Concurrent prepare → `sync_in_progress`.
+## Composition
+- Electron SSH: `TargetExecutor` push + inventory/tar pull.
+- Electron direct hosts: `direct-config-sync.mjs` calls these HTTP routes (`host:<id>` grants in `desktopCredentialSyncGrants`, channel `host-settings`).
+- **Relay hosts (ticket 06):** UI opens an E2EE tunnel (`packages/ui/src/lib/relay/relay-config-sync.ts`) and calls the same HTTP routes via `tunnel.fetch`. Target id is `relay:<serverId>` (signing-key fingerprint). Preview/apply refresh candidates and refuse on `serverId` mismatch (`relay_identity_changed`) with no fallback identity. Outbound credential grants use channel `pairing-settings` (pairing trust UX / host trust settings for the paired relay). Inbound credential grants remain `configSyncInboundCredentialAuthorized` on the receiving Host. Auth is always bearer + grant — never “reachable ⇒ trusted”.

package/server/lib/config-sync/config-sync.test.js ADDED Viewed

@@ -0,0 +1,197 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  OPENCODE_CONFIG_SYNC_BACKUP_DIR,
+  OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS,
+  SYNC_DIRECTION_PULL,
+  SYNC_DIRECTION_PUSH,
+  assertPlanDirection,
+  assertTargetCapability,
+  buildDefaultSyncSelections,
+  buildRemoteSyncFinalizeScript,
+  buildRemoteSyncPrepareScript,
+  createSshSyncTarget,
+  filterPlanBySelections,
+  planOpenCodeConfigSync,
+  planOpenCodeConfigSyncFromInventory,
+  prepareLocalSyncDestination,
+} from './index.js';
+const tempDirs = [];
+const makeTempDir = async () => {
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'oc-config-sync-'));
+  tempDirs.push(dir);
+  return dir;
+};
+afterEach(async () => {
+  while (tempDirs.length > 0) {
+    await fsp.rm(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+describe('config-sync contract', () => {
+  it('requires direction on plans and accepts push/pull', () => {
+    expect(assertPlanDirection({ direction: SYNC_DIRECTION_PUSH })).toBe('push');
+    expect(assertPlanDirection({ direction: SYNC_DIRECTION_PULL })).toBe('pull');
+    expect(() => assertPlanDirection({})).toThrow(/direction/);
+  });
+  it('gates SSH targets by capability derived from managed mode', () => {
+    const managed = createSshSyncTarget('abc', { remoteOpenchamber: { mode: 'managed' } });
+    expect(managed.id).toBe('ssh:abc');
+    expect(managed.capabilities.posixShell).toBe(true);
+    assertTargetCapability(managed, 'posixShell');
+    const plain = createSshSyncTarget('abc', { remoteOpenchamber: { mode: 'external' } });
+    expect(plain.capabilities.posixShell).toBe(false);
+    expect(() => assertTargetCapability(plain, 'posixShell')).toThrow(/posixShell/);
+  });
+  it('plans from an arbitrary directory snapshot with direction (source/target decoupling)', async () => {
+    const home = await makeTempDir();
+    const configDir = path.join(home, '.config', 'opencode');
+    await fsp.mkdir(configDir, { recursive: true });
+    await fsp.writeFile(path.join(configDir, 'opencode.jsonc'), '{}\n');
+    const pushPlan = planOpenCodeConfigSync(home, {
+      direction: SYNC_DIRECTION_PUSH,
+      syncRunId: 'dry-push',
+      sourceTargetId: 'snapshot:a',
+      targetId: 'ssh:remote',
+    });
+    expect(pushPlan.direction).toBe('push');
+    expect(pushPlan.syncRunId).toBe('dry-push');
+    expect(pushPlan.sourceTargetId).toBe('snapshot:a');
+    expect(pushPlan.targetId).toBe('ssh:remote');
+    expect(pushPlan.files.map((entry) => entry.path)).toContain('opencode.jsonc');
+    // Same snapshot as a pull source — contract accepts reverse direction without shape change.
+    const pullPlan = planOpenCodeConfigSync(home, {
+      direction: SYNC_DIRECTION_PULL,
+      syncRunId: 'dry-pull',
+      sourceTargetId: 'ssh:remote',
+      targetId: 'local',
+    });
+    expect(pullPlan.direction).toBe('pull');
+    expect(pullPlan.files.map((entry) => entry.path)).toEqual(pushPlan.files.map((entry) => entry.path));
+  });
+  it('filters plans by whitelist selections and builds pull plans from inventory', async () => {
+    const home = await makeTempDir();
+    const configDir = path.join(home, '.config', 'opencode');
+    await fsp.mkdir(path.join(configDir, 'skills'), { recursive: true });
+    await fsp.writeFile(path.join(configDir, 'opencode.jsonc'), '{}\n');
+    await fsp.writeFile(path.join(configDir, 'AGENTS.md'), 'hi\n');
+    await fsp.writeFile(path.join(configDir, 'skills', 'a.md'), 'a\n');
+    const full = planOpenCodeConfigSync(home, { direction: SYNC_DIRECTION_PUSH, includeAuthFile: false });
+    const selections = buildDefaultSyncSelections({ includeAuthFile: false });
+    selections.fileGroups = selections.fileGroups.map((_, index) => index === 0);
+    selections.singleFiles = selections.singleFiles.map(() => false);
+    selections.directories = selections.directories.map((__, index) => index === 2); // skills
+    selections.agentsRoot = false;
+    const filtered = filterPlanBySelections(full, selections);
+    expect(filtered.files.map((entry) => entry.path)).toEqual(['opencode.jsonc']);
+    expect(filtered.directories.map((entry) => entry.path)).toEqual(['skills']);
+    expect(filtered.agentsRoot).toBeNull();
+    expect(filtered.authFile).toBeNull();
+    const inventoryPlan = planOpenCodeConfigSyncFromInventory({
+      files: [{ path: 'opencode.jsonc', bytes: 3 }],
+      directories: [{ path: 'skills', fileCount: 1, bytes: 2 }],
+      agentsRoot: null,
+      authFile: { bytes: 9 },
+    }, {
+      direction: SYNC_DIRECTION_PULL,
+      selections: { ...selections, authFile: true },
+      includeAuthFile: true,
+    });
+    expect(inventoryPlan.direction).toBe('pull');
+    expect(inventoryPlan.authFile).toEqual({ bytes: 9 });
+    expect(inventoryPlan.files.map((entry) => entry.path)).toEqual(['opencode.jsonc']);
+  });
+});
+describe('local pull destination backups', () => {
+  it('creates generational local backups and preserves failed-run scenes until pruned', async () => {
+    const home = await makeTempDir();
+    const configDir = path.join(home, '.config', 'opencode');
+    await fsp.mkdir(configDir, { recursive: true });
+    await fsp.writeFile(path.join(configDir, 'opencode.jsonc'), '{}\n');
+    const plan = {
+      files: [{ path: 'opencode.jsonc', bytes: 3 }],
+      directories: [],
+      deletes: ['config.json', 'opencode.json'],
+      agentsRoot: null,
+      authFile: null,
+    };
+    await prepareLocalSyncDestination(home, plan, { syncRunId: 'pull-01', generations: 2 });
+    expect(fs.existsSync(path.join(configDir, OPENCODE_CONFIG_SYNC_BACKUP_DIR, 'pull-01', 'opencode.jsonc'))).toBe(true);
+    await fsp.writeFile(path.join(configDir, 'opencode.jsonc'), '{v2}\n');
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    await prepareLocalSyncDestination(home, plan, { syncRunId: 'pull-02', generations: 2 });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    await prepareLocalSyncDestination(home, plan, { syncRunId: 'pull-03', generations: 2 });
+    const remaining = fs.readdirSync(path.join(configDir, OPENCODE_CONFIG_SYNC_BACKUP_DIR)).sort();
+    expect(remaining).toHaveLength(2);
+    expect(remaining).not.toContain('pull-01');
+  });
+});
+describe('generational prepare backups', () => {
+  it('keeps N generations and preserves older failed-run dirs until pruned', async () => {
+    const home = await makeTempDir();
+    const configDir = path.join(home, '.config', 'opencode');
+    await fsp.mkdir(configDir, { recursive: true });
+    await fsp.writeFile(path.join(configDir, 'opencode.jsonc'), '{}\n');
+    const plan = planOpenCodeConfigSync(home, { direction: SYNC_DIRECTION_PUSH });
+    const generations = OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS;
+    for (let index = 0; index < generations + 2; index += 1) {
+      // Stagger mtimes so ls -1t ordering is stable across platforms.
+      await new Promise((resolve) => setTimeout(resolve, 15));
+      const syncRunId = `run-${String(index).padStart(2, '0')}`;
+      const script = buildRemoteSyncPrepareScript(plan, { syncRunId, generations });
+      execFileSync('sh', ['-c', script], { env: { ...process.env, HOME: home } });
+      // Simulate a failed run leaving its backup scene in place (no wipe of root).
+      const runBackup = path.join(configDir, OPENCODE_CONFIG_SYNC_BACKUP_DIR, syncRunId);
+      expect(fs.existsSync(runBackup)).toBe(true);
+      expect(fs.existsSync(path.join(runBackup, 'opencode.jsonc'))).toBe(true);
+    }
+    const backupRoot = path.join(configDir, OPENCODE_CONFIG_SYNC_BACKUP_DIR);
+    const remaining = fs.readdirSync(backupRoot).sort();
+    expect(remaining).toHaveLength(generations);
+    expect(remaining).toEqual(
+      Array.from({ length: generations }, (_, index) => `run-${String(index + 2).padStart(2, '0')}`),
+    );
+    // Earliest runs pruned; a mid-generation failed scene that remained until prune is gone only after exceeding N.
+    expect(remaining).not.toContain('run-00');
+    expect(remaining).not.toContain('run-01');
+  });
+  it('finalize confirms the run backup directory', async () => {
+    const home = await makeTempDir();
+    const configDir = path.join(home, '.config', 'opencode');
+    await fsp.mkdir(path.join(configDir, OPENCODE_CONFIG_SYNC_BACKUP_DIR, 'fin-1'), { recursive: true });
+    const ok = execFileSync('sh', ['-c', buildRemoteSyncFinalizeScript({ syncRunId: 'fin-1' })], {
+      env: { ...process.env, HOME: home },
+    });
+    expect(ok.toString()).toContain('SYNC_DONE');
+    expect(() => execFileSync('sh', ['-c', buildRemoteSyncFinalizeScript({ syncRunId: 'missing' })], {
+      env: { ...process.env, HOME: home },
+    })).toThrow();
+  });
+});

package/server/lib/config-sync/constants.js ADDED Viewed

@@ -0,0 +1,39 @@
+/** Allowlist for mirroring `~/.config/opencode` (non-session) across sync targets. */
+export const OPENCODE_CONFIG_SYNC_ALLOWLIST = {
+  // Mutually exclusive groups: first existing local file wins; other members are deleted on remote.
+  fileGroups: [
+    ['config.json', 'opencode.json', 'opencode.jsonc'],
+    ['oh-my-opencode-slim.json', 'oh-my-opencode-slim.jsonc'],
+    ['oh-my-openagent.json', 'oh-my-openagent.jsonc'],
+  ],
+  singleFiles: ['AGENTS.md', 'cursor-models.json'],
+  directories: [
+    { path: 'agents', legacy: 'agent' },
+    { path: 'commands', legacy: 'command' },
+    { path: 'skills', legacy: 'skill' },
+    { path: 'snippet' },
+    { path: 'snippets' },
+    { path: 'plugins', excludeNames: ['node_modules'] },
+    { path: '.oh-my-opencode-slim' },
+  ],
+};
+export const OPENCODE_CONFIG_SYNC_BACKUP_DIR = '.openchamber.sync-backup';
+/** Backup root for `$HOME/.agents` (outside `~/.agents` so rm -rf does not eat it). */
+export const OPENCODE_AGENTS_SYNC_BACKUP_DIR = '.openchamber.sync-backup-agents';
+/** Backup root for provider `auth.json` (outside `~/.local/share`). */
+export const OPENCODE_AUTH_SYNC_BACKUP_DIR = '.openchamber.sync-backup-auth';
+export const OPENCODE_AGENTS_ROOT_PROBE_MARKER = '__AGENTS_ROOT__';
+export const OPENCODE_AUTH_FILE_PROBE_MARKER = '__AUTH_FILE__';
+export const OPENCODE_CONFIG_SYNC_MAX_BYTES = 512 * 1024 * 1024;
+export const OPENCODE_CONFIG_SYNC_MAX_FILES = 20000;
+/** Generational backup retention per backup root (newest kept). */
+export const OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS = 5;
+/** Plan direction. Ticket 02 implements push only; pull reuses the same contract. */
+export const SYNC_DIRECTION_PUSH = 'push';
+export const SYNC_DIRECTION_PULL = 'pull';
+export const SYNC_DIRECTIONS = Object.freeze([SYNC_DIRECTION_PUSH, SYNC_DIRECTION_PULL]);

package/server/lib/config-sync/contract.js ADDED Viewed

@@ -0,0 +1,130 @@
+import {
+  syncTargetIdForDirectHost,
+  syncTargetIdForRelayServer,
+  syncTargetIdForSshInstance,
+} from './target-id.js';
+/**
+ * @typedef {{
+ *   posixShell: boolean,
+ *   tarExtract: boolean,
+ *   authFileWrite: boolean,
+ *   ocHttp?: boolean,
+ * }} SyncTargetCapabilities
+ *
+ * @typedef {{
+ *   id: string,
+ *   kind: string,
+ *   capabilities: SyncTargetCapabilities,
+ * }} SyncTarget
+ *
+ * @typedef {{
+ *   remoteExisting: string[],
+ *   remoteAgentsRootExists: boolean,
+ *   remoteAuthFileExists: boolean,
+ * }} SyncProbeResult
+ *
+ * Payload for putTar. Callers always hand a fully buffered archive
+ * (SSH stdin and direct/relay HTTP bodies alike).
+ * @typedef {Buffer | Uint8Array} SyncTarPayload
+ *
+ * @typedef {{
+ *   probe: (plan: object) => Promise<SyncProbeResult>,
+ *   prepare: (plan: object, ctx: { syncRunId: string }) => Promise<void>,
+ *   putTar: (args: { kind: 'config' | 'agents' | 'auth', payload: SyncTarPayload }) => Promise<void>,
+ *   finalize: (plan: object, ctx: { syncRunId: string }) => Promise<{ ok: true }>,
+ * }} TargetExecutor
+ */
+export const EMPTY_SYNC_CAPABILITIES = Object.freeze({
+  posixShell: false,
+  tarExtract: false,
+  authFileWrite: false,
+  ocHttp: false,
+});
+export const MANAGED_SSH_SYNC_CAPABILITIES = Object.freeze({
+  posixShell: true,
+  tarExtract: true,
+  authFileWrite: true,
+  ocHttp: false,
+});
+export const DIRECT_HOST_SYNC_CAPABILITIES = Object.freeze({
+  posixShell: false,
+  tarExtract: false,
+  authFileWrite: true,
+  ocHttp: true,
+});
+export const RELAY_HOST_SYNC_CAPABILITIES = Object.freeze({
+  posixShell: false,
+  tarExtract: false,
+  authFileWrite: true,
+  ocHttp: true,
+});
+/**
+ * Build a namespaced SyncTarget for an SSH instance.
+ * Managed remotes expose posixShell/tarExtract/authFileWrite; others expose none
+ * (semantic equivalent of the former mode==='managed' hard gate).
+ *
+ * @param {string} instanceId
+ * @param {{ remoteOpenchamber?: { mode?: string } } | null | undefined} [instance]
+ * @returns {SyncTarget}
+ */
+export const createSshSyncTarget = (instanceId, instance) => {
+  const managed = instance?.remoteOpenchamber?.mode === 'managed';
+  return {
+    id: syncTargetIdForSshInstance(instanceId),
+    kind: 'ssh',
+    capabilities: managed ? { ...MANAGED_SSH_SYNC_CAPABILITIES } : { ...EMPTY_SYNC_CAPABILITIES },
+  };
+};
+/**
+ * Direct OpenChamber host reached over HTTP (apiUrl + clientToken).
+ * @param {string} hostId
+ * @returns {SyncTarget}
+ */
+export const createDirectHostSyncTarget = (hostId) => ({
+  id: syncTargetIdForDirectHost(hostId),
+  kind: 'direct',
+  capabilities: { ...DIRECT_HOST_SYNC_CAPABILITIES },
+});
+/**
+ * Relay OpenChamber host pinned by serverId (signing-key fingerprint).
+ * @param {string} serverId
+ * @returns {SyncTarget}
+ */
+export const createRelayHostSyncTarget = (serverId) => ({
+  id: syncTargetIdForRelayServer(serverId),
+  kind: 'relay',
+  capabilities: { ...RELAY_HOST_SYNC_CAPABILITIES },
+});
+/**
+ * @param {SyncTarget | null | undefined} target
+ * @param {keyof SyncTargetCapabilities} capability
+ */
+export const assertTargetCapability = (target, capability) => {
+  if (!target || typeof target !== 'object') {
+    throw new Error('Sync target is required');
+  }
+  if (!target.capabilities?.[capability]) {
+    throw new Error(`OpenCode config sync requires target capability: ${capability}`);
+  }
+};
+/**
+ * Validate that a plan is direction-aware and uses a known direction value.
+ * @param {object} plan
+ */
+export const assertPlanDirection = (plan) => {
+  const direction = plan?.direction;
+  if (direction !== 'push' && direction !== 'pull') {
+    throw new Error(`Sync plan requires direction 'push' or 'pull', got ${String(direction)}`);
+  }
+  return direction;
+};

package/server/lib/config-sync/credential-auth.js ADDED Viewed

@@ -0,0 +1,39 @@
+/**
+ * Credential sync authorization is separate from target reachability.
+ * Access to an SSH/managed remote does NOT imply permission to transfer
+ * provider tokens (auth.json). Grants are per SyncTarget id and must be
+ * established through a trust channel (instance settings / pairing).
+ */
+export const CREDENTIAL_SYNC_UNAUTHORIZED_CODE = 'credential_sync_unauthorized';
+export const CREDENTIAL_SYNC_GRANT_CHANNEL_INSTANCE_SETTINGS = 'instance-settings';
+export class CredentialSyncUnauthorizedError extends Error {
+  /**
+   * @param {string} targetId
+   */
+  constructor(targetId) {
+    super(`Credential sync is not authorized for ${targetId}`);
+    this.name = 'CredentialSyncUnauthorizedError';
+    this.code = CREDENTIAL_SYNC_UNAUTHORIZED_CODE;
+    this.targetId = targetId;
+  }
+}
+/**
+ * @param {object | null | undefined} plan
+ */
+export const planIncludesCredentials = (plan) => Boolean(plan?.authFile);
+/**
+ * Enforce authorization when a plan carries credentials.
+ * Call from preview and apply before probe/prepare/putTar.
+ *
+ * @param {object | null | undefined} plan
+ * @param {{ targetId: string, authorized: boolean }} ctx
+ */
+export const assertCredentialSyncAuthorized = (plan, ctx) => {
+  if (!planIncludesCredentials(plan)) return;
+  if (ctx?.authorized === true) return;
+  throw new CredentialSyncUnauthorizedError(String(ctx?.targetId || plan?.targetId || 'unknown'));
+};