peaks-loop 4.0.29 → 4.0.30

package/dist/cli/commands/worktree-lease-commands.js

@@ -0,0 +1,500 @@
+/**
+ * `peaks worktree <spawn|release|renew|list|gc|lease-status>` — lease
+ * lifecycle sub-commands.
+ *
+ * Extracted from `worktree-auth-commands.ts` to keep that file under the
+ * 800 LOC cap (mechanical verbatim move). These commands own the lease
+ * lifecycle: spawn writes a lease + runs `git worktree add`; release runs
+ * `git worktree remove` + transitions the lease to 'released'; renew /
+ * list / gc / lease-status read and mutate the same on-disk lease store.
+ * They coexist with `peaks worktree auth grant|revoke|status` (the L2 hook
+ * gate surface) on the shared `peaks worktree` parent command.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { emitLeaseEvent } from '../../services/observability/observability-service.js';
+import { deserializeLease, finalizeLease, generateLeaseId, isLeaseActive, isLeaseGcEligible, leaseFilePath, leaseStoreDir, listLeasesSync, markExpired, markGc, markReleased, renewLease, ttlForRole, worktreePath, } from '../../services/worktree/worktree-lease.js';
+import { execSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync as readFileSyncNode, statSync } from 'node:fs';
+export function resolveSessionId(options, projectRoot) {
+    if (typeof options.session === 'string' && options.session.length > 0)
+        return options.session;
+    // Reuse the same precedence as the rest of peaks: explicit --session > PEAKS_SESSION_ID > active session.json
+    return process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+}
+export function resolveProjectRoot(options) {
+    return options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+}
+export function registerWorktreeLeaseCommands(auth, io) {
+    // Slice 2026-07-29-worktree-l2-extended Part 1 — `peaks worktree spawn`
+    // and `peaks worktree release`. These commands own the lease lifecycle:
+    // spawn writes a lease + runs `git worktree add`; release runs `git
+    // worktree remove` + transitions the lease to 'released'. The remaining
+    // CLI surface (renew / list / gc / status) ships in Part 2 along with
+    // the hook integration that consults the lease.
+    //
+    // Coexistence with `peaks worktree auth`: this slice does NOT delete
+    // `peaks worktree auth grant|revoke|status` — those are the L2 hook
+    // gate's existing surface and remain valid for sub-agents that have
+    // NOT adopted the lease contract yet. New code uses lease; old code
+    // uses grant; both live on the `peaks worktree` parent command.
+    function resolveTtlMs(raw, role) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            return ttlForRole(role);
+        const parsed = Number(raw);
+        if (!Number.isFinite(parsed) || parsed <= 0)
+            return ttlForRole(role);
+        return parsed;
+    }
+    function deriveBranch(rid) {
+        // Branch names must be safe for git ref-format. Strip leading
+        // `rid-` if present and replace any non-safe chars with `-`.
+        return rid.replace(/[^A-Za-z0-9._/-]/g, '-').slice(0, 80);
+    }
+    addJsonOption(auth
+        .command('spawn')
+        .description(`Spawn a worktree under .peaks/_runtime/<sid>/worktrees/<leaseId>/ with a managed lease. ` +
+        `The lease is the source of truth for the L2 hook gate (Part 2 of this slice); ` +
+        `until the hook integration ships, sub-agents may still invoke raw \`git worktree add\` ` +
+        `with a current \`peaks worktree auth grant\` token. Default TTL is role-aware ` +
+        `(rd=30m / qa=15m / ui=1h); pass --ttl <ms> to override.`)
+        .requiredOption('--rid <rid>', 'peaks request id the lease is associated with')
+        .requiredOption('--role <role>', 'sub-agent role (rd | qa | ui | sc | prd | general-purpose)')
+        .requiredOption('--purpose <text>', 'why this worktree was spawned (audit log)')
+        .option('--ttl <ms>', `time-to-live in ms (default role-aware; override with positive number)`)
+        .option('--branch <name>', 'git branch name (default: derived from rid)')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        const projectRoot = resolveProjectRoot(options);
+        const sessionId = resolveSessionId(options, projectRoot);
+        try {
+            const leaseId = generateLeaseId();
+            const now = Date.now();
+            const ttlMs = resolveTtlMs(options.ttl, options.role);
+            const branch = options.branch ?? deriveBranch(options.rid);
+            const wtPath = worktreePath(joinPathSession(projectRoot, sessionId), leaseId);
+            const lease = finalizeLease({
+                leaseId,
+                rid: options.rid,
+                role: options.role,
+                path: wtPath,
+                branch,
+                createdAt: now,
+                expiresAt: now + ttlMs,
+                purpose: options.purpose
+            });
+            // Run `git worktree add` from the project root. The PreToolUse hook
+            // (Part 2 of this slice) will consult the lease file we just wrote
+            // and authorize this very `git worktree add`; for Part 1 we still
+            // require a current `peaks worktree auth grant` token to remain
+            // consistent with the slice-027 hard gate contract.
+            execSync(`git worktree add "${wtPath}" -b "${branch}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+            atomicWriteJson(leaseFilePath(joinPathSession(projectRoot, sessionId), leaseId), lease);
+            // Part 4.A: emit spawn metric (fire-and-forget; never blocks).
+            emitLeaseEvent({
+                sessionId,
+                projectRoot,
+                kind: 'spawn',
+                leaseId,
+                rid: options.rid,
+                role: options.role
+            });
+            printResult(io, ok('worktree.spawn', {
+                lease,
+                sessionId,
+                projectRoot,
+                ttlMs,
+                nextActions: [
+                    `Worktree path: ${wtPath}`,
+                    `Branch: ${branch}`,
+                    `Lease expires at: ${new Date(lease.expiresAt).toISOString()}`,
+                    'Run `peaks worktree release --lease-id <leaseId>` when done',
+                    'Hook integration (lease-aware gate) ships in Part 2'
+                ]
+            }, [], []), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('worktree.spawn', 'SPAWN_FAILED', getErrorMessage(error), { rid: options.rid, role: options.role, sessionId }, [
+                'Verify `git worktree add` succeeded (output above).',
+                'If the lease file was NOT written, retry; the lease directory is .peaks/_runtime/<sid>/worktree-leases/.',
+                'For an existing branch, pass --branch <name> explicitly (the spawn refuses to overwrite an active branch).'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(auth
+        .command('release')
+        .description('Transition a lease to released and run `git worktree remove`. Idempotent on already-released leases.')
+        .requiredOption('--lease-id <id>', 'lease id returned by `peaks worktree spawn`')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        const projectRoot = resolveProjectRoot(options);
+        const sessionId = resolveSessionId(options, projectRoot);
+        try {
+            const file = leaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+            let lease;
+            try {
+                if (!existsSync(file)) {
+                    printResult(io, fail('worktree.release', 'LEASE_NOT_FOUND', `no lease on disk at ${file}`, { leaseId: options.leaseId, file }, [
+                        'Run `peaks worktree list` to inspect active leases.',
+                        'For a never-spawned lease, this is a no-op — no further action needed.'
+                    ]), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                const raw = readFileSyncNode(file, 'utf8');
+                lease = deserializeLease(raw);
+            }
+            catch (error) {
+                printResult(io, fail('worktree.release', 'LEASE_FILE_INVALID', getErrorMessage(error), { leaseId: options.leaseId, file }, [
+                    'Delete the malformed lease file manually and re-issue spawn.',
+                    'For security, release never fails open on a malformed lease.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (lease.status === 'released') {
+                // Idempotent: already released, nothing to do.
+                printResult(io, ok('worktree.release', { lease, sessionId, projectRoot, alreadyReleased: true }, [], [`Lease ${lease.leaseId} already released; nothing to do.`]), options.json);
+                return;
+            }
+            // Run `git worktree remove` from the project root. If the path is
+            // missing on disk (e.g. manually pruned), this fails; we still
+            // update the lease state so the L2 hook (Part 2) treats it as
+            // released.
+            let gitWorktreeRemoveFailed = false;
+            try {
+                execSync(`git worktree remove --force "${lease.path}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+            }
+            catch {
+                gitWorktreeRemoveFailed = true;
+            }
+            const released = markReleased(lease);
+            atomicWriteJson(file, released);
+            // Part 4.A: emit release metric (manual path; auto-release is
+            // recorded in dispatch-record-writer's tryAutoReleaseLease).
+            emitLeaseEvent({
+                sessionId,
+                projectRoot,
+                kind: 'release',
+                leaseId: released.leaseId,
+                rid: released.rid,
+                role: released.role
+            });
+            printResult(io, ok('worktree.release', { lease: released, sessionId, projectRoot, gitWorktreeRemoveFailed }, gitWorktreeRemoveFailed ? ['git worktree remove failed (likely the path was already pruned); lease marked released.'] : [], [
+                `Lease ${lease.leaseId} marked released.`,
+                gitWorktreeRemoveFailed
+                    ? 'Manual `git worktree prune` may be needed.'
+                    : `Worktree ${lease.path} removed.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('worktree.release', 'RELEASE_FAILED', getErrorMessage(error), { leaseId: options.leaseId, sessionId }, [
+                'Verify the lease id and re-run.',
+                'If the lease was never spawned, no-op.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(auth
+        .command('renew')
+        .description('Extend an active lease\'s `expiresAt` and persist it. Idempotent for already-active leases. ' +
+        'Default TTL uses `DEFAULT_TTL_BY_ROLE[<lease.role>]`; pass --ttl <ms> to override.')
+        .requiredOption('--lease-id <id>', 'lease id returned by `peaks worktree spawn`')
+        .option('--ttl <ms>', 'time-to-live in ms from now (default: role-default)')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        const projectRoot = resolveProjectRoot(options);
+        const sessionId = resolveSessionId(options, projectRoot);
+        try {
+            const file = leaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+            if (!existsSync(file)) {
+                printResult(io, fail('worktree.renew', 'LEASE_NOT_FOUND', `no lease on disk at ${file}`, { leaseId: options.leaseId, file }, [
+                    'Run `peaks worktree list` to inspect active leases.',
+                    'For a never-spawned lease, this is a no-op.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            let lease;
+            try {
+                lease = deserializeLease(readFileSyncNode(file, 'utf8'));
+            }
+            catch (err) {
+                printResult(io, fail('worktree.renew', 'LEASE_FILE_INVALID', getErrorMessage(err), { leaseId: options.leaseId, file }, [
+                    'Delete the malformed lease file manually and re-spawn.',
+                    'For security, renew never fails open on a malformed lease.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (lease.status === 'released' || lease.status === 'gc') {
+                printResult(io, fail('worktree.renew', 'LEASE_NOT_RENEWABLE', `lease is in status '${lease.status}'; only active/expired leases may be renewed`, { leaseId: lease.leaseId, status: lease.status }, [
+                    'Released leases cannot be renewed. Run `peaks worktree spawn` to start a new lease.',
+                    'Gc-marked leases are terminal — re-spawn.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const now = Date.now();
+            const ttlMs = options.ttl === undefined ? ttlForRole(lease.role) : Number.parseInt(options.ttl, 10);
+            if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
+                printResult(io, fail('worktree.renew', 'INVALID_TTL', '--ttl must be a positive integer (ms)', { ttl: options.ttl }, [
+                    'Re-run with --ttl 1800000 (30 min) or omit to use role default.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const renewed = renewLease(lease, now + ttlMs);
+            atomicWriteJson(file, renewed);
+            // Part 4.A: emit renew metric.
+            emitLeaseEvent({
+                sessionId,
+                projectRoot,
+                kind: 'renew',
+                leaseId: renewed.leaseId,
+                rid: renewed.rid,
+                role: renewed.role
+            });
+            printResult(io, ok('worktree.renew', { lease: renewed, sessionId, projectRoot, ttlMs, previousExpiresAt: lease.expiresAt }, [], [
+                `Lease ${renewed.leaseId} renewed; new expiresAt: ${new Date(renewed.expiresAt).toISOString()}.`,
+                `Branch ${renewed.branch} at ${renewed.path} remains intact (no ` +
+                    '`git worktree` operation was performed — the worktree was always there).'
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('worktree.renew', 'RENEW_FAILED', getErrorMessage(err), { leaseId: options.leaseId, sessionId }, [
+                'Re-run after fixing the failure (see cause in the error message).'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(auth
+        .command('list')
+        .description('List every lease under the current session\'s lease store. ' +
+        'Optionally filter by --status (active|released|expired|gc) and/or --expired-only. ' +
+        'Leases past their expiresAt with status=active are still listed under "active" by default ' +
+        '(`isLeaseActive` returns false for them, but the on-disk status only flips to "expired" ' +
+        'after `peaks worktree gc` runs).')
+        .option('--status <state>', 'filter by lease status: active | released | expired | gc')
+        .option('--expired-only', 'only show leases whose expiresAt is in the past')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        const projectRoot = resolveProjectRoot(options);
+        const sessionId = resolveSessionId(options, projectRoot);
+        try {
+            const storeDir = leaseStoreDir(joinPathSession(projectRoot, sessionId));
+            const result = listLeasesSync(storeDir, {
+                readdir: (p) => readdirSync(p),
+                readFile: (p) => readFileSyncNode(p, 'utf8'),
+                existsSync: (p) => existsSync(p)
+            });
+            if (result.kind === 'store-missing') {
+                printResult(io, ok('worktree.list', { sessionId, projectRoot, leases: [], errors: [], storeMissing: true }, [], [
+                    `No lease store at ${storeDir}. Spawn a worktree first (\`peaks worktree spawn ...\`).`
+                ]), options.json);
+                return;
+            }
+            const now = Date.now();
+            const annotated = result.leases.map((l) => ({
+                ...l,
+                live: isLeaseActive(l, now),
+                elapsedMs: now - l.createdAt,
+                remainingMs: l.expiresAt - now
+            }));
+            let filtered = annotated;
+            if (options.status) {
+                filtered = filtered.filter((l) => l.status === options.status);
+            }
+            if (options.expiredOnly === true) {
+                filtered = filtered.filter((l) => !l.live);
+            }
+            // Sort by createdAt desc — most-recent first. Stable for diffs.
+            filtered = [...filtered].sort((a, b) => b.createdAt - a.createdAt);
+            printResult(io, ok('worktree.list', {
+                sessionId,
+                projectRoot,
+                storeDir,
+                totalOnDisk: result.leases.length,
+                returned: filtered.length,
+                errors: result.errors,
+                leases: filtered
+            }, result.errors.map((e) => `Malformed lease: ${e.file} (${e.error})`), [
+                `${filtered.length} lease(s) matched (${result.leases.length} on disk).`,
+                result.errors.length > 0 ? 'Some lease files were malformed — see errors[]; they were skipped.' : ''
+            ].filter(Boolean)), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('worktree.list', 'LIST_FAILED', getErrorMessage(err), { sessionId }, [
+                'Re-run after fixing the failure (see cause in the error message).'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(auth
+        .command('gc')
+        .description('Sweep released/expired leases: remove their git worktree (if still attached), prune git\'s ' +
+        'worktree references, and mark the lease as "gc". With --lease-id <id>, only that lease is ' +
+        'considered. With --dry-run, report what would be gc\'d without mutating. Expired-active ' +
+        'leases (status=active but past expiresAt) are eligible — they are first marked "expired" ' +
+        'then their worktree is removed.')
+        .option('--lease-id <id>', 'only consider this specific lease')
+        .option('--dry-run', 'report what would be gc\'d without mutating')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        const projectRoot = resolveProjectRoot(options);
+        const sessionId = resolveSessionId(options, projectRoot);
+        try {
+            const storeDir = leaseStoreDir(joinPathSession(projectRoot, sessionId));
+            const result = listLeasesSync(storeDir, {
+                readdir: (p) => readdirSync(p),
+                readFile: (p) => readFileSyncNode(p, 'utf8'),
+                existsSync: (p) => existsSync(p)
+            });
+            if (result.kind === 'store-missing') {
+                printResult(io, ok('worktree.gc', { sessionId, projectRoot, swept: 0, storeMissing: true }, [], [
+                    `No lease store at ${storeDir}; nothing to gc.`
+                ]), options.json);
+                return;
+            }
+            const now = Date.now();
+            const candidates = result.leases
+                .filter((l) => (options.leaseId ? l.leaseId === options.leaseId : true))
+                .filter((l) => isLeaseGcEligible(l, now));
+            const dryRun = options.dryRun === true;
+            const swept = [];
+            for (const lease of candidates) {
+                let prevStatus = lease.status;
+                let updated = lease;
+                // If the lease is still marked active but past expiresAt, transition to expired first.
+                if (lease.status === 'active' && lease.expiresAt <= now) {
+                    updated = markExpired(lease);
+                    prevStatus = 'active';
+                }
+                if (!dryRun) {
+                    // `git worktree remove --force` is best-effort — if the path is
+                    // already gone we still mark the lease gc.
+                    let gitWorktreeRemoveFailed = false;
+                    try {
+                        execSync(`git worktree remove --force "${updated.path}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+                    }
+                    catch {
+                        gitWorktreeRemoveFailed = true;
+                    }
+                    // `git worktree prune` clears any stale admin entries. Best-effort.
+                    try {
+                        execSync('git worktree prune', { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+                    }
+                    catch {
+                        // ignore — prune is idempotent
+                    }
+                    const finalLease = markGc(updated);
+                    atomicWriteJson(leaseFilePath(joinPathSession(projectRoot, sessionId), lease.leaseId), finalLease);
+                    // Part 4.A: emit gc metric (per swept lease).
+                    emitLeaseEvent({
+                        sessionId,
+                        projectRoot,
+                        kind: 'gc',
+                        leaseId: lease.leaseId,
+                        rid: lease.rid,
+                        role: lease.role
+                    });
+                    swept.push({ leaseId: lease.leaseId, path: lease.path, prevStatus, gitWorktreeRemoveFailed });
+                }
+                else {
+                    swept.push({ leaseId: lease.leaseId, path: lease.path, prevStatus, gitWorktreeRemoveFailed: false });
+                }
+            }
+            printResult(io, ok('worktree.gc', { sessionId, projectRoot, dryRun, candidates: candidates.length, swept, errors: result.errors }, result.errors.map((e) => `Malformed lease: ${e.file} (${e.error})`), [
+                dryRun
+                    ? `[dry-run] Would gc ${swept.length} lease(s); no filesystem changes were made.`
+                    : `Gc'd ${swept.length} lease(s).`,
+                'For per-lease detail, run `peaks worktree status --lease-id <id>`.'
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('worktree.gc', 'GC_FAILED', getErrorMessage(err), { sessionId }, [
+                'Re-run after fixing the failure (see cause in the error message).'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(auth
+        .command('lease-status')
+        .description('Show one lease in detail: full lease record + computed `live` flag (active AND not past ' +
+        'expiry) + path/branch/path-exists-on-disk diagnostics. Use this when triaging why a ' +
+        'sub-agent cannot write to a worktree.')
+        .requiredOption('--lease-id <id>', 'lease id to inspect')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        const projectRoot = resolveProjectRoot(options);
+        const sessionId = resolveSessionId(options, projectRoot);
+        try {
+            const file = leaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+            if (!existsSync(file)) {
+                printResult(io, fail('worktree.lease-status', 'LEASE_NOT_FOUND', `no lease on disk at ${file}`, { leaseId: options.leaseId, file }, [
+                    'Run `peaks worktree list` to inspect available leases.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            let lease;
+            try {
+                lease = deserializeLease(readFileSyncNode(file, 'utf8'));
+            }
+            catch (err) {
+                printResult(io, fail('worktree.lease-status', 'LEASE_FILE_INVALID', getErrorMessage(err), { leaseId: options.leaseId, file }, [
+                    'Delete the malformed lease file manually and re-spawn.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const now = Date.now();
+            const pathExists = existsSync(lease.path);
+            let pathIsDirectory = false;
+            if (pathExists) {
+                try {
+                    pathIsDirectory = statSync(lease.path).isDirectory();
+                }
+                catch {
+                    pathIsDirectory = false;
+                }
+            }
+            printResult(io, ok('worktree.lease-status', {
+                sessionId,
+                projectRoot,
+                file: '.peaks/_runtime/' + sessionId + '/worktree-leases/' + lease.leaseId + '.json',
+                lease,
+                live: isLeaseActive(lease, now),
+                diagnostics: {
+                    now,
+                    remainingMs: lease.expiresAt - now,
+                    pathExists,
+                    pathIsDirectory
+                }
+            }, [], [
+                `Lease ${lease.leaseId} is ${isLeaseActive(lease, now) ? 'LIVE' : 'NOT LIVE'} ` +
+                    `(status=${lease.status}, remaining=${lease.expiresAt - now}ms).`,
+                `Worktree path ${lease.path} ${pathExists ? (pathIsDirectory ? 'exists (dir)' : 'exists (NOT a dir)') : 'MISSING'}.`
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('worktree.lease-status', 'STATUS_FAILED', getErrorMessage(err), { leaseId: options.leaseId, sessionId }, [
+                'Re-run after fixing the failure (see cause in the error message).'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+/**
+ * Resolve the per-session runtime directory: `<projectRoot>/.peaks/_runtime/<sessionId>`.
+ * The runtime tree is gitignored; the spawn CLI writes the lease file
+ * under `<this>/worktree-leases/<leaseId>.json` and the worktree itself
+ * under `<this>/worktrees/<leaseId>/`.
+ */
+function joinPathSession(projectRoot, sessionId) {
+    return `${projectRoot.replace(/[\\/]+$/, '')}/.peaks/_runtime/${sessionId}`;
+}

