tickmarkr 1.30.0

package/dist/drivers/herdr.js

@@ -0,0 +1,394 @@
+import { shq } from "../adapters/types.js";
+import { createWorktree, sh } from "../run/git.js";
+import { herdrSealShellPrefix } from "./subprocess.js";
+import { canonicalizeLegacyName, formatOwnedName, panesToClose } from "./types.js";
+// VIS-09 P43-03: adopted safety floor from 43-MEASUREMENT.md (narrowest safe 53 → floor 108).
+export const TRAILER_SAFE_FLOOR_COLS = 108;
+export const TRAILER_WIDTH_MARGIN = 2; // cols below (floor + margin) refuse a rightward first split
+/** First-generation join direction from measured trailer-safe floor (43-MEASUREMENT.md). */
+export function workerSplitDirection(paneCols, safeFloor = TRAILER_SAFE_FLOOR_COLS, margin = TRAILER_WIDTH_MARGIN) {
+    if (paneCols == null || paneCols <= 0)
+        return "down";
+    return paneCols / 2 >= safeFloor + margin ? "right" : "down";
+}
+export class HerdrDriver {
+    bin;
+    workersPerTab;
+    id = "herdr";
+    interactive = true;
+    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)
+    groupSerial = Promise.resolve();
+    // VIS-10: the run's workspace id, captured once at construction (the daemon inherits it from the
+    // operator's env before the driver is built). Required at slot() time, never in the constructor —
+    // pickDriver and its unit test construct HerdrDriver without env, so slot() is the trust gate.
+    ws = process.env.HERDR_WORKSPACE_ID;
+    constructor(bin = "herdr", workersPerTab = 3) {
+        this.bin = bin;
+        this.workersPerTab = workersPerTab;
+    }
+    serial(fn) {
+        const p = this.groupSerial.then(fn, fn);
+        this.groupSerial = p.catch(() => undefined);
+        return p;
+    }
+    static available() {
+        return process.env.HERDR_ENV === "1";
+    }
+    herdr(args, cwd = process.cwd(), timeoutMs) {
+        return sh(`${shq(this.bin)} ${args}`, cwd, timeoutMs);
+    }
+    // pane ids compact when panes close — resolve fresh via the durable agent name (spec §5)
+    async paneId(slot) {
+        const r = await this.herdr(`agent get ${shq(slot.name)}`);
+        try {
+            const id = JSON.parse(r.stdout).result?.agent?.pane_id;
+            if (typeof id === "string" && id)
+                return id;
+        }
+        catch {
+            /* fall back to cached id */
+        }
+        return slot.id;
+    }
+    // VIS-09 P43-03: runtime width for the layout gate (43-MEASUREMENT.md licensing condition 2).
+    async paneWidth(paneId) {
+        const r = await this.herdr(`pane layout --pane ${shq(paneId)}`);
+        if (r.code !== 0)
+            return null;
+        try {
+            const layout = JSON.parse(r.stdout).result?.layout;
+            const pane = layout?.panes?.find((p) => p.pane_id === paneId);
+            const w = pane?.rect?.width ?? layout?.area?.width;
+            return typeof w === "number" && w > 0 ? w : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async slot(cwd, name, opts) {
+        // T1 ownership contract: `opts.owned` (T2 call sites) names the pane canonically —
+        // drovr:<role>:<taskId>:<attempt>:<runId>. Without it, `name` passes through byte-identical
+        // (today's legacy daemon/gates/consult shapes) — canonicalizeLegacyName (types.ts) is what lets
+        // reconcile.ts and this driver's own renameGroupTab/glyphFor decode role/taskId/attempt from
+        // those shapes without a call-site migration; T2 retires this branch by always passing `owned`.
+        const resolved = opts?.owned ? formatOwnedName(opts.owned) : name;
+        // group wins if both are set (a group tab is already stage-labeled; passing both is a caller bug).
+        // label (without group) → dedicated labeled tab via tabSlot's third param: no groups-map entry, no
+        // refcount, no groupSerial, no degrade latch — dedicated tabs have no shared state to guard (SUP-01).
+        if (opts?.group)
+            return this.serial(() => this.groupSlot(cwd, resolved, opts.group));
+        return this.tabSlot(cwd, resolved, opts?.label); // label undefined → defaults to name (today's behavior)
+    }
+    // today's per-slot tab path, plus the VIS-04 orphan reap
+    // label defaults to the slot name; group tabs pass the STAGE name instead — a first-member label
+    // outlives its member once keepPanes reaps it (run-20260709-104447: the codex pane sat in a tab
+    // named after a dead cursor worker and the operator read it as a mislabeled agent)
+    async tabSlot(cwd, name, label = name) {
+        // tab-per-slot: concurrent agents in one tab split it into sliver columns — TUIs exit or
+        // hard-wrap at COLUMNS≈2, shredding even the DROVR_RESULT marker (v1.4 phase-1 incident).
+        // A dedicated named tab gives every agent a full-width pane; tab close() reaps it.
+        // VIS-10 (operator ruling 2026-07-11): "pane placed by focus heuristic" is a DEFECT CLASS.
+        // Fail closed at every step — env unset, tab-create non-zero, unparseable stdout, or a parsed
+        // payload with no tab_id all REJECT. There is no path from here to an untargeted pane.
+        if (!this.ws)
+            throw new Error("herdr placement requires HERDR_WORKSPACE_ID — refusing untargeted pane (VIS-10: fail closed, never place by focus)");
+        // pin the tab to the RUN's workspace, UNCONDITIONALLY (inherited via HERDR_WORKSPACE_ID), never the
+        // operator's focused one (Intl-Dossier run-20260709-104447 incident: worker tabs opened in the drovr repo workspace)
+        const t = await this.herdr(`tab create --label ${shq(label)} --no-focus --workspace ${shq(this.ws)}`);
+        if (t.code !== 0)
+            throw new Error(`herdr tab create failed (exit ${t.code}, refusing untargeted placement): ${t.stderr || t.stdout}`);
+        let res;
+        try {
+            res = JSON.parse(t.stdout).result;
+        }
+        catch {
+            throw new Error(`herdr tab create returned unparseable JSON (refusing untargeted placement): ${t.stdout}`);
+        }
+        const tabId = res?.tab?.tab_id;
+        const rootPane = res?.root_pane?.pane_id; // auto-created shell pane (SKILL:343)
+        if (typeof tabId !== "string" || !tabId)
+            throw new Error(`herdr tab create returned no tab_id (refusing untargeted placement): ${t.stdout}`);
+        let r = await this.herdr(`agent start ${shq(name)} --cwd ${shq(cwd)} --tab ${shq(tabId)} --no-focus -- bash`);
+        if (r.code !== 0 && /agent_name_taken/.test(r.stderr + r.stdout)) {
+            // DEFECT-01: a prior (killed) process's kept pane still holds this durable name — reclaim it.
+            // The old attempt is void by construction: its worktree was rm -rf'd on re-dispatch (git.ts:34),
+            // so adoption is meaningless; close the stale PANE only (never its tab — sibling prior-run panes
+            // may still be under the operator's eye) and restart. Match BOTH streams (herdr's error-stream
+            // convention varies — Pitfall 6); an unrelated nonzero exit must never reach pane close (T-10-04).
+            const g = await this.herdr(`agent get ${shq(name)}`);
+            try {
+                const stale = JSON.parse(g.stdout).result?.agent?.pane_id;
+                if (typeof stale === "string" && stale)
+                    await this.herdr(`pane close ${shq(stale)}`);
+            }
+            catch {
+                /* holder vanished between calls (agent_not_found) — retry the start regardless */
+            }
+            r = await this.herdr(`agent start ${shq(name)} --cwd ${shq(cwd)} --tab ${shq(tabId)} --no-focus -- bash`); // once
+        }
+        if (r.code !== 0)
+            throw new Error(`herdr agent start failed: ${r.stderr || r.stdout}`); // fail closed, no loop
+        const id = JSON.parse(r.stdout).result?.agent?.pane_id;
+        if (typeof id !== "string" || !id)
+            throw new Error(`herdr agent start returned no pane id: ${r.stdout}`);
+        // tab create auto-spawns a root shell pane and agent start --tab adds the agent as a SECOND
+        // pane — reap the idle shell so no tab shows a dead "drovr git:" prompt beside its agent
+        // (VIS-04 orphan fix). Best-effort: a failed reap costs cosmetics only.
+        if (typeof rootPane === "string" && rootPane && rootPane !== id) {
+            await this.herdr(`pane close ${shq(rootPane)}`);
+        }
+        // VIS-10 hole 3: seed the run's workspace id into the agent pane's shell so a worker's own ad-hoc
+        // `herdr agent start` is workspace-targeted BY CONSTRUCTION — correct placement is the default a
+        // worker GETS, not a rule it must remember (P40-02 probe leak). Fail closed: a failed seed rejects.
+        // v1.22 T3 / OBS-17: also strip HERDR_ENV + socket path so the worker cannot open/mutate panes in
+        // the operator's session. Daemon-side this.herdr() calls keep process.env (unsealed).
+        const seed = await this.herdr(`pane run ${shq(id)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; ${herdrSealShellPrefix()}`)}`);
+        if (seed.code !== 0)
+            throw new Error(`herdr workspace-id seed failed (refusing untargeted pane): ${seed.stderr || seed.stdout}`);
+        return { id, name, cwd, tabId };
+    }
+    // VIS-04 role-tab (extended VIS-09 item 2): first member bootstraps generation 1 (WORKERS);
+    // later members join the latest generation with live-member room via joinGroup, else a NEW
+    // overflow generation tab (cleanup, cleanup, …) opens — a second `tab create`, NOT a further
+    // split of tab 1. The cap is the constructor's workersPerTab (plumbed from config via pickDriver).
+    // splitUnsupported stays PER GROUP: a herdr that can't split can't split in any tab, so once it
+    // latches every later member degrades to a per-slot tab (no overflow tab can be populated by join).
+    async groupSlot(cwd, name, group) {
+        const state = this.groups.get(group);
+        if (state?.splitUnsupported)
+            return this.tabSlot(cwd, name); // D-09: degrade, NOT a shared-tab member
+        if (state) {
+            const latest = state.generations[state.generations.length - 1];
+            if (latest && latest.members.length < this.workersPerTab) {
+                const joined = await this.joinGroup(cwd, name, group, latest);
+                if (joined)
+                    return joined;
+                state.splitUnsupported = true; // D-09 fail-safe: this and future members degrade to per-slot tabs
+                return this.tabSlot(cwd, name);
+            }
+            return this.newGeneration(cwd, name, group, state); // cap full → overflow to a new generation tab
+        }
+        const fresh = { generations: [], created: 0 };
+        this.groups.set(group, fresh);
+        return this.newGeneration(cwd, name, group, fresh); // first member ever → bootstrap generation 1
+    }
+    // bootstrap a fresh generation tab: gen 1 keeps the WORKERS stage label (today's primary tab);
+    // every overflow generation is a "cleanup" tab (VIS-13 amendment) — never a WORKERS-N numeric suffix.
+    async newGeneration(cwd, name, group, state) {
+        state.created++;
+        const label = state.created === 1 ? group.toUpperCase() : "cleanup";
+        const s = await this.tabSlot(cwd, name, label);
+        const entry = { tabId: s.tabId, label, members: [{ name, paneId: s.id }] };
+        state.generations.push(entry);
+        await this.renameGroupTab(entry);
+        return { ...s, group };
+    }
+    // Only GroupEntry instances originate in newGeneration(), after tabSlot created the tab. This never
+    // adopts or renames an operator tab; the newest live worker contributes at most one task-id token.
+    // VIS-13: that token carries ONE state glyph — ↻ for a retry attempt (attempt > 0 parsed from the
+    // member name), ✋ when the driver observes the member blocked (queried live); bare on normal running.
+    // T1: token/attempt now come from canonicalizeLegacyName (types.ts) instead of ad hoc regex — same
+    // extraction for today's legacy names ("T2-worker-...-a0-...") and, once T2 passes `owned`, for
+    // canonical names too — one parser, not two.
+    async renameGroupTab(entry) {
+        const newest = [...entry.members].reverse().find((m) => canonicalizeLegacyName(m.name, "").role === "worker");
+        const token = newest ? canonicalizeLegacyName(newest.name, "").taskId : undefined;
+        const glyph = newest ? await this.glyphFor(newest) : "";
+        const label = token ? `${entry.label} · ${token}${glyph}` : entry.label;
+        try {
+            await this.herdr(`tab rename ${shq(entry.tabId)} ${shq(label)}`);
+        }
+        catch {
+            /* cosmetic only — a relabel failure never blocks membership or teardown (v1.18 invariant) */
+        }
+    }
+    // VIS-13: at most one glyph on the hot token. ✋ wins — the driver observes the member blocked live
+    // (the actionable state the operator must clear); else ↻ for a retry attempt (attempt > 0 in the
+    // member's owned name); else bare. Status observation failure → "unknown" (never ✋), fail-safe.
+    async glyphFor(m) {
+        if ((await this.statusByName(m.name)) === "blocked")
+            return "✋";
+        return canonicalizeLegacyName(m.name, "").attempt > 0 ? "↻" : "";
+    }
+    // stack a subsequent member into the group tab; null → caller degrades (D-09)
+    async joinGroup(cwd, name, group, entry) {
+        // pane ids compact when panes close — resolve the split source fresh from the newest LIVE
+        // member's durable name (never a cached id: closing the newest member must not poison this)
+        const src = entry.members[entry.members.length - 1];
+        const srcPane = await this.paneId({ id: src.paneId, name: src.name, cwd });
+        // VIS-09 P43-03 (43-MEASUREMENT.md): first join in a generation may split right when
+        // paneWidth/2 ≥ TRAILER_SAFE_FLOOR_COLS + margin (measured floor 108, margin 2); later joins
+        // stack down. Rightward splits below the measured floor shred the marker (e8aa003 at COLUMNS≈2;
+        // unrecoverable at 25 cols per measurement). Introspection failure → down (fail closed).
+        const direction = entry.members.length === 1 ? workerSplitDirection(await this.paneWidth(srcPane)) : "down";
+        const sp = await this.herdr(`pane split ${shq(srcPane)} --direction ${direction} --no-focus`);
+        if (sp.code !== 0)
+            return null;
+        let pane;
+        try {
+            pane = JSON.parse(sp.stdout).result?.pane?.pane_id ?? undefined;
+        }
+        catch {
+            /* fall through to degrade */
+        }
+        if (typeof pane !== "string" || !pane)
+            return null;
+        // the split pane is a bare shell: give it a durable agent name (SKILL:197) and VERIFY the name
+        // resolves back to this pane (research A1 is checked live per join, never assumed) — then cd the
+        // shell into this member's own worktree (a split inherits its parent's cwd, not ours).
+        const rn = await this.herdr(`agent rename ${shq(pane)} ${shq(name)}`);
+        const verified = rn.code === 0 && (await this.paneId({ id: "", name, cwd })) === pane;
+        const cd = verified ? await this.herdr(`pane run ${shq(pane)} ${shq(`cd ${shq(cwd)}`)}`) : null;
+        if (!cd || cd.code !== 0) {
+            await this.herdr(`pane close ${shq(pane)}`); // reap the failed join, best-effort
+            return null;
+        }
+        // VIS-10 hole 3: seed the run's workspace id into the split pane's shell. A split pane is a bare
+        // shell with FRESH env from herdr (not the parent pane's exports), so without this a worker's
+        // ad-hoc herdr call from this pane would be untargeted. Fail closed: a failed seed reaps + degrades
+        // like a failed cd (return null → caller falls back to a per-slot tab). this.ws is guaranteed set —
+        // joinGroup runs only after the first member's tabSlot succeeded, which requires it (VIS-10).
+        // v1.22 T3: same env seal as tabSlot — strip control-plane vars after the workspace seed.
+        const seed = await this.herdr(`pane run ${shq(pane)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; ${herdrSealShellPrefix()}`)}`);
+        if (seed.code !== 0) {
+            await this.herdr(`pane close ${shq(pane)}`);
+            return null;
+        }
+        entry.members = [...entry.members, { name, paneId: pane }];
+        await this.renameGroupTab(entry);
+        return { id: pane, name, cwd, tabId: entry.tabId, group };
+    }
+    async run(slot, cmd) {
+        const pane = await this.paneId(slot);
+        const r = await this.herdr(`pane run ${shq(pane)} ${shq(cmd)}`, slot.cwd);
+        if (r.code !== 0)
+            throw new Error(`herdr pane run failed: ${r.stderr || r.stdout}`);
+    }
+    async waitOutput(slot, pattern, timeoutMs, opts) {
+        const pane = await this.paneId(slot);
+        const r = await this.herdr(`wait output ${shq(pane)} --match ${shq(pattern)}${opts?.regex ? " --regex" : ""} --timeout ${Math.floor(timeoutMs)}`, slot.cwd, timeoutMs + 15_000);
+        return r.code === 0 && !r.stdout.includes('"error"'); // dead pane: exit 0 + error json (herdr bite)
+    }
+    async waitAgentStatus(slot, status, timeoutMs) {
+        const pane = await this.paneId(slot);
+        const r = await this.herdr(`wait agent-status ${shq(pane)} --status ${shq(status)} --timeout ${Math.floor(timeoutMs)}`, slot.cwd, timeoutMs + 15_000);
+        return r.code === 0 && !r.stdout.includes('"error"');
+    }
+    async status(slot) {
+        return this.statusByName(slot.name);
+    }
+    // shared by status() and the VIS-13 blocked glyph (renameGroupTab): resolve the live agent_status
+    // by durable name; "unknown" on any failure (dead pane, unparseable json) — never throws.
+    async statusByName(name) {
+        const r = await this.herdr(`agent get ${shq(name)}`);
+        try {
+            const s = JSON.parse(r.stdout).result?.agent?.agent_status;
+            return typeof s === "string" ? s : "unknown";
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    async read(slot, lines) {
+        const pane = await this.paneId(slot);
+        const r = await this.herdr(`pane read ${shq(pane)} --source recent-unwrapped --lines ${lines}`, slot.cwd);
+        return r.stdout;
+    }
+    // v1.22 T5 / OBS-19: raw keystroke into the pane TUI (trust-dialog auto-answer). Resolves the pane
+    // id fresh like every other pane-addressed call (ids compact). Fail closed on nonzero herdr exit.
+    async sendKey(slot, key) {
+        const pane = await this.paneId(slot);
+        const r = await this.herdr(`pane send-keys ${shq(pane)} ${shq(key)}`, slot.cwd);
+        if (r.code !== 0)
+            throw new Error(`herdr pane send-keys failed: ${r.stderr || r.stdout}`);
+    }
+    async notify(msg, opts) {
+        if (opts?.tier === "routine")
+            return;
+        await this.herdr(`notification show ${shq(msg)} --sound ${opts?.tier === "attention" ? "request" : opts?.sound ?? "request"}`);
+    }
+    async close(slot) {
+        if (slot.group && this.groups.has(slot.group)) {
+            return this.serial(() => this.closeGrouped(slot));
+        }
+        if (slot.tabId) {
+            await this.herdr(`tab close ${shq(slot.tabId)}`); // reaps the slot's whole tab, best-effort
+            return;
+        }
+        const pane = await this.paneId(slot);
+        await this.herdr(`pane close ${shq(pane)}`); // best-effort
+    }
+    // D-08 ref-counted teardown, PER GENERATION (VIS-09 item 2): pane close per member; a generation's
+    // tab closes only when ITS OWN last member leaves; the group entry dies when all generations are gone.
+    // C2's "resolve the newest LIVE member" rule applies per generation — members[] holds only live members.
+    async closeGrouped(slot) {
+        const state = this.groups.get(slot.group);
+        if (!state)
+            return; // group already torn down — its tabs are gone
+        // find THIS member's generation by tab id: each overflow tab closes when its own last member leaves
+        const gen = state.generations.find((g) => g.tabId === slot.tabId);
+        if (!gen)
+            return; // generation already torn down — its tab is gone
+        const pane = await this.paneId(slot);
+        await this.herdr(`pane close ${shq(pane)}`); // best-effort
+        gen.members = gen.members.filter((m) => m.name !== slot.name);
+        await this.renameGroupTab(gen);
+        if (gen.members.length === 0) {
+            await this.herdr(`tab close ${shq(gen.tabId)}`); // refcount 0 → reap THIS generation's tab only
+            state.generations = state.generations.filter((g) => g.tabId !== gen.tabId);
+            if (state.generations.length === 0)
+                this.groups.delete(slot.group); // group dies when all generations gone
+        }
+    }
+    // T6 narrator: the run's single live surface — a drovr-created "watch" tab running the daemon's
+    // status command. Reuses the dedicated-tab slot path (label → tabSlot); close() reaps the whole tab
+    // at run end. One per run (the daemon calls this once). Failures propagate — the daemon swallows.
+    // T2: with a runId the pane is named canonically (drovr:watch:run:0:<runId>) so reconcile owns it;
+    // the legacy `narrator-watch-<pid>` shape survives for runId-less callers (canonicalizeLegacyName).
+    async narrator(cwd, command, runId) {
+        const name = runId ? formatOwnedName({ role: "watch", taskId: "run", attempt: 0, runId }) : `narrator-watch-${process.pid}`;
+        const s = await this.slot(cwd, name, { label: "watch" });
+        await this.run(s, command);
+        return s;
+    }
+    // OBS-17 T2 / v1.22b T1: close every drovr-owned pane that should not exist (superseded attempts,
+    // killed-daemon orphans, leftovers from OLDER runs) — in this run's workspace OR misplaced in any
+    // other one — then reap the tabs those closes emptied. Ownership is decided ONLY by parseOwnedName
+    // (drivers/types.ts panesToClose) — foreign names never become candidates, in any workspace; a pane
+    // this same run legitimately holds elsewhere is left alone (only run age marks a misplaced pane
+    // garbage). spareLiveLlm: same-run judge/review/consult panes have no journal row while live (their
+    // events land after the verdict is read), so mid-run sweeps spare them; boundary sweeps (start/
+    // resume/end) run with nothing in flight and take them too. Cosmetic by contract: every failure —
+    // herdr gone, pane vanished mid-sweep, unparseable listing — is swallowed; this method never throws.
+    async reconcile(desired, runId, opts) {
+        try {
+            if (!this.ws)
+                return;
+            const list = await this.herdr("agent list");
+            const agents = JSON.parse(list.stdout).result?.agents ?? [];
+            const toClose = panesToClose(agents.map((a) => ({ name: a.name, paneId: a.pane_id, tabId: a.tab_id, workspaceId: a.workspace_id })), desired, this.ws, runId, opts);
+            const touched = new Set();
+            for (const c of toClose) {
+                if (typeof c.tabId === "string")
+                    touched.add(c.tabId);
+                await this.herdr(`pane close ${shq(c.paneId)}`); // best-effort — a vanished pane is already reconciled
+            }
+            if (touched.size === 0)
+                return;
+            // a tab our closes emptied was ours by construction (a tab with operator panes still has panes)
+            const pl = await this.herdr("pane list");
+            const alive = new Set((JSON.parse(pl.stdout).result?.panes ?? []).map((p) => p.tab_id));
+            for (const tab of touched)
+                if (!alive.has(tab))
+                    await this.herdr(`tab close ${shq(tab)}`);
+        }
+        catch {
+            /* cosmetic — visibility hygiene never fails the run */
+        }
+    }
+    worktree(repo, branch, baseRef) {
+        return createWorktree(repo, branch, baseRef);
+    }
+}

package/dist/drivers/index.d.ts

@@ -0,0 +1,3 @@
+import type { DrovrConfig } from "../config/config.js";
+import type { ExecutorDriver } from "./types.js";
+export declare function pickDriver(cfg: DrovrConfig, override?: "auto" | "herdr" | "subprocess"): ExecutorDriver;

package/dist/drivers/index.js

@@ -0,0 +1,13 @@
+import { HerdrDriver } from "./herdr.js";
+import { SubprocessDriver } from "./subprocess.js";
+export function pickDriver(cfg, override) {
+    const want = override ?? cfg.driver;
+    // VIS-09 item 2: plumb the per-tab cap into the HerdrDriver — the driver takes it as a constructor
+    // param and never imports config (cfg is the only seam). Guaranteed present: DEFAULT_CONFIG seeds
+    // workersPerTab:3 and deepMerge overlays on top, so a missing overlay key still resolves.
+    if (want === "herdr")
+        return new HerdrDriver("herdr", cfg.visibility.workersPerTab);
+    if (want === "subprocess")
+        return new SubprocessDriver();
+    return HerdrDriver.available() ? new HerdrDriver("herdr", cfg.visibility.workersPerTab) : new SubprocessDriver();
+}

package/dist/drivers/subprocess.d.ts

@@ -0,0 +1,25 @@
+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"];
+/** Copy of env with herdr control-plane vars stripped. Daemon process.env is left alone. */
+export declare function sealHerdrEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Shell prefix that unsets herdr control vars in a pane/login shell (herdr seed + daemon setup). */
+export declare function herdrSealShellPrefix(): string;
+export declare class SubprocessDriver implements ExecutorDriver {
+    id: string;
+    interactive: boolean;
+    private slots;
+    private n;
+    slot(cwd: string, name: string): Promise<Slot>;
+    private state;
+    run(slot: Slot, cmd: string): Promise<void>;
+    waitOutput(slot: Slot, pattern: string, timeoutMs: number, opts?: {
+        regex?: boolean;
+    }): Promise<boolean>;
+    waitAgentStatus(slot: Slot, status: string, timeoutMs: number): Promise<boolean>;
+    status(_slot: Slot): Promise<string>;
+    read(slot: Slot, lines: number): Promise<string>;
+    notify(msg: string, _opts?: NotifyOpts): Promise<void>;
+    close(slot: Slot): Promise<void>;
+    worktree(repo: string, branch: string, baseRef: string): Promise<string>;
+}

package/dist/drivers/subprocess.js

@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { createWorktree } from "../run/git.js";
+// HARD-03: cap retained worker output so a chatty worker can't grow drovr's heap unbounded.
+// 2MB is safe against BOTH consumers: the largest read() call site asks for 1000 lines
+// (daemon.ts:217/247), and every marker (DROVR_RESULT, DROVR_EXIT_<nonce>) is emitted at the
+// END of output — a trailer would only be evicted if >2MB arrived AFTER it inside one 200ms
+// 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"];
+/** Copy of env with herdr control-plane vars stripped. Daemon process.env is left alone. */
+export function sealHerdrEnv(env = process.env) {
+    const out = { ...env };
+    for (const k of HERDR_CONTROL_VARS)
+        delete out[k];
+    return out;
+}
+/** Shell prefix that unsets herdr control vars in a pane/login shell (herdr seed + daemon setup). */
+export function herdrSealShellPrefix() {
+    return HERDR_CONTROL_VARS.map((k) => `unset ${k}`).join("; ") + "; ";
+}
+export class SubprocessDriver {
+    id = "subprocess";
+    interactive = false; // no pane, no operator — interactive workers force print here
+    // OBS-17 T2: no `reconcile` — there are no panes/tabs to sweep; the daemon's optional-chain
+    // call is a no-op here by construction, so the oracle suite runs byte-identical.
+    slots = new Map();
+    n = 0;
+    async slot(cwd, name) {
+        const id = `sp-${++this.n}`;
+        this.slots.set(id, { buf: "", exited: false });
+        return { id, name, cwd };
+    }
+    state(slot) {
+        const s = this.slots.get(slot.id);
+        if (!s)
+            throw new Error(`unknown slot ${slot.id}`);
+        return s;
+    }
+    async run(slot, cmd) {
+        const s = this.state(slot);
+        // HARD-05: interactive=false — no operator, so an open stdin pipe is a promise drovr 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.
+        const p = spawn("bash", ["-lc", cmd], {
+            cwd: slot.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: sealHerdrEnv(process.env),
+        });
+        s.proc = p;
+        p.stdout.on("data", (d) => (s.buf = (s.buf + d).slice(-MAX_BUF)));
+        p.stderr.on("data", (d) => (s.buf = (s.buf + d).slice(-MAX_BUF)));
+        p.on("close", () => (s.exited = true));
+        p.on("error", (e) => { s.buf = (s.buf + `\n[drovr subprocess error] ${e}\n`).slice(-MAX_BUF); s.exited = true; });
+    }
+    async waitOutput(slot, pattern, timeoutMs, opts) {
+        const s = this.state(slot);
+        const re = opts?.regex ? new RegExp(pattern) : null; // compile once, not per 200ms poll
+        const hit = re ? (b) => re.test(b) : (b) => b.includes(pattern);
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (hit(s.buf))
+                return true;
+            await new Promise((r) => setTimeout(r, 200)); // ponytail: 200ms poll; herdr driver has real event waits
+        }
+        return hit(s.buf);
+    }
+    async waitAgentStatus(slot, status, timeoutMs) {
+        if (status !== "done")
+            return false; // subprocess knows only process-exit
+        const s = this.state(slot);
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (s.exited)
+                return true;
+            await new Promise((r) => setTimeout(r, 200));
+        }
+        return s.exited;
+    }
+    async status(_slot) {
+        return "unknown"; // no screen to scrape; never reports blocked
+    }
+    async read(slot, lines) {
+        return this.state(slot).buf.split("\n").slice(-lines).join("\n");
+    }
+    async notify(msg, _opts) {
+        if (_opts?.tier === "routine")
+            return;
+        console.log(`[drovr] ${msg}`);
+    }
+    async close(slot) {
+        const s = this.slots.get(slot.id);
+        if (s?.proc && !s.exited)
+            s.proc.kill("SIGKILL");
+        this.slots.delete(slot.id);
+    }
+    worktree(repo, branch, baseRef) {
+        return createWorktree(repo, branch, baseRef);
+    }
+}

