peaks-loop 4.1.1 → 4.1.3

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

@@ -0,0 +1,117 @@
+/**
+ * `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 { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { emitLeaseEvent } from '../../services/observability/observability-service.js';
+import { isLeaseGcEligible, leaseFilePath, markExpired, markGc } from '../../services/worktree/worktree-lease.js';
+import { pruneWorktreesBestEffort, removeWorktreeBestEffort } from './worktree-lease-git.js';
+import { loadLeaseStore, malformedLeaseWarnings } from './worktree-lease-store.js';
+import { joinPathSession, resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+const 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.';
+const GC_LEASE_ID_DESCRIPTION = 'only consider this specific lease';
+const GC_DRY_RUN_DESCRIPTION = "report what would be gc'd without mutating";
+function sweepLease(ctx) {
+    const { lease, dryRun, now, projectRoot, sessionId } = ctx;
+    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) {
+        return {
+            leaseId: lease.leaseId,
+            path: lease.path,
+            prevStatus,
+            gitWorktreeRemoveFailed: false
+        };
+    }
+    // `git worktree remove --force` is best-effort — if the path is
+    // already gone we still mark the lease gc.
+    const gitWorktreeRemoveFailed = removeWorktreeBestEffort(projectRoot, updated.path);
+    pruneWorktreesBestEffort(projectRoot);
+    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
+    });
+    return { leaseId: lease.leaseId, path: lease.path, prevStatus, gitWorktreeRemoveFailed };
+}
+function printGcStoreMissing(io, options, ctx) {
+    const { sessionId, projectRoot, storeDir } = ctx;
+    printResult(io, ok('worktree.gc', { sessionId, projectRoot, swept: 0, storeMissing: true }, [], [`No lease store at ${storeDir}; nothing to gc.`]), options.json);
+}
+function printGcOk(io, options, ctx) {
+    const { sessionId, projectRoot, dryRun, candidates, swept, errors } = ctx;
+    printResult(io, ok('worktree.gc', { sessionId, projectRoot, dryRun, candidates, swept, errors }, malformedLeaseWarnings(errors), [
+        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);
+}
+function printGcFailed(io, options, err, sessionId) {
+    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;
+}
+function runGc(options, io) {
+    const projectRoot = resolveProjectRoot(options);
+    const sessionId = resolveSessionId(options, projectRoot);
+    try {
+        const { storeDir, result } = loadLeaseStore(projectRoot, sessionId);
+        if (result.kind === 'store-missing') {
+            printGcStoreMissing(io, options, { sessionId, projectRoot, storeDir });
+            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) {
+            swept.push(sweepLease({ lease, dryRun, now, projectRoot, sessionId }));
+        }
+        printGcOk(io, options, {
+            sessionId,
+            projectRoot,
+            dryRun,
+            candidates: candidates.length,
+            swept,
+            errors: result.errors
+        });
+    }
+    catch (err) {
+        printGcFailed(io, options, err, sessionId);
+    }
+}
+export function registerWorktreeLeaseGcCommand(auth, io) {
+    addJsonOption(auth
+        .command('gc')
+        .description(GC_DESCRIPTION)
+        .option('--lease-id <id>', GC_LEASE_ID_DESCRIPTION)
+        .option('--dry-run', GC_DRY_RUN_DESCRIPTION)
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => runGc(options, io));
+}

package/dist/cli/commands/worktree-lease-git.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Best-effort `git worktree` shell helpers shared by `release` and `gc`.
+ *
+ * Both commands detach a worktree the same way (and `gc` additionally
+ * prunes stale admin entries). Extracted verbatim from
+ * `worktree-lease-commands.ts`: the commands, cwd, stdio/encoding flags
+ * and the swallow-on-failure posture are unchanged.
+ */
+/**
+ * `git worktree remove --force` is best-effort: when the path is already
+ * pruned the caller still marks the lease released / gc. Returns whether
+ * the git invocation failed.
+ *
+ * `windowsHide: true` is spelled at each call site rather than shared: the
+ * guard (`tests/unit/spawn-windows-hide-guard.test.ts`) resolves a same-file
+ * plain-`const` object literal and a spread of it, but not one declared
+ * `as const`, frozen, `let`, or imported from another file — measured: both
+ * call sites below were reported while the shared constant was `as const`.
+ */
+export declare function removeWorktreeBestEffort(projectRoot: string, wtPath: string): boolean;
+/** `git worktree prune` clears stale admin entries. Best-effort. */
+export declare function pruneWorktreesBestEffort(projectRoot: string): void;

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

