spexcode 0.6.6 → 0.6.8

package/node_modules/@spexcode/spec-cli/dist/guide.js

@@ -71,8 +71,9 @@ FRONTMATTER (YAML between the opening and closing --- lines; every field optiona
            duplicates, globs/directories with a selector, and dead/ambiguous units all error loud. A
            selector-scoped governor claims units, not the file, so it stays out of the \`owners\` bound
            (spex spec owner still displays it, marked "(scoped)"). Anchors are optional.
-           Python \`.py\`/\`.pyi\` anchors recognize structural \`def\`, \`async def\`, and \`class\`
-           declarations. Methods and nested declarations use lexical qualified names such as
+           Tree-sitter-backed \`.ts\`/\`.tsx\`/\`.py\`/\`.go\`/\`.rs\`/\`.java\`/\`.rb\` anchors recognize
+           structural function, method, class, interface, enum, and type declarations. Methods and nested
+           declarations use lexical qualified names such as
            \`Class.method\`, \`outer.inner\`, or \`Outer.Inner.method\`; attached decorators belong to
            the declaration's range. Runtime-created/assigned callables, imported aliases, and generated
            names are outside this declaration extractor and therefore resolve as dead anchors.
@@ -546,8 +547,15 @@ behavior, decided per KIND (and, for a contract file, by its live CONTENT).
 ── THE FOUR KINDS (all fixed) ──
   spec data       .spec/ (incl .plugins/) + spexcode.json — ALWAYS tracked. Git is the database; there is
                   deliberately NO way to say "untrack the spec" in this schema.
-  machine facts   spexcode.local.json, the hook shims (.claude/settings.json, .codex/hooks.json), plugin
-                  bundles — NEVER tracked; always in the per-clone exclude.
+  (no delivery)   \`spex init --harness none\` ("harnesses": []) adopts the spec tree, the lint and the git
+                  hooks and writes NOTHING into any agent's config — the L0-only footprint.
+  machine facts   spexcode.local.json, the hook shims, plugin bundles — NEVER tracked; always in the
+                  per-clone exclude. A shim is a machine fact only while it is WHOLLY OURS: where the harness
+                  discovers its hooks in a file that is ALSO your project config (.claude/settings.json,
+                  .codex/hooks.json, .zcode/settings.json), SpexCode co-owns only its own hook entries —
+                  your permissions/env/statusLine/hooks are merged around, never replaced, and uninstall
+                  takes back exactly those entries. Such a file stays visible to git (hiding yours would be
+                  data-loss shaped), so keep our absolute toolchain paths out of your commits.
   artifacts       the CLAUDE.md/AGENTS.md contract blocks + materialized skills/agents — derived, NEVER
                   tracked; hidden via .git/info/exclude. The host's tracked .gitignore is never touched.
   run residue     .worktrees/, the global store (~/.spexcode), .git/spexcode evidence — never tracked;
@@ -621,15 +629,20 @@ Use the session's file list when an artifact belongs in the human's hands:
   spex session files retract <path>  withdraw one path
 
 Posting resolves a relative path from your current directory and records its absolute path beside the global
-session record. It copies, moves, stages, and uploads NOTHING. The path is live: editing the file after
+session record only after confirming it is a readable regular file. It copies, moves, stages, and uploads NOTHING. The path is live: editing the file after
 posting changes what the human downloads. The reference is host-local; opening the session elsewhere cannot
 make its path point at another machine's file.
 
+Put raw run artifacts in a persistent directory OUTSIDE the product repository by default. A worktree artifact
+makes merge readiness report a dirty tree and pressures generated evidence into the product commit. Before review,
+run \`spex session files ls\`: a target that disappeared or became unreadable is printed as \`INVALID\` and must be
+recreated or retracted; a valid path prints normally.
+
 The session page's top-right files icon is grey while the list is empty. Once live, it opens the posted list;
 choosing a path previews its current text or raster-image bytes in a pop-out, while the adjacent download tool
 downloads it through the backend at that moment. Previews are limited to 2 MiB, text and PNG/JPEG/GIF/WebP;
-other types and larger files say to download instead. A missing, moved, or unreadable target stays listed but
-reports that it no longer exists. The backend refuses a preview or download for any path not on that session's
+other types and larger files say to download instead. A missing, moved, or unreadable target stays listed and is
+marked invalid by the CLI; preview/download reports that it no longer exists. The backend refuses a preview or download for any path not on that session's
 list.
 
 This is the reverse of a dashboard attachment: [[file-attach]] sends human bytes to an agent. Files publishes

package/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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;