@paths.design/caws-cli 10.2.0 → 11.1.0

package/dist/init/hook-packs/manifest-claude-code.js

@@ -0,0 +1,190 @@
+"use strict";
+// Claude Code hook pack manifest.
+//
+// Installs the v11-shape Claude Code hook plane into a repo. Activation
+// requires a session restart in Claude Code: hook registration is read at
+// session start, so installing mid-session does not affect the current
+// session's tool calls.
+//
+// Lineage entries this pack covers — see
+// packages/caws-cli/docs-status/failure-lineage.md:
+//   Entry 1  — git init catastrophic deletion (block-dangerous + classify_command)
+//   Entry 4  — worktree cross-contamination, inherited-dirty-state (worktree-guard)
+//   Entry 6  — stash-and-destroy (worktree-guard)
+//   Entry 8  — scope violations, union-mode interference (scope-guard)
+//   Entry 11 — ownership claim, CAWSFIX-31/32 (worktree-guard, session-caws-status)
+//   Entry 12 — unbound = no authority (scope-guard fail-closed)
+//   Entry 13 — working-spec.yaml baseline clobber (worktree-write-guard)
+//   Entry 16 — adjudicator overstep / role partitioning (the pack itself)
+//   Entry 17 — git --bare init bypass + danger latch (classify_command + block-dangerous + reset-danger-latch)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_CODE_PACK = exports.CLAUDE_CODE_PACK_VERSION = void 0;
+// Pack version bumps when managed file contents change in a way that
+// existing installs should pick up via the managed_old_version → auto-
+// update path. Version 2 ships the strike-level diagnostic triage,
+// activation-banner wording fix, settings.json "why we don't write it"
+// note, and tightened ask/block semantics in block-dangerous.
+exports.CLAUDE_CODE_PACK_VERSION = 2;
+exports.CLAUDE_CODE_PACK = {
+    id: 'claude-code',
+    targetSurface: 'claude-code',
+    packVersion: exports.CLAUDE_CODE_PACK_VERSION,
+    cawsMinMajor: 11,
+    summary: 'v11-shape Claude Code hook pack: scope, worktree, dangerous-command, ' +
+        'and session lifecycle guards.',
+    activation: 'restart_required',
+    lifecycleEvents: ['pre_bash', 'pre_write', 'pre_edit', 'session_start', 'stop'],
+    stateModel: {
+        reads: [
+            '.caws/specs/*.yaml',
+            '.caws/worktrees.json',
+            '.caws/agents.json',
+            '.caws/policy.yaml',
+            'package.json',
+        ],
+        writes: [
+            '.claude/logs/audit.log',
+            '.claude/logs/session-*.log',
+            '.claude/hooks/state/danger-latch-*.json',
+            '.claude/hooks/state/guard-strikes-*.json',
+            'tmp/<session-id>/',
+        ],
+    },
+    lineageRefs: [1, 4, 6, 8, 11, 12, 13, 16, 17],
+    // Installed files. Order is deterministic (used by tests and by the
+    // install reporter). destPath is relative to repo root.
+    // sourcePath is relative to the pack root
+    // (packages/caws-cli/templates/hook-packs/claude-code/).
+    installedFiles: [
+        // -- Scope and worktree guards (v11-shape) --
+        {
+            destPath: '.claude/hooks/scope-guard.sh',
+            sourcePath: 'scope-guard.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/worktree-guard.sh',
+            sourcePath: 'worktree-guard.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/worktree-write-guard.sh',
+            sourcePath: 'worktree-write-guard.sh',
+            executable: true,
+            managed: true,
+        },
+        // -- Entry 17 dangerous-command hardening (preserved verbatim) --
+        {
+            destPath: '.claude/hooks/block-dangerous.sh',
+            sourcePath: 'block-dangerous.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/classify_command.py',
+            sourcePath: 'classify_command.py',
+            executable: true,
+            managed: true,
+        },
+        // -- Human-authorized escape hatches (preserved) --
+        {
+            destPath: '.claude/hooks/reset-strikes.sh',
+            sourcePath: 'reset-strikes.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/reset-danger-latch.sh',
+            sourcePath: 'reset-danger-latch.sh',
+            executable: true,
+            managed: true,
+        },
+        // -- Strike counter shared library (sourced by scope-guard) --
+        {
+            destPath: '.claude/hooks/guard-strikes.sh',
+            sourcePath: 'guard-strikes.sh',
+            executable: true,
+            managed: true,
+        },
+        // -- Session lifecycle and logging --
+        {
+            destPath: '.claude/hooks/session-caws-status.sh',
+            sourcePath: 'session-caws-status.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/session-log.sh',
+            sourcePath: 'session-log.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/audit.sh',
+            sourcePath: 'audit.sh',
+            executable: true,
+            managed: true,
+        },
+        // -- Shared libraries sourced by every hook script --
+        {
+            destPath: '.claude/hooks/runtime-paths.sh',
+            sourcePath: 'runtime-paths.sh',
+            executable: false,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/lib/parse-input.sh',
+            sourcePath: 'lib/parse-input.sh',
+            executable: false,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/lib/run-handlers.sh',
+            sourcePath: 'lib/run-handlers.sh',
+            executable: false,
+            managed: true,
+        },
+        // -- Dispatch entrypoints invoked from .claude/settings.json --
+        {
+            destPath: '.claude/hooks/dispatch/pre_tool_use.sh',
+            sourcePath: 'dispatch/pre_tool_use.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/dispatch/post_tool_use.sh',
+            sourcePath: 'dispatch/post_tool_use.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/dispatch/session_start.sh',
+            sourcePath: 'dispatch/session_start.sh',
+            executable: true,
+            managed: true,
+        },
+        {
+            destPath: '.claude/hooks/dispatch/stop.sh',
+            sourcePath: 'dispatch/stop.sh',
+            executable: true,
+            managed: true,
+        },
+        // NOTE: .claude/settings.json is NOT a managed pack file. It often
+        // carries user-authored `permissions` and `env` blocks that the pack
+        // should not touch. Install emits explicit instructions for the
+        // user to wire the four dispatch entrypoints into their existing
+        // settings.json (or to create one from the canonical snippet in
+        // CLAUDE.md if absent). This avoids JSON-merge complexity and
+        // preserves user-owned settings.
+        // -- Doctrine landing for hook editors --
+        {
+            destPath: '.claude/hooks/CLAUDE.md',
+            sourcePath: 'CLAUDE.md',
+            executable: false,
+            managed: true,
+        },
+    ],
+};
+//# sourceMappingURL=manifest-claude-code.js.map

