@afokapu/atdd-flow 0.3.10 → 0.3.12

package/package.json

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

package/src/cli.ts

@@ -1,10 +1,10 @@
 #!/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";
@@ -25,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>
@@ -85,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"));

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/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,26 @@ 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 launchEligibleTasks(root: string, record: Seat) {
+  const tasks = await seatTasks(root, record.project, record.address);
+  const eligible = await Promise.all(tasks.map(async (entry) => {
+    if (entry.task.assignee !== record.address || entry.task.blocker) return undefined;
+    if (entry.task.status === "in_progress") return entry;
+    if (entry.task.status !== "todo") return undefined;
+    const dependencies = await Promise.all((entry.task.depends_on ?? []).map(async (id) => {
+      try { return (await readYaml<{ status?: string }>(paths(root).taskFile(record.project, id))).status === "done"; }
+      catch { return false; }
+    }));
+    return dependencies.every(Boolean) ? entry : undefined;
+  }));
+  return eligible.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry));
+}
+
+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 +193,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 launchEligibleTasks(root, record);
+  if (!active.length) throw new Error(`${resolved} has no launch-eligible 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);