package/dist/services/artifacts/request-artifact-service.js

@@ -9,7 +9,7 @@ import { ensureSession, getSessionIdCanonical } from '../session/session-manager
 // gone; request-artifact callers pass `options.sessionId` explicitly
 // or accept the requestId as the default. Path-safety helpers now
 // live at `shared/path-safety.ts` if this module ever needs them.
-import { getNextNumber, buildNumberedFilename } from '../../shared/incrementing-number.js';
+import { getNextNumber, buildNumberedFilename, slugifyDescription } from '../../shared/incrementing-number.js';
 import { lintRequestArtifact } from './artifact-lint-service.js';
 import { checkTypeSanity } from '../scan/type-sanity-service.js';
 import { requireUserConfirmation } from '../mode/mode-enforcement.js';
@@ -94,10 +94,15 @@ export async function createRequestArtifact(options) {
     // Check if a file with this requestId already exists (regardless of number prefix)
     if (await isDirectory(requestsDir)) {
         const existingFiles = await listMarkdownFiles(requestsDir);
+        // The writer lowercases the request id into a kebab slug
+        // (`buildNumberedFilename`), so the duplicate-detection endsWith must
+        // compare against the SAME slug — a mixed-case id like
+        // `2026-09-06-split-batchA` is stored as `...-split-batcha.md`.
+        const slug = slugifyDescription(options.requestId);
         const alreadyExists = existingFiles.some((file) => {
             if (file === `${options.requestId}.md`)
                 return true;
-            if (/^\d+-/.test(file) && file.endsWith(`-${options.requestId}.md`))
+            if (/^\d+-/.test(file) && file.endsWith(`-${slug}.md`))
                 return true;
             return false;
         });
@@ -272,6 +277,11 @@ export async function showRequestArtifact(options) {
         throw new Error(`Invalid request id: ${options.requestId} (expected letters, digits, dots, underscores, or dashes)`);
     }
     // Search for files matching the requestId (supports both legacy and numbered formats)
+    // The numbered format lowercases the request id into a kebab slug
+    // (`buildNumberedFilename`), so the endsWith must compare against the SAME
+    // slug — a mixed-case id like `2026-09-06-split-batchA` is stored as
+    // `...-split-batcha.md` and must still resolve here.
+    const slug = slugifyDescription(options.requestId);
     const findFileInDir = async (dir) => {
         const files = await listMarkdownFiles(dir);
         for (const file of files) {
@@ -280,7 +290,7 @@ export async function showRequestArtifact(options) {
                 return { fileName: file, path: join(dir, file) };
             }
             // Match numbered format: ${number}-${requestId}.md
-            if (/^\d+-/.test(file) && file.endsWith(`-${options.requestId}.md`)) {
+            if (/^\d+-/.test(file) && file.endsWith(`-${slug}.md`)) {
                 return { fileName: file, path: join(dir, file) };
             }
         }

package/dist/services/code/auto-compact-lifecycle.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Auto-compact lifecycle telemetry (v2.13.0 AC-2 + AC-3 + AC-4,
+ * slice 2026-08-01-compact-lifecycle Task 5).
+ *
+ * Extracted from `auto-compact-orchestrator.ts` to keep that file under
+ * the 800 LOC cap (mechanical verbatim move). Publishes the stages a
+ * compact attempt actually PROVED in-process (`queued` / `preparing` /
+ * `compacting`) plus the terminal `failed` stage, and settles an open
+ * `compacting` run using a real post-compact measurement. Telemetry is
+ * strictly subordinate to the compact itself: every write is best-effort
+ * and never changes the threshold decision, the dispatch, or the
+ * returned envelope.
+ */
+import { type CompactLifecycleRecord, type CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
+/**
+ * Stages a compact *attempt* can prove from inside the dispatching
+ * process. `verifying` / `completed` are deliberately absent — see
+ * `CompactLifecyclePublisher` and `settleOpenLifecycleRun` for why.
+ */
+type ObservableDispatchStage = Extract<CompactLifecycleStage, 'queued' | 'preparing' | 'compacting'>;
+/**
+ * One id per compact attempt. Timestamp-prefixed so a human reading
+ * the raw record can order runs by eye; the random suffix keeps two
+ * attempts inside the same millisecond distinct.
+ */
+export declare function newCompactRunId(now: Date): string;
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5): the local transition
+ * builder. Carries `runId`, `triggerRatio` and `redLine` forward from
+ * the run that opened, and remembers the prior stage so a failure can
+ * name the stage it died in.
+ *
+ * TRUTHFULNESS: this publisher only ever emits a stage the calling
+ * process has actually PROVED. It never emits `verifying` or
+ * `completed` off the back of a successful dispatch — see
+ * `runAutoCompact` and `settleOpenLifecycleRun` for the reason.
+ *
+ * Telemetry is strictly subordinate to the compact itself: every write
+ * is best-effort, and a store failure must not change the threshold
+ * decision, the dispatch, or the returned envelope.
+ */
+export declare class CompactLifecyclePublisher {
+    private readonly ctx;
+    private lastStage;
+    constructor(ctx: {
+        readonly projectRoot: string;
+        readonly sessionId: string;
+        readonly runId: string;
+        readonly triggerRatio: number;
+        readonly redLine: boolean;
+        readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
+        readonly failLifecycleWrite?: boolean | undefined;
+    });
+    /** Publish an active stage the process has proved. */
+    advance(stage: ObservableDispatchStage): void;
+    /** Publish the terminal failure, attributed to the last stage reached. */
+    fail(error: unknown): void;
+    private write;
+}
+/**
+ * Reduce an arbitrary thrown value to a single-line, bounded summary
+ * fit for a statusline. Stack frames are dropped (the record is a
+ * human-facing indicator, not a crash dump); the store clamps the
+ * result to its own 160-character cap as a second line of defence.
+ *
+ * `null` / `undefined` thrown values — a real possibility from
+ * `Promise.reject(null)` or a thrown `undefined` — must not collapse
+ * to the empty string, which the store would then reject as missing.
+ * They map to a fixed "unknown error" sentinel so the record always
+ * carries some diagnostic text.
+ */
+export declare function summarizeLifecycleError(error: unknown): string;
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5, Step 4): close out an
+ * open compact run using a REAL measurement.
+ *
+ * This is the integration with the actual post-compact detection path.
+ * The claude-code adapter's `postCompactDetectCommand` is
+ * `peaks compact auto --json` — i.e. the next probe through this very
+ * function. So when a probe finds a run still sitting at `compacting`
+ * and MEASURES a ratio that has dropped below the auto-fire threshold,
+ * that measurement is the proof the compact landed. Only then do we
+ * emit `verifying` (we have a measurement in hand) followed by
+ * `completed` (it confirms the drop), carrying the measured
+ * `afterRatio`.
+ *
+ * We refuse to complete when:
+ *   - the probe could not measure anything (`conservative-fallback`
+ *     returns `ratio: 0`, which means "unknown", NOT "empty"). Writing
+ *     `afterRatio: 0` there would publish a fabricated number;
+ *   - the ratio is still at or above the auto-fire threshold — the
+ *     compact has not landed, so the run stays open.
+ */
+export declare function settleOpenLifecycleRun(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly measuredRatio: number;
+    readonly source: string;
+    readonly autoFireThreshold: number;
+    readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
+}): void;
+export {};