@kontourai/flow-agents 3.0.0 → 3.1.0

package/build/src/lib/flow-resolver.js

@@ -14,6 +14,8 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 // ─── Security: Layer 1 traversal defense ─────────────────────────────────────
 //
 // Both kitId and flowName originate from agent-writable sources (active_flow_id
@@ -270,30 +272,44 @@ function findRepoRoot(startDir) {
     // Fallback: process.cwd() covers the common "run from repo root" case
     return process.cwd();
 }
+/**
+ * Delegate to the shared pure-CJS per-actor current-pointer reader
+ * (scripts/hooks/lib/current-pointer.js), mirroring the exact createRequire idiom
+ * workflow-sidecar.ts already uses for its own cross-boundary CJS helper reuse (Wave 2 Task 2.2,
+ * #291). Deliberately NO inline duplicate fallback — this is the single choke point for the
+ * per-actor-first/legacy-fallback compat-shim rule; a second hand-rolled reader here would let it
+ * drift from every other consumer.
+ */
+function loadCurrentPointerHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/current-pointer.js");
+    return _req(helperPath);
+}
 /**
  * Resolve the active flow step from current.json.
  *
- * Reads active_flow_id and active_step_id from <flowAgentsDir>/current.json.
- * If both are present, delegates to resolveFlowStep. The repoRoot is derived by
- * walking upward from flowAgentsDir to find the nearest ancestor containing kits/,
- * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
- * subproject layouts without hardcoding the repo structure.
+ * Reads active_flow_id and active_step_id via the shared per-actor current-pointer helper
+ * (#291 Wave 2 Task 2.2): when `actorKey` is a resolved actor with its own
+ * `current/<actor>.json` projection, that file is preferred; otherwise (no actorKey, an
+ * unresolved actor, or no per-actor file yet) this falls straight back to the legacy global
+ * `<flowAgentsDir>/current.json` — IDENTICAL to this function's pre-#291 behavior for every
+ * caller that does not pass `actorKey`. The repoRoot is derived by walking upward from
+ * flowAgentsDir to find the nearest ancestor containing kits/, with a fallback to
+ * process.cwd(). This handles temp dirs, CI workspaces, and subproject layouts without
+ * hardcoding the repo structure.
  *
  * @param flowAgentsDir Path to the runtime artifact root directory (contains current.json).
+ * @param actorKey Optional resolved actor identity (Wave 2 Task 2.1's `writeCurrent()` dual-write
+ *   key) — when omitted, behavior is unchanged (legacy-file-only, exactly as before #291).
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
-export function resolveActiveFlowStep(flowAgentsDir) {
+export function resolveActiveFlowStep(flowAgentsDir, actorKey) {
     if (!flowAgentsDir)
         return null;
-    const currentFile = path.join(flowAgentsDir, "current.json");
-    let current;
-    try {
-        const raw = fs.readFileSync(currentFile, "utf8");
-        current = JSON.parse(raw);
-    }
-    catch {
+    const pointer = loadCurrentPointerHelper().readCurrentPointer(flowAgentsDir, actorKey);
+    if (pointer.source === "none" || !pointer.payload)
         return null;
-    }
+    const current = pointer.payload;
     const flowId = typeof current["active_flow_id"] === "string" ? current["active_flow_id"] : null;
     const stepId = typeof current["active_step_id"] === "string" ? current["active_step_id"] : null;
     if (!flowId || !stepId)

package/build/src/tools/validate-source-tree.js

@@ -83,6 +83,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/lib/actor-identity.js", { category: "shared hook library", requiredNeedles: ["resolveActor", "FLOW_AGENTS_ACTOR"] }],
     ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
     ["scripts/hooks/lib/config-protection-remedies.js", { category: "shared hook library", requiredNeedles: ["SANCTIONED_REMEDIES", "REMEDY_COMMAND_CANDIDATES"] }],
+    ["scripts/hooks/lib/current-pointer.js", { category: "shared hook library", requiredNeedles: ["readCurrentPointer", "perActorCurrentFile"] }],
     ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
     ["scripts/hooks/lib/liveness-heartbeat.js", { category: "shared hook library", requiredNeedles: ["maybeEmitHeartbeat", "resolveHeartbeatThrottleSeconds"] }],
     ["scripts/hooks/lib/liveness-policy.js", { category: "shared hook library", requiredNeedles: ["isLivenessEnabled", "resolveTtlSeconds"] }],
@@ -93,7 +94,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
 ]);
 const fixtureOwnerPolicies = new Map([
-    ["evals/fixtures/assignment-provider", { owners: ["evals/integration/test_assignment_provider_local_file.sh", "evals/integration/test_assignment_provider_github.sh", "evals/integration/test_pull_work_assignment_join.sh"], classification: "AssignmentProvider local-file and GitHub render/status fixtures (#290)" }],
+    ["evals/fixtures/assignment-provider", { owners: ["evals/integration/test_assignment_provider_local_file.sh", "evals/integration/test_assignment_provider_github.sh", "evals/integration/test_pull_work_assignment_join.sh", "evals/integration/test_ensure_session_ownership_guard.sh"], classification: "AssignmentProvider local-file and GitHub render/status fixtures (#290); hostile-effective-state.json is the #291 ensure-session ownership guard's AC9 sanitization fixture" }],
     ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
     ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
     ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],

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

@@ -93,10 +93,18 @@ delivers all four:
 | Transition | Mutator | When | Owning issue |
 | --- | --- | --- | --- |
 | `claim` | the claiming session | at selection | **#290 (this issue)** |
+| `claim` / `supersede` | `ensure-session`'s pre-entry ownership guard (a SECOND mutator, alongside `assignment-provider claim`) | on session entry, before any session directory is created — `free` establishes a claim, `reclaimable` requires explicit `--supersede-stale` | **#291** |
 | `clean_release` | the incumbent (Stop hook / terminal `advance-state`) | session end — unassign + handoff comment | #292 |
 | `supersede` | the successor, inside the takeover protocol | after the grace beat | #294 |
 | `crash_no_successor` | nobody, initially; corrected by the next actor to want the subject, or the janitor | lazily, or on a janitor sweep | out of scope — the Console relay's first cross-machine duty (ADR 0021 §4/§7) |
 
+`ensure-session`'s guard reuses this file's own `computeEffectiveState`/`performLocalClaim`/
+`performLocalSupersede` (Wave 1 exports) rather than a parallel implementation — see
+`docs/adr/0021-assignment-leases-and-stale-claim-takeover.md` §3 for why a second claim point
+was needed (a session entered without going through `pull-work` previously got no durable claim
+at all) and the canonical `actor_key` field (below) that keeps its self-recognition consistent
+with every other tool that reads or writes a claim record.
+
 Lazy correction is *safe* by the join rule above (stale assignment excludes nothing), but leaves
 the human-visible board stale in the crash case until the next claim attempt or a janitor sweep
 corrects it.
@@ -146,6 +154,7 @@ detect an incompatible future shape before parsing fields it does not understand
 | `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. |
 | `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. |
 | `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/contracts/probe-docs-write-contract.md

@@ -0,0 +1,187 @@
+# Probe Docs-Write Contract
+
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
+Normative contract for how a Probe (`design-probe`, and its Builder Kit
+`pickup-probe` specialization) writes durable documentation as understanding
+crystallizes during probing. This is the docs-write half of the grill-with-docs
+pattern: a Probe already interviews and aligns; this contract says what a Probe
+must leave behind in durable docs, not just in the session artifact.
+
+## Why
+
+Probe outcomes previously landed only in session artifacts (`.kontourai/flow-agents/<slug>/`):
+vocabulary and decisions crystallized while probing had to be re-extracted later,
+or were lost when the session archived. Grill-with-docs' whole point is that the
+interview leaves living documentation behind, not session-local notes. This
+contract makes that the default behavior for every Probe, not an occasional
+manual follow-up.
+
+## Scope
+
+Applies to `design-probe` (generic) and `pickup-probe` (the Builder Kit
+pickup specialization) — see
+[`kits/builder/skills/design-probe/SKILL.md`](../../kits/builder/skills/design-probe/SKILL.md)
+and
+[`kits/builder/skills/pickup-probe/SKILL.md`](../../kits/builder/skills/pickup-probe/SKILL.md).
+It does not create a new skill; both existing Probe skills already own the
+grill/grill-with-docs behavior (R1 in
+[flow-agents#311](https://github.com/kontourai/flow-agents/issues/311)) — this
+contract only normalizes what they write and where.
+
+Out of scope: enforcement gating on Probe docs-writes (a separate issue),
+`CONTEXT.md` restructuring beyond vocabulary sections, and repositories with no
+`CONTEXT.md` (an open question the owner has not settled; non-blocking for
+flow-agents, which always has one).
+
+## The Two-Delta Rule
+
+**Per crystallized understanding** — a question the Probe asked and the user (or
+discoverable local evidence) definitively answered, not a still-open question or
+an accepted gap — the Probe emits, in the same motion:
+
+1. **A vocabulary delta** into `CONTEXT.md` (or the owning `CONTEXT-MAP.md`
+   context when one exists) — see [Vocabulary Delta](#1-vocabulary-delta-coin-first).
+2. **A decision delta** into `docs/decisions/<slug>.md` — see
+   [Decision Delta](#2-decision-delta-retrieval-at-write).
+3. **Transcript provenance** — the decision delta's `evidence[]` links the
+   session artifact that produced it — see
+   [Transcript Provenance](#3-transcript-provenance).
+
+Not every Probe question needs both deltas. A question resolved by reading
+existing docs/code needs neither (nothing crystallized — it was already
+decided). A question about implementation detail, sequencing, or a transient
+planning choice needs neither (it belongs in the workflow artifact, per
+`context/contracts/artifact-contract.md`, not durable docs). The two-delta rule
+applies specifically to a **decision subject** crystallizing: a durable,
+reusable answer to a named domain question that other work will need to look up
+later. If in doubt, ask: "will a future session need to know this answer without
+re-deriving it?" — if yes, it is a decision subject and both deltas apply.
+
+### 1. Vocabulary delta (coin-first)
+
+**A decision subject may only use subject terms present in (or added to)
+`CONTEXT.md` in the same session** (R2). Vocabulary is the topic namespace the
+decision registry's slugs are drawn from
+(`context/contracts/decision-registry-contract.md` § Slug rules), so the term
+must exist before the topic file can be named.
+
+- If the crystallized understanding's subject noun is **already** a `CONTEXT.md`
+  glossary term, the vocabulary delta may be a **refinement** of that entry
+  rather than a new one — e.g. removing "subject open" language once a decision
+  ratifies it, tightening a definition, or adding an `_Avoid_` term. This still
+  counts as a vocabulary delta: the glossary is a living document, not
+  write-once.
+- If the subject noun is **absent**, **coin it first**: add a tight one- or
+  two-sentence `### <Term>` entry to `CONTEXT.md`'s Glossary section, in the
+  same style as existing entries (definition, optional `_Avoid_` line). Do this
+  before creating the decision file — the term is the slug's namespace, not an
+  afterthought.
+- Keep the vocabulary delta to glossary-style terminology. Implementation
+  detail, rationale, and derivation stay out of `CONTEXT.md` (unchanged from the
+  Probe skills' existing docs discipline).
+- If a `CONTEXT-MAP.md` exists and a more specific context owns the term, update
+  that context instead of assuming the root glossary owns every term.
+
+### 2. Decision delta (retrieval-at-write)
+
+Once the vocabulary exists, record the decision per
+`context/contracts/decision-registry-contract.md` in full — this contract does
+not repeat the frontmatter/slug/tombstone rules, only the Probe-specific
+sequencing:
+
+1. **Consult `docs/decisions/index.md`** (the always-loaded slug + one-liner
+   index) before writing anything, and propose **revise-vs-create**:
+   - An existing topic slug already covers the subject (including a
+     `needs-decision` stub seeded by ADR-freeze tooling, issue #314) → **revise
+     that file in place.** Flip `needs-decision` → `current` (or edit a `current`
+     file's body/`decided` date for a superseding decision), add the new
+     `evidence[]` refs, do not create a second file for the same subject.
+   - No topic covers the subject → confirm the vocabulary delta above landed,
+     then **create** `docs/decisions/<slug>.md` with the frontmatter shape
+     `context/contracts/decision-registry-contract.md` defines.
+2. Run `npm run gen:decisions-index && npm run check:decisions` after every
+   decision-delta write. A Probe session is not done touching the registry until
+   both exit 0.
+3. Never propose a numbered ADR. `docs/adr/` is frozen history
+   (`docs/adr/README.md`); a Probe's decision delta always targets the
+   topic-keyed registry, never a new `docs/adr/NNNN-*.md` file.
+
+### 3. Transcript provenance
+
+Every decision file a Probe creates or edits carries an `evidence[]` entry of
+`kind: session-archive` pointing at the Probe's own session artifact (R3) — the
+Markdown file recording the interview, decisions, and accepted gaps
+(`.kontourai/flow-agents/<slug>/<slug>--design-probe.md`,
+`<slug>--pull-work.md`, or the equivalent Probe record the active workflow
+artifact uses).
+
+- Record the **live session path** at write time, even though the topic file
+  and the decision-registry contract describe `session-archive` as pointing at
+  an *archived* artifact "promoted at retirement" — the Probe runs at shaping
+  time, before the session archives. This is a deliberate, documented seam: the
+  promote-then-archive gate (issue #312) is the retirement-time mechanism that
+  moves the session directory to `<artifact-root>/archive/<slug>/` and is
+  responsible for keeping already-written evidence refs accurate across that
+  move. The Probe's job is emitting the initial link, not the later archival
+  move; do not block a decision delta on the session having archived first.
+- When the Probe is also citing a frozen ADR as prior provenance (e.g. upgrading
+  a `needs-decision` stub whose `evidence[]` already names one), keep that `adr`
+  evidence entry and add the `session-archive` entry alongside it — provenance
+  accumulates, it does not replace.
+- Also add a `pr`/`issue` evidence entry once a PR or issue number exists for the
+  work, following the same pattern every other decision file in the registry
+  uses.
+
+## Worked Example: Upgrading a Needs-Decision Stub
+
+The ADR-freeze cutover (issue #314, landed in #368) seeded 17 `needs-decision`
+stubs, each naming a subject with provenance in a frozen ADR but no ratified
+living decision. These are the natural first targets for this contract: a Probe
+that settles one of these subjects from existing evidence (the frozen ADR
+already states a decision that remains true — nothing new needs deciding, only
+recording) does the following:
+
+1. **Read the stub** (`docs/decisions/<slug>.md`, `status: needs-decision`) and
+   its `evidence[]`-linked frozen ADR(s).
+2. **Vocabulary delta**: the subject noun is already a `CONTEXT.md` term (seeded
+   alongside the stub during the freeze cutover) — refine its definition to
+   state the decision is now living rather than "subject open in the Decision
+   Registry," and keep the link to `docs/decisions/<slug>.md`.
+3. **Decision delta**: consult `docs/decisions/index.md` — the slug already
+   exists (revise, not create). Edit `docs/decisions/<slug>.md`:
+   `status: needs-decision` → `current`, set `decided` to today, keep the
+   existing `adr` evidence ref(s), append a `session-archive` ref (this Probe's
+   session artifact) and a `pr` ref once the PR exists, and write the `# <Title>`
+   body stating the decision (drawn from the ADR) plus lean rationale.
+4. Run `npm run gen:decisions-index && npm run check:decisions`; both must exit
+   0 before the Probe records the gate claim.
+5. **Transcript provenance**: the session-archive evidence ref from step 3 is the
+   provenance link (R3).
+
+This exercises all three rules end-to-end without inventing a new decision —
+the frozen ADR already made the call; the Probe's job is only recording that it
+is still true and giving it a living home.
+
+## Relationship To Other Contracts
+
+- **`context/contracts/decision-registry-contract.md`** is the normative
+  frontmatter/slug/tombstone/validation contract for every `docs/decisions/`
+  file, Probe-written or not. This contract only adds *when* and *in what
+  sequence* a Probe writes to that registry.
+- **`context/contracts/artifact-contract.md`** governs the Probe's session
+  artifact itself (the thing this contract's transcript-provenance rule links
+  to) and the promote/archive lifecycle referenced above.
+- **`docs/adr/README.md`** is where this contract is announced as the mechanism
+  that supersedes the prior "propose ADRs sparingly" Probe guidance — Probes
+  never write numbered ADRs; they write decision-registry deltas.
+
+## Validation
+
+- `npm run check:decisions` / `npm run gen:decisions-index` — the decision
+  delta must pass the registry validator and keep the index current (wired into
+  the required `source-and-static` CI lane).
+- `evals/static/test_workflow_skills.sh` — asserts `design-probe` and
+  `pickup-probe` reference this contract and describe the two-delta behavior.
+- `evals/static/test_decisions.sh` — regression coverage for the validator and
+  generator this contract's decision deltas depend on.

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

@@ -131,6 +131,18 @@ function checkProtectedPathPattern(filePath) {
     };
   }
 
+  // .kontourai/flow-agents/current/<actor>.json (#291) — the per-actor projection of the same
+  // pointer above. An agent could forge active_flow_id/active_step_id here exactly as it could
+  // via the legacy global file, so this is protected identically (same reason text).
+  // SAFE: the workflow CLI writes this via writePerActorCurrent → fs.writeFileSync,
+  // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
+  if (/(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$/.test(norm)) {
+    return {
+      name: '.kontourai/flow-agents/current/<actor>.json',
+      reason: 'an agent could forge active_flow_id/active_step_id to route the gate to a permissive FlowDefinition',
+    };
+  }
+
   // .kontourai/flow-agents/.goal-fit-block-streak.json controls soft-block
   // release counting. An agent could force early advisory-gate release by
   // writing a high count.
@@ -403,12 +415,13 @@ function checkCommandForBypass(command) {
  * Regex that matches a normalized (forward-slash) path ending with a protected
  * kill-switch file: shell profiles, .claude/settings*.json,
  * .kontourai/flow-agents/current.json,
+ * .kontourai/flow-agents/current/<actor>.json (#291 per-actor projection),
  * .kontourai/flow-agents/.goal-fit-block-streak.json,
  * .kontourai/flow-agents/<slug>/state.json,
  * .kontourai/flow-agents/<slug>/trust.bundle, and deprecated runtime-shaped
  * .flow-agents equivalents.
  */
