@afokapu/atdd-flow 0.3.58 → 0.3.60

package/extensions/pi/index.ts

@@ -5,6 +5,7 @@ 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 { paths, readYaml, type Seat } from "../../src/core";
+import { expectsNativeMail, inactiveMailNotice } 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";
@@ -44,6 +45,8 @@ export type PiRuntimeOptions = {
   heartbeatMs?: number;
   staleAfterMs?: number;
   deliver: InboxOptions["deliver"];
+  /** Live Pi session id recorded on the advisory runtime state for status seat. */
+  piSession?: string;
   createTransport?: (options: InboxOptions) => FlowInboxTransport;
   /** Flow-launched Pi instances register and heartbeat before their verified launch activates inbox delivery. */
   deferActivation?: boolean;
@@ -236,7 +239,7 @@ export const createInboxReconciler = createInboxTransport;
  */
 export function createPiRuntime({
   root, seat, pid = process.pid, model = process.env.PI_MODEL ?? "pi", cwd = process.cwd(),
-  heartbeatMs = defaultHeartbeatMs, staleAfterMs = defaultStaleAfterMs, deliver, createTransport = createInboxTransport, deferActivation = false,
+  heartbeatMs = defaultHeartbeatMs, staleAfterMs = defaultStaleAfterMs, deliver, piSession, createTransport = createInboxTransport, deferActivation = false,
 }: PiRuntimeOptions) {
   const ownerToken = runtimeOwnerToken();
   let transport: FlowInboxTransport | undefined;
@@ -283,7 +286,7 @@ export function createPiRuntime({
     // This removes only an expired local observation. Registration itself is
     // replacement-safe and does not alter the authoritative Desk seat.
     await clearStaleRuntimeState(root, seat, staleAfterMs);
-    await registerRuntimeState(root, { seat, owner_token: ownerToken, pid, model, cwd });
+    await registerRuntimeState(root, { seat, owner_token: ownerToken, pid, model, cwd, ...(piSession ? { pi_session: piSession } : {}) });
     heartbeat = setInterval(() => {
       void heartbeatRuntimeState(root, seat, ownerToken).then((state) => {
         if (!state) void stop();
@@ -296,6 +299,11 @@ export function createPiRuntime({
 
 type LaunchReceipt = { seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string };
 
+/** The bounded window ended without a verified receipt and matching binding. */
+export class ActivationTimeout extends Error {
+  constructor() { super("Timed out waiting for verified Flow launch receipt and binding."); }
+}
+
 /** 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;
@@ -316,7 +324,7 @@ export async function awaitLaunchActivation({ root, seat, piSession, herdrSessio
     } catch { /* Binding and receipt are written after Herdr verification; wait within this finite window. */ }
     await pause(intervalMs);
   }
-  throw new Error("Timed out waiting for verified Flow launch receipt and binding.");
+  throw new ActivationTimeout();
 }
 
 /**
@@ -393,7 +401,17 @@ export default function (pi: ExtensionAPI) {
     } catch { /* No validated replacement request exists for this source session. */ }
   });
   pi.on("session_start", async (_event, ctx) => {
-    runtime = createPiRuntime({ root, seat, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
+    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" });
+    };
+    runtime = createPiRuntime({ root, seat, piSession: liveSession, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
       if (!sendIfOwned) return false;
       if (hostActivatedAt !== undefined && Date.parse(typeof mail.created_at === "string" ? mail.created_at : "") < hostActivatedAt) return sendIfOwned(async () => undefined);
       const notify = typeof mail.id === "string" && typeof thread.id === "string" && await shouldNotifyMail(root, seat, notices, thread.id, mail.id);
@@ -412,7 +430,6 @@ export default function (pi: ExtensionAPI) {
     const herdrSession = process.env.ATDD_FLOW_HERDR_SESSION;
     const pane = process.env.ATDD_FLOW_HERDR_PANE;
     if (!piSession && !herdrSession && !pane) {
-      const sessionManager = (ctx as { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } }).sessionManager;
       if (await hostAttachedActivation({ root, seat, herdrSession: process.env.HERDR_SESSION, pane: process.env.HERDR_PANE_ID, piSession: sessionManager?.getSessionId?.(), piSessionPath: sessionManager?.getSessionFile?.() })) {
         hostActivatedAt = Date.now();
         if (await runtime.activate()) {
@@ -420,7 +437,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();
       return;
     }
     if (!piSession || !herdrSession || !pane) return;
@@ -443,7 +460,7 @@ 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(() => undefined);
+    }).catch((error) => error instanceof ActivationTimeout ? noticeInactive() : undefined);
   });
   pi.on("session_shutdown", () => { void runtime?.stop(); });
 }

package/package.json

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

package/src/core.ts

@@ -25,6 +25,8 @@ export type Desk = {
   /** Named commands that model portfolio entries may resolve through. */
   executables?: Record<string, string>;
   aliases?: Record<string, string>;
+  /** Model id used for a role when launch model selection falls back; unlisted roles use the strongest candidate. */
+  fallback_model?: Record<string, string>;
 };
 export type ModelCandidate = {
   id: string;

package/src/mail-activation-notice.ts

@@ -0,0 +1,42 @@
+// URN: component:flow:e009:mail-activation-notice:backend:application
+// Tested-By:
+// - test:flow:relaunched-seat-mail-activation
+// Runtime: bun
+// Purpose: Name a Pi whose native mail is inactive; it never rewrites a binding.
+
+import { paths, readYaml, type Seat } from "./core";
+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; }
+}
+
+/** 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; }
+}
+
+/** The task coordinator to ask for a relaunch, or main of the seat's project when no open task names one. */
+async function relaunchOwner(root: string, seat: string) {
+  const project = seat.slice(seat.lastIndexOf("@") + 1);
+  try {
+    const open = (await seatTasks(root, project, seat)).find((entry) => entry.task.assignee === seat && !terminal(entry.task));
+    return open?.task.coordinator ?? `main@${project}`;
+  } 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);
+  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}.`;
+}
+
+/** A fresh advisory runtime whose live session differs from the seat binding; legacy or matching records report nothing. */
+export function nativeMailInactive(bound: string | undefined, live: string | undefined): InactiveMail | undefined {
+  return bound && live && bound !== live ? { bound, live } : undefined;
+}

package/src/overview.ts

@@ -2,6 +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 { type Message, type Thread } from "./threads";
 
 type ListedTask = { project: string; id: string; task: Task; waiting: string[] };
@@ -354,6 +355,8 @@ async function seatDashboard(root: string, address: string) {
   for (const [application, nativeAddress] of Object.entries(runtime?.addresses ?? {})) console.log(`  ${application}${application === runtime?.application ? " *" : "  "} ${nativeAddress}`);
   const advisory = await readRuntimeState(root, resolved);
   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})`);
   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/pi-runtime-launch.ts

@@ -38,6 +38,10 @@ export type PiRuntimeLaunchDependencies = {
   command?: (command: string[]) => Promise<string>;
   sessionId?: () => string;
   at?: () => string;
+  /** Pause between session-path polls; injectable so tests need no real delay. */
+  sleep?: (milliseconds: number) => Promise<void>;
+  /** How long Herdr may take to report the exact session path after start. */
+  sessionPathWindowMs?: number;
 };
 
 type Bind = (root: string, address: string, args: string[], selectedModel?: string, wake?: Runtime["wake"], piSession?: string, piSessionPath?: string, launchReceipt?: string) => Promise<void>;
@@ -108,6 +112,15 @@ async function launchEligibleTasks(root: string, record: Seat, address: string)
   return eligible.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry));
 }
 
