@spexcode/spec-cli 0.6.5

package/dist/harness-select.d.ts

@@ -0,0 +1,18 @@
+import { type Harness, type HarnessId } from './harness.js';
+export type HarnessTarget = {
+    kind: 'native';
+    id: HarnessId;
+} | {
+    kind: 'plugin';
+    folder: string;
+};
+export declare const NATIVE_HARNESS_IDS: readonly HarnessId[];
+export declare function parseHarnessFlag(spec: string): unknown[];
+export declare function resolveHarnessTargets(raw: unknown): HarnessTarget[];
+export declare function partitionHarnesses(targets: HarnessTarget[]): {
+    selected: Harness[];
+    unselected: Harness[];
+    plugins: {
+        folder: string;
+    }[];
+};

package/dist/harness-select.js

@@ -0,0 +1,62 @@
+import { HARNESSES } from './harness.js';
+// the native vocabulary (for messages and init's flag parsing). There is NO default set: the delivery
+// targets are an explicit adopter choice, stamped by `spex init --harness` and read back from config forever.
+export const NATIVE_HARNESS_IDS = HARNESSES.map((h) => h.id);
+const KNOWN = HARNESSES.map((h) => h.id);
+// the one-line repair every missing-selection error carries — the field is REQUIRED, never defaulted,
+// because with many harnesses a silent "deliver everywhere" would litter the adopter's tree with artifacts
+// for tools they never installed.
+const MISSING = `spexcode.json has no "harnesses" field — the delivery targets are an EXPLICIT choice, never a default. Declare it, e.g. "harnesses": ["claude"] — members are native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}. Fresh adoption: \`spex init --harness <ids>\` stamps it.`;
+// parse `spex init --harness <spec>` into the raw JSON members the `harnesses` field carries: a comma-
+// separated list where `plugin:<folder>` means a plugin target and anything else is a native id. Pure
+// spelling translation — legality (unknown ids, plugin exclusivity) stays with resolveHarnessTargets.
+export function parseHarnessFlag(spec) {
+    return spec.split(',').map((s) => s.trim()).filter(Boolean)
+        .map((s) => (s.startsWith('plugin:') ? { plugin: s.slice('plugin:'.length) } : s));
+}
+// parse + validate the spexcode.json `harnesses` field into resolved targets. FAIL LOUD on an illegal set —
+// materialize and init both gate on this so a bad config never silently delivers the wrong thing. `raw` is the
+// JSON value as written; a MISSING field is itself illegal (the choice must exist, stamped by init).
+export function resolveHarnessTargets(raw) {
+    if (raw === undefined || raw === null)
+        throw new Error(MISSING);
+    if (!Array.isArray(raw))
+        throw new Error(`spexcode.json "harnesses" must be an ARRAY of targets (got ${typeof raw}). Members are native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}.`);
+    if (raw.length === 0)
+        throw new Error(`spexcode.json "harnesses" is EMPTY — list at least one target: native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}.`);
+    const targets = [];
+    for (const m of raw) {
+        if (typeof m === 'string') {
+            if (m === 'plugin')
+                throw new Error(`spexcode.json "harnesses": a plugin target needs an EXPLICIT landing folder — write {"plugin":"<folder>"} (e.g. {"plugin":".adopter-a"}), not the bare string "plugin", because each host agent reads a different plugins dir.`);
+            if (!KNOWN.includes(m))
+                throw new Error(`spexcode.json "harnesses": unknown harness id "${m}" — known native ids are ${KNOWN.join(', ')}, or use {"plugin":"<folder>"}.`);
+            targets.push({ kind: 'native', id: m });
+        }
+        else if (m && typeof m === 'object' && !Array.isArray(m) && 'plugin' in m) {
+            const folder = m.plugin;
+            if (typeof folder !== 'string' || !folder.trim())
+                throw new Error(`spexcode.json "harnesses": a {"plugin":…} target needs a NON-EMPTY folder string (e.g. {"plugin":".adopter-a"}) — each host agent reads a different plugins dir, so the folder must be explicit.`);
+            targets.push({ kind: 'plugin', folder: folder.trim() });
+        }
+        else {
+            throw new Error(`spexcode.json "harnesses": each member must be a native id string (${KNOWN.join(', ')}) or a {"plugin":"<folder>"} object — got ${JSON.stringify(m)}.`);
+        }
+    }
+    // PLUGIN EXCLUSIVITY: a plugin bundle is a SUPERSET delivery to its host agent, so pairing it with any
+    // native harness double-delivers. So a set with a plugin may carry NO native harness.
+    const natives = targets.filter((t) => t.kind === 'native');
+    if (targets.some((t) => t.kind === 'plugin') && natives.length)
+        throw new Error(`spexcode.json "harnesses": a plugin target is EXCLUSIVE — it cannot coexist with native harnesses (${natives.map((t) => t.id).join(', ')}). A plugin bundle already delivers the whole system to its host agent, so pairing it with a native harness double-delivers. Choose EITHER native harnesses OR plugin target(s).`);
+    return targets;
+}
+// split the live HARNESSES adapters by whether the resolved targets SELECT them: selected get write()n,
+// unselected get clean()ed (pruned). `plugins` carries the plugin targets (no emitter yet — a later node).
+export function partitionHarnesses(targets) {
+    const selectedIds = new Set(targets.filter((t) => t.kind === 'native').map((t) => t.id));
+    return {
+        selected: HARNESSES.filter((h) => selectedIds.has(h.id)),
+        unselected: HARNESSES.filter((h) => !selectedIds.has(h.id)),
+        plugins: targets.filter((t) => t.kind === 'plugin').map((t) => ({ folder: t.folder })),
+    };
+}