-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)\/\.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$|(?:^|\/)(?:\.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

@@ -22,6 +22,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.',
   '.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':
+    '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/.goal-fit-block-streak.json':
     'This file is only mutated internally by the goal-fit Stop hook; there is no sanctioned agent writer. Never disable this hook to make the write.',
   '.kontourai/flow-agents/<slug>/state.json':
@@ -61,6 +63,13 @@ const REMEDY_COMMAND_CANDIDATES = [
   { name: '.kontourai/flow-agents/<slug>/trust.bundle', needles: ['trust.bundle'] },
   { name: '.kontourai/flow-agents/<slug>/state.json', needles: ['state.json'] },
   { name: '.kontourai/flow-agents/.goal-fit-block-streak.json', needles: ['.goal-fit-block-streak.json'] },
+  // #291: the per-actor projection (current/<actor>.json) is checked BEFORE the legacy
+  // current.json needle below — its needle is a directory-scoped substring
+  // ('flow-agents/current/') that never overlaps with the bare 'current.json' basename, so
+  // ordering between these two entries has no effect on real inputs, but keeping the more
+  // specific per-actor entry first mirrors this table's existing "specific before generic"
+  // convention.
+  { name: '.kontourai/flow-agents/current/<actor>.json', needles: ['flow-agents/current/', '.flow-agents/current/'] },
   { name: '.kontourai/flow-agents/current.json', needles: ['current.json'] },
   { name: '.claude/settings.local.json', needles: ['settings.local.json'] },
   { name: '.claude/settings.json', needles: ['.claude/settings.json'] },

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

@@ -42,6 +42,8 @@ const {
   flowAgentsArtifactRoot,
   flowAgentsArtifactRootsForRead,
 } = require('./lib/local-artifact-paths');
+const { resolveActor } = require('./lib/actor-identity.js');
+const { readCurrentPointer } = require('./lib/current-pointer.js');
 
 const MAX_STDIN = 1024 * 1024;
 const ACTIVE_STATUSES = new Set([
@@ -1531,7 +1533,7 @@ async function bundleEnforcement(artifactDir, activeFlowStep) {
  * to scanning all of .kontourai/flow-agents (newest-mtime).
  */
 function preferredArtifactDir(flowAgentsDir) {
-  const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
+  const { payload: current } = readCurrentPointer(flowAgentsDir, resolveActor(process.env).actor);
   if (!current) return null;
   const slug = current.artifact_dir || current.active_slug;
   if (typeof slug !== 'string' || !slug.trim()) return null;
@@ -1549,7 +1551,7 @@ function hasSidecarPresence(artifactDir) {
 // return that slug so analyze() can log the staleness rather than silently falling back to
 // a global mtime scan that could resurface an abandoned/never-real session as active.
 function staleCurrentSlug(flowAgentsDir) {
-  const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
+  const { payload: current } = readCurrentPointer(flowAgentsDir, resolveActor(process.env).actor);
   if (!current) return null;
   const slug = current.artifact_dir || current.active_slug;
   if (typeof slug !== 'string' || !slug.trim()) return null;

package/context/scripts/hooks/workflow-steering.js

@@ -19,6 +19,7 @@ const path = require('path');
 const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
 const { resolveActor } = require('./lib/actor-identity');
 const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
+const { readCurrentPointer } = require('./lib/current-pointer');
 
 const STEERING = {
   'tool-planner': [
@@ -102,7 +103,48 @@ function readJson(file) {
   }
 }
 
+/**
+ * #291 (Conflict #2, Wave 2 Task 2.4): actor-scoped preference consulted BEFORE the global
+ * newest-mtime scan below. For each read-root, resolve the "current" pointer via
+ * `readCurrentPointer` (per-actor `current/<actor>.json` preferred, legacy global
+ * `current.json` fallback — the same single choke point every other Wave 2 consumer uses) and,
+ * if it names a session dir whose `state.json` is still in an ACTIVE_STATE_STATUSES status,
+ * return that state immediately — so actor A's own ambient steering hint always prefers A's own
+ * current task over a globally-newer-mtime `state.json` some other actor (B) happened to touch
+ * more recently. Returns null (never throws) when no root yields an actor-scoped resolution,
+ * so the caller falls through to the unchanged global scan below — this is the compat-shim
+ * guarantee: when `actorKey` is empty/unresolved and/or no per-actor file exists yet, this
+ * degrades to the SAME legacy-`current.json`-or-nothing lookup the compat shim already performs
+ * for every other Wave 2 reader, so a single-session/CI/legacy-only fixture cannot fail to
+ * resolve here in a way it wouldn't already have resolved via the global scan.
+ *
+ * @param {string} root
+ * @param {string} actorKey
+ * @returns {{file: string, payload: object, mtimeMs: number}|null}
+ */
+function actorScopedWorkflowState(root, actorKey) {
+  for (const flowAgentsDir of flowAgentsArtifactRootsForRead(root)) {
+    const { payload: current } = readCurrentPointer(flowAgentsDir, actorKey);
+    if (!current) continue;
+    const slug = current.artifact_dir || current.active_slug;
+    if (typeof slug !== 'string' || !slug.trim()) continue;
+    const safe = slug.replace(/\.\.+/g, '').replace(/^[/\\]+/, '');
+    const dir = path.join(flowAgentsDir, safe);
+    if (!dir.startsWith(flowAgentsDir + path.sep) || !fs.existsSync(dir)) continue;
+    const file = path.join(dir, 'state.json');
+    let stat;
+    try { stat = fs.statSync(file); } catch { continue; }
+    const payload = readJson(file);
+    if (!payload || !ACTIVE_STATE_STATUSES.has(payload.status)) continue;
+    return { file, payload, mtimeMs: stat.mtimeMs };
+  }
+  return null;
+}
+
 function latestWorkflowState(root) {
+  const preferred = actorScopedWorkflowState(root, resolveActor(process.env).actor);
+  if (preferred) return preferred;
+
   const states = flowAgentsArtifactRootsForRead(root)
     .flatMap(artifactRoot => walkStateFiles(artifactRoot))
     .map(file => {

package/docs/adr/0001-flow-agents-consumes-flow.md

@@ -2,6 +2,8 @@
 title: ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement
 
 Date: 2026-05-24

package/docs/adr/0002-flow-kits-as-extension-unit.md

@@ -2,6 +2,8 @@
 title: ADR 0002: Flow Kits As The Extension Unit
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0002: Flow Kits As The Extension Unit
 
 Flow Agents will use **Flow Kit** as the product and implementation term for installable workflow bundles, replacing the older "pack" vocabulary. A Flow Kit may contain Flow Definitions, skills, adapters, provider contracts, docs, and evals; the Kit Catalog lists available kits and installable assets, but the workflow semantics live in kit-owned Flow Definition files. This avoids overloading packaging metadata with process semantics and gives custom workflow authoring a clearer product language.

package/docs/adr/0003-flow-agents-coordinates-kits-and-adapters.md

@@ -2,6 +2,8 @@
 title: ADR 0003: Flow Agents Coordinates Kits And Adapters
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0003: Flow Agents Coordinates Kits And Adapters
 
 Flow Agents will not own the builder, or knowledge workflows as core behavior. Those out-of-the-box behaviors will be extracted into normal Flow Kits that use the same manifest, Flow Definition, skill, doc, provider, and eval contracts as third-party kits. Flow Agents owns kit validation, installation, runtime adapter selection, provider wiring, status/control commands, and runtime-specific export; Runtime Adapters own target-specific integration for local agent runtimes and API/framework agents.

package/docs/adr/0004-gates-expect-surface-claims.md

@@ -2,6 +2,8 @@
 title: ADR 0004: Gates Expect Hachure Trust Bundles
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0004: Gates Expect Hachure Trust Bundles
 
 Flow-backed kits will model rich gate evidence as claim expectations using the Hachure trust.bundle format rather than provider-specific requirements. A gate expectation can require `kind: "trust.bundle"`, a domain claim type such as `builder.verify.tests`, accepted trust statuses such as `verified`, and whether the expectation blocks the transition; project or runtime config maps claim types to trusted Surface producers and authority traces. This lets the Builder Kit use repo governance, command checks, CI, human decisions, or future producers without naming a specific provider in the Flow Definition.

package/docs/adr/0005-kubernetes-inspired-resource-contracts.md

@@ -2,6 +2,8 @@
 title: ADR 0005: Kubernetes-Inspired Kontour Resource Contracts
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0005: Kubernetes-Inspired Kontour Resource Contracts
 
 Date: 2026-05-27

package/docs/adr/0006-typescript-first-source-policy.md

@@ -2,6 +2,8 @@
 title: ADR 0006: TypeScript-First Source Policy
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0006: TypeScript-First Source Policy
 
 Date: 2026-05-31

package/docs/adr/0007-flow-skill-kit-tool-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0007: Flow / Skill / Kit / Tool Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0007: Flow / Skill / Kit / Tool Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0007-skill-audit.md

@@ -2,6 +2,8 @@
 title: "Skill Audit 2026-06-15: Flow / Skill / Kit / Tool Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # Skill Audit: Flow / Skill / Kit / Tool Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0008-kit-operation-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0008: Kit Operation Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0008: Kit Operation Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0009-canonical-hook-core-kit-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0009: Canonical Hook Core/Kit Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0009: Canonical Hook Core/Kit Boundary
 
 **Date:** 2026-06-23

package/docs/adr/0010-workflow-trust-state-as-hachure-bundle.md

@@ -2,6 +2,8 @@
 title: "ADR 0010: Workflow Trust State as a Hachure Trust Bundle"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0010: Workflow Trust State as a Hachure Trust Bundle
 
 **Date:** 2026-06-23

package/docs/adr/0011-mcp-posture.md

@@ -2,6 +2,8 @@
 title: "ADR 0011: MCP Posture — Enforcement Stays Hooks; Surface Owns MCP Projection; No Auto-Injected Config"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0011: MCP Posture
 
 **Date:** 2026-06-24

package/docs/adr/0012-agent-coordination-as-liveness-claims.md

@@ -2,6 +2,8 @@
 title: "ADR 0012: Agent Coordination as Hachure Liveness Claims"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0012: Agent Coordination as Hachure Liveness Claims
 
 **Date:** 2026-06-24

package/docs/adr/0013-context-lifecycle.md

@@ -2,6 +2,8 @@
 title: "ADR 0013: Context Lifecycle — Workflow-Boundary Compaction, Freshness-Gated Reuse, and the Learning Split"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0013: Context Lifecycle
 
 **Date:** 2026-06-25

package/docs/adr/0014-core-vs-domain-kit-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0014: Flow Agents core vs domain kits — the generic/kit boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0014: Flow Agents core vs domain kits
 
 **Date:** 2026-06-25

package/docs/adr/0015-flow-flow-agents-boundary-reconciliation.md

@@ -2,6 +2,8 @@
 title: "ADR 0015: Flow / Flow Agents Boundary Reconciliation"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0015: Flow / Flow Agents Boundary Reconciliation
 
 **Date:** 2026-06-25

package/docs/adr/0016-three-hard-boundary-model.md

@@ -2,6 +2,8 @@
 title: "ADR 0016: The Three-Hard-Boundary Model — a FlowDefinition-Driven, Kit-Agnostic Core"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0016: The Three-Hard-Boundary Model — a FlowDefinition-Driven, Kit-Agnostic Core
 
 **Date:** 2026-06-26

package/docs/adr/0017-anti-gaming-trust-security-model.md

@@ -2,6 +2,8 @@
 title: "ADR 0017: The Anti-Gaming Trust Security Model — Layered Defense + External CI Anchor"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0017: The Anti-Gaming Trust Security Model — Layered Defense + External CI Anchor
 
 Status: Accepted