@kontourai/flow-agents 2.2.0 → 2.4.0

package/scripts/hooks/lib/local-artifact-paths.js

@@ -4,18 +4,20 @@ const fs = require('fs');
 const path = require('path');
 
 const KONTOURAI_DIR = '.kontourai';
-const LEGACY_FLOW_AGENTS_DIR = '.flow-agents';
+const FLOW_AGENTS_RUNTIME_SUBDIR = 'flow-agents';
+const FLOW_AGENTS_RUNTIME_DIR = `${KONTOURAI_DIR}/${FLOW_AGENTS_RUNTIME_SUBDIR}`;
+const DURABLE_FLOW_AGENTS_DIR = '.flow-agents';
 
 function flowAgentsArtifactRoot(cwd = process.cwd()) {
-  return path.resolve(cwd, KONTOURAI_DIR, 'flow-agents');
+  return path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
 }
 
-function legacyFlowAgentsArtifactRoot(cwd = process.cwd()) {
-  return path.resolve(cwd, LEGACY_FLOW_AGENTS_DIR);
+function durableFlowAgentsRoot(cwd = process.cwd()) {
+  return path.resolve(cwd, DURABLE_FLOW_AGENTS_DIR);
 }
 
 function flowAgentsArtifactRootsForRead(cwd = process.cwd()) {
-  const roots = [flowAgentsArtifactRoot(cwd), legacyFlowAgentsArtifactRoot(cwd)];
+  const roots = [flowAgentsArtifactRoot(cwd)];
   return roots.filter((root, index) => roots.indexOf(root) === index && fs.existsSync(root));
 }
 
@@ -25,8 +27,12 @@ function defaultArtifactRootForRead(cwd = process.cwd()) {
 }
 
 module.exports = {
+  DURABLE_FLOW_AGENTS_DIR,
+  FLOW_AGENTS_RUNTIME_DIR,
+  FLOW_AGENTS_RUNTIME_SUBDIR,
+  KONTOURAI_DIR,
+  durableFlowAgentsRoot,
   flowAgentsArtifactRoot,
-  legacyFlowAgentsArtifactRoot,
   flowAgentsArtifactRootsForRead,
   defaultArtifactRootForRead,
 };

package/scripts/hooks/opencode-telemetry-hook.js

@@ -66,9 +66,35 @@ async function main() {
   const [, , eventArg = 'unknown', agentName = 'dev'] = process.argv;
   const raw = await readStdinRaw();
   const payload = parseJson(raw);
+  const canonical = canonicalEvent(eventArg, payload);
   const telemetryScript = path.resolve(__dirname, '..', 'telemetry', 'telemetry.sh');
 
-  const result = spawnSync('bash', [telemetryScript, canonicalEvent(eventArg, payload), agentName], {
+  if (canonical === 'postToolUse') {
+    try {
+      const heartbeatResult = require('./lib/liveness-heartbeat').maybeEmitHeartbeat({
+        cwd: process.cwd(),
+        env: process.env,
+      });
+      const conflict = heartbeatResult && heartbeatResult.conflict;
+      // Degraded-runtime conflict surfacing (issue #320, AC4): this runtime's generated
+      // plugin/extension does not consume this wrapper's stdout for context injection today
+      // (confirmed by reading the generated bundle's tool-result handler) — a disclosed,
+      // pre-existing gap (see plan Unresolved Questions), not a silent one. Until that
+      // structural gap is closed, emit a stderr diagnostic only; the next-turn
+      // workflow-steering.js liveness warning remains the fallback corrector. Guarded on a
+      // well-formed `conflict` shape so a malformed value degrades to no diagnostic, never a
+      // thrown error (AC8, fail-open).
+      if (conflict && typeof conflict.actor === 'string' && typeof conflict.lastAt === 'string') {
+        process.stderr.write(
+          `[OpencodeTelemetryHook] liveness conflict: actor "${conflict.actor}" claimed this subject at "${conflict.lastAt}" — no mid-turn injection available on this runtime (see docs/spec/runtime-hook-surface.md); relying on next-turn workflow-steering warning.\n`
+        );
+      }
+    } catch (err) {
+      process.stderr.write(`[OpencodeTelemetryHook] liveness heartbeat error: ${err.message}\n`);
+    }
+  }
+
+  const result = spawnSync('bash', [telemetryScript, canonical, agentName], {
     input: raw,
     encoding: 'utf8',
     cwd: process.cwd(),

package/scripts/hooks/pi-telemetry-hook.js

@@ -70,9 +70,35 @@ async function main() {
   const [, , eventArg = 'unknown', agentName = 'dev'] = process.argv;
   const raw = await readStdinRaw();
   const payload = parseJson(raw);
+  const canonical = canonicalEvent(eventArg, payload);
   const telemetryScript = path.resolve(__dirname, '..', 'telemetry', 'telemetry.sh');
 
-  const result = spawnSync('bash', [telemetryScript, canonicalEvent(eventArg, payload), agentName], {
+  if (canonical === 'postToolUse') {
+    try {
+      const heartbeatResult = require('./lib/liveness-heartbeat').maybeEmitHeartbeat({
+        cwd: process.cwd(),
+        env: process.env,
+      });
+      const conflict = heartbeatResult && heartbeatResult.conflict;
+      // Degraded-runtime conflict surfacing (issue #320, AC4): this runtime's generated
+      // plugin/extension does not consume this wrapper's stdout for context injection today
+      // (confirmed by reading the generated bundle's tool-result handler) — a disclosed,
+      // pre-existing gap (see plan Unresolved Questions), not a silent one. Until that
+      // structural gap is closed, emit a stderr diagnostic only; the next-turn
+      // workflow-steering.js liveness warning remains the fallback corrector. Guarded on a
+      // well-formed `conflict` shape so a malformed value degrades to no diagnostic, never a
+      // thrown error (AC8, fail-open).
+      if (conflict && typeof conflict.actor === 'string' && typeof conflict.lastAt === 'string') {
+        process.stderr.write(
+          `[PiTelemetryHook] liveness conflict: actor "${conflict.actor}" claimed this subject at "${conflict.lastAt}" — no mid-turn injection available on this runtime (see docs/spec/runtime-hook-surface.md); relying on next-turn workflow-steering warning.\n`
+        );
+      }
+    } catch (err) {
+      process.stderr.write(`[PiTelemetryHook] liveness heartbeat error: ${err.message}\n`);
+    }
+  }
+
+  const result = spawnSync('bash', [telemetryScript, canonical, agentName], {
     input: raw,
     encoding: 'utf8',
     cwd: process.cwd(),

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

@@ -2,7 +2,7 @@
 /**
  * Stop Hook: warn when an active workflow is about to stop short of its goal.
  *
- * The hook reads .flow-agents artifacts, looks for the most recent active
+ * The hook reads .kontourai/flow-agents artifacts, looks for the most recent active
  * delivery/session file, and reports missing Definition Of Done, Goal Fit, or
  * Final Acceptance state.
  *
@@ -15,7 +15,7 @@
  * Code at L2) set block so the installed product enforces while the engine
  * default and conformance contract stay warn.
  *
- * Scope: the gate evaluates the session's current task (.flow-agents/current.json)
+ * Scope: the gate evaluates the session's current task (.kontourai/flow-agents/current.json)
  * when set, so an unrelated active workflow elsewhere in the repo does not gate
  * this stop. It also never hard-blocks a pre-execution (not-yet-started) task on
  * mere incompleteness — only genuine false-completion signals (a claimed pass the
@@ -315,6 +315,30 @@ function loadActiveFlowStep(flowAgentsDir) {
   }
 }
 
+/**
+ * Message-assembly only: derive the user-facing gate identity prefix from the
+ * resolved active FlowDefinition step (loadActiveFlowStep). Produces
+ * "[<flowId>/<gateId>]" (e.g. "[builder.build/verify-gate]") when a
+ * FlowDefinition gate is active, else the generic "[stop-gate]" fallback.
+ * Purely cosmetic — never affects claim selection, HARD_BLOCK/FULL_BLOCK
+ * classification, block counting, or exit codes.
+ */
+function gateLabel(activeFlowStep) {
+  return activeFlowStep && activeFlowStep.flowId && activeFlowStep.gateId
+    ? `[${activeFlowStep.flowId}/${activeFlowStep.gateId}]`
+    : '[stop-gate]';
+}
+
+/**
+ * Derive the declared claimType Set from an active FlowDefinition's gate expects[].
+ * Returns null when no FlowDefinition is active (callers fall back to workflow.* only).
+ */
+function declaredClaimTypesFor(activeFlowStep) {
+  return activeFlowStep && Array.isArray(activeFlowStep.gateExpects)
+    ? new Set(activeFlowStep.gateExpects.map(e => e && e.bundle_claim && e.bundle_claim.claimType).filter(Boolean))
+    : null;
+}
+
 function safeOneLine(value, maxLength = 220) {
   const text = String(value || '').replace(/\s+/g, ' ').trim();
   if (text.length <= maxLength) return text;
@@ -527,9 +551,7 @@ function bundlePendingCriteriaCount(claims, declaredClaimTypes) {
 function sidecarGuidance(root, artifactDir, activeFlowStep) {
   // Build the declared claimType set from the FlowDefinition gate expects[] (P-c).
   // Null when no FlowDefinition is active (fallback: helpers use workflow.* prefix only).
-  const declaredClaimTypes = activeFlowStep && Array.isArray(activeFlowStep.gateExpects)
-    ? new Set(activeFlowStep.gateExpects.map(e => e && e.bundle_claim && e.bundle_claim.claimType).filter(Boolean))
-    : null;
+  const declaredClaimTypes = declaredClaimTypesFor(activeFlowStep);
   const warnings = [];
   const state = readJsonFile(path.join(artifactDir, 'state.json'));
   const base = relative(root, artifactDir);
@@ -890,10 +912,39 @@ function verifyCommandLogChain(artifactDir) {
  *       FLOW_AGENTS_GOAL_FIT_RECHECK=true (the RCE-risky opt-in path).
  * Returns { argv, cwd, source } or null when nothing trusted resolves.
  */
+// WS8 (AC10b): a kind:"command" evidence ref's excerpt/command must be a literally runnable
+// shell command, not a prose description of a manual verification step. This heuristic
+// rejects prose so the goal-fit backstop never spawns `bash -lc "<a sentence>"` and
+// misreports the resulting shell error as a caught false-completion. Pairs with the rule
+// stated in context/contracts/planning-contract.md (AC11).
+function isRunnableCommandText(text) {
+  const s = typeof text === 'string' ? text.trim() : '';
+  if (!s) return false;
+  // Sentence-like prose (a . ! or ? followed by more words) is not a single command.
+  if (/[.!?]\s+\S/.test(s)) return false;
+  const first = s.split(/\s+/)[0] || '';
+  // WS8 (AC10b, iteration 2): the first-token allowlist is broadened to the common
+  // real-world verify binaries a project's runnable evidence names (git, tsc, eslint,
+  // python/python3, docker, curl, jq, diff, grep, test) so honest command evidence is not
+  // misclassified as prose. Still fail-closed for genuinely non-command prose: a bare
+  // sentence whose first token is none of these (and carries no path prefix or shell
+  // metacharacter) is rejected rather than executed.
+  const knownBinary = /^(npm|npx|pnpm|yarn|node|bash|sh|zsh|make|just|task|cargo|go|pytest|tox|deno|bun|ruby|rake|mvn|gradle|dotnet|swift|flutter|dart|git|tsc|eslint|python|python3|docker|curl|jq|diff|grep|test)$/.test(first)
+    || first.startsWith('./') || first.startsWith('/') || first.includes('/');
+  const hasShellMeta = /[|&;<>()$`]/.test(s);
+  return knownBinary || hasShellMeta;
+}
+
 function resolveTrustedCommand(root, artifactDir, check, acceptance) {
   // (a) acceptance criterion command for the matching criterion.
   const fromAcceptance = acceptanceCommandFor(check, acceptance);
-  if (fromAcceptance) return { argv: ['bash', '-lc', fromAcceptance], cwd: root, source: 'acceptance' };
+  if (fromAcceptance) {
+    // WS8 (AC10b): never spawn a prose "excerpt" as bash. A kind:"command" ref whose text
+    // is not a runnable shell command is malformed-evidence — reported distinctly, not
+    // executed, and not conflated with a caught false-completion.
+    if (!isRunnableCommandText(fromAcceptance)) return { malformed: fromAcceptance };
+    return { argv: ['bash', '-lc', fromAcceptance], cwd: root, source: 'acceptance' };
+  }
 
   // (b) declared manifest target. Map the check command/id to a declared script.
   const declared = declaredManifestTarget(root, check);
@@ -1020,9 +1071,7 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
   // Build the declared claimType set from the FlowDefinition gate expects[] (P-c).
   // Null when no FlowDefinition is active (fallback: bundleClaimedPassCommandChecks
   // uses workflow.check.* prefix only — no regression for non-FlowDefinition sessions).
-  const declaredClaimTypes = activeFlowStep && Array.isArray(activeFlowStep.gateExpects)
-    ? new Set(activeFlowStep.gateExpects.map(e => e && e.bundle_claim && e.bundle_claim.claimType).filter(Boolean))
-    : null;
+  const declaredClaimTypes = declaredClaimTypesFor(activeFlowStep);
   const bundle = readJsonFile(path.join(artifactDir, 'trust.bundle'));
   const acceptance = readJsonFile(path.join(artifactDir, 'acceptance.json'));
   const log = readLatestCommandLog(artifactDir); // Fix C: latest-wins; genuine fix-then-rerun-to-pass clears the block
@@ -1157,6 +1206,12 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
       continue;
     }
     const trusted = resolveTrustedCommand(root, artifactDir, check, acceptance);
+    if (trusted && trusted.malformed) {
+      // WS8 (AC10b): the matching acceptance criterion named a kind:"command" evidence ref
+      // whose text is prose, not a runnable command. Do NOT execute it; classify it.
+      warnings.push(`${base} evidence check ${id}: malformed-evidence — acceptance criterion names a kind:"command" evidence ref whose text is not a runnable shell command ("${safeOneLine(trusted.malformed, 120)}"); it was NOT executed. Use a literal runnable command, or record the check as not_verified/accepted_gap (see context/contracts/planning-contract.md).`);
+      continue;
+    }
     if (!trusted) {
       warnings.push(`${base} evidence check ${id}: claimed pass but NOT_VERIFIED — command "${safeOneLine(cmd, 120)}" was never captured and no trusted command (acceptance criterion / declared manifest target) resolves to re-run it. Set FLOW_AGENTS_GOAL_FIT_RECHECK=true to opt into re-running the model's free-form command.`);
       continue;
@@ -1360,9 +1415,7 @@ async function bundleEnforcement(artifactDir, activeFlowStep) {
   // When activeFlowStep is non-null, select claims whose claimType is in the
   // gate's declared set. When null, fall back to the existing workflow.* prefix
   // filter so no-FlowDefinition sessions are unaffected.
-  const declaredClaimTypes = activeFlowStep && Array.isArray(activeFlowStep.gateExpects)
-    ? new Set(activeFlowStep.gateExpects.map(e => e && e.bundle_claim && e.bundle_claim.claimType).filter(Boolean))
-    : null;
+  const declaredClaimTypes = declaredClaimTypesFor(activeFlowStep);
 
   // SECURITY (Layer 2 — gate-bypass-chain fix): use UNION form instead of if/else.
   // With the old if/else, an empty declaredClaimTypes (Set{}) from a fake flow with
@@ -1473,9 +1526,9 @@ async function bundleEnforcement(artifactDir, activeFlowStep) {
 }
 
 /**
- * Scope to the session's current task when .flow-agents/current.json points at
+ * Scope to the session's current task when .kontourai/flow-agents/current.json points at
  * one (mirroring evidence-capture.js). Returns the slug dir, or null to fall back
- * to scanning all of .flow-agents (newest-mtime).
+ * to scanning all of .kontourai/flow-agents (newest-mtime).
  */
 function preferredArtifactDir(flowAgentsDir) {
   const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
@@ -1487,6 +1540,24 @@ function preferredArtifactDir(flowAgentsDir) {
   return dir.startsWith(flowAgentsDir + path.sep) && fs.existsSync(dir) ? dir : null;
 }
 
+/** WS8 (AC10a): a session dir is eligible as "active" only with real sidecar presence. */
+function hasSidecarPresence(artifactDir) {
+  return fs.existsSync(path.join(artifactDir, 'state.json')) || fs.existsSync(path.join(artifactDir, 'trust.bundle'));
+}
+
+// WS8 (AC10a): when current.json names a slug whose session directory does NOT exist,
+// 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'));
+  if (!current) return null;
+  const slug = current.artifact_dir || current.active_slug;
+  if (typeof slug !== 'string' || !slug.trim()) return null;
+  const safe = slug.replace(/\.\.+/g, '').replace(/^[/\\]+/, '');
+  const dir = path.join(flowAgentsDir, safe);
+  return (dir.startsWith(flowAgentsDir + path.sep) && !fs.existsSync(dir)) ? slug : null;
+}
+
 /**
  * A task is pre-execution (work not yet started) when its state.json status/phase
  * is still in the idea→planning band, or (no state.json) its markdown status is.
@@ -1516,9 +1587,7 @@ function isPreExecution(artifactDir, markdownStatus) {
 // ADR 0016 P-c: pass activeFlowStep so bundlePendingCriteriaCount includes declared types.
 function missingBundleOrStateSignal(artifactDir, activeFlowStep) {
   // Build the declared claimType set from the FlowDefinition gate expects[] (P-c).
-  const declaredClaimTypes = activeFlowStep && Array.isArray(activeFlowStep.gateExpects)
-    ? new Set(activeFlowStep.gateExpects.map(e => e && e.bundle_claim && e.bundle_claim.claimType).filter(Boolean))
-    : null;
+  const declaredClaimTypes = declaredClaimTypesFor(activeFlowStep);
   const warnings = [];
   const hasBundle = fs.existsSync(path.join(artifactDir, 'trust.bundle'));
   const state = readJsonFile(path.join(artifactDir, 'state.json'));
@@ -1576,19 +1645,29 @@ function missingBundleOrStateSignal(artifactDir, activeFlowStep) {
 // MAX_BLOCKS hard-block guard (preventing auto-release of hard blocks).
 const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered/;
 // FULL_BLOCK adds: workflow-state hygiene, surface-unavailable fail-closed, missing log.
-const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered/;
+const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered|malformed-evidence/;
 
 async function analyze(root, now = Date.now()) {
   const flowAgentsDirs = flowAgentsArtifactRootsForRead(root);
   // Scope to the session's current task when current.json names one, so an
   // unrelated active workflow elsewhere in the repo does not gate this stop.
   const scoped = flowAgentsDirs.map(preferredArtifactDir).find(Boolean);
+  // WS8 (AC10a): if current.json points at a nonexistent slug, LOG the staleness and, in
+  // the global fallback, require sidecar presence so a stale pointer cannot resurface an
+  // abandoned/never-real markdown-only directory as "the active session".
+  const staleSlug = scoped ? null : flowAgentsDirs.map(staleCurrentSlug).find(Boolean);
+  if (staleSlug) {
+    process.stderr.write(`[Hook] Goal Fit: current.json names slug "${safeOneLine(staleSlug, 80)}" but no such session directory exists — ignoring the stale pointer instead of resurfacing an abandoned session via a global mtime scan.\n`);
+  }
   const searchDirs = scoped ? [scoped] : flowAgentsDirs;
-  const artifacts = searchDirs
+  let artifacts = searchDirs
     .flatMap(dir => walkMarkdown(dir))
     .map(readArtifact)
     .filter(isWorkflowArtifact)
     .sort((a, b) => b.mtimeMs - a.mtimeMs);
+  if (staleSlug) {
+    artifacts = artifacts.filter(a => a && hasSidecarPresence(path.dirname(a.file)));
+  }
 
   if (artifacts.length === 0) return { warnings: [], blocking: false };
 
@@ -1664,7 +1743,7 @@ async function analyze(root, now = Date.now()) {
     if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
     return blockRe.test(w);
   });
-  return { warnings, blocking, preExecution };
+  return { warnings, blocking, preExecution, gatePrefix: gateLabel(activeFlowStep) };
 }
 
 /**
@@ -1717,6 +1796,52 @@ function bumpBlockStreak(root, hash) {
   return count;
 }
 
+/**
+ * Message-assembly only: per-gap remediation guidance (linter-style "  → " line)
+ * appended under a matching warning. Fix-first / accept-second ordering per
+ * class; the "accept" path always names a reason requirement and is never the
+ * only or primary option. Does not affect which warnings are emitted, HARD_BLOCK/
+ * FULL_BLOCK classification, block counting, or exit codes — text only.
+ * Returns null when a warning does not match one of the four known classes.
+ */
+function remediationFor(warning) {
+  const w = String(warning || '');
+
+  // (1) claimed pass but the trusted re-run failed — reuse the exact command
+  // already named in the warning text; never invent a different one.
+  // NOTE: anchor on the quoted command substring + fixed tail, NOT on
+  // `trusted backstop (<source>)` paren-matching. trusted.source can itself
+  // contain parens (e.g. "model-command (FLOW_AGENTS_GOAL_FIT_RECHECK)"), and a
+  // non-nesting `[^)]*` silently fails to match that nested-paren source,
+  // dropping the guidance line for the RECHECK backstop path.
+  const rerun = /re-run of "([\s\S]+?)" FAILED with exit \d+, contradicting the claimed pass/.exec(w);
+  if (rerun) {
+    return `  → run: ${rerun[1]} — fix the failures, then re-record the check`;
+  }
+
+  // (2) claimed pass never captured (no trusted command resolved, backstop
+  // disabled via FLOW_AGENTS_GOAL_FIT_BACKSTOP=skip, or the backstop could not launch).
+  // Same nested-paren fix as (1): match on the invariant "could not run" tail
+  // rather than paren-counting the `(<source>)` segment.
+  if (/claimed pass but NOT_VERIFIED — command ".+?" was never captured/.test(w)
+    || /claimed pass but NOT_VERIFIED — trusted backstop .*could not run/.test(w)) {
+    return "  → run the command in this session (evidence capture is active), then re-record the check with the exact command string via: npm run workflow:sidecar -- record-evidence <artifact-dir> --verdict <v> --check-json '...'";
+  }
+
+  // (3) critique verdict fail / open findings.
+  if (/critique status:/.test(w) || /critique open /.test(w)) {
+    return '  → resolve the findings and record a passing critique (record-critique), or mark each finding accepted with a reason';
+  }
+
+  // (4) evidence verdict fail / missing acceptance evidence.
+  if (/evidence verdict:/.test(w) || /evidence check .+ status:/.test(w)
+    || /evidence NOT_VERIFIED gap:/.test(w) || /Final Acceptance:/.test(w)) {
+    return '  → fix the failing check, or record it as an accepted gap with justification in the session artifact';
+  }
+
+  return null;
+}
+
 async function run(rawInput) {
   const input = parseJson(rawInput);
   const root = findRepoRoot(input.cwd || process.cwd());
@@ -1728,9 +1853,15 @@ async function run(rawInput) {
     return rawInput;
   }
 
+  const gatePrefix = result.gatePrefix || '[stop-gate]';
   const message = [
-    '[Hook] Goal Fit warning:',
-    ...result.warnings.map(w => ` - ${w}`),
+    `${gatePrefix} Goal Fit warning:`,
+    ...result.warnings.flatMap(w => {
+      const lines = [` - ${w}`];
+      const guidance = remediationFor(w);
+      if (guidance) lines.push(guidance);
+      return lines;
+    }),
   ].join('\n');
 
   if (mode !== 'block' || !result.blocking) {
@@ -1746,7 +1877,7 @@ async function run(rawInput) {
     // N identical hard blocks to escape via the streak counter must not work.
     //
     // BAR-RAISER, NOT AIRTIGHT: an agent with shell access can still reset the streak
-    // by deleting .flow-agents/.goal-fit-block-streak.json or by modifying the warning
+    // with runtime-constructed paths or by modifying the warning
     // text so the hash changes. The real anchor is external (signed checkpoints + human
     // review). This raises the cost of the burn-through-the-counter escape vector.
     const isHardBlock = result.warnings.some(w => {
@@ -1757,20 +1888,20 @@ async function run(rawInput) {
       // Do NOT clear the streak — keep accumulating so the same hard block stays visible.
       return {
         stdout: rawInput,
-        stderr: `${message}\n[Hook] Goal Fit: max-blocks reached but the block is a caught false-completion / integrity failure — not auto-releasing; requires a real fix or operator override.`,
+        stderr: `${message}\n${gatePrefix} max-blocks reached but the block is a caught false-completion / integrity failure — not auto-releasing; requires a real fix or operator override.`,
         exitCode: 2,
       };
     }
     clearBlockStreak(root);
     return {
       stdout: rawInput,
-      stderr: `${message}\n[Hook] Goal Fit block RELEASED after ${count} consecutive identical blocks (FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS=${maxBlocks}): the same gap persists, surfacing to the human instead of looping.`,
+      stderr: `${message}\n${gatePrefix} released — the same gap(s) blocked ${count}x without progress; needs your decision (listed above).`,
       exitCode: 0,
     };
   }
   return {
     stdout: rawInput,
-    stderr: `${message}\n[Hook] Goal Fit BLOCK ${count}/${maxBlocks}.`,
+    stderr: `${message}\n${gatePrefix} Stop blocked — ${result.warnings.length} evidence gap(s) (block ${count}; after ${maxBlocks} identical blocks I stop blocking and hand this to you)`,
     exitCode: 2,
   };
 }

package/scripts/hooks/workflow-steering.js

@@ -17,6 +17,7 @@
 const fs = require('fs');
 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 STEERING = {
@@ -205,6 +206,52 @@ function contextMapSteering(root) {
   ].join(' ');
 }
 
+function promptText(input) {
+  const candidates = [
+    input && input.prompt,
+    input && input.user_prompt,
+    input && input.message,
+    input && input.text,
+    input && input.tool_input && input.tool_input.prompt,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate;
+  }
+  return '';
+}
+
+function looksLikeBuilderWork(text) {
+  const normalized = safeStateText(text, 2000).toLowerCase();
+  if (!normalized) return false;
+  const readOnlyIntent = /\b(read[- ]only|review[- ]only|no (source |code |file )?(changes?|edits?|modifications?)|do not (modify|edit|change|write|fix|implement|touch)|don't (modify|edit|change|write|fix|implement|touch)|dont (modify|edit|change|write|fix|implement|touch))\b/.test(normalized);
+  if (readOnlyIntent) return false;
+  const questionOnlyIntent = /^(what|which|who|when|where|why|how)\b/.test(normalized);
+  if (questionOnlyIntent) return false;
+  const noCodeQuestion = /\b(explain|describe|summari[sz]e|what is|how does|how do i|why does|review|critique)\b/.test(normalized)
+    && !/\b(build|create|implement|ship|deliver|fix|debug|refactor|add|update|change|modify|wire|migrate|install|scaffold|write|code)\b/.test(normalized);
+  if (noCodeQuestion) return false;
+  const verificationOnlyIntent = /\b(validate|test|verify|check)\b/.test(normalized)
+    && !/\b(build|create|implement|ship|deliver|fix|debug|refactor|add|update|change|modify|wire|migrate|install|scaffold|write|code)\b/.test(normalized);
+  if (verificationOnlyIntent) return false;
+  const hasWorkVerb = /\b(build|create|implement|ship|deliver|fix|debug|refactor|add|update|change|modify|wire|migrate|install|scaffold|write|code)\b/.test(normalized);
+  const hasWorkObject = /\b(api|endpoint|component|feature|bug|failing test|regression|integration|hook|script|cli|config|schema|migration)\b/.test(normalized);
+  const hasRequestLanguage = /\b(can you|please|let's|lets|need|should|make|ensure|support|add|update|fix|work on)\b/.test(normalized);
+  return hasWorkVerb || (hasWorkObject && hasRequestLanguage);
+}
+
+function builderWorkflowSteering(input) {
+  if (!looksLikeBuilderWork(promptText(input))) return '';
+  return [
+    'BUILDER WORKFLOW ROUTE: this user prompt looks like coding/build work.',
+    'Builder lifecycle: shape raw ideas -> build selected work -> publish verified branch/PR -> learn correction feedback.',
+    'Before source edits or implementation commands, activate Builder Kit delivery workflow.',
+    'If the user explicitly requested TDD, activate `tdd-workflow`; otherwise activate `deliver` and keep the session on `builder.build`.',
+    'Use `npm run workflow:sidecar -- ensure-session --flow-id builder.build ...` when the repo provides the sidecar writer.',
+    'After local verification, continue to publish/release-readiness and learning-review; do not treat local verification as terminal delivery.',
+    'Do not bypass plan-work -> execute-plan -> review-work -> verify-work for coding tasks; direct implementation is only acceptable when the user explicitly asks for no workflow or explanation-only help.',
+  ].join(' ');
+}
+
 /**
  * Compose the RESUME block for SessionStart.
  *
@@ -297,15 +344,20 @@ function resumeSteering(root, current) {
 
     // Liveness advisory
     try {
+      const resolved = resolveActor(process.env);
+      const selfActor = resolved.actor || 'local';
       const events = flowAgentsArtifactRootsForRead(root)
         .flatMap(artifactRoot => readLivenessEvents(path.join(artifactRoot, 'liveness', 'events.jsonl')));
       if (events.length > 0) {
-        const selfActor = (process.env.FLOW_AGENTS_ACTOR || '').trim() || 'local';
+        // selfActor (for exclusion matching) stays raw here; only the display strings pushed
+        // into `lines` are sanitized below, since holders come from the shared multi-writer
+        // liveness stream and must be treated as untrusted display input (#287 fix iteration 1).
         const holders = freshHolders(events, slug, selfActor, Date.now());
         for (const h of holders) {
-          lines.push(`[LIVENESS WARNING: another agent appears live on this work: actor ${h.actor}, last seen ${h.lastAt}]`);
+          lines.push(`[LIVENESS WARNING: another agent appears live on this work: actor ${safeStateText(h.actor)}, last seen ${h.lastAt}]`);
         }
       }
+      lines.push(`ACTOR: ${safeStateText(selfActor)} (${resolved.source})`);
     } catch { /* skip */ }
 
     // Pull-work route hint
@@ -348,6 +400,15 @@ function run(rawInput) {
       }
     }
 
+    if (event === 'UserPromptSubmit') {
+      const builderHint = builderWorkflowSteering(input);
+      if (builderHint) {
+        hints.push(builderHint);
+        const contextHint = contextMapSteering(root);
+        if (contextHint) hints.push(contextHint);
+      }
+    }
+
     // SessionStart only: append the RESUME block for richer situational awareness
     if (event === 'SessionStart' && current) {
       const resumeBlock = resumeSteering(root, current);
@@ -379,4 +440,17 @@ if (require.main === module) {
   });
 }
 
-module.exports = { run, stateSteering, critiqueSteering, contextMapSteering, latestWorkflowState, findRepoRoot, safeStateText, stateNeedsAmbientSteering, resumeSteering };
+module.exports = {
+  run,
+  stateSteering,
+  critiqueSteering,
+  contextMapSteering,
+  latestWorkflowState,
+  findRepoRoot,
+  safeStateText,
+  stateNeedsAmbientSteering,
+  resumeSteering,
+  promptText,
+  looksLikeBuilderWork,
+  builderWorkflowSteering,
+};