@junghanacs/entwurf 0.13.0 → 0.14.0

package/scripts/lib/step-outcome.sh

@@ -0,0 +1,88 @@
+# shellcheck shell=bash
+# Release-gate STEP OUTCOME protocol — the one place PASS / SKIP / FAIL is decided.
+#
+# SOURCE-ONLY. It carries the executable bit because check-pack requires every
+# shipped `.sh` to have one (a blanket packaging invariant worth more than an
+# exception carved for this file), not because anyone should run it.
+#
+# Sourced by run.sh's `release_gate`; sourced directly by
+# scripts/check-release-gate-outcomes.ts so the truth table is exercised as a
+# unit instead of being re-derived by eye from the aggregate's output.
+#
+# WHY A PROTOCOL AND NOT A PER-BACKEND BRANCH (P1, 2026-07-31). The aggregate's
+# prose said a cut needs `LIVE=1` and `SKIP=0`, but its exit authority read only
+# the FAIL counter, so `./run.sh release-gate` returned 0 with 14 SKIPs and the
+# summary still printed "all green". Worse, a step that WAS invoked could decide
+# it lacked a prerequisite and exit 0 — Cortex with no
+# `ENTWURF_ACP_CORTEX_CONNECTION` is the measured case — and the aggregate
+# counted that as PASS. Both holes have the same shape: a skip that cannot be
+# told from an acceptance. So the fix is one outcome protocol every step speaks,
+# never a special case per backend or per prerequisite.
+#
+# EXIT CONTRACT (house style: the verdict IS the exit code)
+#   0                          PASS — the step ran and its assertions held.
+#   ENTWURF_STEP_SKIP_EXIT     SKIP — the step declined a prerequisite it does
+#                              not have. NOT acceptance, and never rounded up.
+#   anything else              FAIL — including a crash or a signal death.
+#
+# WHY 97. The repo already spends 0..4 on per-tool exit contracts that mean
+# different things per tool (meta-bridge-fresh-cut's 3 = "cut transition
+# incomplete", meta-bridge-store-doctor's 3 = "unreadable store", dev-bin's 3 =
+# "refused a foreign link"), and 126+ belongs to the shell. A LIVE smoke shells
+# out to some of those tools, so reusing a low number would let a dependency's
+# unrelated verdict surface as a false SKIP — the exact confusion this protocol
+# exists to remove. 97 is reserved for THIS cross-tool protocol and nothing else.
+ENTWURF_STEP_SKIP_EXIT=97
+
+# Classify one step's exit code. Prints PASS | SKIP | FAIL on stdout.
+entwurf_step_outcome() {
+	case "${1:-}" in
+		0) printf 'PASS\n' ;;
+		"$ENTWURF_STEP_SKIP_EXIT") printf 'SKIP\n' ;;
+		*) printf 'FAIL\n' ;;
+	esac
+}
+
+# The release authority. Returns 0 when the run may be read as a cut floor.
+#
+#   $1 MUST fail count   $2 MUST skip count   $3 cut mode (1 = a real cut)
+#
+# A FAIL always blocks. A SKIP blocks ONLY in cut mode: an ordinary diagnostic
+# `./run.sh release-gate <dir>` must stay runnable unattended and still exit 0
+# while honestly reporting what it did not call. `--cut` is the executable half
+# of "a CUT needs LIVE=1, SKIP=0" — and it needs no separate LIVE assertion,
+# because with LIVE unset every LIVE-gated step skips and the skip count blocks.
+entwurf_release_releasable() {
+	local failc="${1:-0}" skipc="${2:-0}" cut="${3:-0}"
+	[ "$failc" -gt 0 ] && return 1
+	if [ "$cut" = "1" ] && [ "$skipc" -gt 0 ]; then
+		return 1
+	fi
+	return 0
+}
+
+# The same decision as ONE greppable token, because "why is this red" must be
+# machine-readable and not parsed out of prose.
+#
+#   $1 MUST fail count   $2 MUST skip count   $3 cut mode (1 = a real cut)
+#
+# A step that RAN AND BROKE and a step that NEVER RAN are different facts, and a
+# release record that blurs them is worthless: the first is a defect to fix, the
+# second is a prerequisite to supply. So the counters are never fudged either —
+# a policy block keeps `FAIL=0 SKIP=n` and says `BLOCKED (MUST SKIP)`. Reporting
+# a synthetic `FAIL=1` for the policy block would destroy exactly the
+# distinction this protocol exists to create.
+entwurf_release_verdict() {
+	local failc="${1:-0}" skipc="${2:-0}" cut="${3:-0}"
+	if [ "$failc" -gt 0 ]; then
+		printf 'cut: BLOCKED (MUST FAIL)\n'
+	elif [ "$cut" = "1" ] && [ "$skipc" -gt 0 ]; then
+		printf 'cut: BLOCKED (MUST SKIP)\n'
+	elif [ "$cut" = "1" ]; then
+		printf 'cut: OK\n'
+	elif [ "$skipc" -gt 0 ]; then
+		printf 'cut: n/a (diagnostic, %s SKIP)\n' "$skipc"
+	else
+		printf 'cut: n/a (diagnostic)\n'
+	fi
+}

