@kontourai/flow-agents 3.12.1 → 4.1.0

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

@@ -140,7 +140,7 @@ function walkMarkdown(dir, out = []) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === 'archive') continue;
+      if (entry.name === 'archive' || entry.name === 'narrative') continue;
       walkMarkdown(full, out);
     } else if (entry.isFile() && entry.name.endsWith('.md')) {
       out.push(full);
@@ -996,7 +996,12 @@ function verifyCommandLogChain(artifactDir) {
     sources.push(entry.source);
     parentSources.set(chain.prevHash, sources);
     if (sources.length > 1) {
-      if (!sources.every(s => s === 'postToolUse-capture')) {
+      // #634: the canonical writer's own execution observations
+      // ('canonical-writer-execution', appended by record-gate-claim under the
+      // same lockfile) legitimately race the PostToolUse capture on the same
+      // tip inside the lock's fail-open window. Both sources are benign fork
+      // siblings; any OTHER source on a shared parent stays tamper.
+      if (!sources.every(s => s === 'postToolUse-capture' || s === 'canonical-writer-execution')) {
         return { status: 'broken', brokenAt: i, forkAt: null };
       }
       if (firstForkAt === null) firstForkAt = i;
@@ -1026,10 +1031,86 @@ function verifyCommandLogChain(artifactDir) {
 // WS8 (AC10b): isRunnableCommandText now lives in ./lib/runnable-command.js (single
 // source of truth shared with workflow-sidecar.ts's record-time validation, #412).
 
+function decodeNarrativeReference(value) {
+  try { return decodeURIComponent(String(value || '')); } catch { return String(value || ''); }
+}
+
+function realpathWithExistingPrefix(candidate) {
+  let cursor = path.resolve(candidate);
+  const suffix = [];
+  while (!fs.existsSync(cursor)) {
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return path.resolve(candidate);
+    suffix.unshift(path.basename(cursor));
+    cursor = parent;
+  }
+  try {
+    const real = fs.realpathSync.native ? fs.realpathSync.native(cursor) : fs.realpathSync(cursor);
+    return path.resolve(real, ...suffix);
+  } catch { return path.resolve(candidate); }
+}
+
+function isNarrativeArtifactContent(bytes) {
+  const text = Buffer.isBuffer(bytes) ? bytes.toString('utf8') : String(bytes || '');
+  try {
+    const value = JSON.parse(text);
+    if (value && typeof value === 'object') {
+      if (value.schema_version === 'grounded-execution-narrative/v1' || value.schema_version === 'grounded-runtime-projection/v1') return true;
+      if (value.schema_version === '1.0' && typeof value.narrative_id === 'string' && typeof value.captured_at === 'string'
+        && value.compiler && typeof value.compiler === 'object' && value.capture_completeness && typeof value.capture_completeness === 'object'
+        && Array.isArray(value.sources)) return true;
+    }
+  } catch { /* non-JSON content may still be a rendered narrative */ }
+  return text.includes('flow-agents-narrative-composer') && text.includes('# Grounded Execution Narrative') && text.includes('## Authority provenance');
+}
+
+function referencesNarrativeNamespace(root, command) {
+  // Static scanning cannot resolve arbitrary runtime shell composition such as
+  // `base=.kontourai; test -f "$base/narrative/..."`. The compensating control
+  // is that command evidence persists only the command, exit status, and an
+  // observed-output digest; it never materializes referenced file bytes. Every
+  // channel that does materialize files is independently content-shape guarded.
+  const decoded = decodeNarrativeReference(command).replaceAll('\\', '/');
+  const foldedCommand = decoded.toLowerCase();
+  if (foldedCommand.includes('.kontourai/narrative')) return true;
+  if (/(?:^|[^A-Za-z0-9._-])\.kontourai(?:\/[^/\s"'`]+)*\/narrative(?:$|[/\s"'`])/.test(decoded.toLowerCase())) return true;
+
+  // A relative narrative path becomes namespace-bearing after a shell `cd`.
+  // Resolve the directory operand, then inspect only the subsequent command.
+  for (const match of decoded.matchAll(/(?:^|[;&|]\s*)cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&|]+))\s*&&([\s\S]*?)(?=(?:[;&|]\s*cd\s+)|$)/gi)) {
+    const cdTarget = match[1] || match[2] || match[3];
+    const canonicalTarget = realpathWithExistingPrefix(path.isAbsolute(cdTarget) ? cdTarget : path.resolve(root, cdTarget));
+    const foldedTarget = canonicalTarget.replaceAll('\\', '/').toLowerCase();
+    const inKontouraiTree = foldedTarget.endsWith('/.kontourai') || foldedTarget.includes('/.kontourai/');
+    if (!inKontouraiTree) continue;
+    const subsequentTokens = match[4].split(/[\s"'`;|&<>]+/).filter(Boolean);
+    if (subsequentTokens.some(token => /(?:^|\/)narrative\//i.test(token.replaceAll('\\', '/')))) return true;
+  }
+
+  const matches = [...decoded.matchAll(/(?:file:\/\/[^\s"'`;&|<>]+|(?:\.{0,2}\/|\/)[^\s"'`;&|<>]+|[^\s"'`;&|<>]+\/[^\s"'`;&|<>]+)/g)].map(match => match[0]);
+  const tokens = [decoded, ...matches];
+  const canonicalNamespace = realpathWithExistingPrefix(path.join(root, '.kontourai', 'narrative')).toLowerCase();
+  for (let token of tokens) {
+    token = token.replace(/^[('"`]+|[)'"`,:]+$/g, '');
+    if (!token || (token.includes('://') && !token.startsWith('file://'))) continue;
+    if (token.startsWith('file://')) {
+      try { token = new URL(token).pathname; } catch { continue; }
+    }
+    const candidate = realpathWithExistingPrefix(path.isAbsolute(token) ? token : path.resolve(root, token));
+    const folded = candidate.toLowerCase();
+    if (folded === canonicalNamespace || folded.startsWith(`${canonicalNamespace}${path.sep}`)) return true;
+    try {
+      if (fs.statSync(candidate).isFile() && isNarrativeArtifactContent(fs.readFileSync(candidate))) return true;
+    } catch { /* unresolved command tokens are handled by ordinary command validation */ }
+  }
+  return false;
+}
+
 function resolveTrustedCommand(root, artifactDir, check, acceptance) {
   // (a) acceptance criterion command for the matching criterion.
   const fromAcceptance = acceptanceCommandFor(check, acceptance);
   if (fromAcceptance) {
+    if (referencesNarrativeNamespace(root, fromAcceptance)) return { refused: fromAcceptance, refusal: 'narrative trust isolation (#619)' };
     // 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.
@@ -1070,6 +1151,7 @@ function resolveTrustedCommand(root, artifactDir, check, acceptance) {
   // (c) free-form model command — opt-in only.
   if (String(process.env.FLOW_AGENTS_GOAL_FIT_RECHECK || '').toLowerCase() === 'true') {
     const cmd = normalizeCommand(check && check.command);
+    if (cmd && referencesNarrativeNamespace(root, cmd)) return { refused: cmd, refusal: 'narrative trust isolation (#619)' };
     if (cmd) return { argv: ['bash', '-lc', cmd], cwd: root, source: 'model-command (FLOW_AGENTS_GOAL_FIT_RECHECK)' };
   }
   return null;
@@ -1380,6 +1462,10 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
       continue;
     }
     const trusted = resolveTrustedCommand(root, artifactDir, check, acceptance);
+    if (trusted && trusted.refused) {
+      warnings.push(`${base} evidence check ${id}: ${trusted.refusal} — command "${safeOneLine(trusted.refused, 120)}" references the narrative namespace and was NOT executed.`);
+      continue;
+    }
     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.
@@ -2174,7 +2260,7 @@ async function analyze(root, now = Date.now()) {
     warnings.push(`workflow state: canonical Flow run remains active at step ${activeStep}; complete or explicitly cancel the run before stopping.`);
   }
   const blockRe = ((preExecution && !activeFlowRun) || terminal) ? HARD_BLOCK : FULL_BLOCK;
-  const activeTurnAuthority = activeFlowRun && canonicalFlow.state && !unsafeActiveCanonical
+  const activeTurnAuthority = activeFlowRun && !terminal && canonicalFlow.state && !unsafeActiveCanonical
     ? validateActiveTurnAuthority({
       sessionDir: latestArtifactDir,
       runId: process.env.FLOW_AGENTS_CONTINUATION_RUN_ID,
@@ -2192,14 +2278,77 @@ async function analyze(root, now = Date.now()) {
     if (activeTurnAuthority.valid && isOrdinaryActiveGateWarning(w, relPath)) return false;
     return blockingRe.test(w);
   });
-  return { warnings, blocking, activeFlowRun, activeTurnAuthority: activeTurnAuthority.valid, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
+  return {
+    warnings,
+    blocking,
+    activeFlowRun,
+    activeTurnAuthority: activeTurnAuthority.valid,
+    activeTurnIssuedStep: activeTurnAuthority.valid ? activeTurnAuthority.record.issued_step : null,
+    activeFlowCurrentStep: canonicalFlow.state?.current_step || null,
+    preExecution,
+    gatePrefix: gateLabel(activeFlowStep),
+    warningRelPath: relPath,
+    latestArtifactDir,
+  };
+}
+
+// #659 Slice B: internal Flow-step / expectation vocabulary → plain-English
+// labels, so the human lead below doesn't leak implementation terms.
+const PLAIN_STEP = {
+  'pull-work': 'work selection',
+  'design-probe': 'scoping',
+  plan: 'planning',
+  execute: 'the build',
+  verify: 'final review',
+  'release-readiness': 'release readiness',
+  'learning-review': 'the wrap-up review',
+};
+// Each entry maps a token that appears in the raw warnings to a plain label for
+// "what still needs recording". Order is display order.
+const PLAIN_EXPECTATIONS = [
+  { rx: /clean-critique|critique\.review/, label: 'a reviewer sign-off' },
+  { rx: /acceptance-criteria|acceptance\.criterion/, label: 'the acceptance checks' },
+  { rx: /tests?-evidence|verify\.tests/, label: 'test results' },
+  { rx: /policy-compliance/, label: 'a policy check' },
+];
+
+// #659 Slice A: a plain-language lead for the stop-hook output. Returns a short
+// human summary (what is paused, how many sign-offs remain, the two options), or
+// null when there is no active Builder run to explain. Presentation only — it
+// reads the same `result` the technical block is built from and never mutates it.
+function plainStopLead(result, gapCount) {
+  if (!result || !result.activeFlowRun) return null;
+  const name = result.latestArtifactDir ? path.basename(result.latestArtifactDir) : 'a task';
+  const step = String(result.activeFlowCurrentStep || '').trim();
+  const stepPhrase = PLAIN_STEP[step] || (step ? `the "${step}" step` : 'a checkpoint');
+  const haystack = Array.isArray(result.warnings) ? result.warnings.join('\n') : '';
+  const needs = PLAIN_EXPECTATIONS.filter(e => e.rx.test(haystack)).map(e => e.label);
+  const needsList = needs.length ? ` Still needed: ${needs.join(', ')}.` : '';
+  const count = Number.isFinite(gapCount) && gapCount > 0
+    ? (gapCount === 1 ? '1 sign-off' : `${gapCount} sign-offs`)
+    : 'a few sign-offs';
+  return [
+    `⏸ In plain terms: the task "${name}" is paused at its ${stepPhrase}. ${count} still need recording before it can finish on its own.${needsList}`,
+    `   Two ways forward: let it finish those checks, or cancel the run to close it now. Nothing else you're doing is blocked by this.`,
+    `   (The technical detail below is for the agent/debugging.)`,
+  ].join('\n');
 }
 
 function isOrdinaryActiveGateWarning(warning, relPath) {
+  const normalizedRelPath = relPath.replaceAll('\\', '/');
+  const sessionSlug = path.posix.basename(path.posix.dirname(normalizedRelPath));
+  const canonicalActive = /^workflow state: canonical Flow run remains active at step .+; complete or explicitly cancel the run before stopping\.$/.test(warning);
+  if (HARD_BLOCK.test(warning) && !canonicalActive) return false;
+  const finalAcceptancePrefix = `${sessionSlug} Final Acceptance:`;
+  const currentFinalAcceptance = warning.startsWith(finalAcceptancePrefix)
+    && /^ \d+ acceptance criterion\/criteria still pending; complete CI\/merge\/docs before final delivery\.$/.test(warning.slice(finalAcceptancePrefix.length));
+  const surfaceUnavailable = /^surface unavailable — \d+ high\/critical-impact claim\(s\) could not be re-derived at gate; stored claim status is trusted without independent re-derivation \(fail-closed: high-assurance path\)\. Ensure @kontourai\/surface is installed and importable, or escalate for operator review\.$/.test(warning);
   return warning.startsWith(`${relPath} is still status:`)
     || /(?:^|\/)\.kontourai\/flow-agents\/[^/]+ workflow state:/.test(warning)
     || /(?:^|\/)\.kontourai\/flow-agents\/[^/]+ (?:next action|required skills|required operations|next command):/.test(warning)
-    || /canonical Flow run remains active at step .+; complete or explicitly cancel the run before stopping\.$/.test(warning);
+    || currentFinalAcceptance
+    || surfaceUnavailable
+    || canonicalActive;
 }
 
 function isHardStopWarning(warning, relPath, activeTurnAuthority) {
@@ -2582,9 +2731,33 @@ async function run(rawInput) {
   }
 
   const gatePrefix = result.gatePrefix || '[stop-gate]';
+  const relPath = result.warningRelPath || relative(root, result.latestArtifactDir || root);
+  const remediationWarnings = result.activeTurnAuthority && result.blocking
+    ? result.warnings.filter(w => isHardStopWarning(w, relPath, true))
+    : result.warnings;
+  // A signed continuation turn owns one issued gate action. When a real blocker
+  // requires another model pass, do not mix the next gate's advisory actions into
+  // that remediation prompt: smaller models reasonably treat every visible next
+  // action as authorized work and can cross the driver's fresh-context boundary.
+  const issuedStep = safeOneLine(result.activeTurnIssuedStep || 'unknown', 80);
+  const canonicalStep = safeOneLine(result.activeFlowCurrentStep || 'unknown', 80);
+  const repairBoundary = issuedStep !== canonicalStep
+    ? `Do not perform work for later canonical step "${canonicalStep}" in this turn.`
+    : `Remain within issued step "${issuedStep}" in this turn.`;
+  const repairScope = result.activeTurnAuthority && result.blocking
+    ? ` - continuation repair scope: this signed turn was issued for step "${issuedStep}"; repair only the hard blocker(s) below and return control to the driver. ${repairBoundary}`
+    : null;
+  // #659 Slice A+B: lead with a plain-language summary so a human (not just an
+  // agent) can tell what is paused and what their options are. Presentation only
+  // — derived from the same state, prepended to the output string, and NEVER
+  // folded into remediationWarnings/result.warnings (those feed reasonsHash,
+  // block-dedup, and the HARD_BLOCK detector, which must stay byte-stable).
+  const plainLead = plainStopLead(result, remediationWarnings.length);
   const message = [
+    ...(plainLead ? [plainLead, ''] : []),
     `${gatePrefix} Goal Fit warning:`,
-    ...result.warnings.flatMap(w => {
+    ...(repairScope ? [repairScope] : []),
+    ...remediationWarnings.flatMap(w => {
       const lines = [` - ${w}`];
       const guidance = remediationFor(w);
       if (guidance) lines.push(guidance);
@@ -2598,7 +2771,7 @@ async function run(rawInput) {
   }
 
   const maxBlocks = resolveMaxBlocks();
-  const count = bumpBlockStreak(root, reasonsHash(result.warnings));
+  const count = bumpBlockStreak(root, reasonsHash(remediationWarnings));
   if (count >= maxBlocks) {
     // AC2: never auto-release a HARD block (caught false-completion, capture contradiction,
     // tamper signal, gate misconfiguration, integrity failure). An agent burning through
@@ -2628,7 +2801,7 @@ async function run(rawInput) {
   }
   return {
     stdout: rawInput,
-    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)`,
+    stderr: `${message}\n${gatePrefix} Stop blocked — ${remediationWarnings.length} evidence gap(s) (block ${count}; after ${maxBlocks} identical blocks I stop blocking and hand this to you)`,
     exitCode: 2,
   };
 }
@@ -2664,4 +2837,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { analyze, run, resolveGoalFitMode, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine, captureCrossReference, bundleEnforcement, loadActiveFlowStep, readCommandLog, resolveTrustedCommand, declaredManifestTarget, verifyCommandLogChain, CHAIN_GENESIS_VERIFY, hasLaunderingOperator, releaseOnNonTerminalStop, isHardStopWarning, canonicalFlowState };
+module.exports = { analyze, run, resolveGoalFitMode, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine, captureCrossReference, bundleEnforcement, loadActiveFlowStep, readCommandLog, resolveTrustedCommand, declaredManifestTarget, verifyCommandLogChain, CHAIN_GENESIS_VERIFY, hasLaunderingOperator, releaseOnNonTerminalStop, isHardStopWarning, canonicalFlowState, plainStopLead };

package/scripts/hooks/workflow-steering.js

@@ -16,11 +16,13 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
 const { resolveActor, isUnresolvedActor } = require('./lib/actor-identity');
 const { flowAgentsArtifactRootsForRead, resolveSharedRepoRoot, warnIfFailingOpenInsideGitTree } = require('./lib/local-artifact-paths');
 const { readOwnCurrentPointer } = require('./lib/current-pointer');
-const { workflowTriggersFor } = require('./lib/kit-catalog');
+const { readKitManifests, workflowTriggersFor } = require('./lib/kit-catalog');
+const { canonicalFlowState } = require('./stop-goal-fit');
 
 const STEERING = {
   'tool-planner': [
@@ -69,6 +71,7 @@ const ACTIVE_STATE_STATUSES = new Set([
   'not_verified',
   'failed',
   'delivered',
+  'canceled',
 ]);
 
 function findRepoRoot(startDir) {
@@ -231,6 +234,115 @@ function stateNeedsAmbientSteering(state) {
   );
 }
 
+const CANONICAL_NONTERMINAL_STATUSES = new Set(['active', 'blocked', 'needs_decision', 'paused']);
+const CANONICAL_TERMINAL_STATUSES = new Set(['completed', 'canceled', 'failed', 'accepted_by_exception']);
+const ACTION_ID_RE = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+function flowStepAction(flowId, stepId) {
+  const packageRoot = path.resolve(__dirname, '..', '..');
+  const inventory = readKitManifests(packageRoot);
+  if (inventory.warnings.length) return { action: null, error: 'installed kit metadata is unavailable or malformed' };
+  const matches = [];
+  for (const kit of inventory.kits) {
+    const actions = kit.manifest && kit.manifest.flow_step_actions;
+    if (!Array.isArray(actions)) continue;
+    for (const action of actions) {
+      if (action && action.flow_id === flowId && action.step_id === stepId) matches.push({ ...action, kit_id: kit.kit_id });
+    }
+  }
+  if (matches.length !== 1) return { action: null, error: `expected one installed step action for ${flowId}/${stepId}; found ${matches.length}` };
+  const action = matches[0];
+  const skills = action.skills === undefined ? [] : action.skills;
+  const operations = action.operations === undefined ? [] : action.operations;
+  if (!Array.isArray(skills) || !skills.every(value => ACTION_ID_RE.test(value))
+    || !Array.isArray(operations) || !operations.every(value => ACTION_ID_RE.test(value))
+    || typeof action.implementation_allowed !== 'boolean') {
+    return { action: null, error: `installed step action for ${flowId}/${stepId} is malformed` };
+  }
+  return {
+    action: {
+      kit_id: action.kit_id,
+      flow_id: action.flow_id,
+      step_id: action.step_id,
+      skills,
+      operations,
+      implementation_allowed: action.implementation_allowed,
+    },
+    error: null,
+  };
+}
+
+function guidanceConflict(reason) {
+  return { kind: 'conflict', code: 'GUIDANCE_CONFLICT', reason: safeStateText(reason, 240) };
+}
+
+function canonicalGuidance(root, current) {
+  const sidecar = current && current.payload;
+  const projected = sidecar && sidecar.flow_run;
+  if (!projected) return { kind: 'legacy' };
+  if (typeof projected !== 'object' || Array.isArray(projected)) return guidanceConflict('Flow Agents flow_run projection is malformed');
+
+  const canonical = canonicalFlowState(root, path.dirname(current.file));
+  if (canonical.error || !canonical.state || !canonical.definition) {
+    return guidanceConflict(canonical.error || 'canonical Flow state is unavailable');
+  }
+  const state = canonical.state;
+  const expected = {
+    run_id: state.run_id,
+    definition_id: state.definition_id,
+    definition_version: state.definition_version,
+    status: state.status,
+    current_step: state.current_step,
+  };
+  for (const [field, value] of Object.entries(expected)) {
+    if (projected[field] !== value) return guidanceConflict(`Flow Agents ${field} does not match canonical Flow state`);
+  }
+  if (!CANONICAL_NONTERMINAL_STATUSES.has(state.status) && !CANONICAL_TERMINAL_STATUSES.has(state.status)) {
+    return guidanceConflict(`canonical Flow status ${state.status} is unsupported for guidance`);
+  }
+
+  const terminal = CANONICAL_TERMINAL_STATUSES.has(state.status);
+  const resolved = terminal ? { action: null, error: null } : flowStepAction(state.definition_id, state.current_step);
+  if (resolved.error) return guidanceConflict(resolved.error);
+  const identityPayload = { state, definition: canonical.definition, action: resolved.action };
+  const identity = crypto.createHash('sha256').update(JSON.stringify(identityPayload)).digest('hex');
+  return {
+    kind: terminal ? 'terminal' : 'canonical',
+    state,
+    action: resolved.action,
+    identity,
+  };
+}
+
+function canonicalGuidanceLines(guidance) {
+  if (guidance.kind === 'conflict') {
+    return [
+      `${guidance.code}: ${guidance.reason}.`,
+      'No executable workflow recommendation is available until canonical Flow and Flow Agents state agree.',
+    ];
+  }
+  const { state } = guidance;
+  const lines = [
+    `Canonical Flow: ${safeStateText(state.definition_id, 120)}@${safeStateText(state.definition_version, 80)}/${safeStateText(state.run_id, 120)} status:${state.status} current_step:${safeStateText(state.current_step, 120)}.`,
+    `Canonical guidance identity: sha256:${guidance.identity}.`,
+  ];
+  if (guidance.kind === 'terminal') {
+    lines.push('This canonical run is terminal; no gate action or implementation is authorized.');
+    return lines;
+  }
+  const { action } = guidance;
+  lines.push(`Gate action source: installed kit ${safeStateText(action.kit_id, 80)}.`);
+  if (action.skills.length) lines.push(`Gate skills: ${action.skills.join(' -> ')}.`);
+  if (action.operations.length) lines.push(`Gate operations: ${action.operations.join(' -> ')}.`);
+  if (!action.skills.length && !action.operations.length) lines.push('Gate action: no skill or operation declared.');
+  lines.push(`Implementation allowed: ${action.implementation_allowed ? 'yes' : 'no'}.`);
+  if (state.status === 'blocked') lines.push('The run is blocked; clear or route the blocker before executing the gate action.');
+  else if (state.status === 'needs_decision') lines.push('The run needs a decision; record it before executing the gate action.');
+  else if (state.status === 'paused') lines.push('The run is paused; resume it before executing the gate action.');
+  else lines.push(`Continue only with the declared action for ${safeStateText(state.current_step, 120)}; do not restart or route to another step.`);
+  return lines;
+}
+
 function critiqueSteering(workflowDir) {
   const critique = readJson(path.join(workflowDir, 'critique.json'));
   if (!critique || critique.required !== true) return '';
@@ -266,10 +378,12 @@ function critiqueSteering(workflowDir) {
   return parts.join(' ');
 }
 
-function stateSteering(root) {
-  const current = latestWorkflowState(root);
+function stateSteering(root, currentState = null, resolvedGuidance = null) {
+  const current = currentState || latestWorkflowState(root);
   if (!current) return '';
   const state = current.payload;
+  const guidance = resolvedGuidance || canonicalGuidance(root, current);
+  if (guidance.kind !== 'legacy') return canonicalGuidanceLines(guidance).join(' ');
   const next = state.next_action || {};
   if (next.status === 'done' || state.status === 'archived' || state.status === 'accepted') return '';
   const parts = [
@@ -417,19 +531,24 @@ function kitWorkflowSteering(input, root) {
  * @param {{ file: string, payload: object }} current  Latest active state entry
  * @returns {string}
  */
-function resumeSteering(root, current) {
+function resumeSteering(root, current, resolvedGuidance = null) {
   try {
     const state = current.payload;
     const workflowDir = path.dirname(current.file);
     const slug = state.task_slug || path.basename(workflowDir);
     const next = state.next_action || {};
 
+    const guidance = resolvedGuidance || canonicalGuidance(root, current);
+    if (guidance.kind !== 'legacy') {
+      return canonicalGuidanceLines(guidance).join('\n');
+    }
     if (next.status === 'done' || state.status === 'archived' || state.status === 'accepted') return '';
 
     const lines = [];
 
     // Header line
     lines.push(`RESUME: ${slug} status:${safeStateText(state.status, 60)} phase:${safeStateText(state.phase, 60)}`);
+    lines.push('Guidance source: NON-CANONICAL FALLBACK.');
 
     // Full next action (240-char display path, not the 80-char normalization)
     const nextSummary = next.summary ? safeStateText(next.summary, 240) : 'none';
@@ -441,6 +560,16 @@ function resumeSteering(root, current) {
       lines.push(`Required operations: ${next.operations.map(operation => safeStateText(operation, 80)).join(' -> ')}`);
     }
     if (next.command) lines.push(`Run: ${safeStateText(next.command, 240)}`);
+    if (next.target_phase) lines.push(`Target phase: ${safeStateText(next.target_phase, 80)}`);
+    if (stateNeedsAmbientSteering(state)) {
+      lines.push('WORKFLOW STATE ATTENTION: unresolved workflow state must be addressed before completion.');
+    }
+    if (next.status === 'needs_user' || state.status === 'needs_decision' || state.status === 'not_verified') {
+      lines.push('Do not deliver as complete until the user decision or accepted gap is recorded.');
+    }
+    if (state.status === 'failed') lines.push('Route back through execution, then re-review and re-verify.');
+    const critiqueHint = critiqueSteering(workflowDir);
+    if (critiqueHint) lines.push(critiqueHint);
 
     // Plan artifact path
     let planPath = 'not found';
@@ -456,7 +585,7 @@ function resumeSteering(root, current) {
     } catch { /* skip */ }
     lines.push(`Plan: ${planPath}`);
 
-    // Handoff: next_steps[0] and blockers
+    // Legacy sessions use handoff.next_steps as a noncanonical compatibility fallback.
     let nextStep = 'none';
     let blockers = 'none';
     try {
@@ -519,8 +648,7 @@ function resumeSteering(root, current) {
       lines.push(`ACTOR: ${safeStateText(selfActor)} (${resolved.source})`);
     } catch { /* skip */ }
 
-    // Pull-work route hint
-    lines.push('To continue: resume this work. Or run pull-work to assess WIP and start new/parallel work.');
+    lines.push('To continue (noncanonical fallback): resume this work. Or run pull-work to assess WIP and start new/parallel work.');
 
     return lines.join('\n');
   } catch {
@@ -581,30 +709,39 @@ function run(rawInput) {
     const toolInput = input.tool_input || {};
     const root = findRepoRoot(input.cwd || process.cwd());
     const current = latestWorkflowState(root);
+    const guidance = current ? canonicalGuidance(root, current) : { kind: 'legacy' };
     const hints = [];
     let shouldAppendWorkflowContext = false;
 
     if (toolInput.command === 'InvokeSubagents') {
-      const subagents = toolInput.content?.subagents || [];
-      hints.push(...subagents
-        .map(s => STEERING[s.agent_name])
-        .filter(Boolean));
-      shouldAppendWorkflowContext = hints.length > 0;
+      if (guidance.kind === 'legacy') {
+        const subagents = toolInput.content?.subagents || [];
+        hints.push(...subagents
+          .map(s => STEERING[s.agent_name])
+          .filter(Boolean));
+        shouldAppendWorkflowContext = hints.length > 0;
+      } else {
+        hints.push(canonicalGuidanceLines(guidance).join(' '));
+        const contextHint = contextMapSteering(root);
+        if (contextHint) hints.push(contextHint);
+      }
     }
 
-    if ((event === 'UserPromptSubmit' || event === 'SessionStart') && current) {
-      const stateHint = stateSteering(root);
+    if (event === 'UserPromptSubmit' && current) {
+      const stateHint = stateSteering(root, current, guidance);
       if (stateHint) {
-        hints.push(stateNeedsAmbientSteering(current.payload)
-          ? 'WORKFLOW STATE ATTENTION: current sidecars show unresolved workflow state at turn start.'
-          : 'WORKFLOW STATE: an active task is in progress — re-ground the recorded goal and resume the next step before doing anything else.');
+        if (guidance.kind === 'legacy') {
+          hints.push(stateNeedsAmbientSteering(current.payload)
+            ? 'WORKFLOW STATE ATTENTION: current sidecars show unresolved workflow state at turn start.'
+            : 'WORKFLOW STATE: an active task is in progress — re-ground the recorded goal and resume the next step before doing anything else.');
+        }
         hints.push(stateHint);
         const contextHint = contextMapSteering(root);
         if (contextHint) hints.push(contextHint);
       }
     }
 
-    if (event === 'UserPromptSubmit') {
+    if (event === 'UserPromptSubmit' && guidance.kind === 'legacy') {
       const kitHint = kitWorkflowSteering(input, root);
       if (kitHint) {
         hints.push(kitHint);
@@ -622,8 +759,10 @@ function run(rawInput) {
 
     // SessionStart only: append the RESUME block for richer situational awareness
     if (event === 'SessionStart' && current) {
-      const resumeBlock = resumeSteering(root, current);
+      const resumeBlock = resumeSteering(root, current, guidance);
       if (resumeBlock) hints.push(resumeBlock);
+      const contextHint = contextMapSteering(root);
+      if (contextHint) hints.push(contextHint);
       const supersessionHint = supersessionSteering(root, current);
       if (supersessionHint) hints.push(supersessionHint);
     }
@@ -676,4 +815,6 @@ module.exports = {
   promptText,
   looksLikeImplementationWork,
   kitWorkflowSteering,
+  flowStepAction,
+  canonicalGuidance,
 };

package/scripts/telemetry/economics-record.schema.json

@@ -131,7 +131,7 @@
         "runtime": { "type": ["string", "null"] },
         "per_delegation_tokens": {
           "type": "boolean",
-          "description": "Whether the runtime isolates per-sub-agent token usage. False on every runtime today → per-delegation cost is unavailable."
+          "description": "Whether the runtime isolates per-sub-agent token usage. DERIVED (not hardcoded, #620) from the runtime's capability declaration (build/generated/capability-declarations.json, keyed on the normalized .agent.runtime with kiro-cli→kiro): true IFF the declared per_delegation_tokens status is 'supported'. An unresolved runtime or a missing declaration JSON yields the explicit sentinel false, never a fabricated true. False on every runtime today → per-delegation cost is unavailable."
         },
         "per_delegation_outcome": {
           "type": "string",

package/scripts/telemetry/economics-record.sh

@@ -138,6 +138,45 @@ if [[ -n "$agents_dir" && -d "$agents_dir" ]]; then
   [[ -n "$assembled" && "$assembled" != "null" ]] && delegations_json="$assembled"
 fi
 
+# --- per_delegation_tokens signal: DERIVED from the capability declaration (#620) ------------------
+# Replaces the former hardcoded `false` literal. The value is read from the build-only generated
+# JSON (build/generated/capability-declarations.json — src/tools/generate-capability-matrix.ts, keyed
+# on canonical runtime id), keyed on the NORMALIZED `.agent.runtime`. The alias fold mirrors
+# src/lib/capability-declarations.ts::normalizeRuntimeId (lowercase, trim, collapse whitespace,
+# kiro-cli→kiro / raw-model→base) so a Kiro record (whose runtime value is `kiro-cli`) resolves its
+# declaration instead of silently missing. Kept hermetic: jq-only, no node subprocess at emit time.
+#
+# SENTINEL SEMANTICS (never fabricate a `true` one layer down): the boolean is true IFF the declared
+# per_delegation_tokens capability STATUS is "supported". An unresolved runtime (blank, or a runtime
+# with no declaration) OR a missing/unreadable JSON yields the EXPLICIT sentinel `false` — matching
+# the prior default — via a DISTINCT jq branch from a declared-false value. Declared-false (status
+# unsupported/partial) and unresolved both map to `false` today, but because they travel separate
+# branches, a future `supported` declaration flips the signal ONLY for a genuinely-declared runtime
+# while an unknown runtime stays sentinel-false. The final `case` re-clamps any non-boolean jq output
+# (parse/read failure) back to the `false` sentinel so a fabricated `true` is impossible.
+capability_decl_file="${FLOW_AGENTS_CAPABILITY_DECL_FILE:-$SCRIPT_DIR/../../build/generated/capability-declarations.json}"
+capability_decl_json="$(read_json_or_null "$capability_decl_file")"
+raw_runtime="$(printf '%s' "$usage_event" | jq -r '.agent.runtime // ""' 2>/dev/null)" || raw_runtime=""
+per_delegation_tokens="$(
+  printf '%s' "$capability_decl_json" | jq -r \
+    --arg raw "$raw_runtime" '
+    ( $raw | ascii_downcase | gsub("^\\s+";"") | gsub("\\s+$";"") | gsub("\\s+";"-") ) as $lc
+    | ( if   $lc == "kiro-cli"         then "kiro"
+        elif $lc == "raw-model"        then "base"
+        elif $lc == "raw-model-runner" then "base"
+        else $lc end ) as $canon
+    | if   . == null            then false   # missing/unreadable JSON  -> sentinel false (unresolved)
+      elif ($canon == "")       then false   # blank runtime            -> sentinel false (unresolved)
+      elif (has($canon) | not)  then false   # runtime not declared     -> sentinel false (unresolved)
+      else ((.[$canon].per_delegation_tokens.status // "") == "supported")  # DECLARED value
+      end
+  ' 2>/dev/null
+)" || per_delegation_tokens="false"
+case "$per_delegation_tokens" in
+  true | false) ;;
+  *) per_delegation_tokens="false" ;;   # re-clamp any jq parse/read failure to the sentinel
+esac
+
 tenant_self="${CONSOLE_TENANT_ID:-${FLOW_AGENTS_CONSOLE_TENANT:-}}"
 
 # --- assemble the record with ONE jq -c filter (injection-safe, valid JSON) -------------------------
@@ -148,6 +187,7 @@ record="$(printf '%s' "$usage_event" | jq -c \
   --argjson critique "$critique_json" \
   --argjson acceptance "$acceptance_json" \
   --argjson delegations "$delegations_json" \
+  --argjson per_delegation_tokens "$per_delegation_tokens" \
   --arg tenant "$tenant_self" '
   . as $e
   | ($e.usage // {}) as $u
@@ -219,14 +259,18 @@ record="$(printf '%s' "$usage_event" | jq -c \
       delegations: ($delegations // []),
       # signals: what telemetry the CURRENT runtime actually exposed, so a consumer can tell a real zero
       # from a harness-blind gap (never fabricate — see docs/specs/harness-capability-matrix.md).
-      #   per_delegation_tokens: no runtime isolates per-sub-agent token usage today → cost-per-delegation
-      #     is unavailable; the console attributes at (role,model) granularity via cost.by_model instead.
+      #   per_delegation_tokens: DERIVED (not hardcoded, #620) from the runtime capability declaration
+      #     via build/generated/capability-declarations.json, keyed on the normalized .agent.runtime
+      #     (kiro-cli→kiro). true IFF the declared status is "supported"; unresolved runtime / missing
+      #     JSON → explicit sentinel false (never a fabricated true). No runtime isolates per-sub-agent
+      #     token usage today → cost-per-delegation is unavailable; the console attributes at
+      #     (role,model) granularity via cost.by_model instead.
       #   per_delegation_outcome: coverage of the outcome signal on THIS run — "full" (every delegation has
       #     a real outcome), "partial" (some do), "none" (delegations exist but none had a verdict/escalation),
       #     "n/a" (no delegations observed).
       signals: {
         runtime: ($e.agent.runtime // null),
-        per_delegation_tokens: false,
+        per_delegation_tokens: $per_delegation_tokens,
         per_delegation_outcome: (
           ($delegations // []) as $d
           | ($d | length) as $n

package/scripts/telemetry/lib/session.sh

@@ -63,4 +63,7 @@ session_cleanup() {
   # Bound the per-cwd project-label cache (see console_project_label) so a project rename
   # (package.json name / git remote) self-heals within the same window instead of caching forever.
   find "${TELEMETRY_SESSION_DIR}" -name "project-label.*" -mtime +1 -delete 2>/dev/null || true
+  # Bound #580 tool-start records (see tool_start_record_path) so an invoke whose matching
+  # result never fires (crash, dropped hook, etc.) doesn't leak the start file forever.
+  find "${TELEMETRY_SESSION_DIR}" -name "toolstart-*" -mtime +1 -delete 2>/dev/null || true
 }