peaks-loop 4.0.3 → 4.0.5

package/dist/services/context/auto-compact-reader.js

@@ -22,7 +22,7 @@
  *   3. `ratio: 0` with `source: 'conservative-fallback'` — the
  *      orchestrator MUST NOT auto-fire compact on this signal.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { detectIdeFromEnv } from './ide-detect.js';
@@ -64,39 +64,76 @@ function readClaudeStatuslinePercent() {
             }
         }
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
+    catch (err) { // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs (e.g. broken statusline JSON)
+        return null; // only swallow IO errors
     }
     return null;
 }
 /**
- * Conservative transcript-size fallback. Walks
- * `~/.claude/projects/<hash>/<sid>.jsonl` and estimates
- * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
- * orchestrator can show "estimated from 124KB of 256KB transcript"
- * in the envelope. Tagged `'conservative-fallback'` so callers
- * know NOT to treat this as a hard gate.
+ * Recursive search for `<sessionId>.jsonl` under `projectsDir`. Used by
+ * `readClaudeTranscriptFallback` and exported via `_internal` so unit
+ * tests can drive it without monkey-patching `os.homedir` (which is
+ * non-configurable in ESM module namespaces).
+ *
+ * The Mac layout encodes the cwd as a single hash directory; on Mac
+ * Claude Code nests the transcript under that hash with an extra level
+ * of subdirectory we cannot predict ahead of time. A flat readdir misses
+ * that branch and returns null — the silent-failure mode that this fix
+ * closes.
  */