@@ -0,0 +1,48 @@
+/**
+ * Best-effort `git worktree` shell helpers shared by `release` and `gc`.
+ *
+ * Both commands detach a worktree the same way (and `gc` additionally
+ * prunes stale admin entries). Extracted verbatim from
+ * `worktree-lease-commands.ts`: the commands, cwd, stdio/encoding flags
+ * and the swallow-on-failure posture are unchanged.
+ */
+import { execSync } from 'node:child_process';
+/**
+ * `git worktree remove --force` is best-effort: when the path is already
+ * pruned the caller still marks the lease released / gc. Returns whether
+ * the git invocation failed.
+ *
+ * `windowsHide: true` is spelled at each call site rather than shared: the
+ * guard (`tests/unit/spawn-windows-hide-guard.test.ts`) resolves a same-file
+ * plain-`const` object literal and a spread of it, but not one declared
+ * `as const`, frozen, `let`, or imported from another file — measured: both
+ * call sites below were reported while the shared constant was `as const`.
+ */
+export function removeWorktreeBestEffort(projectRoot, wtPath) {
+    try {
+        execSync(`git worktree remove --force "${wtPath}"`, {
+            cwd: projectRoot,
+            stdio: 'pipe',
+            encoding: 'utf8',
+            windowsHide: true
+        });
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/** `git worktree prune` clears stale admin entries. Best-effort. */
+export function pruneWorktreesBestEffort(projectRoot) {
+    try {
+        execSync('git worktree prune', {
+            cwd: projectRoot,
+            stdio: 'pipe',
+            encoding: 'utf8',
+            windowsHide: true
+        });
+    }
+    catch {
+        // ignore — prune is idempotent
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * `peaks worktree list` — enumerate every lease in the session store.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The store read is now the shared
+ * `loadLeaseStore`; the live/elapsed/remaining annotation, the
+ * `--status` / `--expired-only` filters, the createdAt-desc sort and the
+ * ok/fail envelopes are unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorktreeLeaseListCommand(auth: Command, io: ProgramIO): void;

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

@@ -0,0 +1,100 @@
+/**
+ * `peaks worktree list` — enumerate every lease in the session store.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The store read is now the shared
+ * `loadLeaseStore`; the live/elapsed/remaining annotation, the
+ * `--status` / `--expired-only` filters, the createdAt-desc sort and the
+ * ok/fail envelopes are unchanged.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { isLeaseActive } from '../../services/worktree/worktree-lease.js';
+import { loadLeaseStore, malformedLeaseWarnings } from './worktree-lease-store.js';
+import { resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+const 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).';
+const LIST_STATUS_DESCRIPTION = 'filter by lease status: active | released | expired | gc';
+const LIST_EXPIRED_ONLY_DESCRIPTION = 'only show leases whose expiresAt is in the past';
+function annotateLeases(leases, now) {
+    return leases.map((l) => ({
+        ...l,
+        live: isLeaseActive(l, now),
+        elapsedMs: now - l.createdAt,
+        remainingMs: l.expiresAt - now
+    }));
+}
+function filterLeases(leases, options) {
+    let filtered = leases;
+    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.
+    return [...filtered].sort((a, b) => b.createdAt - a.createdAt);
+}
+function printListStoreMissing(io, options, ctx) {
+    const { sessionId, projectRoot, storeDir } = ctx;
+    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);
+}
+function printListOk(io, options, ctx) {
+    const { sessionId, projectRoot, storeDir, totalOnDisk, errors, leases } = ctx;
+    printResult(io, ok('worktree.list', {
+        sessionId,
+        projectRoot,
+        storeDir,
+        totalOnDisk,
+        returned: leases.length,
+        errors,
+        leases
+    }, malformedLeaseWarnings(errors), [
+        `${leases.length} lease(s) matched (${totalOnDisk} on disk).`,
+        errors.length > 0
+            ? 'Some lease files were malformed — see errors[]; they were skipped.'
+            : ''
+    ].filter(Boolean)), options.json);
+}
+function printListFailed(io, options, err, sessionId) {
+    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;
+}
+function runList(options, io) {
+    const projectRoot = resolveProjectRoot(options);
+    const sessionId = resolveSessionId(options, projectRoot);
+    try {
+        const { storeDir, result } = loadLeaseStore(projectRoot, sessionId);
+        if (result.kind === 'store-missing') {
+            printListStoreMissing(io, options, { sessionId, projectRoot, storeDir });
+            return;
+        }
+        const now = Date.now();
+        const filtered = filterLeases(annotateLeases(result.leases, now), options);
+        printListOk(io, options, {
+            sessionId,
+            projectRoot,
+            storeDir,
+            totalOnDisk: result.leases.length,
+            errors: result.errors,
+            leases: filtered
+        });
+    }
+    catch (err) {
+        printListFailed(io, options, err, sessionId);
+    }
+}
+export function registerWorktreeLeaseListCommand(auth, io) {
+    addJsonOption(auth
+        .command('list')
+        .description(LIST_DESCRIPTION)
+        .option('--status <state>', LIST_STATUS_DESCRIPTION)
+        .option('--expired-only', LIST_EXPIRED_ONLY_DESCRIPTION)
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => runList(options, io));
+}

package/dist/cli/commands/worktree-lease-load.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared single-lease loader for the three read-by-lease-id commands
+ * (`release`, `renew`, `lease-status`).
+ *
+ * All three used to inline the same two failure shapes — a missing lease
+ * file (`LEASE_NOT_FOUND`) and an unparseable one (`LEASE_FILE_INVALID`) —
+ * differing only in the envelope `command` string and the two hint lines.
+ * Both are parameters here. The message text, the `{ leaseId, file }`
+ * data payload and the caller's `process.exitCode = 1` are unchanged.
+ */
+import { type ProgramIO } from '../cli-helpers.js';
+import { type WorktreeLease } from '../../services/worktree/worktree-lease.js';
+/** The option surface the loader reads: the lease id and `--json`. */
+export interface LeaseIdOptions {
+    leaseId: string;
+    json?: boolean;
+}
+export interface LeaseLoadHints {
+    /** nextActions printed for `LEASE_NOT_FOUND`. */
+    missing: string[];
+    /** nextActions printed for `LEASE_FILE_INVALID`. */
+    invalid: string[];
+}
+export interface LeaseLoadRequest {
+    /** The envelope `command` string (e.g. `worktree.renew`). */
+    command: string;
+    /** Absolute path of the lease file to read. */
+    file: string;
+    hints: LeaseLoadHints;
+}
+export type LeaseLoadResult = {
+    stop: true;
+} | {
+    stop: false;
+    lease: WorktreeLease;
+};
+export declare function loadLeaseOrStop(io: ProgramIO, options: LeaseIdOptions, request: LeaseLoadRequest): LeaseLoadResult;

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

@@ -0,0 +1,28 @@
+/**
+ * Shared single-lease loader for the three read-by-lease-id commands
+ * (`release`, `renew`, `lease-status`).
+ *
+ * All three used to inline the same two failure shapes — a missing lease
+ * file (`LEASE_NOT_FOUND`) and an unparseable one (`LEASE_FILE_INVALID`) —
+ * differing only in the envelope `command` string and the two hint lines.
+ * Both are parameters here. The message text, the `{ leaseId, file }`
+ * data payload and the caller's `process.exitCode = 1` are unchanged.
+ */
+import { fail } from 'peaks-loop-shared/result';
+import { existsSync, readFileSync as readFileSyncNode } from 'node:fs';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { deserializeLease } from '../../services/worktree/worktree-lease.js';
+export function loadLeaseOrStop(io, options, request) {
+    const { command, file, hints } = request;
+    if (!existsSync(file)) {
+        printResult(io, fail(command, 'LEASE_NOT_FOUND', `no lease on disk at ${file}`, { leaseId: options.leaseId, file }, hints.missing), options.json);
+        return { stop: true };
+    }
+    try {
+        return { stop: false, lease: deserializeLease(readFileSyncNode(file, 'utf8')) };
+    }
+    catch (error) {
+        printResult(io, fail(command, 'LEASE_FILE_INVALID', getErrorMessage(error), { leaseId: options.leaseId, file }, hints.invalid), options.json);
+        return { stop: true };
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * `peaks worktree release` — transition a lease to 'released' and run
+ * `git worktree remove`.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The lease-file failures now route through the
+ * shared `loadLeaseOrStop` (same envelope, same hints, same exit code);
+ * the idempotent already-released branch, the best-effort git removal and
+ * the ok/fail envelopes are unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorktreeLeaseReleaseCommand(auth: Command, io: ProgramIO): void;

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

@@ -0,0 +1,105 @@
+/**
+ * `peaks worktree release` — transition a lease to 'released' and run
+ * `git worktree remove`.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The lease-file failures now route through the
+ * shared `loadLeaseOrStop` (same envelope, same hints, same exit code);
+ * the idempotent already-released branch, the best-effort git removal and
+ * the ok/fail envelopes are unchanged.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { emitLeaseEvent } from '../../services/observability/observability-service.js';
+import { leaseFilePath, markReleased } from '../../services/worktree/worktree-lease.js';
+import { loadLeaseOrStop } from './worktree-lease-load.js';
+import { removeWorktreeBestEffort } from './worktree-lease-git.js';
+import { joinPathSession, resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+const RELEASE_DESCRIPTION = 'Transition a lease to released and run `git worktree remove`. Idempotent on already-released leases.';
+const RELEASE_MISSING_HINTS = [
+    'Run `peaks worktree list` to inspect active leases.',
+    'For a never-spawned lease, this is a no-op — no further action needed.'
+];
+const RELEASE_INVALID_HINTS = [
+    'Delete the malformed lease file manually and re-issue spawn.',
+    'For security, release never fails open on a malformed lease.'
+];
+function printReleaseAlreadyReleased(io, options, ctx) {
+    const { lease, sessionId, projectRoot } = ctx;
+    // 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);
+}
+function printReleaseDone(io, options, ctx) {
+    const { lease, released, sessionId, projectRoot, gitWorktreeRemoveFailed } = ctx;
+    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);
+}
+function printReleaseFailed(io, options, error, sessionId) {
+    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;
+}
+function runRelease(options, io) {
+    const projectRoot = resolveProjectRoot(options);
+    const sessionId = resolveSessionId(options, projectRoot);
+    try {
+        const file = leaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+        const loaded = loadLeaseOrStop(io, options, {
+            command: 'worktree.release',
+            file,
+            hints: { missing: RELEASE_MISSING_HINTS, invalid: RELEASE_INVALID_HINTS }
+        });
+        if (loaded.stop) {
+            process.exitCode = 1;
+            return;
+        }
+        const lease = loaded.lease;
+        if (lease.status === 'released') {
+            printReleaseAlreadyReleased(io, options, { lease, sessionId, projectRoot });
+            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.
+        const gitWorktreeRemoveFailed = removeWorktreeBestEffort(projectRoot, lease.path);
+        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
+        });
+        printReleaseDone(io, options, {
+            lease,
+            released,
+            sessionId,
+            projectRoot,
+            gitWorktreeRemoveFailed
+        });
+    }
+    catch (error) {
+        printReleaseFailed(io, options, error, sessionId);
+    }
+}
+export function registerWorktreeLeaseReleaseCommand(auth, io) {
+    addJsonOption(auth
+        .command('release')
+        .description(RELEASE_DESCRIPTION)
+        .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) => runRelease(options, io));
+}

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

@@ -0,0 +1,11 @@
+/**
+ * `peaks worktree renew` — extend an active lease's `expiresAt`.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The lease-file failures route through the shared
+ * `loadLeaseOrStop`; the LEASE_NOT_RENEWABLE / INVALID_TTL guards, the
+ * renewal write, the metric emit and the ok/fail envelopes are unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorktreeLeaseRenewCommand(auth: Command, io: ProgramIO): void;

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

@@ -0,0 +1,99 @@
+/**
+ * `peaks worktree renew` — extend an active lease's `expiresAt`.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The lease-file failures route through the shared
+ * `loadLeaseOrStop`; the LEASE_NOT_RENEWABLE / INVALID_TTL guards, the
+ * renewal write, the metric emit and the ok/fail envelopes are unchanged.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { emitLeaseEvent } from '../../services/observability/observability-service.js';
+import { leaseFilePath, renewLease, ttlForRole } from '../../services/worktree/worktree-lease.js';
+import { loadLeaseOrStop } from './worktree-lease-load.js';
+import { joinPathSession, resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+const 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.';
+const RENEW_MISSING_HINTS = [
+    'Run `peaks worktree list` to inspect active leases.',
+    'For a never-spawned lease, this is a no-op.'
+];
+const RENEW_INVALID_HINTS = [
+    'Delete the malformed lease file manually and re-spawn.',
+    'For security, renew never fails open on a malformed lease.'
+];
+function printRenewNotRenewable(io, options, lease) {
+    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;
+}
+function printRenewInvalidTtl(io, options) {
+    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;
+}
+function printRenewOk(io, options, ctx) {
+    const { lease, renewed, sessionId, projectRoot, ttlMs } = ctx;
+    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);
+}
+function printRenewFailed(io, options, err, sessionId) {
+    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;
+}
+function runRenew(options, io) {
+    const projectRoot = resolveProjectRoot(options);
+    const sessionId = resolveSessionId(options, projectRoot);
+    try {
+        const file = leaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+        const loaded = loadLeaseOrStop(io, options, {
+            command: 'worktree.renew',
+            file,
+            hints: { missing: RENEW_MISSING_HINTS, invalid: RENEW_INVALID_HINTS }
+        });
+        if (loaded.stop) {
+            process.exitCode = 1;
+            return;
+        }
+        const lease = loaded.lease;
+        if (lease.status === 'released' || lease.status === 'gc') {
+            printRenewNotRenewable(io, options, lease);
+            return;
+        }
+        const now = Date.now();
+        const ttlMs = options.ttl === undefined ? ttlForRole(lease.role) : Number.parseInt(options.ttl, 10);
+        if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
+            printRenewInvalidTtl(io, options);
+            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
+        });
+        printRenewOk(io, options, { lease, renewed, sessionId, projectRoot, ttlMs });
+    }
+    catch (err) {
+        printRenewFailed(io, options, err, sessionId);
+    }
+}
+export function registerWorktreeLeaseRenewCommand(auth, io) {
+    addJsonOption(auth
+        .command('renew')
+        .description(RENEW_DESCRIPTION)
+        .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) => runRenew(options, io));
+}

package/dist/cli/commands/worktree-lease-session.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Session / project-root resolution shared by every `peaks worktree
+ * <spawn|release|renew|list|gc|lease-status>` sub-command.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` so each
+ * `worktree-lease-<name>-command.ts` sibling can resolve the same roots
+ * without importing the registrar module (the dependency direction stays
+ * one-way: siblings → this module → services).
+ */
+export declare function resolveSessionId(options: {
+    session?: string;
+}, projectRoot: string): string;
+export declare function resolveProjectRoot(options: {
+    project?: string;
+}): string;
+/**
+ * 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>/`.
+ */
+export declare function joinPathSession(projectRoot: string, sessionId: string): string;

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

@@ -0,0 +1,29 @@
+/**
+ * Session / project-root resolution shared by every `peaks worktree
+ * <spawn|release|renew|list|gc|lease-status>` sub-command.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` so each
+ * `worktree-lease-<name>-command.ts` sibling can resolve the same roots
+ * without importing the registrar module (the dependency direction stays
+ * one-way: siblings → this module → services).
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+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();
+}
+/**
+ * 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>/`.
+ */
+export function joinPathSession(projectRoot, sessionId) {
+    return `${projectRoot.replace(/[\\/]+$/, '')}/.peaks/_runtime/${sessionId}`;
+}