@kontourai/flow-agents 3.12.1 → 4.0.0

package/dist/pi/schemas/narrative-source-manifest.schema.json

@@ -0,0 +1,294 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/narrative-source-manifest.schema.json",
+  "title": "Flow Agents Narrative Source Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "narrative_id",
+    "captured_at",
+    "compiler",
+    "capture_completeness",
+    "sources"
+  ],
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "chain_prev_hash": {
+      "anyOf": [
+        {
+          "const": "a3f9e2b7d5c84f1e6a0d2c3b9f7e1a4d8c6b5f2e9a0d3c7b1f4e8a2d6c0b9f3"
+        },
+        {
+          "$ref": "#/$defs/sha256"
+        }
+      ]
+    },
+    "source_id": {
+      "type": "string",
+      "pattern": "^fa1:(telemetry|cmdlog|agent-event|delegation|trust-claim|trust-evidence|flow-state|flow-report|flow-transition|surface-explanation|transcript|file):(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*:(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*(?:#(?:0|[1-9][0-9]*))?$"
+    },
+    "integrity_class": {
+      "type": "string",
+      "enum": [
+        "hash_chained",
+        "append_only_unhashed",
+        "rotatable",
+        "overwritten_in_place",
+        "path_only"
+      ]
+    },
+    "origin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["store", "path_class"],
+      "properties": {
+        "store": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path_class": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "chain": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["seq", "prevHash", "hash"],
+          "properties": {
+            "seq": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "prevHash": {
+              "$ref": "#/$defs/chain_prev_hash"
+            },
+            "hash": {
+              "$ref": "#/$defs/sha256"
+            }
+          }
+        },
+        "package": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "version"],
+          "properties": {
+            "name": { "type": "string", "minLength": 1 },
+            "version": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "redactions": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_$-]+(?:\\.[A-Za-z0-9_$-]+)*$"
+      }
+    },
+    "lineage": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["at", "event"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "event": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "snapshotted_source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_id",
+        "integrity_class",
+        "captured_at",
+        "origin",
+        "status",
+        "sha256",
+        "bytes",
+        "lineage"
+      ],
+      "properties": {
+        "source_id": {
+          "$ref": "#/$defs/source_id"
+        },
+        "integrity_class": {
+          "$ref": "#/$defs/integrity_class"
+        },
+        "captured_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "origin": {
+          "$ref": "#/$defs/origin"
+        },
+        "status": {
+          "const": "snapshotted"
+        },
+        "sha256": {
+          "$ref": "#/$defs/sha256"
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "redactions": {
+          "$ref": "#/$defs/redactions"
+        },
+        "lineage": {
+          "$ref": "#/$defs/lineage"
+        }
+      }
+    },
+    "unavailable_source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_id",
+        "integrity_class",
+        "captured_at",
+        "origin",
+        "status",
+        "unavailable_reason",
+        "lineage"
+      ],
+      "properties": {
+        "source_id": {
+          "$ref": "#/$defs/source_id"
+        },
+        "integrity_class": {
+          "$ref": "#/$defs/integrity_class"
+        },
+        "captured_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "origin": {
+          "$ref": "#/$defs/origin"
+        },
+        "status": {
+          "const": "unavailable"
+        },
+        "unavailable_reason": {
+          "type": "string",
+          "enum": [
+            "expired",
+            "redacted",
+            "unauthorized",
+            "not_captured",
+            "corrupt"
+          ]
+        },
+        "redactions": {
+          "$ref": "#/$defs/redactions"
+        },
+        "lineage": {
+          "$ref": "#/$defs/lineage"
+        }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "narrative_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "captured_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "compiler": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "policy_hash"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "policy_hash": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "capture_completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channels", "known_gaps"],
+      "properties": {
+        "channels": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["active", "inactive", "unknown"]
+          }
+        },
+        "known_gaps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["class", "ref"],
+            "properties": {
+              "class": {
+                "type": "string",
+                "enum": [
+                  "mcp_non_native_tools",
+                  "actor_attribution_conflation",
+                  "cross_session_event_contamination"
+                ]
+              },
+              "ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "note": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    },
+    "sources": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/snapshotted_source"
+          },
+          {
+            "$ref": "#/$defs/unavailable_source"
+          }
+        ]
+      }
+    }
+  }
+}

