@afokapu/atdd-flow 0.3.60 → 0.3.62

package/extensions/pi/index.ts

@@ -3,9 +3,9 @@ import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/pr
 import { basename, dirname, join } from "node:path";
 import { parse, stringify } from "yaml";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
+import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, recordMailActivation, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
 import { paths, readYaml, type Seat } from "../../src/core";
-import { expectsNativeMail, inactiveMailNotice } from "../../src/mail-activation-notice";
+import { activationNotice, diagnoseMailActivation, expectsNativeMail } from "../../src/mail-activation-notice";
 import { type NoticeState, createNoticeState, refreshDelivered, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
 import { handoverThresholdInstruction, runtimeStartupInstruction, successorInstruction } from "../../src/collaboration-policy";
 import { type RecoveryMode, recoveryFor } from "../../src/recovery-bundle";
@@ -261,7 +261,7 @@ export function createPiRuntime({
   const activate = async () => {
     if (!await owned()) return false;
     if (activated) return true;
-    transport = createTransport({
+    const candidate = createTransport({
       root, seat, batchSize: defaultBatchSize, intervalMs: defaultIntervalMs,
       deliver: async (mail, thread, path) => {
         // The application supplies the wake action, but this shared filesystem
@@ -278,7 +278,9 @@ export function createPiRuntime({
         return ownership === true && accepted !== false;
       },
     });
-    await transport.start();
+    // The transport counts as started only after start() succeeds; a failed start is stopped and leaves no transport behind.
+    try { await candidate.start(); } catch (error) { candidate.stop(); throw error; }
+    transport = candidate;
     activated = true;
     return true;
   };
@@ -294,7 +296,7 @@ export function createPiRuntime({
     }, heartbeatMs);
     if (!deferActivation) await activate();
   };
-  return { ownerToken, start, activate, stop, reconcile, get transport() { return transport; } };
+  return { ownerToken, start, activate, stop, reconcile, get transport() { return transport; }, get active() { return activated; } };
 }
 
 type LaunchReceipt = { seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string };
@@ -307,7 +309,8 @@ export class ActivationTimeout extends Error {
 /** Wait only for the launcher's already-verified receipt and exact Desk binding; this never creates either record. */
 export async function awaitLaunchActivation({ root, seat, piSession, herdrSession, pane, activate, intervalMs = defaultActivationIntervalMs, timeoutMs = defaultActivationTimeoutMs }: LaunchActivationOptions) {
   const deadline = Date.now() + timeoutMs;
-  while (Date.now() <= deadline) {
+  let matched = false;
+  while (!matched && Date.now() <= deadline) {
     try {
       const record = await readYaml<Seat>(paths(root).seatFile(seat));
       const runtime = record.runtime;
@@ -315,18 +318,28 @@ export async function awaitLaunchActivation({ root, seat, piSession, herdrSessio
       if (runtime?.application === "herdr" && typeof locator !== "string" && locator?.session === herdrSession && locator.pane === pane
         && runtime.pi_session === piSession && runtime.pi_session_path && runtime.launch_receipt) {
         const receipt = await readYaml<LaunchReceipt>(runtime.launch_receipt);
-        if (receipt.seat === seat && receipt.pi_session === piSession && receipt.pi_session_path === runtime.pi_session_path
-          && receipt.herdr_session === herdrSession && receipt.pane === pane) {
-          await activate();
-          return;
-        }
+        matched = receipt.seat === seat && receipt.pi_session === piSession && receipt.pi_session_path === runtime.pi_session_path
+          && receipt.herdr_session === herdrSession && receipt.pane === pane;
       }
     } catch { /* Binding and receipt are written after Herdr verification; wait within this finite window. */ }
-    await pause(intervalMs);
+    if (!matched) await pause(intervalMs);
   }
+  // The callback runs at most once, outside the polling try: a failing startup step is reported, never retried every poll.
+  if (matched) return activate();
   throw new ActivationTimeout();
 }
 
+/** A transient start failure (for example a busy inbox lock under concurrent reloads) is retried a bounded number of times before it is reported. */
+export async function activateWithRetry(activate: () => Promise<boolean>, attempts = 3, delayMs = 1_000) {
+  for (let attempt = 1; ; attempt += 1) {
+    try { return await activate(); }
+    catch (error) {
+      if (attempt >= attempts) throw error;
+      await pause(delayMs);
+    }
+  }
+}
+
 /**
  * Host-attached Pi has no launcher variables; it may activate only when Herdr's injected pane identity exactly
  * matches the Desk seat's native scoped binding. This reads the seat and never writes or creates a binding.
@@ -403,13 +416,19 @@ 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?.();
-    // One visible notice per session: a refused or timed-out activation must never be silent.
-    let inactiveNoticed = false;
-    const noticeInactive = async () => {
-      if (inactiveNoticed) return;
-      inactiveNoticed = true;
-      const content = await inactiveMailNotice(root, seat, liveSession).catch(() => undefined);
-      if (content) pi.sendMessage({ customType: "atdd-flow-mail-inactive", content, display: true, details: { seat, live: liveSession, authority: "binding" } }, { triggerTurn: true, deliverAs: "followUp" });
+    // 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 activation = await diagnoseMailActivation(root, seat, live, transport, error).catch(() => undefined);
+      if (!activation) return;
+      if (runtime) await recordMailActivation(root, seat, runtime.ownerToken, activation).catch(() => undefined);
+      if (transport === "active" && !error) return;
+      const content = await activationNotice(root, seat, activation).catch(() => undefined);
+      const customType = transport === "active" ? "atdd-flow-mail-startup-failed" : "atdd-flow-mail-inactive";
+      if (content) pi.sendMessage({ customType, content, display: true, details: { seat, live, authority: "binding" } }, { triggerTurn: false });
     };
     runtime = createPiRuntime({ root, seat, piSession: liveSession, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
       if (!sendIfOwned) return false;
@@ -437,7 +456,7 @@ export default function (pi: ExtensionAPI) {
           const notice = "Notices created before this session were not replayed; run atdd-flow status seat " + seat + " for unanswered mail.";
           pi.sendMessage({ customType: "atdd-flow-start", content: `${runtimeStartupInstruction(seat, bundle)} ${notice}`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
         }
-      } else if (await expectsNativeMail(root, seat)) await noticeInactive();
+      } else if (await expectsNativeMail(root, seat)) await noticeActivation("inactive");
       return;
     }
     if (!piSession || !herdrSession || !pane) return;
@@ -445,7 +464,7 @@ export default function (pi: ExtensionAPI) {
     void awaitLaunchActivation({
       root, seat, piSession, herdrSession, pane,
       activate: async () => {
-        if (!await current.activate()) return;
+        if (!await activateWithRetry(() => current.activate())) return;
         const request = await readHandoverReplacement(root, seat).catch(() => undefined);
         const successor = request && request.source.pi_session !== piSession ? request : undefined;
         const bundle = await recovery(root, seat, successor ? "successor" : "start", piSession);
@@ -460,7 +479,9 @@ export default function (pi: ExtensionAPI) {
         await sendTaskDirective(host, root, seat, notices);
         if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
       },
-    }).catch((error) => error instanceof ActivationTimeout ? noticeInactive() : undefined);
+    }).catch((error) => error instanceof ActivationTimeout
+      ? noticeActivation("inactive")
+      : noticeActivation(current.active ? "active" : "inactive", error instanceof Error ? error.message : String(error)));
   });
   pi.on("session_shutdown", () => { void runtime?.stop(); });
 }

package/package.json

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

package/src/mail-activation-notice.ts

@@ -1,23 +1,28 @@
 // URN: component:flow:e009:mail-activation-notice:backend:application
 // Tested-By:
 // - test:flow:relaunched-seat-mail-activation
+// - test:flow:inactive-mail-notice-diagnosable
 // Runtime: bun
 // Purpose: Name a Pi whose native mail is inactive; it never rewrites a binding.
 
+import { existsSync } from "node:fs";
 import { paths, readYaml, type Seat } from "./core";
+import type { MailActivation } from "./runtime-state";
 import { seatTasks, terminal } from "./tasks";
 
 /** The bound and live Pi sessions of a seat whose native mail cannot activate. */
 export type InactiveMail = { bound?: string; live?: string };
 
-/** Reads the seat binding at call time; a missing or unreadable seat has no bound session. */
-async function boundSession(root: string, seat: string) {
-  try { return (await readYaml<Seat>(paths(root).seatFile(seat))).runtime?.pi_session; } catch { return undefined; }
+/** The live identifiers a Pi compared with its seat binding; an unknown value is left undefined. */
+export type LiveIdentity = { pi_session?: string; herdr_session?: string; pane?: string };
+
+async function readSeat(root: string, seat: string) {
+  try { return await readYaml<Seat>(paths(root).seatFile(seat)); } catch { return undefined; }
 }
 
 /** Only a seat bound for native wake expects Pi to deliver its mail; host-wake seats are not warned. */
 export async function expectsNativeMail(root: string, seat: string) {
-  try { return (await readYaml<Seat>(paths(root).seatFile(seat))).runtime?.wake === "native"; } catch { return false; }
+  return (await readSeat(root, seat))?.runtime?.wake === "native";
 }
 
 /** The task coordinator to ask for a relaunch, or main of the seat's project when no open task names one. */
@@ -29,11 +34,39 @@ async function relaunchOwner(root: string, seat: string) {
   } catch { return `main@${project}`; }
 }
 
-/** One line for the agent: native mail will not arrive, with the bound and live sessions and the supported recovery. */
-export async function inactiveMailNotice(root: string, seat: string, live?: string) {
-  const bound = await boundSession(root, seat);
+function boundIdentity(record: Seat | undefined): MailActivation["bound"] {
+  const runtime = record?.runtime;
+  const locator = runtime?.addresses.herdr;
+  const scoped = typeof locator === "object" ? locator : undefined;
+  const receipt = runtime?.launch_receipt ? (existsSync(runtime.launch_receipt) ? "present" : "missing") : "none";
+  return { pi_session: runtime?.pi_session, herdr_session: scoped?.session, pane: scoped?.pane, receipt };
+}
+
+/** Compares the live identity with the seat binding at call time; an unknown live value counts as differing from a bound one. */
+export async function diagnoseMailActivation(root: string, seat: string, live: LiveIdentity, transport: MailActivation["transport"], error?: string): Promise<MailActivation> {
+  const bound = boundIdentity(await readSeat(root, seat));
+  const fields = [["session", live.pi_session, bound.pi_session], ["herdr", live.herdr_session, bound.herdr_session], ["pane", live.pane, bound.pane]] as const;
+  const differs = fields.filter(([, liveValue, boundValue]) => boundValue !== undefined && liveValue !== boundValue).map(([name]) => name);
+  return { at: new Date().toISOString(), transport, live, bound, differs, ...(error ? { error } : {}) };
+}
+
+/** The exact compared values, shared by the notice and `status seat`. */
+export function describeActivation(activation: MailActivation) {
+  const value = (entry?: string) => entry ?? "unknown";
+  const { live, bound } = activation;
+  return `live session=${value(live.pi_session)} herdr=${value(live.herdr_session)} pane=${value(live.pane)}; bound session=${value(bound.pi_session)} herdr=${value(bound.herdr_session)} pane=${value(bound.pane)} receipt=${bound.receipt}`;
+}
+
+/** Display-only text: INACTIVE only when the transport never started; a failed later startup step is reported as ACTIVE. */
+export async function activationNotice(root: string, seat: string, activation: MailActivation) {
+  const values = describeActivation(activation);
+  if (activation.transport === "active") {
+    return `SYSTEM: native Flow mail is ACTIVE for ${seat}; a startup step failed: ${activation.error ?? "unknown"}. Display only; no action is required for mail delivery. ${values}.`;
+  }
+  const differs = activation.differs.length ? ` Differs: ${activation.differs.join(", ")} (live does not match the binding).` : " All compared values match.";
+  const error = activation.error ? ` Last activation error: ${activation.error}.` : "";
   const owner = await relaunchOwner(root, seat);
-  return `SYSTEM: native Flow mail is INACTIVE for ${seat}: live Pi session ${live ?? "unknown"} does not match bound session ${bound ?? "none"}, or its launch receipt is missing. Queued mail will not reach this pane. Run atdd-flow status seat ${seat}; ask ${owner} to relaunch via atdd-flow pi runtime launch ${seat}.`;
+  return `SYSTEM: native Flow mail is INACTIVE for ${seat} (display only). ${values}.${differs}${error} Queued mail will not reach this pane. Run atdd-flow status seat ${seat}; ask ${owner} to relaunch via atdd-flow pi runtime launch ${seat}.`;
 }
 
 /** A fresh advisory runtime whose live session differs from the seat binding; legacy or matching records report nothing. */

package/src/overview.ts

@@ -2,7 +2,7 @@ import { readdir } from "node:fs/promises";
 import { canonicalAddress, desk, exists, paths, readYaml, type Checkpoint, type Seat } from "./core";
 import { type Task, type TaskHandoff, type TaskStatus, terminal } from "./tasks";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
-import { nativeMailInactive } from "./mail-activation-notice";
+import { describeActivation, nativeMailInactive } from "./mail-activation-notice";
 import { type Message, type Thread } from "./threads";
 
 type ListedTask = { project: string; id: string; task: Task; waiting: string[] };
@@ -357,6 +357,8 @@ async function seatDashboard(root: string, address: string) {
   if (advisory) console.log(`  pi advisory  ${isRuntimeStateStale(advisory, 60_000) ? "stale" : "active"} · ${advisory.model} · pid ${advisory.pid} · heartbeat ${advisory.heartbeat_at}`);
   const inactive = advisory && !isRuntimeStateStale(advisory, 60_000) ? nativeMailInactive(runtime?.pi_session, advisory.pi_session) : undefined;
   if (inactive) console.log(`  ${tone("native mail inactive", "WAITING")} (bound ${inactive.bound}, live ${inactive.live})`);
+  const activation = advisory && !isRuntimeStateStale(advisory, 60_000) ? advisory.mail_activation : undefined;
+  if (activation) console.log(`  native mail ${activation.transport}: ${describeActivation(activation)}${activation.differs.length ? `; differs ${activation.differs.join(", ")}` : ""}${activation.error ? `; error: ${activation.error}` : ""}`);
   rule("RESPONSIBILITIES", String(owned.length));
   if (!owned.length) console.log(`  ${muted("No task currently names this seat.")}`);
   for (const task of owned.slice(0, 6)) console.log(`  ${tone("●", taskPhase(task))} ${task.id}  ${taskPhase(task)}${task.task.assignee === resolved ? "  owner" : "  coordinator"}`);

package/src/runtime-state.ts

@@ -3,6 +3,16 @@ import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { addressParts, atomicYaml, yaml } from "./core";
 
+/** The values one activation attempt compared, as recorded for `status seat`; advisory and absent on legacy records. */
+export type MailActivation = {
+  at: string;
+  transport: "active" | "inactive";
+  live: { pi_session?: string; herdr_session?: string; pane?: string };
+  bound: { pi_session?: string; herdr_session?: string; pane?: string; receipt: "present" | "missing" | "none" };
+  differs: string[];
+  error?: string;
+};
+
 /**
  * A local, advisory observation of one runtime for one already-authoritative
  * Desk seat. This record is deliberately not a registry: it cannot select a
@@ -19,6 +29,7 @@ export type RuntimeState = {
   heartbeat_at: string;
   /** Live Pi session id when known; absent on legacy records. Advisory only: it never selects a recipient. */
   pi_session?: string;
+  mail_activation?: MailActivation;
 };
 
 export type RuntimeStateRegistration = Pick<RuntimeState, "seat" | "owner_token" | "pid" | "model" | "cwd"> & Partial<Pick<RuntimeState, "pi_session">>;
@@ -47,7 +58,8 @@ function valid(value: unknown): value is RuntimeState {
     && nonEmpty(record.cwd)
     && timestamp(record.started_at)
     && timestamp(record.heartbeat_at)
-    && (record.pi_session === undefined || nonEmpty(record.pi_session));
+    && (record.pi_session === undefined || nonEmpty(record.pi_session))
+    && (record.mail_activation === undefined || (typeof record.mail_activation === "object" && record.mail_activation !== null));
 }
 
 function assertRegistration(value: RuntimeStateRegistration) {
@@ -162,6 +174,18 @@ export async function heartbeatRuntimeState(root: string, seat: string, ownerTok
   });
 }
 
+/** Record the compared activation values only while this owner holds the record; the heartbeat and every other field are kept. */
+export async function recordMailActivation(root: string, seat: string, ownerToken: string, activation: MailActivation) {
+  if (!nonEmpty(ownerToken)) throw new Error("Runtime state requires a non-empty owner token.");
+  const file = runtimeStatePath(root, seat);
+  return exclusive(file, async () => {
+    const current = await readRuntimeState(root, seat);
+    if (!current || current.owner_token !== ownerToken) return false;
+    await atomicYaml(file, { ...current, mail_activation: activation });
+    return true;
+  });
+}
+
 /** Remove local advisory state only if this owner still owns it. */
 export async function clearRuntimeState(root: string, seat: string, ownerToken: string) {
   if (!nonEmpty(ownerToken)) throw new Error("Runtime state requires a non-empty owner token.");

package/src/tasks.ts

@@ -13,6 +13,7 @@ export type HandoffState = "executing" | "awaiting_coordinator" | "awaiting_assi
 export type TaskHandoff = { state: HandoffState; evidence: string; updated_at: string; submitted_phase?: TaskPhase };
 export type DoneWhen = { text: string; proof?: string };
 export type GovernedBase = { coordinator: string; branch: string; commit: string };
+export type LineageRef = { ref: string; commit: string; reason?: string };
 /** An append-only accountability decision; prior coordinator evidence remains untouched. */
 export type CoordinatorTransfer = {
   from: string;
@@ -21,6 +22,8 @@ export type CoordinatorTransfer = {
   /** Required when main executes the transfer; references an operator@desk message. */
   authorization?: string;
   exact_head: { branch: string; commit: string };
+  /** The driver ref used for the lineage check; HEAD means the recorded branch no longer resolved. */
+  lineage_ref?: LineageRef;
   effective_at: string;
 };
 export type TerminalDisposition = { kind: "superseded" | "rejected"; by: string; at: string; reason: string };
@@ -117,6 +120,23 @@ async function writeTask(root: string, projectName: string, id: string, task: Ta
 
 /** Records the exact parent head for new bounded topology without rewriting legacy tasks. */
 async function governedBase(root: string, projectName: string, coordinatorAddress: string, assignee?: string): Promise<GovernedBase | undefined> {
+  return (await governedLineage(root, projectName, coordinatorAddress, assignee))?.base;
+}
+
+/** The recorded branch when it resolves; otherwise the driver worktree HEAD; otherwise fail closed. */
+async function driverLineageRef(driver: Seat): Promise<LineageRef> {
+  const resolveRef = (ref: string) => runOutput(["git", "-C", driver.worktree, "rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  try { return { ref: driver.branch, commit: await resolveRef(driver.branch) }; }
+  catch {
+    if (!await exists(driver.worktree)) {
+      throw new Error(`Driver ${driver.address} branch ${driver.branch} no longer resolves and its worktree ${driver.worktree} is missing; cannot verify lineage.`);
+    }
+    try { return { ref: "HEAD", commit: await resolveRef("HEAD"), reason: `recorded branch ${driver.branch} no longer resolves; used worktree HEAD` }; }
+    catch { throw new Error(`Driver ${driver.address} branch ${driver.branch} no longer resolves and worktree ${driver.worktree} has no valid HEAD.`); }
+  }
+}
+
+async function governedLineage(root: string, projectName: string, coordinatorAddress: string, assignee?: string): Promise<{ base: GovernedBase; lineage: LineageRef } | undefined> {
   if (!assignee) return undefined;
   const config = await project(root, projectName);
   if (!config.repository) return undefined;
@@ -146,9 +166,10 @@ async function governedBase(root: string, projectName: string, coordinatorAddres
     throw new Error(`Task coordinator ${coordinator.address} must be main or a named coordinator.`);
   }
   const commit = await runOutput(["git", "-C", coordinator.worktree, "rev-parse", branch]);
-  const common = await runOutput(["git", "-C", driver.worktree, "merge-base", commit, driver.branch]);
+  const lineage = await driverLineageRef(driver);
+  const common = await runOutput(["git", "-C", driver.worktree, "merge-base", commit, lineage.commit]);
   if (common !== commit) throw new Error(`Driver ${driver.address} is not based on the exact coordinator head ${commit}.`);
-  return { coordinator: coordinator.address, branch, commit };
+  return { base: { coordinator: coordinator.address, branch, commit }, lineage };
 }
 
 /**
@@ -390,8 +411,9 @@ export async function transfer(root: string, projectName: string, id: string, ar
 
   // governedBase confirms main/named-coordinator identity, exact branch head,
   // and the driver's descendant relationship before accountability changes.
-  const base = await governedBase(root, projectName, target, task.assignee);
-  if (!base) throw new Error(`Task ${id} needs an assigned driver and governed repository before transfer.`);
+  const governed = await governedLineage(root, projectName, target, task.assignee);
+  const base = governed?.base;
+  if (!governed || !base) throw new Error(`Task ${id} needs an assigned driver and governed repository before transfer.`);
   const authorization = actor === main ? required(words(args, "--authorization"), "an owner-authorized topology plan") : undefined;
   if (authorization) await operatorAuthorization(root, authorization, main, {
     schema: "atdd-workflow/task-transfer-authorization/v1",
@@ -408,6 +430,7 @@ export async function transfer(root: string, projectName: string, id: string, ar
     reason: required(words(args, "--reason"), "--reason"),
     ...(authorization ? { authorization } : {}),
     exact_head: { branch: base.branch, commit: base.commit },
+    lineage_ref: governed.lineage,
     effective_at: now(),
   };
   task.coordinator = target;