@afokapu/atdd-flow 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -1,15 +1,16 @@
 #!/usr/bin/env bun
 
 import { basename, resolve } from "node:path";
-import { init, initProject, spawn, bind, useApplication, attach, describe, checkpoint, migrate, openSeat, piExtensionPath } from "./seats";
+import { init, initProject, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
 import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
-import { required, values, words } from "./core";
+import { required, values, words, yaml } from "./core";
 import { addressBook } from "./address-book";
 import * as judgment from "./judgment";
 import * as reviews from "./reviews";
 import { status } from "./overview";
 import { multiplexer } from "./multiplexer";
+import * as cleanup from "./ephemeral-resources";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
 
@@ -24,6 +25,7 @@ Usage:
   atdd-flow bind <address> [--application <application>] --address <native-address> [--session <name>] [--agent <executable>] [--worktree <path>] [--wake host|native]
   atdd-flow attach <address> [--application <application>] [--wake host|native]
   atdd-flow pi extension-path
+  atdd-flow pi runtime launch <address> --pane <existing-herdr-pane> --herdr-session <session> [--resume] [--dry-run]
   atdd-flow application use <address> <application>
   atdd-flow multiplexer status|apply herdr [--session <name>]
   atdd-flow describe <address> --purpose <one-line responsibility>
@@ -39,6 +41,8 @@ Usage:
   atdd-flow task unblock <project> <task-id> --by <coordinator-address>
   atdd-flow task list <project> [--coordinator <address>] [--assignee <address>]
   atdd-flow task open <project> <task-id>
+  atdd-flow cleanup status <project>
+  atdd-flow cleanup checklist <project> <task-id>
   atdd-flow thread start --with <address,...> --subject <text> [--task <project/task-id>]
   atdd-flow thread add <thread-id> <address>
   atdd-flow thread open <thread-id>
@@ -82,7 +86,13 @@ async function main() {
     attach: () => attach(root, required(rest[0], "address"), rest.slice(1)),
     pi: async () => {
       if (rest[0] === "extension-path") return console.log(piExtensionPath());
-      throw new Error("Use `atdd-flow pi extension-path`.");
+      if (rest[0] === "runtime" && rest[1] === "launch") {
+        const plan = await launchPiRuntime(root, required(rest[2], "address"), rest.slice(3));
+        if (plan.dryRun) console.log(yaml.print(plan));
+        else console.log(`Launched Pi runtime for ${required(rest[2], "address")} with ${plan.candidate}.`);
+        return;
+      }
+      throw new Error("Use `pi extension-path` or `pi runtime launch <address> --pane <pane> --herdr-session <session> [--resume] [--dry-run]`.");
     },
     application: async () => {
       if (rest[0] === "use") return useApplication(root, required(rest[1], "address"), required(rest[2], "application"));
@@ -108,6 +118,12 @@ async function main() {
       if (subcommand === "open") return tasks.open(root, required(projectName, "project"), required(taskId, "task id"));
       throw new Error("Use `atdd-flow task add|assign|amend|import|start|prove|review|return|done|block|unblock|list|open`.");
     },
+    cleanup: async () => {
+      const [subcommand, projectName, taskId] = rest;
+      if (subcommand === "status") return console.log(Bun.YAML.stringify(await cleanup.coordinatorStatus(root, required(projectName, "project"))));
+      if (subcommand === "checklist") return console.log(await cleanup.checklist(root, { project: required(projectName, "project"), task: required(taskId, "task id") }));
+      throw new Error("Use `atdd-flow cleanup status <project>` or `atdd-flow cleanup checklist <project> <task-id>`.");
+    },
     thread: async () => {
       const [subcommand, ...tail] = rest;
       if (subcommand === "start") return startThread(root, tail);

package/src/core.ts

@@ -51,7 +51,19 @@ export type Project = {
 export type HerdrLocator = { session: string; pane: string };
 /** Strings are legacy native addresses; new Herdr bindings retain their session. */
 export type RuntimeAddress = string | HerdrLocator;
-export type Runtime = { application: string; addresses: Record<string, RuntimeAddress>; attached_at?: string; model?: string; wake?: "host" | "native" };
+export type Runtime = {
+  application: string;
+  addresses: Record<string, RuntimeAddress>;
+  attached_at?: string;
+  model?: string;
+  wake?: "host" | "native";
+  /** Exact Pi session used by the narrow Pi/Herdr launch command. */
+  pi_session?: string;
+  /** Exact durable JSONL path reported by Herdr for that Pi session. */
+  pi_session_path?: string;
+  /** Immutable, non-secret receipt for that selected launch. */
+  launch_receipt?: string;
+};
 
 export function runtimeAddress(application: string, value: RuntimeAddress, legacyHerdrSession?: string) {
   if (application !== "herdr" || typeof value === "string") return { address: value, ...(application === "herdr" && legacyHerdrSession ? { session: legacyHerdrSession } : {}) };

package/src/ephemeral-resources.ts

@@ -0,0 +1,236 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { atomicYaml, exists, now, readYaml, taskId } from "./core";
+
+export type InventoryKind = "fixture-directory" | "git-worktree" | "git-branch" | "process" | "port" | "herdr-workspace" | "github-preview";
+export type InventoryEntry = { kind: InventoryKind; locator: string };
+export type Parent = { project: string; task: string; pr?: string };
+export type Declaration = {
+  id: string;
+  owner: string;
+  purpose: string;
+  parent: Parent;
+  trigger: { merge?: boolean; close?: boolean; expiresAt?: string };
+  inventory: InventoryEntry[];
+  cleanupAssignee: string;
+  authorizedScope: "local" | "git" | "herdr" | "github";
+};
+type Status = "pending" | "ready" | "cancelled" | "received" | "failed" | "timeout" | "retained";
+type Record = {
+  schema: "atdd-workflow/ephemeral-resource/v1";
+  id: string;
+  declaration: Declaration;
+  cleanupTask: string;
+  status: Status;
+  updated_at: string;
+};
+type CleanupRecord = {
+  schema: "atdd-workflow/cleanup-record/v1";
+  id: string;
+  parent: Parent;
+  assignee: string;
+  status: Status;
+  updated_at: string;
+};
+type Audit = { schema: "atdd-workflow/ephemeral-resource-audit/v1"; event: string; immutable: true; at: string; detail?: string };
+
+const resourceRoot = (root: string) => join(root, ".atdd-flow", "ephemeral-resources");
+const resourceFile = (root: string, id: string) => join(resourceRoot(root), `${taskId(id)}.yaml`);
+const cleanupFile = (root: string, id: string) => join(resourceRoot(root), "cleanup", `${taskId(id)}.yaml`);
+const auditRoot = (root: string, id: string) => join(resourceRoot(root), "audit", taskId(id));
+const tombstoneFile = (root: string, id: string) => join(resourceRoot(root), "tombstones", `${taskId(id)}.yaml`);
+
+function required(value: unknown, name: string): asserts value {
+  if (value === undefined || value === null || value === "" || Array.isArray(value) && !value.length) throw new Error(`Declaration requires ${name}.`);
+}
+
+const scopeForKind: Record<InventoryKind, Declaration["authorizedScope"]> = {
+  "fixture-directory": "local",
+  "git-worktree": "git",
+  "git-branch": "git",
+  process: "local",
+  port: "local",
+  "herdr-workspace": "herdr",
+  "github-preview": "github",
+};
+
+function validate(value: Declaration) {
+  required(value?.id, "id");
+  taskId(value.id);
+  required(value.owner, "owner");
+  required(value.purpose, "purpose");
+  required(value.parent, "authoritative parent");
+  required(value.parent.project, "parent project");
+  required(value.parent.task, "parent task");
+  taskId(value.parent.task);
+  required(value.trigger, "expiry or trigger");
+  if (!value.trigger.merge && !value.trigger.close && !value.trigger.expiresAt) throw new Error("Declaration requires an expiry or trigger.");
+  required(value.inventory, "exact inventory");
+  required(value.cleanupAssignee, "cleanup assignee");
+  required(value.authorizedScope, "authorized scope");
+  if (!(["local", "git", "herdr", "github"] as string[]).includes(value.authorizedScope)) throw new Error("Declaration has an unsupported authorized scope.");
+  for (const entry of value.inventory) {
+    required(entry?.kind, "inventory kind");
+    required(entry.locator, "inventory locator");
+    if (!(["fixture-directory", "git-worktree", "git-branch", "process", "port", "herdr-workspace", "github-preview"] as string[]).includes(entry.kind)) {
+      throw new Error(`Declaration has unsupported inventory kind: ${entry.kind}.`);
+    }
+    if (scopeForKind[entry.kind] !== value.authorizedScope) {
+      throw new Error(`Declaration scope ${value.authorizedScope} is incompatible with ${entry.kind}; it requires ${scopeForKind[entry.kind]} scope.`);
+    }
+  }
+}
+
+async function read(root: string, id: string) {
+  return readYaml<Record>(resourceFile(root, id));
+}
+
+async function write(root: string, value: Record) {
+  value.updated_at = now();
+  await atomicYaml(resourceFile(root, value.id), value);
+  await atomicYaml(cleanupFile(root, value.id), {
+    schema: "atdd-workflow/cleanup-record/v1", id: value.cleanupTask, parent: value.declaration.parent,
+    assignee: value.declaration.cleanupAssignee, status: value.status, updated_at: value.updated_at,
+  } satisfies CleanupRecord);
+}
+
+/** Audit entries are write-once files; state records only point at that history. */
+async function appendAudit(root: string, id: string, event: string, detail?: string) {
+  const folder = auditRoot(root, id);
+  await mkdir(folder, { recursive: true });
+  // A collision-proof name keeps concurrent signal records write-once; do not
+  // derive a filename from a racy directory listing.
+  await atomicYaml(join(folder, `${now().replace(/[^0-9]/g, "")}-${randomUUID()}-${event}.yaml`), {
+    schema: "atdd-workflow/ephemeral-resource-audit/v1", event, immutable: true, at: now(), ...(detail ? { detail } : {}),
+  } satisfies Audit);
+}
+
+export async function declare(root: string, declaration: Declaration) {
+  validate(declaration);
+  if (await exists(resourceFile(root, declaration.id))) throw new Error(`Ephemeral resource ${declaration.id} is already declared.`);
+  const value: Record = {
+    schema: "atdd-workflow/ephemeral-resource/v1", id: declaration.id, declaration,
+    cleanupTask: `cleanup-${taskId(declaration.id)}`, status: "pending", updated_at: now(),
+  };
+  // Persist the resource and cleanup record before publishing the declaration audit.
+  await write(root, value);
+  await appendAudit(root, declaration.id, "declared");
+  return { id: value.id, cleanupTask: value.cleanupTask, status: value.status as "pending" };
+}
+
+export async function signal(root: string, id: string, event: "merged" | "closed" | "expired" | "cancelled") {
+  const value = await read(root, id);
+  if (value.status === "received" || value.status === "retained") return { status: value.status };
+  value.status = event === "cancelled" ? "cancelled" : "ready";
+  await write(root, value);
+  await appendAudit(root, id, event);
+  return { status: value.status as "ready" | "cancelled" };
+}
+
+function fixtureRefusal(root: string, declaration: Declaration, entry: InventoryEntry) {
+  if (entry.kind !== "fixture-directory" || declaration.authorizedScope !== "local") {
+    return `${entry.kind} cleanup requires a separately authorized typed adapter with verified scope, ownership, liveness, and Git safety attestations.`;
+  }
+  const fixtureRoot = resolve(root, ".atdd-flow", "fixtures");
+  const target = resolve(entry.locator);
+  const relation = relative(fixtureRoot, target);
+  if (!relation || relation.startsWith("..") || isAbsolute(relation)) {
+    return `Fixture target ${entry.locator} is outside the declared bounded fixture scope ${fixtureRoot}.`;
+  }
+}
+
+/**
+ * This delivery has no typed destructive adapter. It can execute only a
+ * declared local fixture below the Desk's bounded fixture root; all OS, git,
+ * process, Herdr, and GitHub targets fail closed before an executor is called.
+ * A future adapter must verify and immutably attest scope, ownership, liveness,
+ * and Git safety before it is allowed to extend this boundary. No daemon or GC.
+ */
+export async function execute(root: string, id: string, executor: (entry: InventoryEntry) => Promise<"removed" | "failed" | "timeout" | "cancelled">) {
+  const value = await read(root, id);
+  if (value.status === "received") return { status: "received" as const };
+  if (value.status === "retained") throw new Error(`Cleanup ${id} is retained and cannot be executed.`);
+  if (!(["ready", "cancelled"] as Status[]).includes(value.status)) throw new Error(`Cleanup ${id} is not ready for execution.`);
+  for (const entry of value.declaration.inventory) {
+    const reason = fixtureRefusal(root, value.declaration, entry);
+    if (reason) {
+      await appendAudit(root, id, "cleanup-refused", reason);
+      throw new Error(reason);
+    }
+  }
+  for (const entry of value.declaration.inventory) {
+    const outcome = await executor(entry);
+    if (outcome !== "removed") {
+      value.status = outcome;
+      await write(root, value);
+      await appendAudit(root, id, `cleanup-${outcome}`, entry.locator);
+      return { status: outcome };
+    }
+  }
+  value.status = "received";
+  await write(root, value);
+  await appendAudit(root, id, "cleanup-received");
+  return { status: "received" as const };
+}
+
+export async function receipt(root: string, id: string) {
+  const value = await read(root, id);
+  if (value.status !== "received") throw new Error(`Cleanup ${id} has no receipt; it is ${value.status}.`);
+  return { status: "received" as const };
+}
+
+export async function retain(root: string, id: string, decision: { by: string; reason: string }) {
+  required(decision?.by, "retained decision author");
+  required(decision?.reason, "retained decision reason");
+  const value = await read(root, id);
+  if (value.status === "received") throw new Error(`Cleanup ${id} already has a receipt.`);
+  value.status = "retained";
+  await write(root, value);
+  const tombstone = tombstoneFile(root, id);
+  if (!await exists(tombstone)) await atomicYaml(tombstone, {
+    schema: "atdd-workflow/ephemeral-resource-tombstone/v1", resource: id, immutable: true, retained_by: decision.by, reason: decision.reason, at: now(),
+  });
+  await appendAudit(root, id, "retained", `${decision.by}: ${decision.reason}`);
+  return { status: "retained" as const, tombstone };
+}
+
+export async function audit(root: string, id: string) {
+  const folder = auditRoot(root, id);
+  try {
+    return await Promise.all((await readdir(folder)).filter((file) => file.endsWith(".yaml")).sort().map((file) => readYaml<Audit>(join(folder, file))));
+  } catch { return []; }
+}
+
+async function matching(root: string, parent: Parent) {
+  try {
+    const files = (await readdir(resourceRoot(root))).filter((file) => file.endsWith(".yaml"));
+    const records = await Promise.all(files.map((file) => readYaml<Record>(join(resourceRoot(root), file))));
+    return records.filter((value) => value.declaration.parent.project === parent.project && value.declaration.parent.task === parent.task);
+  } catch { return []; }
+}
+
+async function assertSettled(root: string, parent: Parent) {
+  const pending = (await matching(root, parent)).filter((value) => !(["received", "retained"] as Status[]).includes(value.status));
+  if (pending.length) throw new Error(`Parent ${parent.project}/${parent.task} is held by cleanup receipt or retained decision: ${pending.map((value) => value.id).join(", ")}.`);
+}
+
+export const assertParentMayComplete = assertSettled;
+export const assertDependentsMayUnblock = assertSettled;
+
+export async function coordinatorStatus(root: string, project: string) {
+  // Coordinator status is project-wide, while completion gates match one parent task.
+  let all: Record[] = [];
+  try {
+    all = await Promise.all((await readdir(resourceRoot(root))).filter((file) => file.endsWith(".yaml")).map((file) => readYaml<Record>(join(resourceRoot(root), file))));
+  } catch { /* no declarations is a clean status */ }
+  return { pending: all.filter((value) => value.declaration.parent.project === project && !(["received", "retained"] as Status[]).includes(value.status)).map((value) => value.id).sort() };
+}
+
+export async function checklist(root: string, parent: Parent) {
+  const records = await matching(root, parent);
+  const pending = records.filter((value) => !(["received", "retained"] as Status[]).includes(value.status));
+  return pending.length
+    ? `Cleanup pending for ${parent.project}/${parent.task}: obtain cleanup receipt or retained-resource decision for ${pending.map((value) => value.id).join(", ")}.`
+    : `Cleanup checklist for ${parent.project}/${parent.task}: every declared resource has a cleanup receipt or retained-resource decision.`;
+}

package/src/seats.ts

@@ -1,13 +1,13 @@
 import { existsSync } from "node:fs";
-import { mkdir, readdir } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { discoverAddress, discoverHerdrLocator, notify } from "./adapters";
 import {
   type Checkpoint, type Desk, type ModelCandidate, type ModelPortfolio, type Project, type Role, type Runtime, type Seat,
   atomicYaml, canonicalAddress, desk, exists, fill, migrateDesk, modelPortfolio, now, paths, project, readYaml,
-  required, run, runtimeAddress, seat, words, yaml,
+  required, run, runOutput, runtimeAddress, seat, words, yaml,
 } from "./core";
-import { selectModel } from "./judgment";
+import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
 import { seatTasks } from "./tasks";
 
 const defaultRoles = (dynamicModels = true): Record<string, Role> => ({
@@ -92,7 +92,7 @@ export async function spawn(root: string, projectName: string, roleName: string,
   console.log(address);
 }
 
-export async function bind(root: string, address: string, args: string[], selectedModel?: string, wake?: Runtime["wake"]) {
+export async function bind(root: string, address: string, args: string[], selectedModel?: string, wake?: Runtime["wake"], piSession?: string, piSessionPath?: string, launchReceipt?: string) {
   const resolved = await canonicalAddress(root, address);
   const record = await seat(root, resolved);
   const config = await desk(root);
@@ -114,6 +114,9 @@ export async function bind(root: string, address: string, args: string[], select
     attached_at: now(),
     ...(selectedModel ? { model: selectedModel } : {}),
     ...(selectedWake ? { wake: selectedWake } : {}),
+    ...(piSession ? { pi_session: piSession } : {}),
+    ...(piSessionPath ? { pi_session_path: piSessionPath } : {}),
+    ...(launchReceipt ? { launch_receipt: launchReceipt } : {}),
   };
   // Legacy Desks use this field as the executable chosen by a later `launch`.
   // Keep it aligned when an existing seat is deliberately re-homed to Pi.
@@ -159,11 +162,11 @@ export function resolveModelCommand(config: Desk, candidate: ModelCandidate) {
   return { agent: resolveExecutable(config, candidate.executable), args: candidate.args ?? [] };
 }
 
-async function chooseLaunchModel(root: string, config: Desk, record: Seat, portfolio: ModelPortfolio) {
+async function chooseLaunchModel(root: string, config: Desk, record: Seat, portfolio: ModelPortfolio, select: (input: ModelSelectionInput) => Promise<ModelSelectionResponse> = selectModel) {
   const candidates = availableModelCandidates(config, portfolio);
   if (!candidates.length) throw new Error("No enabled model in models.yaml has an available executable.");
   const work = (await seatTasks(root, record.project, record.address)).filter((entry) => entry.task.status !== "done");
-  const selection = await selectModel({
+  const selection = await select({
     seat: { address: record.address, role: record.role, ...(record.purpose ? { purpose: record.purpose } : {}) },
     tasks: work.map((entry) => ({
       id: entry.id,
@@ -175,16 +178,138 @@ async function chooseLaunchModel(root: string, config: Desk, record: Seat, portf
     })),
     candidates,
   });
-  if (!selection.available) {
-    console.warn(`Model selection for ${record.address} unavailable: ${selection.reason} Falling back to strongest available model.`);
-    return candidates[0]!;
+  if (!selection.available || selection.confidence < 0.75 || !candidates.some((entry) => entry.id === selection.selected_model)) {
+    const reason = !selection.available ? selection.reason : selection.confidence < 0.75
+      ? `Jev model selection confidence is low (${selection.confidence}).`
+      : `Jev selected a model outside the available portfolio: ${selection.selected_model}.`;
+    return { candidate: candidates[0]!, selection, fallback: reason };
   }
-  return required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`);
+  return { candidate: required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`), selection };
 }
 
 /** Pi loads this extension inside its own process, so it can wake without host text injection. */
 export const piExtensionPath = () => join(import.meta.dir, "..", "extensions", "pi", "index.ts");
 
+type HerdrRequest = { session: string; pane: string; seat: string; root: string; piSession: string; sessionPath?: string; resume: boolean; args: string[] };
+type Command = (command: string[]) => Promise<string>;
+export type PiRuntimeLaunchDependencies = {
+  select?: (input: ModelSelectionInput) => Promise<ModelSelectionResponse>;
+  command?: Command;
+  sessionId?: () => string;
+  at?: () => string;
+};
+
+type PaneReport = { pane: string; agent?: string; status?: string; sessionPath?: string };
+type ProcessReport = { shell?: number; processes: Array<{ name?: string; argv0?: string; cmdline?: string }> };
+
+const object = (value: unknown): Record<string, unknown> | undefined => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const text = (value: unknown) => typeof value === "string" ? value : undefined;
+const number = (value: unknown) => typeof value === "number" ? value : undefined;
+function result(value: unknown) { const root = object(value); return object(root?.result) ?? root; }
+function paneReport(value: unknown): PaneReport {
+  const pane = object(result(value)?.pane) ?? result(value);
+  const session = object(pane?.agent_session);
+  const id = text(pane?.pane_id);
+  if (!id) throw new Error("Herdr pane get did not report a pane id.");
+  return {
+    pane: id,
+    ...(text(pane?.agent) ? { agent: text(pane?.agent) } : {}),
+    ...(text(pane?.agent_status) ? { status: text(pane?.agent_status) } : {}),
+    ...(session?.kind === "path" && text(session.value) ? { sessionPath: text(session.value) } : {}),
+  };
+}
+function processReport(value: unknown): ProcessReport {
+  const report = object(result(value)?.process_info) ?? result(value);
+  const processes = Array.isArray(report?.foreground_processes) ? report.foreground_processes.flatMap((entry) => {
+    const process = object(entry);
+    return process ? [{ name: text(process.name), argv0: text(process.argv0), cmdline: text(process.cmdline) }] : [];
+  }) : [];
+  return { ...(number(report?.shell_pid) ? { shell: number(report?.shell_pid) } : {}), processes };
+}
+function agentReport(value: unknown) {
+  const agent = object(result(value)?.agent) ?? result(value);
+  const name = text(agent?.name);
+  const pane = text(agent?.pane_id);
+  if (!name || !pane) throw new Error("Herdr agent get did not report agent name and pane id.");
+  return { name, pane, status: text(agent?.status) ?? text(agent?.state) };
+}
+function piProcess(processes: ProcessReport["processes"]) {
+  return processes.find((entry) => entry.name === "pi" || entry.argv0?.endsWith("/pi") || entry.argv0 === "pi" || /(^|\/)pi(?:\s|$)/.test(entry.cmdline ?? ""));
+}
+/** Pi's durable JSONL session filenames end in `_<session-id>.jsonl`. */
+function sessionIdFromPiJsonlPath(path: string) {
+  const match = basename(path).match(/_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i);
+  if (!match) throw new Error("Herdr did not report a Pi JSONL path with a documented session ID.");
+  return match[1]!;
+}
+function shellQuote(value: string) { return `'${value.replaceAll("'", "'\\''")}'`; }
+function agentName(address: string) { return `flow-${address.replace(/[^a-z0-9_-]/gi, "-").toLowerCase()}`.slice(0, 32); }
+function herdr(session: string, ...args: string[]) { return ["herdr", "--session", session, ...args]; }
+function startCommand(request: HerdrRequest) {
+  const session = request.resume ? ["--session", required(request.sessionPath, "a previously verified Pi session path")] : ["--session-id", request.piSession];
+  return herdr(request.session, "agent", "start", agentName(request.seat), "--kind", "pi", "--pane", request.pane, "--", ...session, ...request.args);
+}
+function receiptPath(root: string, piSession: string) { return join(root, ".atdd-flow", "runtime-launch", `${encodeURIComponent(piSession)}-${crypto.randomUUID().slice(0, 8)}.yaml`); }
+
+/** A deliberately narrow Pi+Herdr launch using only installed CLI commands on an existing shell pane. */
+export async function launchPiRuntime(root: string, address: string, args: string[], dependencies: PiRuntimeLaunchDependencies = {}) {
+  const resolved = await canonicalAddress(root, address);
+  const record = await seat(root, resolved);
+  const config = await desk(root);
+  const pane = required(words(args, "--pane"), "--pane");
+  const herdrSession = required(words(args, "--herdr-session"), "--herdr-session");
+  const resume = args.includes("--resume");
+  const dryRun = args.includes("--dry-run");
+  if (args.some((argument) => !["--pane", pane, "--herdr-session", herdrSession, "--resume", "--dry-run"].includes(argument))) throw new Error("Use `pi runtime launch <seat> --pane <existing-pane> --herdr-session <session> [--resume] [--dry-run]`.");
+  const active = (await seatTasks(root, record.project, resolved)).filter((entry) => entry.task.status === "in_progress");
+  if (!active.length) throw new Error(`${resolved} has no active bounded task; refusing runtime launch.`);
+  const selection = await chooseLaunchModel(root, config, record, required(await modelPortfolio(root), "models.yaml for Pi runtime launch"), dependencies.select);
+  const model = resolveModelCommand(config, selection.candidate);
+  if (basename(model.agent) !== "pi") throw new Error(`Pi runtime launch requires a Pi candidate, received ${selection.candidate.id}.`);
+  const command = dependencies.command ?? runOutput;
+  const [paneRaw, processRaw] = await Promise.all([command(herdr(herdrSession, "pane", "get", pane)), command(herdr(herdrSession, "pane", "process-info", "--pane", pane))]);
+  const currentPane = paneReport(JSON.parse(paneRaw));
+  const currentProcess = processReport(JSON.parse(processRaw));
+  if (currentPane.pane !== pane) throw new Error("Herdr reported a different pane; refusing runtime launch.");
+  if (currentPane.agent || piProcess(currentProcess.processes)) throw new Error(resume ? "Resume requires the prior Pi to have exited and been released." : "New launch requires an available shell pane.");
+  const piSession = resume ? record.runtime?.pi_session : (dependencies.sessionId ?? (() => crypto.randomUUID()))();
+  if (!piSession) throw new Error("Resume requires the exact Pi session stored on the seat.");
+  if (resume) {
+    const prior = record.runtime?.launch_receipt;
+    if (!prior) throw new Error("Resume requires an existing Flow launch receipt.");
+    try {
+      const receipt = await readYaml<{ seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string }>(prior);
+      if (receipt.seat !== resolved || receipt.pi_session !== piSession || receipt.pi_session_path !== record.runtime?.pi_session_path || receipt.herdr_session !== herdrSession || receipt.pane !== pane) throw new Error("receipt does not match seat/session/path/pane");
+    } catch (error) { throw new Error(`Resume requires a valid Flow launch receipt: ${(error as Error).message}`); }
+  }
+  const priorSessionPath = resume ? required(record.runtime?.pi_session_path, "a previously verified Pi session path") : undefined;
+  const request: HerdrRequest = { session: herdrSession, pane, seat: resolved, root, piSession, ...(priorSessionPath ? { sessionPath: priorSessionPath } : {}), resume, args: [...model.args, "--extension", piExtensionPath()] };
+  const plan = { candidate: selection.candidate.id, piSession, pane, herdrSession, receipt: receiptPath(root, piSession), command: startCommand(request), ...(dryRun ? { dryRun: true } : {}) };
+  if (dryRun) return plan;
+  await command(herdr(herdrSession, "pane", "run", pane, `export ATDD_WORKFLOW_ROOT=${shellQuote(root)} ATDD_WORKFLOW_SEAT=${shellQuote(resolved)}`));
+  await command(startCommand(request));
+  const [agentRaw, verifiedPaneRaw, verifiedProcessRaw] = await Promise.all([command(herdr(herdrSession, "agent", "get", agentName(resolved))), command(herdr(herdrSession, "pane", "get", pane)), command(herdr(herdrSession, "pane", "process-info", "--pane", pane))]);
+  const agent = agentReport(JSON.parse(agentRaw));
+  const verifiedPane = paneReport(JSON.parse(verifiedPaneRaw));
+  const verifiedProcess = piProcess(processReport(JSON.parse(verifiedProcessRaw)).processes);
+  const sessionPath = verifiedPane.sessionPath;
+  if (!sessionPath) throw new Error("Herdr did not report an exact Pi session path; seat binding was not changed.");
+  const reportedId = sessionIdFromPiJsonlPath(sessionPath);
+  if (reportedId !== piSession) throw new Error("Herdr did not verify the exact requested Pi session ID; seat binding was not changed.");
+  if (resume && sessionPath !== record.runtime?.pi_session_path) throw new Error("Herdr did not verify the exact requested Pi session path; seat binding was not changed.");
+  if (agent.name !== agentName(resolved) || agent.pane !== pane || ![agent.status, verifiedPane.status].every((status) => status === "idle" || status === "done") || verifiedPane.pane !== pane || !verifiedProcess) throw new Error("Herdr did not verify the replacement Pi process; seat binding was not changed.");
+  const receipt = plan.receipt;
+  const receiptRecord = {
+    schema: "atdd-flow/pi-runtime-launch-receipt/v1", seat: resolved, tasks: active.map((entry) => entry.id), candidate: selection.candidate.id,
+    selection: selection.fallback ? { result: "fallback", reason: selection.fallback } : { result: "selected", confidence: selection.selection.confidence, ...(selection.selection.available && selection.selection.model ? { model: selection.selection.model } : {}) },
+    pi_session: piSession, pi_session_path: sessionPath, herdr_session: herdrSession, pane, created_at: dependencies.at?.() ?? now(),
+  };
+  await mkdir(dirname(receipt), { recursive: true });
+  await writeFile(receipt, yaml.print(receiptRecord), { encoding: "utf8", flag: "wx" });
+  await bind(root, resolved, ["--application", "herdr", "--address", pane, "--session", herdrSession], selection.candidate.id, "native", piSession, sessionPath, receipt);
+  return plan;
+}
+
 export async function describe(root: string, address: string, args: string[]) {
   const resolved = await canonicalAddress(root, address);
   const record = await seat(root, resolved);

package/src/tasks.ts

@@ -192,6 +192,8 @@ async function transition(root: string, projectName: string, id: string, next: T
   if (next === "done") {
     if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may complete task ${id}.`);
     if (!allProofs(task)) throw new Error(`Task ${id} is missing completion proof.`);
+    const { assertParentMayComplete } = await import("./ephemeral-resources");
+    await assertParentMayComplete(root, { project: projectName, task: id });
     const { assertAcceptedBehavioralReview } = await import("./reviews");
     await assertAcceptedBehavioralReview(root, projectName, id, task);
     if (retire) await retireAssignee(root, projectName, id, task);
@@ -246,6 +248,8 @@ export async function unblock(root: string, projectName: string, id: string, arg
   if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may unblock task ${id}.`);
   if (task.status !== "in_progress") throw new Error(`Task ${id} can only be unblocked while in_progress.`);
   if (!task.blocker) throw new Error(`Task ${id} has no blocker to clear.`);
+  const { assertDependentsMayUnblock } = await import("./ephemeral-resources");
+  await assertDependentsMayUnblock(root, { project: projectName, task: id });
   delete task.blocker;
   await writeTask(root, projectName, id, task);
   console.log(`${id}  unblocked`);