@paths.design/caws-cli 11.0.0 → 11.1.0

package/dist/shell/render/init-hook-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-hook-pack.d.ts","sourceRoot":"","sources":["../../../src/shell/render/init-hook-pack.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAWzE,iCAAiC;AACjC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,GAC5B,MAAM,CAkGR;AAED,yDAAyD;AACzD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CA0ER;AAED;;;;;;;gDAOgD;AAChD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,EAC7B,YAAY,CAAC,EAAE,oBAAoB,GAClC,MAAM,CAyFR"}

package/dist/shell/render/init-hook-pack.js

@@ -0,0 +1,206 @@
+"use strict";
+// Pure formatter for hook-pack install output and settings.json wiring
+// guidance. Each step of `caws init` emits a labeled section so an
+// agent reading the output turn-by-turn can pick up what happened and
+// what to do next.
+//
+// This renderer never decides outcomes; install/inspect decide.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderHookPackInstall = renderHookPackInstall;
+exports.renderSettingsWiring = renderSettingsWiring;
+exports.renderActivationContract = renderActivationContract;
+const hook_install_1 = require("../../init/hook-install");
+function repeatChar(ch, n) {
+    return ch.repeat(Math.max(0, n));
+}
+function section(title) {
+    const bar = repeatChar('─', 64);
+    return `\n┌${bar}\n│ ${title}\n└${bar}`;
+}
+/** Render the install result. */
+function renderHookPackInstall(result) {
+    const lines = [];
+    if (!result.pack) {
+        if (result.outcome === 'skipped_explicit_none') {
+            lines.push(section('Step: hook-pack install'));
+            lines.push('  Skipped — --agent-surface none.');
+            lines.push('  No pre-tool-call governance was installed.');
+            lines.push('  This repo is NOT agent-safe for multi-session work without external governance.');
+            lines.push('  If you intended to enable a hook pack, rerun with --agent-surface claude-code.');
+            return lines.join('\n');
+        }
+        if (result.outcome === 'skipped_ambiguous') {
+            lines.push(section('Step: hook-pack install'));
+            lines.push('  Skipped — no harness detected and no --agent-surface flag passed.');
+            lines.push('  No pre-tool-call governance was installed.');
+            lines.push('  To enable a hook pack now, rerun with one of:');
+            lines.push('    caws init --agent-surface claude-code');
+            lines.push('    caws init --agent-surface none      # explicit opt-out');
+            return lines.join('\n');
+        }
+    }
+    const pack = result.pack;
+    lines.push(section(`Step: hook-pack install (${pack.id} v${pack.packVersion})`));
+    lines.push(`  ${pack.summary}`);
+    lines.push('');
+    // Per-file action lines.
+    const created = [];
+    const updated = [];
+    const unchanged = [];
+    const refused = [];
+    for (const a of result.actions) {
+        switch (a.action) {
+            case 'created':
+                created.push(a.destPath);
+                break;
+            case 'updated':
+                updated.push(a.destPath);
+                break;
+            case 'unchanged':
+                unchanged.push(a.destPath);
+                break;
+            case 'refused':
+                refused.push(`${a.destPath}  [refused: ${a.refusalReason ?? 'unknown'}]`);
+                break;
+        }
+    }
+    if (created.length > 0) {
+        lines.push(`  Created (${created.length}):`);
+        for (const p of created)
+            lines.push(`    + ${p}`);
+    }
+    if (updated.length > 0) {
+        lines.push(`  Updated (${updated.length}):`);
+        for (const p of updated)
+            lines.push(`    ↑ ${p}`);
+    }
+    if (unchanged.length > 0) {
+        lines.push(`  Unchanged (${unchanged.length}):`);
+        for (const p of unchanged)
+            lines.push(`    = ${p}`);
+    }
+    if (refused.length > 0) {
+        lines.push(`  Refused (${refused.length}):`);
+        for (const p of refused)
+            lines.push(`    ! ${p}`);
+        lines.push('');
+        lines.push('  One or more files were refused. To resolve, choose one of:');
+        lines.push('    --overwrite   Replace the file with the canonical pack version.');
+        lines.push('                  CAUTION: local edits to that file will be lost.');
+        lines.push('    --adopt       Leave the file in place; do not enforce that it');
+        lines.push('                  matches the pack. CAUTION: pack drift is no longer');
+        lines.push('                  tracked for this file until the marker is restored.');
+        lines.push('  Alternative: rename or remove the conflicting file, then re-run init.');
+    }
+    return lines.join('\n');
+}
+/** Render the settings.json wiring inspection result. */
+function renderSettingsWiring(status) {
+    const lines = [];
+    lines.push(section('Step: .claude/settings.json wiring'));
+    if (status.kind === 'wired') {
+        lines.push('  OK — .claude/settings.json already wires all four CAWS dispatch entrypoints.');
+        lines.push('  No action needed.');
+        return lines.join('\n');
+    }
+    if (status.kind === 'invalid') {
+        lines.push(`  ERROR — .claude/settings.json exists but could not be parsed: ${status.error}`);
+        lines.push('  Repair the JSON syntax, then re-run `caws doctor` to verify.');
+        lines.push('  The CAWS init does NOT modify settings.json; you must fix this by hand.');
+        return lines.join('\n');
+    }
+    if (status.kind === 'absent') {
+        lines.push('  No .claude/settings.json present. Hooks are installed but will');
+        lines.push('  NOT fire until Claude Code reads a settings.json that wires them.');
+        lines.push('');
+        lines.push('  init does not write this file directly because merging with your');
+        lines.push('  existing permissions, env, and hook entries is your responsibility.');
+        lines.push('');
+        lines.push('  Create .claude/settings.json with the following content:');
+        lines.push('');
+        for (const line of hook_install_1.CANONICAL_SETTINGS_SNIPPET.split('\n')) {
+            lines.push(`    ${line}`);
+        }
+        return lines.join('\n');
+    }
+    // partial
+    lines.push('  .claude/settings.json exists but is missing one or more canonical');
+    lines.push('  CAWS hook entries. Hooks may not fire as expected.');
+    lines.push('');
+    lines.push(`  Missing entries (${status.missing.length}): ${status.missing.join(', ')}`);
+    lines.push('');
+    lines.push('  Add the following blocks to the `hooks` object in your settings.json:');
+    lines.push('');
+    for (const line of hook_install_1.CANONICAL_SETTINGS_SNIPPET.split('\n')) {
+        lines.push(`    ${line}`);
+    }
+    lines.push('');
+    lines.push('  CAWS init does NOT modify settings.json automatically — it');
+    lines.push('  commonly carries user-authored `permissions` and `env` blocks that');
+    lines.push('  the pack should not overwrite. Merge the snippet by hand.');
+    return lines.join('\n');
+}
+/** Render the activation contract. Drives what the agent should do
+ *  immediately after init. The message tailors to three signals:
+ *  - did this run actually install or update files? (changed vs no-op)
+ *  - is settings.json wired? (only known when caller passes wiringStatus)
+ *  - what is the harness's activation model? (from pack)
+ *
+ *  Without these signals the panel becomes a constant STOP sign on every
+ *  re-run, which trains agents to ignore it. */
+function renderActivationContract(result, wiringStatus) {
+    const lines = [];
+    lines.push(section('Step: activation'));
+    if (!result.pack || result.outcome === 'skipped_explicit_none') {
+        lines.push('  No hook pack was installed. Pre-tool-call governance is NOT in effect.');
+        return lines.join('\n');
+    }
+    if (result.outcome === 'skipped_ambiguous') {
+        lines.push('  No hook pack was selected. Pre-tool-call governance is NOT in effect.');
+        return lines.join('\n');
+    }
+    const changed = result.outcome === 'installed' || result.outcome === 'updated';
+    const wired = wiringStatus?.kind === 'wired';
+    switch (result.activation) {
+        case 'immediate':
+            lines.push('  Hooks are active in the current session. No restart required.');
+            break;
+        case 'restart_required':
+            if (!changed && wired) {
+                // No-op re-run on a fully-wired install. Positive confirmation.
+                lines.push('  Hooks are installed and wired. They are active in any Claude Code');
+                lines.push('  session started AFTER the install. If you are running in a session');
+                lines.push('  that pre-dates the install, restart the session to load them.');
+            }
+            else if (changed && wired) {
+                // Files updated; wiring is already in place but the new versions
+                // need a session restart to load.
+                lines.push('  Hook files were installed or updated. Settings.json is wired.');
+                lines.push('  Restart the Claude Code session so the updated hooks load.');
+            }
+            else if (changed && !wired) {
+                // The original STOP-sign case. Files just landed AND wiring is
+                // missing or partial. Agent must not continue.
+                lines.push('  RESTART REQUIRED: Claude Code reads .claude/settings.json at session');
+                lines.push('  start. The hooks you just installed are NOT enforcing in this session.');
+                lines.push('');
+                lines.push('  STOP. Do not continue substantive work. Wire .claude/settings.json');
+                lines.push('  (see the previous panel) and ask the user to restart or reopen');
+                lines.push('  the Claude Code session so the hooks become active.');
+            }
+            else {
+                // Idempotent re-run with wiring still missing or invalid.
+                lines.push('  Hook files are installed but settings.json wiring is not complete.');
+                lines.push('  Hooks will not fire until the wiring is finished (see the previous');
+                lines.push('  panel) and the Claude Code session is restarted.');
+            }
+            break;
+        case 'unknown':
+        case 'not_applicable':
+            lines.push('  Activation semantics for this harness are not known. Consult the');
+            lines.push('  harness documentation for whether hooks take effect mid-session.');
+            break;
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=init-hook-pack.js.map

package/dist/shell/render/init-hook-pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-hook-pack.js","sourceRoot":"","sources":["../../../src/shell/render/init-hook-pack.ts"],"names":[],"mappings":"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"}

package/dist/store/atomic-write.d.ts

@@ -1,11 +1,29 @@
 import { type Result } from '@paths.design/caws-kernel';
+export interface WriteFileAtomicOptions {
+    /**
+     * When true and `targetPath` exists, the temp file is created with the
+     * target's existing mode, and the final on-disk file has the same mode
+     * after rename. Used by the lifecycle substrate to preserve the
+     * executable bit on managed hook scripts.
+     *
+     * When false (default), the temp file is created with the standard
+     * `'w'` mode (0o666 masked by umask). This preserves the historical
+     * behavior of writeFileAtomic so existing callers are not silently
+     * affected.
+     *
+     * When `targetPath` does NOT exist, this option has no effect; the
+     * file is created with the default mode regardless.
+     */
+    readonly preserveMode?: boolean;
+}
 /**
  * Write `contents` to `targetPath` atomically.
  *
  * On Err, the temp file is cleaned up. On Ok, the target file holds the
- * new bytes.
+ * new bytes. When `options.preserveMode` is true and the target exists,
+ * the new file has the same mode bits as the prior file.
  */
-export declare function writeFileAtomic(targetPath: string, contents: string | Buffer): Result<true>;
+export declare function writeFileAtomic(targetPath: string, contents: string | Buffer, options?: WriteFileAtomicOptions): Result<true>;
 /**
  * Best-effort parent-directory fsync. Returns true on success, false on
  * failure (some filesystems / platforms don't support it). Callers that

package/dist/store/atomic-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../../src/store/atomic-write.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAajE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAgC3F;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAiBjD"}
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../../src/store/atomic-write.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAajE,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAAC,IAAI,CAAC,CA4Ed;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAiBjD"}

package/dist/store/atomic-write.js

@@ -66,18 +66,60 @@ function nextTempName(targetPath) {
  * Write `contents` to `targetPath` atomically.
  *
  * On Err, the temp file is cleaned up. On Ok, the target file holds the
- * new bytes.
+ * new bytes. When `options.preserveMode` is true and the target exists,
+ * the new file has the same mode bits as the prior file.
  */
-function writeFileAtomic(targetPath, contents) {
+function writeFileAtomic(targetPath, contents, options = {}) {
     const tmpPath = nextTempName(targetPath);
     let fd;
+    // When preserveMode is requested, stat the target BEFORE the temp
+    // write so we can match the mode at creation time (reducing the
+    // window where the file has a wrong mode) and verify/restore after
+    // rename (so chmod failures on the temp file don't silently drop
+    // the exec bit).
+    let preservedMode;
+    if (options.preserveMode === true) {
+        try {
+            preservedMode = fs.statSync(targetPath).mode & 0o7777;
+        }
+        catch {
+            // Target doesn't exist; preserveMode has no effect.
+        }
+    }
     try {
         fd = fs.openSync(tmpPath, 'w');
         fs.writeFileSync(fd, contents);
         fs.fsyncSync(fd);
         fs.closeSync(fd);
         fd = undefined;
+        // Apply preserved mode to the temp file before rename so the
+        // window between rename and chmod is minimal.
+        if (preservedMode !== undefined) {
+            try {
+                fs.chmodSync(tmpPath, preservedMode);
+            }
+            catch {
+                // chmod on temp may fail on some filesystems (e.g., NFS);
+                // post-rename chmod below is the safety net.
+            }
+        }
         fs.renameSync(tmpPath, targetPath);
+        // Post-rename verification: if preserveMode was requested, ensure
+        // the final file has the right bits. This is the safety net for
+        // pre-rename chmod failure, and a no-op when the pre-rename chmod
+        // succeeded.
+        if (preservedMode !== undefined) {
+            try {
+                const actualMode = fs.statSync(targetPath).mode & 0o7777;
+                if (actualMode !== preservedMode) {
+                    fs.chmodSync(targetPath, preservedMode);
+                }
+            }
+            catch {
+                // Best-effort: if the verify or chmod itself fails, the write
+                // already succeeded; the caller may need to chmod manually.
+            }
+        }
         return (0, caws_kernel_1.ok)(true);
     }
     catch (e) {

package/dist/store/atomic-write.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../../src/store/atomic-write.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../../src/store/atomic-write.ts"],"names":[],"mappings":"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"}

package/dist/store/lifecycle-lock.d.ts

@@ -0,0 +1,34 @@
+import { type Result } from '@paths.design/caws-kernel';
+export interface LifecycleLockHandle {
+    readonly fd: number;
+    readonly lockPath: string;
+}
+export interface AcquireLifecycleLockOptions {
+    /** Override the global lock path. Used by tests; production callers
+     *  pass cawsDir and get the canonical `<cawsDir>/state.lock`. */
+    readonly lockPath?: string;
+    /** Override stale-lock threshold. Defaults to 30s. Tests can lower it
+     *  to validate recovery without sleeping. */
+    readonly staleThresholdMs?: number;
+    /** Override max attempts. Defaults to 3. */
+    readonly maxAttempts?: number;
+    /** Override retry delay. Defaults to 50ms. */
+    readonly retryDelayMs?: number;
+}
+/**
+ * Acquire the global lifecycle mutation lock. Returns a `LifecycleLockHandle`
+ * the caller MUST release via `releaseLifecycleLock` in a `finally` block.
+ *
+ * The lock is held by the existence of `<cawsDir>/state.lock`. Concurrent
+ * callers retry up to `maxAttempts` with `retryDelayMs` between attempts.
+ * Stale locks (older than `staleThresholdMs`) are reclaimed.
+ */
+export declare function acquireLifecycleLock(cawsDir: string, options?: AcquireLifecycleLockOptions): Result<LifecycleLockHandle>;
+/** Release the lifecycle lock. Always safe to call; errors are swallowed
+ *  because lock-release is best-effort (the lockfile is the contract, not
+ *  the fd state). */
+export declare function releaseLifecycleLock(handle: LifecycleLockHandle): void;
+/** Convenience wrapper: acquire, run the body, release in a `finally`.
+ *  Returns the body's `Result` or the acquire-failure `Result`. */
+export declare function withLifecycleLock<T>(cawsDir: string, body: () => Result<T>, options?: AcquireLifecycleLockOptions): Result<T>;
+//# sourceMappingURL=lifecycle-lock.d.ts.map

package/dist/store/lifecycle-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-lock.d.ts","sourceRoot":"","sources":["../../src/store/lifecycle-lock.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAUjE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C;qEACiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;iDAC6C;IAC7C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AA6BD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,MAAM,CAAC,mBAAmB,CAAC,CAmD7B;AAED;;qBAEqB;AACrB,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAWtE;AAED;mEACmE;AACnE,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC,EACrB,OAAO,GAAE,2BAAgC,GACxC,MAAM,CAAC,CAAC,CAAC,CAUX"}

package/dist/store/lifecycle-lock.js

@@ -0,0 +1,168 @@
+"use strict";
+// Lifecycle mutation lock.
+//
+// LIFECYCLE-MUTATION-001 invariant: multi-file lifecycle mutations
+// serialize through a single global `.caws/state.lock`. This lock is
+// distinct from `.caws/events.jsonl.lock` (held by appendEvent only)
+// because lifecycle mutations cross file boundaries — spec YAML +
+// registry + event append — and need a wider critical section than
+// the per-file event lock provides.
+//
+// Per-resource locks (per-spec, per-worktree) are deferred. The plan
+// is: get the lifecycle mutation graph stable on a single conservative
+// lock first; introduce finer-grained locking only when the mutation
+// surface is well understood. Premature optimization here recreates
+// exactly the cross-file split-brain hazard the substrate exists to
+// prevent.
+//
+// Implementation parity with events-store.ts:
+//   - existence-based lockfile (`openSync(path, 'wx')`)
+//   - bounded retry with stale-lock recovery
+//   - same constants: 30s stale threshold, 3 attempts, 50ms retry
+//   - release in `finally` of caller's wrapper (transaction layer)
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireLifecycleLock = acquireLifecycleLock;
+exports.releaseLifecycleLock = releaseLifecycleLock;
+exports.withLifecycleLock = withLifecycleLock;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const caws_kernel_1 = require("@paths.design/caws-kernel");
+const repo_root_1 = require("./repo-root");
+const rules_1 = require("./rules");
+const LOCK_FILE_NAME = 'state.lock';
+const LOCK_MAX_ATTEMPTS = 3;
+const LOCK_RETRY_DELAY_MS = 50;
+const LOCK_STALE_MS = 30_000;
+function sleepSyncMs(ms) {
+    // Busy-wait short sleep. Matches events-store.ts pattern.
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // intentional spin
+    }
+}
+function tryRecoverStaleLock(lockPath, staleThresholdMs) {
+    try {
+        const stat = fs.statSync(lockPath);
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs > staleThresholdMs) {
+            fs.unlinkSync(lockPath);
+            return true;
+        }
+    }
+    catch {
+        // Race: lock was released between EEXIST and statSync. Treat as
+        // recoverable so the next attempt can take it.
+        return true;
+    }
+    return false;
+}
+/**
+ * Acquire the global lifecycle mutation lock. Returns a `LifecycleLockHandle`
+ * the caller MUST release via `releaseLifecycleLock` in a `finally` block.
+ *
+ * The lock is held by the existence of `<cawsDir>/state.lock`. Concurrent
+ * callers retry up to `maxAttempts` with `retryDelayMs` between attempts.
+ * Stale locks (older than `staleThresholdMs`) are reclaimed.
+ */
+function acquireLifecycleLock(cawsDir, options = {}) {
+    const lockPath = options.lockPath ?? path.join(cawsDir, LOCK_FILE_NAME);
+    const staleThresholdMs = options.staleThresholdMs ?? LOCK_STALE_MS;
+    const maxAttempts = options.maxAttempts ?? LOCK_MAX_ATTEMPTS;
+    const retryDelayMs = options.retryDelayMs ?? LOCK_RETRY_DELAY_MS;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            const fd = fs.openSync(lockPath, 'wx');
+            // Best-effort metadata so a future doctor or operator can see who
+            // is holding the lock.
+            try {
+                fs.writeFileSync(fd, JSON.stringify({
+                    pid: process.pid,
+                    at: new Date().toISOString(),
+                    purpose: 'lifecycle-mutation',
+                }));
+                fs.fsyncSync(fd);
+            }
+            catch {
+                // Lock content is best-effort; the lock itself is the file's
+                // existence.
+            }
+            return (0, caws_kernel_1.ok)({ fd, lockPath });
+        }
+        catch (e) {
+            const cause = e;
+            if (cause.code !== 'EEXIST') {
+                return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_LOCK_CONTENTION, `Unexpected error acquiring lifecycle lock: ${cause.message ?? 'unknown error'}.`, { subject: lockPath, data: { code: cause.code ?? null } }));
+            }
+            const recovered = tryRecoverStaleLock(lockPath, staleThresholdMs);
+            if (!recovered) {
+                sleepSyncMs(retryDelayMs);
+            }
+        }
+    }
+    return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_LOCK_CONTENTION, `Could not acquire lifecycle lock after ${maxAttempts} attempts.`, { subject: lockPath }));
+}
+/** Release the lifecycle lock. Always safe to call; errors are swallowed
+ *  because lock-release is best-effort (the lockfile is the contract, not
+ *  the fd state). */
+function releaseLifecycleLock(handle) {
+    try {
+        fs.closeSync(handle.fd);
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        fs.unlinkSync(handle.lockPath);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Convenience wrapper: acquire, run the body, release in a `finally`.
+ *  Returns the body's `Result` or the acquire-failure `Result`. */
+function withLifecycleLock(cawsDir, body, options = {}) {
+    const acquired = acquireLifecycleLock(cawsDir, options);
+    if (!acquired.ok) {
+        return acquired;
+    }
+    try {
+        return body();
+    }
+    finally {
+        releaseLifecycleLock(acquired.value);
+    }
+}
+//# sourceMappingURL=lifecycle-lock.js.map

package/dist/store/lifecycle-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-lock.js","sourceRoot":"","sources":["../../src/store/lifecycle-lock.ts"],"names":[],"mappings":"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"}

package/dist/store/lifecycle-transaction.d.ts

@@ -0,0 +1,79 @@
+import { type ChainedEvent, type EventBody, type Result, type Diagnostic } from '@paths.design/caws-kernel';
+/** A single file write the transaction will perform. Order in
+ *  `plannedWrites` is the order writes are applied. */
+export interface LifecycleFileWrite {
+    /** Absolute path of the file to write. */
+    readonly path: string;
+    /** New contents for this file. */
+    readonly contents: string | Buffer;
+    /** When true, writeFileAtomic preserves the target's existing mode. */
+    readonly preserveMode?: boolean;
+}
+/** Inputs to a lifecycle transaction. */
+export interface LifecycleTransactionPlan {
+    /** Path to the .caws/ directory (passed through to appendEvent). */
+    readonly cawsDir: string;
+    /** Files to write in deterministic order. */
+    readonly plannedWrites: readonly LifecycleFileWrite[];
+    /** Event(s) to append after state writes succeed. Appended in array
+     *  order. The transaction supports multiple events per command (e.g.,
+     *  worktree create emits worktree_created then worktree_bound). */
+    readonly events: readonly EventBody[];
+    /** Optional pre-write validation. Runs AFTER the lock is held and
+     *  files are read, BEFORE any write. Returns Err to abort the
+     *  transaction with LIFECYCLE_PLAN_REJECTED. */
+    readonly validate?: () => Result<void>;
+    /** When true, call fsyncDir on each affected directory after writes.
+     *  Defaults to false; see module header for rationale. */
+    readonly fsyncAfter?: boolean;
+}
+/** Success outcome: all state writes + all event appends succeeded. */
+export interface LifecycleTransactionSuccess {
+    readonly kind: 'success';
+    readonly writes: readonly {
+        readonly path: string;
+    }[];
+    readonly appendedEvents: readonly ChainedEvent[];
+}
+/** Partial-failure-recovered: state writes succeeded, event append
+ *  failed, rollback succeeded. The repository is in its pre-transaction
+ *  state. */
+export interface LifecyclePartialRecovered {
+    readonly kind: 'partial_failure_recovered';
+    readonly cause: readonly Diagnostic[];
+    readonly rolledBack: readonly string[];
+}
+/** Partial-failure-unrecovered: state writes succeeded, event append
+ *  failed, AND rollback also failed. The repository may be in a
+ *  partial state. The caller MUST handle the recovery instruction. */
+export interface LifecyclePartialUnrecovered {
+    readonly kind: 'partial_failure_unrecovered';
+    readonly cause: readonly Diagnostic[];
+    readonly plannedEvents: readonly EventBody[];
+    readonly writesCompleted: readonly string[];
+    readonly rolledBack: readonly string[];
+    readonly rollbackFailed: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+    readonly recoveryInstruction: string;
+}
+export type LifecycleTransactionResult = LifecycleTransactionSuccess | LifecyclePartialRecovered | LifecyclePartialUnrecovered;
+/**
+ * Run a lifecycle transaction.
+ *
+ * The caller MUST hold the lifecycle lock (via withLifecycleLock or
+ * acquireLifecycleLock). This function does not acquire the lock
+ * itself; that responsibility lives in the caller so a higher-level
+ * orchestrator (CLI-SPECS-001, CLI-WORKTREE-001) can group multiple
+ * conceptual mutations inside one lock if needed.
+ *
+ * Returns:
+ *   Ok({ kind: 'success', ... })                    — everything worked
+ *   Ok({ kind: 'partial_failure_recovered', ... })  — rolled back cleanly
+ *   Err([LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED]) — partial state remains
+ *   Err([LIFECYCLE_PLAN_REJECTED])               — validate() rejected
+ *   Err([LIFECYCLE_WRITE_FAILED])                — a write failed before events
+ */
+export declare function runLifecycleTransaction(plan: LifecycleTransactionPlan): Result<LifecycleTransactionResult>;
+//# sourceMappingURL=lifecycle-transaction.d.ts.map

package/dist/store/lifecycle-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-transaction.d.ts","sourceRoot":"","sources":["../../src/store/lifecycle-transaction.ts"],"names":[],"mappings":"AAuCA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,SAAS,EAGd,KAAK,MAAM,EACX,KAAK,UAAU,EAChB,MAAM,2BAA2B,CAAC;AASnC;uDACuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,aAAa,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtD;;uEAEmE;IACnE,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC;;oDAEgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC;8DAC0D;IAC1D,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAWD,uEAAuE;AACvE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD,QAAQ,CAAC,cAAc,EAAE,SAAS,YAAY,EAAE,CAAC;CAClD;AAED;;aAEa;AACb,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;sEAEsE;AACtE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,MAAM,0BAA0B,GAClC,2BAA2B,GAC3B,yBAAyB,GACzB,2BAA2B,CAAC;AAkGhC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,MAAM,CAAC,0BAA0B,CAAC,CA+JpC"}