@afokapu/atdd-flow 0.3.73 → 0.3.75

package/package.json

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

package/src/adoption-authorizations.ts

@@ -22,19 +22,47 @@ export type ExactSessionAdoptionAuthorization = {
   target: { herdr_session: string; pane: string; cwd: string };
 };
 
+// Ids are path components, so only A- plus a safe charset is accepted; this blocks traversal.
 const validId = (value: string) => /^A-[A-Za-z0-9_-]+$/.test(value);
+// A blank value can never bind an adoption, so whitespace-only strings count as missing.
 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`);
+// Records and their digests live side by side in one create-only directory.
+function authorizationDir(root: string) {
+  return join(root, ".atdd-flow", "exact-session-adoption-authorizations");
+}
+function path(root: string, id: string) {
+  return join(authorizationDir(root), `${id}.yaml`);
+}
+function hashPath(root: string, id: string) {
+  return join(authorizationDir(root), `${id}.sha256`);
+}
+// SHA-256 of the exact record bytes; any later edit changes the digest.
 const digest = (content: string) => createHash("sha256").update(content).digest("hex");
 
+// The tuple check is split by concern so every predicate stays small and independently readable.
+function validHeader(record: ExactSessionAdoptionAuthorization) {
+  return record.schema === authorizationSchema && validId(record.id) && record.issued_by === "operator@desk" && nonEmpty(record.created_at);
+}
+// Seat and Pi session identity must be present.
+function validSubject(record: ExactSessionAdoptionAuthorization) {
+  return nonEmpty(record.seat) && nonEmpty(record.pi_session) && nonEmpty(record.pi_session_path);
+}
+// The source Herdr placement must be present.
+function validSource(record: ExactSessionAdoptionAuthorization) {
+  return nonEmpty(record.source?.herdr_session) && nonEmpty(record.source?.pane);
+}
+// The target Herdr placement and working directory must be present.
+function validTarget(record: ExactSessionAdoptionAuthorization) {
+  return nonEmpty(record.target?.herdr_session) && nonEmpty(record.target?.pane) && nonEmpty(record.target?.cwd);
+}
 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);
+  return validHeader(record) && validSubject(record) && validSource(record) && validTarget(record);
 }
 
+/**
+ * Issue a create-only operator authorization: the record and its digest are written with the `wx` flag,
+ * so an existing id can never be overwritten or silently reissued with a different tuple.
+ */
 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.");
@@ -53,40 +81,75 @@ export async function createExactSessionAdoptionAuthorization(root: string, id:
   process.stdout.write(`${id}\n`);
 }
 
-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;
+// The adoption tuple a launch asks to use; the stored record must match it field for field.
+type ExpectedTuple = Omit<ExactSessionAdoptionAuthorization, "schema" | "id" | "issued_by" | "created_at">;
+
+// The operator-issued record must bind every element of the adoption tuple, not a subset.
+// Seat and Pi session identity.
+function sameSubject(record: ExactSessionAdoptionAuthorization, expected: ExpectedTuple) {
+  return record.seat === expected.seat && record.pi_session === expected.pi_session && record.pi_session_path === expected.pi_session_path;
+}
+// Where the session runs before the move.
+function sameSource(record: ExactSessionAdoptionAuthorization, expected: ExpectedTuple) {
+  return record.source.herdr_session === expected.source.herdr_session && record.source.pane === expected.source.pane;
+}
+// Where the session will run after the move, including its working directory.
+function sameTarget(record: ExactSessionAdoptionAuthorization, expected: ExpectedTuple) {
+  return record.target.herdr_session === expected.target.herdr_session && record.target.pane === expected.target.pane && record.target.cwd === expected.target.cwd;
+}
+function same(record: ExactSessionAdoptionAuthorization, expected: ExpectedTuple) {
+  return sameSubject(record, expected) && sameSource(record, expected) && sameTarget(record, expected);
+}
+
+// Narrow an unknown YAML value to a plain object so nested receipt fields can be read without casts.
+const asRecord = (value: unknown): Record<string, unknown> | undefined => (value && typeof value === "object" ? (value as Record<string, unknown>) : undefined);
+
+// A receipt names an authorization when relocation.authorization.id equals the id.
+function receiptNames(receipt: unknown, id: string) {
+  return asRecord(asRecord(asRecord(receipt)?.relocation)?.authorization)?.id === id;
+}
+
+// A receipt that cannot be read or parsed never authorizes reuse, so it counts as not naming the id.
+async function receiptFileNames(file: string, id: string) {
+  try { return receiptNames(yaml.parse<unknown>(await readFile(file, "utf8")), id); }
+  catch { return false; }
 }
 
+// A receipt that already names this authorization id means the one-shot authorization was consumed.
 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. */ }
+  let files: string[];
+  try { files = await readdir(folder); }
+  catch { return false; } // No previous receipt means unused.
+  for (const file of files.filter((entry) => entry.endsWith(".yaml"))) {
+    if (await receiptFileNames(join(folder, file), id)) return true;
+  }
   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.");
+// Each reader fails with the same operator-facing message the combined resolver always used.
+async function readRecord(root: string, id: string) {
   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); }
+  try { return { raw, record: yaml.parse<ExactSessionAdoptionAuthorization>(raw) }; }
   catch { throw new Error("Exact-session adoption requires a well-formed immutable operator authorization record."); }
+}
+
+// The digest written next to the record at creation proves the record was never edited afterwards.
+async function readStoredHash(root: string, id: string, raw: string) {
   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.");
+  return storedHash;
+}
+
+/** Resolve only a create-only operator record whose complete tuple matches before runtime projection. */
+export async function resolveExactSessionAdoptionAuthorization(root: string, id: string, expected: ExpectedTuple) {
+  if (!validId(id)) throw new Error("Exact-session adoption requires an immutable operator authorization record id.");
+  const { raw, record } = await readRecord(root, id);
+  const storedHash = await readStoredHash(root, id, raw);
   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/handover.ts

@@ -745,7 +745,7 @@ export async function requestHandoverReplacement(root: string, address: string,
     source: { herdr_session: intent.source.herdr_session, pane: intent.source.pane }, target: intent.target,
   });
   const legacySource = intent.legacy ? await verifyLegacySource(intent.source, intent.target, authorization.hash, dependencies) : undefined;
-  const recovery = intent.recover ? await buildStaleMainRecovery(root, resolved, intent, { file, isLive: (prior) => replacementMatchesRuntime(intent.record.runtime, prior) }, (canonical) => verifyLegacySource(intent.source, intent.target, authorization.hash, dependencies, canonical)) : undefined;
+  const recovery = intent.recover ? await buildStaleMainRecovery(root, resolved, intent, { file, isLive: (prior) => replacementMatchesRuntime(intent.record.runtime, prior) }, (canonical, once) => verifyLegacySource(intent.source, intent.target, authorization.hash, once(dependencies), canonical)) : undefined;
   const request = { ...replacementRequest(resolved, intent, authorization, legacySource, dependencies), ...(recovery ? { stale_main_recovery: recovery } : {}) };
   await (recovery?.prior_request ? replaceActiveRequest : dependencies.publish ?? publishCreateOnly)(file, yaml.print(request));
   console.log(`Recorded Path-A replacement request for ${resolved}.`);

package/src/stale-main-recovery.ts

@@ -3,13 +3,14 @@
 // - test:atdd-flow:stale-main-binding-recovery
 // - test:atdd-flow:stale-main-recovery-resumed
 // - test:atdd-flow:stale-main-source-exited-path-a
+// - test:atdd-flow:stale-main-s1-exited-recovery
 // Runtime: bun
 // Purpose: Evidence rules for operator-authorized stale-main Pi binding recovery.
 
 import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { type Runtime, type Seat, yaml } from "./core";
+import { type Runtime, type Seat, runOutput, yaml } from "./core";
 import type { HandoverReplacementRequest, LiveSourceProof } from "./handover";
 
 /**
@@ -20,14 +21,15 @@ import type { HandoverReplacementRequest, LiveSourceProof } from "./handover";
 export type StaleMainRecovery = {
   canonical_source: { pi_session: string; pi_session_path: string; herdr_session: string; pane: string; cwd: string; launch_receipt: string };
   prior_receipt: { path: string; sha256: string; archive: string };
-  /** A superseded active request that no longer matches the recorded runtime, preserved by hash. */
-  prior_request?: { path: string; sha256: string; archive: string; source_exited?: SourceExited };
+  /** A superseded active request, preserved by hash; `live_source_exited` proves an active recovery request's own live source Pi was absent from every live Pi agent when a newer source replaced it. */
+  prior_request?: { path: string; sha256: string; archive: string; source_exited?: SourceExited; live_source_exited?: SourceExited };
   live_source: LiveSourceProof;
 };
 
 /** Proof that a runtime-matching prior request's recorded source Pi was absent from every live Pi agent when it was replaced. */
 export type SourceExited = { pi_session: string; pi_session_path: string; herdr_session: string; pane: string; verified_at: string };
 
+type Run = (argv: string[]) => Promise<string>;
 type Source = HandoverReplacementRequest["source"];
 type Target = HandoverReplacementRequest["target"];
 type PriorReceipt = { schema?: string; seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string };
@@ -94,14 +96,36 @@ async function archiveBytes(root: string, folder: string, seat: string, bytes: s
  * matches is replaceable only when its recorded source is exactly the stale canonical source, which the caller has
  * already proven absent from every live Pi agent. The old bytes are archived by hash with that source-exit evidence.
  */
-async function archivePriorRequest(root: string, seat: string, file: string, isLive: (request: HandoverReplacementRequest) => boolean, exit: { canonical: StaleMainRecovery["canonical_source"]; verifiedAt: string }) {
+async function archivePriorRequest(root: string, seat: string, file: string, isLive: (request: HandoverReplacementRequest) => boolean, exit: { canonical: StaleMainRecovery["canonical_source"]; source: Source; verifiedAt: string; assertAbsent: (source: Source) => Promise<void> }) {
   let bytes: string;
   try { bytes = await readFile(file, "utf8"); } catch { return undefined; }
   const prior = yaml.parse<HandoverReplacementRequest>(bytes);
-  const matching = isLive(prior), exited = matching && sourceIsCanonical(prior.source, exit.canonical);
-  if (prior.seat !== seat || (matching && !exited)) throw new Error("A live Path-A replacement request already exists; stale main recovery only replaces a request that no longer matches the recorded runtime or whose matching source has exited.");
-  const source_exited = exited ? sourceExited(exit.canonical, exit.verifiedAt) : undefined;
-  return { path: file, ...await archiveBytes(root, "stale-main-request-archive", seat, bytes), ...(source_exited ? { source_exited } : {}) };
+  const kind = priorKind(prior, isLive, exit);
+  if (prior.seat !== seat || kind === "live") throw new Error("A live Path-A replacement request already exists; stale main recovery only replaces a request that no longer matches the recorded runtime or whose matching source has exited.");
+  if (kind === "live_source_exited") await exit.assertAbsent(prior.source);
+  const proof = kind === "source_exited" ? { source_exited: sourceExited(exit.canonical, exit.verifiedAt) }
+    : kind === "live_source_exited" ? { live_source_exited: sourceExited(prior.source, exit.verifiedAt) } : {};
+  return { path: file, ...await archiveBytes(root, "stale-main-request-archive", seat, bytes), ...proof };
+}
+
+/** How an active request relates to the recorded runtime: replaceable as-is, by proven exit of a named source, or still live. */
+function priorKind(prior: HandoverReplacementRequest, isLive: (request: HandoverReplacementRequest) => boolean, exit: { canonical: StaleMainRecovery["canonical_source"]; source: Source }) {
+  if (!isLive(prior)) return "unmatched";
+  if (sourceIsCanonical(prior.source, exit.canonical)) return "source_exited";
+  return prior.stale_main_recovery && !sameSource(prior.source, exit.source) ? "live_source_exited" : "live";
+}
+
+/** Stale-main recovery proves S0 and any replaced S1 absent from one complete global agent-list snapshot, read once. */
+function agentListOnce() {
+  let list: Promise<string> | undefined;
+  return <T extends { command?: Run }>(dependencies: T): T => {
+    const run = dependencies.command ?? runOutput;
+    return { ...dependencies, command: (argv: string[]) => argv.slice(3, 5).join(" ") === "agent list" ? (list ??= run(argv)) : run(argv) };
+  };
+}
+
+function sameSource(a: Source, b: Source) {
+  return a.pi_session === b.pi_session && a.pi_session_path === b.pi_session_path;
 }
 
 function sourceIsCanonical(source: Source, canonical: StaleMainRecovery["canonical_source"]) {
@@ -109,8 +133,8 @@ function sourceIsCanonical(source: Source, canonical: StaleMainRecovery["canonic
     && source.herdr_session === canonical.herdr_session && source.pane === canonical.pane;
 }
 
-const sourceExited = (canonical: StaleMainRecovery["canonical_source"], verified_at: string): SourceExited =>
-  ({ pi_session: canonical.pi_session, pi_session_path: canonical.pi_session_path, herdr_session: canonical.herdr_session, pane: canonical.pane, verified_at });
+const sourceExited = (source: Source, verified_at: string): SourceExited =>
+  ({ pi_session: source.pi_session, pi_session_path: source.pi_session_path, herdr_session: source.herdr_session, pane: source.pane, verified_at });
 
 /** Swap the active request through a staged file so readers never observe a partial request. */
 export async function replaceActiveRequest(file: string, content: string) {
@@ -157,8 +181,9 @@ function snapshotMatches(request: HandoverReplacementRequest, live: LiveSourcePr
 }
 
 function exitMatches(recovery: StaleMainRecovery) {
-  const exited = recovery.prior_request?.source_exited;
-  return !exited || (sourceIsCanonical({ ...exited }, recovery.canonical_source) && Boolean(exited.verified_at));
+  const exited = recovery.prior_request?.source_exited, replaced = recovery.prior_request?.live_source_exited;
+  return (!exited || (sourceIsCanonical({ ...exited }, recovery.canonical_source) && Boolean(exited.verified_at)))
+    && (!replaced || (!sameSource(replaced, recovery.live_source) && !sourceIsCanonical({ ...replaced }, recovery.canonical_source) && Boolean(replaced.verified_at)));
 }
 
 function archiveNamed(prior: { sha256: string; archive: string } | undefined) {
@@ -176,9 +201,9 @@ export function staleRecoveryMatches(runtime: Runtime | undefined, request: Hand
 }
 
 /** Build the recovery record: verify the live source (injected), then archive the stale receipt and any stale active request by hash. */
-export async function buildStaleMainRecovery(root: string, seat: string, intent: { record: Seat; source: Source; target: Target }, active: { file: string; isLive: (request: HandoverReplacementRequest) => boolean }, verify: (canonical: StaleMainRecovery["canonical_source"]) => Promise<LiveSourceProof>): Promise<StaleMainRecovery> {
+export async function buildStaleMainRecovery(root: string, seat: string, intent: { record: Seat; source: Source; target: Target }, active: { file: string; isLive: (request: HandoverReplacementRequest) => boolean }, verify: (absent: Pick<Source, "pi_session" | "pi_session_path">, once: ReturnType<typeof agentListOnce>) => Promise<LiveSourceProof>): Promise<StaleMainRecovery> {
   const canonical = staleCanonicalSource(intent.record, intent.source, intent.target);
-  const live_source = await verify(canonical);
-  const prior_request = await archivePriorRequest(root, seat, active.file, active.isLive, { canonical, verifiedAt: live_source.verified_at });
+  const once = agentListOnce(), live_source = await verify(canonical, once);
+  const prior_request = await archivePriorRequest(root, seat, active.file, active.isLive, { canonical, source: intent.source, verifiedAt: live_source.verified_at, assertAbsent: async (source) => { await verify(source, once); } });
   return { canonical_source: canonical, prior_receipt: await archiveStaleReceipt(root, seat, canonical), ...(prior_request ? { prior_request } : {}), live_source };
 }