@spexcode/spec-cli 0.6.7 → 0.7.0-next.0

package/dist/graphStream.d.ts

@@ -58,6 +58,8 @@ export type PendingGraphChanges = {
 export declare const addPendingGraphChange: (pending: PendingGraphChanges, scope: Scope) => PendingGraphChanges;
 export declare function isSessionCreateCandidateRegistryEvent(relativePath: string, candidatePaths: Iterable<string>): boolean;
 export declare const notifyBoardChanged: (scope?: Scope) => void;
+export declare const sessionDatabaseWatchIgnore: (databasePath: string) => ((relativePath: string) => boolean);
+export declare function watchSessionDatabase(databasePath: string, onInput: () => void, onFailure: (error: Error) => void, watchFactory?: WatchFactory): TreeWatcherRegistry;
 type RegistryGroup = {
     root: string;
     close(): void;

package/dist/graphStream.js

@@ -1,7 +1,8 @@
 import { streamSSE } from 'hono/streaming';
 import { watch, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join, dirname, relative, resolve, basename } from 'node:path';
-import { sessionsRoot, gitCommonDir, repoRoot, sessionBranchIndex, mainBranch } from '@spexcode/spec-core';
+import { sessionsRoot, gitCommonDir, repoRoot, sessionBranchIndex, mainBranch, isTrashWorktreePath } from '@spexcode/spec-core';
+import { resolveDatabasePath } from '@spexcode/session-selflaunch';
 import { hotSignature, warmSignature, listSessions, pendingSessionCreateWorktreePaths } from './sessions.js';
 import { getBoard, getBoardForSessionRefresh, invalidateBoard, patrolBoard } from './graphCache.js';
 import { unitize, tagOf, diffUnits } from '@spexcode/spec-core';
@@ -439,7 +440,7 @@ function fireChanged(scope = 'full', evalTarget) {
 }
 // ---- event source 0: an EXPLICIT server-side nudge ----
 // for a server-side mutation that must show instantly regardless of watcher health: /rename writes the
-// session's global record (`session.json` — [[session-rename]]), which lives INSIDE the watched store, so
+// session's global runtime envelope (`runtime.json` — [[session-rename]]), which lives INSIDE the watched store, so
 // source 1 normally sees the write too. The explicit route call stays because that fs watch is best-effort
 // (it can fail to attach), and the nudge makes the sub-second rename guarantee deterministic. Same
 // debounced funnel as every other source; defaults to 'full' but the rename route passes 'sessions'.
@@ -535,6 +536,80 @@ function ensureWatcher(root) {
     }
     noteSourceHealthy('store');
 }
+// ---- event source 1b: the canonical session database (lifecycle commits from ANY process) → 'sessions' ----
+// Since the JSON cutover ([[production-cutin]]) a lifecycle transition is a SQLite commit, not a write inside the
+// store above: that watch still sees the runtime envelope and the prompt, but the state a HOOK authors — mark-active
+// on every prompt and tool call, the stop-gate's declarations, idle — is committed by the hook's OWN process through
+// `spex internal session-state`. The backend's in-process commit observer (index.ts) bridges only its own commits,
+// so without this leaf a hook-authored flip reached the board only when some unrelated signal happened to re-splice:
+// a message sent from the dashboard left the row idle for minutes (measured on the dogfood board: 150s of nothing
+// but pings after the commit). One NON-recursive watch on the database's directory, delivering only the database's
+// own names — the file and its `-journal` (journal_mode=delete writes both on every commit); every other file in
+// that directory is filtered out at delivery. Attach failure is held and repaired like every other source, and
+// [[graph-cache]] folds the same file into its session revision so the patrol covers a held or disabled leaf.
+let sessionDatabaseWatcher = null;
+let activeDatabasePath = null;
+const SESSION_DB_SOURCE = 'session-db';
+export const sessionDatabaseWatchIgnore = (databasePath) => {
+    const name = basename(databasePath);
+    return (relativePath) => relativePath !== name && !relativePath.startsWith(`${name}-`);
+};
+export function watchSessionDatabase(databasePath, onInput, onFailure, watchFactory) {
+    return new TreeWatcherRegistry({
+        root: dirname(databasePath),
+        source: SESSION_DB_SOURCE,
+        scope: 'sessions',
+        recursive: false,
+        ignore: sessionDatabaseWatchIgnore(databasePath),
+        watchFactory,
+        onInput: () => onInput(),
+        onFailure,
+    });
+}
+function closeSessionDatabaseWatcher() {
+    sessionDatabaseWatcher?.close();
+    sessionDatabaseWatcher = null;
+    activeDatabasePath = null;
+}
+function ensureSessionDatabaseWatcher() {
+    if (isDisabled(SESSION_DB_SOURCE)) {
+        closeSessionDatabaseWatcher();
+        return;
+    }
+    let databasePath;
+    try {
+        databasePath = resolveDatabasePath();
+    }
+    catch (error) {
+        noteSourceFailure(SESSION_DB_SOURCE, error);
+        return;
+    }
+    if (sessionDatabaseWatcher && activeDatabasePath === databasePath)
+        return;
+    closeSessionDatabaseWatcher();
+    activeDatabasePath = databasePath;
+    if (!mayAttach(SESSION_DB_SOURCE))
+        return;
+    try {
+        mkdirSync(dirname(databasePath), { recursive: true });
+    }
+    catch (error) {
+        console.error(`spec-cli: graph watcher '${SESSION_DB_SOURCE}' could not create ${dirname(databasePath)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const registry = watchSessionDatabase(databasePath, () => fireChanged('sessions'), (error) => {
+        if (sessionDatabaseWatcher === registry)
+            sessionDatabaseWatcher = null;
+        noteSourceFailure(SESSION_DB_SOURCE, error);
+        fireChanged('sessions');
+    });
+    sessionDatabaseWatcher = registry;
+    if (!registry.refresh()) {
+        if (sessionDatabaseWatcher === registry)
+            sessionDatabaseWatcher = null;
+        return;
+    }
+    noteSourceHealthy(SESSION_DB_SOURCE);
+}
 let refsWatchers = null;
 const REFS_OBSERVER = 'graph:refs';
 // @@@ the moved ref NAMES its scope - the watcher has always known which ref moved and threw it away, so
@@ -657,13 +732,14 @@ const worktreeSource = (name) => `worktree:${name}`;
 const PROJECT_ROOT_SOURCE = 'project-root';
 let projectRootWatcher = null;
 const ignoredWorktreePath = (file) => file.split(/[\\/]/).some((segment) => segment === '.git' || segment === 'node_modules');
+const ignoredGeneratedBuildPath = (file) => file.split(/[\\/]/).some((segment) => segment === 'dist' || segment.startsWith('.dist-next-') || segment.startsWith('.dist-previous-'));
 // @@@ linked worktrees are not graph input for THIS backend - the board's node statuses derive from the
 // served checkout's own HEAD, so a file under `.worktrees/<node>` belongs to a different branch's tree and
 // cannot move any status here until it lands and this HEAD advances. Watching them registers one inotify
 // watch per directory (Linux takes the exact-directory transport) and buys nothing: measured on this repo,
 // 20,124 of 20,473 watched directories were linked worktrees against 843 in the served tree.
 // The per-worktree registries above keep their own roots; only the project-root sweep skips them.
-export const ignoredProjectRootPath = (file) => ignoredWorktreePath(file) || file.split(/[\\/]/).some((segment) => segment === '.worktrees');
+export const ignoredProjectRootPath = (file) => ignoredWorktreePath(file) || ignoredGeneratedBuildPath(file) || file.split(/[\\/]/).some((segment) => segment === '.worktrees');
 // The directory whose tree this backend serves is graph input even before it has a `.spec` tree or any live
 // session worktree. Keeping it in the same root registry as linked worktrees means a first `spex init` or
 // agent-created spec invalidates a warmed empty board instead of leaving a confidently stale cache until a
@@ -807,6 +883,8 @@ async function reconcileWorktreePass(forcedSessions, era, common) {
         catch {
             continue;
         }
+        if (isTrashWorktreePath(wtPath))
+            continue;
         const normalizedPath = resolve(wtPath);
         if (!wantedPaths.has(normalizedPath)) {
             if (dropWorktreeWatcher(e.name))
@@ -1033,6 +1111,7 @@ export async function ensureBoardFileWatchers(forceSessionId) {
     activeStoreRoot = storeRoot;
     activeCommonRoot = commonRoot;
     ensureWatcher(storeRoot);
+    ensureSessionDatabaseWatcher();
     ensureRefsWatcher(commonRoot);
     await ensureWorktreeRegistry(forceSessionId);
     ensureProjectRootWatcher();
@@ -1055,6 +1134,7 @@ export function closeBoardFileWatchers() {
     worktreeReconcileFlight = null;
     storeWatcher?.close();
     storeWatcher = null;
+    closeSessionDatabaseWatcher();
     refsWatchers?.close();
     refsWatchers = null;
     registryWatcher?.close();

package/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.
@@ -306,7 +307,7 @@ PORTABILITY, and picking the right one is the whole discipline:
                         below); a targeted env override (SPEXCODE_CODEX_SERVER_CMD, …) still wins at its read site.
 
 Rule of thumb — is the value TRUE FOR THE PROJECT or TRUE FOR THIS MACHINE? A branch name, a dashboard
-icon or launcher-visibility policy, upload policy, lint policy, resource and doctor health budgets, and a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
+icon, upload policy, lint policy, resource and doctor health budgets, and a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
 PATH of a launcher wrapper or a TLS cert path are machine facts → gitignored spexcode.local.json.
 Both files are optional; omit any field to take its default, except \`sessions.defaultLauncher\` when using
 \`spex session new\` or the dashboard without an explicit launcher choice.
@@ -338,13 +339,8 @@ Example — a repo whose trunk is \`staging\`, not \`main\`:
   dashboard.apiUrl  the per-project backend the dashboard proxies to (read frontend-side). For a SHARED
                     install prefer the API_URL env var; apiUrl here is the default only when the dashboard
                     lives inside the project.
-  dashboard.showHeadlessLaunchers
-                    include launchers whose harness declares itself headless in the dashboard New Session
-                    picker. Default: false. This changes dashboard visibility only; explicit CLI
-                    --launcher selection can still use every configured launcher.
 Example:
-  { "dashboard": { "title": "MyApp specs", "icon": "mdi:rocket-launch",
-                   "showHeadlessLaunchers": false } }
+  { "dashboard": { "title": "MyApp specs", "icon": "mdi:rocket-launch" } }
 
 ── HOST GATEWAY ($SPEXCODE_HOME/config.json — per-user host identity, never a project file) ──
   gateway.icon      the global /projects icon, using the same preset ids above. Default: "gateway".
@@ -402,14 +398,17 @@ A named launcher profile fixes BOTH a session's harness AND its exact launch com
 by name with --launcher/the dashboard dropdown, and the chosen name is persisted on the record so a resume
 reuses the same auth. There are NO magic built-ins: \`spex init\` SEEDS an ordinary named launcher for each
 harness the adopter SELECTED (--harness), from the template pool
-  "claude"   → { "harness": "claude",   "cmd": "claude" }
   "claude-headless" → { "harness": "claude-headless", "cmd": "claude" }
-  "codex"    → { "harness": "codex",    "cmd": "codex" }
+  "claude"   → { "harness": "claude",   "cmd": "claude" }
   "codex-headless" → { "harness": "codex-headless", "cmd": "codex --yolo" }
-  "opencode" → { "harness": "opencode", "cmd": "opencode" }
+  "codex"    → { "harness": "codex",    "cmd": "codex" }
   "opencode-headless" → { "harness": "opencode-headless", "cmd": "opencode --auto" }
-  "pi"       → { "harness": "pi",       "cmd": "pi" }
+  "opencode" → { "harness": "opencode", "cmd": "opencode" }
   "pi-headless" → { "harness": "pi-headless", "cmd": "pi" }
+  "pi"       → { "harness": "pi",       "cmd": "pi" }
+Each harness's headless (terminal-free) form leads its interactive one, and \`spex init\` makes the FIRST
+planted launcher the default — so an adoption that selects both forms of a harness creates its sessions
+headless by default, read through the dashboard's Conversation; the interactive TUI launcher is the opt-in.
 The interactive profiles preserve each harness's normal permission model. \`opencode-headless\` and
 \`codex-headless\` are deliberate seed exceptions: their terminal-free runs require \`opencode --auto\` and
 \`codex --yolo\`; interactive profiles stay plain. Other automatic-permission commands are NEVER clean-init
@@ -546,8 +545,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 +627,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/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,5 @@
 import { type SlashCommand } from './slash-commands.js';
-import { type ExecutionTrace, type ExecutionTurn } from './execution-trace.js';
+import { type TranscriptReader } from '@spexcode/transcript';
 import { type HarnessId } from '@spexcode/spec-core';
 export type { HarnessId } from '@spexcode/spec-core';
 export type HarnessLivenessRecord = {
@@ -23,6 +23,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 +59,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;
@@ -121,7 +122,7 @@ export interface Harness {
     readonly events: readonly string[];
     readonly ownsRendezvous: boolean;
     readonly paneTitleIsSelfSummary: boolean;
-    executionTrace(threadId: string, turn: ExecutionTurn | null): ExecutionTrace | null;
+    readonly transcript: TranscriptReader;
     launchCmd(id: string, runtimeDir?: string, cmd?: string): string;
     baseCmd(cmd?: string): string;
     oneShotTurn?(prompt: string, cmd?: string): {
@@ -139,8 +140,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,9 +229,12 @@ 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>;
+export declare function interruptViaRendezvous(id: string, harness: string, opts?: {
+    settle?: boolean;
+}): Promise<DispatchResult>;
 type JsonRpc = {
     id?: number;
     method?: string;
@@ -242,6 +248,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,7 +260,14 @@ 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 function codexReopenThread(sock: string, threadId: string, budgetMs?: number): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;
 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;
@@ -282,7 +296,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 +315,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;
@@ -331,7 +350,6 @@ export type LauncherDefault = {
     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;