package/dist/init/hook-packs/manifest-claude-code.js.map

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

package/dist/init/hook-packs/register.d.ts

@@ -0,0 +1,19 @@
+import type { AgentSurface, HookPackV1 } from './types';
+export type PackResolution = {
+    readonly kind: 'pack';
+    readonly pack: HookPackV1;
+} | {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'declared_not_implemented';
+    readonly surface: Exclude<AgentSurface, 'none'>;
+};
+/** Resolve a requested surface to a pack manifest. */
+export declare function resolveHookPack(surface: AgentSurface): PackResolution;
+/** Full list of surfaces this CLI version recognizes (for help text and
+ *  validation). */
+export declare const KNOWN_SURFACES: readonly AgentSurface[];
+/** Surfaces that have a fully-implemented pack in this CLI version. */
+export declare const IMPLEMENTED_SURFACES: readonly AgentSurface[];
+export declare function isKnownSurface(value: string): value is AgentSurface;
+//# sourceMappingURL=register.d.ts.map

package/dist/init/hook-packs/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/init/hook-packs/register.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGxD,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IACE,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;CACjD,CAAC;AAEN,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,cAAc,CASrE;AAED;mBACmB;AACnB,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAKjD,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,EAAE,SAAS,YAAY,EAAoB,CAAC;AAE7E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAEnE"}

package/dist/init/hook-packs/register.js

@@ -0,0 +1,37 @@
+"use strict";
+// Pack registry. Maps `--agent-surface <id>` to a `HookPackV1` manifest.
+//
+// v11.1 ships only the `claude-code` pack. `cursor` and `windsurf` are
+// recognized as values but resolution returns a "declared but not
+// implemented" diagnostic — the abstraction is in place so adding a
+// new pack is purely additive (drop a manifest, register it here).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPLEMENTED_SURFACES = exports.KNOWN_SURFACES = void 0;
+exports.resolveHookPack = resolveHookPack;
+exports.isKnownSurface = isKnownSurface;
+const manifest_claude_code_1 = require("./manifest-claude-code");
+/** Resolve a requested surface to a pack manifest. */
+function resolveHookPack(surface) {
+    if (surface === 'none') {
+        return { kind: 'none' };
+    }
+    if (surface === 'claude-code') {
+        return { kind: 'pack', pack: manifest_claude_code_1.CLAUDE_CODE_PACK };
+    }
+    // cursor / windsurf: recognized but not yet implemented.
+    return { kind: 'declared_not_implemented', surface };
+}
+/** Full list of surfaces this CLI version recognizes (for help text and
+ *  validation). */
+exports.KNOWN_SURFACES = [
+    'claude-code',
+    'cursor',
+    'windsurf',
+    'none',
+];
+/** Surfaces that have a fully-implemented pack in this CLI version. */
+exports.IMPLEMENTED_SURFACES = ['claude-code'];
+function isKnownSurface(value) {
+    return exports.KNOWN_SURFACES.includes(value);
+}
+//# sourceMappingURL=register.js.map