package/scripts/meta-bridge-doctor.sh

@@ -1207,14 +1207,12 @@ case "$REPO" in
     fi
     ;;
 esac
-# prefixRoots operator policy (5d-4b): the shared env SSOT both v2 surfaces read. Display
-# ONLY — the parser SSOT lives in entwurf-v2-surface.ts (proven by check-entwurf-v2-surface);
-# the doctor does NOT re-implement parsing. Unset ⇒ no prefix promotion (the safe default).
-if [ -z "${ENTWURF_PREFIX_ROOTS:-}" ]; then
-  ok "ENTWURF_PREFIX_ROOTS unset → no prefix auto-approve (preflight default trust)"
-else
-  ok "ENTWURF_PREFIX_ROOTS set → operator prefix-approve roots: $ENTWURF_PREFIX_ROOTS"
-fi
+# NOT REPORTED: ENTWURF_PREFIX_ROOTS. It was the operator-policy SSOT that both v2 surfaces
+# read to feed the dispatch-path trust preflight, and that preflight guarded the resume verdict
+# — so it left with `owned-outcome` in the visible-first cut. Nothing on the dispatch path reads
+# the variable now, and a doctor line saying "set → operator prefix-approve roots" would report a
+# knob that does nothing. Reporting an inert setting as live policy is the failure this doctor
+# exists to prevent, so the row is gone rather than softened.
 
 echo
 if [ "$fail" -eq 0 ]; then echo "meta-bridge doctor: PASS"; else echo "meta-bridge doctor: FAIL (see above)"; exit 1; fi

