@afokapu/atdd-flow 0.3.21 → 0.3.23

package/package.json

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

package/src/adoption-authorizations.ts

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { now, required, words, yaml } from "./core";
+
+export const authorizationSchema = "atdd-flow/exact-session-adoption-authorization/v1" as const;
+export type ExactSessionAdoptionAuthorization = {
+  schema: typeof authorizationSchema;
+  id: string;
+  issued_by: "operator@desk";
+  created_at: string;
+  seat: string;
+  pi_session: string;
+  pi_session_path: string;
+  source: { herdr_session: string; pane: string };
+  target: { herdr_session: string; pane: string; cwd: string };
+};
+
+const validId = (value: string) => /^A-[A-Za-z0-9_-]+$/.test(value);
+const nonEmpty = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
+const path = (root: string, id: string) => join(root, ".atdd-flow", "exact-session-adoption-authorizations", `${id}.yaml`);
+const hashPath = (root: string, id: string) => join(root, ".atdd-flow", "exact-session-adoption-authorizations", `${id}.sha256`);
+const digest = (content: string) => createHash("sha256").update(content).digest("hex");
+
+function tuple(record: ExactSessionAdoptionAuthorization) {
+  return record.schema === authorizationSchema && validId(record.id) && record.issued_by === "operator@desk" && nonEmpty(record.created_at)
+    && nonEmpty(record.seat) && nonEmpty(record.pi_session) && nonEmpty(record.pi_session_path)
+    && nonEmpty(record.source?.herdr_session) && nonEmpty(record.source?.pane)
+    && nonEmpty(record.target?.herdr_session) && nonEmpty(record.target?.pane) && nonEmpty(record.target?.cwd);
+}
+
+export async function createExactSessionAdoptionAuthorization(root: string, id: string, args: string[]) {
+  if (!validId(id)) throw new Error("Exact-session adoption authorization id must use A- followed by letters, numbers, underscores, or hyphens.");
+  if (words(args, "--by") !== "operator@desk") throw new Error("Only operator@desk may issue an exact-session adoption authorization.");
+  const record: ExactSessionAdoptionAuthorization = {
+    schema: authorizationSchema, id, issued_by: "operator@desk", created_at: now(),
+    seat: required(words(args, "--seat"), "--seat"), pi_session: required(words(args, "--pi-session"), "--pi-session"),
+    pi_session_path: resolve(required(words(args, "--pi-session-path"), "--pi-session-path")),
+    source: { herdr_session: required(words(args, "--source-herdr-session"), "--source-herdr-session"), pane: required(words(args, "--source-pane"), "--source-pane") },
+    target: { herdr_session: required(words(args, "--target-herdr-session"), "--target-herdr-session"), pane: required(words(args, "--target-pane"), "--target-pane"), cwd: resolve(required(words(args, "--target-cwd"), "--target-cwd")) },
+  };
+  const file = path(root, id);
+  const content = yaml.print(record);
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, content, { encoding: "utf8", flag: "wx" });
+  await writeFile(hashPath(root, id), `${digest(content)}\n`, { encoding: "utf8", flag: "wx" });
+  console.log(id);
+}
+
+function same(record: ExactSessionAdoptionAuthorization, expected: Omit<ExactSessionAdoptionAuthorization, "schema" | "id" | "issued_by" | "created_at">) {
+  return record.seat === expected.seat && record.pi_session === expected.pi_session && record.pi_session_path === expected.pi_session_path
+    && record.source.herdr_session === expected.source.herdr_session && record.source.pane === expected.source.pane
+    && record.target.herdr_session === expected.target.herdr_session && record.target.pane === expected.target.pane && record.target.cwd === expected.target.cwd;
+}
+
+async function used(root: string, id: string) {
+  const folder = join(root, ".atdd-flow", "runtime-launch");
+  try {
+    const files = await readdir(folder);
+    for (const file of files.filter((entry) => entry.endsWith(".yaml"))) {
+      try {
+        const value = yaml.parse<Record<string, unknown>>(await readFile(join(folder, file), "utf8"));
+        const authorization = value.relocation && typeof value.relocation === "object" ? (value.relocation as Record<string, unknown>).authorization : undefined;
+        if (authorization && typeof authorization === "object" && (authorization as Record<string, unknown>).id === id) return true;
+      } catch { /* Malformed receipts never authorize reuse. */ }
+    }
+  } catch { /* No previous receipt means unused. */ }
+  return false;
+}
+
+/** Resolve only a create-only operator record whose complete tuple matches before runtime projection. */
+export async function resolveExactSessionAdoptionAuthorization(root: string, id: string, expected: Omit<ExactSessionAdoptionAuthorization, "schema" | "id" | "issued_by" | "created_at">) {
+  if (!validId(id)) throw new Error("Exact-session adoption requires an immutable operator authorization record id.");
+  let raw: string;
+  try { raw = await readFile(path(root, id), "utf8"); }
+  catch { throw new Error("Exact-session adoption requires an existing immutable operator authorization record."); }
+  let record: ExactSessionAdoptionAuthorization;
+  try { record = yaml.parse<ExactSessionAdoptionAuthorization>(raw); }
+  catch { throw new Error("Exact-session adoption requires a well-formed immutable operator authorization record."); }
+  let storedHash: string;
+  try { storedHash = (await readFile(hashPath(root, id), "utf8")).trim(); }
+  catch { throw new Error("Exact-session adoption requires a create-only immutable operator authorization record."); }
+  if (!/^[a-f0-9]{64}$/i.test(storedHash) || storedHash !== digest(raw)) throw new Error("Exact-session adoption requires an immutable operator authorization record.");
+  if (!tuple(record) || record.id !== id || !same(record, expected)) throw new Error("Exact-session adoption requires an immutable operator authorization record bound to the exact adoption tuple.");
+  if (await used(root, id)) throw new Error("Exact-session adoption authorization record was already used.");
+  return { id, hash: storedHash };
+}

