@ours.network/fleet 0.18.0-nightly.6 → 0.18.0

package/dist/harness/codex.js

@@ -5,7 +5,8 @@ import { agentDir, home } from '../paths.js';
 import { realExec } from '../exec.js';
 import { registerAdapter } from './registry.js';
 import { harnessRuntimeDir } from '../isolation/policy.js';
-import { bundledAcpAgent, resolveBundledAcpAgent } from './acp-agent.js';
+import { resolveBundledAcpAgent, } from './acp-agent.js';
+import { restoreLockedHarnessMarketplace } from '../harness-plugins.js';
 const OPTION_KEYS = [
     'launcher', 'sandbox', 'approval', 'permission_mode', 'search', 'profile', 'config', 'add_dirs',
     'monitor',
@@ -51,9 +52,7 @@ function sandboxMode(role) {
         throw new Error(`invalid harness_options.sandbox "${s}"; allowed: ${SANDBOX_MODES.join(', ')}`);
     return s;
 }
-/** codex-acp exposes the same sandbox postures as named ACP agent modes. */
-function acpAgentMode(role) {
-    const sandbox = sandboxMode(role);
+function modeForSandbox(sandbox) {
     if (sandbox === 'read-only')
         return 'read-only';
     if (sandbox === 'workspace-write')
@@ -62,6 +61,26 @@ function acpAgentMode(role) {
         return 'agent-full-access';
     return undefined;
 }
+/**
+ * Resolve the coupled Codex ACP mode.
+ *
+ * The portable approval contract owns the default mode selection: `allow`
+ * means the adapter's fully non-interactive yolo preset and `auto` means its
+ * ordinary agent preset. This intentionally means that Codex ACP cannot retain
+ * an independent neutral filesystem posture for those two modes. An explicit
+ * native sandbox remains authoritative and selects its corresponding preset.
+ */
+function acpAgentMode(role) {
+    const explicitSandbox = role.harness_options?.sandbox;
+    if (explicitSandbox != null)
+        return modeForSandbox(sandboxMode(role));
+    if (role.permissions?.approval === 'allow')
+        return 'agent-full-access';
+    if (role.permissions?.approval === 'auto')
+        return 'agent';
+    const sandbox = sandboxMode(role);
+    return modeForSandbox(sandbox);
+}
 function acpModePermissions(mode) {
     if (mode === 'read-only')
         return { approval: 'on-request', sandbox: 'read-only' };
@@ -69,6 +88,10 @@ function acpModePermissions(mode) {
         return { approval: 'never', sandbox: 'danger-full-access' };
     return { approval: 'on-request', sandbox: 'workspace-write' };
 }
+/** The sandbox Codex will actually receive from the selected coupled ACP mode. */
+function acpRuntimeSandbox(role) {
+    return acpModePermissions(acpAgentMode(role)).sandbox;
+}
 function fleetModeForApproval(nativeMode) {
     if (nativeMode === 'never')
         return 'allow';
@@ -102,6 +125,18 @@ function launcherMode(role) {
 function bundledCodexAcp() {
     return resolveBundledAcpAgent(CODEX_ACP_PACKAGE, 'codex-acp', 'codex-acp');
 }
+/** Bind launch argv and metadata provenance to one already-completed resolution. */
+export function codexAcpLaunchForResolution(resolution) {
+    const permissionMetadataSource = resolution.bundled
+        && resolution.version === BUNDLED_CODEX_ACP_VERSION
+        && resolution.manifestPath !== undefined
+        ? 'codex-acp'
+        : undefined;
+    return {
+        argv: [...resolution.argv],
+        ...(permissionMetadataSource ? { permissionMetadataSource } : {}),
+    };
+}
 function canOverrideBundledAcpApproval() {
     const resolution = bundledCodexAcp();
     return resolution.bundled && resolution.version === BUNDLED_CODEX_ACP_VERSION
@@ -147,7 +182,7 @@ function codexAcpEnvironment(role, dirs) {
     return {
         CODEX_PATH: command,
         [CODEX_PROXY_APPROVAL_ENV]: approvalPolicy(role) ?? 'on-request',
-        [CODEX_PROXY_SANDBOX_ENV]: sandboxMode(role) ?? 'workspace-write',
+        [CODEX_PROXY_SANDBOX_ENV]: acpRuntimeSandbox(role),
         [CODEX_PROXY_MANIFEST_ENV]: resolution.manifestPath,
         ...(process.env.CODEX_PATH ? { [CODEX_PROXY_REAL_PATH_ENV]: process.env.CODEX_PATH } : {}),
     };
@@ -275,6 +310,9 @@ export function makeCodexAdapter(exec = realExec) {
             return errs;
         },
         async prepareSession(role, dirs) {
+            // Re-materialize only from the persisted exact lock. Ordinary launches
+            // never resolve npm tags or run an installer.
+            restoreLockedHarnessMarketplace('codex', role.harnessPluginChannel);
             // Per-role harness runtime home (5.1); harmless for un-isolated roles.
             // Only a role that declares `isolation:` gets a sandbox, and only a
             // sandbox needs this directory to exist before entry.
@@ -285,7 +323,16 @@ export function makeCodexAdapter(exec = realExec) {
             if (requested === 'ours-codex' && !hasOursCodex)
                 throw new Error('harness_options.launcher is ours-codex, but ours-codex is not on PATH; install @ours.network/codex or use launcher: auto');
             const command = requested === 'codex' ? 'codex' : hasOursCodex ? 'ours-codex' : 'codex';
-            return { argv: [], env: codexAcpEnvironment(role, dirs), command };
+            return {
+                argv: [],
+                // OURS_BIND_IDENTITY is the connector's startup bind seed — see the note in
+                // claude-code.ts's prepareSession. It belongs on EVERY harness that runs a
+                // role with an ours identity, not just claude-code: a seed that works on one
+                // harness and silently does nothing on the other is the same class of defect
+                // as a config key that only works on one session type.
+                env: { OURS_BIND_IDENTITY: role.identity, ...codexAcpEnvironment(role, dirs) },
+                command,
+            };
         },
         buildLaunch(role, mode, _s, prep) {
             const stateDir = roleStateDir(role);
@@ -299,17 +346,30 @@ export function makeCodexAdapter(exec = realExec) {
         },
         buildAcpLaunch(role, prep) {
             const configured = role.session_options?.acp?.command;
+            // Resolve once: both argv and permission-metadata provenance must describe
+            // the same artifact. A bare PATH fallback is launchable for compatibility,
+            // but is never authenticated for protected-MCP auto-approval.
+            const resolved = configured == null
+                ? codexAcpLaunchForResolution(bundledCodexAcp())
+                : undefined;
             const argv = Array.isArray(configured)
                 ? [...configured]
                 : typeof configured === 'string'
                     ? ['sh', '-c', configured]
-                    : bundledAcpAgent(CODEX_ACP_PACKAGE, 'codex-acp', 'codex-acp');
+                    : resolved.argv;
             const initialMode = acpAgentMode(role);
             return {
                 argv,
                 env: initialMode ? { ...prep.env, INITIAL_AGENT_MODE: initialMode } : prep.env,
+                ...(resolved?.permissionMetadataSource
+                    ? { permissionMetadataSource: resolved.permissionMetadataSource } : {}),
             };
         },
+        // INITIAL_AGENT_MODE covers session/new in codex-acp; session/set_mode
+        // keeps resumed/loaded sessions and live status on the identical mode.
+        acpPermissionModeId(role) {
+            return acpAgentMode(role);
+        },
         isolationPaths(role, _dirs) {
             const codexHome = join(home(), '.codex');
             const profile = role.harness_options?.profile;
@@ -362,7 +422,9 @@ export function makeCodexAdapter(exec = realExec) {
                 const mode = acpAgentMode(role) ?? 'agent';
                 const configured = role.session_options?.acp?.command;
                 const overrideAvailable = configured == null && canOverrideBundledAcpApproval();
-                const actual = overrideAvailable ? { approval, sandbox } : acpModePermissions(mode);
+                const actual = overrideAvailable
+                    ? { approval, sandbox: acpRuntimeSandbox(role) }
+                    : acpModePermissions(mode);
                 const exact = actual.approval === approval && actual.sandbox === sandbox;
                 return {
                     ...translated,
@@ -372,10 +434,9 @@ export function makeCodexAdapter(exec = realExec) {
                             ? `custom ACP command cannot be verified against approval=${approval} sandbox=${sandbox}; `
                                 + `its '${mode}' mode is conservatively treated as approval=${actual.approval} `
                                 + `sandbox=${actual.sandbox}`
-                            : `codex-acp mode '${mode}' actually uses approval=${actual.approval} `
-                                + `sandbox=${actual.sandbox}, and the bundled ${BUNDLED_CODEX_ACP_VERSION} `
-                                + `app-server override is unavailable; this does not exactly represent `
-                                + `approval=${approval} sandbox=${sandbox}`],
+                            : `Codex ACP mode '${mode}' couples approval and filesystem as `
+                                + `approval=${actual.approval} sandbox=${actual.sandbox}; this does not exactly `
+                                + `represent approval=${approval} sandbox=${sandbox}`],
                     capabilities: codexCapabilities(actual.approval, actual.sandbox),
                 };
             }
@@ -411,6 +472,7 @@ export function makeCodexAdapter(exec = realExec) {
             currentIdentityTool: 'current_identity',
             sendTool: 'send_message',
             getMessagesTool: 'get_messages',
+            watchCommand: id => `ours-mcp watch "${id}"`,
             monitorInstruction: (id, configuredRole) => {
                 const consented = configuredRole?.harness_options?.monitor === true;
                 const consent = consented

package/dist/harness/types.d.ts

@@ -1,3 +1,4 @@
+import type { McpServer } from '@agentclientprotocol/sdk';
 import type { CommonPermissions, FleetPermissionMode, ResolvedRole } from '../config.js';
 export interface PrereqCheck {
     name: string;
@@ -21,14 +22,39 @@ export interface SessionPrep {
     env: Record<string, string>;
     /** Optional launcher selected after runtime prerequisite probing. */
     command?: string;
+    /**
+     * The settings overlay prepareSession wrote, if it wrote one.
+     *
+     * The tmux launch delivers this as `--settings <path>` in `argv`; an ACP agent
+     * takes no flags, so it needs the PATH rather than the flag. Recorded here so
+     * the two deliveries read one value instead of each re-deriving the filename.
+     */
+    settingsOverlay?: string;
+    /**
+     * The MCP config file prepareSession wrote for `harness_options.mcp_servers`,
+     * if the role declared any. Same reason as `settingsOverlay`: the tmux launch
+     * passes the file, the ACP launch has to send the servers themselves.
+     */
+    mcpConfigFile?: string;
 }
+/**
+ * One MCP server as ACP's `session/new` declares it.
+ *
+ * ⚠ THE PROTOCOL'S OWN TYPE, DELIBERATELY NOT A LOCAL RESTATEMENT. `mcpServers`
+ * goes onto the wire unchanged, so a hand-written near-copy would compile while
+ * being subtly wrong — `env` and `headers` are REQUIRED arrays, and the stdio
+ * variant is the one with no `type` field at all. Aliasing it also keeps
+ * `session/new`'s response type inferable, which a structural stand-in silently
+ * broke (every field of the result degraded to `unknown`).
+ */
+export type AcpMcpServer = McpServer;
 export interface Launch {
     argv: string[];
     env: Record<string, string>;
 }
-export interface AcpLaunch {
-    argv: string[];
-    env: Record<string, string>;
+export interface AcpLaunch extends Launch {
+    /** Metadata vocabulary authenticated by the exact ACP artifact in argv. */
+    permissionMetadataSource?: 'codex-acp';
 }
 /**
  * The result of expressing neutral `permissions:` in a harness's own terms.
@@ -67,6 +93,7 @@ export interface BriefingVocab {
     currentIdentityTool: string;
     sendTool: string;
     getMessagesTool: string;
+    watchCommand(identity: string): string;
     monitorInstruction(identity: string, role?: ResolvedRole): string;
     /** Wake-source wording for a role whose monitor is supervisor-owned (monitor.mode=fleet). */
     supervisedWakeNote(identity: string, role?: ResolvedRole): string;
@@ -95,7 +122,13 @@ export interface HarnessAdapter {
     id: string;
     supportsResume: boolean;
     checkPrereqs(): Promise<PrereqReport>;
-    validateOptions(opts: unknown): ValidationError[];
+    /**
+     * `role` is the SESSION-AWARE half: some harness options can only be honoured
+     * on some session types, and an option that is silently dropped is worse than
+     * one that is refused. Optional so an adapter that has nothing session-specific
+     * to say keeps its one-argument implementation.
+     */
+    validateOptions(opts: unknown, role?: ResolvedRole): ValidationError[];
     prepareSession(role: ResolvedRole, dirs: RoleDirs): Promise<SessionPrep>;
     buildLaunch(role: ResolvedRole, mode: 'fresh' | 'resume', s: SessionState, prep: SessionPrep): Launch;
     buildAcpLaunch?(role: ResolvedRole, prep: SessionPrep): AcpLaunch;
@@ -105,6 +138,23 @@ export interface HarnessAdapter {
      * agent's default. Omit for a harness whose ACP agent has no modes.
      */
     acpPermissionModeId?(role: ResolvedRole): string | undefined;
+    /**
+     * The MCP servers this role declares, for the `mcpServers` array of ACP's
+     * `session/new` / `resume` / `load`. Empty (or omitted) leaves the agent's own
+     * configuration alone, which is what fleet has always sent.
+     */
+    acpMcpServers?(role: ResolvedRole): AcpMcpServer[];
+    /**
+     * Agent-specific `_meta` for `session/new` — how a capability the CLI takes as
+     * a flag reaches an ACP agent that accepts no flags.
+     *
+     * ⚠ THIS IS A PER-AGENT VOCABULARY, NOT PROTOCOL. `_meta` is free-form in ACP,
+     * so what an adapter puts here is only honoured by the agent it was written
+     * for. An adapter must therefore return nothing for an ACP command it did not
+     * choose, and the options that depend on it must be refused at validation for
+     * such a role rather than sent and silently ignored.
+     */
+    acpSessionMeta?(role: ResolvedRole, prep: SessionPrep): Record<string, unknown> | undefined;
     /** Effective portable policy and harness-native approval mode after native overrides win. */
     effectivePermissionMode?(role: ResolvedRole): {
         fleetMode: FleetPermissionMode;

package/dist/harness-plugins.d.ts

@@ -0,0 +1,48 @@
+import { type Exec } from './exec.js';
+export declare const HARNESS_PLUGIN_IDS: readonly ["codex", "claude-code"];
+export type HarnessPluginId = (typeof HARNESS_PLUGIN_IDS)[number];
+export type HarnessPluginChannel = 'stable' | 'nightly';
+export interface HarnessPluginConfig {
+    plugin_channel: HarnessPluginChannel;
+}
+export type HarnessPluginConfigs = Record<HarnessPluginId, HarnessPluginConfig>;
+export interface HarnessPluginLock {
+    schemaVersion: 1;
+    harness: HarnessPluginId;
+    channel: HarnessPluginChannel;
+    distTag: 'latest' | 'nightly';
+    package: string;
+    version: string;
+    registry: 'https://registry.npmjs.org';
+    resolvedAt: string;
+}
+export interface HarnessPluginInstallResult {
+    lock: HarnessPluginLock;
+    lockPath: string;
+    marketplacePath: string;
+    resolved: boolean;
+}
+export declare function resolveHarnessPluginConfigs(raw: unknown, file?: string): HarnessPluginConfigs;
+export declare const harnessPluginRoot: (harness: HarnessPluginId) => string;
+export declare const harnessPluginLockPath: (harness: HarnessPluginId) => string;
+export declare const harnessPluginMarketplaceRoot: (harness: HarnessPluginId) => string;
+export declare const harnessPluginMarketplacePath: (harness: HarnessPluginId) => string;
+export declare function readHarnessPluginLock(harness: HarnessPluginId): HarnessPluginLock | undefined;
+/**
+ * Re-materialize the generated marketplace from the persisted exact lock.
+ * This is the ONLY ordinary startup/reconciliation path: it performs no exec,
+ * no network call, and cannot observe a moving npm dist-tag.
+ */
+export declare function restoreLockedHarnessMarketplace(harness: HarnessPluginId, expectedChannel?: HarnessPluginChannel): HarnessPluginLock | undefined;
+/**
+ * Explicit install/update transaction.
+ *
+ * install reuses an existing same-channel lock (deterministic repair/reinstall);
+ * update always resolves the requested channel once and advances the lock.
+ */
+export declare function installHarnessPlugin(harness: HarnessPluginId, channel: HarnessPluginChannel, options?: {
+    update?: boolean;
+    exec?: Exec;
+    now?: () => Date;
+}): Promise<HarnessPluginInstallResult>;
+export declare function selectedHarnessPluginIds(values: string[]): HarnessPluginId[];

package/dist/harness-plugins.js

@@ -0,0 +1,309 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { replaceFileAtomically, withFileLock } from './atomic-file.js';
+import { realExec } from './exec.js';
+import { stateRoot } from './paths.js';
+export const HARNESS_PLUGIN_IDS = ['codex', 'claude-code'];
+const REGISTRY = 'https://registry.npmjs.org';
+const SPECS = {
+    codex: {
+        package: '@ours.network/codex',
+        marketplaceName: 'ours-fleet-codex-lock',
+        marketplaceManifest: '.agents/plugins/marketplace.json',
+        executable: 'codex',
+    },
+    'claude-code': {
+        package: '@ours.network/claude-code',
+        marketplaceName: 'ours-fleet-claude-lock',
+        marketplaceManifest: '.claude-plugin/marketplace.json',
+        executable: 'claude',
+    },
+};
+const EXACT_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export function resolveHarnessPluginConfigs(raw, file = 'fleet.yaml') {
+    const resolved = {
+        codex: { plugin_channel: 'stable' },
+        'claude-code': { plugin_channel: 'stable' },
+    };
+    if (raw === undefined)
+        return resolved;
+    if (!isRecord(raw))
+        throw new Error(`${file}: harnesses must be a map`);
+    const unknown = Object.keys(raw).filter(key => !HARNESS_PLUGIN_IDS.includes(key));
+    if (unknown.length)
+        throw new Error(`${file}: harnesses has unknown harness(es) ${unknown.join(', ')}; allowed: ${HARNESS_PLUGIN_IDS.join(', ')}`);
+    for (const harness of HARNESS_PLUGIN_IDS) {
+        const value = raw[harness];
+        if (value === undefined)
+            continue;
+        if (!isRecord(value))
+            throw new Error(`${file}: harnesses.${harness} must be a map`);
+        const bad = Object.keys(value).filter(key => key !== 'plugin_channel');
+        if (bad.length)
+            throw new Error(`${file}: harnesses.${harness} has unknown key(s) ${bad.join(', ')}; allowed: plugin_channel`);
+        const channel = value.plugin_channel;
+        if (channel !== 'stable' && channel !== 'nightly')
+            throw new Error(`${file}: harnesses.${harness}.plugin_channel must be one of: stable, nightly`);
+        resolved[harness] = { plugin_channel: channel };
+    }
+    return resolved;
+}
+export const harnessPluginRoot = (harness) => join(stateRoot(), 'harness-plugins', harness);
+export const harnessPluginLockPath = (harness) => join(harnessPluginRoot(harness), 'plugin-lock.json');
+export const harnessPluginMarketplaceRoot = (harness) => join(harnessPluginRoot(harness), 'marketplace');
+export const harnessPluginMarketplacePath = (harness) => join(harnessPluginMarketplaceRoot(harness), SPECS[harness].marketplaceManifest);
+function validateLock(value, harness, path) {
+    const spec = SPECS[harness];
+    const fail = (detail) => {
+        throw new Error(`invalid harness plugin lock ${path}: ${detail}; run \`ours-fleet plugins update ${harness}\``);
+    };
+    if (!isRecord(value))
+        return fail('expected a JSON object');
+    if (value.schemaVersion !== 1)
+        fail('unsupported schemaVersion');
+    if (value.harness !== harness)
+        fail(`harness must be '${harness}'`);
+    if (value.channel !== 'stable' && value.channel !== 'nightly')
+        fail('channel must be stable or nightly');
+    const expectedTag = value.channel === 'stable' ? 'latest' : 'nightly';
+    if (value.distTag !== expectedTag)
+        fail(`distTag must be '${expectedTag}' for channel '${value.channel}'`);
+    if (value.package !== spec.package)
+        fail(`package must be '${spec.package}'`);
+    if (typeof value.version !== 'string' || !EXACT_SEMVER.test(value.version))
+        return fail('version must be an exact semver');
+    const version = value.version;
+    if (value.channel === 'stable' && version.includes('-'))
+        fail('stable channel resolved to a prerelease');
+    if (value.channel === 'nightly' && !version.includes('-nightly.'))
+        fail('nightly channel did not resolve to a -nightly.N prerelease');
+    if (value.registry !== REGISTRY)
+        fail(`registry must be '${REGISTRY}'`);
+    if (typeof value.resolvedAt !== 'string' || !Number.isFinite(Date.parse(value.resolvedAt)))
+        fail('resolvedAt must be an ISO timestamp');
+    return value;
+}
+export function readHarnessPluginLock(harness) {
+    const path = harnessPluginLockPath(harness);
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`invalid harness plugin lock ${path}: ${error.message}; `
+            + `run \`ours-fleet plugins update ${harness}\``);
+    }
+    return validateLock(parsed, harness, path);
+}
+function marketplaceDocument(lock) {
+    const spec = SPECS[lock.harness];
+    const source = lock.harness === 'codex'
+        ? { source: 'npm', package: lock.package, version: lock.version, registry: lock.registry }
+        : { source: 'npm', package: lock.package, version: lock.version };
+    if (lock.harness === 'codex') {
+        return {
+            name: spec.marketplaceName,
+            interface: { displayName: `ours.network (${lock.channel}, locked ${lock.version})` },
+            plugins: [{
+                    name: 'ours', source,
+                    policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+                    category: 'Productivity',
+                }],
+        };
+    }
+    return {
+        $schema: 'https://json.schemastore.org/claude-code-marketplace.json',
+        name: spec.marketplaceName,
+        owner: { name: 'Adapt Framework Solutions Ltd', url: 'https://ours.network' },
+        description: `Generated by ours-fleet; @ours.network/claude-code is locked to ${lock.version}.`,
+        plugins: [{
+                name: 'ours', source,
+                description: 'Secure ours.network messaging for Claude Code.',
+            }],
+    };
+}
+function writeMarketplace(lock) {
+    const path = harnessPluginMarketplacePath(lock.harness);
+    replaceFileAtomically(path, `${JSON.stringify(marketplaceDocument(lock), null, 2)}\n`, 0o644);
+    return path;
+}
+/**
+ * Re-materialize the generated marketplace from the persisted exact lock.
+ * This is the ONLY ordinary startup/reconciliation path: it performs no exec,
+ * no network call, and cannot observe a moving npm dist-tag.
+ */
+export function restoreLockedHarnessMarketplace(harness, expectedChannel) {
+    const lock = readHarnessPluginLock(harness);
+    if (!lock) {
+        if (expectedChannel === 'nightly')
+            throw new Error(`harness '${harness}' requests nightly but has no exact lock; `
+                + `run \`ours-fleet plugins install ${harness}\``);
+        return undefined;
+    }
+    if (expectedChannel && lock.channel !== expectedChannel)
+        throw new Error(`harness '${harness}' requests ${expectedChannel} but its exact lock is ${lock.channel} `
+            + `(${lock.version}); run \`ours-fleet plugins update ${harness}\``);
+    if (lock)
+        writeMarketplace(lock);
+    return lock;
+}
+async function checked(exec, command, args, action) {
+    const result = await exec(command, args);
+    if (result.code !== 0)
+        throw new Error(`${action} failed (${command} ${args.join(' ')}): ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`);
+    return result;
+}
+function parseJson(output, action) {
+    try {
+        return JSON.parse(output);
+    }
+    catch (error) {
+        throw new Error(`${action} returned invalid JSON: ${error.message}`);
+    }
+}
+async function resolveExactVersion(harness, channel, exec, now) {
+    const spec = SPECS[harness];
+    const distTag = channel === 'stable' ? 'latest' : 'nightly';
+    const result = await checked(exec, 'npm', ['view', `${spec.package}@${distTag}`, 'version', '--json'], `resolve ${spec.package} ${distTag}`);
+    const version = parseJson(result.stdout, `npm view ${spec.package}@${distTag}`);
+    if (typeof version !== 'string' || !EXACT_SEMVER.test(version))
+        throw new Error(`npm view ${spec.package}@${distTag} did not return one exact semver`);
+    if (channel === 'stable' && version.includes('-'))
+        throw new Error(`refusing stable ${spec.package}: npm latest resolved to prerelease ${version}`);
+    if (channel === 'nightly' && !version.includes('-nightly.'))
+        throw new Error(`refusing nightly ${spec.package}: npm nightly resolved to ${version}`);
+    return {
+        schemaVersion: 1,
+        harness,
+        channel,
+        distTag,
+        package: spec.package,
+        version,
+        registry: REGISTRY,
+        resolvedAt: now().toISOString(),
+    };
+}
+function marketplaceEntries(harness, output) {
+    const parsed = parseJson(output, `${SPECS[harness].executable} plugin marketplace list`);
+    if (harness === 'codex') {
+        if (!isRecord(parsed) || !Array.isArray(parsed.marketplaces))
+            throw new Error('codex plugin marketplace list returned an unexpected shape');
+        return parsed.marketplaces.filter(isRecord);
+    }
+    if (!Array.isArray(parsed))
+        throw new Error('claude plugin marketplace list returned an unexpected shape');
+    return parsed.filter(isRecord);
+}
+async function ensureMarketplaceRegistered(harness, exec) {
+    const spec = SPECS[harness];
+    const root = harnessPluginMarketplaceRoot(harness);
+    const result = await checked(exec, spec.executable, ['plugin', 'marketplace', 'list', '--json'], `list ${harness} marketplaces`);
+    const existing = marketplaceEntries(harness, result.stdout)
+        .find(entry => entry.name === spec.marketplaceName);
+    if (existing) {
+        if (harness === 'codex') {
+            const declared = isRecord(existing.marketplaceSource)
+                ? existing.marketplaceSource.source : existing.root;
+            if (typeof declared !== 'string' || resolve(declared) !== resolve(root))
+                throw new Error(`marketplace '${spec.marketplaceName}' already exists but does not point to ${root}; `
+                    + 'refusing to replace an unrelated marketplace');
+        }
+        else {
+            // Claude copies marketplace contents into its cache, but retains the
+            // source kind in list output. Refresh that copy after each lock update.
+            if (existing.source !== 'directory')
+                throw new Error(`marketplace '${spec.marketplaceName}' already exists but is not a local directory; `
+                    + 'refusing to replace an unrelated marketplace');
+            await checked(exec, 'claude', ['plugin', 'marketplace', 'update', spec.marketplaceName], `refresh ${harness} locked marketplace`);
+        }
+        return;
+    }
+    const args = harness === 'codex'
+        ? ['plugin', 'marketplace', 'add', root, '--json']
+        : ['plugin', 'marketplace', 'add', root, '--scope', 'user'];
+    await checked(exec, spec.executable, args, `register ${harness} locked marketplace`);
+}
+async function removeLegacyPluginSelections(harness, exec) {
+    const spec = SPECS[harness];
+    const result = await checked(exec, spec.executable, ['plugin', 'list', '--json'], `list ${harness} plugins`);
+    const parsed = parseJson(result.stdout, `${spec.executable} plugin list`);
+    if (harness === 'codex' && (!isRecord(parsed) || !Array.isArray(parsed.installed)))
+        throw new Error('codex plugin list returned an unexpected shape');
+    if (harness === 'claude-code' && !Array.isArray(parsed))
+        throw new Error('claude plugin list returned an unexpected shape');
+    const entries = (harness === 'codex'
+        ? parsed.installed
+        : parsed).filter(isRecord);
+    const ids = new Set(entries
+        .map(entry => harness === 'codex' ? entry.pluginId : entry.id)
+        .filter((id) => typeof id === 'string'));
+    const legacy = harness === 'codex'
+        ? ['ours@ours-codex-marketplace', 'ours-fleet@ours-codex-marketplace']
+        : ['ours@ours', 'ours@ours.network'];
+    for (const selector of legacy.filter(id => ids.has(id))) {
+        const args = harness === 'codex'
+            ? ['plugin', 'remove', selector, '--json']
+            : ['plugin', 'uninstall', selector, '--scope', 'user', '--keep-data'];
+        await checked(exec, spec.executable, args, `remove legacy moving selection ${selector}`);
+    }
+}
+async function installFromLock(lock, exec) {
+    const spec = SPECS[lock.harness];
+    // The Codex package also owns the ours-codex launcher. Pin that executable to
+    // the same exact artifact as the local marketplace; never invoke its broad
+    // installer, which may select daemon/SDK packages outside this feature.
+    if (lock.harness === 'codex') {
+        await checked(exec, 'npm', ['install', '--global', `${lock.package}@${lock.version}`], `install ${lock.package}@${lock.version}`);
+    }
+    await ensureMarketplaceRegistered(lock.harness, exec);
+    const selector = `ours@${spec.marketplaceName}`;
+    const args = lock.harness === 'codex'
+        ? ['plugin', 'add', selector, '--json']
+        : ['plugin', 'install', selector, '--scope', 'user'];
+    await checked(exec, spec.executable, args, `install ${selector}`);
+    // The same plugin under an older Git marketplace is a distinct harness
+    // selection and can remain enabled beside the lock. Remove only the known
+    // ours selectors, after the exact local selection is installed successfully.
+    await removeLegacyPluginSelections(lock.harness, exec);
+}
+/**
+ * Explicit install/update transaction.
+ *
+ * install reuses an existing same-channel lock (deterministic repair/reinstall);
+ * update always resolves the requested channel once and advances the lock.
+ */
+export async function installHarnessPlugin(harness, channel, options = {}) {
+    const exec = options.exec ?? realExec;
+    const root = harnessPluginRoot(harness);
+    return withFileLock(`${root}.lock`, async () => {
+        const existing = readHarnessPluginLock(harness);
+        const mustResolve = options.update === true || !existing || existing.channel !== channel;
+        const lock = mustResolve
+            ? await resolveExactVersion(harness, channel, exec, options.now ?? (() => new Date()))
+            : existing;
+        if (mustResolve)
+            replaceFileAtomically(harnessPluginLockPath(harness), `${JSON.stringify(lock, null, 2)}\n`);
+        // Publish the lock first. If installation is interrupted, every retry uses
+        // this same exact version; no half-finished transaction can observe a newer
+        // dist-tag on its own.
+        const marketplacePath = writeMarketplace(lock);
+        await installFromLock(lock, exec);
+        return {
+            lock,
+            lockPath: harnessPluginLockPath(harness),
+            marketplacePath,
+            resolved: mustResolve,
+        };
+    });
+}
+export function selectedHarnessPluginIds(values) {
+    if (!values.length)
+        return [...HARNESS_PLUGIN_IDS];
+    const unknown = values.filter(value => !HARNESS_PLUGIN_IDS.includes(value));
+    if (unknown.length)
+        throw new Error(`unknown harness(es) ${unknown.join(', ')}; allowed: ${HARNESS_PLUGIN_IDS.join(', ')}`);
+    return [...new Set(values)];
+}

package/dist/index.d.ts

@@ -28,3 +28,5 @@ export { doctor } from './doctor.js';
 export { runOnce, runTemp } from './runner.js';
 export { Tmux } from './tmux.js';
 export { VERSION } from './version.js';
+export { HARNESS_PLUGIN_IDS, installHarnessPlugin, readHarnessPluginLock, restoreLockedHarnessMarketplace, resolveHarnessPluginConfigs, } from './harness-plugins.js';
+export type { HarnessPluginId, HarnessPluginChannel, HarnessPluginConfig, HarnessPluginConfigs, HarnessPluginLock, HarnessPluginInstallResult, } from './harness-plugins.js';

package/dist/index.js

@@ -23,3 +23,4 @@ export { doctor } from './doctor.js';
 export { runOnce, runTemp } from './runner.js';
 export { Tmux } from './tmux.js';
 export { VERSION } from './version.js';
+export { HARNESS_PLUGIN_IDS, installHarnessPlugin, readHarnessPluginLock, restoreLockedHarnessMarketplace, resolveHarnessPluginConfigs, } from './harness-plugins.js';