@kontourai/flow-agents 3.5.0 → 3.6.0

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

@@ -118,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_builder_entry_enforcement.sh

@@ -209,7 +209,7 @@ if (workItem.source_provider?.kind !== 'local' || workItem.source_provider?.path
 if (flowState.current_step !== 'design-probe' || flowState.subject !== 'local:local-request') process.exit(1);
 if (state.flow_run?.current_step !== 'design-probe') process.exit(1);
 if (JSON.stringify(state.next_action?.skills) !== JSON.stringify(['pickup-probe'])) process.exit(1);
-if (!state.next_action?.command?.includes('builder-run sync')) process.exit(1);
+if (!state.next_action?.command?.includes("'workflow' 'status'")) process.exit(1);
 if ('enforcement' in state.next_action) process.exit(1);
 const bundle = JSON.parse(fs.readFileSync(path.join(root, 'local-request', 'trust.bundle'), 'utf8'));
 const selected = (bundle.claims || []).find((claim) => claim.claimType === 'builder.pull-work.selected');
@@ -247,7 +247,7 @@ const sidecar = JSON.parse(fs.readFileSync(path.join(session, 'state.json'), 'ut
 if (flowState.current_step !== 'design-probe' || flowState.subject !== 'local:local-request') process.exit(1);
 if (sidecar.flow_run?.current_step !== 'design-probe') process.exit(1);
 if (JSON.stringify(sidecar.next_action?.skills) !== JSON.stringify(['pickup-probe'])) process.exit(1);
-if (!sidecar.next_action?.command?.includes('builder-run sync')) process.exit(1);
+if (!sidecar.next_action?.command?.includes("'workflow' 'status'")) process.exit(1);
 NODE
 then
   pass "repeated ensure-session loads the canonical Flow run without resetting its history"
@@ -275,7 +275,7 @@ elif [[ -f "$BROKEN_ROOT/broken-start/state.json" ]] \
 const fs = require('node:fs');
 const state = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
 if (state.flow_run) process.exit(1);
-if (!state.next_action?.command?.includes('builder-run start')) process.exit(1);
+if (!state.next_action?.command?.includes("'workflow' 'start'")) process.exit(1);
 NODE
 then
   pass "failed canonical startup is visible and leaves only retryable sidecar guidance"
@@ -482,12 +482,13 @@ else
   stop_status=$?
   if [[ "$stop_status" -eq 2 ]] \
     && grep -q 'required skills: pickup-probe' "$TMP/stop.err" \
-    && grep -q 'builder-run sync' "$TMP/stop.err" \
+    && grep -q 'next command: sh -c' "$TMP/stop.err" \
     && grep -q 'release skipped for active Flow run' "$TMP/stop.err" \
     && node - "$LOCAL_SESSION/state.json" <<'NODE'
 const fs = require('node:fs');
 const state = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
 if (state.flow_run?.status !== 'active' || state.flow_run?.current_step !== 'design-probe') process.exit(1);
+if (!state.next_action?.command?.includes("'workflow' 'status'")) process.exit(1);
 NODE
   then
     pass "active Flow run blocks Stop, preserves liveness, and exposes executable guidance"

package/evals/integration/test_bundle_install.sh

@@ -896,18 +896,19 @@ cat >"$PACKAGE_AMBIENT/kits/builder/flows/build.flow.json" <<'JSON'
 }
 JSON
 PACKAGE_PACK_LOG="$TMPDIR_EVAL/package-pack.log"
+PACKAGE_CLI="$PACKAGE_CONSUMER/node_modules/@kontourai/flow-agents/build/src/cli.js"
+PACKAGE_SESSION="$PACKAGE_PROJECT/.kontourai/flow-agents/packed-builder-entry"
 if (cd "$ROOT_DIR" && npm pack --silent --pack-destination "$TMPDIR_EVAL" >"$PACKAGE_PACK_LOG") \
   && PACKAGE_TARBALL="$(find "$TMPDIR_EVAL" -maxdepth 1 -type f -name 'kontourai-flow-agents-*.tgz' -print -quit)" \
   && [[ -n "$PACKAGE_TARBALL" ]] \
   && npm install --silent --no-audit --no-fund --ignore-scripts --prefix "$PACKAGE_CONSUMER" "$PACKAGE_TARBALL" \
-  && (cd "$PACKAGE_AMBIENT" && node "$PACKAGE_CONSUMER/node_modules/@kontourai/flow-agents/build/src/cli/workflow-sidecar.js" ensure-session \
+  && (cd "$PACKAGE_AMBIENT" && CODEX_SESSION_ID=packed-package-consumer node "$PACKAGE_CONSUMER/node_modules/@kontourai/flow-agents/build/src/cli/workflow-sidecar.js" ensure-session \
     --artifact-root "$PACKAGE_PROJECT/.kontourai/flow-agents" \
     --task-slug packed-builder-entry \
-    --actor packed-package-consumer \
     --title "Packed Builder entry" \
     --summary "Installed package should project pickup-probe." \
     --flow-id builder.build >/dev/null 2>&1) \
-  && node - "$PACKAGE_PROJECT" <<'NODE'
+  && node - "$PACKAGE_PROJECT" <<'NODE' &&
 const fs = require('node:fs');
 const path = require('node:path');
 const project = process.argv[2];
@@ -917,11 +918,64 @@ const bundle = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow
 if (flow.current_step !== 'design-probe' || state.flow_run?.current_step !== 'design-probe') process.exit(1);
 if (JSON.stringify(state.next_action?.skills) !== JSON.stringify(['pickup-probe'])) process.exit(1);
 if (!(bundle.claims || []).some((claim) => claim.claimType === 'builder.pull-work.selected' && claim.status === 'verified')) process.exit(1);
+NODE
+  node --input-type=module - "$PACKAGE_PROJECT" "$PACKAGE_CONSUMER" <<'NODE' &&
+import fs from 'node:fs';
+import path from 'node:path';
+import { generateKeyPairSync, sign } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+const [project, consumer] = process.argv.slice(2);
+const slug = 'packed-builder-entry';
+const assignment = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow-agents', 'assignment', `${slug}.json`), 'utf8'));
+const state = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow-agents', slug, 'state.json'), 'utf8'));
+const packageEntry = path.join(consumer, 'node_modules', '@kontourai', 'flow-agents', 'build', 'src', 'index.js');
+const { builderLifecycleAuthorizationPayload } = await import(pathToFileURL(packageEntry).href);
+const keys = generateKeyPairSync('ed25519');
+const keyId = 'packed-consumer';
+fs.mkdirSync(path.join(project, '.flow-agents'), { recursive: true });
+fs.writeFileSync(path.join(project, '.flow-agents', 'lifecycle-authority-keys.json'), JSON.stringify({
+  schema_version: '1.0',
+  keys: [{ id: keyId, algorithm: 'ed25519', public_key_pem: keys.publicKey.export({ type: 'spki', format: 'pem' }) }],
+}, null, 2));
+for (const operation of ['cancel', 'archive']) {
+  const requestedAt = new Date();
+  const unsigned = {
+    schema_version: '1.0',
+    operation,
+    run_id: slug,
+    subject: state.work_item_refs[0],
+    assignment_actor_key: assignment.actor_key,
+    assignment_actor: { ...assignment.actor, human: assignment.actor.human ?? null },
+    nonce: `packed-${operation}`,
+    expires_at: new Date(requestedAt.getTime() + 60 * 60_000).toISOString(),
+    request: {
+      reason: `packed consumer ${operation}`,
+      authority: { kind: 'user_request', actor: 'packed-fixture', request_ref: `fixture://packed/${operation}`, requested_at: requestedAt.toISOString() },
+    },
+  };
+  const authorization = { ...unsigned, signature: { algorithm: 'ed25519', key_id: keyId, value: sign(null, Buffer.from(builderLifecycleAuthorizationPayload(unsigned)), keys.privateKey).toString('base64') } };
+  fs.writeFileSync(path.join(project, `${operation}.authorization.json`), JSON.stringify(authorization, null, 2));
+}
+NODE
+  (cd "$PACKAGE_PROJECT" && CODEX_SESSION_ID=packed-package-consumer node "$PACKAGE_CLI" builder-run pause --session-dir "$PACKAGE_SESSION" --reason "packed pause" >/dev/null) \
+  && (cd "$PACKAGE_PROJECT" && CODEX_SESSION_ID=packed-package-consumer node "$PACKAGE_CLI" builder-run resume --session-dir "$PACKAGE_SESSION" --reason "packed resume" >/dev/null) \
+  && (cd "$PACKAGE_PROJECT" && node "$PACKAGE_CLI" builder-run cancel --session-dir "$PACKAGE_SESSION" --authorization-file "$PACKAGE_PROJECT/cancel.authorization.json" >/dev/null) \
+  && (cd "$PACKAGE_PROJECT" && node "$PACKAGE_CLI" builder-run archive --session-dir "$PACKAGE_SESSION" --authorization-file "$PACKAGE_PROJECT/archive.authorization.json" >/dev/null) \
+  && node - "$PACKAGE_PROJECT" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const project = process.argv[2];
+const slug = 'packed-builder-entry';
+const archived = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow-agents', 'archive', slug, 'state.json'), 'utf8'));
+const flow = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow', 'runs', slug, 'state.json'), 'utf8'));
+const consumed = fs.readdirSync(path.join(project, '.kontourai', 'flow-agents', 'lifecycle-authority', 'consumed'));
+if (archived.status !== 'archived' || flow.status !== 'canceled' || consumed.length !== 2) process.exit(1);
+if (fs.existsSync(path.join(project, '.kontourai', 'flow-agents', slug))) process.exit(1);
 NODE
 then
-  _pass "packed npm consumer ignores unrelated ambient Flow definitions and projects pickup-probe"
+  _pass "packed npm consumer projects Builder entry and executes lifecycle commands"
 else
-  _fail "packed npm consumer did not execute canonical Builder entry"
+  _fail "packed npm consumer did not execute canonical Builder entry and lifecycle commands"
 fi
 
 if [[ -d "$CODEX_FULL_DEST/.codex/skills/plan-work" && -d "$CODEX_FULL_DEST/.codex/skills/deliver" && -d "$CODEX_FULL_DEST/.codex/skills/agentic-engineering" ]]; then

package/evals/integration/test_public_workflow_cli.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+fail() { printf 'FAIL %s\n' "$*" >&2; exit 1; }
+pass() { printf 'PASS %s\n' "$*"; }
+
+cd "$ROOT_DIR"
+npm run build --silent
+npm run build:bundles --silent
+npm pack --silent --pack-destination "$TMP" >/dev/null
+TARBALL="$(find "$TMP" -maxdepth 1 -name 'kontourai-flow-agents-*.tgz' -print -quit)"
+[[ -n "$TARBALL" ]] || fail "npm pack did not produce a tarball"
+VERSION="$(node -p "require('./package.json').version")"
+CONSUMER="$TMP/consumer"
+ARTIFACT_ROOT="$CONSUMER/.kontourai/flow-agents"
+mkdir -p "$CONSUMER"
+
+run_candidate() {
+  (cd "$CONSUMER" && CODEX_SESSION_ID=public-workflow-eval npx --yes --package="file:$TARBALL" flow-agents workflow "$@")
+}
+
+PRIMARY_HELP="$(cd "$CONSUMER" && npx --yes --package="file:$TARBALL" flow-agents --help)"
+WORKFLOW_HELP="$(run_candidate --help)"
+[[ "$PRIMARY_HELP" == *"workflow"* && "$WORKFLOW_HELP" != *"workflow-sidecar"* && "$WORKFLOW_HELP" != *"npm run workflow:sidecar"* ]] || fail "public help exposes internal writer terminology or omits workflow"
+pass "primary help exposes the public workflow command without internal writer terminology"
+
+run_candidate start --artifact-root "$ARTIFACT_ROOT" --flow builder.build --work-item acme/widgets#101 --summary "Release fixture" >/dev/null
+RELEASE_SESSION="$ARTIFACT_ROOT/acme-widgets-101"
+[[ -f "$RELEASE_SESSION/state.json" ]] || fail "packed start did not create a session"
+[[ ! -e "$CONSUMER/package.json" ]] || fail "consumer unexpectedly gained package.json"
+pass "packed start works in a non-Node consumer"
+set +e
+UNSAFE_START="$(run_candidate start --artifact-root "$ARTIFACT_ROOT" --flow builder.build --work-item acme/widgets#103 --skip-ownership-guard 2>&1)"
+UNSAFE_START_RC=$?
+set -e
+[[ "$UNSAFE_START_RC" -ne 0 && "$UNSAFE_START" == *"does not support --skip-ownership-guard"* && ! -e "$ARTIFACT_ROOT/acme-widgets-103" ]] || fail "public start accepted an internal ownership bypass"
+pass "public start rejects internal authority flags before mutation"
+
+LOCAL_RETRY_PROJECT="$TMP/local-retry-project"
+LOCAL_RETRY_ROOT="$LOCAL_RETRY_PROJECT/.kontourai/flow-agents"
+mkdir -p "$LOCAL_RETRY_PROJECT/.kontourai"
+printf 'not a run-store directory\n' >"$LOCAL_RETRY_PROJECT/.kontourai/flow"
+set +e
+(cd "$LOCAL_RETRY_PROJECT" && CODEX_SESSION_ID=public-workflow-eval npx --yes --package="file:$TARBALL" flow-agents-workflow-sidecar ensure-session \
+  --artifact-root "$LOCAL_RETRY_ROOT" --task-slug local-retry \
+  --title "Local retry" --summary "Resume the bound local workflow." --flow-id builder.build >/dev/null 2>&1)
+LOCAL_SEED_RC=$?
+set -e
+[[ "$LOCAL_SEED_RC" -ne 0 ]] || fail "local retry fixture unexpectedly started against an invalid Flow store"
+LOCAL_RETRY_COMMAND="$(node -p "JSON.parse(require('fs').readFileSync('$LOCAL_RETRY_ROOT/local-retry/state.json')).next_action.command")"
+[[ "$LOCAL_RETRY_COMMAND" == *"'--work-item' 'local:local-retry'"* && "$LOCAL_RETRY_COMMAND" == *"'--task-slug' 'local-retry'"* && "$LOCAL_RETRY_COMMAND" == *"'--artifact-root' '$LOCAL_RETRY_ROOT'"* ]] || fail "emitted local retry did not bind its Work Item, slug, and originating artifact root"
+rm -f "$LOCAL_RETRY_PROJECT/.kontourai/flow"
+FOREIGN_RETRY_CWD="$TMP/foreign-retry-cwd"
+mkdir -p "$FOREIGN_RETRY_CWD"
+EXECUTABLE_RETRY="$(node -e 'process.stdout.write(process.argv[1].replace(process.argv[2], process.argv[3]))' "$LOCAL_RETRY_COMMAND" "'@kontourai/flow-agents@$VERSION'" "'file:$TARBALL'")"
+(cd "$FOREIGN_RETRY_CWD" && CODEX_SESSION_ID=public-workflow-eval eval "$EXECUTABLE_RETRY" >/dev/null)
+[[ -f "$LOCAL_RETRY_PROJECT/.kontourai/flow/runs/local-retry/state.json" && ! -e "$FOREIGN_RETRY_CWD/.kontourai" ]] || fail "emitted local retry mutated the caller cwd instead of the originating store"
+pass "emitted local retry executes from a foreign cwd against its exact originating store"
+
+snapshot_tree() {
+  local root="$1"
+  find "$root" -type f -print0 | sort -z | xargs -0 shasum -a 256
+}
+BEFORE_STATUS="$(snapshot_tree "$CONSUMER/.kontourai")"
+STATUS_JSON="$(run_candidate status --artifact-root "$ARTIFACT_ROOT" --json)"
+AFTER_STATUS="$(snapshot_tree "$CONSUMER/.kontourai")"
+[[ "$BEFORE_STATUS" == "$AFTER_STATUS" ]] || fail "workflow status mutated durable artifacts"
+node -e 'const r=JSON.parse(process.argv[1]); if(r.definition_id!=="builder.build"||r.current_step!=="design-probe")process.exit(1)' "$STATUS_JSON" || fail "status did not report canonical run"
+pass "status is canonical and byte-read-only"
+
+FLOW_MANIFEST="$CONSUMER/.kontourai/flow/runs/acme-widgets-101/evidence/manifest.json"
+BEFORE_EVIDENCE="$(node -p "JSON.parse(require('fs').readFileSync('$FLOW_MANIFEST')).evidence.length")"
+run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status not_verified --summary "Consumer fixture intentionally leaves this claim unverified." --json >/dev/null
+AFTER_EVIDENCE="$(node -p "JSON.parse(require('fs').readFileSync('$FLOW_MANIFEST')).evidence.length")"
+[[ "$AFTER_EVIDENCE" -eq $((BEFORE_EVIDENCE + 1)) ]] || fail "evidence invocation did not attach exactly once"
+pass "evidence records and synchronizes exactly once"
+
+OUTSIDE="$TMP/outside-session"
+mkdir -p "$OUTSIDE"
+printf '{"schema_version":"1.0","task_slug":"outside"}\n' >"$OUTSIDE/state.json"
+ln -s "$OUTSIDE" "$ARTIFACT_ROOT/symlink-session"
+OUTSIDE_BEFORE="$(snapshot_tree "$OUTSIDE")"
+set +e
+SYMLINK_EVIDENCE="$(run_candidate evidence --session-dir "$ARTIFACT_ROOT/symlink-session" --expectation pickup-probe-readiness --status not_verified --summary rejected 2>&1)"
+SYMLINK_RC=$?
+set -e
+[[ "$SYMLINK_RC" -ne 0 && "$SYMLINK_EVIDENCE" == *"session directory must be a non-symlink directory"* && "$(snapshot_tree "$OUTSIDE")" == "$OUTSIDE_BEFORE" ]] || fail "evidence followed a symlinked session"
+pass "evidence rejects symlinked session paths before mutation"
+
+run_candidate pause --session-dir "$RELEASE_SESSION" --reason "consumer pause" >/dev/null
+run_candidate resume --session-dir "$RELEASE_SESSION" --reason "consumer resume" >/dev/null
+run_candidate release --session-dir "$RELEASE_SESSION" --reason "consumer release" >/dev/null
+node -e 'const fs=require("fs");const r=JSON.parse(fs.readFileSync(process.argv[1]));if(r.status!=="released")process.exit(1)' "$ARTIFACT_ROOT/assignment/acme-widgets-101.json" || fail "release did not release assignment"
+pass "pause, resume, and release use the public command"
+
+run_candidate start --artifact-root "$ARTIFACT_ROOT" --flow builder.build --work-item acme/widgets#102 --summary "Cancel fixture" >/dev/null
+CANCEL_SESSION="$ARTIFACT_ROOT/acme-widgets-102"
+node --input-type=module - "$CONSUMER" "$CANCEL_SESSION" <<'NODE'
+import fs from 'node:fs';
+import path from 'node:path';
+import { generateKeyPairSync, sign } from 'node:crypto';
+const [project, session] = process.argv.slice(2);
+const slug = path.basename(session);
+const assignment = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow-agents', 'assignment', `${slug}.json`), 'utf8'));
+const state = JSON.parse(fs.readFileSync(path.join(session, 'state.json'), 'utf8'));
+const keys = generateKeyPairSync('ed25519');
+fs.mkdirSync(path.join(project, '.flow-agents'), { recursive: true });
+fs.writeFileSync(path.join(project, '.flow-agents', 'lifecycle-authority-keys.json'), JSON.stringify({ schema_version: '1.0', keys: [{ id: 'consumer', algorithm: 'ed25519', public_key_pem: keys.publicKey.export({ type: 'spki', format: 'pem' }) }] }, null, 2));
+for (const operation of ['cancel', 'archive']) {
+  const requestedAt = new Date();
+  const unsigned = {
+    schema_version: '1.0', operation, run_id: slug, subject: state.work_item_refs[0],
+    assignment_actor_key: assignment.actor_key,
+    assignment_actor: { ...assignment.actor, human: assignment.actor.human ?? null },
+    nonce: `consumer-${operation}`,
+    expires_at: new Date(requestedAt.getTime() + 3600000).toISOString(),
+    request: { reason: `consumer ${operation}`, authority: { kind: 'user_request', actor: 'consumer-user', request_ref: `fixture://consumer/${operation}`, requested_at: requestedAt.toISOString() } },
+  };
+  const authorization = { ...unsigned, signature: { algorithm: 'ed25519', key_id: 'consumer', value: sign(null, Buffer.from(JSON.stringify(unsigned)), keys.privateKey).toString('base64') } };
+  fs.writeFileSync(path.join(project, `${operation}.authorization.json`), JSON.stringify(authorization, null, 2));
+}
+NODE
+run_candidate cancel --session-dir "$CANCEL_SESSION" --authorization-file "$CONSUMER/cancel.authorization.json" >/dev/null
+run_candidate archive --session-dir "$CANCEL_SESSION" --authorization-file "$CONSUMER/archive.authorization.json" >/dev/null
+[[ -f "$ARTIFACT_ROOT/archive/acme-widgets-102/state.json" && ! -e "$CANCEL_SESSION" ]] || fail "cancel/archive did not retain archived session"
+pass "signed cancel and archive execute through the public command"
+
+DOCTOR="$TMP/doctor-consumer"
+mkdir -p "$DOCTOR/node_modules/@kontourai/flow-agents" "$DOCTOR/node_modules/.bin" "$DOCTOR/.flow-agents" "$DOCTOR/kits/builder/flows" "$DOCTOR/.kontourai/flow-agents/doctor-session"
+cat >"$DOCTOR/node_modules/@kontourai/flow-agents/package.json" <<'JSON'
+{"name":"@kontourai/flow-agents","version":"3.4.3","bin":{"flow-agents":"bin.js"}}
+JSON
+cat >"$DOCTOR/node_modules/.bin/flow-agents" <<'SH'
+#!/usr/bin/env bash
+echo STALE_LOCAL_BINARY
+SH
+chmod +x "$DOCTOR/node_modules/.bin/flow-agents"
+cat >"$DOCTOR/.flow-agents/install.json" <<'JSON'
+{"version":"3.4.3","runtime":"codex","active_kit_ids":["builder"]}
+JSON
+cat >"$DOCTOR/kits/builder/kit.json" <<'JSON'
+{"schema_version":"0.9","id":"builder"}
+JSON
+cat >"$DOCTOR/kits/builder/flows/build.flow.json" <<'JSON'
+{"id":"builder.build","version":"0.9"}
+JSON
+cat >"$DOCTOR/.kontourai/flow-agents/current.json" <<'JSON'
+{"active_slug":"doctor-session","artifact_dir":"doctor-session"}
+JSON
+cat >"$DOCTOR/.kontourai/flow-agents/doctor-session/state.json" <<'JSON'
+{"schema_version":"0.9","task_slug":"doctor-session","flow_run":{"definition_id":"builder.build","definition_version":"0.9"}}
+JSON
+cat >"$DOCTOR/.kontourai/flow-agents/doctor-session/trust.bundle" <<'JSON'
+{"schema_version":"0.9"}
+JSON
+set +e
+DOCTOR_JSON="$(cd "$DOCTOR" && npx --yes --package="file:$TARBALL" flow-agents workflow doctor --project-root "$DOCTOR" --artifact-root "$DOCTOR/.kontourai/flow-agents" --json 2>/dev/null)"
+DOCTOR_RC=$?
+set -e
+[[ "$DOCTOR_RC" -eq 2 ]] || fail "doctor should return 2 for incompatible consumer fixtures"
+node - "$DOCTOR_JSON" "$VERSION" "$DOCTOR" <<'NODE'
+const [reportText, version, root] = process.argv.slice(2);
+const report = JSON.parse(reportText);
+if (report.cli.version !== version || report.cli.workflow_contract_version !== '1.0') process.exit(1);
+if (report.local_dependency.version !== '3.4.3' || report.local_dependency.selected !== false) process.exit(2);
+if (!report.warnings.some((w) => w.includes('hook/writer version 3.4.3'))) process.exit(3);
+if (!report.warnings.some((w) => w.includes('Builder Kit'))) process.exit(4);
+if (!report.warnings.some((w) => w.includes('builder.build version 0.9'))) process.exit(5);
+if (!report.warnings.some((w) => w.includes('Artifact schema 0.9'))) process.exit(6);
+if (!report.warnings.some((w) => w.includes('Trust bundle schema 0.9'))) process.exit(7);
+if (!report.warnings.some((w) => w.includes('hook/writer assets failed integrity'))) process.exit(10);
+if (!report.remediation.startsWith('sh -c ') || !report.remediation.includes(`'@kontourai/flow-agents@${version}'`) || !report.remediation.includes("'--runtime' 'codex'") || !report.remediation.includes("'--activate-kit' 'builder'")) process.exit(8);
+if (report.cli.package_root.startsWith(root)) process.exit(9);
+NODE
+pass "doctor detects same-major hook/writer, Kit, Flow, and schema skew with exact remediation"
+[[ "$DOCTOR_JSON" != *"STALE_LOCAL_BINARY"* ]] || fail "explicit package invocation selected stale local binary"
+pass "explicit packed package wins over an old local dependency"
+
+node - "$DOCTOR/node_modules/@kontourai/flow-agents/package.json" "$VERSION" <<'NODE'
+const fs = require('node:fs');
+const [file, version] = process.argv.slice(2);
+const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+value.version = version;
+fs.writeFileSync(file, JSON.stringify(value));
+NODE
+SAME_VERSION_HELP="$(cd "$DOCTOR" && npx --yes --package="file:$TARBALL" flow-agents --help)"
+[[ "$SAME_VERSION_HELP" == *"workflow"* && "$SAME_VERSION_HELP" != *"STALE_LOCAL_BINARY"* ]] || fail "explicit tarball selected a hostile same-version local binary"
+pass "explicit tarball wins over a hostile same-version local binary"
+
+PINNED_COMMAND_MODULE="pinned-cli-command.js"
+ISOLATED_COMMAND="$(node --input-type=module - "$ROOT_DIR/build/src/lib/$PINNED_COMMAND_MODULE" "file:$TARBALL" <<'NODE'
+import { pathToFileURL } from 'node:url';
+const [modulePath, packageSpec] = process.argv.slice(2);
+const { isolatedPackageCommand } = await import(pathToFileURL(modulePath));
+console.log(isolatedPackageCommand(packageSpec, 'flow-agents', ['--help']));
+NODE
+)"
+ISOLATED_HELP="$(cd "$DOCTOR" && eval "$ISOLATED_COMMAND")"
+[[ "$ISOLATED_HELP" == *"workflow"* && "$ISOLATED_HELP" != *"STALE_LOCAL_BINARY"* ]] || fail "isolated package command selected a hostile same-version local binary"
+pass "generated isolated package command defeats a hostile same-version local binary"
+
+rm -f "$DOCTOR/kits/builder/kit.json" "$DOCTOR/kits/builder/flows/build.flow.json"
+printf '{"version":"%s","runtime":"codex","active_kit_ids":["builder"]}\n' "$VERSION" >"$DOCTOR/.flow-agents/install.json"
+set +e
+MISSING_JSON="$(cd "$DOCTOR" && npx --yes --package="file:$TARBALL" flow-agents workflow doctor --project-root "$DOCTOR" --artifact-root "$DOCTOR/.kontourai/flow-agents" --json 2>/dev/null)"
+MISSING_RC=$?
+set -e
+[[ "$MISSING_RC" -eq 2 ]] || fail "doctor should fail when an activated Kit is missing"
+node -e 'const r=JSON.parse(process.argv[1]);if(!r.warnings.some(w=>w.includes("Activated Builder Kit is missing"))||!r.warnings.some(w=>w.includes("Activated builder.build definition is missing")))process.exit(1)' "$MISSING_JSON" || fail "doctor did not report missing activated Kit components"
+pass "doctor fails closed for missing activated Kit components"
+
+HEALTHY="$TMP/healthy-install"
+mkdir -p "$HEALTHY"
+(cd "$HEALTHY" && npx --yes --package="file:$TARBALL" flow-agents init --runtime codex --dest "$HEALTHY" --activate-kit builder --yes >/dev/null)
+HEALTHY_JSON="$(cd "$HEALTHY" && npx --yes --package="file:$TARBALL" flow-agents workflow doctor --project-root "$HEALTHY" --artifact-root "$HEALTHY/.kontourai/flow-agents" --json)"
+node -e 'const r=JSON.parse(process.argv[1]);if(!r.ok||r.warnings.length||!r.hook.integrity.ok||r.installed.active_kit_ids[0]!=="builder")process.exit(1)' "$HEALTHY_JSON" || fail "doctor did not pass immediately after its own remediation install"
+pass "real init converges to doctor PASS"
+
+cp "$HEALTHY/build/src/cli/workflow.js" "$TMP/workflow.js.clean"
+printf '\n// WORKFLOW_CONTRACT_VERSION = "1.0"\n' >>"$HEALTHY/build/src/cli/workflow.js"
+set +e
+TAMPERED_CLI_JSON="$(cd "$HEALTHY" && npx --yes --package="file:$TARBALL" flow-agents workflow doctor --project-root "$HEALTHY" --artifact-root "$HEALTHY/.kontourai/flow-agents" --json 2>/dev/null)"
+TAMPERED_CLI_RC=$?
+set -e
+[[ "$TAMPERED_CLI_RC" -eq 2 && "$TAMPERED_CLI_JSON" == *"asset mismatch: build/src/cli/workflow.js"* ]] || fail "doctor accepted marker-preserving CLI tampering"
+cp "$TMP/workflow.js.clean" "$HEALTHY/build/src/cli/workflow.js"
+pass "doctor rejects marker-preserving CLI tampering"
+
+cp "$HEALTHY/.codex/hooks.json" "$TMP/hooks.json.clean"
+node - "$HEALTHY/.codex/hooks.json" <<'NODE'
+const fs = require('node:fs');
+const file = process.argv[2];
+const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+const group = value.hooks.SessionStart.find((entry) => JSON.stringify(entry).includes('workflow-steering'));
+group.hooks[0].command += '; true';
+fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+NODE
+set +e
+TAMPERED_HOOK_JSON="$(cd "$HEALTHY" && npx --yes --package="file:$TARBALL" flow-agents workflow doctor --project-root "$HEALTHY" --artifact-root "$HEALTHY/.kontourai/flow-agents" --json 2>/dev/null)"
+TAMPERED_HOOK_RC=$?
+set -e
+[[ "$TAMPERED_HOOK_RC" -eq 2 && "$TAMPERED_HOOK_JSON" == *"does not contain the packaged managed hooks"* ]] || fail "doctor accepted name-preserving hook tampering"
+cp "$TMP/hooks.json.clean" "$HEALTHY/.codex/hooks.json"
+pass "doctor rejects name-preserving hook configuration tampering"
+
+for RUNTIME in base claude-code opencode pi kiro; do
+  RUNTIME_ROOT="$TMP/runtime-$RUNTIME"
+  mkdir -p "$RUNTIME_ROOT"
+  (cd "$RUNTIME_ROOT" && npx --yes --package="file:$TARBALL" flow-agents init --runtime "$RUNTIME" --dest "$RUNTIME_ROOT" --activate-kit builder --yes >/dev/null)
+  RUNTIME_JSON="$(cd "$RUNTIME_ROOT" && npx --yes --package="file:$TARBALL" flow-agents workflow doctor --project-root "$RUNTIME_ROOT" --artifact-root "$RUNTIME_ROOT/.kontourai/flow-agents" --json)"
+  node -e 'const r=JSON.parse(process.argv[1]);if(!r.ok||r.warnings.length||!r.hook.integrity.ok)process.exit(1)' "$RUNTIME_JSON" || fail "doctor did not validate $RUNTIME runtime wiring"
+  pass "doctor validates $RUNTIME runtime wiring"
+done
+
+printf 'public workflow CLI integration passed\n'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -149,7 +149,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@kontourai/flow": "^3.0.0"
+    "@kontourai/flow": "^3.1.0"
   },
   "optionalDependencies": {
     "@kontourai/surface": "^2.0.0",