@kontourai/flow-agents 3.0.0 → 3.1.0

package/scripts/hooks/evidence-capture.js

@@ -49,6 +49,8 @@
 const fs = require('fs');
 const path = require('path');
 const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
+const { resolveActor } = require('./lib/actor-identity.js');
+const { readCurrentPointer } = require('./lib/current-pointer.js');
 const crypto = require('crypto');
 
 const MAX_STDIN = 1024 * 1024;
@@ -198,8 +200,9 @@ function latestStateDir(flowAgentsDir) {
  * to the newest-mtime state.json directory.
  */
 function resolveArtifactDir(root) {
+  const actorKey = resolveActor(process.env).actor;
   for (const flowAgentsDir of flowAgentsArtifactRootsForRead(root)) {
-    const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
+    const { payload: current } = readCurrentPointer(flowAgentsDir, actorKey);
     if (current) {
       const slug = current.artifact_dir || current.active_slug;
       if (typeof slug === 'string' && slug.trim()) {

package/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/scripts/hooks/lib/current-pointer.js

@@ -0,0 +1,123 @@
+'use strict';
+/**
+ * current-pointer.js — shared pure-CJS per-actor "current" pointer reader/writer (#291)
+ *
+ * Zero external dependencies (only Node core: fs, path). Consumed by:
+ *   - build/src/cli/workflow-sidecar.js  (ESM compiled, via createRequire — Wave 2 Task 2.1)
+ *   - build/src/lib/flow-resolver.js     (ESM compiled, via createRequire — Wave 2 Task 2.2)
+ *   - scripts/hooks/stop-goal-fit.js, evidence-capture.js, lib/liveness-heartbeat.js,
+ *     scripts/statusline/flow-agents-statusline.js (CJS, direct require — Wave 2 Task 2.3)
+ *   - scripts/hooks/workflow-steering.js (CJS, direct require — Wave 2 Task 2.4)
+ *
+ * Purpose (issue #291): today every one of the consumers above hand-rolls its own
+ * `fs.readFileSync(path.join(flowAgentsDir, "current.json"))`, so once `ensure-session` starts
+ * projecting a per-actor `current/<actor>.json` pointer (Wave 2 Task 2.1's `writeCurrent()` dual
+ * write), every reader must gain the SAME actor-aware preference or session A's own "what am I
+ * working on" view keeps getting silently overwritten by session B's more-recent legacy write.
+ * This module is the single choke point for that preference rule — every reader listed above
+ * calls `readCurrentPointer()` instead of hand-rolling its own fallback, so the compat-shim rule
+ * (per-actor first, legacy-global fallback) can never drift between call sites.
+ *
+ * `sanitizeSegment` is required from `./actor-identity.js` (already reviewed: restricts to
+ * `[A-Za-z0-9_.-]`, caps 64 chars) — this file deliberately does NOT re-implement a second
+ * sanitizer; it is the same charset restriction `assignment-provider.ts`'s `assignmentFilePath()`
+ * already applies to its own per-subject filenames, so the naming convention is consistent across
+ * both per-key-file stores in this repo (`assignment/<subject>.json` and now
+ * `current/<actor>.json`).
+ *
+ * Exports:
+ *   perActorCurrentFile(flowAgentsDir, actorKey)     → string (path, unsanitized existence not
+ *                                                        implied — caller must still fs.existsSync)
+ *   readCurrentPointer(flowAgentsDir, actorKey)       → { payload: object|null,
+ *                                                        source: "per-actor"|"legacy"|"none",
+ *                                                        file: string|null }
+ *   writePerActorCurrent(flowAgentsDir, actorKey, payload) → void
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { sanitizeSegment, isUnresolvedActor } = require('./actor-identity.js');
+
+/**
+ * Best-effort tolerant JSON read: missing file or corrupt/unparseable content are BOTH treated
+ * as "absent" (returns null), never thrown — this is an advisory read used to decide which
+ * pointer file to prefer, not a durable-write persistence path. Mirrors the `readJsonFile`
+ * tolerance convention already used by stop-goal-fit.js/evidence-capture.js for this exact file
+ * (`current.json`) today.
+ *
+ * @param {string} file
+ * @returns {object|null}
+ */
+function readJsonFileTolerant(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Path to the per-actor current pointer file for a given actor key, sanitized via the shared
+ * `sanitizeSegment` (reused, not re-implemented) so the filename is path-traversal-safe exactly
+ * like `assignment-provider.ts`'s `assignmentFilePath()`.
+ *
+ * @param {string} flowAgentsDir
+ * @param {string} actorKey
+ * @returns {string}
+ */
+function perActorCurrentFile(flowAgentsDir, actorKey) {
+  return path.join(flowAgentsDir, 'current', `${sanitizeSegment(actorKey)}.json`);
+}
+
+/**
+ * The ENTIRE compat-shim fallback rule (#291): when `actorKey` is a non-empty, resolved (not
+ * `isUnresolvedActor`) string and its per-actor file exists and parses, prefer it
+ * (`source: "per-actor"`). Otherwise — no actorKey, an unresolved actor, or no per-actor file yet
+ * — fall back to the legacy global `<flowAgentsDir>/current.json`; if THAT exists and parses,
+ * return it (`source: "legacy"`). Otherwise return `{ payload: null, source: "none", file: null }`.
+ *
+ * A missing/corrupt per-actor file is tolerated as absent (falls through to the legacy branch,
+ * never throws) — same best-effort tolerance the existing `readJsonFile`-style readers already
+ * apply to `current.json` today. This fallback must be EXACTLY equivalent to today's plain
+ * `current.json` read for every caller that has no actorKey (or an unresolved one) — that is
+ * what makes this a compat shim rather than a behavior change.
+ *
+ * @param {string} flowAgentsDir
+ * @param {string} [actorKey]
+ * @returns {{ payload: object|null, source: "per-actor"|"legacy"|"none", file: string|null }}
+ */
+function readCurrentPointer(flowAgentsDir, actorKey) {
+  const key = actorKey == null ? '' : String(actorKey);
+  if (key && !isUnresolvedActor(key)) {
+    const perActorFile = perActorCurrentFile(flowAgentsDir, key);
+    const perActorPayload = readJsonFileTolerant(perActorFile);
+    if (perActorPayload !== null) return { payload: perActorPayload, source: 'per-actor', file: perActorFile };
+  }
+
+  const legacyFile = path.join(flowAgentsDir, 'current.json');
+  const legacyPayload = readJsonFileTolerant(legacyFile);
+  if (legacyPayload !== null) return { payload: legacyPayload, source: 'legacy', file: legacyFile };
+
+  return { payload: null, source: 'none', file: null };
+}
+
+/**
+ * Durable write-side counterpart to `readCurrentPointer`'s per-actor branch — used only by
+ * `workflow-sidecar.ts`'s `writeCurrent()` (Wave 2 Task 2.1), which calls this ALONGSIDE
+ * (never instead of) its existing unconditional legacy `current.json` write, so the legacy
+ * compat-shim fallback always has a value to read for any caller that never resolves an actor.
+ * `fs.mkdirSync` the `current/` subdir with `{ recursive: true }` before writing — this is the
+ * ONLY writer of that subdir, so no other caller needs to pre-create it.
+ *
+ * @param {string} flowAgentsDir
+ * @param {string} actorKey
+ * @param {object} payload
+ * @returns {void}
+ */
+function writePerActorCurrent(flowAgentsDir, actorKey, payload) {
+  const file = perActorCurrentFile(flowAgentsDir, actorKey);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+module.exports = { perActorCurrentFile, readCurrentPointer, writePerActorCurrent };

package/scripts/hooks/lib/liveness-heartbeat.js

@@ -18,10 +18,24 @@
  * the actor-scoped stream has no shared-write race.
  *
  * Hot-path ordering + bounded read (F3, #288 fix iteration 1, sec-MED +
- * cr-MED): steps run enabled? -> current.json active_slug present? ->
- * resolveActor() -> bounded tail read, in that order, so a repo with liveness
- * disabled or no active session never pays the `resolveActor()` process-
- * ancestry `ps` spawn cost.
+ * cr-MED; restored by F4, fix-plan iteration 1): steps run enabled? ->
+ * mightHaveActiveSession() peek -> resolveActor() -> current.json
+ * active_slug present? -> bounded tail read, in that order, so a repo with
+ * liveness disabled OR no active session never pays the `resolveActor()`
+ * process-ancestry `ps` spawn cost. (#291 initially moved resolveActor()
+ * ahead of the active_slug check unconditionally, since the current-pointer
+ * read became actor-aware and needs the resolved actor to choose per-actor
+ * vs. legacy `current.json` — this silently dropped the "no active session"
+ * half of the short-circuit for every liveness-enabled call, not just the
+ * "disabled" half. F4 restores it: `mightHaveActiveSession()` is a plain,
+ * actor-free `fs.existsSync` peek of the legacy `current.json` file and the
+ * `current/` per-actor directory — when NEITHER exists, no actor could
+ * possibly have an active session (per-actor files only ever live under
+ * `current/`), so resolveActor() is skipped entirely, exactly restoring the
+ * pre-#291 short-circuit for the common "enabled, no session yet" case. Only
+ * once a current-pointer file might exist does resolveActor() run, still
+ * exactly once, reused for both the actor-scoped current-pointer read and the
+ * actor-unresolved gate below.)
  *
  * Orphan-heartbeat invariant (F8(ii), #288 fix iteration 2): a heartbeat must
  * never be treated as its own evidence of a claim. The reviewer-reproduced
@@ -74,12 +88,12 @@
 
 const fs = require('fs');
 const path = require('path');
-
 const { isLivenessEnabled, resolveHeartbeatThrottleSeconds } = require('./liveness-policy');
 const { livenessStreamFile, appendLivenessEvent } = require('./liveness-write');
 const { readLivenessEvents, readLivenessEventsTail, freshHolders } = require('./liveness-read');
 const { resolveActor, isUnresolvedActor, sanitizeSegment } = require('./actor-identity');
 const { flowAgentsArtifactRoot } = require('./local-artifact-paths');
+const { readCurrentPointer } = require('./current-pointer');
 
 /**
  * Resolve a caller-supplied `now` (Date, ISO string, or omitted) to epoch ms.
@@ -101,35 +115,50 @@ function resolveNowMs(now) {
 }
 
 /**
- * Read `current.json`'s `active_slug` from the given artifact root, sanitized through the same
- * charset+cap restriction as actor-identity.js's `sanitizeSegment` (F5, #288 fix iteration 1,
- * sec-LOW: `current.json` is a local file that could be hand-edited or otherwise hostile —
- * `active_slug` must never be trusted verbatim before it is used as a JSONL grouping key /
- * emitted `subjectId` or compared against event data). Tolerates a missing file or malformed
- * JSON (returns "").
+ * Read the active_slug from the actor-scoped "current" pointer (#291: per-actor
+ * `current/<actor>.json` preferred over the legacy global `current.json`, via
+ * `readCurrentPointer` — the single choke point for that preference rule), sanitized through the
+ * same charset+cap restriction as actor-identity.js's `sanitizeSegment` (F5, #288 fix iteration 1,
+ * sec-LOW: this is a local file that could be hand-edited or otherwise hostile — `active_slug`
+ * must never be trusted verbatim before it is used as a JSONL grouping key / emitted `subjectId`
+ * or compared against event data). Tolerates a missing file or malformed JSON (returns "") exactly
+ * like the plain-`fs.readFileSync` read this replaces; when `actorKey` is empty/unresolved,
+ * `readCurrentPointer` falls straight to the legacy global file, so behavior for that case is
+ * unchanged from before #291.
  *
  * @param {string} root
+ * @param {string} [actorKey]
  * @returns {string}
  */
-function readActiveSlug(root) {
-  let raw = '';
-  try {
-    raw = fs.readFileSync(path.join(root, 'current.json'), 'utf8');
-  } catch {
-    return '';
-  }
-  try {
-    const parsed = JSON.parse(raw);
-    const activeSlug = (parsed && parsed.active_slug) || '';
-    if (!activeSlug) return '';
-    // sanitizeSegment falls back to the literal "unknown" for an all-stripped input; that
-    // fallback is not a legitimate slug, so treat it as "no active slug" here rather than
-    // matching against a subject that was never really claimed.
-    const sanitized = sanitizeSegment(activeSlug);
-    return sanitized === 'unknown' ? '' : sanitized;
-  } catch {
-    return '';
-  }
+/**
+ * F4 fix (fix-plan iteration 1, MED): a cheap, actor-free existence peek restoring the module's
+ * documented "no active session never pays resolveActor()" invariant. `readCurrentPointer`'s
+ * actor-aware preference genuinely needs a resolved actor to choose per-actor vs. legacy — but
+ * that choice is only ever relevant when SOME current-pointer file might exist at all. When
+ * neither the legacy global `<root>/current.json` file NOR the `<root>/current/` per-actor
+ * directory exists, there is provably no active session for any actor (per-actor files are only
+ * ever written into that directory — see current-pointer.js's writePerActorCurrent), so this
+ * function returns false without calling resolveActor() at all, exactly restoring the pre-#291
+ * short-circuit for the common "liveness enabled, no session yet" case. Two plain fs.existsSync
+ * calls — no ps/proc ancestry cost, no JSON parse.
+ *
+ * @param {string} root
+ * @returns {boolean}
+ */
+function mightHaveActiveSession(root) {
+  return fs.existsSync(path.join(root, 'current.json')) || fs.existsSync(path.join(root, 'current'));
+}
+
+function readActiveSlug(root, actorKey) {
+  const { payload: current } = readCurrentPointer(root, actorKey);
+  if (!current) return '';
+  const activeSlug = (current && current.active_slug) || '';
+  if (!activeSlug) return '';
+  // sanitizeSegment falls back to the literal "unknown" for an all-stripped input; that
+  // fallback is not a legitimate slug, so treat it as "no active slug" here rather than
+  // matching against a subject that was never really claimed.
+  const sanitized = sanitizeSegment(activeSlug);
+  return sanitized === 'unknown' ? '' : sanitized;
 }
 
 /**
@@ -221,9 +250,10 @@ function attachConflictField(result, conflict) {
  * object, never throws.
  *
  * See the module header for the full F8(ii) throttle/emit split. Summary:
- *   - enabled? -> slug present? -> resolveActor() -> bounded tail read, in
- *     that order (F3), so a disabled repo or one with no active session
- *     never pays the resolveActor() ancestry `ps` spawn cost.
+ *   - enabled? -> mightHaveActiveSession() peek -> resolveActor() -> slug
+ *     present? -> bounded tail read, in that order (F3, restored by F4), so
+ *     a disabled repo or one with no active session never pays the
+ *     resolveActor() ancestry `ps` spawn cost.
  *   - THROTTLE decision reads only the bounded tail (never a full read):
  *     a release found there refuses; a fresh event there throttles.
  *   - EMIT decision requires an actual `claim` event for the pair: taken
@@ -248,12 +278,22 @@ function maybeEmitHeartbeat(opts = {}) {
     }
 
     const root = flowAgentsArtifactRoot(cwd);
-    const slug = readActiveSlug(root);
-    if (!slug) {
+    // F4 fix (fix-plan iteration 1, MED): restore the "no active session never pays
+    // resolveActor()" invariant. mightHaveActiveSession() is a plain fs.existsSync peek of the
+    // LEGACY current.json / current/ dir — no actor needed — so a repo with liveness enabled but
+    // no session at all (the common case this invariant exists for) short-circuits here, exactly
+    // like pre-#291. Only once a current-pointer file MIGHT exist do we pay for resolveActor(),
+    // needed to decide per-actor vs. legacy preference via readActiveSlug/readCurrentPointer.
+    if (!mightHaveActiveSession(root)) {
       return { emitted: false, reason: 'no-current' };
     }
 
     const { actor } = resolveActor(env);
+    const slug = readActiveSlug(root, actor);
+    if (!slug) {
+      return { emitted: false, reason: 'no-current' };
+    }
+
     if (isUnresolvedActor(actor)) {
       return { emitted: false, reason: 'actor-unresolved' };
     }

package/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/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/scripts/statusline/flow-agents-statusline.js

@@ -10,6 +10,8 @@
 
 const fs = require('fs');
 const path = require('path');
+const { resolveActor } = require('../hooks/lib/actor-identity.js');
+const { readCurrentPointer } = require('../hooks/lib/current-pointer.js');
 
 const MAX_SUMMARY = 72;
 
@@ -76,7 +78,7 @@ function stateFiles(workflowRoot) {
 }
 
 function chooseWorkflow(workflowRoot) {
-  const current = readJson(path.join(workflowRoot, 'current.json'));
+  const { payload: current } = readCurrentPointer(workflowRoot, resolveActor(process.env).actor);
   if (current?.active_slug || current?.artifact_dir) {
     const slug = current.active_slug || current.artifact_dir;
     const dir = path.join(workflowRoot, slug);