peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/services/workflow/workflow-spec.js

@@ -19,8 +19,16 @@
  * pair. Anything more elaborate (e.g. conditionals on outputs) belongs
  * in a future minor.
  *
- * File budget: ≤ 800 lines (Karpathy §2).
+ * File budget: ≤ 400 lines (rid-006 split). This file now holds the
+ * parser + private constants + private build helpers; types live in
+ * `workflow-spec-types.ts`; YAML field helpers live in
+ * `workflow-spec-yaml.ts`; lint lives in `workflow-spec-lint.ts`.
+ * The re-export shim at the bottom preserves the original public
+ * surface so external callers (`workflow-loader.ts`,
+ * `loop-eval-commands.ts`, `evaluator-dispatcher.ts`) compile
+ * unchanged.
  */
+import { arrayField, leadingSpaces, numberField, objectField, parseScalar, stringArrayField, stringField } from './workflow-spec-yaml.js';
 const VALID_EVALUATORS = new Set([
     'karpathy',
     'code-review',
@@ -285,147 +293,10 @@ function buildEvaluator(raw) {
         ...(threshold !== undefined ? { threshold } : {})
     };
 }
-/** Lint a parsed spec — returns a report with semantic errors / warnings. */
-export function lintWorkflowSpec(spec) {
-    const errors = [];
-    const warnings = [];
-    // Phase ids must be unique.
-    const seen = new Set();
-    for (const phase of spec.phases) {
-        if (seen.has(phase.id))
-            errors.push(`duplicate phase id "${phase.id}"`);
-        seen.add(phase.id);
-    }
-    // Gate references in phases must exist in the gates list (or be a known
-    // built-in like "Gate B3").
-    const gateIds = new Set(spec.gates.map((g) => g.id));
-    for (const phase of spec.phases) {
-        for (const gateRef of phase.gates) {
-            if (!gateIds.has(gateRef) && !gateRef.startsWith('Gate ')) {
-                warnings.push(`phase "${phase.id}" references unknown gate "${gateRef}" (not in gates[] and not a built-in "Gate …" label)`);
-            }
-        }
-    }
-    // Evaluator gates must match a gate id when present.
-    for (const ev of spec.evaluators) {
-        if (ev.gate !== undefined && !gateIds.has(ev.gate) && !ev.gate.startsWith('Gate ')) {
-            warnings.push(`evaluator "${ev.type}" references unknown gate "${ev.gate}"`);
-        }
-    }
-    // dependsOn references must resolve.
-    const phaseIds = new Set(spec.phases.map((p) => p.id));
-    for (const phase of spec.phases) {
-        if (phase.dependsOn !== undefined) {
-            for (const dep of phase.dependsOn) {
-                if (!phaseIds.has(dep))
-                    errors.push(`phase "${phase.id}" depends on missing phase "${dep}"`);
-            }
-        }
-    }
-    // Parallel groups must contain ≥2 phases.
-    const groupCounts = new Map();
-    for (const phase of spec.phases) {
-        if (phase.parallelGroup !== undefined) {
-            groupCounts.set(phase.parallelGroup, (groupCounts.get(phase.parallelGroup) ?? 0) + 1);
-        }
-    }
-    for (const [group, count] of groupCounts) {
-        if (count < 2)
-            warnings.push(`parallelGroup "${group}" has only ${count} phase(s); parallelism requires ≥2`);
-    }
-    // Budget sanity.
-    if (spec.budget.cycles !== undefined && spec.budget.cycles < 1) {
-        errors.push(`budget.cycles must be ≥1 when set (got ${spec.budget.cycles})`);
-    }
-    if (spec.budget.tokens !== undefined && spec.budget.tokens < 1) {
-        errors.push(`budget.tokens must be ≥1 when set (got ${spec.budget.tokens})`);
-    }
-    if (spec.budget.wallSeconds !== undefined && spec.budget.wallSeconds < 1) {
-        errors.push(`budget.wallSeconds must be ≥1 when set (got ${spec.budget.wallSeconds})`);
-    }
-    return {
-        ok: errors.length === 0,
-        errors,
-        warnings,
-        normalizedSpec: spec
-    };
-}
-// ─── yaml helper primitives ─────────────────────────────────────────────
-function leadingSpaces(line) {
-    let n = 0;
-    for (const ch of line) {
-        if (ch === ' ')
-            n++;
-        else
-            break;
-    }
-    return n;
-}
-function parseScalar(raw) {
-    if (raw === '')
-        return '';
-    if (raw === 'true')
-        return true;
-    if (raw === 'false')
-        return false;
-    if (raw === 'null' || raw === '~')
-        return null;
-    // Inline array form `[a, b, c]`
-    if (raw.startsWith('[') && raw.endsWith(']')) {
-        const inner = raw.slice(1, -1).trim();
-        if (inner === '')
-            return [];
-        return inner.split(',').map((s) => parseScalar(s.trim()));
-    }
-    // Strip optional surrounding quotes.
-    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
-        return raw.slice(1, -1);
-    }
-    // Number?
-    if (/^-?\d+$/.test(raw))
-        return parseInt(raw, 10);
-    if (/^-?\d+\.\d+$/.test(raw))
-        return parseFloat(raw);
-    return raw;
-}
-function stringField(obj, key, fallback) {
-    const v = obj[key];
-    if (typeof v === 'string')
-        return v;
-    if (fallback !== undefined)
-        return fallback;
-    throw new Error(`workflow yaml: missing required string field "${key}"`);
-}
-function numberField(obj, key, fallback) {
-    const v = obj[key];
-    if (typeof v === 'number' && Number.isFinite(v))
-        return v;
-    if (fallback !== undefined)
-        return fallback;
-    throw new Error(`workflow yaml: missing required number field "${key}"`);
-}
-function arrayField(obj, key) {
-    const v = obj[key];
-    if (v === undefined)
-        return [];
-    if (!Array.isArray(v))
-        throw new Error(`workflow yaml: field "${key}" must be an array`);
-    return v;
-}
-function objectField(obj, key) {
-    const v = obj[key];
-    if (v === undefined)
-        return {};
-    if (v === null || typeof v !== 'object' || Array.isArray(v)) {
-        throw new Error(`workflow yaml: field "${key}" must be an object`);
-    }
-    return v;
-}
-function stringArrayField(obj, key) {
-    const v = obj[key];
-    if (v === undefined)
-        return [];
-    if (!Array.isArray(v))
-        throw new Error(`workflow yaml: field "${key}" must be an array of strings`);
-    return v.map((s) => String(s));
-}
+// ─── verbatim re-export shim (rid-006) ────────────────────────────────────
+// External callers (`workflow-loader.ts`, `loop-eval-commands.ts`,
+// `evaluator-dispatcher.ts`) import the public types and the lint
+// function from this module. Re-export them under their original names
+// so the call sites compile unchanged. The lint function moved to
+// `workflow-spec-lint.ts`; the types moved to `workflow-spec-types.ts`.
+export { lintWorkflowSpec } from './workflow-spec-lint.js';

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