package/dist/pi/scripts/check-hachure-boundary.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * check-hachure-boundary — portfolio layer-doctrine ratchet.
+ *
+ * Doctrine (surface/docs/architecture/portfolio-layer-doctrine.md): only Surface
+ * may depend on the open trust format (hachure) directly. Products speak the
+ * format THROUGH Surface (Surface.validateTrustBundle / validateInquiryRecord /
+ * TrustBundleBuilder), so a hachure version can never drift across the suite.
+ *
+ * This check FAILS if a NEW direct-hachure usage appears in src/ or package.json.
+ * Today's known usages are allowlisted below and should be removed as each one
+ * migrates onto the Surface OTF read side. It is a ratchet: it does not force the
+ * existing migration, it prevents the problem from getting worse.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+// ── Allowlist: current, pending-migration direct-hachure usage ───────────────
+// Remove an entry once its hachure usage is gone (routed through @kontourai/surface).
+const ALLOWLISTED_SOURCE_FILES = new Set([]);
+// package.json may still declare hachure while a source file above still needs it.
+const ALLOW_PACKAGE_JSON_HACHURE_DEP = false;
+
+// No `\b` before `require`: flow-agents calls `_require.resolve("hachure")`
+// (an aliased require), so a word-boundary anchor would miss it.
+const IMPORT_PATTERNS = [
+  /from\s+['"]hachure['"]/,
+  /require(\.resolve)?\(\s*['"]hachure['"]\s*\)/,
+  /import\(\s*['"]hachure['"]\s*\)/,
+];
+const SOURCE_EXT = /\.(ts|tsx|mjs|cjs|js|jsx)$/;
+
+function trackedSourceFiles() {
+  return execFileSync("git", ["ls-files", "src"], { encoding: "utf8" })
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((f) => f && SOURCE_EXT.test(f));
+}
+
+const violations = [];
+
+for (const file of trackedSourceFiles()) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    continue;
+  }
+  text.split("\n").forEach((line, index) => {
+    if (IMPORT_PATTERNS.some((re) => re.test(line)) && !ALLOWLISTED_SOURCE_FILES.has(file)) {
+      violations.push(`${file}:${index + 1}  direct hachure usage — route through @kontourai/surface instead`);
+    }
+  });
+}
+
+const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+let pkgDeclaresHachure = false;
+for (const field of ["dependencies", "optionalDependencies", "peerDependencies", "devDependencies"]) {
+  if (pkg[field] && Object.prototype.hasOwnProperty.call(pkg[field], "hachure")) {
+    pkgDeclaresHachure = true;
+    if (!ALLOW_PACKAGE_JSON_HACHURE_DEP) {
+      violations.push(`package.json ${field}.hachure — depend on @kontourai/surface, not hachure directly`);
+    }
+  }
+}
+
+if (violations.length) {
+  console.error("[check-hachure-boundary] FAILED — new direct-hachure usage (products speak the open format through Surface):");
+  for (const v of violations) console.error(`  ${v}`);
+  console.error(
+    "\nSee the Portfolio Layer Doctrine (surface/docs/architecture/portfolio-layer-doctrine.md).\n" +
+      "Use @kontourai/surface (validateTrustBundle / validateInquiryRecord / TrustBundleBuilder).\n" +
+      "If this is a deliberate, reviewed exception, add it to the allowlist in this script with a migration note.",
+  );
+  process.exitCode = 1;
+} else {
+  const notes = [];
+  if (ALLOWLISTED_SOURCE_FILES.size) notes.push(`${ALLOWLISTED_SOURCE_FILES.size} allowlisted source file(s) pending migration`);
+  if (pkgDeclaresHachure && ALLOW_PACKAGE_JSON_HACHURE_DEP) notes.push("package.json hachure dep allowlisted pending migration");
+  console.log(`[check-hachure-boundary] OK — no new direct-hachure usage${notes.length ? ` (${notes.join("; ")})` : ""}.`);
+}

package/dist/pi/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 };