tickmarkr 2.2.1 → 2.3.0

package/dist/cli/commands/verify.js

@@ -1,16 +1,18 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { allAdapters, probeAll, readDoctor, rolePools } from "../../adapters/registry.js";
 import { channelKey } from "../../adapters/types.js";
 import { loadConfig } from "../../config/config.js";
 import { captureBaseline, detectGateCommands } from "../../gates/baseline.js";
+import { modelProvider } from "../../gates/review.js";
 import { runGates } from "../../gates/run-gates.js";
 import { getTask, loadGraph } from "../../graph/graph.js";
 import { GATE_NAMES } from "../../graph/schema.js";
 import { linkNodeModules, removeWorktree, shGit, shGitOk } from "../../run/git.js";
+import { Journal } from "../../run/journal.js";
 /**
  * tickmarkr verify — the gate battery as a standalone command (OPERATING-MODEL-2026-08-11 item 3).
  *
@@ -59,6 +61,70 @@ const DIRTY_WHY = `refusing to gate a dirty worktree: the shell gates run agains
 export function verifyStateDir(cwd) {
     return join(realpathSync(tmpdir()), "tickmarkr-verify", createHash("sha256").update(cwd).digest("hex").slice(0, 12));
 }
+const STATE_FILES = ["graph.json", "doctor.json", "config.yaml"];
+const LOCKFILES = ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"];
+/** Linked worktrees share operational state with the repository that owns the common git dir. */
+export async function verifyStateRoot(cwd) {
+    const commonDir = resolve(cwd, (await shGitOk("git rev-parse --git-common-dir", cwd)).trim());
+    const commonRoot = realpathSync(dirname(commonDir));
+    if (commonRoot === realpathSync(cwd))
+        return cwd;
+    const localState = join(cwd, ".tickmarkr");
+    const commonState = join(commonRoot, ".tickmarkr");
+    return STATE_FILES.some((file) => !existsSync(join(localState, file)) && existsSync(join(commonState, file)))
+        ? commonRoot
+        : cwd;
+}
+const hashParts = (parts) => {
+    const hash = createHash("sha256");
+    for (const part of parts)
+        hash.update(part);
+    return hash.digest("hex").slice(0, 12);
+};
+/** Cache identity is repository content, never a checkout path. */
+export function baselineCachePath(cwd, baseSha, commands) {
+    const lockParts = [];
+    for (const file of LOCKFILES) {
+        const path = join(cwd, file);
+        lockParts.push(file, existsSync(path) ? readFileSync(path) : "<absent>");
+    }
+    const commandParts = Object.entries(commands).sort(([a], [b]) => a.localeCompare(b)).map(([name, command]) => `${name}\0${command}\0`);
+    return join(realpathSync(tmpdir()), "tickmarkr-verify", "cache", `baseline-${baseSha.slice(0, 12)}-${hashParts(lockParts)}-${hashParts(commandParts)}.json`);
+}
+const verdictlessCommands = (baseline, commands) => Object.keys(commands).filter((name) => baseline.commands[name]?.exitCode === undefined);
+export function excludeAuthorProvider(channels, author) {
+    const provider = modelProvider(author.model, author.vendor);
+    return [author, ...channels.filter((candidate) => candidate !== author && modelProvider(candidate.model, candidate.vendor) !== provider)];
+}
+function recordedMerges(repoRoot) {
+    const runs = join(repoRoot, ".tickmarkr", "runs");
+    if (!existsSync(runs))
+        return [];
+    const rows = [];
+    for (const runId of readdirSync(runs).filter((name) => name.startsWith("run-")).sort().reverse()) {
+        const path = join(runs, runId, "journal.jsonl");
+        if (!existsSync(path))
+            continue;
+        for (const line of readFileSync(path, "utf8").split("\n").filter(Boolean)) {
+            try {
+                const row = JSON.parse(line);
+                if (row.event === "merge" && row.taskId && row.data?.commit)
+                    rows.push({ runId, taskId: row.taskId, commit: row.data.commit });
+            }
+            catch { /* torn journal tail is not a merge record */ }
+        }
+    }
+    return rows;
+}
+async function warnWideTaskRange(cwd, stateRoot, taskId, mergeBase) {
+    const inRange = new Set((await shGitOk(`git rev-list --merges '${mergeBase}..HEAD'`, cwd)).trim().split("\n").filter(Boolean));
+    const merges = recordedMerges(stateRoot).filter((row) => inRange.has(row.commit));
+    const own = merges.find((row) => row.taskId === taskId);
+    const others = own ? merges.filter((row) => row.taskId !== taskId) : [];
+    if (own && others.length) {
+        console.error(`verify: WARNING --task ${taskId} range also carries merge commit(s) for ${others.map((row) => `${row.taskId} ${row.commit.slice(0, 12)}`).join(", ")}; ${taskId}'s own merge ${own.commit} is the intended HEAD`);
+    }
+}
 export async function verify(argv, cwd = process.cwd()) {
     const { values } = parseArgs({
         args: argv,
@@ -69,13 +135,18 @@ export async function verify(argv, cwd = process.cwd()) {
             files: { type: "string", multiple: true },
             author: { type: "string" },
             baseline: { type: "string" },
+            record: { type: "string" },
             json: { type: "boolean", default: false },
             "no-review": { type: "boolean", default: false },
             "no-acceptance": { type: "boolean", default: false },
         },
         allowPositionals: false,
     });
-    const cfg = loadConfig(cwd);
+    const stateRoot = await verifyStateRoot(cwd);
+    if (resolve(stateRoot) !== resolve(cwd)) {
+        console.error(`verify: state files graph.json, doctor.json and config.yaml resolved read-only from ${join(stateRoot, ".tickmarkr")} (linked worktree)`);
+    }
+    const cfg = loadConfig(stateRoot);
     const head = (await shGitOk("git rev-parse HEAD", cwd)).trim();
     const baseTip = (await shGitOk(`git rev-parse '${values.base}'`, cwd).catch(() => {
         throw new Error(`--base ${values.base} is not a resolvable ref — pass --base <ref> naming the branch this diff targets`);
@@ -89,9 +160,7 @@ export async function verify(argv, cwd = process.cwd()) {
     let files = values.files ?? [];
     let goal = `independent verification of the ${values.base}..HEAD diff`;
     if (values.task) {
-        const t = getTask(loadGraph(cwd), values.task);
-        if (!t)
-            throw new Error(`--task ${values.task}: no such task in .tickmarkr/graph.json`);
+        const t = getTask(loadGraph(stateRoot), values.task);
         acceptance = t.acceptance;
         if (!files.length)
             files = t.files;
@@ -102,6 +171,8 @@ export async function verify(argv, cwd = process.cwd()) {
         if (!acceptance.length)
             throw new Error(`--criteria ${values.criteria}: no criteria found (bullets or command:/test:/judge: lines)`);
     }
+    if (values.task)
+        await warnWideTaskRange(cwd, stateRoot, values.task, mergeBase);
     const wantAcceptance = acceptance.length > 0 && !values["no-acceptance"];
     const wantReview = !values["no-review"];
     // A gate that enforced nothing must not print a green row. `files` has exactly three sources —
@@ -145,7 +216,7 @@ export async function verify(argv, cwd = process.cwd()) {
     let author = HUMAN_AUTHOR;
     const adapters = allAdapters();
     if (wantAcceptance || wantReview) {
-        const health = readDoctor(cwd) ?? (await probeAll(adapters));
+        const health = readDoctor(stateRoot) ?? (await probeAll(adapters));
         const pools = rolePools(cfg, adapters, health);
         judgeChannels = pools.judge;
         channels = pools.review;
@@ -157,6 +228,7 @@ export async function verify(argv, cwd = process.cwd()) {
                 throw new Error(`--author ${values.author} does not name a discoverable review channel — one of: ${channels.map(channelKey).join(", ") || "(none)"}`);
             }
             author = { adapter: c.adapter, model: c.model, channel: c.channel, tier: c.tier };
+            channels = excludeAuthorProvider(channels, c);
         }
         else {
             channels = [...channels, HUMAN_CHANNEL];
@@ -173,28 +245,56 @@ export async function verify(argv, cwd = process.cwd()) {
     const stateDir = verifyStateDir(cwd);
     mkdirSync(stateDir, { recursive: true });
     let baseline;
-    const cachePath = join(stateDir, `baseline-${mergeBase.slice(0, 12)}.json`);
+    const cachePath = baselineCachePath(cwd, mergeBase, commands);
+    const verdictlessMarker = `${cachePath}.verdictless`;
+    mkdirSync(dirname(cachePath), { recursive: true });
     if (values.baseline) {
         baseline = JSON.parse(readFileSync(values.baseline, "utf8"));
     }
-    else if (existsSync(cachePath)) {
-        console.error(`verify: reusing cached baseline for ${mergeBase.slice(0, 12)} (${cachePath})`);
-        baseline = JSON.parse(readFileSync(cachePath, "utf8"));
-    }
     else {
-        const baseDir = join(stateDir, `base-${mergeBase.slice(0, 12)}`);
-        console.error(`verify: capturing baseline at merge-base ${mergeBase.slice(0, 12)} (one-time per base; cached at ${cachePath})`);
-        await shGit(`git worktree remove --force '${baseDir}'`, cwd); // stale leftover from an interrupted run
-        await shGitOk(`git worktree add --detach '${baseDir}' '${mergeBase}'`, cwd);
-        try {
-            linkNodeModules(cwd, baseDir, { force: true });
-            baseline = await captureBaseline(baseDir, commands);
-            writeFileSync(cachePath, JSON.stringify(baseline, null, 2));
+        let cached;
+        if (existsSync(cachePath)) {
+            cached = JSON.parse(readFileSync(cachePath, "utf8"));
+            const missing = verdictlessCommands(cached, commands);
+            if (missing.length) {
+                console.error(`verify: cached baseline recorded no verdict for ${missing.join(", ")}; it was not reusable and will be recaptured`);
+                rmSync(cachePath, { force: true });
+                cached = undefined;
+            }
         }
-        finally {
-            await removeWorktree(cwd, baseDir);
+        if (cached) {
+            console.error(`verify: reusing cached baseline for ${mergeBase.slice(0, 12)} (${cachePath})`);
+            baseline = cached;
+        }
+        else {
+            if (existsSync(verdictlessMarker)) {
+                console.error(`verify: prior baseline recorded no verdict and was not cached; recapturing merge-base ${mergeBase.slice(0, 12)}`);
+            }
+            else {
+                console.error(`verify: capturing baseline at merge-base ${mergeBase.slice(0, 12)} (cached by base, lockfile and command hashes at ${cachePath})`);
+            }
+            const baseDir = join(stateDir, `base-${mergeBase.slice(0, 12)}`);
+            await shGit(`git worktree remove --force '${baseDir}'`, cwd); // stale leftover from an interrupted run
+            await shGitOk(`git worktree add --detach '${baseDir}' '${mergeBase}'`, cwd);
+            try {
+                linkNodeModules(cwd, baseDir, { force: true });
+                baseline = await captureBaseline(baseDir, commands);
+                const missing = verdictlessCommands(baseline, commands);
+                if (missing.length) {
+                    writeFileSync(verdictlessMarker, JSON.stringify({ base: mergeBase, commands: missing }) + "\n");
+                    rmSync(cachePath, { force: true });
+                }
+                else {
+                    writeFileSync(cachePath, JSON.stringify(baseline, null, 2));
+                    rmSync(verdictlessMarker, { force: true });
+                }
+            }
+            finally {
+                await removeWorktree(cwd, baseDir);
+            }
         }
     }
+    const recordJournal = values.record ? Journal.open(stateRoot, values.record) : undefined;
     const artifactDir = join(stateDir, new Date().toISOString().replace(/[:.]/g, "-"));
     mkdirSync(artifactDir, { recursive: true });
     const { results } = await runGates(task, {
@@ -212,12 +312,27 @@ export async function verify(argv, cwd = process.cwd()) {
         },
     });
     const green = results.length > 0 && results.every((r) => r.pass || r.meta?.skipped === true);
+    const reviewRows = results.filter((result) => result.gate === "review");
+    const reviewFindings = reviewRows.flatMap((result) => result.details.split("\n").flatMap((line) => {
+        const match = /^- \[([^\]]+)\] (.*)$/.exec(line);
+        return match ? [{ classification: match[1], note: match[2], reviewer: result.meta?.reviewer }] : [];
+    }));
+    const artifactPath = join(artifactDir, "verify-results.json");
+    writeFileSync(artifactPath, JSON.stringify({ base: baseTip, head, mergeBase, green, gateRows: results, reviewFindings }, null, 2) + "\n");
+    console.error(`verify: artifacts written to ${artifactPath}`);
+    const review = reviewRows.at(-1);
+    if (recordJournal && review) {
+        recordJournal.append("review-leg2", values.task ?? "VERIFY", {
+            base: baseTip, head, mergeBase, author: channelKey(author), artifactPath,
+            ...review,
+        });
+    }
     if (values.json) {
-        return { out: JSON.stringify({ base: baseTip, head, mergeBase, green, results }, null, 2), code: green ? 0 : 2 };
+        return { out: JSON.stringify({ base: baseTip, head, mergeBase, green, artifactPath, results }, null, 2), code: green ? 0 : 2 };
     }
     const lines = results.map((r) => `${r.pass ? "PASS" : "FAIL"} ${r.gate}\n${r.details.split("\n").map((l) => `  ${l}`).join("\n")}`);
     const verdict = green
-        ? `verify GREEN — ${results.length} gate(s) passed on ${mergeBase.slice(0, 12)}..${head.slice(0, 12)} (merge is a human decision)`
-        : `verify RED — first failure decides; artifacts in ${artifactDir}`;
+        ? `verify GREEN — ${results.length} gate(s) passed on ${mergeBase.slice(0, 12)}..${head.slice(0, 12)} (merge is a human decision; artifacts: ${artifactPath})`
+        : `verify RED — first failure decides; artifacts: ${artifactPath}`;
     return { out: [...lines, "", verdict].join("\n"), code: green ? 0 : 2 };
 }

package/dist/compile/collateral.js

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { extname, join, relative } from "node:path";
 import { filesGlob } from "../graph/files-glob.js";
 import { criticalPathHits, DEFAULT_CONFIG, DEFAULT_REVIEW_CRITICAL_PATHS, effectiveReviewPolicy, loadConfig, } from "../config/config.js";
@@ -15,6 +15,7 @@ const MAX_WALK_FILES = 400;
 const MAX_HITS_PER_TASK = 20;
 /** Skip giant fixtures / snapshots. */
 const MAX_READ_BYTES = 512 * 1024;
+const EXPORT_MANIFEST_TEST = "tests/repo/export-manifest.test.ts";
 const SRC_EXT = /\.(ts|tsx|js|jsx|mts|cts)$/;
 const CODE_EXT = /\.(ts|tsx|js|jsx|mts|cts)$/;
 function isSrcPath(p) {
@@ -112,15 +113,20 @@ export function collateralHits(tasks, repoRoot) {
     const read = makeReader(repoRoot);
     for (const t of tasks) {
         // OBS-22: scopeGate accepts picomatch globs; advisory collateral warnings must agree.
-        const scoped = filesGlob(t.files.map((f) => f.replace(/^\.\//, "")));
-        const srcFiles = t.files.map((f) => f.replace(/^\.\//, "")).filter(isSrcPath);
-        if (!srcFiles.length)
-            continue;
+        const files = t.files.map((f) => f.replace(/^\.\//, ""));
+        const scoped = filesGlob(files);
+        const srcFiles = files.filter(isSrcPath);
+        const hits = [];
+        // Exact-enumerated scripts are an export-set contract: a new path has no name or symbol for the
+        // ordinary sweep to find, but the manifest test will reject it unless the task owns that oracle.
+        if (testFiles.includes(EXPORT_MANIFEST_TEST)
+            && !scoped(EXPORT_MANIFEST_TEST)
+            && files.some((path) => path.startsWith("scripts/") && !/[?*{[]/.test(path) && !existsSync(join(repoRoot, path))))
+            hits.push(EXPORT_MANIFEST_TEST);
         // needles unioned across all src files in this task
         const needles = [...new Set(srcFiles.flatMap(needlesFor))];
-        const hits = [];
         for (const tf of testFiles) {
-            if (scoped(tf))
+            if (scoped(tf) || hits.includes(tf))
                 continue;
             const text = read(tf);
             if (text === null)
@@ -128,9 +134,9 @@ export function collateralHits(tasks, repoRoot) {
             if (mentions(text, needles))
                 hits.push(tf);
         }
-        // deterministic: walk already sorted; stable list
+        // deterministic: the special hit and walk are stable; sort their union for one canonical map.
         if (hits.length)
-            map.set(t.id, hits);
+            map.set(t.id, hits.sort());
     }
     return map;
 }

package/dist/compile/native.js

@@ -805,9 +805,9 @@ acceptance is required on every task (a nested list of observable outcomes).
       set closed — this milestone paid a halted run to learn that the two populations are not identical.
     - SPIKE-THE-CONTRACT-THEN-SCOPE trigger question: COULD A TEST THIS TASK DOES NOT OWN BE ASSERTING THE
       THING I AM CHANGING? "I'D HAVE TO GREP TO KNOW" IS YES. This applies to observable contracts:
-      execution order, event-stream order, diagnostics/output sets, CLI surface, serialised formats, or
-      timing measurements. If yes, implement the change as a throwaway spike, run the full suite, read the
-      reds, THEN scope files[].
+      execution order, event-stream order, diagnostics/output sets, CLI surface, serialised formats,
+      timing measurements, or adding or removing a shipped file. If yes, implement the change as a
+      throwaway spike, run the full suite, read the reds, THEN scope files[].
     - Caveat: a spike measures ONE implementation. It converts unknown collateral into
       measured-for-one-specimen collateral; it does NOT make its reds the closed blocker set for every
       route. A worker taking a different route can still red on unowned collateral; that remains a PLAN

package/dist/config/config.js

@@ -713,7 +713,7 @@ export function overlayBytesLoadError(repoRoot, bytes, opts = {}) {
 export function configTemplate(overlay) {
     const base = `# tickmarkr config overlay — merges over built-in defaults (repo beats global beats defaults)
 # concurrency: 3
-# driver: auto            # auto | herdr | subprocess | orca
+# driver: auto            # auto: herdr when HERDR_ENV=1, then orca when TERM_PROGRAM=Orca + ORCA_TERMINAL_HANDLE, else subprocess; name orca explicitly outside an Orca terminal
 # taskTimeoutMinutes: 30
 # contextWarnTokens: 170000   # v1.23: journal+notify once per attempt when live worker context crosses this (status shows the sample)
 # setup: npm ci --prefer-offline   # run in each fresh task worktree before dispatch

package/dist/drivers/index.d.ts

@@ -2,6 +2,12 @@ import type { TickmarkrConfig } from "../config/config.js";
 import type { ExecutorDriver } from "./types.js";
 export declare const DRIVER_CHOICES: readonly ["auto", "herdr", "subprocess", "orca"];
 export type DriverChoice = (typeof DRIVER_CHOICES)[number];
+/**
+ * Orca authors both markers on every terminal it creates. Requiring the pair avoids treating an
+ * unrelated TERM_PROGRAM value or a copied terminal handle as host identity. This is deliberately
+ * environment-only: selection must not execute a binary or contact the Orca runtime.
+ */
+export declare function orcaHostDetected(env?: NodeJS.ProcessEnv): boolean;
 /** Validate argv at the CLI boundary rather than casting an arbitrary string into a driver choice. */
 export declare function parseDriverOverride(override?: string): DriverChoice | undefined;
 export declare function driverEvidence(cfg: TickmarkrConfig, driver: ExecutorDriver, override?: string): string;

package/dist/drivers/index.js

@@ -3,6 +3,14 @@ import { OrcaDriver } from "./orca.js";
 import { SubprocessDriver } from "./subprocess.js";
 export const DRIVER_CHOICES = ["auto", "herdr", "subprocess", "orca"];
 const overrideByDriver = new WeakMap();
+/**
+ * Orca authors both markers on every terminal it creates. Requiring the pair avoids treating an
+ * unrelated TERM_PROGRAM value or a copied terminal handle as host identity. This is deliberately
+ * environment-only: selection must not execute a binary or contact the Orca runtime.
+ */
+export function orcaHostDetected(env = process.env) {
+    return env.TERM_PROGRAM === "Orca" && env.ORCA_TERMINAL_HANDLE !== undefined;
+}
 /** Validate argv at the CLI boundary rather than casting an arbitrary string into a driver choice. */
 export function parseDriverOverride(override) {
     if (override === undefined)
@@ -20,8 +28,13 @@ export function driverEvidence(cfg, driver, override) {
     if (want !== "auto")
         return `${driver.id} (config)`;
     const herdrAvailable = process.env.HERDR_ENV === "1";
-    if (driver.id === (herdrAvailable ? "herdr" : "subprocess")) {
-        return `auto → ${driver.id} (${herdrAvailable ? "HERDR_ENV=1" : "HERDR_ENV unset"})`;
+    if (herdrAvailable && driver.id === "herdr")
+        return "auto → herdr (HERDR_ENV=1)";
+    if (!herdrAvailable && orcaHostDetected() && driver.id === "orca") {
+        return "auto → orca (TERM_PROGRAM+ORCA_TERMINAL_HANDLE)";
+    }
+    if (!herdrAvailable && !orcaHostDetected() && driver.id === "subprocess") {
+        return "auto → subprocess (HERDR_ENV unset)";
     }
     return `auto → ${driver.id} (runtime)`;
 }
@@ -34,9 +47,11 @@ export function pickDriver(cfg, override) {
     const driver = want === "herdr" ? new HerdrDriver("herdr", cfg.visibility.workersPerTab)
         : want === "subprocess" ? new SubprocessDriver()
             // Orca is an operator-selected execution surface. Its runtime failure stays on Orca; selection
-            // must never substitute a hidden subprocess worker after this explicit choice.
+            // must never substitute a hidden subprocess worker after an explicit or detected choice.
             : want === "orca" ? new OrcaDriver()
-                : HerdrDriver.available() ? new HerdrDriver("herdr", cfg.visibility.workersPerTab) : new SubprocessDriver();
+                : HerdrDriver.available() ? new HerdrDriver("herdr", cfg.visibility.workersPerTab)
+                    : orcaHostDetected() ? new OrcaDriver()
+                        : new SubprocessDriver();
     if (selectedOverride !== undefined)
         overrideByDriver.set(driver, selectedOverride);
     return driver;

package/dist/drivers/orca.d.ts

@@ -1,7 +1,8 @@
 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"];
+export declare const ORCA_RESPONSE_FAMILIES: readonly ["status", "create", "list", "read", "send", "wait", "show", "close", "worktree-current", "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";
@@ -13,6 +14,7 @@ export declare const NOT_WRITABLE_CODE = "terminal_not_writable";
 /** The ONLY terminal status that licenses reading a terminal's bytes or its agent state. */
 export declare const RUNNING_STATUS = "running";
 export declare const STATUS_GOVERNED_METHODS: readonly ["read", "waitOutput", "status", "waitAgentStatus"];
+export declare const WORKTREE_ADOPTION_TIMEOUT_MS = 60000;
 export interface OrcaExec {
     (args: string[], cwd: string, timeoutMs?: number): Promise<ShResult>;
 }
@@ -113,6 +115,9 @@ export declare class OrcaDriver implements ExecutorDriver {
     private pageLines;
     private pollMs;
     private probeStalenessMs;
+    private journalRoots;
+    private narrate?;
+    private hookCoverage?;
     constructor(opts?: OrcaDriverOpts);
     private call;
     /** The live runtime's identity, or an explicit failure. A missing or unreachable runtime is a
@@ -128,6 +133,15 @@ export declare class OrcaDriver implements ExecutorDriver {
     private assertAvailable;
     run(slot: Slot, cmd: string): Promise<void>;
     private create;
+    /**
+     * A freshly-created git checkout does not become a valid Orca selector atomically. Ask
+     * `worktree current` FROM that checkout until Orca itself resolves the exact filesystem identity;
+     * an enclosing checkout is still not adoption. Only selector_not_found is a retryable refusal —
+     * malformed envelopes and every other refusal remain explicit driver failures.
+     */
+    private awaitWorktreeAdoption;
+    /** Same repo/run/narration path Herdr uses for its driver-owned dispatch-retry row. */
+    private appendAdoptionWait;
     /**
      * Every terminal-addressed call — read AND write — goes through here, and the runtime identity is
      * established BEFORE the runtime-scoped handle goes on the wire. Discarding a lookalike's answer
@@ -149,6 +163,8 @@ export declare class OrcaDriver implements ExecutorDriver {
     private liveShowTerm;
     private tailText;
     private readPage;
+    /** A rendered-frame liveness read. `--screen` and `--cursor` are mutually exclusive in Orca. */
+    private readScreen;
     /** A single UNPAGED tail read — exactly what the caller asked for and nothing more. Markers split
      *  across cursor pages are not reassembled here; that is waitOutput's job. */
     read(slot: Slot, lines: number): Promise<string>;
@@ -163,12 +179,17 @@ export declare class OrcaDriver implements ExecutorDriver {
         regex?: boolean;
     }): Promise<boolean>;
     status(slot: Slot): Promise<string>;
+    private hookAgent;
+    /** true = hooked, false = definitively unhooked, undefined = agent absent from Orca's table. */
+    private agentHookAvailable;
+    private loadHookCoverage;
     /** One `terminal wait` through the full identity machinery. The recorded 1.4.186 elapsed answer
      *  is rc 1 + ok:true + {handle, condition, satisfied:false, status:"running"}; it is "not yet"
      *  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>;
     notify(msg: string, opts?: NotifyOpts): Promise<void>;
+    narrateWith(narrate: (event: JournalEvent) => void): void;
     close(slot: Slot): Promise<void>;
     /**
      * The one destructive call in this driver, for a slot's own terminal AND for a reconcile candidate