+/** Fallback is the role's configured model when set (failing closed if unavailable), else the strongest candidate. */
+function fallbackCandidate(config: Desk, role: string, candidates: ModelCandidate[], reason: string) {
+  const configured = config.fallback_model?.[role];
+  if (configured === undefined) return { candidate: candidates[0]! };
+  const candidate = candidates.find((entry) => entry.id === configured);
+  if (!candidate) throw new Error(`fallback_model.${role} names "${configured}", which is not an enabled model with an available executable in models.yaml; refusing launch.`);
+  return { candidate, appliedFallback: { role, model: candidate.id, reason } };
+}
+
 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.");
@@ -128,7 +141,7 @@ async function chooseLaunchModel(root: string, config: Desk, record: Seat, portf
     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 { selection, fallback: reason, ...fallbackCandidate(config, record.role, candidates, reason) };
   }
   return { candidate: required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`), selection };
 }
@@ -373,24 +386,41 @@ function assertVerifiedProcess(launch: PreparedLaunch, pane: string, agent: Retu
   }
 }
 
-/** Corroborate the started runtime through agent, pane, and process reports. */
-async function verifyRuntime(launch: PreparedLaunch, pane: string, priorPath?: string) {
+const sessionPathPollMs = 250;
+const defaultSessionPathWindowMs = 10_000;
+
+async function readRuntimeReports(launch: PreparedLaunch, pane: string) {
   const { command, options, resolved } = launch;
   const [agentRaw, paneRaw, processRaw] = await Promise.all([
     command(herdr(options.herdrSession, "agent", "get", agentName(resolved))),
     command(herdr(options.herdrSession, "pane", "get", pane)),
     command(herdr(options.herdrSession, "pane", "process-info", "--pane", pane)),
   ]);
-  const agent = agentReport(JSON.parse(agentRaw)), verifiedPane = paneReport(JSON.parse(paneRaw));
-  const verifiedProcess = piProcess(processReport(JSON.parse(processRaw)).processes);
-  const sessionPath = assertVerifiedSession(launch, verifiedPane, priorPath);
-  assertVerifiedProcess(launch, pane, agent, verifiedPane, verifiedProcess);
+  return { agent: agentReport(JSON.parse(agentRaw)), verifiedPane: paneReport(JSON.parse(paneRaw)), verifiedProcess: piProcess(processReport(JSON.parse(processRaw)).processes) };
+}
+
+/**
+ * Corroborate the started runtime through agent, pane, and process reports. Only an absent session path is
+ * polled again, within a bounded window: Herdr may report it a moment after the process starts. Every other
+ * mismatch, and a path still absent when the window ends, fails closed without changing the seat binding.
+ */
+async function verifyRuntime(launch: PreparedLaunch, pane: string, priorPath?: string) {
+  const { dependencies } = launch;
+  const sleep = dependencies.sleep ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
+  const polls = Math.floor((dependencies.sessionPathWindowMs ?? defaultSessionPathWindowMs) / sessionPathPollMs);
+  let reports = await readRuntimeReports(launch, pane);
+  for (let poll = 0; poll < polls && !reports.verifiedPane.sessionPath; poll += 1) {
+    await sleep(sessionPathPollMs);
+    reports = await readRuntimeReports(launch, pane);
+  }
+  const sessionPath = assertVerifiedSession(launch, reports.verifiedPane, priorPath);
+  assertVerifiedProcess(launch, pane, reports.agent, reports.verifiedPane, reports.verifiedProcess);
   return sessionPath;
 }
 
 function receiptSelection(launch: PreparedLaunch) {
   const { selection } = launch;
-  if (selection.fallback) return { result: "fallback", reason: selection.fallback };
+  if (selection.fallback) return { result: "fallback", reason: selection.fallback, ...(selection.appliedFallback ? { applied_fallback: selection.appliedFallback } : {}) };
   return { result: "selected", confidence: selection.selection.confidence,
     ...(selection.selection.available && selection.selection.model ? { model: selection.selection.model } : {}) };
 }

package/src/runtime-state.ts

@@ -17,9 +17,11 @@ export type RuntimeState = {
   cwd: string;
   started_at: string;
   heartbeat_at: string;
+  /** Live Pi session id when known; absent on legacy records. Advisory only: it never selects a recipient. */
+  pi_session?: string;
 };
 
-export type RuntimeStateRegistration = Pick<RuntimeState, "seat" | "owner_token" | "pid" | "model" | "cwd">;
+export type RuntimeStateRegistration = Pick<RuntimeState, "seat" | "owner_token" | "pid" | "model" | "cwd"> & Partial<Pick<RuntimeState, "pi_session">>;
 
 const schema = "atdd-flow/pi-runtime-state/v1" as const;
 const lockStaleMs = 5 * 60_000;
@@ -44,7 +46,8 @@ function valid(value: unknown): value is RuntimeState {
     && nonEmpty(record.model)
     && nonEmpty(record.cwd)
     && timestamp(record.started_at)
-    && timestamp(record.heartbeat_at);
+    && timestamp(record.heartbeat_at)
+    && (record.pi_session === undefined || nonEmpty(record.pi_session));
 }
 
 function assertRegistration(value: RuntimeStateRegistration) {