@kontourai/flow-agents 3.0.0 → 3.2.0

package/build/src/cli/assignment-provider.js

@@ -64,22 +64,29 @@ function loadActorStructFromFile(file) {
  * fixture-friendly path (used by evals and any caller that already knows its own struct);
  * when omitted, auto-derive from the live environment via the shared resolver, mirroring
  * (never forking) the exact struct fields serializeActor() already defines.
+ *
+ * F1 fix (fix-plan iteration 1, HIGH): also returns `actorKey` — set to the canonical
+ * `resolveActor(env).actor` string ONLY on the auto-derive path (pull-work's real path, and any
+ * other caller with no --actor-json), so a claim made via `assignment-provider claim` and one
+ * made via ensure-session share the same canonical key. `--actor-json` explicit fixtures leave
+ * `actorKey` unset — `performLocalClaim`/`performLocalSupersede` then fall back to
+ * `serializeActor(actor)` for the record's `actor_key`, preserving existing fixture behavior.
  */
 function loadActorStruct(args) {
     const actorJsonPath = flagString(args.flags, "actor-json");
     if (actorJsonPath)
-        return loadActorStructFromFile(actorJsonPath);
+        return { actor: loadActorStructFromFile(actorJsonPath) };
     const helper = loadActorIdentityHelper();
     const resolved = helper.resolveActor(process.env);
     if (helper.isUnresolvedActor(resolved.actor))
         throw new Error("could not resolve an actor identity (no --actor-json and no resolvable environment actor); pass --actor-json explicitly");
-    return { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null };
+    return { actor: { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null }, actorKey: resolved.actor };
 }
-function assignmentFilePath(artifactRoot, subjectId) {
+export function assignmentFilePath(artifactRoot, subjectId) {
     const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
     return path.join(artifactRoot, "assignment", `${sanitized}.json`);
 }
-function readLocalRecord(artifactRoot, subjectId) {
+export function readLocalRecord(artifactRoot, subjectId) {
     const file = assignmentFilePath(artifactRoot, subjectId);
     if (!fs.existsSync(file))
         return null;
@@ -99,7 +106,7 @@ function readLocalRecord(artifactRoot, subjectId) {
         throw new Error(`${file}: unsupported schema_version ${String(record.schema_version)}`);
     return record;
 }
-function writeLocalRecord(artifactRoot, subjectId, record) {
+export function writeLocalRecord(artifactRoot, subjectId, record) {
     // writeJson throws on any mkdir/writeFileSync failure; that error is intentionally allowed to
     // propagate to main()'s top-level try/catch and exit non-zero. Durable writes must fail loud,
     // never fail open (artifact-contract.md).
@@ -142,7 +149,7 @@ function subjectLockDir(artifactRoot, subjectId) {
  * the write) of all three local-file mutators in this, since all three mutate the same record
  * file for a given subject.
  */
-function withSubjectLock(artifactRoot, subjectId, body) {
+export function withSubjectLock(artifactRoot, subjectId, body) {
     const lockDir = subjectLockDir(artifactRoot, subjectId);
     const staleMs = Number(process.env.FLOW_AGENTS_ASSIGNMENT_STALE_LOCK_MS ?? 5 * 60 * 1000);
     const deadline = Date.now() + 30000;
@@ -196,7 +203,7 @@ function withSubjectLock(artifactRoot, subjectId, body) {
  * through here too means `--now` deterministically governs idle_days as well as liveness
  * freshness, rather than idle_days silently reading the real wall clock regardless of `--now`.
  */
-function computeEffectiveState(assignment, freshHoldersList, selfActor, nowMs) {
+export function computeEffectiveState(assignment, freshHoldersList, selfActor, nowMs) {
     const record = assignment.record && assignment.record.status === "claimed" ? assignment.record : null;
     const isAssigned = Boolean(assignment.assignee) || Boolean(record);
     if (!isAssigned) {
@@ -222,7 +229,14 @@ function computeEffectiveState(assignment, freshHoldersList, selfActor, nowMs) {
         // human's work (Design Decision 3 / ADR 0021 §6's "never auto-reclaim" non-goal).
         return { effective_state: "human-held", reason: "assignee_without_claim_record", holder: { assignee: assignment.assignee } };
     }
-    const holderActorKey = loadActorIdentityHelper().serializeActor(record.actor);
+    // F1 fix (fix-plan iteration 1, HIGH): prefer the canonical actor_key over re-serializing
+    // record.actor. record.actor_key IS resolveActor(env).actor for records written by the fixed
+    // performLocalClaim/performLocalSupersede paths (below) — the same flat/bare string liveness
+    // whoami, `liveness claim --actor`, per-actor current.json, and pull-work's --self-actor all
+    // use — so for an explicit-override actor the self-check and the liveness join now agree with
+    // every other tool. BACK-COMPAT: records with no actor_key (every pre-fix record, every #290
+    // eval fixture) fall back to serializeActor(record.actor) exactly as before this fix.
+    const holderActorKey = record.actor_key || loadActorIdentityHelper().serializeActor(record.actor);
     if (selfActor && holderActorKey === selfActor)
         return { effective_state: "held", reason: "self_is_holder", holder: { actor: holderActorKey } };
     const fresh = freshHoldersList.find((holder) => holder.actor === holderActorKey);
@@ -349,22 +363,17 @@ function loadLivenessInputs(args) {
 }
 // ─── local-file: claim | release | supersede (the durable-write path; real I/O by design — no
 // external mutation to defer to a skill for this provider kind, per Design Decision 1) ─────────
-function claimLocalFile(argv) {
-    const args = parseArgs(argv);
-    const provider = flagString(args.flags, "provider", "local-file");
-    if (provider !== "local-file")
-        throw new Error(`claim: --provider must be local-file (use render-claim for github); got ${provider}`);
-    const artifactRoot = requireFlag(args, "artifact-root");
-    const subjectId = requireFlag(args, "subject-id");
-    const actor = loadActorStruct(args);
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside claimLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's ownership
+ * guard (workflow-sidecar.ts, Wave 2) can reuse the EXACT same claim logic — same-actor idempotent
+ * refresh, different-actor throw, atomic write under withSubjectLock — rather than reimplementing
+ * a second, parallel claim path. claimLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export function performLocalClaim(artifactRoot, subjectId, actor, opts) {
     const helper = loadActorIdentityHelper();
-    const ttlSecondsRaw = flagString(args.flags, "ttl-seconds", "1800") ?? "1800";
-    const ttlSeconds = Number(ttlSecondsRaw);
-    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
-        throw new Error(`--ttl-seconds must be a positive number; got ${ttlSecondsRaw}`);
-    const branch = requireFlag(args, "branch");
-    const artifactDir = requireFlag(args, "artifact-dir");
-    const reason = flagString(args.flags, "reason") ?? "claim";
+    const reason = opts.reason ?? "claim";
     // F1 fix (fix-plan iteration 1, CRITICAL): the existing-claim check AND the write must happen
     // atomically with respect to any other `assignment-provider` invocation on the same subject —
     // see withSubjectLock()'s doc comment for the full rationale.
@@ -384,57 +393,159 @@ function claimLocalFile(argv) {
             role: "AssignmentClaimRecord",
             subject_id: subjectId,
             actor,
+            ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
             claimed_at: isoNow(),
-            ttl_seconds: ttlSeconds,
-            branch,
-            artifact_dir: artifactDir,
+            ttl_seconds: opts.ttlSeconds,
+            branch: opts.branch,
+            artifact_dir: opts.artifactDir,
             status: "claimed",
             audit_trail: [...(existing?.audit_trail ?? []), { at: isoNow(), transition: "claim", from_actor: null, to_actor: actor, reason }],
         };
         writeLocalRecord(artifactRoot, subjectId, record);
-        console.log(JSON.stringify({ role: "AssignmentClaimResult", subject_id: subjectId, record }, null, 2));
-        return 0;
+        return record;
     });
 }
-function releaseLocalFile(argv) {
+function claimLocalFile(argv) {
     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}`);
+        throw new Error(`claim: --provider must be local-file (use render-claim 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 { actor, actorKey } = loadActorStruct(args);
+    const ttlSecondsRaw = flagString(args.flags, "ttl-seconds", "1800") ?? "1800";
+    const ttlSeconds = Number(ttlSecondsRaw);
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
+        throw new Error(`--ttl-seconds must be a positive number; got ${ttlSecondsRaw}`);
+    const branch = requireFlag(args, "branch");
+    const artifactDir = requireFlag(args, "artifact-dir");
+    const reason = flagString(args.flags, "reason") ?? "claim";
+    const record = performLocalClaim(artifactRoot, subjectId, actor, { ttlSeconds, branch, artifactDir, reason, actorKey });
+    console.log(JSON.stringify({ role: "AssignmentClaimResult", subject_id: subjectId, record }, null, 2));
+    return 0;
+}
+/**
+ * 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, subjectId, releasedBy, opts = {}) {
+    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, () => {
         const existing = readLocalRecord(artifactRoot, subjectId);
-        if (!existing || existing.status !== "claimed")
+        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 = {
             ...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 supersedeLocalFile(argv) {
+function releaseLocalFile(argv) {
     const args = parseArgs(argv);
     const provider = flagString(args.flags, "provider", "local-file");
     if (provider !== "local-file")
-        throw new Error(`supersede: --provider must be local-file (use render-supersede for github); got ${provider}`);
+        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
+ * `--supersede-stale` takeover path (workflow-sidecar.ts, Wave 2) can reuse the EXACT same
+ * supersede logic — from-actor holder verification, ttl/branch/artifact_dir carry-forward,
+ * audit-trail append, atomic write under withSubjectLock — rather than reimplementing a second,
+ * parallel supersede path. supersedeLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export function performLocalSupersede(artifactRoot, subjectId, fromActor, toActor, opts = {}) {
     const helper = loadActorIdentityHelper();
-    const fromActor = loadActorStructFromFile(requireFlag(args, "from-actor-json"));
-    const toActor = loadActorStructFromFile(requireFlag(args, "to-actor-json"));
-    const reason = flagString(args.flags, "reason") ?? "supersede";
-    const ttlSecondsOverride = flagString(args.flags, "ttl-seconds");
-    const branchOverride = flagString(args.flags, "branch");
-    const artifactDirOverride = flagString(args.flags, "artifact-dir");
+    const reason = opts.reason ?? "supersede";
     // F1 fix (fix-plan iteration 1, CRITICAL): supersede mutates the same record file claim/release
     // do, under the same per-subject lock (see withSubjectLock()'s doc comment).
     return withSubjectLock(artifactRoot, subjectId, () => {
@@ -444,7 +555,7 @@ function supersedeLocalFile(argv) {
         if (helper.serializeActor(existing.actor) !== helper.serializeActor(fromActor)) {
             throw new Error(`--from-actor-json does not match the current holder (${helper.serializeActor(existing.actor)}); refusing to supersede a claim held by someone else`);
         }
-        const ttlSecondsRaw = ttlSecondsOverride ?? String(existing.ttl_seconds);
+        const ttlSecondsRaw = opts.ttlSeconds != null ? String(opts.ttlSeconds) : String(existing.ttl_seconds);
         const ttlSeconds = Number(ttlSecondsRaw);
         if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
             throw new Error(`--ttl-seconds must be a positive number; got ${ttlSecondsRaw}`);
@@ -453,17 +564,39 @@ function supersedeLocalFile(argv) {
             role: "AssignmentClaimRecord",
             subject_id: subjectId,
             actor: toActor,
+            ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
             claimed_at: isoNow(),
             ttl_seconds: ttlSeconds,
-            branch: branchOverride ?? existing.branch,
-            artifact_dir: artifactDirOverride ?? existing.artifact_dir,
+            branch: opts.branch ?? existing.branch,
+            artifact_dir: opts.artifactDir ?? existing.artifact_dir,
             status: "claimed",
             audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "supersede", from_actor: fromActor, to_actor: toActor, reason }],
         };
         writeLocalRecord(artifactRoot, subjectId, record);
-        console.log(JSON.stringify({ role: "AssignmentSupersedeResult", subject_id: subjectId, record }, null, 2));
-        return 0;
+        return record;
+    });
+}
+function supersedeLocalFile(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "local-file");
+    if (provider !== "local-file")
+        throw new Error(`supersede: --provider must be local-file (use render-supersede for github); got ${provider}`);
+    const artifactRoot = requireFlag(args, "artifact-root");
+    const subjectId = requireFlag(args, "subject-id");
+    const fromActor = loadActorStructFromFile(requireFlag(args, "from-actor-json"));
+    const toActor = loadActorStructFromFile(requireFlag(args, "to-actor-json"));
+    const reason = flagString(args.flags, "reason") ?? "supersede";
+    const ttlSecondsOverride = flagString(args.flags, "ttl-seconds");
+    const branchOverride = flagString(args.flags, "branch");
+    const artifactDirOverride = flagString(args.flags, "artifact-dir");
+    const record = performLocalSupersede(artifactRoot, subjectId, fromActor, toActor, {
+        ttlSeconds: ttlSecondsOverride != null ? Number(ttlSecondsOverride) : undefined,
+        branch: branchOverride ?? undefined,
+        artifactDir: artifactDirOverride ?? undefined,
+        reason,
     });
+    console.log(JSON.stringify({ role: "AssignmentSupersedeResult", subject_id: subjectId, record }, null, 2));
+    return 0;
 }
 // ─── GitHub: render-claim | render-release | render-supersede (render, don't execute — Design
 // Decision 1). Pure functions: no I/O beyond reading --input-json/--actor-json. Never invoke
@@ -624,6 +757,17 @@ function renderSupersede(argv) {
     return 0;
 }
 // ─── status | list (both provider kinds) ────────────────────────────────────────────────────
+/**
+ * Wave 1 (#291) extraction: the local-file branch of statusCommand's assignment-layer read,
+ * mirrored exactly so ensure-session's ownership guard (workflow-sidecar.ts, Wave 2) derives an
+ * AssignmentStatus identically to the `assignment-provider status` CLI command — a single
+ * implementation, not a second parallel local-file read.
+ */
+export function readLocalAssignmentStatus(artifactRoot, subjectId) {
+    const record = readLocalRecord(artifactRoot, subjectId);
+    const active = record && record.status === "claimed" ? record : null;
+    return { subject_id: subjectId, provider: "local-file", assignee: active ? loadActorIdentityHelper().serializeActor(active.actor) : null, record: active };
+}
 function statusCommand(argv) {
     const args = parseArgs(argv);
     const provider = requireFlag(args, "provider");
@@ -633,9 +777,7 @@ function statusCommand(argv) {
         const artifactRoot = requireFlag(args, "artifact-root");
         if (!requestedSubjectId)
             throw new Error("--subject-id is required for status --provider local-file");
-        const record = readLocalRecord(artifactRoot, requestedSubjectId);
-        const active = record && record.status === "claimed" ? record : null;
-        assignment = { subject_id: requestedSubjectId, provider: "local-file", assignee: active ? loadActorIdentityHelper().serializeActor(active.actor) : null, record: active };
+        assignment = readLocalAssignmentStatus(artifactRoot, requestedSubjectId);
     }
     else if (provider === "github") {
         const issueJsonPath = requireFlag(args, "issue-json");

package/build/src/cli/workflow-sidecar.d.ts

@@ -145,7 +145,7 @@ type SurfaceModule = {
  * @param critiques  Critique objects (from critique.json .critiques array)
  * @param commandLog Optional parsed command-log.jsonl entries (capture-authoritative fold)
  */
-export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string): Promise<AnyObj | null>;
+export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string, actorKey?: string): Promise<AnyObj | null>;
 /**
  * Fail-open wrapper: builds (via Surface), validates, and writes a trust.bundle.
  * Accepts raw check/criterion/critique inputs directly (ADR 0010 Phase 4a).
@@ -159,7 +159,7 @@ export declare function buildTrustBundle(slug: string, timestamp: string, checks
  * @param criteria   Acceptance criteria objects (same as buildTrustBundle)
  * @param critiques  Critique objects (same as buildTrustBundle)
  */
-export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[]): Promise<{
+export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], actorKey?: string): Promise<{
     written: boolean;
     errors: string[];
 }>;
@@ -204,19 +204,28 @@ export declare function sealTrustCheckpoint(dir: string, slug: string, sealedAt:
 /**
  * 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 declare function publishDelivery(dir: string, repoRoot: string | null): Promise<void>;
 export declare function validateLearningCorrection(record: AnyObj): void;
@@ -301,5 +310,6 @@ export declare function gateAdvisoryFix(calibration: GateCalibration, claimId: s
  * @param now                 Optional timestamp override for deterministic tests
  */
 export declare function buildGateInquiryRecords(bundle: BundleFile, blockSignal: GateBlockSignal, slug: string, expectedCriterionIds: string[], surface: SurfaceModule, now?: Date): AnyObj[];
+export declare const LIVENESS_TERMINAL: Set<string>;
 export { buildClaimExplanation } from "./sidecar-claim-explain.js";
 export type { ClaimEvidenceItem, ClaimExplanation } from "./sidecar-claim-explain.js";