package/src/cli.ts

@@ -2,6 +2,7 @@
 
 import { basename, resolve } from "node:path";
 import { init, initProject, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
+import { createExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
 import { required, values, words, yaml } from "./core";
@@ -26,7 +27,8 @@ 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 <asserted-herdr-pane>] --herdr-session <session> [--resume] [--dry-run]
+  atdd-flow pi runtime authorize-adoption <id> --by operator@desk --seat <seat> --pi-session <id> --pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --target-herdr-session <session> --target-pane <pane> --target-cwd <path>
+  atdd-flow pi runtime launch <address> [--pane <asserted-herdr-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <record-id>]
   atdd-flow application use <address> <application>
   atdd-flow multiplexer status|apply herdr [--session <name>]
   atdd-flow describe <address> --purpose <one-line responsibility>
@@ -92,13 +94,14 @@ async function main() {
     attach: () => attach(root, required(rest[0], "address"), rest.slice(1)),
     pi: async () => {
       if (rest[0] === "extension-path") return console.log(piExtensionPath());
+      if (rest[0] === "runtime" && rest[1] === "authorize-adoption") return createExactSessionAdoptionAuthorization(root, required(rest[2], "authorization id"), rest.slice(3));
       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 <asserted-pane>] --herdr-session <session> [--resume] [--dry-run]`.");
+      throw new Error("Use `pi extension-path`, `pi runtime authorize-adoption <id> ...`, or `pi runtime launch <address> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <record-id>]`.");
     },
     application: async () => {
       if (rest[0] === "use") return useApplication(root, required(rest[1], "address"), required(rest[2], "application"));

package/src/seats.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
-import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { basename, dirname, join, resolve } from "node:path";
 import { discoverAddress, discoverHerdrLocator, notify } from "./adapters";
 import {
@@ -11,6 +12,7 @@ import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } fr
 import { seatTasks } from "./tasks";
 import { projectHerdrSeat } from "./multiplexer";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
+import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 
 const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
@@ -291,6 +293,15 @@ function startCommand(request: HerdrRequest) {
 }
 function receiptPath(root: string, piSession: string) { return join(root, ".atdd-flow", "runtime-launch", `${encodeURIComponent(piSession)}-${crypto.randomUUID().slice(0, 8)}.yaml`); }
 
+async function immutableSessionBackup(root: string, sessionPath: string, piSession: string) {
+  const content = await readFile(sessionPath);
+  const sha256 = createHash("sha256").update(content).digest("hex");
+  const backup = join(root, ".atdd-flow", "runtime-launch", "backups", `${encodeURIComponent(piSession)}-${crypto.randomUUID()}.jsonl`);
+  await mkdir(dirname(backup), { recursive: true });
+  await writeFile(backup, content, { flag: "wx" });
+  return { backup, sha256 };
+}
+
 /** 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);
@@ -300,15 +311,41 @@ export async function launchPiRuntime(root: string, address: string, args: strin
   const herdrSession = required(words(args, "--herdr-session"), "--herdr-session");
   const resume = args.includes("--resume");
   const dryRun = args.includes("--dry-run");
-  const allowed = ["--herdr-session", herdrSession, "--resume", "--dry-run", ...(requestedPane ? ["--pane", requestedPane] : [])];
-  if (args.some((argument) => !allowed.includes(argument))) throw new Error("Use `pi runtime launch <seat> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run]`.");
+  const adoptedSessionPath = words(args, "--adopt-session");
+  const sourceHerdrSession = words(args, "--source-herdr-session");
+  const sourcePane = words(args, "--source-pane");
+  const authorization = words(args, "--authorization");
+  const adoptionFields = [adoptedSessionPath, sourceHerdrSession, sourcePane, authorization];
+  const adopting = adoptionFields.some(Boolean);
+  const allowed = ["--herdr-session", herdrSession, "--resume", "--dry-run", ...(requestedPane ? ["--pane", requestedPane] : []),
+    ...(adoptedSessionPath ? ["--adopt-session", adoptedSessionPath] : []), ...(sourceHerdrSession ? ["--source-herdr-session", sourceHerdrSession] : []),
+    ...(sourcePane ? ["--source-pane", sourcePane] : []), ...(authorization ? ["--authorization", authorization] : [])];
+  if (args.some((argument) => !allowed.includes(argument))) throw new Error("Use `pi runtime launch <seat> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <owner-reference>]`.");
+  if (adopting && (resume || !adoptionFields.every(Boolean))) throw new Error("Exact-session adoption requires --adopt-session, --source-herdr-session, --source-pane, and --authorization without --resume.");
+  const existingHerdr = record.runtime?.addresses.herdr;
+  const existingPane = typeof existingHerdr === "object" ? existingHerdr.pane : undefined;
+  const existingSession = typeof existingHerdr === "object" ? existingHerdr.session : undefined;
+  if (resume && ((requestedPane && requestedPane !== existingPane) || herdrSession !== existingSession)) {
+    throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
+  }
   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 piSession = adopting ? sessionIdFromPiJsonlPath(required(adoptedSessionPath, "an exact adopted Pi session path")) : resume ? record.runtime?.pi_session : (dependencies.sessionId ?? (() => crypto.randomUUID()))();
+  if (!piSession) throw new Error("Resume requires the exact Pi session stored on the seat.");
+  const canonicalAdoptedSessionPath = adopting ? resolve(required(adoptedSessionPath, "an exact adopted Pi session path")) : undefined;
+  const authorizationRecord = adopting
+    ? await resolveExactSessionAdoptionAuthorization(root, required(authorization, "an immutable operator authorization record"), {
+      seat: resolved, pi_session: piSession, pi_session_path: required(canonicalAdoptedSessionPath, "an exact adopted Pi session path"),
+      source: { herdr_session: required(sourceHerdrSession, "a source Herdr session"), pane: required(sourcePane, "a source pane") },
+      target: { herdr_session: herdrSession, pane: required(requestedPane, "--pane for exact-session adoption"), cwd: resolve(record.worktree) },
+    })
+    : undefined;
   const projection = await projectHerdrSeat(root, resolved, herdrSession, command);
+  if (resume && projection.pane !== existingPane) throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
   if (requestedPane && requestedPane !== projection.pane) throw new Error("The asserted --pane does not match the seat-scoped Herdr projection.");
   const pane = projection.pane;
   const [paneRaw, processRaw] = await Promise.all([command(herdr(herdrSession, "pane", "get", pane)), command(herdr(herdrSession, "pane", "process-info", "--pane", pane))]);
@@ -316,8 +353,6 @@ export async function launchPiRuntime(root: string, address: string, args: strin
   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.");
@@ -326,10 +361,24 @@ export async function launchPiRuntime(root: string, address: string, args: strin
       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 priorSessionPath = adopting ? required(canonicalAdoptedSessionPath, "an exact adopted Pi session path") : resume ? required(record.runtime?.pi_session_path, "a previously verified Pi session path") : undefined;
+  if (adopting) {
+    const [sourcePaneRaw, sourceProcessRaw] = await Promise.all([
+      command(herdr(required(sourceHerdrSession, "a source Herdr session"), "pane", "get", required(sourcePane, "a source pane"))),
+      command(herdr(required(sourceHerdrSession, "a source Herdr session"), "pane", "process-info", "--pane", required(sourcePane, "a source pane"))),
+    ]);
+    const sourceReport = paneReport(JSON.parse(sourcePaneRaw));
+    const sourceProcess = processReport(JSON.parse(sourceProcessRaw));
+    if (sourceReport.pane !== sourcePane || sourceReport.agent || piProcess(sourceProcess.processes)) {
+      throw new Error("Exact-session adoption requires proof that the source Pi has exited and been released.");
+    }
+  }
+  const request: HerdrRequest = { session: herdrSession, pane, seat: resolved, root, piSession, ...(priorSessionPath ? { sessionPath: priorSessionPath } : {}), resume: resume || adopting, 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;
+  // The source snapshot is a pre-migration prerequisite: never start a target
+  // Pi when its immutable recovery copy cannot be created.
+  const relocation = adopting ? await immutableSessionBackup(root, required(canonicalAdoptedSessionPath, "an exact adopted Pi session path"), piSession) : undefined;
   await command(herdr(herdrSession, "pane", "run", pane, `export ATDD_WORKFLOW_ROOT=${shellQuote(root)} ATDD_WORKFLOW_SEAT=${shellQuote(resolved)} ATDD_FLOW_PI_SESSION=${shellQuote(piSession)} ATDD_FLOW_HERDR_SESSION=${shellQuote(herdrSession)} ATDD_FLOW_HERDR_PANE=${shellQuote(pane)}`));
   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))]);
@@ -340,13 +389,15 @@ export async function launchPiRuntime(root: string, address: string, args: strin
   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 ((resume || adopting) && sessionPath !== priorSessionPath) 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(),
+    pi_session: piSession, pi_session_path: sessionPath, herdr_session: herdrSession, pane,
+    ...(relocation ? { relocation: { source_herdr_session: sourceHerdrSession, source_pane: sourcePane, authorization: authorizationRecord, backup: relocation.backup, backup_sha256: relocation.sha256 } } : {}),
+    created_at: dependencies.at?.() ?? now(),
   };
   await mkdir(dirname(receipt), { recursive: true });
   await writeFile(receipt, yaml.print(receiptRecord), { encoding: "utf8", flag: "wx" });