peaks-loop 4.0.29 → 4.0.31

package/dist/cli/commands/request-format-helpers.js

@@ -0,0 +1,102 @@
+/**
+ * Format / parse helpers extracted from `request-commands.ts`
+ * (slice 2026-09-06-split-batch-b) so the command file stays under the
+ * 800-line cap. Behaviour-preserving verbatim move.
+ */
+import { InvalidArgumentError } from 'commander';
+import { allowedStatesForRole, isRequestType, VALID_REQUEST_TYPES, } from '../../services/artifacts/request-artifact-service.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
+/**
+ * Per-artifact default format. Only PRD and tech-doc are user-review
+ * surfaces; all other RD/QA/TXT artifacts default to compact. The
+ * `--pretty` / `--compact` flags override uniformly. See tech-doc
+ * §1.3.
+ */
+const DEFAULT_FORMAT_BY_ARTIFACT = {
+    prd: 'pretty',
+    'tech-doc': 'pretty',
+    'code-review': 'compact',
+    'security-review': 'compact',
+    'perf-baseline': 'compact',
+    'bug-analysis': 'compact',
+    'test-cases': 'compact',
+    'test-reports': 'compact',
+    'security-findings': 'compact',
+    'performance-findings': 'compact',
+    handoff: 'compact'
+};
+export function resolveDefaultFormat(artifactName) {
+    return DEFAULT_FORMAT_BY_ARTIFACT[artifactName] ?? 'compact';
+}
+export function applyPerArtifactFormat(envelope, override) {
+    if (override === null || envelope === null || typeof envelope !== 'object')
+        return envelope;
+    // The service returns `{ id, sessionId, role, body, ... }` for a
+    // single-artifact show. The per-artifact `body` field is the only
+    // thing that changes; we attach a `format` field to surface the
+    // choice to the caller. Slice 023 (R3) AC6 / AC7.
+    const obj = envelope;
+    if (typeof obj.body === 'string') {
+        return {
+            ...obj,
+            body: override === 'compact' ? formatMdCompact(obj.body) : obj.body,
+            format: override
+        };
+    }
+    return envelope;
+}
+/**
+ * Map a request-artifact envelope to a `DEFAULT_FORMAT_BY_ARTIFACT` key.
+ * The service returns the path of the artifact in `path`; the role +
+ * filename stem gives us the artifact name. Falls back to the role
+ * itself when no `path` field is present.
+ */
+export function inferArtifactName(envelope, role) {
+    if (envelope === null || typeof envelope !== 'object')
+        return role;
+    const obj = envelope;
+    const pathField = typeof obj.path === 'string' ? obj.path : '';
+    // Path looks like `.peaks/_runtime/<sid>/<role>/requests/<file>.md`.
+    // The role is the second-to-last directory; the file stem is the
+    // last segment. For RD role, the artifact is one of {code-review,
+    // security-review, perf-baseline, bug-analysis, tech-doc}; the file
+    // stem usually carries the artifact name (e.g. `tech-doc.md`,
+    // `code-review-002.md`). We strip the trailing `-<digits>` suffix
+    // when present.
+    const stem = pathField.split(/[\\/]/).pop()?.replace(/\.md$/, '') ?? '';
+    if (stem.length > 0) {
+        // Try the stem verbatim first.
+        if (DEFAULT_FORMAT_BY_ARTIFACT[stem] !== undefined)
+            return stem;
+        // Strip a trailing -<digits> (e.g. code-review-002 -> code-review).
+        const trimmed = stem.replace(/-\d+$/, '');
+        if (DEFAULT_FORMAT_BY_ARTIFACT[trimmed] !== undefined)
+            return trimmed;
+        // Last-ditch: match by prefix.
+        for (const key of Object.keys(DEFAULT_FORMAT_BY_ARTIFACT)) {
+            if (stem.startsWith(key))
+                return key;
+        }
+    }
+    return role;
+}
+export const VALID_ROLES = ['prd', 'ui', 'rd', 'qa', 'sc'];
+export function parseRole(value) {
+    if (!VALID_ROLES.includes(value)) {
+        throw new InvalidArgumentError(`must be one of ${VALID_ROLES.join(', ')}`);
+    }
+    return value;
+}
+export function parseStateForRole(role, value) {
+    const allowed = allowedStatesForRole(role);
+    if (!allowed.includes(value)) {
+        throw new InvalidArgumentError(`must be one of ${allowed.join(', ')} for role ${role}`);
+    }
+    return value;
+}
+export function parseRequestType(value) {
+    if (!isRequestType(value)) {
+        throw new InvalidArgumentError(`must be one of ${VALID_REQUEST_TYPES.join(', ')}`);
+    }
+    return value;
+}

package/dist/cli/commands/workspace/init-command.js