package/dist/init/hook-packs/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/init/hook-packs/register.ts"],"names":[],"mappings":";AAAA,yEAAyE;AACzE,EAAE;AACF,uEAAuE;AACvE,kEAAkE;AAClE,oEAAoE;AACpE,mEAAmE;;;AAcnE,0CASC;AAcD,wCAEC;AApCD,iEAA0D;AAU1D,sDAAsD;AACtD,SAAgB,eAAe,CAAC,OAAqB;IACnD,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,uCAAgB,EAAE,CAAC;IAClD,CAAC;IACD,yDAAyD;IACzD,OAAO,EAAE,IAAI,EAAE,0BAA0B,EAAE,OAAO,EAAE,CAAC;AACvD,CAAC;AAED;mBACmB;AACN,QAAA,cAAc,GAA4B;IACrD,aAAa;IACb,QAAQ;IACR,UAAU;IACV,MAAM;CACP,CAAC;AAEF,uEAAuE;AAC1D,QAAA,oBAAoB,GAA4B,CAAC,aAAa,CAAC,CAAC;AAE7E,SAAgB,cAAc,CAAC,KAAa;IAC1C,OAAQ,sBAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC"}

package/dist/init/hook-packs/types.d.ts

@@ -0,0 +1,123 @@
+/** Supported agent harnesses. v11.1 implements claude-code only. */
+export type AgentSurface = 'claude-code' | 'cursor' | 'windsurf' | 'none';
+/** Lifecycle interception points a pack may register on a harness. */
+export type LifecycleEvent = 'pre_bash' | 'pre_write' | 'pre_edit' | 'session_start' | 'stop';
+/** A single file the pack installs, relative to the repo root. */
+export interface HookPackFile {
+    /** Destination path relative to repo root (e.g., `.claude/hooks/scope-guard.sh`). */
+    readonly destPath: string;
+    /** Source path within the templates tree, relative to the pack root
+     *  (e.g., `scope-guard.sh`). */
+    readonly sourcePath: string;
+    /** When true, the installed file must be executable (chmod +x). */
+    readonly executable: boolean;
+    /** When true, this file gets a managed header prepended/verified.
+     *  Set false for non-script auxiliary files where a comment marker
+     *  is not appropriate (e.g., a state directory placeholder). */
+    readonly managed: boolean;
+}
+/** State surfaces the pack reads from / writes to. Informational; used
+ *  by docs and by future drift detection. */
+export interface HookPackStateModel {
+    /** Files/dirs the pack reads (relative to repo root). */
+    readonly reads: readonly string[];
+    /** Files/dirs the pack writes (relative to repo root). */
+    readonly writes: readonly string[];
+}
+/** The pack manifest. */
+export interface HookPackV1 {
+    /** Pack identifier, stable across versions (e.g., "claude-code"). */
+    readonly id: string;
+    /** The harness this pack targets. */
+    readonly targetSurface: Exclude<AgentSurface, 'none'>;
+    /** Pack version. Bumps when managed file contents change in a way
+     *  that requires an update on re-install. */
+    readonly packVersion: number;
+    /** Minimum CAWS major version this pack is compatible with. */
+    readonly cawsMinMajor: number;
+    /** Lifecycle events this pack registers on the harness. */
+    readonly lifecycleEvents: readonly LifecycleEvent[];
+    /** Files installed by this pack, in deterministic order. */
+    readonly installedFiles: readonly HookPackFile[];
+    /** State surfaces (read/write paths). */
+    readonly stateModel: HookPackStateModel;
+    /** Failure-lineage entry numbers this pack covers. */
+    readonly lineageRefs: readonly number[];
+    /** Human-readable summary for init output. One short sentence. */
+    readonly summary: string;
+    /** Activation contract: whether installed hooks take effect in the
+     *  current harness session, or require a restart. */
+    readonly activation: 'immediate' | 'restart_required' | 'unknown';
+}
+/** Managed-file header fields. Used by install for parse/emit. */
+export interface ManagedHeader {
+    readonly hookPack: string;
+    readonly hookPackVersion: number;
+    readonly cawsMinMajor: number;
+    readonly lineageRefs: readonly number[];
+}
+/** Outcome of evaluating an installed-file path against the local filesystem
+ *  during install. */
+export type InstallFileState = 
+/** No file at destPath; safe to create. */
+{
+    readonly kind: 'absent';
+}
+/** Managed file at destPath matching this pack/version and unchanged
+ *  from bundled content. Safe to no-op. */
+ | {
+    readonly kind: 'managed_clean';
+    readonly header: ManagedHeader;
+}
+/** Managed file at destPath matching this pack but at an older version.
+ *  Safe to update under update policy. */
+ | {
+    readonly kind: 'managed_old_version';
+    readonly header: ManagedHeader;
+    readonly currentVersion: number;
+}
+/** Managed file at destPath matching this pack/version but content
+ *  differs from bundled. Refuses without --adopt or --overwrite. */
+ | {
+    readonly kind: 'managed_drift';
+    readonly header: ManagedHeader;
+}
+/** File at destPath without a managed header. Refuses without
+ *  --adopt or --overwrite. */
+ | {
+    readonly kind: 'unmanaged_collision';
+};
+/** Aggregate outcome of an install operation. */
+export type HookPackInstallOutcome = 
+/** Pack was installed for the first time (or new files added to an
+ *  existing pack install). */
+'installed'
+/** Pack files all present at correct version and content; no changes. */
+ | 'already_installed'
+/** Pack files updated from an older version. */
+ | 'updated'
+/** Caller explicitly chose `--agent-surface none`. No pack installed. */
+ | 'skipped_explicit_none'
+/** No harness detected, non-interactive mode. No pack installed, warning
+ *  emitted. */
+ | 'skipped_ambiguous';
+/** Per-file install action recorded for reporting. */
+export interface HookPackFileAction {
+    readonly destPath: string;
+    readonly action: 'created' | 'updated' | 'unchanged' | 'refused';
+    /** When action === 'refused', the reason. */
+    readonly refusalReason?: 'unmanaged_collision' | 'managed_drift';
+}
+/** Result of installing a pack into a repo. */
+export interface HookPackInstallResult {
+    readonly outcome: HookPackInstallOutcome;
+    /** The pack that was (or would have been) installed. Null when
+     *  outcome is 'skipped_explicit_none' or 'skipped_ambiguous'. */
+    readonly pack: HookPackV1 | null;
+    /** Per-file actions. */
+    readonly actions: readonly HookPackFileAction[];
+    /** Whether the harness requires a session restart for hooks to take
+     *  effect. Drives the activation banner. */
+    readonly activation: 'immediate' | 'restart_required' | 'unknown' | 'not_applicable';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/init/hook-packs/types.d.ts.map

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

package/dist/init/hook-packs/types.js

@@ -0,0 +1,29 @@
+"use strict";
+// HookPackV1 — manifest model for harness-specific hook packs installed by
+// `caws init --agent-surface <name>`.
+//
+// A hook pack is the **runtime adapter** that projects CAWS authority into
+// an agent harness's lifecycle (Claude Code, Cursor, Windsurf, etc.).
+// The kernel/store/shell trinity owns canonical state. The pack interposes
+// at pre-Edit/Write/Bash, where the kernel cannot reach (it runs downstream
+// of the agent's tool call).
+//
+// Every file installed by a pack carries a CAWS-MANAGED-HOOK header:
+//
+//   # CAWS-MANAGED-HOOK
+//   # hook_pack: <id>
+//   # hook_pack_version: <pack_version>
+//   # caws_min_major: <caws_min_major>
+//   # lineage_refs: <comma-separated lineage entry numbers>
+//   # do_not_edit_directly: update via `caws init --agent-surface <id>`
+//
+// The marker is what install/update uses to distinguish managed files
+// (safe to rewrite under explicit policy) from local user files (refused
+// without --adopt/--overwrite).
+//
+// Lineage: every pack must declare which failure-lineage entries it covers
+// (packages/caws-cli/docs-status/failure-lineage.md). Removing or weakening
+// a pack file requires naming the entry and identifying the replacement
+// mechanism.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/init/hook-packs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/init/hook-packs/types.ts"],"names":[],"mappings":";AAAA,2EAA2E;AAC3E,sCAAsC;AACtC,EAAE;AACF,2EAA2E;AAC3E,sEAAsE;AACtE,2EAA2E;AAC3E,4EAA4E;AAC5E,6BAA6B;AAC7B,EAAE;AACF,qEAAqE;AACrE,EAAE;AACF,wBAAwB;AACxB,sBAAsB;AACtB,wCAAwC;AACxC,uCAAuC;AACvC,4DAA4D;AAC5D,wEAAwE;AACxE,EAAE;AACF,sEAAsE;AACtE,yEAAyE;AACzE,gCAAgC;AAChC,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,wEAAwE;AACxE,aAAa"}

package/dist/shell/binding/resolve-binding.d.ts

@@ -0,0 +1,4 @@
+import type { GitWorktreeEntry, ResolveBindingInput, ResolvedBinding } from './types';
+export declare function parseWorktreePorcelain(text: string): readonly GitWorktreeEntry[];
+export declare function resolveBinding(input: ResolveBindingInput): ResolvedBinding;
+//# sourceMappingURL=resolve-binding.d.ts.map

package/dist/shell/binding/resolve-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-binding.d.ts","sourceRoot":"","sources":["../../../src/shell/binding/resolve-binding.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EAChB,MAAM,SAAS,CAAC;AA0BjB,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,gBAAgB,EAAE,CAqChF;AA6BD,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,eAAe,CA2F1E"}

package/dist/shell/binding/resolve-binding.js

@@ -0,0 +1,228 @@
+"use strict";
+// resolve-binding — turn (repoRoot, cwd, registry, specsBySpecId) into a
+// `BindingState` plus a worktree-name resolution provenance.
+//
+// Algorithm:
+//
+//   1. Real-resolve repoRoot and cwd. macOS /tmp ↔ /private/tmp matters.
+//   2. If cwd is the repoRoot (or a descendant that is NOT inside any
+//      worktree path), we are NOT in a tracked worktree → `unbound`.
+//   3. Walk worktrees.json entries with a recorded `path`. Pick the entry
+//      whose realpath(path) is cwd or an ancestor of cwd. (Multiple matches
+//      would be a registry conflict; we take the deepest match, with a
+//      stable tiebreak by name.)
+//   4. If no registry entry matches, fall back to `git worktree list
+//      --porcelain` to find the worktree path containing cwd, then look up
+//      that path in the registry. If still no match: `unbound`.
+//   5. With a worktree name in hand, look up the bound spec by following
+//      registry.specId → spec. If the spec exists, hand the Spec +
+//      registry + name to kernel `deriveBindingState`. If not, synthesize
+//      an `unbound` (and emit a one-sided shape if the registry has a
+//      specId pointing at something that didn't load).
+//
+// The shell NEVER uses `basename(cwd)` to invent a worktree name.
+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.parseWorktreePorcelain = parseWorktreePorcelain;
+exports.resolveBinding = resolveBinding;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const caws_kernel_1 = require("@paths.design/caws-kernel");
+function safeRealpath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function isAncestorOrEqual(maybeAncestor, descendant) {
+    if (maybeAncestor === descendant)
+        return true;
+    const withSep = maybeAncestor.endsWith(path.sep)
+        ? maybeAncestor
+        : maybeAncestor + path.sep;
+    return descendant.startsWith(withSep);
+}
+function defaultGitWorktreeList(repoRoot) {
+    const r = (0, node_child_process_1.spawnSync)('git', ['-C', repoRoot, 'worktree', 'list', '--porcelain'], {
+        encoding: 'utf8',
+    });
+    if (r.status !== 0 || typeof r.stdout !== 'string')
+        return [];
+    return parseWorktreePorcelain(r.stdout);
+}
+function parseWorktreePorcelain(text) {
+    const out = [];
+    let currentPath;
+    let currentBranch;
+    for (const line of text.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            if (currentPath !== undefined) {
+                const entry = currentBranch !== undefined
+                    ? { path: currentPath, branch: currentBranch }
+                    : { path: currentPath };
+                out.push(entry);
+            }
+            currentPath = line.slice('worktree '.length);
+            currentBranch = undefined;
+        }
+        else if (line.startsWith('branch ')) {
+            currentBranch = line.slice('branch '.length);
+        }
+        else if (line === '') {
+            if (currentPath !== undefined) {
+                const entry = currentBranch !== undefined
+                    ? { path: currentPath, branch: currentBranch }
+                    : { path: currentPath };
+                out.push(entry);
+                currentPath = undefined;
+                currentBranch = undefined;
+            }
+        }
+    }
+    if (currentPath !== undefined) {
+        const entry = currentBranch !== undefined
+            ? { path: currentPath, branch: currentBranch }
+            : { path: currentPath };
+        out.push(entry);
+    }
+    return out;
+}
+function findRegistryMatch(cwdReal, registry) {
+    let best = null;
+    let bestDepth = -1;
+    for (const [name, record] of Object.entries(registry)) {
+        if (typeof record?.path !== 'string')
+            continue;
+        const recordReal = safeRealpath(record.path);
+        if (!isAncestorOrEqual(recordReal, cwdReal))
+            continue;
+        const depth = recordReal.split(path.sep).length;
+        if (depth > bestDepth ||
+            (depth === bestDepth && best !== null && name < best.name)) {
+            best = { name, path: recordReal };
+            bestDepth = depth;
+        }
+    }
+    return best;
+}
+function resolveBinding(input) {
+    const cwdReal = safeRealpath(input.cwd);
+    const repoRootReal = safeRealpath(input.repoRoot);
+    // If cwd is exactly the repo root, we are in the main checkout. Walk the
+    // registry anyway in case a worktree was created at the repo root (rare,
+    // would imply specId === <main> binding). Otherwise this returns null.
+    let candidate = findRegistryMatch(cwdReal, input.registry);
+    let source = 'registry_path_match';
+    if (candidate === null) {
+        // Fallback: git porcelain. Find the worktree path containing cwd,
+        // then match that path against the registry.
+        const lister = input.gitWorktreeList ?? defaultGitWorktreeList;
+        const wts = lister(input.repoRoot);
+        let porcelainMatch = null;
+        let porcelainDepth = -1;
+        for (const wt of wts) {
+            const wtReal = safeRealpath(wt.path);
+            if (!isAncestorOrEqual(wtReal, cwdReal))
+                continue;
+            const depth = wtReal.split(path.sep).length;
+            if (depth > porcelainDepth) {
+                porcelainMatch = wt;
+                porcelainDepth = depth;
+            }
+        }
+        if (porcelainMatch !== null) {
+            const porcelainReal = safeRealpath(porcelainMatch.path);
+            // Skip if porcelain match is the main checkout (no worktree binding).
+            if (porcelainReal !== repoRootReal) {
+                // Look up registry entry by path equality.
+                for (const [name, record] of Object.entries(input.registry)) {
+                    if (typeof record?.path === 'string' &&
+                        safeRealpath(record.path) === porcelainReal) {
+                        candidate = { name, path: porcelainReal };
+                        source = 'git_porcelain_match';
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    if (candidate === null) {
+        return { binding: { kind: 'unbound' }, source: 'none' };
+    }
+    // We have a worktree name. Now find the bound spec for kernel evaluation.
+    const record = input.registry[candidate.name];
+    const registrySpecId = record?.specId;
+    if (typeof registrySpecId !== 'string' || registrySpecId.length === 0) {
+        // Registry knows the worktree but no spec is linked. Neither side
+        // points at the other, so this is `unbound`, NOT `one_sided`.
+        // The repair is "bind this worktree to a spec", not "repair corrupt
+        // asymmetric binding". The downstream renderer keys off the
+        // worktreeName being set to distinguish "tracked worktree without
+        // spec" from "cwd outside any worktree".
+        return {
+            binding: { kind: 'unbound' },
+            worktreeName: candidate.name,
+            source,
+        };
+    }
+    // We have registrySpecId. Find the bound spec in the loaded specs list.
+    const boundSpec = input.specs.find((s) => s.id === registrySpecId);
+    if (boundSpec === undefined) {
+        // Registry points at a spec id that didn't load. From the kernel's
+        // perspective this is one-sided (registry has specId, spec missing).
+        return {
+            binding: {
+                kind: 'one_sided',
+                detail: {
+                    specHasWorktree: false,
+                    registryHasSpecId: true,
+                    registrySpecId,
+                    worktreeName: candidate.name,
+                },
+            },
+            worktreeName: candidate.name,
+            source,
+        };
+    }
+    return {
+        binding: (0, caws_kernel_1.deriveBindingState)(boundSpec, input.registry, candidate.name),
+        worktreeName: candidate.name,
+        source,
+    };
+}
+//# sourceMappingURL=resolve-binding.js.map