peaks-loop 4.0.4 → 4.0.5

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;

package/dist/services/dispatch/post-merge.js

@@ -0,0 +1,13 @@
+export function planMergeBack(input) {
+    if (input.agentBranch.length === 0)
+        return { kind: 'missing', reason: 'agent-branch-empty' };
+    if (input.callerBranch === input.agentBranch)
+        return { kind: 'noop' };
+    if (input.conflictingFiles.length > 0)
+        return { kind: 'conflict', conflictingFiles: input.conflictingFiles };
+    const base = ['git', 'merge', '--no-ff'];
+    if (input.callerBranch === 'main' && input.commitsBehind === 0) {
+        return { kind: 'fast-forward', command: ['git', 'merge', '--ff-only', input.agentBranch] };
+    }
+    return { kind: 'no-ff', command: [...base, input.agentBranch] };
+}

package/dist/services/dispatch/service-shutdown.d.ts

@@ -0,0 +1,22 @@
+export type ServiceRegistration = {
+    readonly pid: number;
+    readonly name: string;
+    readonly url?: string;
+};
+export type ServiceKillOutcome = {
+    readonly pid: number;
+    readonly name: string;
+    readonly skipped: false;
+    readonly signal: 'SIGTERM' | 'SIGKILL' | 'taskkill';
+};
+export type ServiceKillSkipped = {
+    readonly pid: number;
+    readonly name: string;
+    readonly skipped: true;
+    readonly reason: 'not-running';
+};
+export type ServiceKillResult = ServiceKillOutcome | ServiceKillSkipped;
+export declare function killRegisteredServices(input: {
+    readonly registrations: ReadonlyArray<ServiceRegistration>;
+    readonly platform?: NodeJS.Platform;
+}): ReadonlyArray<ServiceKillResult>;

package/dist/services/dispatch/service-shutdown.js

@@ -0,0 +1,51 @@
+/**
+ * service-shutdown — best-effort kill helper for sub-agent-registered
+ * local services.
+ *
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 3). The parent session
+ * reads `.peaks/_runtime/<sid>/dispatch/<dispatchId>/service-registrations.json`
+ * (written by `peaks sub-agent shutdown register --pid <pid> --name <label>`)
+ * and calls `killRegisteredServices` BEFORE the merge-back step so a
+ * long-lived `vite dev` / mock-API / docker-proxy process started by the
+ * sub-agent does not block the merge (file lock, port collision, dirty
+ * db, etc).
+ *
+ * The helper is intentionally minimal:
+ *   - pid <= 0 or pid === process.pid → skip (`not-running`).
+ *   - win32: `taskkill /T /F /PID <pid>` (force, with subtree).
+ *   - POSIX: `kill -TERM <pid>`; on failure escalate to `kill -KILL`.
+ *   - any error → `not-running` (best-effort; the parent will retry
+ *     merge regardless).
+ *
+ * All native calls are best-effort and never throw; the orchestrator
+ * (merge-back-runner.ts) just records the array of outcomes on the
+ * dispatch record's `serviceKill` field (added in Task 7).
+ */
+import { execFileSync } from 'node:child_process';
+export function killRegisteredServices(input) {
+    const platform = input.platform ?? process.platform;
+    return input.registrations.map((reg) => {
+        if (reg.pid <= 0 || reg.pid === process.pid) {
+            return { pid: reg.pid, name: reg.name, skipped: true, reason: 'not-running' };
+        }
+        try {
+            if (platform === 'win32') {
+                execFileSync('taskkill', ['/T', '/F', '/PID', String(reg.pid)], { stdio: 'ignore' });
+                return { pid: reg.pid, name: reg.name, skipped: false, signal: 'taskkill' };
+            }
+            // POSIX: try SIGTERM via the `kill` CLI (universally available);
+            // escalate to SIGKILL on failure. The runner is best-effort.
+            try {
+                execFileSync('kill', ['-TERM', String(reg.pid)], { stdio: 'ignore' });
+            }
+            catch {
+                execFileSync('kill', ['-KILL', String(reg.pid)], { stdio: 'ignore' });
+                return { pid: reg.pid, name: reg.name, skipped: false, signal: 'SIGKILL' };
+            }
+            return { pid: reg.pid, name: reg.name, skipped: false, signal: 'SIGTERM' };
+        }
+        catch {
+            return { pid: reg.pid, name: reg.name, skipped: true, reason: 'not-running' };
+        }
+    });
+}