-function readClaudeTranscriptFallback(sessionId) {
-    const projectsDir = join(homedir(), '.claude', 'projects');
+function findTranscriptJsonl(projectsDir, sessionId) {
     if (!existsSync(projectsDir))
         return null;
     try {
-        const { readdirSync } = require('node:fs');
-        for (const hashDir of readdirSync(projectsDir)) {
-            const candidate = join(projectsDir, hashDir, `${sessionId}.jsonl`);
-            if (existsSync(candidate)) {
-                const bytes = statSync(candidate).size;
-                const ratio = Math.min(1, bytes / (256 * 1024));
-                return { ratio, bytes };
+        const stack = [projectsDir];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            if (dir === undefined)
+                break;
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const full = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (entry.isFile() && entry.name === `${sessionId}.jsonl`) {
+                    const bytes = statSync(full).size;
+                    return { path: full, bytes };
+                }
             }
         }
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
+    catch (err) { // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs
+        return null; // only swallow IO errors
     }
     return null;
 }
+/**
+ * Conservative transcript-size fallback. Recursively searches
+ * `~/.claude/projects/<hash>/<sid-or-nested>.jsonl` (Mac may nest
+ *  the jsonl under an
+ * extra directory we cannot predict ahead of time) and estimates
+ * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
+ * orchestrator can show "estimated from 124KB of 256KB transcript"
+ * in the envelope. Tagged `'transcript-estimate'` (v2.14.0) so callers
+ * know it is a real signal, NOT a hard gate.
+ */
+function readClaudeTranscriptFallback(sessionId) {
+    const projectsDir = join(homedir(), '.claude', 'projects');
+    const hit = findTranscriptJsonl(projectsDir, sessionId);
+    if (hit === null)
+        return null;
+    const ratio = Math.min(1, hit.bytes / (256 * 1024));
+    return { ratio, bytes: hit.bytes };
+}
 /**
  * Probe the current AI CLI's context-fill ratio. Adapter-driven:
  * looks up the registered `IdeAdapter.compact` profile via
@@ -121,6 +158,24 @@ export function readContextPercent(input) {
     // through `unknown` to IdeId's wider 8-element set.
     const ideId = (detected === 'unknown' ? 'claude-code' : detected);
     const adapter = getAdapter(ideId);
+    // P0 user-overridden takes priority over env / statusline / transcript.
+    // Mac escape hatch: when the CLI/helper passes `--prompt-size <bytes>`,
+    // honor that number directly. Do NOT read env, statusline, or transcript
+    // — user intent always wins. Negative / non-finite values are ignored
+    // here (CLI layer validates >= 0); they fall through to the chain below.
+    if (input.promptSizeBytes !== undefined &&
+        Number.isFinite(input.promptSizeBytes) &&
+        input.promptSizeBytes >= 0) {
+        const ratio = Math.min(1, input.promptSizeBytes / capacityBytes);
+        return {
+            ratio,
+            source: 'user-overridden',
+            rawBytes: input.promptSizeBytes,
+            capacityBytes,
+            ide: ideId,
+            capturedAt
+        };
+    }
     // Primary: read the adapter-declared env-var (no hard-coded IDE names).
     if (adapter.compact) {
         const primary = readEnvPercent(env, adapter.compact.envVarForContextPercent);
@@ -147,7 +202,7 @@ export function readContextPercent(input) {
         if (fallback !== null) {
             return {
                 ratio: fallback.ratio,
-                source: 'conservative-fallback',
+                source: 'transcript-estimate',
                 rawBytes: fallback.bytes,
                 capacityBytes,
                 ide: ideId,
@@ -161,4 +216,4 @@ export function readContextPercent(input) {
     return { ratio: 0, source: 'conservative-fallback', capacityBytes, ide: ideId, capturedAt };
 }
 /** Re-export the env-var probe for unit tests. */
-export const _internal = { readEnvPercent, readClaudeStatuslinePercent, readClaudeTranscriptFallback };
+export const _internal = { readEnvPercent, readClaudeStatuslinePercent, readClaudeTranscriptFallback, findTranscriptJsonl };

package/dist/services/context/auto-compact-types.d.ts

@@ -152,10 +152,18 @@ export interface ContextPercentProbe {
     readonly ratio: number;
     /**
      * Adapter-driven source tag. Fixed values:
+     *   - `user-overridden`         (v2.14.0 rid-002: explicit `--prompt-size
+     *                                <bytes>` from the CLI / hook wrapper —
+     *                                takes priority P0 over EVERY other source.
+     *                                Mac escape hatch.)
      *   - `${ideId}-env`            (e.g. `claude-code-env`)
      *   - `statusline-poll`         (Claude Code MVP fallback)
-     *   - `conservative-fallback`   (transcript size estimate OR
-     *                                no signal available — caller
+     *   - `transcript-estimate`     (v2.14.0 Mac-aware: recursive
+     *                                readdir under ~/.claude/projects/
+     *                                finds <sid>.jsonl and reports
+     *                                bytes/256K; a real signal, NOT
+     *                                a hard gate)
+     *   - `conservative-fallback`   (no signal available — caller
      *                                MUST NOT treat as hard gate)
      * Future IDEs may add per-ide sources; the type accepts any
      * string to keep the schema forward-compatible.

package/dist/services/context/build-dispatch-system-prompt.d.ts

@@ -52,6 +52,32 @@ export interface DispatchPromptInput {
  * --ttl <5m>` (already shipped). Update the prose once `spawn` lands.
  */
 export declare const L1_WORKTREE_GOVERNANCE_BLOCK = "## Superpowers chain refusal (L1 worktree governance \u2014 locked 2026-07-29)\n\nYou MUST NOT follow the superpowers chain for worktree decisions:\n\n- superpowers:brainstorming \u2192 superpowers:writing-plans \u2192\n  superpowers:subagent-driven-development \u2192 superpowers:using-git-worktrees\n\nThis chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.md line 96). It bypasses peaks-loop's L2 hook gate and L3 IDE `permissions.deny`. Even when L3 denies the terminal Skill, the chain has already taught you to use raw `git worktree add`, so L3 is not sufficient.\n\nFor worktree operations, use ONLY:\n\n- `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)\n- until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`\n\nThe superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`) are authoritative.\n\nIf the upstream superpowers chain suggests raw `git worktree add`:\n\n1. STOP\n2. Re-author the plan as a peaks-rd artifact\n3. Continue with `peaks worktree spawn` (or the auth-grant fallback)\n";
+/**
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 8): the dispatch
+ * system prompt gains three lifecycle rules. The sub-agent must:
+ *
+ *   1. Register any long-lived local process it starts (vite dev,
+ *      mock API, docker proxy, etc.) with
+ *      `peaks sub-agent shutdown register --pid <pid> --name <label>`
+ *      before it exits, so the parent session can best-effort-kill
+ *      the process before merge-back (Task 3 + Task 6).
+ *
+ *   2. NOT run E2E. The parent session runs Playwright verification
+ *      once after merge-back (Task 10). Sub-agent E2E runs are
+ *      duplicates that the parent's single E2E pass will catch.
+ *
+ *   3. NOT call `git merge / pull / rebase` or
+ *      `peaks worktree release`. The parent session owns the
+ *      merge-back step (Task 9). Sub-agent merges double-write the
+ *      index, race the worktree release, and can corrupt the
+ *      caller's working branch.
+ *
+ * These rules are appended to the system prompt on top of the L1
+ * worktree governance block so the sub-agent sees them last (i.e.
+ * most-recently-read), which is the strongest prompt position in
+ * transformer attention.
+ */
+export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 2026-08-01)\n\n- If you start a long-lived local service (vite dev, mock API, docker container, etc.), register it with `peaks sub-agent shutdown register --pid <pid> --name <label>` before you exit. The parent session will best-effort-kill it before merge-back.\n- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10). Your E2E work is duplicate effort.\n- Do NOT call `git merge`, `git pull`, `git rebase`, or `peaks worktree release`. The parent session owns the merge-back step.\n";
 /**
  * Compose the system-prompt body that the dispatch site prepends to
  * `formatTestToolDetection()\n\n`.

package/dist/services/context/build-dispatch-system-prompt.js

@@ -42,6 +42,37 @@ If the upstream superpowers chain suggests raw \`git worktree add\`:
 2. Re-author the plan as a peaks-rd artifact
 3. Continue with \`peaks worktree spawn\` (or the auth-grant fallback)
 `;
+/**
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 8): the dispatch
+ * system prompt gains three lifecycle rules. The sub-agent must:
+ *
+ *   1. Register any long-lived local process it starts (vite dev,
+ *      mock API, docker proxy, etc.) with
+ *      `peaks sub-agent shutdown register --pid <pid> --name <label>`
+ *      before it exits, so the parent session can best-effort-kill
+ *      the process before merge-back (Task 3 + Task 6).
+ *
+ *   2. NOT run E2E. The parent session runs Playwright verification
+ *      once after merge-back (Task 10). Sub-agent E2E runs are
+ *      duplicates that the parent's single E2E pass will catch.
+ *
+ *   3. NOT call `git merge / pull / rebase` or
+ *      `peaks worktree release`. The parent session owns the
+ *      merge-back step (Task 9). Sub-agent merges double-write the
+ *      index, race the worktree release, and can corrupt the
+ *      caller's working branch.
+ *
+ * These rules are appended to the system prompt on top of the L1
+ * worktree governance block so the sub-agent sees them last (i.e.
+ * most-recently-read), which is the strongest prompt position in
+ * transformer attention.
+ */
+export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
+
+- If you start a long-lived local service (vite dev, mock API, docker container, etc.), register it with \`peaks sub-agent shutdown register --pid <pid> --name <label>\` before you exit. The parent session will best-effort-kill it before merge-back.
+- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10). Your E2E work is duplicate effort.
+- Do NOT call \`git merge\`, \`git pull\`, \`git rebase\`, or \`peaks worktree release\`. The parent session owns the merge-back step.
+`;
 /**
  * Compose the system-prompt body that the dispatch site prepends to
  * `formatTestToolDetection()\n\n`.
@@ -66,9 +97,9 @@ export function buildDispatchSystemPrompt(input) {
     const { taskBody, memoryBlock, contextProbe } = input;
     const contextBlock = renderContextBlock(contextProbe ?? null);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${contextBlock}${memoryBlock.block}\n## Task\n${taskBody}\n`;
+        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${contextBlock}${memoryBlock.block}\n## Task\n${taskBody}\n${LIFECYCLE_RULES}`;
     }
-    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${contextBlock}${taskBody}`;
+    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${contextBlock}${taskBody}\n${LIFECYCLE_RULES}`;
 }
 /**
  * Slice 2026-07-29-context-evaluation-accuracy: emit a

package/dist/services/dispatch/conflict-replay.d.ts

@@ -0,0 +1,32 @@
+/**
+ * conflict-replay — pure envelope builder for the auto re-dispatch path.
+ *
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 5). When the parent
+ * session's merge-back attempt conflicts (see planMergeBack), the
+ * merge-back-runner (Task 9) calls `buildConflictReplay` to compose
+ * the envelope the parent passes back into the sub-agent dispatch
+ * site. The envelope has three sections:
+ *
+ *   1. callerBranch: <branch>
+ *   2. Original prompt (verbatim)
+ *   3. Prior merge transcript (one line per attempt)
+ *   4. Conflict diff (wrapped in a fenced ```diff block)
+ *
+ * Plus a stable instruction list the re-dispatched agent receives in
+ * addition to its task system prompt. The instruction set forbids
+ * new functionality and tells the agent to re-run the dispatch and
+ * report the new conflict state — the parent will retry the merge.
+ *
+ * The builder is pure: no fs, no network, no child_process.
+ */
+export type ConflictReplayInput = {
+    readonly originalPrompt: string;
+    readonly mergeAttemptTranscript: ReadonlyArray<string>;
+    readonly conflictDiff: string;
+    readonly callerBranch: string;
+};
+export type ConflictReplayOutput = {
+    readonly prompt: string;
+    readonly instructions: ReadonlyArray<string>;
+};
+export declare function buildConflictReplay(input: ConflictReplayInput): ConflictReplayOutput;

package/dist/services/dispatch/conflict-replay.js

@@ -0,0 +1,44 @@
+/**
+ * conflict-replay — pure envelope builder for the auto re-dispatch path.
+ *
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 5). When the parent
+ * session's merge-back attempt conflicts (see planMergeBack), the
+ * merge-back-runner (Task 9) calls `buildConflictReplay` to compose
+ * the envelope the parent passes back into the sub-agent dispatch
+ * site. The envelope has three sections:
+ *
+ *   1. callerBranch: <branch>
+ *   2. Original prompt (verbatim)
+ *   3. Prior merge transcript (one line per attempt)
+ *   4. Conflict diff (wrapped in a fenced ```diff block)
+ *
+ * Plus a stable instruction list the re-dispatched agent receives in
+ * addition to its task system prompt. The instruction set forbids
+ * new functionality and tells the agent to re-run the dispatch and
+ * report the new conflict state — the parent will retry the merge.
+ *
+ * The builder is pure: no fs, no network, no child_process.
+ */
+const INSTRUCTIONS = [
+    'A previous merge into the caller branch conflicted. Resolve the conflict preserving the intent of both your prior work and the caller branch.',
+    'Do NOT introduce new functionality or refactor outside the conflict.',
+    'Re-run the dispatch and report the new conflict state. The parent will retry the merge.',
+];
+export function buildConflictReplay(input) {
+    const prompt = [
+        '## Conflict replay',
+        `callerBranch: ${input.callerBranch}`,
+        '',
+        '### Original prompt',
+        input.originalPrompt,
+        '',
+        '### Prior merge transcript',
+        ...input.mergeAttemptTranscript.map((l) => `  ${l}`),
+        '',
+        '### Conflict diff',
+        '```diff',
+        input.conflictDiff,
+        '```',
+    ].join('\n');
+    return { prompt, instructions: INSTRUCTIONS };
+}

package/dist/services/dispatch/dispatch-record-writer.d.ts

@@ -43,7 +43,7 @@ export interface DispatchRecord {
      * truth for "this record is v3.1-form"; readers check
      * `version === '3.1'` for forward-compatible dispatching.
      */
-    readonly version: '3.1';
+    readonly version: '3.2';
     readonly createdAt: string;
     readonly completedAt: string | null;
     readonly outcome: DispatchOutcome;
@@ -90,6 +90,36 @@ export interface DispatchRecord {
      * cross-referencing the metrics stream.
      */
     readonly isolationStartedAt: string | null;
+    /**
+     * Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.2 schema
+     * bump. One entry per pid the parent best-effort-killed during
+     * the service-shutdown phase of the merge-back pipeline (see
+     * src/services/dispatch/service-shutdown.ts). Empty array when
+     * the sub-agent did not register any services. The shape is the
+     * union of ServiceKillOutcome (skipped=false) and
+     * ServiceKillSkipped (skipped=true) — kept as a plain object
+     * here so the on-disk schema does not lock onto the helper's
+     * narrower union. The reader (merge-back-runner.ts) interprets
+     * each entry based on the `skipped` field.
+     */
+    readonly serviceKill: ReadonlyArray<{
+        readonly pid: number;
+        readonly name: string;
+        readonly signal: string;
+        readonly exitCode: number | null;
+        readonly skipped?: boolean;
+        readonly reason?: string;
+    }>;
+    /**
+     * Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.2 schema
+     * bump. Counts how many merge attempts the parent session has
+     * made against this dispatch's branch. The conflict-replay
+     * orchestrator bumps this on each retry (bounded to ONE re-dispatch
+     * per merge attempt; multi-conflict cases escalate). Persisted so
+     * the dashboard can render the retry count without replaying the
+     * merge transcript.
+     */
+    readonly mergeBackAttempts: number;
 }
 /** Input for the initial write. */
 export type WriteInitialDispatchInput = {

package/dist/services/dispatch/dispatch-record-writer.js

@@ -44,7 +44,7 @@ export function writeInitialDispatchRecord(input) {
     const path = dispatchRecordPath(projectRoot, sessionId, requestId, now());
     const safePath = assertSafeDispatchRecordPath(path, projectRoot);
     const record = {
-        version: '3.1',
+        version: '3.2',
         createdAt: now().toISOString(),
         completedAt: null,
         outcome: 'no-execution',
@@ -86,7 +86,12 @@ export function writeInitialDispatchRecord(input) {
         // handle is acceptable for the dashboard.
         isolationStartedAt: typeof input.isolationStartedAt === 'string' && input.isolationStartedAt.length > 0
             ? input.isolationStartedAt
-            : null
+            : null,
+        // Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.2 fields.
+        // New records start with empty serviceKill and zero attempts;
+        // the merge-back-runner (Task 9) populates them in place.
+        serviceKill: [],
+        mergeBackAttempts: 0
     };
     writeAtomic(safePath, record);
     // Slice 2026-06-23-audit-4th #A4: register the path in the
@@ -553,9 +558,9 @@ function upgradeRecord(parsed) {
     // with a schema we have not implemented). v1 records
     // (pre-audit-trail) must be regenerated.
     const rawVersion = obj.version;
-    if (rawVersion !== '3.1' && rawVersion !== 3 && rawVersion !== 2 && rawVersion !== 1) {
-        throw new Error(`Dispatch record version mismatch: expected '3.1', 3, 2, or 1, got ${JSON.stringify(rawVersion)}. ` +
-            'The v1 → v3.1 migration is in-file; records from much older or newer builds must be regenerated.');
+    if (rawVersion !== '3.2' && rawVersion !== '3.1' && rawVersion !== 3 && rawVersion !== 2 && rawVersion !== 1) {
+        throw new Error(`Dispatch record version mismatch: expected '3.2', '3.1', 3, 2, or 1, got ${JSON.stringify(rawVersion)}. ` +
+            'The v1 → v3.2 migration is in-file; records from much older or newer builds must be regenerated.');
     }
     const role = stringField(obj, 'role');
     const requestId = stringField(obj, 'requestId');
@@ -597,7 +602,7 @@ function upgradeRecord(parsed) {
         ? obj.batchId
         : 'legacy-batch';
     return {
-        version: '3.1',
+        version: '3.2',
         createdAt,
         completedAt,
         outcome,
@@ -632,7 +637,22 @@ function upgradeRecord(parsed) {
         // to `null`. v3.1 readers can treat the field as opt-in.
         isolationStartedAt: typeof obj.isolationStartedAt === 'string' && obj.isolationStartedAt.length > 0
             ? obj.isolationStartedAt
-            : null
+            : null,
+        // Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.1 → v3.2
+        // migration. Legacy v3.1 records have no `serviceKill` or
+        // `mergeBackAttempts` fields. Default to [] and 0 so the
+        // merge-back-runner (Task 9) can read either schema on disk.
+        serviceKill: Array.isArray(obj.serviceKill)
+            ? (obj.serviceKill.filter((e) => {
+                if (typeof e !== 'object' || e === null)
+                    return false;
+                const o = e;
+                return typeof o.pid === 'number' && typeof o.name === 'string' && typeof o.signal === 'string' && (o.exitCode === null || typeof o.exitCode === 'number');
+            }))
+            : [],
+        mergeBackAttempts: typeof obj.mergeBackAttempts === 'number' && Number.isFinite(obj.mergeBackAttempts) && obj.mergeBackAttempts >= 0
+            ? Math.floor(obj.mergeBackAttempts)
+            : 0
     };
 }
 function isObject(v) {

package/dist/services/dispatch/e2e-fixtures.d.ts

@@ -0,0 +1,18 @@
+export type E2EFixture = {
+    readonly name: string;
+    readonly file: string;
+    readonly url: string;
+    readonly matchers: ReadonlyArray<string>;
+};
+export type E2EPlan = {
+    readonly kind: 'disabled';
+    readonly reason: string;
+} | {
+    readonly kind: 'empty';
+} | {
+    readonly kind: 'fixtures';
+    readonly fixtures: ReadonlyArray<E2EFixture>;
+};
+export declare function readE2EPlan(input: {
+    readonly dir: string;
+}): E2EPlan;

package/dist/services/dispatch/e2e-fixtures.js

@@ -0,0 +1,72 @@
+/**
+ * e2e-fixtures — pure reader for `qa/e2e/<slice>/<scenario>/*.md`.
+ *
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 4). The parent session
+ * calls `peaks e2e verify --slice <rid>` after the merge-back step. The
+ * CLI delegates to `runE2EVerify` (Task 10), which uses this reader to
+ * enumerate the fixtures for the slice. The reader returns one of
+ * three plans:
+ *
+ *   - { kind: 'disabled', reason }   when `qa/e2e/<slice>/disabled`
+ *                                     exists (the user has opted out)
+ *   - { kind: 'empty' }              when the slice has no fixtures
+ *   - { kind: 'fixtures', fixtures } when at least one *.md exists
+ *
+ * Each fixture is parsed for two fields:
+ *   - `url: <absolute URL>`           (mandatory line)
+ *   - `matchers: [...]`               (free-form lines below)
+ *
+ * The reader is intentionally simple: it does not validate the URL
+ * shape, the matcher grammar, or any browser-level concern. Those
+ * concerns belong to the Playwright runner (out of scope here).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+function readMarkdownFixture(file) {
+    const raw = readFileSync(file, 'utf8');
+    let url = '';
+    const matchers = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const urlMatch = /^url:\s*(\S.*)$/.exec(line);
+        if (urlMatch)
+            url = urlMatch[1] ?? '';
+        const matcherMatch = /^matchers:\s*(.*)$/.exec(line);
+        if (matcherMatch) {
+            const inline = (matcherMatch[1] ?? '').trim();
+            if (inline.length > 0)
+                matchers.push(inline);
+        }
+        const listMatch = /^\s*-\s*['"]?(.*?)['"]?\s*$/.exec(line);
+        if (listMatch && !/^matchers:\s*$/.test(line)) {
+            matchers.push((listMatch[1] ?? '').trim());
+        }
+    }
+    return { url, matchers };
+}
+export function readE2EPlan(input) {
+    if (!existsSync(input.dir))
+        return { kind: 'empty' };
+    if (existsSync(join(input.dir, 'disabled'))) {
+        return { kind: 'disabled', reason: 'disabled-file-present' };
+    }
+    const fixtures = [];
+    for (const scenario of readdirSync(input.dir)) {
+        const scenarioDir = join(input.dir, scenario);
+        if (!statSync(scenarioDir).isDirectory())
+            continue;
+        for (const file of readdirSync(scenarioDir)) {
+            if (!file.endsWith('.md'))
+                continue;
+            const parsed = readMarkdownFixture(join(scenarioDir, file));
+            if (parsed === null)
+                continue;
+            fixtures.push({
+                name: scenario,
+                file: join(scenarioDir, file),
+                url: parsed.url,
+                matchers: parsed.matchers,
+            });
+        }
+    }
+    return fixtures.length === 0 ? { kind: 'empty' } : { kind: 'fixtures', fixtures };
+}

package/dist/services/dispatch/merge-back-runner.d.ts

@@ -0,0 +1,18 @@
+import { type ServiceKillResult } from './service-shutdown.js';
+import { type ConflictReplayOutput } from './conflict-replay.js';
+export type RunMergeBackInput = {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly dispatchId: string;
+    readonly callerBranch: string;
+    readonly agentBranch: string;
+    readonly onConflict: (replay: ConflictReplayOutput) => Promise<{
+        readonly ok: boolean;
+    }>;
+};
+export type RunMergeBackResult = {
+    readonly kind: 'merged' | 'noop' | 'replay-exhausted' | 'replay-still-conflict';
+    readonly attempts: number;
+    readonly serviceKills: ReadonlyArray<ServiceKillResult>;
+};
+export declare function runMergeBack(input: RunMergeBackInput): Promise<RunMergeBackResult>;

package/dist/services/dispatch/merge-back-runner.js

@@ -0,0 +1,83 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { planMergeBack } from './post-merge.js';
+import { killRegisteredServices } from './service-shutdown.js';
+import { buildConflictReplay } from './conflict-replay.js';
+const REGISTRATIONS_FILE = 'service-registrations.json';
+function registrationsFile(input) {
+    return join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'dispatch', input.dispatchId, REGISTRATIONS_FILE);
+}
+function readRegistrations(input) {
+    const f = registrationsFile(input);
+    if (!existsSync(f))
+        return [];
+    try {
+        return JSON.parse(readFileSync(f, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+function captureConflictDiff(input) {
+    try {
+        return execFileSync('git', ['diff', '--merge', '--no-color'], { cwd: input.projectRoot, encoding: 'utf8' });
+    }
+    catch {
+        return '';
+    }
+}
+function captureTranscript(input) {
+    try {
+        return execFileSync('git', ['merge', '--no-edit', '--no-ff', input.agentBranch], { cwd: input.projectRoot, encoding: 'utf8' }).split('\n');
+    }
+    catch {
+        return ['git merge --no-edit --no-ff ' + input.agentBranch];
+    }
+}
+export async function runMergeBack(input) {
+    const kills = killRegisteredServices({ registrations: readRegistrations(input) });
+    const originalPrompt = process.env.PEAKS_DISPATCH_PROMPT ?? '';
+    let attempts = 0;
+    while (attempts < 2) {
+        attempts += 1;
+        const plan = planMergeBack({
+            callerBranch: input.callerBranch,
+            agentBranch: input.agentBranch,
+            commitsBehind: 0,
+            conflictingFiles: [],
+        });
+        if (plan.kind === 'noop')
+            return { kind: 'noop', attempts, serviceKills: kills };
+        if (plan.kind === 'missing')
+            return { kind: 'replay-exhausted', attempts, serviceKills: kills };
+        if (plan.kind === 'conflict') {
+            const conflictDiff = captureConflictDiff(input);
+            const replay = buildConflictReplay({ originalPrompt, mergeAttemptTranscript: [], conflictDiff, callerBranch: input.callerBranch });
+            const replayResult = await input.onConflict(replay);
+            if (!replayResult.ok) {
+                return { kind: attempts >= 2 ? 'replay-exhausted' : 'replay-still-conflict', attempts, serviceKills: kills };
+            }
+            continue;
+        }
+        try {
+            execFileSync('git', ['checkout', input.callerBranch], { cwd: input.projectRoot, stdio: 'ignore' });
+            execFileSync(plan.command[0], plan.command.slice(1), { cwd: input.projectRoot, stdio: 'ignore' });
+            return { kind: 'merged', attempts, serviceKills: kills };
+        }
+        catch (error) {
+            const transcript = captureTranscript(input);
+            const conflictDiff = captureConflictDiff(input);
+            const replay = buildConflictReplay({ originalPrompt, mergeAttemptTranscript: transcript, conflictDiff, callerBranch: input.callerBranch });
+            const replayResult = await input.onConflict(replay);
+            try {
+                execFileSync('git', ['merge', '--abort'], { cwd: input.projectRoot, stdio: 'ignore' });
+            }
+            catch { /* ignore */ }
+            if (!replayResult.ok) {
+                return { kind: attempts >= 2 ? 'replay-exhausted' : 'replay-still-conflict', attempts, serviceKills: kills };
+            }
+        }
+    }
+    return { kind: 'replay-exhausted', attempts, serviceKills: kills };
+}

package/dist/services/dispatch/post-merge.d.ts

@@ -0,0 +1,21 @@
+export type MergePlan = {
+    readonly kind: 'fast-forward';
+    readonly command: ReadonlyArray<string>;
+} | {
+    readonly kind: 'no-ff';
+    readonly command: ReadonlyArray<string>;
+} | {
+    readonly kind: 'conflict';
+    readonly conflictingFiles: ReadonlyArray<string>;
+} | {
+    readonly kind: 'noop';
+} | {
+    readonly kind: 'missing';
+    readonly reason: string;
+};
+export declare function planMergeBack(input: {
+    readonly callerBranch: string;
+    readonly agentBranch: string;
+    readonly commitsBehind: number;
+    readonly conflictingFiles: ReadonlyArray<string>;
+}): MergePlan;