tickmarkr 2.2.1 → 2.4.0

package/dist/drivers/orca.js

@@ -2,8 +2,9 @@ import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { shq } from "../adapters/types.js";
 import { createWorktree, sh } from "../run/git.js";
+import { Journal } from "../run/journal.js";
 import { MAX_BUF } from "./subprocess.js";
-import { formatOwnedName, panesToClose } from "./types.js";
+import { formatOwnedName, panesToClose, parseOwnedName } from "./types.js";
 // Orca (onorca.dev) as a third execution surface beside herdr and subprocess. tickmarkr keeps
 // worktrees, routing, gates, journal and merges; orca supplies visible terminals only. Everything
 // here is bound by the 1.4.186 conformance spike
@@ -31,7 +32,10 @@ import { formatOwnedName, panesToClose } from "./types.js";
 //  - `terminal list`'s `--worktree` is OPTIONAL (same help): the reconcile sweep omits it, because
 //    an older run's leftover sits in a checkout this run never knew (T2).
 /** 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"];
+export const ORCA_RESPONSE_FAMILIES = [
+    "status", "create", "list", "read", "send", "wait", "show", "close",
+    "worktree-current", "worktree-set", "hooks-status",
+];
 export const ORCA_FIXTURE_VERSION = "1.4.195";
 export const ORCA_CLI_COMMAND_ENV = "ORCA_CLI_COMMAND";
 export const STALE_HANDLE_CODE = "terminal_handle_stale";
@@ -50,6 +54,10 @@ const PAGE_LINES = 500; // per-page ask; orca caps server-side and reports `limi
 const LIST_LIMIT = 10000; // well past orca's own row default; `truncated` still decides (listAll)
 const MAX_PAGES = 400; // runaway guard: a cursor that stops advancing ends the sweep, never loops
 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)),
@@ -252,6 +260,11 @@ export class OrcaDriver {
     pageLines;
     pollMs;
     probeStalenessMs;
+    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.
@@ -347,7 +360,16 @@ export class OrcaDriver {
         // Canonical: git and Orca can spell one checkout two ways, and every later comparison — create
         // receipt, relist, reconcile — is against THIS value.
         const worktree = canonicalWorktreePath(cwd);
-        this.slots.set(id, { title, cwd: worktree, buf: "", recoveries: 0, recovering: false });
+        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). */
@@ -368,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) {
@@ -377,25 +410,32 @@ 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));
+        await this.awaitWorktreeAdoption(st);
         // The selector names THIS slot's checkout outright, and the CLI child is bound to it too, so
         // neither the UI's active worktree (`active`/`current`) nor the daemon's cwd can place it.
         const env = await this.call("create", [
@@ -424,11 +464,70 @@ 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" });
         }
     }