package/dist/services/hooks/presence-marker-detector.js

@@ -46,15 +46,23 @@ function readPresenceFile(absolutePath) {
     try {
         raw = readFileSync(absolutePath, 'utf8');
     }
-    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
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
-    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
     }
     if (parsed === null || typeof parsed !== 'object')
         return null;

package/dist/services/hooks/worktree-authorization-gate.d.ts

@@ -104,6 +104,8 @@ export type WorktreeAuthDenyCode =
 /** Slice 2026-07-29-worktree-l2-extended Part 19: container
  * lease id is set but the lease file is unreadable / malformed. */
  | 'CONTAINER_LEASE_FILE_INVALID'
+/** Host Agent/Task worktree isolation was not issued by Peaks dispatch. */
+ | 'HOST_AGENT_ISOLATION_UNMANAGED'
 /** Container lease exists but is not active (status != 'active' OR past expiresAt). */
  | 'CONTAINER_LEASE_NOT_ACTIVE'
 /** Container lease exists but its rid does not match the current peaks request. */
@@ -139,6 +141,8 @@ export type WorktreeAuthCheckInput = {
      * is active and its rid matches.
      */
     readonly containerLeaseId: string | null;
+    /** Peaks-issued provenance token required for host Agent/Task worktree isolation. */
+    readonly dispatchProvenanceToken?: string | null;
 };
 /** Stable identifier of the current "user authorization" — derived from session + tool + key args. */
 export declare function currentAuthFingerprint(input: WorktreeAuthCheckInput): string;

package/dist/services/hooks/worktree-authorization-gate.js

@@ -36,6 +36,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { deserializeLease, isLeaseActive, leaseFilePath, } from '../worktree/worktree-lease.js';
+import { readDispatchProvenance } from '../worktree/dispatch-provenance.js';
 import { containerLeaseFilePath, deserializeContainerLease, isContainerLeaseActive, } from '../container/container-lease.js';
 export const WORKTREE_AUTH_FILE = 'worktree-auth.json';
 /** Stable identifier of the current "user authorization" — derived from session + tool + key args. */
@@ -232,6 +233,27 @@ export function decideFromAuthorization(input, operation, file) {
  */
 export function evaluateWorktreeAuth(input) {
     const operation = classifyToolCall(input);
+    if (operation === 'agent-isolation-worktree') {
+        const token = input.dispatchProvenanceToken ?? '';
+        const provenance = token.length > 0
+            ? readDispatchProvenance({ projectRoot: input.projectRoot, sessionId: input.sessionId, token })
+            : null;
+        if (provenance === null ||
+            input.leaseId === null ||
+            provenance.leaseId !== input.leaseId ||
+            (input.requestId !== null && provenance.requestId !== input.requestId)) {
+            return {
+                allow: false,
+                code: 'HOST_AGENT_ISOLATION_UNMANAGED',
+                reason: 'Host Agent/Task worktree isolation lacks a matching Peaks dispatch provenance record and canonical lease.',
+                remediation: 'Route the work through Peaks sub-agent dispatch with worktree isolation. Existing leaked host worktrees must be reconciled or adopted before cleanup.'
+            };
+        }
+        const leaseDecision = decideFromLease({ ...input, requestId: provenance.requestId });
+        if (!leaseDecision.allow)
+            return leaseDecision;
+        return leaseDecision;
+    }
     if (operation === null) {
         // Pass-through (Read, Glob, etc., and any Bash that isn't worktree-mutating).
         return {