@cleocode/paths 2026.5.95 → 2026.5.96

package/dist/index.d.ts

@@ -12,7 +12,7 @@
  *   {@link getCleoSystemInfo}, {@link getCleoTemplatesTildePath}
  * - Worktree primitives: {@link computeProjectHash},
  *   {@link resolveWorktreeRootForHash}, {@link resolveTaskWorktreePath},
- *   {@link getCleoWorktreesRoot}
+ *   {@link getCleoWorktreesRoot}, {@link resolveWorktreeIndexPath}
  * - {@link isAbsolutePath} — cross-platform abs-path check
  *
  * @packageDocumentation
@@ -21,5 +21,5 @@
 export { isAbsolutePath } from './abs-path.js';
 export { _resetCleoPlatformPathsCache, getCanonicalTemplatesTildePath, getCleoHome, getCleoPlatformPaths, getCleoSystemInfo, getCleoTemplatesTildePath, resolveLegacyCleoDir, } from './cleo-paths.js';
 export { createPlatformPathsResolver, type PlatformPaths, type PlatformPathsResolver, type SystemInfo, } from './platform-paths.js';
-export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeRootForHash, } from './worktree-paths.js';
+export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeIndexPath, resolveWorktreeRootForHash, } from './worktree-paths.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -12,7 +12,7 @@
  *   {@link getCleoSystemInfo}, {@link getCleoTemplatesTildePath}
  * - Worktree primitives: {@link computeProjectHash},
  *   {@link resolveWorktreeRootForHash}, {@link resolveTaskWorktreePath},
- *   {@link getCleoWorktreesRoot}
+ *   {@link getCleoWorktreesRoot}, {@link resolveWorktreeIndexPath}
  * - {@link isAbsolutePath} — cross-platform abs-path check
  *
  * @packageDocumentation
@@ -21,5 +21,5 @@
 export { isAbsolutePath } from './abs-path.js';
 export { _resetCleoPlatformPathsCache, getCanonicalTemplatesTildePath, getCleoHome, getCleoPlatformPaths, getCleoSystemInfo, getCleoTemplatesTildePath, resolveLegacyCleoDir, } from './cleo-paths.js';
 export { createPlatformPathsResolver, } from './platform-paths.js';
-export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeRootForHash, } from './worktree-paths.js';
+export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeIndexPath, resolveWorktreeRootForHash, } from './worktree-paths.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,GAI5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,GAI5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}

package/dist/worktree-paths.d.ts

@@ -6,7 +6,13 @@
  *
  * `cleoHome` is resolved via {@link getCleoHome} (env-paths + `CLEO_HOME` override).
  *
+ * Council verdict D009 (T9802 / SG-WORKTREE-CANON) added the hybrid sentinel
+ * index concept: a per-project JSON file at `<projectRoot>/.cleo/worktrees.json`
+ * that acts as the canonical registry of active worktrees for that project.
+ * Use {@link resolveWorktreeIndexPath} to get this path.
+ *
  * @task T1883
+ * @task T9802
  */
 /**
  * Compute a stable 16-character project hash from an absolute project root path.
@@ -61,4 +67,43 @@ export declare function resolveTaskWorktreePath(projectHash: string, taskId: str
  * @public
  */
 export declare function getCleoWorktreesRoot(): string;
+/**
+ * Resolve the canonical SENTINEL INDEX path for active worktrees associated
+ * with a project — `<projectRoot>/.cleo/worktrees.json`.
+ *
+ * Council verdict D009 (T9802 / SG-WORKTREE-CANON) introduced the hybrid
+ * worktree-location model: worktree directories themselves live under the XDG
+ * data directory (see {@link resolveWorktreeRootForHash}), while a lightweight
+ * JSON index file lives **inside the project** at
+ * `<projectRoot>/.cleo/worktrees.json`. This sentinel acts as the canonical
+ * registry of active worktrees for that project and is:
+ *
+ * - **Tracked alongside project state** — lives in `.cleo/` (git-ignored),
+ *   survives across `CLEO_HOME` changes and machine migrations.
+ * - **Machine-local** — absolute XDG paths inside the JSON are valid only on
+ *   the machine that created them; consumers must handle stale entries.
+ * - **FILE not DIRECTORY** — the path ends in `.json`, never a directory.
+ *   Create with `JSON.stringify` + `fs.writeFileSync`; read with
+ *   `JSON.parse(fs.readFileSync(...))`.
+ *
+ * Invariant: the returned path is always
+ * `<projectRoot>/.cleo/worktrees.json` regardless of `CLEO_HOME`, XDG
+ * environment variables, or platform. It is the T9805 lifecycle hook's
+ * canonical write target.
+ *
+ * @param projectRoot - Absolute path to the project root (the directory that
+ *   contains the `.cleo/` subdirectory for this project).
+ * @returns Absolute path to `<projectRoot>/.cleo/worktrees.json`.
+ *
+ * @example
+ * ```typescript
+ * import { resolveWorktreeIndexPath } from '@cleocode/paths';
+ *
+ * const indexPath = resolveWorktreeIndexPath('/mnt/projects/cleocode');
+ * // "/mnt/projects/cleocode/.cleo/worktrees.json"
+ * ```
+ *
+ * @public
+ */
+export declare function resolveWorktreeIndexPath(projectRoot: string): string;
 //# sourceMappingURL=worktree-paths.d.ts.map

