@kontourai/flow-agents 3.1.0 → 3.2.0

package/src/cli/assignment-provider.ts

@@ -559,31 +559,129 @@ function claimLocalFile(argv: string[]): number {
   return 0;
 }
 
-function releaseLocalFile(argv: string[]): number {
-  const args = parseArgs(argv);
-  const provider = flagString(args.flags, "provider", "local-file");
-  if (provider !== "local-file") throw new Error(`release: --provider must be local-file (use render-release for github); got ${provider}`);
-  const artifactRoot = requireFlag(args, "artifact-root");
-  const subjectId = requireFlag(args, "subject-id");
-  const releasedBy = flagString(args.flags, "actor-json") ? loadActorStructFromFile(requireFlag(args, "actor-json")) : null;
-  const reason = flagString(args.flags, "reason") ?? "released";
+/**
+ * Wave 1 (#292) extraction: the durable-write body previously inlined inside releaseLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so the Stop hook's non-terminal
+ * release lifecycle (scripts/hooks/stop-goal-fit.js, #292 Wave 2) can reuse the EXACT same release
+ * logic — actor-ownership verification, audit-trail append, atomic write under withSubjectLock —
+ * rather than reimplementing a second, parallel release path. releaseLocalFile (CLI wrapper,
+ * below) is now a thin parse-args/print-envelope shell around this, mirroring the
+ * performLocalSupersede/supersedeLocalFile extraction shape exactly.
+ *
+ * Two behaviors are deliberately DIFFERENT from a naive inline release, both required for the
+ * Stop hook's idempotent, actor-scoped lifecycle release (never for the interactive CLI, which
+ * keeps `tolerateNoActiveClaim` unset/false and therefore 100% of its prior throw-on-error shape):
+ *
+ * - `opts.tolerateNoActiveClaim === true` and there is no existing record, or the existing
+ *   record's status is not `"claimed"`: return `null` (a tolerated no-op) instead of throwing
+ *   "no active claim to release". This is the one deliberate idempotency change vs today's
+ *   releaseLocalFile — a second release call (e.g. a double Stop event) must be a safe no-op.
+ * - `releasedBy` is provided and does not match the existing record's holder: never force-release
+ *   a claim held by a different actor — return `null` (if tolerateNoActiveClaim) or throw
+ *   (otherwise), same as the no-active-claim case. The comparison mirrors computeEffectiveState()'s
+ *   `record.actor_key || helper.serializeActor(record.actor)` canonical-key preference EXACTLY
+ *   (actor_key-first, falling back to serializeActor only when actor_key is absent) — the read
+ *   path (status/effective-state) and this write path (release) must use the identical
+ *   canonical-key comparison, or a claim written under an explicit-override actor (`actor_key`
+ *   bare, e.g. `"canonical-x"`, but `serializeActor(record.actor)` a DIFFERENT triple, e.g.
+ *   `"explicit-override:canonical-x:host"`) can be self-recognized by computeEffectiveState() yet
+ *   fail to release here because the releaser's canonical key was compared against the wrong
+ *   (re-derived, triple) form instead of the stored actor_key. Comparing two serializeActor()
+ *   calls unconditionally — as a prior version of this function did — is NOT correct for override
+ *   actors and reintroduces the exact #291 seam on the release path.
+ *
+ * Contract: when `releasedBy` is provided AND the existing record is `actor_key`-stamped,
+ * `opts.actorKey` is REQUIRED (the canonical `resolveActor(env).actor` string) — otherwise
+ * ownership cannot be verified. A caller that passes `releasedBy` without `opts.actorKey` against
+ * an `actor_key`-stamped record would have its ownership compared as
+ * `existing.actor_key` (bare canonical) vs `serializeActor(releasedBy)` (re-derived triple), which
+ * can NEVER match even for the legitimate holder — a silent-failure trap, not a real ownership
+ * check. This is refused loudly (see the guard at the top of the `releasedBy` branch below) rather
+ * than allowed to silently no-op or wrongly refuse.
+ */
+export function performLocalRelease(
+  artifactRoot: string,
+  subjectId: string,
+  releasedBy: ActorStruct | null,
+  opts: { reason?: string; actorKey?: string; tolerateNoActiveClaim?: boolean } = {},
+): AssignmentClaimRecord | null {
+  const helper = loadActorIdentityHelper();
+  const reason = opts.reason ?? "released";
+  const tolerateNoActiveClaim = opts.tolerateNoActiveClaim ?? false;
 
   // F1 fix (fix-plan iteration 1, CRITICAL): release mutates the same record file claim/supersede
   // do, under the same per-subject lock (see withSubjectLock()'s doc comment).
-  return withSubjectLock(artifactRoot, subjectId, (): number => {
+  return withSubjectLock(artifactRoot, subjectId, (): AssignmentClaimRecord | null => {
     const existing = readLocalRecord(artifactRoot, subjectId);
-    if (!existing || existing.status !== "claimed") throw new Error(`no active claim to release for subject: ${subjectId}`);
+    if (!existing || existing.status !== "claimed") {
+      if (tolerateNoActiveClaim) return null;
+      throw new Error(`no active claim to release for subject: ${subjectId}`);
+    }
+
+    if (releasedBy) {
+      // Contract guard (hardening fix, #292 review): a caller that supplies `releasedBy` but NOT
+      // `opts.actorKey` against a record that already carries `actor_key` cannot reliably prove
+      // ownership — see this function's doc comment. This is the ONLY combination that fires: it
+      // does NOT fire when `existing.actor_key` is absent (the CLI/fixture path, where both sides
+      // fall back to serializeActor() and legitimately compare equal). Fail loudly rather than
+      // silently no-op (tolerant callers) or wrongly refuse (throwing callers) — never silent.
+      if (!opts.actorKey && existing.actor_key) {
+        if (tolerateNoActiveClaim) {
+          console.error(
+            `[performLocalRelease] cannot verify ownership of an actor_key-stamped record without opts.actorKey; skipping release for ${subjectId}`,
+          );
+          return null;
+        }
+        throw new Error(
+          "performLocalRelease: pass opts.actorKey (the canonical resolveActor().actor string) when releasedBy is set and the record carries actor_key — serializeActor(releasedBy) is not a valid ownership key for actor_key-stamped records",
+        );
+      }
+
+      // AC6: never force-release a claim held by a different actor. Mirrors
+      // computeEffectiveState()'s canonical self-recognition comparison EXACTLY —
+      // `holderActorKey` prefers the stored `actor_key` (the canonical resolveActor(env).actor
+      // string, present on records written by the fixed performLocalClaim/performLocalSupersede
+      // paths) and only falls back to `serializeActor(existing.actor)` when `actor_key` is
+      // absent (every pre-fix record, every #290 eval fixture). The releaser's side must use the
+      // SAME canonical form: `opts.actorKey` (the caller's resolveActor(env).actor string, e.g.
+      // scripts/hooks/stop-goal-fit.js's Stop hook) when provided, else re-derived via
+      // serializeActor(releasedBy) — never serializeActor() unconditionally on both sides, which
+      // would compare the bare actor_key form against a re-derived triple form for an
+      // explicit-override actor and spuriously reject a legitimate same-actor release (the #291
+      // seam, relocated to this write path).
+      const holderActorKey = existing.actor_key || helper.serializeActor(existing.actor);
+      const releasedByActorKey = opts.actorKey || helper.serializeActor(releasedBy);
+      if (holderActorKey !== releasedByActorKey) {
+        if (tolerateNoActiveClaim) return null;
+        throw new Error(`--actor-json does not match the current holder (${holderActorKey}); refusing to release a claim held by someone else`);
+      }
+    }
+
     const record: AssignmentClaimRecord = {
       ...existing,
+      ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
       status: "released",
       audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "release", from_actor: existing.actor, to_actor: releasedBy, reason }],
     };
     writeLocalRecord(artifactRoot, subjectId, record);
-    console.log(JSON.stringify({ role: "AssignmentReleaseResult", subject_id: subjectId, record }, null, 2));
-    return 0;
+    return record;
   });
 }
 
+function releaseLocalFile(argv: string[]): number {
+  const args = parseArgs(argv);
+  const provider = flagString(args.flags, "provider", "local-file");
+  if (provider !== "local-file") throw new Error(`release: --provider must be local-file (use render-release for github); got ${provider}`);
+  const artifactRoot = requireFlag(args, "artifact-root");
+  const subjectId = requireFlag(args, "subject-id");
+  const releasedBy = flagString(args.flags, "actor-json") ? loadActorStructFromFile(requireFlag(args, "actor-json")) : null;
+  const reason = flagString(args.flags, "reason") ?? "released";
+
+  const record = performLocalRelease(artifactRoot, subjectId, releasedBy, { reason, tolerateNoActiveClaim: false });
+  console.log(JSON.stringify({ role: "AssignmentReleaseResult", subject_id: subjectId, record }, null, 2));
+  return 0;
+}
+
 /**
  * Wave 1 (#291) extraction: the durable-write body previously inlined inside supersedeLocalFile's
  * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's

package/src/cli/workflow-sidecar.ts

@@ -1619,7 +1619,30 @@ function recordAgentEvent(p: ReturnType<typeof parseArgs>): number {
   if (hasExplicitRoot || !explicit) requireArtifactDirUnderRoot(dir, root);
   const timestamp = opt(p, "timestamp", now());
   const agent = validateAgentId(opt(p, "agent-id"));
-  const event = { timestamp, agent_id: agent, kind: opt(p, "kind", "note"), status: opt(p, "status", "info"), summary: opt(p, "summary"), ...(opt(p, "ref") ? { ref: opt(p, "ref") } : {}) };
+  // #376 model routing: optionally stamp the delegate role/model resolved from
+  // .datum/config.json onto the event so a downstream economics record (#349)
+  // can price role assignments per delegation, and so an escalate-on-gate-failure
+  // re-dispatch records which tier it climbed FROM. Fully additive/optional: when
+  // no routing flag is passed the event shape is byte-identical to before.
+  // These live as TOP-LEVEL event fields (not nested) on purpose: appendJsonl's
+  // serializer (spacedLine) uses the top-level key list as a JSON.stringify array
+  // replacer, which is an allowlist applied at every nesting level — a nested
+  // routing object would have its inner keys stripped. Flat keeps the shape a
+  // simple per-event routing record a JSONL economics feed can read directly.
+  const role = opt(p, "role");
+  const model = opt(p, "model");
+  const escalatedFrom = opt(p, "escalated-from");
+  const event = {
+    timestamp,
+    agent_id: agent,
+    kind: opt(p, "kind", "note"),
+    status: opt(p, "status", "info"),
+    summary: opt(p, "summary"),
+    ...(opt(p, "ref") ? { ref: opt(p, "ref") } : {}),
+    ...(role ? { role } : {}),
+    ...(model ? { model } : {}),
+    ...(escalatedFrom ? { escalated_from: escalatedFrom } : {}),
+  };
   appendJsonl(path.join(dir, "agents", agent, "events.jsonl"), event);
   updateCurrentAgent(root, dir, agent, event.status, timestamp, actorKey);
   return 0;
@@ -2526,52 +2549,118 @@ async function sealCheckpoint(p: ReturnType<typeof parseArgs>): Promise<number>
 // Called automatically from recordRelease and advanceState→delivered (best-effort).
 // Also exposed as the `publish-delivery <artifact-dir>` subcommand for explicit use.
 
+/**
+ * #379 supersede-on-publish cleanup: keep delivery/ bounded by pruning inherited PER-SESSION
+ * seal dirs (the growth vector), scoped to avoid any cross-PR conflict.
+ *
+ * An inherited per-session seal dir (`delivery/<other-slug>/`) is UNIQUELY named, so pruning
+ * it can never conflict with a concurrent PR: two branches deleting the same inherited dir is
+ * a delete/delete (auto-merges), and each new delivery adds its OWN distinct
+ * `delivery/<slug>/`. And it is HARMLESS to leave: trust-reconcile.js's prefer-newest
+ * ownership selection always picks THIS session's fresher bundle over an older inherited one.
+ * Pruning is therefore purely to stop unbounded accumulation of permanently-superseded dirs.
+ *
+ * The SHARED FLAT path (`delivery/trust.bundle` + checkpoints) is deliberately NOT pruned
+ * here. During the migration window other concurrent PRs may still seal to the flat path;
+ * deleting it would produce a modify/delete conflict → a DIRTY PR → the no-CI failure this
+ * whole change fixes. The flat path is a single fixed location (not a growth vector) and the
+ * reconciler treats a stale flat bundle as non-owning / older-owning, so leaving it is safe.
+ * Removing the flat legacy seals is a one-time cleanup for a dedicated PR once no open PR
+ * still seals to it — intentionally NOT bundled into every delivery.
+ *
+ * Best-effort: a prune failure is logged, never fatal to the delivery. Never touches
+ * README.md, DECLARED, the flat seal files, or any subdir that is not itself a seal dir.
+ */
+function pruneSupersededSeals(deliveryDir: string, keepSlug: string): void {
+  let entries: fs.Dirent[] = [];
+  try {
+    entries = fs.readdirSync(deliveryDir, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === keepSlug) continue;
+    const subdir = path.join(deliveryDir, entry.name);
+    // Only prune dirs that actually look like a seal dir (contain a trust.bundle or
+    // trust.checkpoint.json) — never an unrelated directory a human placed under delivery/.
+    const looksLikeSeal =
+      fs.existsSync(path.join(subdir, "trust.bundle")) ||
+      fs.existsSync(path.join(subdir, "trust.checkpoint.json"));
+    if (!looksLikeSeal) continue;
+    try {
+      fs.rmSync(subdir, { recursive: true, force: true });
+      process.stderr.write(`[publish-delivery] #379: pruned superseded per-session seal delivery/${entry.name}/ (older-owning/stale; the reconciler selects the newest bundle regardless)\n`);
+    } catch (err) {
+      process.stderr.write(`[publish-delivery] #379: could not prune per-session seal delivery/${entry.name}/ (non-fatal): ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+  }
+}
+
 /**
  * Publish the session's trust artifacts to the committed delivery/ path.
  *
+ * #379: writes to a PER-SESSION path `<repoRoot>/delivery/<slug>/` (slug = the session
+ * artifact dir's basename) rather than the shared flat `delivery/`. A shared path guarantees
+ * a git conflict between ANY two concurrent deliveries, and a conflicting (DIRTY) PR gets NO
+ * pull_request workflows — the required Trust Reconcile check silently never runs (field
+ * incidents #330/#358/#378). Per-session paths make concurrent deliveries write DISTINCT
+ * files that never contend. trust-reconcile.js reads both the flat (back-compat) and
+ * per-session layouts via resolveDeliveryCandidates() and selects the owning candidate by
+ * commit ancestry.
+ *
  * Copies trust.bundle, trust.checkpoint.json, and (if present)
- * trust.checkpoint.intoto.json / trust.checkpoint.sig.json from the
- * session artifact dir to <repoRoot>/delivery/.
+ * trust.checkpoint.intoto.json / trust.checkpoint.sig.json / trust.checkpoint.attestation.json
+ * from the session artifact dir to <repoRoot>/delivery/<slug>/.
  *
  * Fail-soft on a missing bundle: if trust.bundle is absent, returns without throwing.
  * Fail-CLOSED on repo-root resolution: repoRoot must be a real, resolved kits/ ancestor
  * (see findRepoRootFromDirStrict) — null (no ancestor found) skips the publish with a
  * visible warning instead of writing to whatever process.cwd() happens to be. This
  * prevents a scratch/test session dir (no kits/ ancestor) from silently clobbering an
- * unrelated real repo's delivery/trust.bundle when invoked with that repo as cwd (see
+ * unrelated real repo's delivery/ seal when invoked with that repo as cwd (see
  * evals/integration/test_checkpoint_signing.sh TEST 2 and the WS5 session findings at
  * .kontourai/flow-agents/ws5-governance-kit-slice1 for the root cause this fixes).
- * Idempotent: overwrites on re-delivery.
+ * Idempotent: overwrites on re-delivery to the same slug.
  */
 export async function publishDelivery(dir: string, repoRoot: string | null): Promise<void> {
   const bundleSrc = path.join(dir, "trust.bundle");
   if (!fs.existsSync(bundleSrc)) return; // no bundle — skip gracefully
 
   if (!repoRoot) {
-    process.stderr.write(`[publish-delivery] WARNING: no kits/ ancestor found from ${dir}; skipping publish. Refusing to fall back to process.cwd() to avoid clobbering an unrelated repo's delivery/trust.bundle. Pass --repo-root explicitly if this session dir is intentionally outside a repo checkout.\n`);
+    process.stderr.write(`[publish-delivery] WARNING: no kits/ ancestor found from ${dir}; skipping publish. Refusing to fall back to process.cwd() to avoid clobbering an unrelated repo's delivery/ seal. Pass --repo-root explicitly if this session dir is intentionally outside a repo checkout.\n`);
     return;
   }
 
   const deliveryDir = path.join(repoRoot, "delivery");
+  // #379: slug is the session artifact dir's basename — the same human-meaningful id used
+  // throughout the session (.kontourai/flow-agents/<slug>/). The per-session dir NAME is only
+  // a collision-avoidance handle; ownership is decided by commit ancestry, not by name.
+  const slug = path.basename(path.resolve(dir));
+  const sessionDeliveryDir = path.join(deliveryDir, slug);
+
   fs.mkdirSync(deliveryDir, { recursive: true });
+  // Supersede inherited/flat seals BEFORE writing this session's dir (keepSlug = our own).
+  pruneSupersededSeals(deliveryDir, slug);
+  fs.mkdirSync(sessionDeliveryDir, { recursive: true });
 
   // Required: trust.bundle (the CI anchor)
-  fs.copyFileSync(bundleSrc, path.join(deliveryDir, "trust.bundle"));
+  fs.copyFileSync(bundleSrc, path.join(sessionDeliveryDir, "trust.bundle"));
 
   // Optional companions: checkpoint + signing artifacts
   const companions = [
     "trust.checkpoint.json",
     "trust.checkpoint.intoto.json",
     "trust.checkpoint.sig.json",
+    "trust.checkpoint.attestation.json",
   ];
   for (const filename of companions) {
     const src = path.join(dir, filename);
     if (fs.existsSync(src)) {
-      fs.copyFileSync(src, path.join(deliveryDir, filename));
+      fs.copyFileSync(src, path.join(sessionDeliveryDir, filename));
     }
   }
 
-  process.stderr.write(`[publish-delivery] published trust.bundle and companions to ${deliveryDir}\n`);
+  process.stderr.write(`[publish-delivery] published trust.bundle and companions to ${sessionDeliveryDir} (per-session path, #379)\n`);
 }
 
 /**
@@ -3330,7 +3419,7 @@ function loadLivenessReadHelper(): {
 // init-plan claims the work-item; advance-state heartbeats (or releases on terminal),
 // so the workflow lifecycle itself maintains the liveness claim — no manual liveness calls.
 // Additive + fail-open: a liveness-emit failure never affects the workflow command.
-const LIVENESS_TERMINAL = new Set(["delivered", "accepted", "archived"]);
+export const LIVENESS_TERMINAL = new Set(["delivered", "accepted", "archived"]);
 /**
  * Delegate to the shared pure-CJS resolver (scripts/hooks/lib/actor-identity.js), mirroring the
  * createRequire pattern used by readLivenessEvents() above. Deliberately NO inline duplicate