tickmarkr 2.3.0 → 2.4.0

package/dist/compile/index.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { parse } from "yaml";
 import { validateGraph } from "../graph/schema.js";
 import { taskUnitContractErrors } from "./collateral.js";
 import { blocksCompile, ownershipFindings, renderOwnershipFinding } from "./ownership.js";
@@ -33,8 +34,40 @@ function detect(src) {
 // tasks are too large to converge. A violation is a compile error, never a warning — the failures it
 // prevents (silently dropped commits, a 28-dispatch task) are invisible until they have already cost
 // hours, which is exactly the class of thing that has to fail at authoring time.
-function enforceTaskUnitContract(g, src) {
-    const errors = taskUnitContractErrors(g.tasks);
+function repoOverlayMode(repoRoot) {
+    if (!repoRoot)
+        return undefined;
+    try {
+        const cfg = parse(readFileSync(join(repoRoot, ".tickmarkr", "config.yaml"), "utf8"));
+        return typeof cfg?.routing?.mode === "string" ? cfg.routing.mode : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasModeOverride(src) {
+    try {
+        for (const line of readFileSync(src, "utf8").split("\n")) {
+            if (/^##\s+T\d+:/i.test(line))
+                return false;
+            if (/^mode-override:\s*true\s*(?:#.*)?$/.test(line))
+                return true;
+        }
+    }
+    catch { /* unreadable specs fail elsewhere */ }
+    return false;
+}
+function enforceModeOverlay(graph, src, repoRoot) {
+    if (graph.spec.source !== "native" || graph.mode === undefined)
+        return;
+    const overlayMode = repoOverlayMode(repoRoot);
+    if (overlayMode === undefined || overlayMode === graph.mode || hasModeOverride(src))
+        return;
+    throw new CompileError(`${src} front-matter mode ${graph.mode} disagrees with repository routing.mode ${overlayMode}; `
+        + `write mode-override: true beside the mode line to make the override explicit.`);
+}
+function enforceTaskUnitContract(g, src, repoRoot) {
+    const errors = taskUnitContractErrors(g.tasks, repoRoot);
     if (errors.length > 0) {
         throw new CompileError(`${src} violates the task unit contract (${errors.length} error${errors.length > 1 ? "s" : ""}):\n`
             + errors.map((e) => `  - ${e}`).join("\n"));
@@ -52,7 +85,8 @@ export function finalizePlan(plan, src, repoRoot) {
             ...(plan.base !== undefined ? { base: plan.base } : {}),
         },
         tasks: plan.tasks,
-    }), src);
+    }), src, repoRoot);
+    enforceModeOverlay(graph, src, repoRoot);
     // overseer-217 removal condition, now paid: on this milestone's authored graph the conventional
     // name map emitted 21 raw unowned-test findings; review found 1 real and 20 false, while intersecting
     // with a direct import or command-entry spawn retained the real one and left 0 false positives. That
@@ -73,11 +107,11 @@ export function finalizePlan(plan, src, repoRoot) {
     }
     return graph;
 }
-function compilePlan(src, type, root) {
+function compilePlan(src, type, root, options = {}) {
     const kind = type ?? detect(src);
     const graph = kind === "speckit" ? compileSpecKit(src)
         : kind === "gsd" ? compileGsd(src, root)
-            : kind === "native" ? compileNative(src)
+            : kind === "native" ? compileNative(src, { strict: options.strict })
                 : kind === "prd" ? compilePrd(src)
                     : null;
     if (!graph) {
@@ -93,6 +127,6 @@ function compilePlan(src, type, root) {
         tasks: graph.tasks,
     };
 }
-export function compileSource(src, type, root, beforeFinalize = (plan) => plan) {
-    return finalizePlan(beforeFinalize(compilePlan(src, type, root)), src, root);
+export function compileSource(src, type, root, beforeFinalize = (plan) => plan, options = {}) {
+    return finalizePlan(beforeFinalize(compilePlan(src, type, root, options)), src, root);
 }

package/dist/compile/native.d.ts

@@ -17,7 +17,7 @@ export declare const COLLECTABLE_TESTS = "tests/**/*.test.ts";
 export declare const LEGACY_PREFIX: string;
 export declare const TICKMARKR_NATIVE_MARKER: RegExp;
 export declare const NATIVE_MARKER: RegExp;
-export declare const AUTHORING_LINT_CODES: readonly ["criterion-scope", "dependency-closure", "dependency-coupling", "proxy-metric", "external-referent", "closed-enumeration", "one-behavior", "concern-bundle", "seam-exists"];
+export declare const AUTHORING_LINT_CODES: readonly ["criterion-scope", "dependency-closure", "dependency-coupling", "proxy-metric", "external-referent", "closed-enumeration", "one-behavior", "concern-bundle", "seam-exists", "fence-symbol-absent"];
 export type AuthoringLintCode = (typeof AUTHORING_LINT_CODES)[number];
 export interface AuthoringLintFinding {
     code: AuthoringLintCode;
@@ -31,5 +31,7 @@ export interface AuthoringLintFinding {
  * compile boundary; the remaining checks are review findings, emitted by compileNative below.
  */
 export declare function authoringLintFindings(tasks: readonly Task[], file: string): AuthoringLintFinding[];
-export declare function compileNative(file: string): RunGraph;
+export declare function compileNative(file: string, options?: {
+    strict?: boolean;
+}): RunGraph;
 export declare function specTemplate(): string;

package/dist/compile/native.js

@@ -83,6 +83,7 @@ export const AUTHORING_LINT_CODES = [
     "one-behavior",
     "concern-bundle",
     "seam-exists",
+    "fence-symbol-absent",
 ];
 // The authoring frame's observable oracle is the branch-tip test corpus, never the mutable index or
 // an author's untracked checkout. Load it once per repository: one bounded git read replaces a grep
@@ -217,6 +218,31 @@ function criterionScopeFinding(task, text, criterion, id, tests) {
         detail: `criterion names asserting file${missing.length === 1 ? "" : "s"} outside expanded files[] and context[]: ${missing.join(", ")} — ${remedy}`,
     };
 }
+// OBS-898: the fence lint's corpus is listed ONCE per compile by git (tracked plus untracked-not-ignored,
+// the same set a checkout walk sees minus the ignored trees) and filtered per task. The walk it replaces
+// descended every dot-directory (.tickmarkr/runs alone held 3 799 files here) once PER TASK, so a
+// 20-task spec compiled in seconds and the committed-spec corpus test timed out. Fail-open like
+// testsAtHead: no git answer means no corpus, and the lint stays quiet rather than wrong.
+function repoFileList(root) {
+    const ls = spawnSync("git", ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { encoding: "utf8", maxBuffer: 1 << 25 });
+    if (ls.status !== 0 || typeof ls.stdout !== "string")
+        return [];
+    return ls.stdout.split("\0").filter(Boolean).sort();
+}
+function repoFiles(files, entries) {
+    const scoped = filesGlob(entries.map((entry) => entry.replace(/^\.\//, "")));
+    return files.filter(scoped);
+}
+const PRESERVATION_RE = /\b(?:keeps?|preserves?|retains?|does\s+not\s+weaken|do\s+not\s+weaken|not\s+weaken)\b/i;
+const IDENTIFIER_SHAPED_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function fencedIdentifiers(text) {
+    if (!PRESERVATION_RE.test(text))
+        return [];
+    return [...new Set([...text.matchAll(/`([^`\n]{1,120})`/g)]
+            .map((match) => match[1].trim())
+            .filter((token) => IDENTIFIER_SHAPED_RE.test(token) && /[A-Z0-9_$]/.test(token)))]
+        .sort();
+}
 function exportedIdentifier(root, files, identifier) {
     const escaped = identifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const declaration = new RegExp(`\\bexport\\s+(?:(?:declare|default|async)\\s+)*(?:function|class|const|let|var|interface|type)\\s+${escaped}\\b|\\bexport\\s*\\{[^}]*\\b${escaped}\\b`);
@@ -240,14 +266,33 @@ export function authoringLintFindings(tasks, file) {
     const root = repositoryRoot(file);
     let indexedTests;
     const testIndex = () => indexedTests ??= root ? testsAtHead(root) : [];
+    let indexedFiles;
+    const fileIndex = () => indexedFiles ??= root ? repoFileList(root) : [];
     const findings = [];
     for (const task of tasks) {
         const criteria = criterionTexts(task);
+        const taskFiles = root && task.files.length ? repoFiles(fileIndex(), task.files) : [];
+        const taskTexts = new Map(taskFiles.map((path) => {
+            try {
+                return [path, readFileSync(join(root, path), "utf8")];
+            }
+            catch {
+                return [path, ""];
+            }
+        }));
         for (const [index, text] of criteria.entries()) {
             const needsTestIndex = /`[^`\n]{2,120}`|\b\d+\s*(?:\/|of)\s*\d+\b|\b[A-Za-z0-9_.-]+\.test\.ts\b/.test(text);
             const scope = criterionScopeFinding(task, text, index + 1, id, needsTestIndex ? testIndex() : []);
             if (scope)
                 findings.push(scope);
+            for (const symbol of fencedIdentifiers(text)) {
+                if (!taskTexts.size || [...taskTexts.values()].some((body) => body.includes(symbol)))
+                    continue;
+                findings.push({
+                    code: "fence-symbol-absent", fixtureId: id, taskId: task.id, criterion: index + 1,
+                    detail: `preservation fence cites \`${symbol}\` but that symbol has zero hits in this task's files[] (${taskFiles.join(", ")}) — OBS-604`,
+                });
+            }
             if (/line[- ]count|physical line|not greater than (?:the|\d)|no larger than|at most \d+ (?:lines|bytes)/i.test(text)) {
                 findings.push({ code: "proxy-metric", fixtureId: id, taskId: task.id, criterion: index + 1, detail: "criterion uses a proxy size metric; state the structural intent instead" });
             }
@@ -308,7 +353,7 @@ function renderAuthoringFinding(finding) {
     const criterion = finding.criterion === undefined ? "" : ` criterion ${finding.criterion}`;
     return `tickmarkr: authoring-lint[${finding.code}] fixture ${finding.fixtureId} task ${finding.taskId}${criterion}: ${finding.detail}`;
 }
-export function compileNative(file) {
+export function compileNative(file, options = {}) {
     if (!existsSync(file))
         throw new CompileError(`no such native spec file: ${file}`);
     const content = readFileSync(file, "utf8");
@@ -638,13 +683,17 @@ export function compileNative(file) {
         tasks,
     });
     const authoringFindings = authoringLintFindings(result.tasks, file);
-    for (const finding of authoringFindings.filter(({ code }) => code !== "criterion-scope")) {
+    const blockingCodes = new Set(["criterion-scope", "fence-symbol-absent"]);
+    const blockingFindings = authoringFindings.filter((finding) => options.strict || blockingCodes.has(finding.code));
+    for (const finding of authoringFindings.filter((finding) => !blockingFindings.includes(finding))) {
         console.warn(renderAuthoringFinding(finding));
     }
-    const scopeErrors = authoringFindings.filter(({ code }) => code === "criterion-scope");
-    if (scopeErrors.length > 0) {
-        throw new CompileError(`${file} violates the criterion-scope authoring lint (${scopeErrors.length} error${scopeErrors.length === 1 ? "" : "s"}):\n`
-            + scopeErrors.map((finding) => `  - ${renderAuthoringFinding(finding)}`).join("\n"));
+    if (blockingFindings.length > 0) {
+        const strict = options.strict ? " under --strict" : "";
+        const onlyCriterionScope = blockingFindings.every(({ code }) => code === "criterion-scope");
+        const label = onlyCriterionScope && !options.strict ? "the criterion-scope authoring lint" : `authoring lints${strict}`;
+        throw new CompileError(`${file} violates ${label} (${blockingFindings.length} error${blockingFindings.length === 1 ? "" : "s"}):\n`
+            + blockingFindings.map((finding) => `  - ${renderAuthoringFinding(finding)}`).join("\n"));
     }
     // v1.19 read-old/write-new: a plain-string acceptance item compiles as a judge oracle. This is the
     // one-time nudge toward typed oracles (command/test/judge); PRD/Spec Kit/GSD stay silent (untouched).

package/dist/compile/ownership.js

@@ -22,14 +22,31 @@ function testSources(repoRoot) {
         return [];
     }
 }
-function namedSources(test, tasks) {
+function sourceFiles(repoRoot) {
+    const root = join(repoRoot, "src");
+    try {
+        return readdirSync(root, { recursive: true, encoding: "utf8" })
+            .filter((path) => /\.(?:[cm]?[jt]sx?)$/.test(path))
+            .map((path) => `src/${normalize(path)}`)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// OBS-898: `allSources` is indexed once per ownership pass by the caller, never per test source.
+function namedSources(test, tasks, allSources) {
     const stem = basename(test).replace(/\.test\.ts$/, "");
     const matches = new Map();
     for (const task of tasks) {
-        for (const entry of task.files.map(normalize).filter((path) => path.startsWith("src/") && !/[*?{[]/.test(path))) {
-            const source = basename(entry, extname(entry));
-            if (stem === source || stem.startsWith(`${source}-`)) {
-                matches.set(`${task.id}:${entry}`, { taskId: task.id, source: entry });
+        for (const entry of task.files.map(normalize).filter((path) => path.startsWith("src/"))) {
+            const fromGlob = /[*?{[]/.test(entry);
+            const entries = fromGlob ? allSources.filter(filesGlob(entry)) : [entry];
+            for (const sourcePath of entries) {
+                const source = basename(sourcePath, extname(sourcePath));
+                if (stem === source || stem.startsWith(`${source}-`)) {
+                    matches.set(`${task.id}:${sourcePath}`, { taskId: task.id, source: sourcePath, fromGlob });
+                }
             }
         }
     }
@@ -148,19 +165,27 @@ export function ownershipFindings(tasks, repoRoot) {
             predictedBy.set(hit, ids);
         }
     }
+    const globOwnedTests = new Map();
+    const allSources = sourceFiles(repoRoot);
     for (const source of sources) {
         const ids = predictedBy.get(source.path) ?? new Set();
-        for (const { taskId } of namedSources(source.path, tasks))
-            ids.add(taskId);
+        for (const named of namedSources(source.path, tasks, allSources)) {
+            ids.add(named.taskId);
+            if (named.fromGlob) {
+                const owners = globOwnedTests.get(source.path) ?? new Set();
+                owners.add(named.taskId);
+                globOwnedTests.set(source.path, owners);
+            }
+        }
         if (ids.size > 0)
             predictedBy.set(source.path, ids);
     }
     const findings = [];
     for (const [test, taskIds] of predictedBy) {
-        if (owners(test).length === 0) {
+        if (owners(test).length === 0 && !(globOwnedTests.get(test)?.size)) {
             const ids = [...taskIds].sort();
             const source = sourceByPath.get(test);
-            const evidence = corroboration(source, namedSources(test, tasks));
+            const evidence = corroboration(source, namedSources(test, tasks, allSources));
             findings.push({
                 code: "unowned-test",
                 test,

package/dist/config/config.d.ts

@@ -266,6 +266,7 @@ export declare const TickmarkrConfigSchema: z.ZodObject<{
     }, z.core.$strip>;
     review: z.ZodObject<{
         complexityThreshold: z.ZodNumber;
+        timeoutMs: z.ZodNumber;
         required: z.ZodBoolean;
         prefer: z.ZodOptional<z.ZodArray<z.ZodString>>;
         policy: z.ZodOptional<z.ZodEnum<{

package/dist/config/config.js

@@ -355,6 +355,7 @@ export const TickmarkrConfigSchema = z.object({
         // because routing hints and the setup cockpit still read it as a complexity landmark; NOTHING in
         // src/gates/review.ts reads it any more, and a value here can no longer disable a review.
         complexityThreshold: z.number(),
+        timeoutMs: z.number().int().positive(),
         required: z.boolean(),
         prefer: z.array(z.string()).optional(),
         // R3: the operator's participation floor. "full" forces a cross-vendor review on every task;
@@ -484,8 +485,15 @@ export const DEFAULT_CONFIG = {
                 // 2026-07-16 (cursor-agent 2026.07.09); gives cursor a cheap-tier channel so low-complexity shapes
                 // stop burning its mid. Operator-approved 2026-07-16.
                 "composer-2.5-fast": "cheap",
+                // OBS-871: LiveBench 2026_06_25, fetched 2026-09-03; released 2026-09-01.
+                "claude-fable-5-1": "frontier",
+                // OBS-871: LiveBench 2026_06_25, fetched 2026-09-03; released 2026-09-02.
+                "gemini-3.8-flash": "mid",
+            },
+            windows: {
+                "composer-2.5": 200_000, "composer-2.5-fast": 200_000,
+                "claude-fable-5-1": 1_000_000, "gemini-3.8-flash": 1_000_000,
             },
-            windows: { "composer-2.5": 200_000, "composer-2.5-fast": 200_000 },
         },
         // GLM-5.2 → mid per benchmark policy (2026-07): SWE-bench Pro 62.1 (> GPT-5.5 58.6), FrontierSWE 74.4 ≈ Opus 4.8;
         // no independent Terminal-Bench score → conservative mid, overlays may raise.
@@ -507,8 +515,46 @@ export const DEFAULT_CONFIG = {
         // cross-harness) is pre-existing, FLEET-05 owns it.
         pi: {
             vendor: "zhipu", channel: "sub",
-            models: { "zai/glm-5.2": "mid" },
-            windows: { "zai/glm-5.2": 1_000_000 },
+            models: {
+                "zai/glm-5.2": "mid",
+                // OBS-871: LiveBench 2026_06_25, fetched 2026-09-03; GLM-5.3 released 2026-08-18.
+                "zai/glm-5.3": "frontier",
+                // OBS-871: same LiveBench source and 2026-09-03 fetch; speed variant remains mid.
+                "zai/glm-5.3-flash": "mid",
+            },
+            windows: { "zai/glm-5.2": 1_000_000, "zai/glm-5.3": 1_000_000, "zai/glm-5.3-flash": 200_000 },
+        },
+        // OBS-871: gateway ids and bands from LiveBench 2026_06_25, fetched 2026-09-03.
+        omp: {
+            vendor: "mixed", channel: "sub",
+            models: {
+                "google/gemini-3.8-flash": "mid",
+                "zai/glm-5.3": "frontier",
+                "alibaba/qwen3.8-max": "frontier",
+            },
+            modelOverrides: {
+                "google/gemini-3.8-flash": { vendor: "google" },
+                "zai/glm-5.3": { vendor: "zhipu" },
+                "alibaba/qwen3.8-max": { vendor: "alibaba" },
+            },
+            windows: {
+                "google/gemini-3.8-flash": 1_000_000,
+                "zai/glm-5.3": 1_000_000,
+                "alibaba/qwen3.8-max": 1_000_000,
+            },
+        },
+        // OBS-871: Qwen 3.8 Max scored 64.6 in LiveBench 2026_06_25, fetched 2026-09-03.
+        qwen: {
+            vendor: "alibaba", channel: "sub",
+            models: { "qwen3.8-max": "frontier" },
+            windows: { "qwen3.8-max": 1_000_000 },
+        },
+        // OBS-871: prime-agent listed this prime-inference route on 2026-09-03; GLM-5.2 remains mid.
+        "prime-agent": {
+            vendor: "mixed", channel: "sub",
+            models: { "prime-inference/z-ai/glm-5.2": "mid" },
+            modelOverrides: { "prime-inference/z-ai/glm-5.2": { vendor: "zhipu" } },
+            windows: { "prime-inference/z-ai/glm-5.2": 1_000_000 },
         },
         // Native grok CLI (Phase 40). grok-4.5 → mid: same benchmark provenance as the retired cursor-agent
         // grok-4.5-xhigh seed above (AA 54, TB2.1 83.3%, SWE-b Pro 64.7% — researched 2026-07-10).
@@ -543,7 +589,7 @@ export const DEFAULT_CONFIG = {
     judge: { adapter: "claude-code", model: "fable" },
     // R3: no `policy` floor — the neutral floor leaves the compiler's per-task assignment standing, so
     // the path-keyed rule is reachable out of the box rather than raised to full by construction.
-    review: { complexityThreshold: 7, required: true, criticalPaths: [...DEFAULT_REVIEW_CRITICAL_PATHS] },
+    review: { complexityThreshold: 7, timeoutMs: 900_000, required: true, criticalPaths: [...DEFAULT_REVIEW_CRITICAL_PATHS] },
     consult: { adapter: "claude-code", model: "fable", stallMinutes: 15 },
     // v1.4: gate LLM calls (judge/review/consult) run headless by default; pane opts back into visible agents.
     // v1.2: workers are the real agent TUI in the pane; "print" restores the -p-rendered-in-pane path.
@@ -765,7 +811,7 @@ export function configTemplate(overlay) {
 #   test: npm test
 #   byShape:
 #     docs: { acceptance: false, review: false }  # baseline, evidence, and scope are mandatory
-# review: { complexityThreshold: 7, required: true, prefer: [codex:gpt-5.6-sol, kimi] }
+# review: { complexityThreshold: 7, timeoutMs: 900000, required: true, prefer: [codex:gpt-5.6-sol, kimi] }
 #                         # prefer: ordered reviewer seat preference (adapter | adapter:model); ranks
 #                         # diversity-eligible channels only — never admits a same-vendor/same-model reviewer
 # consult: { adapter: claude-code, model: fable, stallMinutes: 15, prefer: [codex:gpt-5.6-sol, kimi:kimi-code/k3] }

package/dist/drivers/herdr.d.ts

@@ -56,6 +56,7 @@ export declare class HerdrDriver implements ExecutorDriver {
     private journal?;
     id: string;
     interactive: boolean;
+    readSource: string;
     private groups;
     private groupSerial;
     private deliverySerial;

package/dist/drivers/herdr.js

@@ -142,6 +142,7 @@ export class HerdrDriver {
     journal;
     id = "herdr";
     interactive = true;
+    readSource = "recent-unwrapped";
     groups = new Map();
     // grouped slot()/close() mutate shared group state across awaits — serialize them so two
     // concurrent first members can never both create the group tab (mergeSerial idiom, daemon.ts)
@@ -1339,7 +1340,16 @@ export class HerdrDriver {
                 if (alive.has(tab))
                     continue;
                 const closed = await this.herdr(`tab close ${shq(tab)}`);
-                if (closed.code !== 0) {
+                if (closed.code !== 0 && /tab_not_found/i.test(`${closed.stderr}\n${closed.stdout}`)) {
+                    this.journalReconcile(journalHandle, "tab-reconcile-close-skipped", undefined, {
+                        tabId: tab,
+                        runId,
+                        sweeperRunId: runId,
+                        exitCode: 0,
+                        reason: "tab_not_found",
+                    });
+                }
+                else if (closed.code !== 0) {
                     this.journalReconcile(journalHandle, "tab-reconcile-close-failed", undefined, {
                         tabId: tab,
                         runId,

package/dist/drivers/orca.d.ts

@@ -2,7 +2,7 @@ import { type ShResult } from "../run/git.js";
 import { type JournalEvent } from "../run/journal.js";
 import { type ExecutorDriver, type NotifyOpts, type Slot, type SlotOpts } from "./types.js";
 /** The response families the ONE shared envelope parser serves. There is no second JSON seam. */
-export declare const ORCA_RESPONSE_FAMILIES: readonly ["status", "create", "list", "read", "send", "wait", "show", "close", "worktree-current", "hooks-status"];
+export declare const ORCA_RESPONSE_FAMILIES: readonly ["status", "create", "list", "read", "send", "wait", "show", "close", "worktree-current", "worktree-set", "hooks-status"];
 export type OrcaFamily = (typeof ORCA_RESPONSE_FAMILIES)[number];
 export declare const ORCA_FIXTURE_VERSION = "1.4.195";
 export declare const ORCA_CLI_COMMAND_ENV = "ORCA_CLI_COMMAND";
@@ -118,6 +118,8 @@ export declare class OrcaDriver implements ExecutorDriver {
     private journalRoots;
     private narrate?;
     private hookCoverage?;
+    private taskWorktrees;
+    private pendingProjects;
     constructor(opts?: OrcaDriverOpts);
     private call;
     /** The live runtime's identity, or an explicit failure. A missing or unreachable runtime is a
@@ -131,7 +133,13 @@ export declare class OrcaDriver implements ExecutorDriver {
     private state;
     private latched;
     private assertAvailable;
+    describe(slot: Slot): {
+        surface?: string;
+        hostPlatform?: string;
+    };
     run(slot: Slot, cmd: string): Promise<void>;
+    private sendText;
+    private sendReceipt;
     private create;
     /**
      * A freshly-created git checkout does not become a valid Orca selector atomically. Ask
@@ -188,6 +196,11 @@ export declare class OrcaDriver implements ExecutorDriver {
      *  only after this method validates all four fields. Any malformed/refused wait remains explicit. */
     private waitCondition;
     waitAgentStatus(slot: Slot, status: string, timeoutMs: number): Promise<boolean>;
+    sendKey(slot: Slot, key: string): Promise<void>;
+    nudge(slot: Slot, message: string): Promise<boolean>;
+    narrator(cwd: string, command: string, runId?: string): Promise<Slot>;
+    project(taskId: string, state: "in-progress" | "in-review" | "completed"): Promise<void>;
+    private setWorkspaceStatus;
     notify(msg: string, opts?: NotifyOpts): Promise<void>;
     narrateWith(narrate: (event: JournalEvent) => void): void;
     close(slot: Slot): Promise<void>;

package/dist/drivers/orca.js

@@ -34,7 +34,7 @@ import { formatOwnedName, panesToClose, parseOwnedName } from "./types.js";
 /** The response families the ONE shared envelope parser serves. There is no second JSON seam. */
 export const ORCA_RESPONSE_FAMILIES = [
     "status", "create", "list", "read", "send", "wait", "show", "close",
-    "worktree-current", "hooks-status",
+    "worktree-current", "worktree-set", "hooks-status",
 ];
 export const ORCA_FIXTURE_VERSION = "1.4.195";
 export const ORCA_CLI_COMMAND_ENV = "ORCA_CLI_COMMAND";
@@ -57,6 +57,7 @@ const POLL_MS = 200;
 export const WORKTREE_ADOPTION_TIMEOUT_MS = 60_000;
 const WORKTREE_ADOPTION_POLL_MS = 1_000;
 const WORKTREE_ADOPTION_JOURNAL_MS = 2_000;
+const NUDGE_ECHO_TIMEOUT_MS = 2_000;
 const SYSTEM_TIME = {
     now: () => Date.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -262,6 +263,8 @@ export class OrcaDriver {
     journalRoots = new Map();
     narrate;
     hookCoverage;
+    taskWorktrees = new Map();
+    pendingProjects = new Map();
     constructor(opts = {}) {
         this.bin = opts.bin ?? resolveOrcaCliBinary(process.cwd(), { env: opts.env, platform: opts.platform }) ?? "orca";
         // Config values flow into a shell here: every argv element is quoted, always.
@@ -358,6 +361,15 @@ export class OrcaDriver {
         // receipt, relist, reconcile — is against THIS value.
         const worktree = canonicalWorktreePath(cwd);
         this.slots.set(id, { title, cwd: worktree, agent: opts?.agent, buf: "", recoveries: 0, recovering: false });
+        const owned = parseOwnedName(title);
+        if (owned?.role === "worker") {
+            this.taskWorktrees.set(owned.taskId, worktree);
+            const pending = this.pendingProjects.get(owned.taskId);
+            if (pending) {
+                await this.setWorkspaceStatus(worktree, pending);
+                this.pendingProjects.delete(owned.taskId);
+            }
+        }
         return { id, name: title, cwd: worktree, group: opts?.group };
     }
     /** Where to invoke the CLI for this slot's calls (see OrcaSlotState.dir). */
@@ -378,6 +390,17 @@ export class OrcaDriver {
         if (st.unavailable)
             throw new OrcaUnavailableError(family, st.unavailable, "");
     }
+    describe(slot) {
+        const st = this.state(slot);
+        // The daemon asks only after run(), but callers probing a lazy slot must see absence rather
+        // than an invented placement. The interface's object spread accepts this runtime absence.
+        if (!st.handle)
+            return undefined;
+        return {
+            ...(st.surface === undefined ? {} : { surface: st.surface }),
+            ...(st.hostPlatform === undefined ? {} : { hostPlatform: st.hostPlatform }),
+        };
+    }
     async run(slot, cmd) {
         const st = this.state(slot);
         if (!st.handle) {
@@ -387,22 +410,28 @@ export class OrcaDriver {
         this.assertAvailable("send", st);
         // Later deliveries go into the terminal this slot already owns — never a second create.
         // terminalOp proves the runtime binding before the handle goes on the wire.
-        const env = await this.terminalOp("send", st, (h) => this.call("send", ["terminal", "send", "--terminal", h, "--text", cmd, "--enter"], this.cliCwd(st)), { mutating: true });
-        // Recorded 1.4.186 send receipt: result.send = {handle, accepted, bytesWritten} — there is no
-        // `delivered`. `ok:true` alone is not a receipt: only an accepted receipt naming THIS handle
-        // proves the text was submitted, so anything else is a failed send, never a silent no-op.
+        await this.sendText(st, cmd);
+    }
+    async sendText(st, text) {
+        const env = await this.terminalOp("send", st, (h) => this.call("send", ["terminal", "send", "--terminal", h, "--text", text, "--enter"], this.cliCwd(st)), { mutating: true });
+        // Recorded 1.4.195 send receipt: result.send = {handle, accepted, bytesWritten}. `ok:true`
+        // alone is not delivery: the accepted receipt must name this handle and account for the bytes.
+        const receipt = this.sendReceipt(env, st);
+        const expectedBytes = Buffer.byteLength(text, "utf8") + 1;
+        if (receipt.accepted !== true || typeof receipt.bytesWritten !== "number" || receipt.bytesWritten !== expectedBytes) {
+            throw new OrcaError("send", `send receipt does not report expected byte delivery (accepted: ${JSON.stringify(receipt.accepted)}, bytesWritten: ${receipt.bytesWritten}, expected: ${expectedBytes})`, env.raw);
+        }
+    }
+    sendReceipt(env, st) {
         const receipt = env.result.send;
         if (typeof receipt !== "object" || receipt === null || Array.isArray(receipt)) {
             throw new OrcaError("send", "send response carries no send receipt", env.raw);
         }
-        const s = receipt;
-        if (str(s.handle) !== st.handle) {
-            throw new OrcaError("send", `send receipt names terminal ${str(s.handle) ?? "none"}, not the addressed ${st.handle}`, env.raw);
-        }
-        const expectedBytes = Buffer.byteLength(cmd, "utf8") + 1; // 1 for the --enter newline
-        if (s.accepted !== true || typeof s.bytesWritten !== "number" || s.bytesWritten !== expectedBytes) {
-            throw new OrcaError("send", `send receipt does not report expected byte delivery (accepted: ${JSON.stringify(s.accepted)}, bytesWritten: ${s.bytesWritten}, expected: ${expectedBytes})`, env.raw);
+        const parsed = receipt;
+        if (str(parsed.handle) !== st.handle) {
+            throw new OrcaError("send", `send receipt names terminal ${str(parsed.handle) ?? "none"}, not the addressed ${st.handle}`, env.raw);
         }
+        return parsed;
     }
     async create(st, cmd) {
         await this.probeRuntime(this.cliCwd(st));
@@ -435,9 +464,10 @@ export class OrcaDriver {
         st.handle = handle;
         // The handle is bound to the runtime identity that ANSWERED its create.
         st.runtimeId = env.runtimeId;
-        const surface = str(term.surface);
-        if (surface !== undefined && surface !== "visible") {
-            await this.notify(`tickmarkr orca terminal created on ${surface} surface`, { tier: "attention" });
+        st.surface = str(term.surface);
+        st.hostPlatform = str(term.hostPlatform);
+        if (st.surface !== undefined && st.surface !== "visible") {
+            await this.notify(`tickmarkr orca terminal created on ${st.surface} surface`, { tier: "attention" });
         }
     }
     /**
@@ -920,6 +950,75 @@ export class OrcaDriver {
             await this.time.sleep(Math.min(this.pollMs, left2));
         }
     }
+    async sendKey(slot, key) {
+        const st = this.state(slot);
+        this.assertAvailable("send", st);
+        if (key === "enter") {
+            await this.sendText(st, "");
+            return;
+        }
+        if (key === "ctrl+c") {
+            const env = await this.terminalOp("send", st, (h) => this.call("send", ["terminal", "send", "--terminal", h, "--interrupt"], this.cliCwd(st)), { mutating: true });
+            // UNRECORDED SHAPE: Orca 1.4.195 was not captured for `send --interrupt`. Until a live
+            // receipt exists, validate only the shared envelope and its handle binding; do not invent
+            // accepted/bytesWritten semantics for an interrupt.
+            this.sendReceipt(env, st);
+            return;
+        }
+        throw new OrcaError("send", `Orca has no terminal key verb for ${JSON.stringify(key)}`, "");
+    }
+    async nudge(slot, message) {
+        if (!message)
+            return false;
+        try {
+            const st = this.state(slot);
+            if (!await this.waitCondition(st, "tui-idle", 1))
+                return false;
+            // Drain to the current stream cursor before sending. A message already present makes the
+            // proof ambiguous, so decline rather than reporting delivery from old scrollback.
+            const before = await this.sweep(st);
+            if (before.includes(message) || joinWrapped(before).includes(message))
+                return false;
+            await this.sendText(st, message);
+            const deadline = this.time.now() + NUDGE_ECHO_TIMEOUT_MS;
+            for (;;) {
+                const after = await this.sweep(st);
+                if (after.includes(message) || joinWrapped(after).includes(message))
+                    return true;
+                const left = deadline - this.time.now();
+                if (left <= 0)
+                    return false;
+                await this.time.sleep(Math.min(this.pollMs, left));
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    async narrator(cwd, command, runId) {
+        if (!runId)
+            throw new OrcaError("create", "Orca narrator requires a run identity", "");
+        const slot = await this.slot(cwd, formatOwnedName({ role: "watch", taskId: "run", attempt: 0, runId }), { owned: { role: "watch", taskId: "run", attempt: 0, runId } });
+        await this.run(slot, command);
+        return slot;
+    }
+    async project(taskId, state) {
+        const worktree = this.taskWorktrees.get(taskId);
+        if (!worktree) {
+            // The daemon projects in-progress immediately before it creates the task checkout/slot.
+            // Hold only that latest state; slot() applies it once the task's own path is known.
+            this.pendingProjects.set(taskId, state);
+            return;
+        }
+        await this.setWorkspaceStatus(worktree, state);
+    }
+    async setWorkspaceStatus(worktree, state) {
+        // UNRECORDED SHAPE: no Orca 1.4.195 `worktree set` receipt was captured. The shared envelope
+        // parser is the complete success proof here; no result payload is assumed or fabricated.
+        await this.call("worktree-set", [
+            "worktree", "set", "--worktree", `path:${worktree}`, "--workspace-status", state,
+        ], worktree);
+    }
     async notify(msg, opts) {
         if (opts?.tier === "routine")
             return;