@oisin-ee/pi-dogsled 0.15.0 → 0.16.0

package/README.md

@@ -11,13 +11,13 @@ Install the binary on each Herdr host. Use the same release tag in each command.
 Binary:
 
 ```sh
-mise use github:oisin-ee/dogsled@v0.15.0
+mise use github:oisin-ee/dogsled@v0.16.0
 ```
 
 Pi (extension, tools, and skill), from npm or as part of `@oisin-ee/oisinpi`:
 
 ```sh
-pi install npm:@oisin-ee/pi-dogsled@0.15.0
+pi install npm:@oisin-ee/pi-dogsled@0.16.0
 ```
 
 At session start the extension compares its version with `dogsled --version` and warns when they differ.
@@ -25,14 +25,14 @@ At session start the extension compares its version with `dogsled --version` and
 Claude Code (hooks, tools, and skill):
 
 ```sh
-claude plugin marketplace add oisin-ee/dogsled#v0.15.0
+claude plugin marketplace add oisin-ee/dogsled#v0.16.0
 claude plugin install dogsled@dogsled
 ```
 
 Codex (hooks, tools, and skill):
 
 ```sh
-codex plugin marketplace add oisin-ee/dogsled --ref v0.15.0
+codex plugin marketplace add oisin-ee/dogsled --ref v0.16.0
 codex plugin add dogsled@dogsled
 ```
 
@@ -42,7 +42,7 @@ The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#code
 Herdr (status-board popup):
 
 ```sh
-herdr plugin install oisin-ee/dogsled --ref v0.15.0 --yes
+herdr plugin install oisin-ee/dogsled --ref v0.16.0 --yes
 ```
 
 Harness plugins use the binary on `PATH`. They do not install it or start host services.
