@kontourai/flow-agents 3.4.3 → 3.6.0

package/context/contracts/assignment-provider-contract.md

@@ -138,8 +138,10 @@ detect an incompatible future shape before parsing fields it does not understand
 {
   "schema_version": "1.0",
   "role": "AssignmentClaimRecord",
-  "subject_id": "kontourai/flow-agents#290",
+  "subject_id": "kontourai-flow-agents-290",
   "actor": { "runtime": "claude-code", "session_id": "...", "host": "...", "human": null },
+  "actor_key": "claude-code:...:host",
+  "work_item_ref": "kontourai/flow-agents#290",
   "claimed_at": "2026-07-02T00:00:00Z",
   "ttl_seconds": 1800,
   "branch": "agent/<actor>/<slug>",
@@ -152,9 +154,10 @@ detect an incompatible future shape before parsing fields it does not understand
 | --- | --- | --- |
 | `schema_version` | yes | Version of this record shape, `"1.0"`. |
 | `role` | yes | Constant `"AssignmentClaimRecord"`, for readers scanning mixed content (e.g. a GitHub comment thread) for this record type. |
-| `subject_id` | yes | The claimed work item, in `owner/repo#id` form — the same string `workItemSlug` derives the deterministic session slug from. |
+| `subject_id` | yes | The provider subject key. The local-file provider uses the deterministic session slug; provider-backed records may use their native subject identifier. |
 | `actor` | yes | `{ runtime, session_id, host, human? }` — the exact struct `actor-identity.js` defines. `human` is set (non-null) only for a human assignee; its presence, not a username heuristic, gates the human-held join state. |
 | `actor_key` | no (additive, #291) | The canonical `resolveActor(env).actor` string for the claiming actor — the same flat/bare token `liveness whoami`, `liveness claim --actor`, per-actor `current.json`, and pull-work's `--self-actor` all use. When present, `computeEffectiveState` compares against THIS (not a re-serialization of `actor`) for both self-recognition and the liveness join, because `serializeActor(actor)` and `resolveActor(env).actor` diverge for an explicit-override actor (a bare token vs. a `explicit-override:<value>:<host>` triple) while agreeing for a derived actor. Absent on any pre-#291 record or fixture — `computeEffectiveState` falls back to `serializeActor(actor)` in that case, reproducing pre-#291 behavior exactly. |
+| `work_item_ref` | no (additive, #541) | Exact Work Item reference acquired by Builder `ensure-session`. This preserves identity beyond the local provider's lossy filesystem slug and allows an interrupted acquisition to retry safely. Older records and ordinary assignment-provider claims omit it and cannot automatically satisfy `builder.pull-work.selected`. |
 | `claimed_at` | yes | ISO-8601 timestamp the claim was recorded. Mirrors the liveness stream's own claim-event field so a reader compares freshness with one mental model across both layers, even though the two are stored in different media. |
 | `ttl_seconds` | yes | Same field name/semantics as the liveness stream's `ttlSeconds` (default `1800`). |
 | `branch` | yes | The branch this actor is working on, per the `agent/<actor>/<slug>` convention. |

package/context/scripts/hooks/config-protection.js

@@ -120,6 +120,13 @@ function checkProtectedPathPattern(filePath) {
     };
   }
 
+  if (/(?:^|\/)\.flow-agents\/lifecycle-authority-keys\.json$/.test(norm)) {
+    return {
+      name: '.flow-agents/lifecycle-authority-keys.json',
+      reason: 'an agent could replace the pinned lifecycle authority key and forge cancellation authority',
+    };
+  }
+
   // .kontourai/flow-agents/current.json — an agent could forge active_flow_id / active_step_id
   // to route the gate to a permissive or empty-expects FlowDefinition.
   // SAFE: the workflow CLI writes current.json via fs (writeJson → fs.writeFileSync),
@@ -426,7 +433,7 @@ function checkCommandForBypass(command) {
  */
 // #379: the delivery/ arms carry an optional (?:[^/]+\/)? segment so redirects/tee to the
 // per-session path delivery/<slug>/trust.bundle (+ checkpoint) are caught, not just the flat path.
-const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)\.flow-agents\/lifecycle-authority-keys\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
 
 /**
  * Return true when a token (an unquoted redirect target or tee argument) matches

package/context/scripts/hooks/lib/config-protection-remedies.js

@@ -20,6 +20,8 @@ const SANCTIONED_REMEDIES = {
     'There is no sanctioned automated writer for this file. Ask a human maintainer to edit it directly. Never disable this hook to make the write.',
   '.claude/settings.local.json':
     'There is no sanctioned automated writer for this file. Ask a human maintainer to edit it directly. Never disable this hook to make the write.',
+  '.flow-agents/lifecycle-authority-keys.json':
+    'Only the trusted harness installer or a human maintainer may rotate lifecycle authority keys. Never let an agent replace this trust root.',
   '.kontourai/flow-agents/current.json':
     'Use `npm run workflow:sidecar -- ensure-session` (or `advance-state`), which writes this file for you. Never disable this hook to make the write.',
   '.kontourai/flow-agents/current/<actor>.json':
@@ -58,6 +60,7 @@ function remedyFor(name) {
  * basename 'trust.bundle') -- first match wins, deterministically.
  */
 const REMEDY_COMMAND_CANDIDATES = [
+  { name: '.flow-agents/lifecycle-authority-keys.json', needles: ['lifecycle-authority-keys.json'] },
   { name: 'delivery/trust.checkpoint.json', needles: ['delivery/trust.checkpoint.json', 'trust.checkpoint.json'] },
   { name: 'delivery/trust.bundle', needles: ['delivery/trust.bundle'] },
   { name: '.kontourai/flow-agents/<slug>/trust.bundle', needles: ['trust.bundle'] },

package/context/scripts/hooks/stop-goal-fit.js

@@ -77,7 +77,7 @@ const PRE_EXECUTION_PHASES = new Set(['idea', 'backlog', 'pickup', 'planning']);
 // Terminal tasks are complete — they must never gate a stop or count as "active".
 // A stale current.json pointing at one, or a graveyard of finished states, must
 // not block an unrelated session.
-const TERMINAL_STATUSES = new Set(['done', 'delivered', 'accepted', 'archived', 'complete', 'completed']);
+const TERMINAL_STATUSES = new Set(['done', 'delivered', 'canceled', 'accepted', 'archived', 'complete', 'completed']);
 
 function isTerminalDeliveredState(state) {
   if (!state || typeof state !== 'object') return false;

package/docs/context-map.md

@@ -54,8 +54,10 @@ Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/f
 | --- | --- | --- |
 | assignment-provider-settings.schema.json | Flow Agents Assignment Provider Settings | https://flow-agents.dev/schemas/assignment-provider-settings.schema.json |
 | backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-settings.schema.json |
+| builder-lifecycle-authorization.schema.json | Builder Lifecycle Authorization | https://kontourai.dev/schemas/builder-lifecycle-authorization.schema.json |
 | decision-record.schema.json | Flow Agents Decision Record | https://flow-agents.dev/schemas/decision-record.schema.json |
 | flow-agents-settings.schema.json | Flow Agents Settings | https://flow-agents.dev/schemas/flow-agents-settings.schema.json |
+| lifecycle-authority-keys.schema.json | Lifecycle Authority Key Registry | https://kontourai.dev/schemas/lifecycle-authority-keys.schema.json |
 | workflow-acceptance.schema.json | Flow Agents Workflow Acceptance | https://flow-agents.dev/schemas/workflow-acceptance.schema.json |
 | workflow-critique.schema.json | Flow Agents Workflow Critique | https://flow-agents.dev/schemas/workflow-critique.schema.json |
 | workflow-evidence.schema.json | Flow Agents Workflow Evidence | https://flow-agents.dev/schemas/workflow-evidence.schema.json |

package/docs/public-workflow-cli.md

@@ -0,0 +1,63 @@
+# Public Workflow CLI
+
+Flow Agents exposes its supported consumer workflow surface through the primary package binary.
+Consumer repositories do not need a `package.json`, a local dependency, or a repository-owned
+writer script.
+
+Use an exact package version from an isolated npm prefix. This prevents a repository-local
+dependency with the same version from intercepting the command. Generated workflow actions and
+doctor remediation include this isolation automatically:
+
+```bash
+flow_agents() (
+  root=$(mktemp -d) || exit 1
+  trap 'rm -rf "$root"' EXIT HUP INT TERM
+  npm exec --yes --prefix "$root" \
+    --package=@kontourai/flow-agents@3.5.0 -- flow-agents "$@"
+)
+
+flow_agents workflow start \
+  --flow builder.build \
+  --work-item owner/repository#123
+
+flow_agents workflow status --json
+
+flow_agents workflow evidence \
+  --expectation implementation-plan \
+  --status pass \
+  --summary "Implementation plan recorded." \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/example/example--plan.md"}'
+```
+
+The public lifecycle verbs are `pause`, `resume`, `release`, `cancel`, and `archive`. Pause,
+resume, and release require the current assignment actor and an explicit reason. Cancel and
+archive require a signed user/operator authorization file. Flow owns the canonical run
+transition; Flow Agents validates assignment and request binding and projects the resulting run.
+
+```bash
+flow_agents workflow pause --reason "Waiting for a decision"
+flow_agents workflow resume --reason "Decision received"
+flow_agents workflow release --reason "Handing work back"
+flow_agents workflow cancel --authorization-file cancel.json
+flow_agents workflow archive --authorization-file archive.json
+```
+
+`workflow status` is read-only. It reads the actor-scoped current-session pointer, the projected
+state, and the canonical Flow run without rewriting either store.
+
+## Compatibility Doctor
+
+Run doctor through the exact isolated package helper defined above:
+
+```bash
+flow_agents workflow doctor --json
+```
+
+The report distinguishes the executing CLI from a repository-local dependency and reports the
+workflow/writer contract, installed hook and writer package, active Kits, Builder Kit content,
+Flow runtime and definition, workflow-state schema, and trust-bundle schema. Incompatible or
+missing installed components produce a nonzero exit and an exact, version-pinned `init` command
+that preserves the recorded runtime and active Kits.
+
+The `flow-agents-workflow-sidecar` binary is deprecated and retained only while package-internal
+callers migrate. New consumer guidance must use `flow-agents workflow`.

package/docs/spec/builder-flow-runtime.md

@@ -36,11 +36,18 @@ flow-agents builder-run start --session-dir .kontourai/flow-agents/<slug>
 ```
 
 `ensure-session --flow-id builder.build` starts or loads this canonical run before
-returning, then projects the first Flow step into the sidecar. The command remains
-the explicit recovery path if Flow startup fails after sidecar creation; the
-failure is returned to the caller and no substitute run state is invented. Runtime
-hooks keep projected actions advisory while the agent performs their declared
-skills and operations.
+returning. When the local assignment provider durably assigns the exact Work Item
+to the resolved workflow actor, `ensure-session` rereads that record and produces
+the declared `builder.pull-work.selected` claim through the normal Surface trust
+bundle path. Flow evaluates that subject-bound evidence and advances to
+`design-probe`; Flow Agents does not write a transition or gate outcome directly.
+Skipped ownership, unresolved actors, precomputed state, and non-local providers do
+not produce selection evidence and remain at `pull-work`.
+
+The command remains the explicit recovery path if Flow startup fails after sidecar
+creation; the failure is returned to the caller and no substitute run state is
+invented. Runtime hooks keep projected actions advisory while the agent performs
+their declared skills and operations.
 
 Sidecars written by 3.4.2 may still contain `next_action.enforcement`. The 1.0
 schema accepts that deprecated field for artifact compatibility, but current
@@ -111,3 +118,40 @@ Workflow steering surfaces these fields on session start and prompt submission.
 Stop hook treats an unfinished canonical Flow run as active even during pickup or
 planning, blocks a premature stop in block mode, and does not release its liveness
 claim. A run is complete only when Flow reaches its terminal step.
+# Builder Lifecycle Authority
+
+The canonical Flow run owns pause, resume, and cancellation. The current assignment actor may
+pause, resume, or release its own assignment with a reason. Cancellation and archival require
+an Ed25519-signed authorization record conforming to
+`schemas/builder-lifecycle-authorization.schema.json`. The record is operation-bound and binds
+the request to the run id, selected Work Item, current assignment actor, immutable external
+request reference, nonce, and expiry. Its signing key must be pinned in the durable
+`.flow-agents/lifecycle-authority-keys.json` registry. Runtime or harness adapters hold the
+private key and capture the signed record from a user/operator channel they trust; agent-authored
+prose or an unsigned model-written file is not cancellation authority.
+
+This is an audit and policy boundary, not authentication against a process with unrestricted
+access as the same operating-system user. The harness must keep its signing key outside the
+agent process and enforce its own filesystem or process isolation when the agent is adversarial.
+The repository hooks protect the pinned public-key registry from ordinary agent writes, but are
+explicitly not an operating-system security boundary.
+Adversarial-runtime authentication is tracked separately in Flow Agents issue #545. Flow's
+current lifecycle authority vocabulary also requires agent-owned pause/resume events to use the
+closest available `operator_request` shape; a distinct canonical runtime authority is tracked in
+Flow issue #118.
+
+```text
+flow-agents builder-run pause --session-dir <dir> --reason <text>
+flow-agents builder-run resume --session-dir <dir> --reason <text>
+flow-agents builder-run cancel --session-dir <dir> --authorization-file <record.json>
+flow-agents builder-run release-assignment --session-dir <dir> --reason <text>
+flow-agents builder-run archive --session-dir <dir> --authorization-file <record.json>
+```
+
+Pause and resume verify the live assignment actor under the assignment lock, and preserve the
+current Flow step and assignment. Assignment release does not
+change the Flow run. Cancellation changes Flow first and then idempotently releases the owning
+assignment while holding the same lock; a successfully consumed cancellation nonce cannot be
+replayed. Archive accepts only completed or canceled runs, moves the session under
+`.kontourai/flow-agents/archive/<slug>/`, and retains the canonical Flow run. None of these
+operations deletes a branch or worktree; cleanup requires a separate provider-aware action.

package/docs/workflow-usage-guide.md

@@ -4,6 +4,11 @@ title: Workflow Usage Guide
 
 # Workflow Usage Guide
 
+> Consumer repositories should use the supported public workflow surface and isolated exact-package
+> launcher documented in [Public Workflow CLI](public-workflow-cli.md). The lower-level writer
+> commands retained later in this guide describe internal/package migration mechanics and are not a
+> consumer prerequisite.
+
 This guide shows how to use the Builder Kit workflow skills in normal chats.
 
 > **Which doc do I want?** This page is the *driver's manual* — what to say at each stage and what should happen. If you want the conceptual map first — layers, sidecars, hooks, evidence, and why the system is shaped this way — read the [Agent System Guidebook](agent-system-guidebook.md). For a one-line summary of every skill and gate, use the [Skills Map](skills-map.md). Flow Agents coordinates the local runtime, installs Flow Kits, and records artifacts; Flow owns gate semantics, including typed `expects` entries with `kind: "trust.bundle"`, trusted producer config, and gate overrides.

package/evals/ci/run-baseline.sh

@@ -41,6 +41,7 @@ CHECKS=(
   "Flow Kit repository integration|bash evals/integration/test_flow_kit_repository.sh"
   "Runtime adapter activation integration|bash evals/integration/test_runtime_adapter_activation.sh"
   "Bundle install integration|bash evals/integration/test_bundle_install.sh"
+  "Public workflow CLI integration|bash evals/integration/test_public_workflow_cli.sh"
   "Bundle lifecycle integration|bash evals/integration/test_bundle_lifecycle.sh"
   "Activate npx context integration|bash evals/integration/test_activate_npx_context.sh"
   "Kit conformance levels integration|bash evals/integration/test_kit_conformance_levels.sh"
@@ -133,6 +134,7 @@ LANE_RUNTIME_AND_KIT=(
   "Flow Kit repository integration"
   "Runtime adapter activation integration"
   "Bundle install integration"
+  "Public workflow CLI integration"
   "Bundle lifecycle integration"
   "Activate npx context integration"
   "Kit conformance levels integration"

package/evals/integration/test_assignment_provider_local_file.sh

@@ -69,6 +69,60 @@ node "$CLI" assignment-provider status \
 [[ "$(json_query "$TMPDIR_EVAL/status-a.json" "assignment.assignee")" == "claude-code:eval-actor-a-session:eval-host" ]] && pass "status reports actor A as assignee" || fail "status reports actor A as assignee"
 [[ "$(json_query "$TMPDIR_EVAL/status-a.json" "assignment.record.claimed_at")" == "$CLAIMED_AT" ]] && pass "status claimed_at matches claim's claimed_at" || fail "status claimed_at matches claim's claimed_at"
 
+# A generic same-actor refresh must preserve exact Builder provenance that an interrupted
+# ensure-session recorded, even though the assignment-provider CLI does not accept that field.
+PROVENANCE_SUBJECT="builder-provenance"
+node "$CLI" assignment-provider claim \
+  --provider local-file --artifact-root "$ARTIFACT_ROOT" \
+  --subject-id "$PROVENANCE_SUBJECT" \
+  --actor-json "$ACTOR_A" \
+  --branch "$BRANCH_A" \
+  --artifact-dir "$ARTIFACT_DIR_A" \
+  --ttl-seconds 1800 \
+  > "$TMPDIR_EVAL/provenance-claim.json"
+PROVENANCE_FILE="$(node - "$ARTIFACT_ROOT/assignment" "$PROVENANCE_SUBJECT" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const [dir, subject] = process.argv.slice(2);
+for (const name of fs.readdirSync(dir)) {
+  if (!name.endsWith('.json')) continue;
+  const file = path.join(dir, name);
+  if (JSON.parse(fs.readFileSync(file, 'utf8')).subject_id === subject) {
+    process.stdout.write(file);
+    process.exit(0);
+  }
+}
+process.exit(1);
+NODE
+)"
+node - "$PROVENANCE_FILE" <<'NODE'
+const fs = require('node:fs');
+const file = process.argv[2];
+const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+record.work_item_ref = 'kontourai/flow-agents#9001';
+fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+NODE
+node "$CLI" assignment-provider claim \
+  --provider local-file --artifact-root "$ARTIFACT_ROOT" \
+  --subject-id "$PROVENANCE_SUBJECT" \
+  --actor-json "$ACTOR_A" \
+  --branch "$BRANCH_A" \
+  --artifact-dir "$ARTIFACT_DIR_A" \
+  --ttl-seconds 1800 \
+  > "$TMPDIR_EVAL/provenance-refresh.json"
+[[ "$(json_query "$TMPDIR_EVAL/provenance-refresh.json" "record.work_item_ref")" == "$SUBJECT_ID" ]] && pass "same-actor refresh preserves exact Work Item provenance" || fail "same-actor refresh preserves exact Work Item provenance"
+node "$CLI" assignment-provider supersede \
+  --provider local-file --artifact-root "$ARTIFACT_ROOT" \
+  --subject-id "$PROVENANCE_SUBJECT" \
+  --from-actor-json "$ACTOR_A" --to-actor-json "$ACTOR_B" \
+  --reason "provenance handoff" >"$TMPDIR_EVAL/provenance-supersede.json"
+[[ "$(json_query "$TMPDIR_EVAL/provenance-supersede.json" "record.work_item_ref")" == "$SUBJECT_ID" ]] && pass "generic supersede preserves exact Work Item provenance" || fail "generic supersede preserves exact Work Item provenance"
+node "$CLI" assignment-provider release \
+  --provider local-file --artifact-root "$ARTIFACT_ROOT" \
+  --subject-id "$PROVENANCE_SUBJECT" \
+  --actor-json "$ACTOR_B" \
+  --reason "provenance fixture cleanup" >/dev/null
+
 # 3. supersede A -> B updates the actor and records an audit trail entry.
 node "$CLI" assignment-provider supersede \
   --provider local-file --artifact-root "$ARTIFACT_ROOT" --subject-id "$SUBJECT_ID" \