package/dist/worktree-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree-paths.d.ts","sourceRoot":"","sources":["../src/worktree-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0BH;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAGR;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}
+{"version":3,"file":"worktree-paths.d.ts","sourceRoot":"","sources":["../src/worktree-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA0BH;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAGR;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE"}

package/dist/worktree-paths.js

@@ -6,7 +6,13 @@
  *
  * `cleoHome` is resolved via {@link getCleoHome} (env-paths + `CLEO_HOME` override).
  *
+ * Council verdict D009 (T9802 / SG-WORKTREE-CANON) added the hybrid sentinel
+ * index concept: a per-project JSON file at `<projectRoot>/.cleo/worktrees.json`
+ * that acts as the canonical registry of active worktrees for that project.
+ * Use {@link resolveWorktreeIndexPath} to get this path.
+ *
  * @task T1883
+ * @task T9802
  */
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
@@ -93,4 +99,45 @@ export function resolveTaskWorktreePath(projectHash, taskId, worktreeRoot) {
 export function getCleoWorktreesRoot() {
     return joinSegments(getCleoHome(), WORKTREES_SUBDIR);
 }
+/**
+ * Resolve the canonical SENTINEL INDEX path for active worktrees associated
+ * with a project — `<projectRoot>/.cleo/worktrees.json`.
+ *
+ * Council verdict D009 (T9802 / SG-WORKTREE-CANON) introduced the hybrid
+ * worktree-location model: worktree directories themselves live under the XDG
+ * data directory (see {@link resolveWorktreeRootForHash}), while a lightweight
+ * JSON index file lives **inside the project** at
+ * `<projectRoot>/.cleo/worktrees.json`. This sentinel acts as the canonical
+ * registry of active worktrees for that project and is:
+ *
+ * - **Tracked alongside project state** — lives in `.cleo/` (git-ignored),
+ *   survives across `CLEO_HOME` changes and machine migrations.
+ * - **Machine-local** — absolute XDG paths inside the JSON are valid only on
+ *   the machine that created them; consumers must handle stale entries.
+ * - **FILE not DIRECTORY** — the path ends in `.json`, never a directory.
+ *   Create with `JSON.stringify` + `fs.writeFileSync`; read with
+ *   `JSON.parse(fs.readFileSync(...))`.
+ *
+ * Invariant: the returned path is always
+ * `<projectRoot>/.cleo/worktrees.json` regardless of `CLEO_HOME`, XDG
+ * environment variables, or platform. It is the T9805 lifecycle hook's
+ * canonical write target.
+ *
+ * @param projectRoot - Absolute path to the project root (the directory that
+ *   contains the `.cleo/` subdirectory for this project).
+ * @returns Absolute path to `<projectRoot>/.cleo/worktrees.json`.
+ *
+ * @example
+ * ```typescript
+ * import { resolveWorktreeIndexPath } from '@cleocode/paths';
+ *
+ * const indexPath = resolveWorktreeIndexPath('/mnt/projects/cleocode');
+ * // "/mnt/projects/cleocode/.cleo/worktrees.json"
+ * ```
+ *
+ * @public
+ */
+export function resolveWorktreeIndexPath(projectRoot) {
+    return joinSegments(projectRoot, '.cleo', 'worktrees.json');
+}
 //# sourceMappingURL=worktree-paths.js.map

package/dist/worktree-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"worktree-paths.js","sourceRoot":"","sources":["../src/worktree-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,gBAAgB,GAAG,WAAW,CAAC;AACrC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;;;;;GASG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,GAAG,KAAe;IACpD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,OAAO,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;AAC9F,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAmB,EAAE,YAAqB;IACnF,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,OAAO,YAAY,CAAC,WAAW,EAAE,EAAE,gBAAgB,EAAE,WAAW,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,WAAmB,EACnB,MAAc,EACd,YAAqB;IAErB,MAAM,IAAI,GAAG,0BAA0B,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACnE,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAC,WAAW,EAAE,EAAE,gBAAgB,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"worktree-paths.js","sourceRoot":"","sources":["../src/worktree-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,gBAAgB,GAAG,WAAW,CAAC;AACrC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;;;;;GASG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,GAAG,KAAe;IACpD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,OAAO,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;AAC9F,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAmB,EAAE,YAAqB;IACnF,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,OAAO,YAAY,CAAC,WAAW,EAAE,EAAE,gBAAgB,EAAE,WAAW,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,WAAmB,EACnB,MAAc,EACd,YAAqB;IAErB,MAAM,IAAI,GAAG,0BAA0B,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACnE,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAC,WAAW,EAAE,EAAE,gBAAgB,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,OAAO,YAAY,CAAC,WAAW,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC;AAC9D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/paths",
-  "version": "2026.5.95",
+  "version": "2026.5.96",
   "private": false,
   "type": "module",
   "description": "CLEO XDG/env-paths SSoT — createPlatformPathsResolver factory, cleo-bound platform paths, project hash + worktree root primitives, isAbsolutePath. Zero-dep leaf package consumed by core, worktree, brain, adapters, and caamp.",