+    /**
+     * 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.
+     */
+    async awaitWorktreeAdoption(st) {
+        const started = this.time.now();
+        const deadline = started + WORKTREE_ADOPTION_TIMEOUT_MS;
+        let lastReported;
+        for (;;) {
+            const left = deadline - this.time.now();
+            if (left < 0)
+                break;
+            try {
+                const env = await this.call("worktree-current", ["worktree", "current"], st.cwd, Math.max(1, left));
+                const worktree = env.result.worktree;
+                if (typeof worktree !== "object" || worktree === null || Array.isArray(worktree)) {
+                    throw new OrcaError("worktree-current", "response carries no worktree record", env.raw, { runtimeId: env.runtimeId });
+                }
+                const reported = terminalWorktree(worktree);
+                if (!reported) {
+                    throw new OrcaError("worktree-current", "worktree record carries no path", env.raw, { runtimeId: env.runtimeId });
+                }
+                lastReported = canonicalWorktreePath(reported);
+                if (lastReported === st.cwd) {
+                    const waitedMs = this.time.now() - started;
+                    if (waitedMs > WORKTREE_ADOPTION_JOURNAL_MS)
+                        this.appendAdoptionWait(st, waitedMs);
+                    return;
+                }
+            }
+            catch (error) {
+                if (!(error instanceof OrcaError) || error.code !== "selector_not_found")
+                    throw error;
+                lastReported = undefined;
+            }
+            const remaining = deadline - this.time.now();
+            if (remaining <= 0)
+                break;
+            await this.time.sleep(Math.min(WORKTREE_ADOPTION_POLL_MS, remaining));
+        }
+        const waitedMs = this.time.now() - started;
+        throw new OrcaUnavailableError("worktree-current", `Orca did not adopt ${st.cwd} within ${WORKTREE_ADOPTION_TIMEOUT_MS}ms${lastReported ? ` (last answered ${lastReported})` : ""}`, `waitedMs=${waitedMs}`);
+    }
+    /** Same repo/run/narration path Herdr uses for its driver-owned dispatch-retry row. */
+    appendAdoptionWait(st, waitedMs) {
+        const owned = parseOwnedName(st.title);
+        if (!owned)
+            throw new Error(`cannot journal worktree-adoption-wait: slot ${st.title} carries no run identity`);
+        const repoRoot = this.journalRoots.get(st.cwd);
+        if (!repoRoot) {
+            throw new Error(`cannot journal worktree-adoption-wait: slot ${st.title} has no daemon repo binding for ${st.cwd}`);
+        }
+        Journal.open(repoRoot, owned.runId, this.narrate).append("worktree-adoption-wait", owned.taskId, {
+            milliseconds: waitedMs,
+        });
+    }
     // ---- handle identity and restart recovery ----------------------------------------------------
     /**
      * Every terminal-addressed call — read AND write — goes through here, and the runtime identity is
@@ -628,6 +727,18 @@ export class OrcaDriver {
         ], this.cliCwd(st)), { onRecovered: () => { recovered = true; } });
         return { term: this.validated(family, st, env), raw: env.raw, recovered };
     }
+    /** A rendered-frame liveness read. `--screen` and `--cursor` are mutually exclusive in Orca. */
+    async readScreen(st) {
+        const env = await this.terminalOp("status", st, (h) => this.call("read", [
+            "terminal", "read", "--terminal", h, "--screen",
+        ], this.cliCwd(st)));
+        const term = this.validated("status", st, env);
+        const source = str(term.source);
+        if (source !== "screen" && source !== "screen-unavailable") {
+            throw new OrcaError("read", `screen read reports source ${source ?? "absent"}, not screen or screen-unavailable`, env.raw);
+        }
+        return { term, source };
+    }
     /** 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. */
     async read(slot, lines) {
@@ -704,10 +815,14 @@ export class OrcaDriver {
             // reporting even when the show record alone would still look connected (show carries no
             // status field of its own, so a terminal can report "unknown"/"exited" on read while its
             // show row still says connected — the read leg is the only place that catches that).
-            await this.readPage("status", st, undefined, 1);
+            const screen = await this.readScreen(st);
             if (`${st.runtimeId}:${st.handle}:${st.recoveries}` !== gen) {
                 continue;
             }
+            // No rendered frame means no trustworthy TUI state. In particular, the stream fragments this
+            // call replaced cannot license an idle verdict or a wait probe.
+            if (screen.source === "screen-unavailable")
+                return "unknown";
             const env = await this.terminalOp("show", st, (h) => this.call("show", ["terminal", "show", "--terminal", h], this.cliCwd(st)));
             if (`${st.runtimeId}:${st.handle}:${st.recoveries}` !== gen) {
                 continue;
@@ -715,6 +830,11 @@ export class OrcaDriver {
             const term = this.liveShowTerm("status", st, env);
             if (term.agentWait === true)
                 return "blocked";
+            // Orca can only report tui-idle/agentWait for agents whose managed hook is installed. A
+            // definitively unhooked adapter is unknown; an agent absent from Orca's table keeps the
+            // legacy probe because absence is not proof that the CLI has no compatible status surface.
+            if (await this.agentHookAvailable(st) === false)
+                return "unknown";
             // `idle` is proven only by orca's own tui-idle condition: a 1ms wait is a point-in-time probe —
             // satisfied now → idle; elapsed (the recorded `timeout` refusal) → not idle.
             const isIdle = await this.waitCondition(st, "tui-idle", 1);
@@ -724,6 +844,50 @@ export class OrcaDriver {
             return mapAgentState(term, isIdle);
         }
     }
+    hookAgent(adapter) {
+        if (adapter === "claude-code")
+            return "claude";
+        if (adapter === "cursor-agent")
+            return "cursor";
+        return adapter;
+    }
+    /** true = hooked, false = definitively unhooked, undefined = agent absent from Orca's table. */
+    async agentHookAvailable(st) {
+        if (!st.agent)
+            return undefined;
+        this.hookCoverage ??= this.loadHookCoverage(st.cwd);
+        const coverage = await this.hookCoverage;
+        const state = coverage.states.get(this.hookAgent(st.agent));
+        // The table's omission is deliberately inconclusive even when managed hooks are disabled:
+        // Orca may not know this agent, so preserve the legacy probe exactly as an unlisted row does.
+        if (state === undefined)
+            return undefined;
+        return coverage.enabled && state === "installed";
+    }
+    async loadHookCoverage(cwd) {
+        const env = await this.call("hooks-status", ["agent", "hooks", "status"], cwd);
+        if (typeof env.result.enabled !== "boolean") {
+            throw new OrcaError("hooks-status", "response carries no boolean enabled", env.raw, { runtimeId: env.runtimeId });
+        }
+        const statuses = env.result.statuses;
+        if (!Array.isArray(statuses)) {
+            throw new OrcaError("hooks-status", "response carries no statuses array", env.raw, { runtimeId: env.runtimeId });
+        }
+        const states = new Map();
+        const allowed = new Set(["installed", "not_installed", "partial", "error"]);
+        for (const row of statuses) {
+            if (typeof row !== "object" || row === null || Array.isArray(row)) {
+                throw new OrcaError("hooks-status", "statuses carries a non-object row", env.raw, { runtimeId: env.runtimeId });
+            }
+            const agent = str(row.agent);
+            const state = str(row.state);
+            if (!agent || !state || !allowed.has(state)) {
+                throw new OrcaError("hooks-status", "status row carries no valid agent/state pair", env.raw, { runtimeId: env.runtimeId });
+            }
+            states.set(agent, state);
+        }
+        return { enabled: env.result.enabled, states };
+    }
     /** 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. */
@@ -786,11 +950,83 @@ 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;
         console.log(`[tickmarkr] ${msg}`); // console fallback only — notification injection is out of scope
     }
+    narrateWith(narrate) {
+        this.narrate = narrate;
+    }
     async close(slot) {
         const st = this.slots.get(slot.id);
         if (!st)
@@ -909,7 +1145,11 @@ export class OrcaDriver {
         catch { /* cosmetic — visibility hygiene never fails the run */ }
     }
     // tickmarkr's own createWorktree stays the sole checkout authority — orca never makes worktrees.
-    worktree(repo, branch, baseRef) {
-        return createWorktree(repo, branch, baseRef);
+    async worktree(repo, branch, baseRef) {
+        const worktree = await createWorktree(repo, branch, baseRef);
+        const repoRoot = canonicalWorktreePath(repo);
+        this.journalRoots.set(repoRoot, repoRoot);
+        this.journalRoots.set(canonicalWorktreePath(worktree), repoRoot);
+        return worktree;
     }
 }

package/dist/drivers/subprocess.d.ts

@@ -1,14 +1,14 @@
 import type { ExecutorDriver, NotifyOpts, Slot } from "./types.js";
 export declare const MAX_BUF: number;
-export declare const HERDR_CONTROL_VARS: readonly ["HERDR_ENV", "HERDR_SOCKET_PATH"];
+export declare const HERDR_CONTROL_VARS: readonly ["HERDR_ENV", "HERDR_SOCKET_PATH", "ORCA_TERMINAL_HANDLE", "ORCA_PANE_KEY", "ORCA_TAB_ID"];
 /**
- * Copy of worker env with the fork cap applied and herdr control-plane vars stripped.
+ * Copy of worker env with the fork cap applied and host control-plane vars stripped.
  * The cap is the one the enclosing run resolved (resolvedForkCap) — a worker's suites divide the
  * same machine the gate shells do, so both seams have to read the same run-owned number rather
  * than a flat constant. The operator's own export still wins.
  */
 export declare function sealHerdrEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
-/** Pane/login-shell form of the same worker env seal (herdr seed + daemon setup). */
+/** Pane/login-shell form of the same host-neutral worker env seal (herdr seed + daemon setup). */
 export declare function herdrSealShellPrefix(env?: NodeJS.ProcessEnv): string;
 export declare class SubprocessDriver implements ExecutorDriver {
     id: string;

package/dist/drivers/subprocess.js

@@ -8,13 +8,20 @@ import { createWorktree, FORK_CAP_ENV, resolvedForkCap } from "../run/git.js";
 // waitOutput poll (~10MB/s sustained, far beyond agent-CLI rates). Tail-truncate, never head:
 // consumers only ever tail-read.
 export const MAX_BUF = 2 * 1024 * 1024;
-// OBS-17 / v1.22 T3: control-plane vars that let a process talk to the operator's herdr.
-// Workers, judges, reviewers, and consults must never inherit them — only the daemon process
-// (and its own herdr driver CLI calls) keep the live session. Socket path is the wire; HERDR_ENV
-// is the "I am inside herdr" gate every agent skill checks before mutating panes.
-export const HERDR_CONTROL_VARS = ["HERDR_ENV", "HERDR_SOCKET_PATH"];
+// OBS-17 / v1.22 T3 and OBS-843: host control-plane vars that let a process address the operator's
+// herdr or Orca UI. Workers, judges, reviewers, and consults must never inherit them — only the
+// daemon process and its driver calls keep the live session. TERM_PROGRAM is host description, not
+// an addressing capability, and ORCA_AGENT_HOOK_* belongs to agent status transport, so both stay.
+// Keep the exported name for compatibility even though the list is now host-neutral.
+export const HERDR_CONTROL_VARS = [
+    "HERDR_ENV",
+    "HERDR_SOCKET_PATH",
+    "ORCA_TERMINAL_HANDLE",
+    "ORCA_PANE_KEY",
+    "ORCA_TAB_ID",
+];
 /**
- * Copy of worker env with the fork cap applied and herdr control-plane vars stripped.
+ * Copy of worker env with the fork cap applied and host control-plane vars stripped.
  * The cap is the one the enclosing run resolved (resolvedForkCap) — a worker's suites divide the
  * same machine the gate shells do, so both seams have to read the same run-owned number rather
  * than a flat constant. The operator's own export still wins.
@@ -27,7 +34,7 @@ export function sealHerdrEnv(env = process.env) {
         delete out[k];
     return out;
 }
-/** Pane/login-shell form of the same worker env seal (herdr seed + daemon setup). */
+/** Pane/login-shell form of the same host-neutral worker env seal (herdr seed + daemon setup). */
 export function herdrSealShellPrefix(env = process.env) {
     const forkCap = sealHerdrEnv(env)[FORK_CAP_ENV] ?? resolvedForkCap();
     return `export ${FORK_CAP_ENV}=${shq(forkCap)}; ` +
@@ -56,8 +63,8 @@ export class SubprocessDriver {
         // HARD-05: interactive=false — no operator, so an open stdin pipe is a promise tickmarkr can never
         // keep; codex exec appends a piped stdin as a <stdin> block (`codex exec --help`) and blocks on a
         // read that never EOFs. One spawn site covers every adapter (D-06).
-        // v1.22 T3: seal herdr control vars so worker/judge/review/consult children cannot reach the
-        // operator's herdr (OBS-17 watch-tab leak class). process.env of the daemon is untouched.
+        // v1.22 T3 / OBS-843: seal host control vars so worker/judge/review/consult children cannot
+        // address the operator's herdr or Orca UI. process.env of the daemon is untouched.
         const p = spawn("bash", ["-lc", cmd], {
             cwd: slot.cwd,
             stdio: ["ignore", "pipe", "pipe"],

package/dist/drivers/types.d.ts

@@ -36,6 +36,8 @@ export interface SlotOpts {
     group?: string;
     label?: string;
     owned?: OwnedName;
+    /** Adapter id for execution surfaces whose liveness support is agent-specific. */
+    agent?: string;
 }
 export declare const OWNED_ROLES: readonly ["worker", "judge", "review", "consult", "watch", "other"];
 export type OwnedRole = (typeof OWNED_ROLES)[number];
@@ -64,9 +66,17 @@ export declare function panesToClose(agents: FleetAgent[], desired: Set<string>,
     tabId?: string;
 }[];
 export declare function canonicalizeLegacyName(name: string, runId: string): OwnedName;
+export interface SlotPlacement {
+    surface?: string;
+    hostPlatform?: string;
+}
 export interface ExecutorDriver {
     id: string;
     interactive: boolean;
+    /** The exact terminal read surface used for liveness evidence. */
+    readSource?: string;
+    /** Placement facts returned by drivers whose terminal host exposes them. */
+    describe?(slot: Slot): SlotPlacement | Promise<SlotPlacement>;
     slot(cwd: string, name: string, opts?: SlotOpts): Promise<Slot>;
     run(slot: Slot, cmd: string): Promise<void>;
     waitOutput(slot: Slot, pattern: string, timeoutMs: number, opts?: {
@@ -82,5 +92,7 @@ export interface ExecutorDriver {
     narrateWith?(narrate: (event: JournalEvent) => void): void;
     worktree(repo: string, branch: string, baseRef: string): Promise<string>;
     narrator?: (cwd: string, command: string, runId?: string) => Promise<Slot>;
+    /** Best-effort projection of a task's lifecycle onto the execution host. */
+    project?: (taskId: string, state: "in-progress" | "in-review" | "completed") => Promise<void>;
     reconcile?: (desired: Set<string>, runId: string, opts?: PanesToCloseOpts) => Promise<void>;
 }

package/dist/gates/baseline.d.ts

@@ -23,6 +23,8 @@ export interface BaselineCommand {
     exitCode?: number;
     fingerprints: string[];
     missingCommand?: boolean;
+    /** Why a capture returned no verdict. */
+    invalidCause?: "ceiling-kill" | "resource-exhaustion";
     /** What this command actually took at capture, on a pristine tree. Absent in pre-v1.90 baselines. */
     durationMs?: number;
     /** Sum of the per-file durations named by the runner; null when its output names none. */