@openchambery/web 2.1.7 → 2.1.8-beta.11

package/server/lib/config-sync/routes.test.js

@@ -27,7 +27,7 @@ afterEach(async () => {
   }
 });
 
-const createApp = async () => {
+const createApp = async (credentials, magpie) => {
   const home = await makeTempDir();
   const configDir = path.join(home, '.config', 'opencode');
   await fsp.mkdir(configDir, { recursive: true });
@@ -36,6 +36,8 @@ const createApp = async () => {
 
   const receiver = createConfigSyncReceiver({
     homedir: () => home,
+    ...(credentials ? { credentials } : {}),
+    ...(magpie ? { magpie } : {}),
   });
 
   const app = express();
@@ -44,6 +46,63 @@ const createApp = async () => {
 };
 
 describe('config-sync HTTP routes', () => {
+  it('discovers Magpie without import and requires a selected transfer before finalizing', async () => {
+    const payload = Buffer.from('fixture-magpie-payload');
+    const received = [];
+    const { app } = await createApp(undefined, {
+      inventory: async () => ({ available: true, installed: false }),
+      download: async () => payload,
+      import: async (buffer) => { received.push(buffer); return { ok: true, magpieWarnings: ['sign_in_required'] }; },
+    });
+    const probe = await request(app).post('/api/openchamber/config-sync/probe').send({ plan: {} });
+    expect(probe.body.inventory.magpie).toEqual({ available: true, installed: false });
+    expect(received).toEqual([]);
+    const download = await request(app).get('/api/openchamber/config-sync/download/magpie').expect(200);
+    expect(download.headers['cache-control']).toBe('no-store');
+    expect(download.body).toEqual(payload);
+    await request(app).put('/api/openchamber/config-sync/magpie')
+      .set('Content-Type', 'application/octet-stream').send(payload).expect(200);
+    const plan = { files: [], directories: [], deletes: [], magpie: { bytes: 0 } };
+    await request(app).post('/api/openchamber/config-sync/prepare').send({ plan, syncRunId: 'magpie-run' }).expect(200);
+    await request(app).post('/api/openchamber/config-sync/finalize').send({ syncRunId: 'magpie-run' }).expect(500);
+    await request(app).put('/api/openchamber/config-sync/put/magpie?syncRunId=magpie-run')
+      .set('Content-Type', 'application/octet-stream').send(payload).expect(200);
+    const receipt = await request(app).post('/api/openchamber/config-sync/finalize').send({ syncRunId: 'magpie-run' }).expect(200);
+    expect(receipt.body.magpieWarnings).toEqual(['sign_in_required']);
+    expect(received).toEqual([payload, payload]);
+  });
+
+  it('transfers credential bytes through HTTP without putting values in inventory or filesystem backups', async () => {
+    const payload = Buffer.from(JSON.stringify({ format: 'opencode-credentials-v1', entries: [{ fixture: 'private-value' }] }));
+    const received = [];
+    const { app, home } = await createApp({
+      inventory: async () => ({ bytes: payload.length }),
+      download: async () => payload,
+      import: async (buffer) => { received.push(buffer); return { ok: true }; },
+    });
+    const plan = { direction: 'push', files: [], directories: [], deletes: [], providerCredentials: { bytes: payload.length } };
+    const inventory = await request(app).get('/api/openchamber/config-sync/credentials/inventory');
+    expect(inventory.body).toEqual({ providerCredentials: { bytes: payload.length } });
+    const download = await request(app).get('/api/openchamber/config-sync/download/credentials');
+    expect(download.headers['cache-control']).toBe('no-store');
+    expect(download.body).toEqual(payload);
+    await request(app).post('/api/openchamber/config-sync/prepare').send({ plan, syncRunId: 'credential-run' }).expect(200);
+    await request(app).post('/api/openchamber/config-sync/finalize').send({ syncRunId: 'credential-run' }).expect(500);
+    await request(app).put('/api/openchamber/config-sync/put/credentials?syncRunId=credential-run')
+      .set('Content-Type', 'application/octet-stream').send(download.body).expect(200);
+    await request(app).post('/api/openchamber/config-sync/finalize').send({ syncRunId: 'credential-run' }).expect(200);
+    await request(app).put('/api/openchamber/config-sync/credentials')
+      .set('Content-Type', 'application/octet-stream').send(payload).expect(200);
+    expect(received).toEqual([payload, payload]);
+    await expect(fsp.stat(path.join(home, '.openchamber.sync-backup-auth'))).rejects.toThrow();
+    await expect(fsp.stat(path.join(home, '.local', 'share', 'opencode', 'auth.json'))).rejects.toThrow();
+    await request(app).post('/api/openchamber/config-sync/prepare')
+      .send({ plan: { ...plan, providerCredentials: null }, syncRunId: 'unselected' }).expect(200);
+    await request(app).put('/api/openchamber/config-sync/put/credentials?syncRunId=unselected')
+      .set('Content-Type', 'application/octet-stream').send(payload).expect(500);
+    expect(received).toHaveLength(2);
+  });
+
   it.each(['http-config', 'http-agents', 'local-pack', 'ssh-config', 'ssh-agents'])(
     '%s archive excludes inventory-skipped files, including inside followed symlinks',
     async (transport) => {
@@ -91,7 +150,7 @@ describe('config-sync HTTP routes', () => {
       directories: [],
       deletes: ['config.json', 'opencode.json'],
       agentsRoot: null,
-      authFile: null,
+      providerCredentials: null,
       totalBytes: 3,
     };
 
@@ -124,7 +183,7 @@ describe('config-sync HTTP routes', () => {
       directories: [],
       deletes: [],
       agentsRoot: null,
-      authFile: null,
+      providerCredentials: null,
       totalBytes: 2,
     };
     const first = await request(app).post('/api/openchamber/config-sync/prepare').send({ plan, syncRunId: 'run-a' });
@@ -143,7 +202,7 @@ describe('config-sync HTTP routes', () => {
       directories: [],
       deletes: [],
       agentsRoot: null,
-      authFile: null,
+      providerCredentials: null,
       totalBytes: 0,
     };
     await request(app).post('/api/openchamber/config-sync/prepare').send({ plan, syncRunId: 'run-stream' });
@@ -151,7 +210,7 @@ describe('config-sync HTTP routes', () => {
     // Tiny invalid tar still proves chunk aggregation reached extract.
     await expect(receiver.put({
       syncRunId: 'run-stream',
-      kind: 'auth',
+      kind: 'config',
       stream: Readable.from([Buffer.from('aa'), Buffer.from('bb')]),
     })).rejects.toThrow(/tar|failed|Local tar extract/i);
 

package/server/lib/config-sync/scripts.js

@@ -3,8 +3,6 @@ import path from 'node:path';
 import {
   OPENCODE_AGENTS_ROOT_PROBE_MARKER,
   OPENCODE_AGENTS_SYNC_BACKUP_DIR,
-  OPENCODE_AUTH_FILE_PROBE_MARKER,
-  OPENCODE_AUTH_SYNC_BACKUP_DIR,
   OPENCODE_CONFIG_SYNC_ALLOWLIST,
   OPENCODE_CONFIG_SYNC_BACKUP_DIR,
   OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS,
@@ -60,7 +58,7 @@ const generationalBackupSetupLines = ({ backupVar, runVar, quotedRunId, generati
  * {@link OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS} are pruned; prepare no longer
  * `rm -rf`s the entire backup root at start.
  *
- * @param {{ files: { path: string }[], directories: { path: string }[], deletes: string[], agentsRoot?: { fileCount: number, bytes: number } | null, authFile?: { bytes: number } | null }} plan
+ * @param {{ files: { path: string }[], directories: { path: string }[], deletes: string[], agentsRoot?: { fileCount: number, bytes: number } | null }} plan
  * @param {{ syncRunId: string, generations?: number }} options
  * @returns {string}
  */
@@ -134,19 +132,6 @@ export const buildRemoteSyncPrepareScript = (plan, options) => {
     lines.push('rm -rf -- "$HOME/.agents"');
   }
 
-  if (plan?.authFile) {
-    lines.push(`AUTH_BK="$HOME/${OPENCODE_AUTH_SYNC_BACKUP_DIR}"`);
-    lines.push(...generationalBackupSetupLines({
-      backupVar: 'AUTH_BK',
-      runVar: 'AUTH_RUN_BK',
-      quotedRunId,
-      generations,
-    }));
-    lines.push('if [ -e "$HOME/.local/share/opencode/auth.json" ]; then');
-    lines.push('  cp -a "$HOME/.local/share/opencode/auth.json" "$AUTH_RUN_BK/auth.json"');
-    lines.push('fi');
-  }
-
   lines.push("printf 'SYNC_READY\\n'");
   return lines.join('\n');
 };
@@ -164,9 +149,6 @@ export const buildRemoteSyncProbeScript = (uniqueProbePaths) => {
   lines.push(
     `[ -e "$HOME/.agents" ] && printf '%s\\n' ${shellQuote(OPENCODE_AGENTS_ROOT_PROBE_MARKER)}`,
   );
-  lines.push(
-    `[ -e "$HOME/.local/share/opencode/auth.json" ] && printf '%s\\n' ${shellQuote(OPENCODE_AUTH_FILE_PROBE_MARKER)}`,
-  );
   lines.push('exit 0');
   return lines.join('\n');
 };
@@ -228,14 +210,9 @@ export const buildRemoteSyncInventoryScript = () => {
   lines.push("  ABYTES=\"$(find \"$HOME/.agents\" -type f ! -path '*/node_modules/*' ! -path '*/.venv-asc/*' ! -name '*.backup' -exec wc -c {} + 2>/dev/null | awk 'END{print $1+0}')\"");
   lines.push('  AGENTS="{\\"fileCount\\":$ACOUNT,\\"bytes\\":$ABYTES}"');
   lines.push('fi');
-  lines.push('AUTH="null"');
-  lines.push('if [ -f "$HOME/.local/share/opencode/auth.json" ]; then');
-  lines.push('  AUBYTES="$(wc -c < "$HOME/.local/share/opencode/auth.json" | tr -d \' \')"');
-  lines.push('  AUTH="{\\"bytes\\":$AUBYTES}"');
-  lines.push('fi');
   lines.push('FILES="${FILES%,}"');
   lines.push('DIRS="${DIRS%,}"');
-  lines.push('printf \'SYNC_INVENTORY={"files":[%s],"directories":[%s],"agentsRoot":%s,"authFile":%s}\\n\' "$FILES" "$DIRS" "$AGENTS" "$AUTH"');
+  lines.push('printf \'SYNC_INVENTORY={"files":[%s],"directories":[%s],"agentsRoot":%s}\\n\' "$FILES" "$DIRS" "$AGENTS"');
   lines.push('exit 0');
   return lines.join('\n');
 };
@@ -265,9 +242,4 @@ export const buildRemoteAgentsTarScript = () => [
   `cd "$HOME" && tar ${OPENCODE_CONFIG_SYNC_TAR_EXCLUDES.map(shellQuote).join(' ')} -h -czf - .agents`,
 ].join('\n');
 
-export const buildRemoteAuthTarScript = () => [
-  'set -e',
-  'cd "$HOME/.local/share/opencode" && tar -h -czf - auth.json',
-].join('\n');
-
 export { shellQuote };

package/server/lib/config-sync/selections.js

@@ -6,13 +6,14 @@ import { OPENCODE_CONFIG_SYNC_ALLOWLIST } from './constants.js';
  *   singleFiles: boolean[],
  *   directories: boolean[],
  *   agentsRoot: boolean,
- *   authFile: boolean,
+ *   providerCredentials: boolean,
+ *   magpie?: boolean,
  * }} SyncSelections
  */
 
 /**
- * Default: everything selected except authFile (credentials stay opt-in).
- * @param {{ includeAuthFile?: boolean }} [options]
+ * Default: everything selected except providerCredentials (credentials stay opt-in).
+ * @param {{ includeProviderCredentials?: boolean }} [options]
  * @returns {SyncSelections}
  */
 export const buildDefaultSyncSelections = (options = {}) => ({
@@ -20,13 +21,14 @@ export const buildDefaultSyncSelections = (options = {}) => ({
   singleFiles: OPENCODE_CONFIG_SYNC_ALLOWLIST.singleFiles.map(() => true),
   directories: OPENCODE_CONFIG_SYNC_ALLOWLIST.directories.map(() => true),
   agentsRoot: true,
-  authFile: options.includeAuthFile === true,
+  providerCredentials: options.includeProviderCredentials === true,
+  magpie: false,
 });
 
 /**
  * Normalize a partial selections object against the allowlist shape.
  * @param {Partial<SyncSelections> | null | undefined} raw
- * @param {{ includeAuthFile?: boolean }} [options]
+ * @param {{ includeProviderCredentials?: boolean }} [options]
  * @returns {SyncSelections}
  */
 export const normalizeSyncSelections = (raw, options = {}) => {
@@ -48,7 +50,8 @@ export const normalizeSyncSelections = (raw, options = {}) => {
     singleFiles,
     directories,
     agentsRoot: raw.agentsRoot !== false,
-    authFile: raw.authFile === true,
+    providerCredentials: raw.providerCredentials === true,
+    magpie: raw.magpie === true,
   };
 };
 
@@ -59,7 +62,7 @@ export const normalizeSyncSelections = (raw, options = {}) => {
  * @param {SyncSelections} selections
  */
 export const filterPlanBySelections = (plan, selections) => {
-  const selected = normalizeSyncSelections(selections, { includeAuthFile: selections?.authFile === true });
+  const selected = normalizeSyncSelections(selections, { includeProviderCredentials: selections?.providerCredentials === true });
   const selectedFileNames = new Set();
   const selectedDeleteNames = new Set();
 
@@ -91,13 +94,13 @@ export const filterPlanBySelections = (plan, selections) => {
   const directories = (Array.isArray(plan?.directories) ? plan.directories : []).filter((entry) => selectedDirNames.has(entry.path));
   const deletes = (Array.isArray(plan?.deletes) ? plan.deletes : []).filter((name) => selectedDeleteNames.has(name) || selectedDirLegacy.has(name));
   const agentsRoot = selected.agentsRoot ? (plan?.agentsRoot ?? null) : null;
-  const authFile = selected.authFile ? (plan?.authFile ?? null) : null;
+  const providerCredentials = selected.providerCredentials ? (plan?.providerCredentials ?? null) : null;
 
   let totalBytes = 0;
   for (const entry of files) totalBytes += Number(entry.bytes) || 0;
   for (const entry of directories) totalBytes += Number(entry.bytes) || 0;
   if (agentsRoot) totalBytes += Number(agentsRoot.bytes) || 0;
-  if (authFile) totalBytes += Number(authFile.bytes) || 0;
+  if (providerCredentials) totalBytes += Number(providerCredentials.bytes) || 0;
 
   return {
     ...plan,
@@ -105,7 +108,8 @@ export const filterPlanBySelections = (plan, selections) => {
     directories,
     deletes,
     agentsRoot,
-    authFile,
+    providerCredentials,
+    magpie: selected.magpie && plan?.magpieAvailable ? { bytes: 0 } : null,
     totalBytes,
     selections: selected,
   };

package/server/lib/opencode/DOCUMENTATION.md

@@ -19,6 +19,7 @@ This module provides OpenCode server integration utilities for the web server ru
   from the authenticated client context (null for owner UI sessions), allowing
   connection shortcuts to exclude themselves without changing management lists.
 - `plugins.js`: config entries and plugin-directory files are inventory, not compatibility checks. They do not synthesize `compatibility` or `compatible` fields; Settings uses the OpenCode runtime inventory for actual load status and errors.
+  - Reads native V2 `plugins` (strings or `{ package, options }`) with legacy `plugin`/tuple fallback. A native array, including an empty one, wins within each document. Entry mutations write only `plugins`, convert retained legacy tuples, and remove the shadowed legacy key in the touched source file. Options, ordering, unrelated configuration and JSONC comments are preserved through the shared atomic config writer; malformed entries or write failures do not replace the original file. Web, Electron and mobile use this host implementation; VS Code mirrors the same persistence contract.
 - `session-directory-runtime.js`: Host-side physical directory identity for session index/list/detail/live projection. Uses a runtime-scoped, bounded 256-entry cache (60s success / 5s failed resolution), cleared when the upstream URL changes. Local directory lists use the upstream project identity and physical-directory filtering to include legacy symlink sessions without mixing worktrees. One request reads one page and preserves opaque cursors; consumers must follow continuations even after filtered-empty pages. Non-loopback upstreams keep their own path namespace.
 - `packages/web/server/lib/opencode/index.js`: public entrypoint (currently baseline placeholder).
 - `packages/web/server/lib/opencode/auth.js`: host-only authoritative provider credential API reads and deletion.
@@ -27,6 +28,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/cli-entry-runtime.js`: CLI entrypoint runtime that detects direct execution, forces `OPENCHAMBER_RUNTIME=web` unless already `ssh-remote` (so `dev:server` cannot inherit a leftover desktop env and host a relay, while SSH-managed remotes may), parses CLI options, and starts server bootstrap.
 - `packages/web/server/lib/opencode/routes.js`: OpenCode/provider settings and auth-related route registration.
 - `packages/web/server/lib/opencode/lifecycle.js`: OpenCode process lifecycle runtime (startup, restart, readiness, health monitoring). Managed child env inherits the user shell environment unchanged; experimental flags such as `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` follow the user's own environment and are never injected by OpenChamber.
+  - Before shared-service/private startup, config-sync's Magpie adapter repairs the discoverable command entry for an existing OpenChamber-managed Magpie CLI. No download occurs at startup. Errors remain explicit rather than starting OpenCode with an undiscoverable managed dependency. External services are not modified.
 - `packages/web/server/lib/opencode/v1-migration-gate.js`: pure V1→v2 migration admission gate (`GET /api/experimental/migration/v1` → whether transcript may be fetched).
 - `packages/web/server/lib/opencode/managed-capabilities-runtime.js`: managed-child scheduled-task resources, config injection, rotating bridge identity, and bridge authorization.
 - `packages/web/server/lib/opencode/env-runtime.js`: OpenCode CLI/binary resolution and shell environment runtime.
@@ -73,11 +75,12 @@ This module provides OpenCode server integration utilities for the web server ru
 
 ## Public exports (auth.js)
 - `configureOpenCodeCredentials(resolveClient)`: host composition injects a call-time SDK client resolver; `null` detaches it. Web/Electron share server wiring; VS Code wires its manager in extension activation. Mobile clients use their host.
+- `currentClient()`: trusted host-only client resolver used by config-sync to retain full V2 credential account records instead of the active-account quota projection.
 - `openCodeCredentialSource({ buildOpenCodeUrl, getOpenCodeAuthHeaders })`: resolves the current endpoint/auth at each read rather than capturing a previous runtime.
 - `readOpenCodeCredentials()`: async SDK `credential.list()` read of the running service; validates entries and projects only active accounts into the quota/TTS credential shape. OAuth `metadata.accountID` becomes `accountId`. No local `auth.json`, local environment, or local provider-config fallback; external service environment-only keys are not exposed by the credential API.
 - `getProviderAuth(providerId)`: async selected stored credential or authoritative `null`; network/auth/schema failures reject with a sanitized error, never empty success.
 - `removeProviderAuth(providerId)`: deletes every stored account for that integration through SDK `credential.remove`, preserving unrelated integrations. Partial failure rejects explicitly; retry lists remaining accounts. Auth-only disconnect requires no process restart.
-- Credential values remain host-only. `credential-boundary.js` blocks raw credential list/creation responses (GET/HEAD/POST `/api/credential`, including encoded/trailing-slash forms) in Web proxy and VS Code bridge because v2 replies contain keys. Provider-source responses expose only existence; errors never include upstream credential bodies/headers. Explicit legacy config-sync file transfer is not a current-service credential source or login operation.
+- Credential values remain host-only outside explicitly selected instance sync. `credential-boundary.js` blocks raw credential list/creation responses (GET/HEAD/POST `/api/credential`, including encoded/trailing-slash forms) in Web proxy and VS Code bridge because v2 replies contain keys. Provider-source responses expose only existence; errors never include upstream credential bodies/headers. The authenticated config-sync routes own explicit V2 credential transfer; previews and run logs contain only metadata.
 
 ## Public exports (shared.js)
 - `OPENCODE_CONFIG_DIR`, `AGENT_DIR`, `COMMAND_DIR`, `SKILL_DIR`, `CONFIG_FILE`, `CUSTOM_CONFIG_FILE`: Path constants.

package/server/lib/opencode/auth.d.ts

@@ -4,6 +4,7 @@ export type ProviderCredential =
   | { type: 'api'; key: string }
   | { type: 'oauth'; access: string; refresh: string; expires: number; accountId?: string; enterpriseUrl?: string };
 export function configureOpenCodeCredentials(resolveClient: (() => OpenCodeClient) | null): void;
+export function currentClient(): OpenCodeClient;
 export function openCodeCredentialSource(deps: {
   buildOpenCodeUrl: (path: string, prefix?: string) => string;
   getOpenCodeAuthHeaders: () => Record<string, string>;

package/server/lib/opencode/auth.js

@@ -49,7 +49,7 @@ async function listCredentials(client) {
   }
 }
 
-function currentClient() {
+export function currentClient() {
   if (!getClient) throw credentialError();
   try { return getClient(); } catch { throw credentialError(); }
 }

package/server/lib/opencode/config-entities-layering.test.js

@@ -66,7 +66,8 @@ describe('Web/Electron entity physical provenance', () => {
     fs.writeFileSync(jsonc, '{ // retained\n"plugin":["higher-plugin"]}');
     const entry = plugins.listPluginEntries().find((item) => item.spec === 'lower-plugin');
     plugins.updatePluginEntry(entry.id, { spec: 'updated-plugin' });
-    expect(readConfigFile(json).plugin).toEqual(['updated-plugin']);
+    expect(readConfigFile(json).plugins).toEqual(['updated-plugin']);
+    expect(readConfigFile(json).plugin).toBeUndefined();
     expect(readConfigFile(jsonc).plugin).toEqual(['higher-plugin']);
   });
 });

package/server/lib/opencode/feature-routes-runtime.js

@@ -522,6 +522,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       fsPromises,
       path,
       openchamberDataDir,
+      broadcastOpenChamberEvent,
     });
     registerFsRoutes(app, {
       os,

package/server/lib/opencode/lifecycle.js

@@ -6,6 +6,7 @@ import { readOpenCode2BinaryVersion } from './ensure-cli.js';
 import { createRevokedRuntimeContract, evaluateRuntimeContract } from './runtime-contract.js';
 import { OPENCODE_V1_MIGRATION_PATH, fetchV1MigrationGate } from './v1-migration-gate.js';
 import { isProcessAlive } from './shared-service.js';
+import { createMagpieSync } from '../config-sync/magpie.js';
 
 const parsePositiveInt = (value, fallback) => {
   const parsed = Number.parseInt(String(value ?? ''), 10);
@@ -71,6 +72,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     buildAugmentedPath,
     buildManagedOpenCodePath,
     getManagedOpenCodeShellEnvSnapshot,
+    prepareMagpieInstallation = () => createMagpieSync().repairInstallation(),
     managedCapabilitiesRuntime = null,
     getActiveSessionCount = () => 0,
     // Official background service (shared-service.js). null keeps the private
@@ -691,6 +693,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
    * or the registration is missing/malformed; the caller decides rollback.
    */
   const connectSharedOpenCodeService = async ({ binaryPath } = {}) => {
+    await prepareMagpieInstallation();
     if (!binaryPath) {
       await applyOpencodeBinaryFromSettings({ strict: true });
       if (typeof ensurePinnedOpenCode2CliEnv === 'function') {
@@ -793,6 +796,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
   const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
   const startOpenCodeOnce = async () => {
+    await prepareMagpieInstallation();
     // New managed instance — drop any prior permit before spawn/probes.
     const generationAtStart = revokeRuntimeExecutionPermit('managed-start');
     const requestedPort = env.ENV_CONFIGURED_OPENCODE_PORT;

package/server/lib/opencode/lifecycle.test.js

@@ -101,6 +101,7 @@ const createRuntime = (overrides = {}, stateRef = null) => {
     normalizeApiPrefix: vi.fn(() => ''),
     applyOpencodeBinaryFromSettings: vi.fn(async () => null),
     ensureOpencodeCliEnv: vi.fn(),
+    prepareMagpieInstallation: vi.fn(async () => {}),
     ensureLocalOpenCodeServerPassword: vi.fn(async () => 'password'),
     resolveManagedOpenCodeLaunchSpec: vi.fn((binary) => ({ binary, args: [], wrapperType: null })),
     setOpenCodePort: vi.fn((port) => {
@@ -195,14 +196,16 @@ describe('OpenCode lifecycle', () => {
   it('launches managed OpenCode with the managed PATH', async () => {
     delete process.env.OPENCODE_BINARY;
     const child = createMockChild();
+    const prepareMagpieInstallation = vi.fn(async () => {});
     spawnMock.mockImplementationOnce(() => {
+      expect(prepareMagpieInstallation).toHaveBeenCalledTimes(1);
       queueMicrotask(() => {
         child.stdout.emit('data', 'opencode server listening on http://127.0.0.1:45678\n');
       });
       return child;
     });
 
-    const runtime = createRuntime();
+    const runtime = createRuntime({ prepareMagpieInstallation });
     const server = await runtime.startOpenCode();
     const [binary, args, options] = spawnMock.mock.calls[0];
 
@@ -1100,13 +1103,15 @@ describe('shared official OpenCode service', () => {
     const sharedService = createSharedService();
     const adoptOpenCodeServerPassword = vi.fn();
     const stateRef = {};
-    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, adoptOpenCodeServerPassword }, stateRef);
+    const prepareMagpieInstallation = vi.fn(async () => {});
+    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, adoptOpenCodeServerPassword, prepareMagpieInstallation }, stateRef);
     const fetchMock = stubSharedFetch();
 
     await runtime.bootstrapOpenCodeAtStartup();
 
     expect(spawnMock).not.toHaveBeenCalled();
     expect(sharedService.start).toHaveBeenCalledTimes(1);
+    expect(prepareMagpieInstallation.mock.invocationCallOrder[0]).toBeLessThan(sharedService.start.mock.invocationCallOrder[0]);
     const startInput = sharedService.start.mock.calls[0][0];
     expect(startInput.binary).toBe('/mock/opencode');
     expect(startInput.env.OPENCODE_SERVER_PASSWORD).toBeUndefined();

package/server/lib/opencode/plugin-routes.test.js

@@ -316,7 +316,7 @@ describe('opencode plugin routes', () => {
 
     const after = await request(app).get('/api/config/plugins').expect(200);
     expect(after.body.entries).toEqual([]);
-    expect(readJson(userConfigPath).plugin).toBeUndefined();
+    expect(readJson(userConfigPath).plugins).toBeUndefined();
     expect(refreshOpenCodeAfterConfigChange).not.toHaveBeenCalled();
   });
 

package/server/lib/opencode/plugins.js

@@ -79,6 +79,25 @@ function readPluginConfigLayers(workingDirectory) {
   return readConfigLayers(workingDirectory);
 }
 
+function readPluginArray(config) {
+  if (Array.isArray(config.plugins)) return config.plugins;
+  return Array.isArray(config.plugin) ? config.plugin : [];
+}
+
+function writePluginArray(config, plugin, filePath) {
+  const next = { ...config };
+  delete next.plugin;
+  if (plugin.length > 0) {
+    next.plugins = plugin.map((raw) => {
+      const parsed = parsePluginRaw(raw);
+      return Array.isArray(raw) ? serializePluginEntry(parsed) : raw;
+    });
+  } else {
+    delete next.plugins;
+  }
+  writeConfig(next, filePath);
+}
+
 function validateFileName(fileName) {
   if (typeof fileName !== 'string' || !fileName) {
     throw codedError('Plugin file name is required', 'INVALID_FILENAME');
@@ -125,9 +144,8 @@ function getPluginTarget(id, workingDirectory) {
   validateScope(scope);
   const layers = readPluginConfigLayers(workingDirectory);
   const source = configSources(layers).find((candidate) => candidate.scope === scope
-    && Array.isArray(candidate.config?.plugin)
-    && candidate.config.plugin.some((raw) => parsePluginRaw(raw).spec === spec));
-  const plugin = Array.isArray(source?.config?.plugin) ? source.config.plugin : [];
+    && readPluginArray(candidate.config).some((raw) => parsePluginRaw(raw).spec === spec));
+  const plugin = source ? [...readPluginArray(source.config)] : [];
   const index = plugin.findIndex((raw) => parsePluginRaw(raw).spec === spec);
   if (!source || index === -1) {
     return null;
@@ -181,13 +199,16 @@ function parsePluginRaw(raw) {
   if (Array.isArray(raw) && raw.length === 2 && isRecord(raw[1])) {
     return { spec: validatePluginSpec(raw[0]), options: { ...raw[1] } };
   }
-  throw codedError('Plugin spec must be a string or [string, object]', 'INVALID_SPEC');
+  if (isRecord(raw) && (raw.options === undefined || isRecord(raw.options))) {
+    return { spec: validatePluginSpec(raw.package), ...(raw.options === undefined ? {} : { options: { ...raw.options } }) };
+  }
+  throw codedError('Plugin spec must be a string or { package, options } object', 'INVALID_SPEC');
 }
 
 function serializePluginEntry(entry) {
   const spec = validatePluginSpec(entry?.spec);
   if (hasOptions(entry?.options)) {
-    return [spec, { ...entry.options }];
+    return { package: spec, options: { ...entry.options } };
   }
   return spec;
 }
@@ -195,10 +216,7 @@ function serializePluginEntry(entry) {
 function listPluginEntries(workingDirectory) {
   const layers = readPluginConfigLayers(workingDirectory);
   return configSources(layers).flatMap((source) => {
-    if (!Array.isArray(source.config?.plugin)) {
-      return [];
-    }
-    return source.config.plugin.map((raw) => {
+    return readPluginArray(source.config).map((raw) => {
       const parsed = parsePluginRaw(raw);
       return {
         id: encodePluginId('config', `${source.scope}:${parsed.spec}`),
@@ -225,8 +243,7 @@ function createPluginEntry(entry, workingDirectory) {
   const layers = readPluginConfigLayers(workingDirectory);
   const existing = configSources(layers).find((source) => (
     source.scope === scope
-    && Array.isArray(source.config?.plugin)
-    && source.config.plugin.some((raw) => parsePluginRaw(raw).spec === spec)
+    && readPluginArray(source.config).some((raw) => parsePluginRaw(raw).spec === spec)
   ));
   if (existing) {
     throw codedError(`Plugin "${spec}" already exists`, 'ENTRY_EXISTS');
@@ -242,11 +259,7 @@ function createPluginEntry(entry, workingDirectory) {
     config = getConfigForPath(layers, targetPath);
   }
 
-  if (!Array.isArray(config.plugin)) {
-    config.plugin = [];
-  }
-  config.plugin.push(serializePluginEntry({ spec, options: entry.options }));
-  writeConfig(config, targetPath);
+  writePluginArray(config, [...readPluginArray(config), serializePluginEntry({ spec, options: entry.options })], targetPath);
 }
 
 function updatePluginEntry(id, updates, workingDirectory) {
@@ -258,7 +271,7 @@ function updatePluginEntry(id, updates, workingDirectory) {
   const nextSpec = updates?.spec === undefined ? existing.spec : validatePluginSpec(updates.spec);
   const nextOptions = updates?.options === undefined ? existing.options : updates.options;
   target.plugin[target.index] = serializePluginEntry({ spec: nextSpec, options: nextOptions });
-  writeConfig(target.source.config, target.source.filePath);
+  writePluginArray(target.source.config, target.plugin, target.source.filePath);
 }
 
 function deletePluginEntry(id, workingDirectory) {
@@ -267,10 +280,7 @@ function deletePluginEntry(id, workingDirectory) {
     throw codedError('Plugin entry not found', 'NOT_FOUND');
   }
   target.plugin.splice(target.index, 1);
-  if (target.plugin.length === 0) {
-    delete target.source.config.plugin;
-  }
-  writeConfig(target.source.config, target.source.filePath);
+  writePluginArray(target.source.config, target.plugin, target.source.filePath);
 }
 
 function listPluginDirFiles(workingDirectory) {