package/scripts/meta-facts.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * meta-facts — owner-normalized, read-only projection of the meta-record store (#65).
+ *
+ * The one join a consumer cannot make anywhere else — `(gardenId, nativeSessionId,
+ * transcriptPath)` — lives only in the meta-record store, and reading that store
+ * correctly means carrying the whole certification contract (strict v3 keyset,
+ * parse-before-uniqueness, no-winner duplicates, O_NOFOLLOW regular-file reads).
+ * External consumers that copied it decayed the day the contract moved. This surface
+ * makes THE owner emit the join: it is `listAllMetaIdentities` over the real store —
+ * the same listing `entwurf_peers` trusts — serialized verbatim. No parallel parser,
+ * no liveness, no socket paths, no transcript contents, no state, no watching.
+ *
+ * stdout (deterministic, 2-space indent, trailing newline):
+ *   {
+ *     "schemaVersion": 1,          // of THIS projection, not of the records
+ *     "storeDir": "/abs/path",
+ *     "citizens": [ <full verbatim strict 9-field v3 records, sorted by gardenId> ],
+ *     "defects":  [ { "filename", "message" }, … sorted by filename ]
+ *   }
+ *
+ * Defects ride IN-BAND: a readable store with uncertifiable entries is a fact to
+ * report, not a failure of this command — the healthy citizens are still true, and
+ * the defect list is exactly what `listAllMetaIdentities` refused and why (a rival
+ * pair is refused on BOTH sides; a schema-invalid record can never quarantine a
+ * healthy neighbour, because parse runs before uniqueness).
+ *
+ * EXIT CONTRACT — the verdict is the exit code (store-doctor precedent):
+ *   0 — store readable; the JSON above is on stdout (defects, if any, in-band).
+ *       A store that does not exist is a readable EMPTY store (ENOENT only).
+ *   2 — usage error (bad argv).
+ *   3 — the store could not be READ (EACCES/ENOTDIR/…). No JSON is emitted:
+ *       an unreadable host must never look like an empty one.
+ */
+
+import { defaultMetaSessionsDir, listAllMetaIdentitiesDir } from "../pi-extensions/lib/meta-session.ts";
+
+const arg = process.argv[2];
+// A dash argv is a flag this command does not have, not a store directory — treating
+// it as a path would answer `--help` with "empty store, exit 0", a silent wrong fact.
+if (process.argv.length > 3 || (arg !== undefined && arg.startsWith("-"))) {
+	console.error("usage: entwurf meta-facts [meta-sessions-dir]");
+	process.exit(2);
+}
+
+let facts: ReturnType<typeof listAllMetaIdentitiesDir>;
+try {
+	facts = listAllMetaIdentitiesDir(arg ?? defaultMetaSessionsDir());
+} catch (err) {
+	console.error(`FAIL: ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(3); // see the EXIT CONTRACT above: 3 = unreadable store, never an empty one
+}
+
+process.stdout.write(
+	`${JSON.stringify(
+		{ schemaVersion: 1, storeDir: facts.dir, citizens: facts.identities, defects: facts.errors },
+		null,
+		2,
+	)}\n`,
+);

package/scripts/mutants/acp-augment.json

@@ -25,6 +25,112 @@
 			"timeoutSeconds": 60,
 			"signature": "[QK:AUGMENT-TRUNC-MARKER]",
 			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-PROVENANCE-STATED",
+			"title": "the augment stops saying what it is — the model is back to reading a first-user prepend as its system prompt (the measured 2026-07-30 misattribution)",
+			"subject": "pi-extensions/lib/acp/augment.ts",
+			"find": [
+				"\t\"This block is prepended to the FIRST USER MESSAGE of this session. It is not your system prompt.\";"
+			],
+			"replace": ["\t\"\";"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-PROVENANCE-STATED]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-FRAME-NAMES-CLAUDE-CARRIER",
+			"title": "the claude frame stops naming its real engraving-only carrier — the model is told what its system prompt is NOT, but never what it IS",
+			"subject": "pi-extensions/lib/acp/augment.ts",
+			"find": [
+				"\t\t\t\t\t`The ${params.backend} rail does have a system-prompt carrier (\\`_meta.systemPrompt\\`), and entwurf keeps it deliberately tiny: it carries the operator engraving only — never this narrative, never AGENTS.md.`,"
+			],
+			"replace": ["\t\t\t\t\t`The ${params.backend} rail carries no system-prompt carrier at all.`,"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-FRAME-NAMES-CLAUDE-CARRIER]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-FRAME-DENIES-CORTEX-CARRIER",
+			"title": "the carrier-less rail is told it has a tiny system-prompt carrier — a flat lie, since cortex's buildSessionMeta sends no _meta at all",
+			"subject": "pi-extensions/lib/acp/augment.ts",
+			"find": [
+				"\t\t\t\t\t`The ${params.backend} rail carries no system-prompt carrier at all — entwurf sends no \\`_meta.systemPrompt\\`, so everything entwurf tells you, including any operator engraving above, arrives here as user-message text.`,"
+			],
+			"replace": [
+				"\t\t\t\t\t`The ${params.backend} rail does have a system-prompt carrier (\\`_meta.systemPrompt\\`), and entwurf keeps it deliberately tiny: it carries the operator engraving only.`,"
+			],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-FRAME-DENIES-CORTEX-CARRIER]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-RAIL-DIFF-IS-SOURCE-PINNED",
+			"title": "cortex grows a session carrier while the augment still tells it there is none — the frame becomes a lie and no prose check would notice",
+			"subject": "pi-extensions/lib/acp/backend-adapter.ts",
+			"find": ["\tbuildSessionMeta() {\n\t\treturn undefined;\n\t},"],
+			"replace": ["\tbuildSessionMeta() {\n\t\treturn { systemPrompt: \"x\" };\n\t},"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-RAIL-DIFF-IS-SOURCE-PINNED]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-LEADS-ITS-OWN-BLOCK",
+			"title": "the carrier loses its leading boundary — the Claude SDK's fixed sentence swallows the operator engraving again (the measured 2026-07-31 A-join)",
+			"subject": "pi-extensions/lib/acp/engraving.ts",
+			"find": ["export const CARRIER_LEAD_SEPARATOR = \"\\n\\n\";"],
+			"replace": ["export const CARRIER_LEAD_SEPARATOR = \"\";"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-LEADS-ITS-OWN-BLOCK]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-OPT-OUT-SURVIVES-SEPARATOR",
+			"title": "the boundary is attached before the emptiness test — an emptied engraving file stops being the opt-out and becomes a whitespace carrier that still replaces the claude_code preset",
+			"subject": "pi-extensions/lib/acp/engraving.ts",
+			"find": [
+				"\tconst body = interpolate(source, params).trim();",
+				"\tif (body.length === 0) return \"\";",
+				"\treturn `${CARRIER_LEAD_SEPARATOR}${body}`;"
+			],
+			"replace": [
+				"\tconst body = `${CARRIER_LEAD_SEPARATOR}${interpolate(source, params).trim()}`;",
+				"\tif (body.length === 0) return \"\";",
+				"\treturn body;"
+			],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-OPT-OUT-SURVIVES-SEPARATOR]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-STAYS-TINY",
+			"title": "the shipped carrier grows into a real prompt — size, not shape, is what routes an OAuth subscription call to metered extra usage",
+			"subject": "pi-extensions/lib/acp/prompts/engraving.md",
+			"find": ["# Engraving Here"],
+			"replace": [
+				"# Engraving Here\n\n## Operator standing orders\n\n- Address the operator by name and keep the reply language matched to the prompt.\n- Prefer surgical edits over rewrites; verify every claim you make about behavior.\n- Never bypass a commit hook, and never push without an explicit request.\n- Indentation is tabs unless the project's linter says otherwise.\n- When docs and behavior disagree, report it and fix the source of truth.\n- Long-running commands belong in tmux, not in a foreground shell.\n- Record the next concrete move before you stop working.\n\n## Project context\n\nThis checkout is the bridge itself, so treat the adapter contract in the rail doc\nas authoritative and re-read it before touching a gate. The qualification lane is\nthe oracle for every contract claim; a green assertion count proves nothing on\nits own."
+			],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-STAYS-TINY]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-META-SENDS-CARRIER-VERBATIM",
+			"title": "the meta hop normalizes the carrier — the boundary is stripped back off on the wire while bridgeConfigSignature still folds the bounded value, so the A-join returns and reuse keys on a string the backend never received",
+			"subject": "pi-extensions/lib/acp/tool-surface.ts",
+			"find": ["\t\tmeta.systemPrompt = normalizedSystemPrompt;"],
+			"replace": ["\t\tmeta.systemPrompt = normalizedSystemPrompt.trim();"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-META-SENDS-CARRIER-VERBATIM]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
 		}
 	]
 }

package/scripts/mutants/acp-cortex.json

@@ -142,13 +142,13 @@
 				"\t\tawait setConfig.call(connection, { sessionId: acpSessionId, configId: \"model\", value: nativeModelId });",
 				"\t},",
 				"",
-				"\t// A connection change must invalidate a reused session (§4/§7). Flat,"
+				"\t// A connection change must invalidate a reused session (rail: Adapter contract). Flat,"
 			],
 			"replace": [
 				"\t\tawait setConfig.call(connection, { sessionId: acpSessionId, configId: \"model\", value: \"auto\" });",
 				"\t},",
 				"",
-				"\t// A connection change must invalidate a reused session (§4/§7). Flat,"
+				"\t// A connection change must invalidate a reused session (rail: Adapter contract). Flat,"
 			],
 			"gate": ["bash", "run.sh", "check-acp-cortex"],
 			"timeoutSeconds": 300,

package/scripts/mutants/acp-overlay.json

@@ -0,0 +1,17 @@
+{
+	"schemaVersion": 1,
+	"lane": "acp-overlay",
+	"mutants": [
+		{
+			"claim": "ACP-OVERLAY-UNATTENDED-BYPASS",
+			"title": "the isolated Claude overlay goes back to authoring permissions.defaultMode \"default\" — the overlay is the only settings authority the ACP child reads, so an unattended entwurf turn suspends on an interactive permission prompt nobody is there to answer, and the session stalls rather than fails",
+			"subject": "pi-extensions/lib/acp/overlay.ts",
+			"find": ["\t\t\tpermissions: { defaultMode: \"bypassPermissions\" },"],
+			"replace": ["\t\t\tpermissions: { defaultMode: \"default\" },"],
+			"gate": ["bash", "run.sh", "check-acp-overlay"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:ACP-OVERLAY-UNATTENDED-BYPASS]",
+			"signatureSource": "scripts/check-acp-overlay.ts"
+		}
+	]
+}

package/scripts/mutants/acp-prompt-lifecycle.json

@@ -0,0 +1,100 @@
+{
+	"schemaVersion": 1,
+	"lane": "acp-prompt-lifecycle",
+	"mutants": [
+		{
+			"claim": "PROMPT-STALL-NOT-KILLED",
+			"title": "an absolute wall clock re-planted on the in-flight prompt — a turn that is still working is cut for being long",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": ["\t\treturn await Promise.race([session.connection.prompt(promptArgs), lifecycle]);"],
+			"replace": [
+				"\t\treturn await Promise.race([\n\t\t\tsession.connection.prompt(promptArgs),\n\t\t\tlifecycle,\n\t\t\tnew Promise<never>((_, reject) => setTimeout(() => reject(new Error(\"prompt timed out after 100ms\")), 100)),\n\t\t]);"
+			],
+			"gate": ["bash", "run.sh", "check-acp-prompt-lifecycle"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:PROMPT-STALL-NOT-KILLED]",
+			"signatureSource": "scripts/check-acp-prompt-lifecycle.ts"
+		},
+		{
+			"claim": "ABORT-SENDS-PROTOCOL-CANCEL",
+			"title": "abort stops asking the agent to cancel its own turn — back to killing a child mid-tool instead of the protocol ending",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": ["\t\t\tsession.connection.cancel?.({ sessionId: promptArgs.sessionId });"],
+			"replace": ["\t\t\tvoid promptArgs;"],
+			"gate": ["bash", "run.sh", "check-acp-prompt-lifecycle"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:ABORT-SENDS-PROTOCOL-CANCEL]",
+			"signatureSource": "scripts/check-acp-prompt-lifecycle.ts"
+		},
+		{
+			"claim": "ABORT-ESCALATION-BOUNDED",
+			"title": "the post-abort grace ignores the bound it was given — an abort against a wedged agent waits on a clock the caller does not control",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": ["\t\tgraceTimer = setTimeout(escalateAbort, opts.graceMs);"],
+			"replace": ["\t\tgraceTimer = setTimeout(escalateAbort, 5_000);"],
+			"gate": ["bash", "run.sh", "check-acp-prompt-lifecycle"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:ABORT-ESCALATION-BOUNDED]",
+			"signatureSource": "scripts/check-acp-prompt-lifecycle.ts"
+		},
+		{
+			"claim": "CHILD-EXIT-DIAGNOSED",
+			"title": "a mid-prompt child death stops reporting HOW it ended — the operator is back to an undiagnosable connection error",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": [
+				"\tconst parts = [\n\t\texit.code !== null ? `exit code ${exit.code}` : undefined,\n\t\texit.signal ? `signal ${exit.signal}` : undefined,\n\t].filter(Boolean);\n\treturn parts.length > 0 ? parts.join(\", \") : \"no exit status\";"
+			],
+			"replace": ["\treturn \"no exit status\";"],
+			"gate": ["bash", "run.sh", "check-acp-prompt-lifecycle"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:CHILD-EXIT-DIAGNOSED]",
+			"signatureSource": "scripts/check-acp-prompt-lifecycle.ts"
+		},
+		{
+			"claim": "REUSE-CARRIES-CHILD-DIAGNOSTICS",
+			"title": "the reuse path drops the child's stderr tail again — exactly the live sonnet failure that showed only \"ACP connection closed\"",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": ["\t\t\tfinishError(err, aborted, session.stderrTail);"],
+			"replace": ["\t\t\tfinishError(err, aborted);"],
+			"gate": ["bash", "run.sh", "check-acp-prompt-lifecycle"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:REUSE-CARRIES-CHILD-DIAGNOSTICS]",
+			"signatureSource": "scripts/check-acp-prompt-lifecycle.ts"
+		},
+		{
+			"claim": "PROMPT-ERROR-NOT-TRANSIENT",
+			"title": "a prompt-phase lifecycle failure worded as a timeout — pi reclassifies it as transient and cold-replays the whole prompt",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": ["\t\t\t\"this turn has no answer\","],
+			"replace": ["\t\t\t\"the prompt timed out\","],
+			"gate": ["bash", "run.sh", "check-acp-prompt-lifecycle"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:PROMPT-ERROR-NOT-TRANSIENT]",
+			"signatureSource": "scripts/check-acp-prompt-lifecycle.ts"
+		},
+		{
+			"claim": "IDLE-DEATH-ANNOUNCED",
+			"title": "a backend session that died between turns is cleared but never announced — the next turn respawns silently and the operator never learns the session is gone",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": [
+				"\t\t\tconst priorEnd = takeUnreportedChildEnd(sessionKey);\n\t\t\tif (priorEnd) {\n\t\t\t\tpushAcpLifecycleNotice(\n\t\t\t\t\tstate,\n\t\t\t\t\t`previous ${adapter.backend} session ended between turns (${describeChildEnd(priorEnd)}) — opening a new one`,\n\t\t\t\t);\n\t\t\t}"
+			],
+			"replace": ["\t\t\ttakeUnreportedChildEnd(sessionKey);"],
+			"gate": ["bash", "run.sh", "check-acp-prompt-lifecycle"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:IDLE-DEATH-ANNOUNCED]",
+			"signatureSource": "scripts/check-acp-prompt-lifecycle.ts"
+		},
+		{
+			"claim": "RETIRED-TEARDOWN-NOT-ANNOUNCED",
+			"title": "a teardown we performed ourselves is reported as a death — every ordinary turn-scoped turn cries wolf about its own cleanup",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": ["\t} else if (!session.retiring) {"],
+			"replace": ["\t} else {"],
+			"gate": ["bash", "run.sh", "check-acp-prompt-lifecycle"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:RETIRED-TEARDOWN-NOT-ANNOUNCED]",
+			"signatureSource": "scripts/check-acp-prompt-lifecycle.ts"
+		}
+	]
+}

package/scripts/mutants/acp-stop-reason.json

@@ -0,0 +1,80 @@
+{
+	"schemaVersion": 1,
+	"lane": "acp-stop-reason",
+	"mutants": [
+		{
+			"claim": "STOP-REFUSAL-NOT-SUCCESS",
+			"title": "a model refusal reported as a finished answer — the turn has no content, yet pi seals it done/stop",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": [
+				"\t\tcase \"refusal\":\n\t\t\treturn {\n\t\t\t\tstopReason: \"error\",\n\t\t\t\trawStopReason: stopReason,\n\t\t\t\terrorMessage: \"ACP backend stopped with: refusal (the model declined to answer; the turn is incomplete)\",\n\t\t\t};"
+			],
+			"replace": ["\t\tcase \"refusal\":\n\t\t\treturn { stopReason: \"stop\", rawStopReason: stopReason };"],
+			"gate": ["bash", "run.sh", "check-acp-stop-reason"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:STOP-REFUSAL-NOT-SUCCESS]",
+			"signatureSource": "scripts/check-acp-stop-reason.ts"
+		},
+		{
+			"claim": "STOP-TURNBUDGET-NOT-SUCCESS",
+			"title": "an exhausted per-turn request budget reported as success — the answer is cut short but pi seals it done",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": [
+				"\t\tcase \"max_turn_requests\":\n\t\t\treturn {\n\t\t\t\tstopReason: \"error\",\n\t\t\t\trawStopReason: stopReason,\n\t\t\t\terrorMessage:\n\t\t\t\t\t\"ACP backend stopped with: max_turn_requests (the backend's per-turn request budget was exhausted; the turn is incomplete)\",\n\t\t\t};"
+			],
+			"replace": ["\t\tcase \"max_turn_requests\":\n\t\t\treturn { stopReason: \"stop\", rawStopReason: stopReason };"],
+			"gate": ["bash", "run.sh", "check-acp-stop-reason"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:STOP-TURNBUDGET-NOT-SUCCESS]",
+			"signatureSource": "scripts/check-acp-stop-reason.ts"
+		},
+		{
+			"claim": "STOP-UNKNOWN-NOT-SUCCESS",
+			"title": "the collapse-to-stop default returns: any reason this build has never seen becomes a clean success",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": [
+				"\t\tdefault:\n\t\t\treturn {\n\t\t\t\tstopReason: \"error\",\n\t\t\t\trawStopReason: stopReason,\n\t\t\t\terrorMessage: `ACP backend stopped with an unrecognized reason: ${stopReason}`,\n\t\t\t};"
+			],
+			"replace": ["\t\tdefault:\n\t\t\treturn { stopReason: \"stop\", rawStopReason: stopReason };"],
+			"gate": ["bash", "run.sh", "check-acp-stop-reason"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:STOP-UNKNOWN-NOT-SUCCESS]",
+			"signatureSource": "scripts/check-acp-stop-reason.ts"
+		},
+		{
+			"claim": "STOP-ABSENT-NOT-SUCCESS",
+			"title": "a prompt result carrying NO stop reason treated as a finished turn instead of an error",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": [
+				"\t\tcase undefined:\n\t\t\treturn {\n\t\t\t\tstopReason: \"error\",\n\t\t\t\terrorMessage: \"ACP backend ended the turn without a stop reason\",\n\t\t\t};"
+			],
+			"replace": ["\t\tcase undefined:\n\t\t\treturn { stopReason: \"stop\" };"],
+			"gate": ["bash", "run.sh", "check-acp-stop-reason"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:STOP-ABSENT-NOT-SUCCESS]",
+			"signatureSource": "scripts/check-acp-stop-reason.ts"
+		},
+		{
+			"claim": "STOP-RAW-PRESERVED",
+			"title": "the raw ACP reason is dropped on the way out, so no consumer can see what the backend actually said",
+			"subject": "pi-extensions/lib/acp/backend.ts",
+			"find": ["\t\tif (verdict.rawStopReason !== undefined) state.output.rawStopReason = verdict.rawStopReason;\n"],
+			"replace": [""],
+			"gate": ["bash", "run.sh", "check-acp-stop-reason"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:STOP-RAW-PRESERVED]",
+			"signatureSource": "scripts/check-acp-stop-reason.ts"
+		},
+		{
+			"claim": "STOP-PENDING-SEED",
+			"title": "the stream state seeds success: an in-flight turn already reads as a finished stop before any terminal arrives",
+			"subject": "pi-extensions/lib/acp/event-mapper.ts",
+			"find": ["\t\tstopReason: \"pending\","],
+			"replace": ["\t\tstopReason: \"stop\","],
+			"gate": ["bash", "run.sh", "check-acp-stop-reason"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:STOP-PENDING-SEED]",
+			"signatureSource": "scripts/check-acp-stop-reason.ts"
+		}
+	]
+}