@afokapu/atdd-flow 0.3.68 → 0.3.70

package/extensions/pi/index.ts

@@ -366,9 +366,9 @@ const sessionUnsetOrEqual = (runtime: Seat["runtime"], piSession?: string, piSes
 const recovery = (root: string, seat: string, mode: RecoveryMode, session?: string) => recoveryFor(root, seat, mode, session).catch(() => undefined);
 
 /** Desk mail is authoritative; the queue is a bounded delivery index and fs.watch only shortens latency. */
-export default function (pi: ExtensionAPI) {
-  const root = process.env.ATDD_WORKFLOW_ROOT;
-  const seat = process.env.ATDD_WORKFLOW_SEAT;
+export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = process.env) {
+  const root = environment.ATDD_WORKFLOW_ROOT;
+  const seat = environment.ATDD_WORKFLOW_SEAT;
   if (!root || !seat) return;
   let runtime: ReturnType<typeof createPiRuntime> | undefined;
   let handoverPrompted = false;
@@ -395,7 +395,7 @@ export default function (pi: ExtensionAPI) {
       const threshold = await contextHandoverThreshold(root);
       if (percent < threshold) return;
       handoverPrompted = true;
-      const bundle = await recovery(root, seat, "threshold", process.env.ATDD_FLOW_PI_SESSION);
+      const bundle = await recovery(root, seat, "threshold", environment.ATDD_FLOW_PI_SESSION);
       pi.sendMessage({
         customType: "atdd-flow-context-handover-replacement",
         content: handoverThresholdInstruction(percent, threshold, bundle),
@@ -404,7 +404,7 @@ export default function (pi: ExtensionAPI) {
     } catch { /* Desk policy is re-read on the next safe boundary. */ }
   });
   pi.on("turn_end", async (_event, ctx) => {
-    const sourceSession = process.env.ATDD_FLOW_PI_SESSION;
+    const sourceSession = environment.ATDD_FLOW_PI_SESSION;
     if (!sourceSession) return;
     try {
       const request = await readHandoverReplacement(root, seat);
@@ -419,13 +419,13 @@ export default function (pi: ExtensionAPI) {
   });
   pi.on("session_start", async (_event, ctx) => {
     const sessionManager = (ctx as { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } }).sessionManager;
-    const liveSession = process.env.ATDD_FLOW_PI_SESSION ?? sessionManager?.getSessionId?.();
+    const liveSession = environment.ATDD_FLOW_PI_SESSION ?? sessionManager?.getSessionId?.();
     // One display-only notice per session: a refused, timed-out or failed activation must never be silent, and never wakes the agent.
     let noticed = false;
     const noticeActivation = async (transport: "active" | "inactive", error?: string) => {
       if (noticed) return;
       noticed = true;
-      const live = { pi_session: liveSession, herdr_session: process.env.ATDD_FLOW_HERDR_SESSION ?? process.env.HERDR_SESSION, pane: process.env.ATDD_FLOW_HERDR_PANE ?? process.env.HERDR_PANE_ID };
+      const live = { pi_session: liveSession, herdr_session: environment.ATDD_FLOW_HERDR_SESSION ?? environment.HERDR_SESSION, pane: environment.ATDD_FLOW_HERDR_PANE ?? environment.HERDR_PANE_ID };
       const activation = await diagnoseMailActivation(root, seat, live, transport, error).catch(() => undefined);
       if (!activation) return;
       if (runtime) await recordMailActivation(root, seat, runtime.ownerToken, activation).catch(() => undefined);
@@ -449,11 +449,11 @@ export default function (pi: ExtensionAPI) {
       });
     } });
     await runtime.start();
-    const piSession = process.env.ATDD_FLOW_PI_SESSION;
-    const herdrSession = process.env.ATDD_FLOW_HERDR_SESSION;
-    const pane = process.env.ATDD_FLOW_HERDR_PANE;
+    const piSession = environment.ATDD_FLOW_PI_SESSION;
+    const herdrSession = environment.ATDD_FLOW_HERDR_SESSION;
+    const pane = environment.ATDD_FLOW_HERDR_PANE;
     if (!piSession && !herdrSession && !pane) {
-      if (await hostAttachedActivation({ root, seat, herdrSession: process.env.HERDR_SESSION, pane: process.env.HERDR_PANE_ID, piSession: sessionManager?.getSessionId?.(), piSessionPath: sessionManager?.getSessionFile?.() })) {
+      if (await hostAttachedActivation({ root, seat, herdrSession: environment.HERDR_SESSION, pane: environment.HERDR_PANE_ID, piSession: sessionManager?.getSessionId?.(), piSessionPath: sessionManager?.getSessionFile?.() })) {
         hostActivatedAt = Date.now();
         if (await runtime.activate()) {
           const bundle = await recovery(root, seat, "start", sessionManager?.getSessionId?.());

package/package.json

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

package/src/cli.ts

@@ -21,7 +21,7 @@ import { linearCommand } from "./linear-cli";
 import * as ownerAlerts from "./owner-escalations";
 import { recoveryFor } from "./recovery-bundle";
 import { reconcileOnce } from "./reconcile";
-import { recordHandover, requestHandoverReplacement, resumedHandoverReplacement, showHandover } from "./handover";
+import { recordHandover, requestHandoverReplacement, resumedHandover, showHandover } from "./handover";
 import { migrateProjectVcs } from "./vcs-migration";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
@@ -140,7 +140,7 @@ async function main() {
     checkpoint: () => checkpoint(root, required(rest[0], "address"), rest.slice(1)),
     handover: () => rest[0] === "show" ? showHandover(root, required(rest[1], "address"))
       : rest[0] === "replace" ? requestHandoverReplacement(root, required(rest[1], "address"), rest.slice(2))
-      : rest[0] === "resumed" ? resumedHandoverReplacement(root, required(rest[1], "address"))
+      : rest[0] === "resumed" ? resumedHandover(root, required(rest[1], "address"))
       : recordHandover(root, required(rest[0], "address"), rest.slice(1)),
     task: async () => {
       const [subcommand, projectName, taskId, ...tail] = rest;

package/src/handover.ts

@@ -12,6 +12,7 @@ import { type Runtime, type Seat, atomicYaml, canonicalAddress, desk, exists, ha
 import { type Task, terminal } from "./tasks";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { exactFailedAdoptionProof } from "./exact-adoption-recovery";
+import { isExactOperatorSeat, operatorActivation, operatorRelaunchSection } from "./operator-launch";
 import { readRuntimeState } from "./runtime-state";
 
 export type Handover = {
@@ -96,10 +97,11 @@ export async function recordHandover(root: string, address: string, args: string
 
 export async function showHandover(root: string, address: string) {
   const resolved = await canonicalAddress(root, address);
-  await seat(root, resolved);
+  const seatRecord = await seat(root, resolved);
   const record = await recorded(root, resolved);
   if (!record) throw new Error(`No handover is recorded for ${resolved}.`);
-  process.stdout.write(record.text.endsWith("\n") ? record.text : `${record.text}\n`);
+  const relaunch = await isExactOperatorSeat(root, seatRecord, resolved) ? await operatorRelaunchSection(root, seatRecord) : "";
+  process.stdout.write((record.text.endsWith("\n") ? record.text : `${record.text}\n`) + relaunch);
 }
 
 export type HandoverReplacementRequest = {
@@ -751,6 +753,18 @@ export async function readHandoverReplacement(root: string, address: string) {
   return request;
 }
 
+async function operatorResumed(root: string, record: Seat) {
+  const { verified, total, discrepancies } = await operatorActivation(root, record, await recorded(root, record.address));
+  console.log(`RESUMED; verified ${verified}/${total}; discrepancies: ${discrepancies.join(", ") || "none"}.`);
+  if (discrepancies.length) throw new Error("Operator successor is not reconciled against the live Desk.");
+}
+
+/** Operator successors report through the launcher-activation check; every other seat keeps the Path-A reconciliation. */
+export async function resumedHandover(root: string, address: string) {
+  const resolved = await canonicalAddress(root, address), record = await seat(root, resolved);
+  return await isExactOperatorSeat(root, record, resolved) ? operatorResumed(root, record) : resumedHandoverReplacement(root, resolved);
+}
+
 export async function resumedHandoverReplacement(root: string, address: string) {
   const resolved = await canonicalAddress(root, address);
   const [request, record] = await Promise.all([readHandoverReplacement(root, resolved), seat(root, resolved)]);

package/src/operator-launch.ts

@@ -0,0 +1,74 @@
+// URN: component:flow:e003:operator-launch:backend:integration
+// Tested-By:
+// - test:atdd-flow:context-handover-session-replacement
+// Runtime: bun
+// Purpose: Define operator seat topology, relaunch command, and activation proof.
+
+import { resolve } from "node:path";
+import { type Seat, desk, exists, project, readYaml } from "./core";
+import { readRuntimeState } from "./runtime-state";
+
+type Receipt = Record<string, string | undefined>;
+type Recorded = { recorded_at: string; text: string };
+
+/** The single generated relaunch command: the Flow launcher resolves the pane, so no --pane, --resume, or hand-edited binding is involved. */
+export const canonicalLaunchCommand = (address: string, herdrSession: string) => `atdd-flow pi runtime launch ${address} --herdr-session ${herdrSession}`;
+
+/** Only operator@<project> on the project's primary main checkout is the supported operator seat. */
+export async function isExactOperatorSeat(root: string, record: Seat, address: string) {
+  if (record.address !== address || record.role !== "operator" || address !== `operator@${record.project}` || record.branch !== "main") return false;
+  const config = await project(root, record.project);
+  return Boolean(config.repository && resolve(record.worktree) === resolve(config.repository));
+}
+
+/** The text appended to `handover show`; the recorded handover itself is never rewritten. */
+export async function operatorRelaunchSection(root: string, record: Seat) {
+  const locator = record.runtime?.addresses.herdr;
+  const session = (typeof locator === "object" ? locator.session : undefined) ?? (await desk(root)).herdr_session;
+  const command = session ? canonicalLaunchCommand(record.address, session) : "UNAVAILABLE: no Herdr session is recorded for this seat or Desk.";
+  return `\nCANONICAL RELAUNCH COMMAND (generated by Flow; run it in a vacant shell pane after this Pi exits, then run \`atdd-flow handover resumed ${record.address}\`):\n${command}\n`;
+}
+
+const notBefore = (value: string | undefined, floor: string | undefined) => Boolean(value && floor && Date.parse(value) >= Date.parse(floor));
+const handoverSession = (handover: Recorded | undefined) => handover?.text.match(/^Runtime:[^|]*\|\s*([^|\s]+)/m)?.[1];
+
+async function readReceipt(path: string | undefined): Promise<Receipt | undefined> {
+  return path && await exists(path) ? readYaml<Receipt>(path) : undefined;
+}
+
+function nativeBinding(record: Seat) {
+  const runtime = record.runtime;
+  return runtime?.application === "herdr" && runtime.wake === "native" && typeof runtime.addresses.herdr === "object";
+}
+
+function receiptMatchesBinding(record: Seat, receipt: Receipt | undefined) {
+  const runtime = record.runtime, locator = runtime?.addresses.herdr;
+  if (!receipt || !runtime?.pi_session || typeof locator !== "object") return false;
+  return receipt.schema === "atdd-flow/pi-runtime-launch-receipt/v1" && receipt.seat === record.address
+    && receipt.pi_session === runtime.pi_session && receipt.pi_session_path === runtime.pi_session_path
+    && receipt.herdr_session === locator.session && receipt.pane === locator.pane;
+}
+
+async function heartbeatMatches(root: string, record: Seat, handover: Recorded | undefined) {
+  const state = await readRuntimeState(root, record.address);
+  return Boolean(state && state.seat === record.address && state.pi_session === record.runtime?.pi_session && notBefore(state.heartbeat_at, handover?.recorded_at));
+}
+
+/**
+ * An operator successor has no Path-A request. It is reported resumed only when the
+ * launcher's fresh receipt, the native-wake binding, and a matching heartbeat all agree.
+ */
+export async function operatorActivation(root: string, record: Seat, handover: Recorded | undefined) {
+  const receipt = await readReceipt(record.runtime?.launch_receipt);
+  const session = record.runtime?.pi_session;
+  const checks: Array<[string, boolean]> = [
+    ["recorded handover", Boolean(handover)],
+    ["native delivery", nativeBinding(record)],
+    ["launcher receipt", receiptMatchesBinding(record, receipt)],
+    ["fresh receipt", notBefore(receipt?.created_at, handover?.recorded_at)],
+    ["fresh heartbeat", await heartbeatMatches(root, record, handover)],
+    ["fresh Pi session", Boolean(session) && session !== handoverSession(handover)],
+  ];
+  const discrepancies = checks.filter(([, ok]) => !ok).map(([name]) => name);
+  return { verified: checks.length - discrepancies.length, total: checks.length, discrepancies };
+}

package/src/pi-runtime-launch.ts

@@ -32,6 +32,7 @@ import { type Task, seatTasks, terminal } from "./tasks";
 import { projectHerdrSeat } from "./multiplexer";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { assertReplacementTarget, replacementForMainLaunch } from "./handover";
+import { canonicalLaunchCommand, isExactOperatorSeat } from "./operator-launch";
 
 export type PiRuntimeLaunchDependencies = {
   select?: (input: ModelSelectionInput) => Promise<ModelSelectionResponse>;
@@ -96,9 +97,10 @@ async function isExactNamedCoordinator(root: string, record: Seat, address: stri
 
 async function launchEligibleTasks(root: string, record: Seat, address: string) {
   const coordinator = await isExactNamedCoordinator(root, record, address);
+  const operator = await isExactOperatorSeat(root, record, address);
   const tasks = await seatTasks(root, record.project, record.address);
   const eligible = await Promise.all(tasks.map(async (entry) => {
-    const accountable = record.role === "driver" ? entry.task.assignee === record.address
+    const accountable = record.role === "driver" || operator ? entry.task.assignee === record.address
       : coordinator && entry.task.coordinator === record.address;
     if (!accountable || entry.task.blocker) return undefined;
     if (entry.task.status === "in_progress") return entry;
@@ -282,7 +284,8 @@ async function prepareLaunch(root: string, address: string, args: string[], depe
   const options = parseLaunchOptions(args), existingPane = existingPaneForResume(record, options);
   const replacement = await replacementForMainLaunch(root, record, resolved);
   const active = replacement ? [{ id: replacement.request.task, task: replacement.task }] : await launchEligibleTasks(root, record, resolved);
-  if (!active.length) throw new Error(`${resolved} has no launch-eligible task; refusing runtime launch.`);
+  const operator = await isExactOperatorSeat(root, record, resolved);
+  if (!active.length && !operator) 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}.`);
@@ -291,7 +294,7 @@ async function prepareLaunch(root: string, address: string, args: string[], depe
   if (!piSession) throw new Error("Resume requires the exact Pi session stored on the seat.");
   const adoptedPath = options.adopting ? resolve(required(options.adoptedSessionPath, "an exact adopted Pi session path")) : undefined;
   const authorizationRecord = await adoptionAuthorization(root, resolved, record, options, piSession, adoptedPath);
-  return { root, resolved, record, options, existingPane, replacement, active, selection, model, command, piSession, adoptedPath, authorizationRecord, dependencies };
+  return { root, resolved, record, operator, options, existingPane, replacement, active, selection, model, command, piSession, adoptedPath, authorizationRecord, dependencies };
 }
 
 /** Match the seat-scoped projection to all caller and replacement assertions. */
@@ -357,7 +360,8 @@ function buildLaunchPlan(launch: PreparedLaunch, pane: string, sessionPath?: str
   const request: HerdrRequest = { session: options.herdrSession, pane, seat: resolved, root, piSession,
     ...(sessionPath ? { sessionPath } : {}), resume: options.resume || options.adopting, args: [...model.args, "--extension", piExtensionPath()] };
   const plan = { candidate: selection.candidate.id, piSession, pane, herdrSession: options.herdrSession,
-    receipt: receiptPath(root, piSession), command: startCommand(request), ...(options.dryRun ? { dryRun: true } : {}) };
+    receipt: receiptPath(root, piSession), command: startCommand(request),
+    ...(launch.operator ? { canonicalCommand: canonicalLaunchCommand(resolved, options.herdrSession) } : {}), ...(options.dryRun ? { dryRun: true } : {}) };
   return { request, plan };
 }