@@ -87,8 +87,10 @@ dogsled items --owner "$HERDR_PANE_ID" --json
 dogsled cancel TICKET
 ```
 
-Jobs use a new tab in the caller's workspace. With `--branch`, an agent uses the pane of the worktree's new Herdr workspace.
-Remote work uses a workspace with the same name as the caller's workspace, creating it when absent.
+With `--branch`, an agent uses the pane of the worktree's new Herdr workspace.
+Other work in a repository opens a new tab where that repository is shown: the workspace of its worktree, else the main checkout's workspace.
+When no workspace shows the repository, dogsled opens a new workspace for it.
+Work outside any repository uses a new tab in the caller's workspace. On a remote host, that is the workspace with the caller's workspace name, created when absent.
 Without a branch, a remote non-repository `--cwd` must exist there.
 Repository directories map to the same path relative to home. A linked-worktree caller needs `--branch` to preserve its branch remotely.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-dogsled",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Pi extension for dogsled: the board, the /dogsled panel, the inbox reader, and the dogsled tools. Needs the dogsled binary of the same version.",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,7 @@
     "orchestration"
   ],
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -44,12 +44,12 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@earendil-works/pi-tui": "^1.3.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.4",
-    "@earendil-works/pi-tui": "1.0.4",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
     "@types/node": "26.6.4",
     "typescript": "7.0.2"
   }

package/pi/index.ts

@@ -3,6 +3,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Box, Text, Key } from "@earendil-works/pi-tui";
 import { type Board, clean, parseBoard } from "./board.ts";
 import { WorkTodo } from "./work-todo.ts";
+import { UnitBridge } from "./unit-bridge.ts";
 import { workBoard, workText, type WorkState } from "./work.ts";
 import { type Details, InboxReader, MESSAGE_TYPE } from "./inbox.ts";
 import { openPanel } from "./panel.ts";
@@ -46,6 +47,9 @@ export default function dogsled(pi: ExtensionAPI) {
 	}
 
 	const inbox = new InboxReader(pi, exec);
+	const units = new UnitBridge(pi, binary);
+	pi.on("tool_call", (event, ctx) => units.call(event, ctx));
+	pi.on("tool_execution_end", (event, ctx) => units.ended(event.toolCallId, ctx));
 
 	pi.registerMessageRenderer<Details>(MESSAGE_TYPE, (message, { expanded, outputPad }, theme) => {
 		const records = message.details?.records ?? [];
@@ -168,6 +172,7 @@ export default function dogsled(pi: ExtensionAPI) {
 		const current = generation;
 		refresh = (async () => {
 			await inbox.drain(ctx);
+			try { await units.ready(ctx); await units.drain(ctx); } catch (error) { ctx.ui.notify(`Dogsled settlement delivery pending: ${String(error)}`, "warning"); }
 			if (ctx.mode !== "tui") return;
 			try {
 				const next = parseBoard(JSON.parse(await exec(["board", "--json"])));
@@ -192,7 +197,8 @@ export default function dogsled(pi: ExtensionAPI) {
 		return refresh;
 	}
 
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
+		units.start(event.reason);
 		if (ctx.mode === "tui") ctx.ui.setWidget("dogsled", undefined);
 		requestWorkRender = undefined;
 		workPanel?.dispose();
@@ -222,6 +228,7 @@ export default function dogsled(pi: ExtensionAPI) {
 		await update(ctx);
 	});
 	pi.on("session_shutdown", (_event, ctx) => {
+		units.stop();
 		workPanel?.dispose();
 		generation++;
 		workAbort?.abort();
@@ -239,7 +246,10 @@ export default function dogsled(pi: ExtensionAPI) {
 	});
 	// A delivered message is in the transcript once Pi ends it: only then is it acknowledged.
 	pi.on("message_end", async event => { await inbox.ended(event.message); });
-	pi.on("agent_settled", () => { inbox.settled(); });
+	pi.on("agent_settled", async (_event, ctx) => {
+		inbox.settled();
+		try { await units.settled(ctx); } catch (error) { ctx.ui.notify(`Dogsled unit acknowledgement pending: ${String(error)}`, "warning"); }
+	});
 	pi.on("agent_before_settle", async event => {
 		if (!owner || event.outcome !== "completed" || !event.context.canContinue || event.continue) return;
 		// The Rust gate owns selection and durable deduplication across all harnesses.
@@ -251,7 +261,9 @@ export default function dogsled(pi: ExtensionAPI) {
 			continue: true,
 		};
 	});
-	pi.on("before_agent_start", async (event) => {
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!units.guard(ctx)) return;
+		try { await units.ready(ctx); } catch (error) { ctx.ui.notify(`Dogsled preparation recovery pending: ${String(error)}`, "warning"); }
 		// Context is optional, including when the binary is absent or fails.
 		try {
 			const result = await pi.exec(binary, ["hook", "context", "--harness", "pi"], { timeout: 6_000 });

package/pi/unit-bridge.ts

@@ -0,0 +1,174 @@
+import type { ExtensionAPI, ExtensionContext, ToolCallEvent, ToolCallEventResult, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import { acquire, execution, prepared, record, reference, repositoryIdentity, sameExecution, sameRef, unitInput, unwrap, type Execution, type Prepared, type UnitRef } from "./unit-protocol.ts";
+import { UnitWorker, type UnitExec } from "./unit-worker.ts";
+
+interface Invocation { origin: UnitRef; execution?: Execution; cwd: string; prepared?: Prepared; ended: boolean }
+const SPAWN = "mcp__dogsled__spawn";
+
+/** Execution bookkeeping stays in Dogsled; the task provider owns all task state. */
+export class UnitBridge {
+	private readonly calls = new Map<string, Invocation>();
+	private epoch = 0;
+	private draining: Promise<void> | undefined;
+	private recovery: Promise<void> | undefined;
+	private recovered = false;
+	private readonly worker: UnitWorker;
+	private readonly exec: UnitExec;
+	private readonly pi: Pick<ExtensionAPI, "events" | "exec" | "getFlag" | "registerFlag">;
+	constructor(pi: Pick<ExtensionAPI, "events" | "exec" | "getFlag" | "registerFlag">, binary: string) {
+		this.pi = pi;
+		this.exec = async (args, cwd) => {
+			const result = await pi.exec(binary, args, cwd === undefined ? undefined : { cwd });
+			if (result.code !== 0) throw new Error(`dogsled ${args.slice(0, 2).join(" ")} failed: ${result.stderr.trim() || result.stdout.trim() || result.code}`);
+			return JSON.parse(result.stdout);
+		};
+		this.worker = new UnitWorker(pi, this.exec);
+	}
+	start(reason: SessionStartEvent["reason"] = "startup"): void { this.epoch++; this.recovered = false; this.worker.start(reason); }
+	stop(): void { this.epoch++; }
+	guard(ctx: ExtensionContext): boolean { return this.worker.guard(ctx); }
+
+	/** Startup handlers have completed before this boundary; no registration-order race. */
+	ready(ctx: ExtensionContext): Promise<void> {
+		if (this.recovered || !acquire(this.pi.events)) return Promise.resolve();
+		if (this.recovery) return this.recovery;
+		const epoch = this.epoch;
+		this.recovery = this.resume(ctx).then(() => { if (epoch === this.epoch) this.recovered = true; }).finally(() => { this.recovery = undefined; });
+		return this.recovery;
+	}
+
+	/** A completed runtime startup establishes that untracked prior invocations cannot execute here. */
+	async resume(ctx: ExtensionContext): Promise<void> {
+		if (!acquire(this.pi.events)) return;
+		const epoch = this.epoch, session = ctx.sessionManager.getSessionId();
+		const pending = await this.exec(["unit", "prepared"], ctx.cwd);
+		if (!Array.isArray(pending)) throw new Error("LAUNCH_UNRESOLVED: prepared listing returned no list");
+		for (const item of pending) {
+			this.current(epoch, session, ctx);
+			if (!record(item) || !execution(item.execution) || !reference(item.origin) || typeof item.toolCallId !== "string") throw new Error("LAUNCH_UNRESOLVED: invalid preparation identity");
+			if (item.origin.sessionId !== session) continue;
+			const executionRef = item.execution, origin = item.origin;
+			if ([...this.calls.values()].some(call => !call.ended && sameRef(call.origin, origin))) continue;
+			await this.exec(["unit", "abandon-prepared", "--input", JSON.stringify({ execution: executionRef })], ctx.cwd);
+		}
+		await this.drain(ctx);
+	}
+
+	async call(event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallEventResult | undefined> {
+		if (event.toolName !== SPAWN) return;
+		const input: unknown = event.input;
+		if (!record(input)) return { block: true, reason: "REQUEST_CONFLICT: spawn input must be an object" };
+		try {
+			if ("preparedUnit" in input) {
+				const owned = this.calls.get(event.toolCallId)?.prepared;
+				if (!owned || Object.keys(input).length !== 1 || JSON.stringify(owned) !== JSON.stringify(input.preparedUnit)) {
+					throw new Error("REQUEST_CONFLICT: preparedUnit is reserved for this invocation's mechanical handoff");
+				}
+				return;
+			}
+			if (!("unit" in input)) return;
+			const request = unitInput(input), epoch = this.epoch, session = ctx.sessionManager.getSessionId();
+			await this.ready(ctx);
+			this.current(epoch, session, ctx);
+			const provider = acquire(this.pi.events);
+			if (!provider) throw new Error("PROVIDER_UNAVAILABLE: pi-todo capability is unavailable or ambiguous");
+			const contract = unwrap(provider.inspect(request.id));
+			if (!record(contract) || !reference(contract.ref) || !record(contract.scope) || typeof contract.scope.repositoryId !== "string") {
+				throw new Error("PROVIDER_UNAVAILABLE: invalid inspected contract");
+			}
+			if (contract.ref.sessionId !== session) throw new Error("STALE_ORIGIN: task belongs to another session");
+			const origin = await this.pi.exec("git", ["remote", "get-url", "origin"], { cwd: ctx.cwd });
+			if (origin.code !== 0 || repositoryIdentity(origin.stdout) !== contract.scope.repositoryId) throw new Error("REQUEST_CONFLICT: checkout origin differs from repositoryId");
+			this.current(epoch, session, ctx);
+			// Retain the origin before I/O: prepare may persist while its response is lost.
+			const invocation: Invocation = { origin: contract.ref, cwd: ctx.cwd, ended: false };
+			this.calls.set(event.toolCallId, invocation);
+			const result = await this.exec(["unit", "prepare", "--input", JSON.stringify({ origin: contract.ref, placement: request.placement }), "--tool-call-id", event.toolCallId], ctx.cwd);
+			if (!execution(result)) throw new Error("LAUNCH_UNRESOLVED: prepare returned invalid execution");
+			invocation.execution = result;
+			this.current(epoch, session, ctx);
+			// Reacquire after I/O so shutdown and ownership changes cannot revive old authority.
+			const current = acquire(this.pi.events);
+			if (!current) throw new Error("PROVIDER_UNAVAILABLE: task provider disappeared before claim");
+			const claim = unwrap(current.claim({ expected: contract.ref, execution: result }));
+			const enriched = record(claim) ? { execution: result, binding: claim.binding, exported: claim.exported } : null;
+			if (!prepared(enriched) || !sameRef(enriched.binding.contract, contract.ref) || !sameExecution(enriched.execution, result)) throw new Error("PROVIDER_UNAVAILABLE: claim returned mismatched export");
+			invocation.prepared = enriched;
+			for (const key of Object.keys(input)) delete input[key];
+			input.preparedUnit = enriched;
+			return;
+		} catch (error) {
+			// This hook never committed. Its own failure proves this invocation did not launch.
+			const invocation = this.calls.get(event.toolCallId);
+			if (invocation?.execution) { invocation.ended = true; await this.recover(event.toolCallId, invocation, ctx); }
+			return { block: true, reason: String(error) };
+		}
+	}
+
+	private current(epoch: number, session: string, ctx: ExtensionContext): void {
+		if (epoch !== this.epoch || session !== ctx.sessionManager.getSessionId() || ctx.signal?.aborted) throw new Error("STALE_ORIGIN: session changed or invocation aborted during handoff");
+	}
+	async ended(id: string, ctx: ExtensionContext): Promise<void> {
+		const invocation = this.calls.get(id);
+		if (!invocation) return;
+		invocation.ended = true;
+		await this.recover(id, invocation, ctx);
+	}
+	private async recover(id: string, invocation: Invocation, ctx: ExtensionContext): Promise<void> {
+		try {
+			if (!invocation.ended) return;
+			if ([...this.calls.values()].some(other => other !== invocation && !other.ended && sameRef(other.origin, invocation.origin))) return;
+			if (!invocation.execution) {
+				const pending = await this.exec(["unit", "prepared"], invocation.cwd);
+				if (!Array.isArray(pending)) throw new Error("LAUNCH_UNRESOLVED: invalid prepared listing");
+				for (const item of pending) {
+					if (!record(item) || !execution(item.execution) || !reference(item.origin) || typeof item.toolCallId !== "string") throw new Error("LAUNCH_UNRESOLVED: invalid preparation identity");
+					// Prepare deduplicates by full origin and retains the first invocation ID on retries.
+					if (sameRef(item.origin, invocation.origin)) invocation.execution = item.execution;
+				}
+				if (!invocation.execution) { this.calls.delete(id); await this.drain(ctx); return; }
+			}
+			const state = await this.exec(["unit", "observe", "--input", JSON.stringify({ execution: invocation.execution })], invocation.cwd);
+			if (!record(state) || !execution(state.execution) || !sameExecution(state.execution, invocation.execution)) throw new Error("LAUNCH_UNRESOLVED: invalid observation");
+			if (state.phase === "prepared" && invocation.ended) {
+				await this.exec(["unit", "abandon-prepared", "--input", JSON.stringify({ execution: invocation.execution })], invocation.cwd);
+			} else if (state.phase === "prepared") return;
+			this.calls.delete(id);
+			await this.drain(ctx);
+		} catch (error) {
+			// Unknown outcome keeps the durable claim and in-memory recovery intent.
+			ctx.ui.notify(`Dogsled unit recovery pending: ${String(error)}`, "warning");
+		}
+	}
+
+	/** Provider settlement acknowledgements are independent of inbox text acknowledgements. */
+	drain(ctx: ExtensionContext): Promise<void> {
+		if (this.draining) return this.draining;
+		const epoch = this.epoch;
+		this.draining = (async () => {
+			if (!acquire(this.pi.events)) return;
+			const pending = await this.exec(["unit", "settlements"], ctx.cwd);
+			if (!Array.isArray(pending)) throw new Error("LAUNCH_UNRESOLVED: settlements returned no list");
+			for (const event of pending) {
+				if (epoch !== this.epoch) return;
+				if (!record(event) || typeof event.eventId !== "string") throw new Error("LAUNCH_UNRESOLVED: invalid settlement identity");
+				const owner = record(event.binding) ? event.binding.execution : event.execution;
+				if (!execution(owner)) throw new Error("LAUNCH_UNRESOLVED: missing settlement execution");
+				const provider = acquire(this.pi.events);
+				if (!provider) return;
+				const result = provider.settle(event);
+				if (!result.ok) continue; // Wrong branch or revision stays pending in Dogsled.
+				if (!record(result.value) || typeof result.value.applied !== "boolean") throw new Error("PROVIDER_UNAVAILABLE: invalid settlement acknowledgement");
+				await this.exec(["unit", "ack-settlement", "--input", JSON.stringify({ execution: owner, eventId: event.eventId })], ctx.cwd);
+			}
+		})().finally(() => { this.draining = undefined; });
+		return this.draining;
+	}
+	async settled(ctx: ExtensionContext): Promise<void> {
+		for (const [id, invocation] of this.calls) {
+			if (invocation.ended) await this.recover(id, invocation, ctx);
+		}
+		await this.worker.settled(ctx);
+		await this.drain(ctx);
+	}
+}

package/pi/unit-protocol.ts

@@ -0,0 +1,85 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export interface UnitRef { sessionId: string; unitId: string; revision: number; contractEntryId: string }
+export interface Execution { executor: string; ownerId: string; requestId: string }
+export interface Binding { contract: UnitRef; execution: Execution; exportDigest: string }
+export interface Exported { version: number; provider: string; contract: { ref: UnitRef; scope: { repositoryId: string } }; digest: string; [key: string]: unknown }
+export interface Prepared { execution: Execution; binding: Binding; exported: Exported }
+export interface Receipt { version: number; execution: Execution; unitRef: UnitRef; digest: string; localSessionId: string; seal: { entryId: string; disposition: "completed" | "abandoned" } | null }
+export type Result = { ok: true; value: unknown } | { ok: false; error: { code: string; message: string } };
+export interface TaskProvider {
+	inspect(id: string): Result;
+	claim(input: { expected: UnitRef; execution: Execution }): Result;
+	settle(input: unknown): Result;
+	imported(): Result;
+}
+export type Placement = { host?: string; branch?: string; base?: string };
+export function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function text(value: unknown): value is string { return typeof value === "string" && value.trim().length > 0; }
+export function reference(value: unknown): value is UnitRef {
+	return record(value) && text(value.sessionId) && text(value.unitId) && Number.isSafeInteger(value.revision) && Number(value.revision) > 0 && text(value.contractEntryId);
+}
+export function execution(value: unknown): value is Execution {
+	return record(value) && value.executor === "dogsled" && text(value.ownerId) && text(value.requestId);
+}
+export function sameRef(a: UnitRef, b: UnitRef): boolean {
+	return a.sessionId === b.sessionId && a.unitId === b.unitId && a.revision === b.revision && a.contractEntryId === b.contractEntryId;
+}
+export function sameExecution(a: Execution, b: Execution): boolean {
+	return a.executor === b.executor && a.ownerId === b.ownerId && a.requestId === b.requestId;
+}
+export function binding(value: unknown): value is Binding {
+	return record(value) && reference(value.contract) && execution(value.execution) && typeof value.exportDigest === "string" && /^[a-f0-9]{64}$/.test(value.exportDigest);
+}
+export function exported(value: unknown): value is Exported {
+	return record(value) && value.version === 1 && value.provider === "pi-todo" && record(value.contract)
+		&& reference(value.contract.ref) && record(value.contract.scope) && text(value.contract.scope.repositoryId)
+		&& typeof value.digest === "string" && /^[a-f0-9]{64}$/.test(value.digest);
+}
+export function prepared(value: unknown): value is Prepared {
+	return record(value) && execution(value.execution) && binding(value.binding) && exported(value.exported)
+		&& sameExecution(value.execution, value.binding.execution) && sameRef(value.binding.contract, value.exported.contract.ref)
+		&& value.binding.exportDigest === value.exported.digest;
+}
+export function receipt(value: unknown): value is Receipt {
+	return record(value) && value.version === 1 && execution(value.execution) && reference(value.unitRef)
+		&& typeof value.digest === "string" && /^[a-f0-9]{64}$/.test(value.digest) && text(value.localSessionId)
+		&& (value.seal === null || (record(value.seal) && text(value.seal.entryId) && ["completed", "abandoned"].includes(String(value.seal.disposition))));
+}
+function provider(value: unknown): value is TaskProvider {
+	return record(value) && ["inspect", "claim", "settle", "imported"].every(key => typeof value[key] === "function");
+}
+export function acquire(events: ExtensionAPI["events"]): TaskProvider | undefined {
+	const replies: unknown[] = [];
+	events.emit("oisin.tasks.acquire.v1", { version: 1, reply: (value: unknown) => { replies.push(value); } });
+	if (replies.length !== 1 || !provider(replies[0])) return undefined;
+	return replies[0];
+}
+export function unwrap(result: Result): unknown {
+	if (!record(result) || typeof result.ok !== "boolean") throw new Error("PROVIDER_UNAVAILABLE: invalid capability result");
+	if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
+	return result.value;
+}
+export function unitInput(input: Record<string, unknown>): { id: string; placement: Placement } {
+	if (Object.keys(input).some(key => !["unit", "host", "branch", "base"].includes(key)) || !record(input.unit)
+		|| Object.keys(input.unit).length !== 1 || !text(input.unit.id)) throw new Error("REQUEST_CONFLICT: unit spawn cannot include a brief, profile, cwd, or prepared envelope");
+	const placement: Placement = {};
+	for (const key of ["host", "branch", "base"] as const) {
+		if (input[key] === undefined) continue;
+		if (!text(input[key])) throw new Error(`REQUEST_CONFLICT: ${key} must be a nonempty string`);
+		placement[key] = input[key];
+	}
+	if (placement.base && !placement.branch) throw new Error("REQUEST_CONFLICT: base requires branch");
+	return { id: input.unit.id, placement };
+}
+
+/** Clone transport is not repository identity. Keep path case; do not accept local paths. */
+export function repositoryIdentity(origin: string): string {
+	const value = origin.trim();
+	const scp = value.includes("://") ? null : /^(?:[^/@:\s]+@)?(?<host>[^/:\s]+):(?<path>[^\s]+)$/.exec(value);
+	const url = new URL(scp?.groups ? `ssh://${scp.groups["host"]}/${scp.groups["path"]}` : value);
+	const path = url.pathname.replace(/^\//, "").replace(/\/$/, "").replace(/\.git$/, "");
+	if (!["ssh:", "https:", "http:", "git:"].includes(url.protocol) || !url.hostname || !path || url.search || url.hash
+		|| path.split("/").some(part => !part || part === "." || part === "..")) throw new Error("REQUEST_CONFLICT: origin must identify a remote repository host/path");
+	return `${url.hostname.toLowerCase()}/${path}`;
+}