package/dist/drivers/types.d.ts

@@ -0,0 +1,61 @@
+export interface Slot {
+    id: string;
+    name: string;
+    cwd: string;
+    tabId?: string;
+    group?: string;
+}
+export type NotifyTier = "routine" | "attention";
+export interface NotifyOpts {
+    tier?: NotifyTier;
+    sound?: "none" | "done" | "request";
+}
+export interface SlotOpts {
+    group?: string;
+    label?: string;
+    owned?: OwnedName;
+}
+export declare const OWNED_ROLES: readonly ["worker", "judge", "review", "consult", "watch", "other"];
+export type OwnedRole = (typeof OWNED_ROLES)[number];
+export interface OwnedName {
+    role: OwnedRole;
+    taskId: string;
+    attempt: number;
+    runId: string;
+}
+export declare function formatOwnedName(o: OwnedName): string;
+export declare function parseOwnedName(name: string): OwnedName | null;
+export declare function isForeignName(name: string): boolean;
+export interface FleetAgent {
+    name?: string;
+    paneId?: string;
+    tabId?: string;
+    workspaceId?: string;
+}
+export declare function panesToClose(agents: FleetAgent[], desired: Set<string>, ws: string, runId: string, opts?: {
+    spareLiveLlm?: boolean;
+}): {
+    paneId: string;
+    tabId?: string;
+}[];
+export declare function canonicalizeLegacyName(name: string, runId: string): OwnedName;
+export interface ExecutorDriver {
+    id: string;
+    interactive: boolean;
+    slot(cwd: string, name: string, opts?: SlotOpts): Promise<Slot>;
+    run(slot: Slot, cmd: string): Promise<void>;
+    waitOutput(slot: Slot, pattern: string, timeoutMs: number, opts?: {
+        regex?: boolean;
+    }): Promise<boolean>;
+    waitAgentStatus(slot: Slot, status: string, timeoutMs: number): Promise<boolean>;
+    status(slot: Slot): Promise<string>;
+    read(slot: Slot, lines: number): Promise<string>;
+    sendKey?(slot: Slot, key: string): Promise<void>;
+    notify(msg: string, opts?: NotifyOpts): Promise<void>;
+    close(slot: Slot): Promise<void>;
+    worktree(repo: string, branch: string, baseRef: string): Promise<string>;
+    narrator?: (cwd: string, command: string, runId?: string) => Promise<Slot>;
+    reconcile?: (desired: Set<string>, runId: string, opts?: {
+        spareLiveLlm?: boolean;
+    }) => Promise<void>;
+}