@kontourai/flow-agents 3.1.0 → 3.3.0

package/.github/workflows/ci.yml

@@ -149,6 +149,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check actor-identity-resolver-integration
 
+      - name: CI-runtime actor identity integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check ci-runtime-actor-identity-integration
+
       - name: Assignment provider local-file integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check assignment-provider-local-file-integration
@@ -157,6 +161,10 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check assignment-provider-github-integration
 
+      - name: Stop hook release-with-handoff integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check stop-hook-release-with-handoff-integration
+
       - name: Pull work assignment join integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check pull-work-assignment-join-integration
@@ -165,6 +173,14 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check ensure-session-ownership-guard-integration
 
+      - name: Verify-hold gate integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check verify-hold-gate-integration
+
+      - name: Takeover protocol integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check takeover-protocol-integration
+
       - name: Current.json per-actor integration
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check current-json-per-actor-integration

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [3.3.0](https://github.com/kontourai/flow-agents/compare/v3.2.0...v3.3.0) (2026-07-05)
+
+
+### Features
+
+* **cleanup-audit:** apply mode — safe, reversible session archival ([#406](https://github.com/kontourai/flow-agents/issues/406)) ([3dd7550](https://github.com/kontourai/flow-agents/commit/3dd7550a664c01ee5afb6eabb75325a02de28b59))
+* **veritas-governance:** exemption-issuance flow — governed path for delivery/DECLARED (ADR 0022 §3) ([#370](https://github.com/kontourai/flow-agents/issues/370)) ([50f8f3b](https://github.com/kontourai/flow-agents/commit/50f8f3b0aa65a7b18c6d736360e93f43bb057145))
+
+
+### Documentation
+
+* unified coordination guide + console integration doc + status hygiene ([#399](https://github.com/kontourai/flow-agents/issues/399)) ([#400](https://github.com/kontourai/flow-agents/issues/400)) ([b60331e](https://github.com/kontourai/flow-agents/commit/b60331e1b10d3a417a941de836bbac01bee490bc))
+
+## [3.2.0](https://github.com/kontourai/flow-agents/compare/v3.1.0...v3.2.0) (2026-07-04)
+
+
+### Features
+
+* **builder:** per-step model-routing hints + escalate-on-gate-failure ladder ([#376](https://github.com/kontourai/flow-agents/issues/376)) ([8182dc6](https://github.com/kontourai/flow-agents/commit/8182dc66da10f3bfd731aef93d7cbd38b63ddd06))
+* **knowledge:** inbound-reference integrity check, fail closed ([#340](https://github.com/kontourai/flow-agents/issues/340)) ([02932ab](https://github.com/kontourai/flow-agents/commit/02932abec98fcc43ae3755d2281697e21c7451a6))
+* **knowledge:** incremental append-mode consolidate (Closes [#343](https://github.com/kontourai/flow-agents/issues/343)) ([9b972f5](https://github.com/kontourai/flow-agents/commit/9b972f5bf9d7a41d1de4af23d5e27619db3b1635))
+* **knowledge:** incremental append-mode consolidate, regenerate snapshot from records ([#343](https://github.com/kontourai/flow-agents/issues/343)) ([32cc263](https://github.com/kontourai/flow-agents/commit/32cc263aedc4c3727b144ced24872bc102a13383))
+* **knowledge:** record-carried freshness + Hachure-aligned status semantics ([#341](https://github.com/kontourai/flow-agents/issues/341)) ([32ff45e](https://github.com/kontourai/flow-agents/commit/32ff45eb9244fa1879a0b32784e95e5e5c80de71))
+
+
+### Fixes
+
+* **delivery:** per-session delivery paths so concurrent deliveries stop contending ([#379](https://github.com/kontourai/flow-agents/issues/379)) ([fedf4db](https://github.com/kontourai/flow-agents/commit/fedf4db5c41c7e45dcf9db949176be076131a09e))
+* **delivery:** per-session delivery paths so concurrent deliveries stop contending ([#379](https://github.com/kontourai/flow-agents/issues/379)) ([a03026f](https://github.com/kontourai/flow-agents/commit/a03026fccf940da2129a3b82e979443c37b87456))
+
 ## [3.1.0](https://github.com/kontourai/flow-agents/compare/v3.0.0...v3.1.0) (2026-07-04)
 
 

package/build/src/cli/assignment-provider.d.ts

@@ -117,6 +117,51 @@ export declare function performLocalClaim(artifactRoot: string, subjectId: strin
     reason?: string;
     actorKey?: string;
 }): AssignmentClaimRecord;
+/**
+ * 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 declare function performLocalRelease(artifactRoot: string, subjectId: string, releasedBy: ActorStruct | null, opts?: {
+    reason?: string;
+    actorKey?: string;
+    tolerateNoActiveClaim?: boolean;
+}): AssignmentClaimRecord | null;
 /**
  * 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/build/src/cli/assignment-provider.js

@@ -80,7 +80,16 @@ function loadActorStruct(args) {
     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 { actor: { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null }, actorKey: resolved.actor };
+    // #398: reconstruct the SAME struct resolveActor serialized for a CI actor, mirroring
+    // resolveEnsureSessionActor (workflow-sidecar.ts) via the shared detectCiActor. Without this the
+    // else-branch would write `record.actor = {runtime:"unknown", session_id:<the whole triple>}` for a
+    // CI session — actor_key stays correct (so no false-block), but record.actor is malformed and the
+    // audit-trail / `assignment-provider status` output for CI sessions would be corrupt.
+    const ci = resolved.source.startsWith("ci-runtime") ? helper.detectCiActor(process.env) : null;
+    const actor = ci && ci.session_id
+        ? { runtime: ci.runtime, session_id: ci.session_id, host: os.hostname(), human: null }
+        : { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null };
+    return { actor, actorKey: resolved.actor };
 }
 export function assignmentFilePath(artifactRoot, subjectId) {
     const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
@@ -424,31 +433,116 @@ function claimLocalFile(argv) {
     console.log(JSON.stringify({ role: "AssignmentClaimResult", subject_id: subjectId, record }, null, 2));
     return 0;
 }
-function releaseLocalFile(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}`);
-    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, 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 releaseLocalFile(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}`);
+    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