peaks-loop 4.1.1 → 4.1.3

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

@@ -9,520 +9,49 @@
  * 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.
+ *
+ * Each sub-command now lives in its own `worktree-lease-<name>-command.ts`
+ * sibling (registrar + runner + helpers), with the shared pieces in
+ * `worktree-lease-session.ts` (session / project-root resolution),
+ * `worktree-lease-load.ts` (single-lease loader), `worktree-lease-store.ts`
+ * (lease-store reader) and `worktree-lease-git.ts` (best-effort git
+ * helpers). This module keeps the registration entry point and re-exports
+ * the two resolvers the rest of the CLI imports from this path. Command
+ * names, options, envelopes, error codes and exit codes are unchanged.
  */
-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();
-}
+import { registerWorktreeLeaseGcCommand } from './worktree-lease-gc-command.js';
+import { registerWorktreeLeaseListCommand } from './worktree-lease-list-command.js';
+import { registerWorktreeLeaseReleaseCommand } from './worktree-lease-release-command.js';
+import { registerWorktreeLeaseRenewCommand } from './worktree-lease-renew-command.js';
+import { registerWorktreeLeaseSpawnCommand } from './worktree-lease-spawn-command.js';
+import { registerWorktreeLeaseStatusCommand } from './worktree-lease-status-command.js';
+export { resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+// 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.
 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.
+    registerWorktreeLeaseSpawnCommand(auth, io);
+    registerWorktreeLeaseReleaseCommand(auth, io);
+    // ─── Part 2.A: renew / list / gc / status ──────────────────────────────
+    // These four commands own the rest of the lease lifecycle. The hook
+    // integration (Part 2.B) and dispatch --isolation (Part 2.C) consult
+    // the same on-disk lease files these commands read/write, so the
+    // source-of-truth contract is preserved end-to-end.
     //
-    // 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',
-                windowsHide: true
-            });
-            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',
-                    windowsHide: true
-                });
-            }
-            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',
-                            windowsHide: true
-                        });
-                    }
-                    catch {
-                        gitWorktreeRemoveFailed = true;
-                    }
-                    // `git worktree prune` clears any stale admin entries. Best-effort.
-                    try {
-                        execSync('git worktree prune', {
-                            cwd: projectRoot,
-                            stdio: 'pipe',
-                            encoding: 'utf8',
-                            windowsHide: true
-                        });
-                    }
-                    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}`;
+    //   renew   — extend an active lease's expiresAt
+    //   list    — enumerate every lease in the session store (with filter)
+    //   gc      — prune released/expired worktrees + mark leases 'gc'
+    //   status  — read a single lease in detail
+    registerWorktreeLeaseRenewCommand(auth, io);
+    registerWorktreeLeaseListCommand(auth, io);
+    registerWorktreeLeaseGcCommand(auth, io);
+    registerWorktreeLeaseStatusCommand(auth, io);
 }

package/dist/cli/commands/worktree-lease-gc-command.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `peaks worktree gc` — sweep released/expired leases.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The per-lease sweep is now `sweepLease`; the
+ * `--lease-id` / `--dry-run` semantics, the expired-active transition, the
+ * best-effort git removal + prune, the per-lease metric emit and the
+ * ok/fail envelopes are unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorktreeLeaseGcCommand(auth: Command, io: ProgramIO): void;