package/pi/unit-worker.ts

@@ -0,0 +1,93 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import { acquire, prepared, receipt, record, sameExecution, sameRef, unwrap, type Prepared, type Receipt } from "./unit-protocol.ts";
+
+/** Read transport correlation, not task semantics; pi-todo validates the actual contract. */
+function seedFile(path: string): Prepared {
+	const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	try {
+		const stat = fstatSync(fd);
+		if (!stat.isFile() || stat.size > 1_048_576) throw new Error("invalid seed artifact");
+		const bytes = readFileSync(fd);
+		if (bytes.length > 1_048_576) throw new Error("seed artifact too large");
+		const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+		if (!record(value) || value.version !== 1 || !prepared(value)) throw new Error("invalid seed correlation");
+		return value;
+	} finally { closeSync(fd); }
+}
+
+export type UnitExec = (args: string[], cwd?: string) => Promise<unknown>;
+
+/** The loaded guard enforces fresh-session startup, not resume-time compaction. */
+export class UnitWorker {
+	private seed: Prepared | undefined;
+	private failure: string | undefined;
+	private managed = false;
+	private reason: SessionStartEvent["reason"] = "startup";
+	private readonly pi: Pick<ExtensionAPI, "events" | "getFlag" | "registerFlag">;
+	private readonly exec: UnitExec;
+	constructor(pi: Pick<ExtensionAPI, "events" | "getFlag" | "registerFlag">, exec: UnitExec) {
+		this.pi = pi; this.exec = exec;
+		// Dogsled alone owns the launch flag and supplies its path over the event bus.
+		// Register it even without pi-todo so the loaded guard can reject missing import.
+		pi.registerFlag("todo-unit-file", { type: "string", description: "Executor-owned worker task seed" });
+		// Register during extension loading, before any session_start import handler.
+		pi.events.on("oisin.tasks.seed-source.v1", input => {
+			if (!record(input) || input.version !== 1 || typeof input.reply !== "function") return;
+			input.reply({ version: 1, path: pi.getFlag("todo-unit-file") ?? null });
+		});
+	}
+	start(reason: SessionStartEvent["reason"] = "startup"): void {
+		this.reason = reason;
+		this.seed = undefined;
+		this.failure = undefined;
+		const path = this.pi.getFlag("todo-unit-file");
+		this.managed = path !== undefined;
+		if (!this.managed) return;
+		try {
+			if (typeof path !== "string" || !path) throw new Error("missing seed path");
+			this.seed = seedFile(path);
+		} catch (error) { this.failure = String(error); }
+	}
+	private imported(ctx: ExtensionContext): Receipt | null {
+		const provider = acquire(this.pi.events);
+		if (!provider) {
+			if (this.managed) throw new Error("task provider unavailable");
+			return null;
+		}
+		const value = unwrap(provider.imported());
+		if (value === null && !this.managed) return null;
+		if (!receipt(value) || value.localSessionId !== ctx.sessionManager.getSessionId()
+			|| value.localSessionId !== value.execution.requestId) throw new Error("missing or mismatched import acknowledgement");
+		const recorded = this.reason === "reload" || this.reason === "resume"
+			|| ctx.sessionManager.getEntries().some(entry => entry.type === "message");
+		if (!recorded) {
+			if (!this.seed || this.failure) throw new Error(this.failure ?? "missing seed");
+			if (!sameExecution(value.execution, this.seed.execution) || !sameRef(value.unitRef, this.seed.binding.contract)
+				|| value.digest !== this.seed.binding.exportDigest) throw new Error("mismatched seed acknowledgement");
+		}
+		return value;
+	}
+	/** Called synchronously before any other before-agent-start await. */
+	guard(ctx: ExtensionContext): boolean {
+		try {
+			const imported = this.imported(ctx);
+			if (imported?.seal) throw new Error("worker execution is sealed");
+			return true;
+		} catch (error) {
+			ctx.abort();
+			ctx.ui.notify(`IMPORT_FAILED: ${String(error)}`, "error");
+			return false;
+		}
+	}
+	async settled(ctx: ExtensionContext): Promise<void> {
+		const imported = this.imported(ctx);
+		if (!imported?.seal) return;
+		const leaf = ctx.sessionManager.getLeafId();
+		if (!leaf) throw new Error("IMPORT_FAILED: sealed session has no final leaf");
+		await this.exec(["unit", "terminal-ack", "--input", JSON.stringify({
+			execution: imported.execution, unitRef: imported.unitRef, digest: imported.digest,
+			sealEntryId: imported.seal.entryId, sessionLeafId: leaf,
+		})], ctx.cwd);
+	}
+}