peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/workspace/workspace-service.js

@@ -0,0 +1,432 @@
+import { mkdir } from 'node:fs/promises';
+import { existsSync, lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDirectory } from 'peaks-loop-shared/fs';
+import { getSessionId, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
+/**
+ * Slice 2026-06-29-change-id-root-removal: list the immediate children of
+ * `.peaks/` so the legacy sibling-dir guard can enumerate date-stamped
+ * residue dirs without re-implementing `readdirSync` inline. Returns
+ * `[]` when the `.peaks/` dir does not exist (legitimate first-run
+ * outcome).
+ */
+function listPeaksRuntimeSiblings(projectRoot) {
+    const peaksDir = join(projectRoot, '.peaks');
+    if (!existsSync(peaksDir))
+        return [];
+    try {
+        return readdirSync(peaksDir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Slice 2026-06-29-change-id-root-removal: list the immediate children of
+ * `.peaks/_runtime/` so the legacy sibling-dir guard can enumerate
+ * date-stamped residue dirs at the runtime layer. Returns `[]` when
+ * the `.peaks/_runtime/` dir does not exist.
+ */
+function listRuntimeSiblings(projectRoot) {
+    const runtimeDir = join(projectRoot, '.peaks', '_runtime');
+    if (!existsSync(runtimeDir))
+        return [];
+    try {
+        return readdirSync(runtimeDir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Slice 2026-06-29-change-id-root-removal: returns `true` when the
+ * basename matches the auto-generated session-id shape
+ * `YYYY-MM-DD-<slug>` (the v2.8.3 hard-ban target). Bare dates
+ * (`YYYY-MM-DD`) are NOT auto-generated and are kept as plain dates.
+ */
+function isDateStampedSiblingId(name) {
+    if (!/^\d{4}-\d{2}-\d{2}-/.test(name))
+        return false;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(name))
+        return false;
+    return true;
+}
+// Slice 2026-06-29-change-id-root-removal: `setCurrentChangeId` and
+// `validateChangeIdOrThrow` were removed with the change-id axis. Init
+// preserves the legacy-sibling-dir guard via inline `lstatSync`; the
+// path-safety helpers moved to `shared/path-safety.ts` but this module
+// does not currently use them.
+import { detectMissingProjectStandards } from '../standards/missing-standards-detector.js';
+import { detectLanguage, executeProjectStandardsInit } from '../standards/project-standards-service.js';
+const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+const PROHIBITED_SUFFIXES = ['session', 'work', 'task', 'test', 'temp', 'tmp'];
+// Auto-generated session ID pattern: YYYY-MM-DD-session-<6位hex>
+const AUTO_SESSION_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]{6}$/;
+/**
+ * Slice C10 (2026-06-24-legacy-change-id-sibling): the relative path
+ * patterns under `.peaks/_runtime/<sessionId>/` that the lazy WRITER (peaks-qa,
+ * peaks-rd, peaks-prd, peaks-txt, peaks-sc) creates via
+ * `mkdir(parent, { recursive: true })` immediately before a write. When
+ * a sibling `.peaks/_runtime/<sessionId>/` exists on disk AND every entry below
+ * it matches one of these patterns (AND no entry is a symlink), the
+ * dir is treated as legitimate writer output and `initWorkspace`
+ * re-init is tolerant — the binding is rewritten without throwing.
+ *
+ * Adding a new pattern here is a deliberate, reviewed change because
+ * it widens the heuristic. The list is intentionally narrow:
+ *   - `qa/screenshots/<file>.{png,jpg,jpeg,webp,gif}` — peaks-qa screenshots
+ *   - `<role>/requests/<file>.md`                     — RD/QA/PRD/TXT/SC artifacts
+ *   - `<role>/findings/<file>.md`                     — QA findings files
+ *
+ * Re-exported so unit tests can assert the pattern list directly.
+ */
+export const WRITER_ALLOWED_RELATIVE_PATTERNS = [
+    /^qa\/screenshots\/[^/]+\.(png|jpg|jpeg|webp|gif)$/i,
+    /^[^/]+\/requests\/[^/]+\.md$/,
+    /^[^/]+\/findings\/[^/]+\.md$/
+];
+export class InvalidSessionIdError extends Error {
+    code = 'INVALID_SESSION_ID';
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidSessionIdError';
+    }
+}
+export class ConflictingSessionError extends Error {
+    existingSessionId;
+    requestedSessionId;
+    code = 'CONFLICTING_SESSION';
+    constructor(message, existingSessionId, requestedSessionId) {
+        super(message);
+        this.existingSessionId = existingSessionId;
+        this.requestedSessionId = requestedSessionId;
+        this.name = 'ConflictingSessionError';
+    }
+}
+/**
+ * Thrown when `peaks workspace init --change-id <id>` is invoked but a
+ * 2.8.0-era legacy sibling directory `.peaks/_runtime/<sessionId>/` already exists
+ * at top level. Under the 2.8.0+ two-axis convention, change-id is a
+ * logical identifier in the SESSION axis — NOT a top-level sibling dir.
+ *
+ * The caller is expected to:
+ *   1. Inspect `.peaks/_runtime/<sessionId>/` to see if it contains user-authored
+ *      content worth preserving.
+ *   2. Migrate or delete the sibling dir.
+ *   3. Re-run `peaks workspace init --change-id <id>`.
+ */
+export class LegacyChangeIdSiblingError extends Error {
+    sessionId;
+    legacyPath;
+    code = 'LEGACY_CHANGE_ID_SIBLING';
+    constructor(sessionId, legacyPath) {
+        super(`peaks-loop 2.8.3+ forbids the legacy sibling dir ${legacyPath}. ` +
+            `Under the two-axis convention, change-id "${sessionId}" must live in the SESSION axis ` +
+            `(.peaks/_runtime/<sessionId>/), not as a top-level sibling of .peaks/_runtime/. ` +
+            `Migration: (1) inspect ${legacyPath} for user-authored content; ` +
+            `(2) move any desired files into .peaks/_runtime/<sessionId>/<role>/; ` +
+            `(3) delete ${legacyPath}; (4) re-run 'peaks workspace init --change-id ${sessionId}'.`);
+        this.sessionId = sessionId;
+        this.legacyPath = legacyPath;
+        this.name = 'LegacyChangeIdSiblingError';
+    }
+}
+export function validateSessionId(sessionId) {
+    // Auto-generated session IDs (YYYY-MM-DD-session-<hex>) bypass manual validation
+    if (AUTO_SESSION_PATTERN.test(sessionId)) {
+        return;
+    }
+    if (/^\d+$/.test(sessionId)) {
+        throw new InvalidSessionIdError(`Session id "${sessionId}" is numeric-only. Use the format YYYY-MM-DD-<kebab-slug> with a 2-5 word topic description.`);
+    }
+    if (/^\d{8}T\d{6}$/.test(sessionId) || /^\d{8}$/.test(sessionId)) {
+        throw new InvalidSessionIdError(`Session id "${sessionId}" looks like a bare timestamp. Use YYYY-MM-DD-<kebab-slug>.`);
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(sessionId)) {
+        throw new InvalidSessionIdError(`Session id "${sessionId}" is a bare date. Append a 2-5 word topic slug (e.g. "${sessionId}-add-user-auth").`);
+    }
+    if (!SESSION_ID_PATTERN.test(sessionId)) {
+        throw new InvalidSessionIdError(`Session id "${sessionId}" must match YYYY-MM-DD-<kebab-slug>, all lowercase, dashes only.`);
+    }
+    const suffix = sessionId.slice(11); // strip "YYYY-MM-DD-"
+    if (PROHIBITED_SUFFIXES.includes(suffix)) {
+        throw new InvalidSessionIdError(`Session id suffix "${suffix}" is a generic placeholder. Use a real topic slug (e.g. "add-user-auth", "v3-indicator-model").`);
+    }
+}
+export async function initWorkspace(options) {
+    validateSessionId(options.sessionId);
+    // Phase 6 refactor (slice 2026-06-05-change-id-as-unit-of-work) +
+    // slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs) +
+    // slice 2026-06-22-top-level-change-id-cleanup (2.8.3):
+    //   - Reviewable artifacts (rd/, qa/, prd/, txt/) live at
+    //     `.peaks/_runtime/<change-id>/<role>/` (tracked in git) when a change-id
+    //     is given. The role subdirs are NOT pre-created — the writer
+    //     (e.g. `peaks request init`, `peaks rd`) creates the parent
+    //     dirs on demand via `mkdirSync(..., { recursive: true })`.
+    //   - The session dir `.peaks/_runtime/<session-id>/` (gitignored)
+    //     now holds ONLY the canonical `session.json` metadata. The
+    //     F3-introduced `system/` subdir is gone — slice 006 removes
+    //     it via `peaks workspace reconcile`; new init calls do not
+    //     pre-create it.
+    //   - The change-id dir is NOT created at top level when `--change-id`
+    //     is given. Slice 2.8.3+ redirects the binding to
+    //     `.peaks/_runtime/current-change` as a plain text file (see
+    //     `LegacyChangeIdSiblingError` for the migration guard). Reviewable
+    //     artifacts still land under `.peaks/_runtime/<sessionId>/<role>/`, but
+    //     that dir is created lazily by the WRITER, not by init. Init only
+    //     writes the binding.
+    //
+    // The CLI accepts `--change-id <id>` to bind the change. The legacy
+    // session-scoped layout (`.peaks/_runtime/<session-id>/<role>/<file>`) is
+    // no longer used by writes; pre-1.3.1 trees get their session
+    // files migrated to the change-id dir by `peaks workspace reconcile`.
+    const runtimeRoot = join(options.projectRoot, '.peaks', '_runtime');
+    const sessionRoot = join(runtimeRoot, options.sessionId);
+    const created = [];
+    const alreadyExisted = [];
+    // 1. Create the session dir (canonical location `.peaks/_runtime/<sid>/`)
+    //    with NO subdirs. The session dir is gitignored; the role
+    //    subdirs and the `system/` subdir are gone entirely (slice 006).
+    if (await isDirectory(sessionRoot)) {
+        alreadyExisted.push('.');
+    }
+    else {
+        await mkdir(sessionRoot, { recursive: true });
+        created.push('.');
+    }
+    // 1a. Write the per-session metadata file. Slice 006 makes
+    //     `.peaks/_runtime/<sid>/session.json` the durable session
+    //     metadata (the body's source of truth, the `peaks workspace
+    //     reconcile` discovery source). The file is created on first
+    //     init and refreshed on every subsequent init. Idempotent.
+    setSessionMeta(options.projectRoot, options.sessionId, {});
+    // 2. Slice 2026-06-29-change-id-root-removal: the change-id axis is
+    //    gone. The session id IS the binding — there is no separate
+    //    `.peaks/_runtime/current-change` file. The v2.8.3 hard-ban on
+    //    `.peaks/<YYYY-MM-DD-*>/` siblings still fires via the inline
+    //    `lstatSync` block below, scoped to legacy residue
+    //    directories (NOT the canonical session dir, which lives at
+    //    `.peaks/_runtime/<sid>/`).
+    //
+    //    Pre-flight guard: refuse to silently walk into a date-stamped
+    //    sibling dir at the `.peaks/` top level. `lstatSync`
+    //    distinguishes file/dir/symlink/broken-symlink. ENOENT (path
+    //    absent) is the legitimate outcome. The guard fires ONLY on
+    //    date-stamped sibling dirs at `.peaks/<date-stamped>/` —
+    //    NOT on the canonical session dir at `.peaks/_runtime/<sid>/`,
+    //    which is a legitimate in-flight or completed session.
+    for (const entry of listPeaksRuntimeSiblings(options.projectRoot)) {
+        if (entry === '_runtime')
+            continue; // canonical session dir layer
+        if (!isDateStampedSiblingId(entry))
+            continue;
+        const legacySiblingDir = join(options.projectRoot, '.peaks', entry);
+        let legacyStat;
+        try {
+            legacyStat = lstatSync(legacySiblingDir);
+        }
+        catch {
+            // ENOENT or transient — accept.
+            continue;
+        }
+        if (!legacyStat.isDirectory())
+            continue;
+        if (legacyStat.isSymbolicLink()) {
+            // A symlink AT a date-stamped sibling path is unambiguous
+            // evasion — even if the target is writer-shaped, refuse.
+            throw new LegacyChangeIdSiblingError(entry, legacySiblingDir);
+        }
+        const shapeOk = isWriterCreatedSiblingShape(legacySiblingDir);
+        if (!shapeOk) {
+            throw new LegacyChangeIdSiblingError(entry, legacySiblingDir);
+        }
+        // Writer-shaped content: silently tolerate. No binding file is
+        // written (the change-id binding store is gone).
+    }
+    // 4. Bind this session as the project's current one.
+    //
+    // Single source of truth: `peaks workspace init` is the only CLI entry point
+    // that takes an explicit --session-id, so it owns the binding to .session.json.
+    // Without this write, downstream commands that fall through to
+    // `ensureSession()` would auto-generate a *different* id and create a second
+    // session directory — the bug that confuses the LLM in peaks-code.
+    //
+    // Conflict rule: if .session.json already points at a different session
+    // whose directory is real (has session.json inside), the caller is starting
+    // a parallel session without closing the previous one. Refuse to bind —
+    // this is the "strict" mode the user picked. The user must finish or delete
+    // the existing session first.
+    const existingSessionId = getSessionId(options.projectRoot);
+    let previousSessionId = null;
+    let bound = false;
+    if (existingSessionId === null) {
+        // No prior binding — adopt the requested id.
+        setCurrentSessionBinding(options.projectRoot, options.sessionId);
+        bound = true;
+    }
+    else if (existingSessionId === options.sessionId) {
+        // Already bound to the same id — idempotent.
+        bound = true;
+    }
+    else {
+        // Different id already bound. The existing session is "real" if its
+        // directory is non-empty — that holds the user's data (rd/, qa/, ui/,
+        // etc.) regardless of whether the per-session metadata file is present.
+        // Refuse to rebind without explicit authorization.
+        previousSessionId = existingSessionId;
+        const existingSessionDir = join(runtimeRoot, existingSessionId);
+        if (await isDirectory(existingSessionDir) && !options.allowSessionRebind) {
+            const { readdirSync } = await import('node:fs');
+            const entries = readdirSync(existingSessionDir);
+            if (entries.length > 0) {
+                throw new ConflictingSessionError(`Project is already bound to session "${existingSessionId}". ` +
+                    `Cannot start session "${options.sessionId}" without closing the previous one. ` +
+                    `Either finish/abandon the prior session first, or pass --allow-session-rebind to override.`, existingSessionId, options.sessionId);
+            }
+        }
+        // Either: existing session dir is empty (true leftover, no user data),
+        // or the caller explicitly authorised a rebind. Overwrite.
+        setCurrentSessionBinding(options.projectRoot, options.sessionId);
+        bound = true;
+    }
+    // Slice 2026-06-16-peaks-code-auto-scaffold (RD#7):
+    //   - Always run the detector and surface the descriptor so the CLI can
+    //     put it on stderr + into the JSON envelope's `data.standardsMissing`.
+    //   - When `initStandards: true` AND the detector reports missing, run
+    //     `executeProjectStandardsInit({ apply: true })` to auto-apply.
+    const detectedLanguage = options.language ?? detectLanguage(options.projectRoot);
+    const standardsMissing = detectMissingProjectStandards(options.projectRoot, detectedLanguage);
+    let standardsApplied;
+    if (options.initStandards === true && standardsMissing.missing) {
+        const initResult = executeProjectStandardsInit({
+            projectRoot: options.projectRoot,
+            apply: true
+        });
+        standardsApplied = {
+            language: initResult.language,
+            writtenFiles: initResult.writtenFiles,
+            skippedFiles: initResult.plannedWrites
+                .filter((write) => write.status === 'existing')
+                .map((write) => write.relativePath)
+        };
+    }
+    return {
+        sessionId: options.sessionId,
+        sessionRoot,
+        created,
+        alreadyExisted,
+        bound,
+        previousSessionId,
+        claudeSettings: await materializeClaudeSettingsLocal(options.projectRoot, options.noClaudeHooks === true),
+        standardsMissing,
+        ...(standardsApplied !== undefined ? { standardsApplied } : {})
+    };
+}
+// Re-export the consumer `.claude/settings.local.json` materialization
+// surface so external callers (CLI, tests) keep importing from this
+// module unchanged. The 3 helpers (`materializeClaudeSettingsLocal`,
+// `writeOfflineTemplateCopy`, `upsertPeaksGitignoreSnippet`) and the
+// `PEAKS_GITIGNORE_*` constants live in the sibling
+// `workspace-claude-settings-materializer.ts` module — see v2.18.3
+// file-split for the rationale. Function signatures and behaviour
+// are unchanged (verbatim move).
+import { materializeClaudeSettingsLocal } from './workspace-claude-settings-materializer.js';
+export { materializeClaudeSettingsLocal } from './workspace-claude-settings-materializer.js';
+/**
+ * Slice C10 (2026-06-24-legacy-change-id-sibling): whole-dir shape check
+ * for the legacy sibling `.peaks/_runtime/<sessionId>/`. Returns `true` ONLY when
+ * every leaf path under the sibling matches one of
+ * `WRITER_ALLOWED_RELATIVE_PATTERNS` AND no entry is a symlink (anywhere
+ * in the tree).
+ *
+ * Heuristic rationale (Karpathy #1 — name the tradeoff):
+ *   - False negative (reject writer-shaped content): we accept this
+ *     failure mode because it preserves the 2.8.3+ hard ban. The user
+ *     gets a clear migration message and can re-run after deleting the
+ *     sibling dir.
+ *   - False positive (accept legacy residue as writer output): we
+ *     REJECT this failure mode by requiring EVERY entry to match the
+ *     writer-allowed shape. One mismatched leaf ⇒ `false`. The whole-dir
+ *     check is conservative on purpose.
+ *
+ * Symlink rejection (Karpathy #3 — surgical): any symlinked entry — at
+ * the root or nested — returns `false` immediately. A symlinked
+ * `.peaks/_runtime/<sessionId>/qa/foo.png` could otherwise bypass the file-extension
+ * check by resolving to user content outside the project.
+ *
+ * Implementation note: the helper is synchronous and uses `lstatSync`
+ * recursively so the caller (the guard in `initWorkspace`) can decide
+ * inline without paying an async round-trip. Tree depth is bounded by
+ * the writer's mkdir pattern (≤3 levels: `<role>/<subdir>/<file>`).
+ * We cap the recursion at 8 levels as a defense-in-depth limit.
+ */
+export function isWriterCreatedSiblingShape(siblingDir) {
+    const MAX_DEPTH = 8;
+    const stack = [
+        { abs: siblingDir, rel: '', depth: 0 }
+    ];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node === undefined)
+            break;
+        if (node.depth > MAX_DEPTH) {
+            // Pathological depth — reject. The writer never goes this deep.
+            return false;
+        }
+        let stat;
+        try {
+            stat = lstatSync(node.abs);
+        }
+        catch {
+            // Any lstat failure (broken symlink, EACCES, etc.) ⇒ not
+            // writer-shaped. Be conservative.
+            return false;
+        }
+        if (stat.isSymbolicLink()) {
+            // Symlink anywhere — reject.
+            return false;
+        }
+        if (stat.isDirectory()) {
+            let entries;
+            try {
+                entries = readdirSync(node.abs);
+            }
+            catch {
+                return false;
+            }
+            if (entries.length === 0) {
+                if (node.depth === 0) {
+                    // The top-level sibling dir is empty — no writer output.
+                    // Reject: an empty `.peaks/<YYYY-MM-DD-*>/` dir is the most
+                    // common legacy residue shape (the user mkdir'd it then
+                    // forgot). The writer never creates an empty top-level
+                    // dir; it always writes at least one file.
+                    return false;
+                }
+                // Nested empty subdir under the sibling is fine — writer
+                // creates parent dirs lazily and may leave a placeholder
+                // behind. Skip.
+                continue;
+            }
+            for (const entry of entries) {
+                stack.push({
+                    abs: join(node.abs, entry),
+                    rel: node.rel.length > 0 ? `${node.rel}/${entry}` : entry,
+                    depth: node.depth + 1
+                });
+            }
+            continue;
+        }
+        if (stat.isFile()) {
+            const rel = node.rel.replace(/\\/g, '/');
+            const matches = WRITER_ALLOWED_RELATIVE_PATTERNS.some((re) => re.test(rel));
+            if (!matches) {
+                return false;
+            }
+            continue;
+        }
+        // Sockets, FIFOs, devices, etc. — not writer-shaped.
+        return false;
+    }
+    return true;
+}

package/dist/services/workspace/workspace-state-service.d.ts

@@ -0,0 +1,7 @@
+export declare function isLegacyDecisionDotfile(name: string): boolean;
+export declare function stateDirPath(projectRoot: string): string;
+export interface CollectResult {
+    moved: string[];
+    skipped: string[];
+}
+export declare function collectLegacyDecisionDotfiles(projectRoot: string): CollectResult;

package/dist/services/workspace/workspace-state-service.js

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, renameSync } from 'node:fs';
+import { join, posix } from 'node:path';
+/**
+ * Spec §8.4 + §8.5 — `.peaks/_state/` collects one-time decision dotfiles.
+ * Migrates from legacy `.peaks/_runtime/<name>` flat layout.
+ *
+ * `stateDirPath` returns a POSIX-normalized logical path so callers and tests
+ * can compare against a platform-independent string (the .peaks tree is a
+ * config key, not a direct fs call). `mkdirSync` / `renameSync` below use
+ * the platform-native `join` so files actually land on disk.
+ */
+const LEGACY_DOTFILES = [
+    '.peaks-init-hooks-decision.json',
+    '.peaks-openspec-opt-in.json',
+];
+const STATE_DIR_NAME = '_state';
+export function isLegacyDecisionDotfile(name) {
+    return LEGACY_DOTFILES.includes(name);
+}
+export function stateDirPath(projectRoot) {
+    return posix.join(projectRoot, '.peaks', STATE_DIR_NAME);
+}
+export function collectLegacyDecisionDotfiles(projectRoot) {
+    const peaksDir = join(projectRoot, '.peaks');
+    // Use the platform-native join for actual filesystem operations;
+    // `stateDirPath` (POSIX) is only the public/portable surface for callers.
+    const stateDir = join(projectRoot, '.peaks', STATE_DIR_NAME);
+    mkdirSync(stateDir, { recursive: true });
+    const moved = [];
+    const skipped = [];
+    for (const name of LEGACY_DOTFILES) {
+        const from = join(peaksDir, name);
+        const to = join(stateDir, name);
+        if (!existsSync(from))
+            continue;
+        if (existsSync(to)) {
+            throw new Error(`DOTFILE_COLLISION: ${name} already exists in ${stateDir} (${readFileSync(to, 'utf8').length} bytes); refusing to overwrite`);
+        }
+        renameSync(from, to);
+        moved.push(name);
+    }
+    return { moved, skipped };
+}

package/dist/services/worktree/worktree-lease.d.ts

@@ -0,0 +1,170 @@
+/**
+ * worktree-lease — pure-function lease store for `peaks worktree spawn`.
+ *
+ * Slice 2026-07-29-worktree-l2-extended Part 1. This is the Layer 2
+ * governance complement to Layer 3 (`permissions.deny` for the superpowers
+ * chain) and Layer 1 (sub-agent dispatch prompt refusal). Together the
+ * three layers close the superpowers-chain jailbreak that previously
+ * bypassed peaks-loop's worktree posture.
+ *
+ * The store is a pure function module: every helper takes the lease
+ * directory path as an argument and returns structured data. Atomic
+ * filesystem writes happen at the call site (CLI command), keeping the
+ * helpers trivially testable. The CLI surface lives in
+ * `src/cli/commands/worktree-spawn-commands.ts`.
+ *
+ * Why a separate lease (vs reusing `peaks worktree auth grant`):
+ * - `auth grant` is a single-shot, short-lived token file consulted by
+ *   the PreToolUse hook BEFORE `git worktree add` runs. It answers
+ *   "is the LLM allowed to do this right now?"
+ * - `lease` is a long-lived lifecycle object that owns the worktree
+ *   path, branch, expiry, and consumption log. It answers
+ *   "what worktrees does this session own, and which are still alive?"
+ * The two coexist: `spawn` writes a lease; the lease's existence
+ * implicitly authorizes worktree operations on its path (the hook
+ * integration is Part 2 of this slice).
+ */
+/**
+ * Per-role default TTL. Sub-agent dispatch duration varies by role:
+ * - rd (long planning + impl) → 30 min
+ * - qa (test design + browser validation) → 15 min
+ * - ui (high-fidelity prototype iteration) → 1 h
+ * - txt (handoff capsule, no worktree expected) → n/a (no worktree)
+ * - general-purpose / unknown → 30 min (rd-like)
+ *
+ * Users MAY override with `--ttl <duration>` (e.g. `--ttl 4h`).
+ */
+export declare const DEFAULT_TTL_BY_ROLE: Readonly<Record<string, number>>;
+export declare const DEFAULT_TTL_MS: number | undefined;
+export type WorktreeLeaseStatus = 'active' | 'released' | 'expired' | 'gc';
+export interface WorktreeLease {
+    /** Random 16-hex lease id; emitted to the operator as the lease handle. */
+    readonly leaseId: string;
+    /** The peaks request id (rid) that the lease was spawned for. */
+    readonly rid: string;
+    /** Sub-agent role (rd | qa | ui | sc | prd | general-purpose | ...). */
+    readonly role: string;
+    /** Absolute worktree path on disk (under .peaks/_runtime/<sid>/worktrees/<leaseId>/). */
+    readonly path: string;
+    /** Branch name (one of the worktree's --branch / -b args). */
+    readonly branch: string;
+    /** Unix epoch ms when the lease was created. */
+    readonly createdAt: number;
+    /** Unix epoch ms when the lease expires. */
+    readonly expiresAt: number;
+    /** Operator-supplied purpose text (audit log). */
+    readonly purpose: string;
+    /** Lifecycle status; updated by `releaseLease` / `markExpired`. */
+    readonly status: WorktreeLeaseStatus;
+    /** Sub-agent batch / dispatch ids that have consumed this lease. */
+    readonly consumedBySubAgents: ReadonlyArray<string>;
+}
+/** Subset of WorktreeLease that the CLI writes on creation. Status starts at 'active'. */
+export type WorktreeLeaseDraft = Omit<WorktreeLease, 'status' | 'consumedBySubAgents'>;
+/**
+ * Compose a deterministic lease path under the per-session runtime dir.
+ * The function is pure: same inputs → same output. The caller passes
+ * `<sessionId>` (NOT a bare `<sid>` per the 2.7.1 single-scope-axis rule).
+ *
+ * Path layout:
+ *   .peaks/_runtime/<sessionId>/worktree-leases/<leaseId>.json
+ *
+ * The `worktree-leases/` directory is gitignored per the .peaks/_runtime/
+ * rule (committed in .gitignore for all runtime artifacts).
+ */
+export declare function leaseStoreDir(sessionRuntimeDir: string): string;
+export declare function leaseFilePath(sessionRuntimeDir: string, leaseId: string): string;
+/**
+ * Compose the absolute worktree path (the `git worktree add <path>` target).
+ * Sits adjacent to the lease file under the same runtime dir.
+ */
+export declare function worktreePath(sessionRuntimeDir: string, leaseId: string): string;
+/**
+ * Generate a 16-hex lease id (8 random bytes, hex-encoded). The id is
+ * unique enough for the per-session scope; collisions across sessions
+ * are irrelevant because each session has its own lease directory.
+ */
+export declare function generateLeaseId(): string;
+/**
+ * Compute the TTL ms for a role, falling back to DEFAULT_TTL_MS for
+ * unknown roles. The CLI overrides with `--ttl <ms>` when the user
+ * passes a positive value.
+ */
+export declare function ttlForRole(role: string): number;
+/**
+ * Pure: produce a fresh `WorktreeLease` from a draft + status.
+ * `status` defaults to `'active'`; `consumedBySubAgents` defaults to [].
+ * Used by the CLI's atomicWriteJson call.
+ */
+export declare function finalizeLease(draft: WorktreeLeaseDraft): WorktreeLease;
+/** Pure: lease status transitions to 'released'. Returns a new lease. */
+export declare function markReleased(lease: WorktreeLease): WorktreeLease;
+/** Pure: lease status transitions to 'expired'. Returns a new lease. */
+export declare function markExpired(lease: WorktreeLease): WorktreeLease;
+/** Pure: lease status transitions to 'gc'. Returns a new lease. */
+export declare function markGc(lease: WorktreeLease): WorktreeLease;
+/** Pure: append a sub-agent batch / dispatch id to the consumption log. Returns a new lease. */
+export declare function recordConsumption(lease: WorktreeLease, subAgentId: string): WorktreeLease;
+/**
+ * Pure: is the lease still active (status === 'active' AND not past expiry).
+ * Expired leases are NOT auto-released; the gc CLI is the only path that
+ * transitions them to 'gc'. Until then, the on-disk state stays 'active'
+ * but `isLeaseActive` returns false so consumers skip the lease.
+ */
+export declare function isLeaseActive(lease: WorktreeLease, now?: number): boolean;
+/**
+ * Pure: read every lease file under the session's lease store dir.
+ * Returns leases in the order returned by `fs.readdir` (no sort).
+ * Malformed files are surfaced as `{ file, error }` records so the caller
+ * (the `list` CLI) can warn without aborting the whole list. Missing
+ * directory is not an error — it returns an empty leases array.
+ */
+export interface LeaseReadError {
+    readonly file: string;
+    readonly error: string;
+}
+export type LeaseListResult = {
+    readonly kind: 'ok';
+    readonly leases: ReadonlyArray<WorktreeLease>;
+    readonly errors: ReadonlyArray<LeaseReadError>;
+} | {
+    readonly kind: 'store-missing';
+    readonly storeDir: string;
+};
+/**
+ * List every lease file under the session's lease store dir.
+ *
+ * Pure with respect to its inputs: it does NOT sort or filter, and it
+ * does NOT mark anything expired. Callers (the `list` CLI) apply their
+ * own sort/filter and run `markExpired` lazily.
+ */
+export declare function listLeasesSync(storeDir: string, fs: {
+    readdir: (path: string) => ReadonlyArray<string>;
+    readFile: (path: string) => string;
+    existsSync: (path: string) => boolean;
+}): LeaseListResult;
+/**
+ * Pure: a lease is eligible for `gc` if its status is one of {released,
+ * expired} AND its worktree path is no longer attached to git (`git
+ * worktree list` would not include it). The CLI re-checks with git and
+ * uses this helper as a coarse pre-filter.
+ */
+export declare function isLeaseGcEligible(lease: WorktreeLease, now?: number): boolean;
+/**
+ * Pure: derive a new lease from an existing one with an extended
+ * `expiresAt`. Other fields are preserved. The CLI writes the new lease
+ * atomically. Used by `peaks worktree renew --lease-id <id> --ttl <ms>`.
+ */
+export declare function renewLease(lease: WorktreeLease, newExpiresAt: number): WorktreeLease;
+/**
+ * Pure: serialize a lease to JSON with stable field order (deterministic
+ * output for diff-friendly audit logs). The CLI passes the result to
+ * `atomicWriteJson`. The function does NOT mutate the input.
+ */
+export declare function serializeLease(lease: WorktreeLease): string;
+/**
+ * Pure: deserialize a lease from JSON. Throws on malformed input — the
+ * CLI catches and returns a `LEASE_FILE_INVALID` envelope (mirroring the
+ * `peaks worktree auth` FILE_INVALID convention).
+ */
+export declare function deserializeLease(raw: string): WorktreeLease;