@@ -26,7 +26,7 @@ import { resolveCanonicalProjectRoot } from '../../../services/config/config-ser
 import { applyHookInstall, readHookStatus } from '../../../services/skills/hooks-settings-service.js';
 import { clearStalePresenceOnRotation } from '../../../services/skills/skill-presence-service.js';
 import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-service.js';
-import { defaultCodegraphInitGuard, writeCodegraphMarker } from '../../../services/codegraph/codegraph-service.js';
+import { createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, writeCodegraphMarker } from '../../../services/codegraph/codegraph-service.js';
 import { mkdirSync } from 'node:fs';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
@@ -339,23 +339,36 @@ export function registerWorkspaceInitCommand(workspace, io) {
             if (report.standardsMissing.missing) {
                 markStandardsChecked(projectRoot, sessionId);
             }
-            // rid-CG-001: auto-stake a peaks-loop-managed `.codegraph/`
-            // directory after a successful workspace init. Calls the
-            // conflict guard (rid-CG-006) BEFORE writing so a foreign
-            // schema is never silently overwritten. We deliberately do
-            // NOT spawn the upstream codegraph binary here — `peaks
-            // workspace init` must stay fast and offline-safe; the user
-            // runs `peaks codegraph index` next if they want the actual
-            // SQLite-backed index.
+            // rid-CG-001 (revised): auto-stake a peaks-loop-managed `.codegraph/`
+            // directory after a successful workspace init. Calls the conflict
+            // guard (rid-CG-006) BEFORE writing so a foreign schema is never
+            // silently overwritten. We now run a REAL upstream `codegraph init`
+            // (not just mkdir + marker) so the schema actually has a
+            // `codegraph.db`, which is what post-slice auto-refresh and the
+            // pre-dispatch preflight gate on. `codegraph init` (WITHOUT
+            // `--index`) is fast (~1 s) and offline-safe — it only `Parser.init()`s
+            // WASM grammars that resolve from node_modules; the slow/offline
+            // concern applies to `index` (full build), not `init`.
             let codegraphAutoOutcome = null;
             try {
                 const guard = defaultCodegraphInitGuard(projectRoot);
                 if (guard.status === 'fresh') {
-                    mkdirSync(guard.codegraphDir, { recursive: true });
-                    writeCodegraphMarker(guard.codegraphDir);
-                    codegraphAutoOutcome = { status: 'fresh' };
-                    nextActions.push(`Auto-created empty ${guard.codegraphDir}/ and stamped the peaks-loop marker. ` +
-                        'Run `peaks codegraph index --project <path>` next to build the SQLite-backed index.');
+                    // 'fresh' here also covers the dangling state (marker present but
+                    // no codegraph.db) — running init self-heals both.
+                    const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }));
+                    if (initResult.exitCode !== 0) {
+                        warningsForEnvelope.push(`codegraph auto-stake init failed (exit ${String(initResult.exitCode)}). ` +
+                            'Run `peaks codegraph init --project <path>` manually to enable codegraph.');
+                    }
+                    else {
+                        // Upstream init creates `.codegraph/`; mkdir is a no-op in the
+                        // real path and lets the marker write succeed. Best-effort.
+                        mkdirSync(guard.codegraphDir, { recursive: true });
+                        writeCodegraphMarker(guard.codegraphDir);
+                        codegraphAutoOutcome = { status: 'fresh' };
+                        nextActions.push(`Auto-staked a peaks-loop-managed ${guard.codegraphDir}/ (upstream init + marker). ` +
+                            'Run `peaks codegraph index --project <path>` next to build the SQLite-backed index.');
+                    }
                 }
                 else if (guard.status === 'noop-already-peaks-loop') {
                     codegraphAutoOutcome = { status: 'noop' };

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

@@ -26,15 +26,9 @@
  */
 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 { clearAllGrants, readAuthorization, writeAuthorization, } from '../../services/hooks/worktree-authorization-gate.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 { reconcileHostWorktrees } from '../../services/worktree/host-worktree-reconciler.js';
-import { existsSync, readdirSync, readFileSync as readFileSyncNode, statSync } from 'node:fs';
+import { registerWorktreeLeaseCommands, resolveProjectRoot, resolveSessionId } from './worktree-lease-commands.js';
 const DEFAULT_TTL_MS = 5 * 60 * 1_000;
 const ALLOWED_OPERATIONS = [
     'git-worktree',
@@ -45,15 +39,6 @@ const ALLOWED_OPERATIONS = [
 function parseOperation(raw) {
     return ALLOWED_OPERATIONS.includes(raw) ? raw : null;
 }
-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';
-}
-function resolveProjectRoot(options) {
-    return options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-}
 export function registerWorktreeAuthCommand(program, io) {
     const auth = program
         .command('worktree')
@@ -220,460 +205,5 @@ export function registerWorktreeAuthCommand(program, io) {
             process.exitCode = 1;
         }
     });
-    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}`;
+    registerWorktreeLeaseCommands(auth, io);
 }