@@ -1,7 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import { mkdir, readFile, readdir, rename, rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isDirectory, pathExists } from '../../shared/fs.js';
+import { isDirectory, pathExists } from 'peaks-loop-shared/fs';
 import { isPathInsideArtifactRoot } from '../../shared/path-safety.js';
 const ROLE_DIRS = new Set(['prd', 'ui', 'rd', 'qa', 'sc', 'system']);
 /** Top-level dirs in `.peaks/` that are NEVER legacy session dirs

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

@@ -1,7 +1,7 @@
 import { mkdir } from 'node:fs/promises';
 import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { isDirectory } from '../../shared/fs.js';
+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

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;

package/dist/services/worktree/worktree-lease.js

@@ -0,0 +1,242 @@
+/**
+ * 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).
+ */
+import { randomBytes } from 'node:crypto';
+import { posix as path } from 'node:path';
+/**
+ * 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 const DEFAULT_TTL_BY_ROLE = Object.freeze({
+    rd: 30 * 60 * 1_000,
+    qa: 15 * 60 * 1_000,
+    ui: 60 * 60 * 1_000,
+    sc: 30 * 60 * 1_000,
+    prd: 15 * 60 * 1_000,
+    general: 30 * 60 * 1_000
+});
+export const DEFAULT_TTL_MS = DEFAULT_TTL_BY_ROLE.rd;
+/**
+ * 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 function leaseStoreDir(sessionRuntimeDir) {
+    return joinPath(sessionRuntimeDir, 'worktree-leases');
+}
+export function leaseFilePath(sessionRuntimeDir, leaseId) {
+    return joinPath(leaseStoreDir(sessionRuntimeDir), `${leaseId}.json`);
+}
+/**
+ * Compose the absolute worktree path (the `git worktree add <path>` target).
+ * Sits adjacent to the lease file under the same runtime dir.
+ */
+export function worktreePath(sessionRuntimeDir, leaseId) {
+    return joinPath(sessionRuntimeDir, 'worktrees', leaseId);
+}
+/**
+ * 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 function generateLeaseId() {
+    return randomBytes(8).toString('hex');
+}
+/**
+ * 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 function ttlForRole(role) {
+    const normalized = role.toLowerCase();
+    const candidate = DEFAULT_TTL_BY_ROLE[normalized];
+    const fallback = DEFAULT_TTL_BY_ROLE['rd'] ?? 30 * 60 * 1_000;
+    return candidate ?? fallback;
+}
+/**
+ * Pure: produce a fresh `WorktreeLease` from a draft + status.
+ * `status` defaults to `'active'`; `consumedBySubAgents` defaults to [].
+ * Used by the CLI's atomicWriteJson call.
+ */
+export function finalizeLease(draft) {
+    return {
+        ...draft,
+        status: 'active',
+        consumedBySubAgents: []
+    };
+}
+/** Pure: lease status transitions to 'released'. Returns a new lease. */
+export function markReleased(lease) {
+    return { ...lease, status: 'released' };
+}
+/** Pure: lease status transitions to 'expired'. Returns a new lease. */
+export function markExpired(lease) {
+    return { ...lease, status: 'expired' };
+}
+/** Pure: lease status transitions to 'gc'. Returns a new lease. */
+export function markGc(lease) {
+    return { ...lease, status: 'gc' };
+}
+/** Pure: append a sub-agent batch / dispatch id to the consumption log. Returns a new lease. */
+export function recordConsumption(lease, subAgentId) {
+    if (lease.consumedBySubAgents.includes(subAgentId))
+        return lease;
+    return { ...lease, consumedBySubAgents: [...lease.consumedBySubAgents, subAgentId] };
+}
+/**
+ * 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 function isLeaseActive(lease, now = Date.now()) {
+    return lease.status === 'active' && lease.expiresAt > now;
+}
+/**
+ * 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 function listLeasesSync(storeDir, fs) {
+    if (!fs.existsSync(storeDir)) {
+        return { kind: 'store-missing', storeDir };
+    }
+    const files = fs.readdir(storeDir).filter((f) => f.endsWith('.json'));
+    const leases = [];
+    const errors = [];
+    for (const f of files) {
+        const file = `${storeDir.replace(/[\\/]+$/, '')}/${f}`;
+        try {
+            leases.push(deserializeLease(fs.readFile(file)));
+        }
+        catch (err) {
+            errors.push({ file, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return { kind: 'ok', leases, errors };
+}
+/**
+ * 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 function isLeaseGcEligible(lease, now = Date.now()) {
+    if (lease.status === 'gc')
+        return false;
+    if (lease.status === 'released')
+        return true;
+    // status === 'active' but past expiry → treat as expired candidate
+    return lease.expiresAt <= now;
+}
+/**
+ * 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 function renewLease(lease, newExpiresAt) {
+    return { ...lease, expiresAt: newExpiresAt, status: 'active' };
+}
+/**
+ * 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 function serializeLease(lease) {
+    return JSON.stringify(lease, null, 2) + '\n';
+}
+/**
+ * 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 function deserializeLease(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('lease file must contain a JSON object');
+    }
+    const obj = parsed;
+    if (typeof obj.leaseId !== 'string')
+        throw new Error('leaseId missing');
+    if (typeof obj.rid !== 'string')
+        throw new Error('rid missing');
+    if (typeof obj.role !== 'string')
+        throw new Error('role missing');
+    if (typeof obj.path !== 'string')
+        throw new Error('path missing');
+    if (typeof obj.branch !== 'string')
+        throw new Error('branch missing');
+    if (typeof obj.createdAt !== 'number')
+        throw new Error('createdAt missing');
+    if (typeof obj.expiresAt !== 'number')
+        throw new Error('expiresAt missing');
+    if (typeof obj.purpose !== 'string')
+        throw new Error('purpose missing');
+    if (typeof obj.status !== 'string')
+        throw new Error('status missing');
+    if (!Array.isArray(obj.consumedBySubAgents))
+        throw new Error('consumedBySubAgents missing');
+    return {
+        leaseId: obj.leaseId,
+        rid: obj.rid,
+        role: obj.role,
+        path: obj.path,
+        branch: obj.branch,
+        createdAt: obj.createdAt,
+        expiresAt: obj.expiresAt,
+        purpose: obj.purpose,
+        status: obj.status,
+        consumedBySubAgents: obj.consumedBySubAgents
+    };
+}
+/** Internal: normalize a path segment to forward slashes (Windows
+ *  callers pass `C:\Users\...`; posix.join sees the backslash and
+ *  silently mangles). Then posix-join. The CLI uses the same module
+ *  so reads + writes always agree. */
+function joinPath(...segments) {
+    if (segments.length === 0)
+        return '';
+    const normalized = segments.map((s) => s.replace(/\\/g, '/'));
+    let acc = normalized[0];
+    for (let i = 1; i < normalized.length; i++) {
+        acc = path.join(acc, normalized[i]);
+    }
+    return acc;
+}