@afokapu/atdd-flow 0.3.63 → 0.3.64

package/extensions/pi/index.ts

@@ -6,7 +6,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, recordMailActivation, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
 import { paths, readYaml, type Seat } from "../../src/core";
 import { activationNotice, diagnoseMailActivation, expectsNativeMail } from "../../src/mail-activation-notice";
-import { type NoticeState, createNoticeState, refreshDelivered, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
+import { type NoticeState, createNoticeState, refreshDelivered, sendSettledDirective, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
 import { handoverThresholdInstruction, runtimeStartupInstruction, successorInstruction } from "../../src/collaboration-policy";
 import { type RecoveryMode, recoveryFor } from "../../src/recovery-bundle";
 import { contextHandoverThreshold, readHandoverReplacement } from "../../src/handover";
@@ -382,7 +382,11 @@ export default function (pi: ExtensionAPI) {
     return message ? { message: message as typeof event.message } : undefined;
   });
   // Nothing queued survives a settled run, so a pending flag left by a cleared queue cannot suppress future notices.
-  pi.on("agent_settled", () => { notices.pending = false; });
+  pi.on("agent_settled", async () => {
+    notices.pending = false;
+    // Run completion is not task completion; one bounded continuation per unchanged directive.
+    await sendSettledDirective(host, root, seat, notices);
+  });
   pi.on("turn_end", async (_event, ctx) => {
     if (handoverPrompted) return;
     const percent = ctx.getContextUsage()?.percent;

package/package.json

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

package/src/cli.ts

@@ -19,6 +19,7 @@ import { multiplexer } from "./multiplexer";
 import * as cleanup from "./ephemeral-resources";
 import * as ownerAlerts from "./owner-escalations";
 import { recoveryFor } from "./recovery-bundle";
+import { reconcileOnce } from "./reconcile";
 import { recordHandover, requestHandoverReplacement, resumedHandoverReplacement, showHandover } from "./handover";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
@@ -65,6 +66,7 @@ Usage:
   atdd-flow task open <project> <task-id>
   atdd-flow cleanup status <project>
   atdd-flow cleanup checklist <project> <task-id>
+  atdd-flow reconcile --once [--dry-run]
   atdd-flow owner-alert scan --by <coordinator-or-main> [--re-notify-after-ms <milliseconds>]
   atdd-flow owner-alert deliver|acknowledge|execute|resolve <alert-id> --by <address> [--note <text>|--option <id>|--reason <text>]
   atdd-flow thread start --with <address,...> --subject <text> [--task <project/task-id>]
@@ -166,6 +168,12 @@ async function main() {
       if (subcommand === "checklist") return console.log(await cleanup.checklist(root, { project: required(projectName, "project"), task: required(taskId, "task id") }));
       throw new Error("Use `atdd-flow cleanup status <project>` or `atdd-flow cleanup checklist <project> <task-id>`.");
     },
+    reconcile: async () => {
+      if (!rest.includes("--once") || rest.some((value) => value !== "--once" && value !== "--dry-run"))
+        throw new Error("Use `atdd-flow reconcile --once [--dry-run]`.");
+      process.stdout.write(Bun.YAML.stringify(await reconcileOnce(root, { dryRun: rest.includes("--dry-run") })));
+      return;
+    },
     "owner-alert": async () => {
       const [subcommand, alertId, ...tail] = rest;
       if (subcommand === "scan") {

package/src/next-action-notices.ts

@@ -14,6 +14,8 @@ export type NoticeState = {
   /** A next-action follow-up has been queued and not yet delivered. */
   pending: boolean;
   lastDelivered?: string;
+  /** One automatic post-settlement continuation per unchanged directive. */
+  settledNudged?: string;
   /** Blocker notices already delivered this session, keyed by task and blocker text. */
   blockers: Set<string>;
   /** Mail ids already notified this session. */
@@ -50,19 +52,46 @@ export async function sendTaskDirective(host: NoticeHost, root: string, seat: st
   }
 }
 
+/** A settled model turn is not task completion. Give one additional nudge for a
+ * still-actionable directive, but never loop on unchanged task state. */
+export async function sendSettledDirective(host: NoticeHost, root: string, seat: string, state: NoticeState) {
+  if (state.pending) return;
+  try {
+    const directive = await nextDirective(root, seat);
+    if (!directive?.command) return; // Waiting for an authority or dependency is not work for this seat.
+    const key = directiveKey(directive);
+    if (key !== state.lastDelivered) return sendTaskDirective(host, root, seat, state);
+    if (state.settledNudged === key) return;
+    state.settledNudged = key;
+    state.pending = true;
+    host.sendMessage({
+      customType: "atdd-flow-next-action",
+      content: directiveNotice(seat, directive),
+      display: true,
+      details: { ...directiveDetails(directive), continuation: true },
+    }, { triggerTurn: true, deliverAs: "followUp" });
+  } catch { state.pending = false; }
+}
+
 /** Re-derives a held next-action follow-up when Pi delivers it; a queued message cannot be dropped, so it is replaced by the shortest truthful text. */
 async function currentDirective(root: string, seat: string, state: NoticeState, message: NoticeMessage): Promise<NoticeMessage> {
   state.pending = false;
   const directive = await nextDirective(root, seat).catch(() => undefined);
   if (!directive) {
     state.lastDelivered = undefined;
+    state.settledNudged = undefined;
     return { ...message, content: `SYSTEM: next-action notice for ${seat} withdrawn: task state has no actionable step. Task state outranks mail.`, details: { authority: "task", lifecycle: "NONE" } };
   }
   const key = directiveKey(directive);
   if (key === state.lastDelivered) {
+    if (message.details?.continuation === true && directive.command) {
+      return { ...message, content: `${directiveNotice(seat, directive)} The task remains open. Continue or escalate a real blocker; do not stop merely because this turn ended.`,
+        details: { ...directiveDetails(directive), continuation: true } };
+    }
     return { ...message, content: `SYSTEM: next action for ${seat} unchanged on ${directive.project}/${directive.task} [${directive.lifecycle}]; see the previous notice.`, details: directiveDetails(directive) };
   }
   state.lastDelivered = key;
+  state.settledNudged = undefined;
   if (directive.lifecycle === "BLOCKED") state.blockers.add(key);
   return { ...message, content: directiveNotice(seat, directive), details: directiveDetails(directive) };
 }

package/src/reconcile.ts

@@ -0,0 +1,151 @@
+// URN: component:flow:e012:reconcile:backend:application
+// Tested-By:
+// - test:flow:continuation:E012-UNIT-001
+// Runtime: bun
+// Purpose: Wake idle owners of existing actionable Flow obligations.
+import { createHash } from "node:crypto";
+import { mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { notify } from "./adapters";
+import { type HerdrLocator, type Seat, atomicYaml, paths, readYaml, runOutput } from "./core";
+import { type TaskDirective, directiveNotice, nextDirective } from "./tasks";
+import { isRuntimeStateStale, readRuntimeState, withOwnedRuntimeState } from "./runtime-state";
+
+type Outcome = "woke" | "dry_run" | "cooldown" | "exhausted" | "inactive" | "unverified" | "busy" | "replaced" | "wake_failed";
+export type Reconciliation = { seat: string; task: string; outcome: Outcome };
+export type ReconcileOptions = {
+  now?: Date;
+  dryRun?: boolean;
+  cooldownMs?: number;
+  maxNudges?: number;
+  inspect?: (locator: HerdrLocator, seat: string) => Promise<string>;
+  wake?: (locator: HerdrLocator, notice: string) => Promise<void>;
+};
+
+type Attempt = { schema: "atdd-flow/continuation-attempt/v1"; key: string; at: string; count: number };
+type Target = { owner: Seat; directive: TaskDirective; locator: HerdrLocator; token: string };
+type Settings = Required<Pick<ReconcileOptions, "now" | "cooldownMs" | "maxNudges" | "inspect" | "wake">> & { dryRun: boolean };
+
+const agentName = (address: string) => `flow-${address.replace(/[^a-z0-9_-]/gi, "-").toLowerCase()}`.slice(0, 32);
+const fingerprint = (target: Target) =>
+  createHash("sha256").update(JSON.stringify({ directive: target.directive, session: target.owner.runtime?.pi_session, owner: target.token })).digest("hex");
+const attemptFile = (root: string, address: string) =>
+  join(root, ".atdd-flow", "continuation", `${encodeURIComponent(address)}.yaml`);
+
+/** Read Herdr status without treating missing or mismatched identities as healthy.
+ * The live host is an observation surface, never a seat registry.
+ */
+async function inspectHerdr(locator: HerdrLocator, address: string) {
+  const raw = JSON.parse(await runOutput(["herdr", "--session", locator.session, "agent", "get", agentName(address)]));
+  const envelope = raw?.result ?? raw;
+  const agent = envelope?.agent ?? envelope;
+  if (agent?.name !== agentName(address) || agent?.pane_id !== locator.pane) return "unverified";
+  return String(agent?.agent_status ?? agent?.status ?? agent?.state ?? "unverified").toLowerCase();
+}
+
+/** Discover durable seat identity from the existing Desk directories.
+ * No second fleet registry is created or synchronized.
+ */
+async function seats(root: string): Promise<Seat[]> {
+  const found: Seat[] = [];
+  for (const project of await readdir(paths(root).work, { withFileTypes: true })) {
+    if (!project.isDirectory()) continue;
+    for (const local of await readdir(paths(root).seats(project.name), { withFileTypes: true }).catch(() => [])) {
+      if (!local.isDirectory()) continue;
+      found.push(await readYaml<Seat>(join(paths(root).seats(project.name), local.name, "seat.yaml")));
+    }
+  }
+  return found;
+}
+
+function validateLimits(cooldownMs: number, maxNudges: number) {
+  if (!Number.isFinite(cooldownMs) || cooldownMs < 0) throw new Error("Invalid continuation cooldown.");
+  if (!Number.isInteger(maxNudges) || maxNudges < 1) throw new Error("Invalid maximum nudge count.");
+}
+
+function settings(options: ReconcileOptions): Settings {
+  const cooldownMs = options.cooldownMs ?? 5 * 60_000;
+  const maxNudges = options.maxNudges ?? 2;
+  validateLimits(cooldownMs, maxNudges);
+  return {
+    now: options.now ?? new Date(),
+    dryRun: options.dryRun ?? false,
+    cooldownMs, maxNudges,
+    inspect: options.inspect ?? inspectHerdr,
+    wake: options.wake ?? ((locator, notice) => notify("herdr", locator.pane, notice, locator.session)),
+  };
+}
+
+const outcome = (owner: Seat, directive: TaskDirective, status: Outcome): Reconciliation =>
+  ({ seat: owner.address, task: `${directive.project}/${directive.task}`, outcome: status });
+
+/** An actionable target also needs a live, matching runtime observation.
+ * This deliberately refuses an unknown or stale session rather than guessing.
+ */
+async function target(root: string, owner: Seat, directive: TaskDirective, at: Date): Promise<Target | undefined> {
+  const runtime = owner.runtime;
+  const locator = runtime?.addresses.herdr;
+  if (runtime?.application !== "herdr" || !locator || typeof locator === "string") return;
+  const active = await readRuntimeState(root, owner.address);
+  if (!active) return;
+  if (isRuntimeStateStale(active, 60_000, at)) return;
+  if (runtime.pi_session && active.pi_session !== runtime.pi_session) return;
+  return { owner, directive, locator, token: active.owner_token };
+}
+
+/** The per-seat retry memo is advisory: changing work or replacing an agent
+ * starts a new key, while unchanged instructions have bounded retries.
+ */
+function attemptDisposition(previous: Attempt | undefined, key: string, config: Settings): Outcome | undefined {
+  if (previous?.schema !== "atdd-flow/continuation-attempt/v1") return;
+  if (previous.key !== key) return;
+  if (previous.count >= config.maxNudges) return "exhausted";
+  if (config.now.getTime() - Date.parse(previous.at) < config.cooldownMs) return "cooldown";
+}
+
+/** Write the attempt before contacting Herdr, so a transient host failure
+ * cannot turn repeated reconciliation into a prompt storm.
+ */
+async function wakeOnce(root: string, candidate: Target, config: Settings): Promise<Outcome> {
+  const file = attemptFile(root, candidate.owner.address);
+  const key = fingerprint(candidate);
+  const previous = await readYaml<Attempt>(file).catch(() => undefined);
+  const suppressed = attemptDisposition(previous, key, config);
+  if (suppressed) return suppressed;
+  const count = previous?.key === key ? previous.count + 1 : 1;
+  await mkdir(join(root, ".atdd-flow", "continuation"), { recursive: true });
+  await atomicYaml(file, { schema: "atdd-flow/continuation-attempt/v1", key, at: config.now.toISOString(), count } satisfies Attempt);
+  try {
+    await config.wake(candidate.locator, `${directiveNotice(candidate.owner.address, candidate.directive)} The task remains open. Continue within your authority; escalate a real blocker rather than ending the obligation.`);
+    return "woke";
+  } catch { return "wake_failed"; }
+}
+
+async function reconcileSeat(root: string, owner: Seat, config: Settings): Promise<Reconciliation | undefined> {
+  if (owner.retired) return;
+  const directive = await nextDirective(root, owner.address);
+  // A directive without a command is a legitimate wait on another actor.
+  if (!directive?.command) return;
+  const candidate = await target(root, owner, directive, config.now);
+  if (!candidate) return outcome(owner, directive, "inactive");
+  let status: string;
+  try { status = await config.inspect(candidate.locator, owner.address); }
+  catch { return outcome(owner, directive, "unverified"); }
+  if (status === "unverified") return outcome(owner, directive, "unverified");
+  if (status !== "idle" && status !== "done") return outcome(owner, directive, "busy");
+  if (config.dryRun) return outcome(owner, directive, "dry_run");
+  // Serialize with a live runtime's token-fenced wake; a replacement cannot be prompted.
+  const result = await withOwnedRuntimeState(root, owner.address, candidate.token, () => wakeOnce(root, candidate, config));
+  return outcome(owner, directive, result.owned ? result.value : "replaced");
+}
+
+/** One-shot, advisory fleet reconciliation. Task state remains the sole work authority. */
+export async function reconcileOnce(root: string, options: ReconcileOptions = {}): Promise<Reconciliation[]> {
+  const config = settings(options);
+  const results: Reconciliation[] = [];
+  for (const owner of await seats(root)) {
+    const result = await reconcileSeat(root, owner, config);
+    if (result) results.push(result);
+  }
+  return results;
+}