@spexcode/spec-cli 0.6.6 → 0.6.8

package/dist/harness-select.js

@@ -6,11 +6,17 @@ 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.`;
+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>"}, and [] means deliver into NO harness (the L0-only posture, \`spex init --harness none\`). Fresh adoption: \`spex init --harness <ids>\` stamps it.`;
+// the CLI spelling of the empty set. `--harness none` is a whole-selection word, not a member: mixing it with
+// a real target is a contradiction, so it only translates when it IS the entire flag (otherwise it falls
+// through as an unknown id and resolveHarnessTargets says why).
+const NO_DELIVERY = 'none';
 // 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) {
+    if (spec.trim() === NO_DELIVERY)
+        return [];
     return spec.split(',').map((s) => s.trim()).filter(Boolean)
         .map((s) => (s.startsWith('plugin:') ? { plugin: s.slice('plugin:'.length) } : s));
 }
@@ -22,15 +28,22 @@ export function resolveHarnessTargets(raw) {
         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>"}.`);
+    // THE EMPTY SET IS A LEGAL, EXPLICIT CHOICE: deliver into no harness at all. That is the L0-only posture —
+    // the spec tree, the lint, and the git hooks, with zero artifacts written into any agent's config. It is
+    // distinct from a MISSING field (undefined/null, rejected above): [] is somebody saying "none", not
+    // somebody forgetting to choose. Everything downstream already handles it — materialize's erase phase
+    // prunes whatever a previous selection delivered, and the published allowlist admits nothing.
     if (raw.length === 0)
-        throw new Error(`spexcode.json "harnesses" is EMPTY — list at least one target: native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}.`);
+        return [];
     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 (m === NO_DELIVERY)
+                throw new Error(`spexcode.json "harnesses": "${NO_DELIVERY}" is not a member — it is the CLI spelling of the WHOLE selection being empty. Write "harnesses": [] for no delivery, or drop "${NO_DELIVERY}" and keep the real targets (\`spex init --harness none\` cannot be combined with another id).`);
             if (!KNOWN.includes(m))
-                throw new Error(`spexcode.json "harnesses": unknown harness id "${m}" — known native ids are ${KNOWN.join(', ')}, or use {"plugin":"<folder>"}.`);
+                throw new Error(`spexcode.json "harnesses": unknown harness id "${m}" — known native ids are ${KNOWN.join(', ')}, or use {"plugin":"<folder>"}; [] (\`--harness ${NO_DELIVERY}\`) delivers into no harness at all.`);
             targets.push({ kind: 'native', id: m });
         }
         else if (m && typeof m === 'object' && !Array.isArray(m) && 'plugin' in m) {

package/dist/harness.d.ts

@@ -1,5 +1,6 @@
 import { type SlashCommand } from './slash-commands.js';
 import { type ExecutionTrace, type ExecutionTurn } from './execution-trace.js';
+import { type TranscriptRead, type TranscriptRange } from './transcript-reader.js';
 import { type HarnessId } from '@spexcode/spec-core';
 export type { HarnessId } from '@spexcode/spec-core';
 export type HarnessLivenessRecord = {
@@ -23,6 +24,7 @@ export type TurnFailure = {
 export type FailureSubscription = {
     close(): void;
     readonly closed: Promise<string | null>;
+    readonly ready?: Promise<boolean>;
 };
 export type DeliveryTransportState = {
     kind: 'reachable';
@@ -58,7 +60,7 @@ export type SharedRuntimeDescriptor = {
     mutationGuard?: (targetReferenceId: string, opts?: {
         coldReceipt?: unknown;
     }) => Promise<SharedRuntimeMutationGuard>;
-    probe(): Promise<SharedRuntimeProbe>;
+    probe(referenceIds?: readonly string[]): Promise<SharedRuntimeProbe>;
 };
 export type SharedRuntimeMutationGuard = {
     healthy: boolean;
@@ -122,6 +124,7 @@ export interface Harness {
     readonly ownsRendezvous: boolean;
     readonly paneTitleIsSelfSummary: boolean;
     executionTrace(threadId: string, turn: ExecutionTurn | null): ExecutionTrace | null;
+    readTranscript(threadId: string, range: TranscriptRange): Promise<TranscriptRead>;
     launchCmd(id: string, runtimeDir?: string, cmd?: string): string;
     baseCmd(cmd?: string): string;
     oneShotTurn?(prompt: string, cmd?: string): {
@@ -139,8 +142,10 @@ export interface Harness {
     agentDir(proj: string): string | null;
     shim(dispatch: string, spex: string): {
         content: string;
+        hooks?: Record<string, unknown[]>;
         cmd: (e: string) => string;
     };
+    shimOwnership: 'exclusive' | 'shared-json';
     writeTrust(proj: string, cmdFor: (e: string) => string): readonly string[];
     slashCommands(): SlashCommand[];
     liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline';
@@ -226,7 +231,7 @@ export declare const rendezvousListening: (id: string, timeoutMs?: number) => Pr
 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 deliverViaRendezvous(id: string, text: string, mid?: string, wallMs?: number): 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 = {
@@ -242,6 +247,7 @@ type JsonRpc = {
 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 codexObservedActiveTurnId(threadId: string): string | null;
 export declare function codexBinary(codexCmd: string): string;
 export type CodexThreadPolicy = {
     approvalPolicy?: 'untrusted' | 'on-request' | 'never';
@@ -253,6 +259,7 @@ export declare function reportHeadlessTurnExit(id: string, harness: string, code
 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 const CODEX_TURN_OBSERVER_SUBSCRIBE_MS = 30000;
 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<{
@@ -282,7 +289,7 @@ export declare function codexSharedRuntimeProbe(dir?: string, endpoint?: Readonl
     receiptFile: string;
     logFile: string;
     socketPath: string;
-}>): Promise<SharedRuntimeProbe>;
+}>, referenceIds?: readonly 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;
@@ -301,6 +308,11 @@ export declare function codexRolloutBytes(threadId: string, root?: string): {
 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 writeManagedJsonHooks(file: string, hooks: Record<string, unknown[]>): boolean;
+export declare function removeManagedJsonHooks(file: string): void;
+export declare function sharedShimHasHostContent(file: string): boolean;
+export declare const GENERATED_MARK = "<!-- spexcode:generated -->";
+export declare function isGeneratedArtifact(file: string): boolean;
 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;