package/dist/harness.d.ts

@@ -0,0 +1,325 @@
+import { type SlashCommand } from './slash-commands.js';
+import { type ExecutionTrace, type ExecutionTurn } from './execution-trace.js';
+import { type HarnessId } from '@spexcode/spec-core';
+export type { HarnessId } from '@spexcode/spec-core';
+export type HarnessLivenessRecord = {
+    session: string;
+    harnessSessionId?: string | null;
+    stopped?: boolean;
+    archived?: boolean;
+};
+export type HarnessLaunchReadyRecord = HarnessLivenessRecord & {
+    governed?: boolean;
+    runtimeDir: string;
+};
+export type HarnessLaunchReadinessFence = {
+    readonly proof: Readonly<Record<string, unknown>>;
+    validate(current: () => HarnessLaunchReadyRecord | null): Promise<boolean>;
+};
+export type TurnFailure = {
+    message: string;
+    completedAt: number | null;
+};
+export type FailureSubscription = {
+    close(): void;
+    readonly closed: Promise<string | null>;
+};
+export type ProcTable = Map<number, {
+    ppid: number;
+    comm: string;
+}>;
+export type PaneProbe = {
+    panePid?: number;
+    procs?: ProcTable;
+    pidAlive?: boolean;
+};
+export type SharedRuntimeDescriptor = {
+    key: string;
+    label: string;
+    pidFile: string;
+    receiptFile: string;
+    targetDescriptorKey?: (rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }) => string | null;
+    residency?: () => Promise<{
+        healthy: boolean;
+        referenceIds: string[];
+        error?: string;
+        rootAbsent?: boolean;
+    }>;
+    mutationGuard?: (targetReferenceId: string, opts?: {
+        coldReceipt?: unknown;
+    }) => Promise<SharedRuntimeMutationGuard>;
+    probe(): Promise<SharedRuntimeProbe>;
+};
+export type SharedRuntimeMutationGuard = {
+    healthy: boolean;
+    referenceIds: string[];
+    targetTurnPresence: 'none' | 'idle' | 'active' | 'unknown';
+    descendantIds: string[];
+    coldTeardownAuthorized?: boolean;
+    error?: string;
+};
+export type SharedRuntimeProbe = {
+    healthy: boolean;
+    references: Array<{
+        referenceId: string;
+        turnPresence: 'idle' | 'active' | 'unknown';
+        turnId?: string;
+    }>;
+    error?: string;
+};
+export type HarnessColdPreflight = {
+    ok: true;
+    alreadyCold?: boolean;
+    receipt?: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+export type HarnessOrphanThreadQuarantine = {
+    ok: true;
+    audit: {
+        adapter: string;
+        threadId: string;
+        action: 'archived' | 'already-unloaded';
+    };
+    compensate(): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+} | {
+    ok: false;
+    reason: string;
+};
+export type AdapterLoadedReferenceState = {
+    healthy: boolean;
+    loaded: boolean;
+    error?: string;
+};
+export declare function adapterLoadedReferenceState(records: readonly (HarnessLivenessRecord & {
+    harness?: string;
+})[], runtimeDir?: string): Promise<Map<string, AdapterLoadedReferenceState>>;
+export interface Harness {
+    readonly id: HarnessId;
+    readonly dispatchId: 'claude' | 'codex' | 'opencode' | 'pi' | 'zcode';
+    readonly headless: boolean;
+    readonly launchOneShot?: boolean;
+    readonly runtimeOwnership?: 'leaf' | 'adapter';
+    readonly sharedRuntimeSpawn?: boolean;
+    readonly fatalLaunchOutput?: readonly string[];
+    readonly events: readonly string[];
+    readonly ownsRendezvous: boolean;
+    readonly paneTitleIsSelfSummary: boolean;
+    executionTrace(threadId: string, turn: ExecutionTurn | null): ExecutionTrace | null;
+    launchCmd(id: string, runtimeDir?: string, cmd?: string): string;
+    baseCmd(cmd?: string): string;
+    oneShotTurn?(prompt: string, cmd?: string): {
+        command: string;
+        stdin: string;
+    };
+    sessionIdArg(id: string): string;
+    readonly sessionEnvVar: string;
+    launchEnv(id: string): string[];
+    shimFile(proj: string): string;
+    shimScope: 'tree' | 'project';
+    worktreeHookAnchor(proj: string): string | null;
+    contractFiles(proj: string): string[];
+    skillDir(proj: string): string | null;
+    agentDir(proj: string): string | null;
+    shim(dispatch: string, spex: string): {
+        content: string;
+        cmd: (e: string) => string;
+    };
+    writeTrust(proj: string, cmdFor: (e: string) => string): readonly string[];
+    slashCommands(): SlashCommand[];
+    liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline';
+    launchReady?(current: () => HarnessLaunchReadyRecord | null, deadline: number): Promise<HarnessLaunchReadinessFence | null>;
+    leafOwnerNeedle?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }): string | null;
+    deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>;
+    observeTurnFailures?(rec: HarnessDeliveryRecord, onFailure: (failure: TurnFailure) => void): FailureSubscription;
+    interrupt?(rec: HarnessDeliveryRecord): Promise<DispatchResult>;
+    cleanupRuntime(rec: HarnessLivenessRecord): Promise<void>;
+    coldPreflight?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }): Promise<HarnessColdPreflight>;
+    coldRetirementPreflight?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }): Promise<{
+        ok: true;
+        alreadyCold: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    coldRuntime?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }, receipt?: unknown): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    restoreRuntime?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }, receipt?: unknown): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    quarantineOrphanThread?(threadId: string, opts: {
+        excludingSessionId: string;
+    }): Promise<HarnessOrphanThreadQuarantine>;
+    sharedRuntimes?(runtimeDir: string): readonly SharedRuntimeDescriptor[];
+    targetDescriptorKey?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }): string | null;
+    deliveryBlockedBy?(paneText: string): string | null;
+    clean(proj: string, arts: HarnessArtifacts, preserveProject?: boolean): void;
+    removeTrust(proj: string): void;
+    resumeArg(rec: {
+        session: string;
+        harnessSessionId?: string | null;
+    }): string;
+}
+export type DispatchResult = {
+    ok: boolean;
+    error?: string;
+};
+export type HarnessDeliveryRecord = {
+    session: string;
+    worktreePath?: string;
+    harnessSessionId?: string | null;
+    runtimeDir?: string;
+    launchCmd?: string | null;
+    mid?: string;
+};
+export type HarnessArtifacts = {
+    skills: readonly string[];
+    agents: readonly string[];
+};
+export declare const legacyRvSock: (id: string) => string;
+export declare const scopedRvSock: (id: string, dir?: string) => string;
+export declare const rvSock: (id: string) => string;
+export declare function stampRvSock(id: string, dir?: string): string;
+export type ListenerProbe = 'live' | 'dead' | 'unproven';
+export declare function listenerAt(path: string, timeoutMs?: number): Promise<ListenerProbe>;
+export declare const rendezvousListening: (id: string, timeoutMs?: number) => Promise<ListenerProbe>;
+export declare const codexAppServerSock: (dir?: string) => string;
+export declare const codexAppServerPid: (dir?: string) => string;
+export declare const codexAppServerReceipt: (dir?: string) => string;
+export declare function deliverViaRendezvous(id: string, text: string, mid?: string): Promise<DispatchResult>;
+export declare function deliverViaClaudeRendezvous(id: string, text: string, mid?: string, runtimeDir?: string): Promise<DispatchResult>;
+export declare function deliverViaSocketOrWake(id: string, text: string, mid: string | undefined, coldWake: () => Promise<DispatchResult>, unprovenError: string): Promise<DispatchResult>;
+type JsonRpc = {
+    id?: number;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code?: number;
+        message?: string;
+    };
+};
+export declare function codexHandshakeMessages(threadId: string): JsonRpc[];
+export declare function codexInjectMessage(threadId: string, text: string, cwd: string | undefined, activeTurnId: string | null, id?: number, clientUserMessageId?: string): JsonRpc;
+export declare function activeTurnIdFromThread(readResult: unknown): string | null;
+export declare function codexBinary(codexCmd: string): string;
+export type CodexThreadPolicy = {
+    approvalPolicy?: 'untrusted' | 'on-request' | 'never';
+    sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
+};
+export declare function codexLauncherThreadPolicy(command: string): CodexThreadPolicy;
+export declare function codexSupportsBypassHookTrust(binary: string): boolean;
+export declare function reportHeadlessTurnExit(id: string, harness: string, code: number | null, cwd?: string): Promise<void>;
+export declare function headlessTurnFailureShell(harness: string, swallow?: boolean): string;
+export declare function sessionIdentityEnvVars(): string[];
+export declare function codexLaunchCommand(id: string, codexCmd?: string, serverCmd?: string, dir?: string, attachTui?: boolean): string;
+export declare function codexTurnFailureObserver(rec: HarnessDeliveryRecord, onFailure: (failure: TurnFailure) => void): FailureSubscription;
+export declare const CODEX_THREAD_SOURCE_KINDS: readonly ["cli", "vscode", "exec", "appServer", "subAgent", "subAgentReview", "subAgentCompact", "subAgentThreadSpawn", "subAgentOther", "unknown"];
+export declare function codexLoadedReferenceIds(sock: string): Promise<{
+    ok: true;
+    referenceIds: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function codexThreadList(sock: string, params: Record<string, unknown>): Promise<{
+    ok: true;
+    ids: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function codexThreadId(sock: string): Promise<{
+    ok: true;
+    threadId: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function codexSharedRuntimeProbe(dir?: string, endpoint?: Readonly<{
+    id: string;
+    pidFile: string;
+    receiptFile: string;
+    logFile: string;
+    socketPath: string;
+}>): Promise<SharedRuntimeProbe>;
+export declare function codexStartThreadParams(cwd?: string, bypassHookTrust?: boolean, shellEnv?: Record<string, string>, policy?: CodexThreadPolicy): Record<string, unknown>;
+export declare function codexStartThread(sock: string, cwd?: string, bypassHookTrust?: boolean, shellEnv?: Record<string, string>, policy?: CodexThreadPolicy): Promise<{
+    ok: true;
+    threadId: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function codexTurn(sock: string, threadId: string, text: string, cwd?: string, clientUserMessageId?: string): Promise<DispatchResult>;
+export declare function codexRolloutExists(threadId: string, root?: string): boolean;
+export declare function codexRolloutBytes(threadId: string, root?: string): {
+    bytes: number;
+} | {
+    unreadable: true;
+};
+export declare function waitForCodexRollout(threadId: string, timeoutMs?: number): Promise<boolean>;
+export declare function writeManagedBlock(file: string, body: string, comment?: readonly [string, string]): boolean;
+export declare function removeManagedBlock(file: string, comment?: readonly [string, string], deleteIfEmpty?: boolean): void;
+export declare function codexHookHash(snakeEvent: string, command: string, timeout?: number, asyncFlag?: boolean): string;
+export declare function writeCodexTrust(proj: string, events: readonly string[], cmdFor: (e: string) => string): string;
+export declare function paneTreeRunsCodex(pane?: PaneProbe): boolean;
+export declare function procSnapshot(timeoutMs?: number): Promise<ProcTable>;
+export declare function opencodeLaunchCommand(opencodeCmd?: string): string;
+export declare const unlinkSocks: (...paths: string[]) => Promise<void>;
+export declare const claudeHarness: Harness;
+export declare const claudeHeadlessHarness: Harness;
+export declare const codexHarness: Harness;
+export declare const codexHeadlessHarness: Harness;
+export declare const piHarness: Harness;
+export declare const piHeadlessHarness: Harness;
+export declare const zcodeHarness: Harness;
+export declare const opencodeHarness: Harness;
+export declare const opencodeHeadlessHarness: Harness;
+export declare const HARNESSES: readonly Harness[];
+export declare const defaultHarness: Harness;
+export declare function harnessByIdOrNull(id: string): Harness | null;
+export declare function harnessById(id: string): Harness;
+export type Launcher = {
+    name: string;
+    harness: string;
+    cmd: string;
+    headless: boolean;
+};
+export type LauncherDefault = {
+    default: string | null;
+    error: string | null;
+};
+export declare function launcherList(root?: string): Launcher[];
+export declare function dashboardLauncherList(root?: string): Launcher[];
+export declare const MISSING_DEFAULT_LAUNCHER_ERROR = "sessions.defaultLauncher is required for a launch without --launcher; set it in spexcode.json or spexcode.local.json (for example {\"sessions\":{\"defaultLauncher\":\"claude\"}})";
+export declare function defaultLauncher(root?: string): string;
+export declare function launcherDefault(root?: string): LauncherDefault;
+export declare function resolveLauncher(name: string, root?: string): Launcher;