@cleocode/cant 2026.5.100 → 2026.5.102

package/dist/index.d.ts

@@ -19,4 +19,3 @@ export { initCantParser, parseCANTMessage } from './parse';
 export type { CantAgentV3, CantContextSourceDef, CantContractBlock, CantContractClause, CantMentalModelRef, CantOverflowStrategy, CantPathPermissions, CantTier, DirectiveType, } from './types';
 export { isCantAgentV3 } from './types';
 export type { MergeResult, WorktreeConfig, WorktreeEntry, WorktreeHandle, WorktreeRequest, } from './worktree.js';
-export { createWorktree, listWorktrees, mergeWorktree, resolveWorktreeRoot, } from './worktree.js';

package/dist/index.js

@@ -2,7 +2,7 @@
 // JIT Agent Composer (ULTRAPLAN Wave 5)
 // Wave 7a: BRAIN-backed ContextProvider (T432)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveWorktreeRoot = exports.mergeWorktree = exports.listWorktrees = exports.createWorktree = exports.isCantAgentV3 = exports.parseCANTMessage = exports.initCantParser = exports.validateAgentCantPath = exports.SEED_PERSONA_IDS = exports.loadSeedAgentIdentities = exports.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = exports.extractAgentSkills = exports.extractAgentProfilesTyped = exports.cantValidateDocumentNative = exports.cantParseNative = exports.cantParseDocumentNative = exports.cantExtractAgentProfilesNative = exports.cantExecutePipelineNative = exports.cantClassifyDirectiveNative = exports.showSummary = exports.showDiff = exports.serializeCantDocument = exports.migrateMarkdown = exports.renderMentalModel = exports.harvestObservations = exports.createEmptyModel = exports.consolidate = exports.WORKER_FORBIDDEN_SPAWN_TOOLS = exports.validateSpawnRequest = exports.THIN_AGENT_TOOLS_STRIPPED = exports.stripSpawnToolsForWorker = exports.ORCHESTRATOR_FORBIDDEN_TOOLS = exports.LEAD_FORBIDDEN_TOOLS = exports.filterToolsForRole = exports.validateDocument = exports.parseDocument = exports.listSections = exports.executePipeline = exports.brainContextProvider = exports.TIER_CAPS = exports.estimateTokens = exports.escalateTier = exports.composeSpawnPayload = exports.toCantAgentV3 = exports.compileBundle = void 0;
+exports.isCantAgentV3 = exports.parseCANTMessage = exports.initCantParser = exports.validateAgentCantPath = exports.SEED_PERSONA_IDS = exports.loadSeedAgentIdentities = exports.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = exports.extractAgentSkills = exports.extractAgentProfilesTyped = exports.cantValidateDocumentNative = exports.cantParseNative = exports.cantParseDocumentNative = exports.cantExtractAgentProfilesNative = exports.cantExecutePipelineNative = exports.cantClassifyDirectiveNative = exports.showSummary = exports.showDiff = exports.serializeCantDocument = exports.migrateMarkdown = exports.renderMentalModel = exports.harvestObservations = exports.createEmptyModel = exports.consolidate = exports.WORKER_FORBIDDEN_SPAWN_TOOLS = exports.validateSpawnRequest = exports.THIN_AGENT_TOOLS_STRIPPED = exports.stripSpawnToolsForWorker = exports.ORCHESTRATOR_FORBIDDEN_TOOLS = exports.LEAD_FORBIDDEN_TOOLS = exports.filterToolsForRole = exports.validateDocument = exports.parseDocument = exports.listSections = exports.executePipeline = exports.brainContextProvider = exports.TIER_CAPS = exports.estimateTokens = exports.escalateTier = exports.composeSpawnPayload = exports.toCantAgentV3 = exports.compileBundle = void 0;
 // Bundle compiler
 var bundle_1 = require("./bundle");
 Object.defineProperty(exports, "compileBundle", { enumerable: true, get: function () { return bundle_1.compileBundle; } });
@@ -64,9 +64,3 @@ Object.defineProperty(exports, "initCantParser", { enumerable: true, get: functi
 Object.defineProperty(exports, "parseCANTMessage", { enumerable: true, get: function () { return parse_1.parseCANTMessage; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "isCantAgentV3", { enumerable: true, get: function () { return types_1.isCantAgentV3; } });
-// Worktree isolation (ULTRAPLAN Wave 9)
-var worktree_js_1 = require("./worktree.js");
-Object.defineProperty(exports, "createWorktree", { enumerable: true, get: function () { return worktree_js_1.createWorktree; } });
-Object.defineProperty(exports, "listWorktrees", { enumerable: true, get: function () { return worktree_js_1.listWorktrees; } });
-Object.defineProperty(exports, "mergeWorktree", { enumerable: true, get: function () { return worktree_js_1.mergeWorktree; } });
-Object.defineProperty(exports, "resolveWorktreeRoot", { enumerable: true, get: function () { return worktree_js_1.resolveWorktreeRoot; } });

package/dist/worktree.d.ts

@@ -1,13 +1,34 @@
 /**
- * Git worktree manager for multi-agent isolation.
+ * Type-only deprecation shim for the legacy cant worktree API.
  *
- * Implements ULTRAPLAN §14: each spawned agent gets its own git
- * worktree so parallel workers cannot conflict. The orchestrator
- * stays on its current branch.
+ * @remarks
+ * This file was 298 LOC of runtime worktree logic (the "2nd creation site"
+ * flagged by the T9801 audit). Per T9986 / E9-RIP-LEGACY, the runtime has
+ * been removed — all callers now route through `@cleocode/worktree` (the
+ * canonical napi-backed SSoT).
+ *
+ * Two downstream consumers (`@cleocode/caamp`) still import
+ * {@link WorktreeHandle} as a TYPE for their `SpawnOptions.worktree` and
+ * `SubagentSpawnOptions.worktree` fields. To avoid a breaking change to
+ * the spawn-adapter contract in the same release that rips the legacy
+ * runtime, the type definitions are preserved here as a one-cycle
+ * deprecation shim. The runtime functions (`createWorktree`,
+ * `mergeWorktree`, `listWorktrees`, `resolveWorktreeRoot`) had ZERO
+ * production consumers and have been deleted.
+ *
+ * Removal target: the next minor cycle after caamp migrates to
+ * `@cleocode/worktree`'s `CreateWorktreeResult` shape directly.
  *
  * @packageDocumentation
+ * @deprecated Import worktree primitives from `@cleocode/worktree` instead.
+ *   This module retains only type shims for one deprecation cycle.
+ * @task T9986
+ */
+/**
+ * Request payload for creating a new git worktree.
+ *
+ * @deprecated Use `CreateWorktreeOptions` from `@cleocode/worktree` instead.
  */
-/** Request payload for creating a new git worktree. */
 export interface WorktreeRequest {
     /** The base ref to branch from (e.g. "main", "develop", a SHA). */
     baseRef: string;
@@ -26,7 +47,11 @@ export interface WorktreeRequest {
  * `CLEO_PROJECT_HASH` in spawned subagent environments without threading
  * {@link WorktreeConfig} through every call site.
  *
+ * Still consumed (as a type) by `@cleocode/caamp` for its
+ * `SpawnOptions.worktree` and `SubagentSpawnOptions.worktree` fields.
+ *
  * @task T380
+ * @deprecated Migrate to `CreateWorktreeResult` from `@cleocode/worktree`.
  */
 export interface WorktreeHandle {
     /** Absolute path to the worktree directory. */
@@ -51,7 +76,12 @@ export interface WorktreeHandle {
     /** Clean up: remove the worktree and optionally delete the branch. */
     cleanup(deleteBranch?: boolean): void;
 }
-/** Configuration for worktree path resolution and git operations. */
+/**
+ * Configuration for worktree path resolution and git operations.
+ *
+ * @deprecated `@cleocode/worktree` derives paths from `@cleocode/paths`
+ *   directly; configuration is no longer threaded through call sites.
+ */
 export interface WorktreeConfig {
     /** Root directory for worktrees. Defaults to $XDG_DATA_HOME/cleo/worktrees/<projectHash>/ */
     worktreeRoot?: string;
@@ -60,67 +90,25 @@ export interface WorktreeConfig {
     /** The project's git root directory. */
     gitRoot: string;
 }
-/** Result of a merge operation. */
+/**
+ * Result of a merge operation.
+ *
+ * @deprecated Use `WorktreeMergeResult` from `@cleocode/contracts` instead.
+ */
 export interface MergeResult {
     /** Whether the merge succeeded. */
     success: boolean;
     /** Error message if the merge failed. */
     error?: string;
 }
-/** Entry in the list of active worktrees. */
+/**
+ * Entry in the list of active worktrees.
+ *
+ * @deprecated Use `WorktreeListEntry` from `@cleocode/contracts` instead.
+ */
 export interface WorktreeEntry {
     /** Absolute path to the worktree directory. */
     path: string;
     /** Branch checked out in this worktree. */
     branch: string;
 }
-/**
- * Resolve the worktree root directory.
- *
- * Uses `$XDG_DATA_HOME/cleo/worktrees/<projectHash>/` per ULTRAPLAN §14.3.
- * Falls back to `~/.local/share/cleo/worktrees/<projectHash>/` when
- * `XDG_DATA_HOME` is not set.
- *
- * @param config - Worktree configuration containing optional override and project hash.
- * @returns Absolute path to the worktree root directory.
- */
-export declare function resolveWorktreeRoot(config: WorktreeConfig): string;
-/**
- * Create a git worktree for an agent.
- *
- * Runs `git worktree add <path> -b <branch> <baseRef>` from the
- * project's git root. Branch naming convention: `cleo/<taskId>-<shortId>`.
- *
- * If a worktree already exists at the target path (stale from a prior run),
- * it is removed before creating the new one.
- *
- * @param request - The worktree request specifying task, base ref, and optional branch name.
- * @param config - Project-level worktree configuration.
- * @returns A handle for the created worktree with cleanup capability.
- * @throws Error if the git worktree add command fails.
- */
-export declare function createWorktree(request: WorktreeRequest, config: WorktreeConfig): WorktreeHandle;
-/**
- * Merge a worktree's branch back into the current branch.
- *
- * On success the worktree is cleaned up (directory removed, branch deleted).
- * On failure the worktree is retained for forensic inspection.
- *
- * @param handle - The worktree handle returned from {@link createWorktree}.
- * @param config - Project-level worktree configuration.
- * @param options - Merge strategy options (defaults to fast-forward only).
- * @returns A result object indicating success or failure with an error message.
- */
-export declare function mergeWorktree(handle: WorktreeHandle, config: WorktreeConfig, options?: {
-    strategy?: 'ff-only' | 'no-ff';
-}): MergeResult;
-/**
- * List active worktrees scoped to the current project.
- *
- * Parses `git worktree list --porcelain` and filters entries whose path
- * falls under the project's worktree root directory.
- *
- * @param config - Project-level worktree configuration.
- * @returns Array of worktree entries with their paths and branch names.
- */
-export declare function listWorktrees(config: WorktreeConfig): WorktreeEntry[];

package/dist/worktree.js

@@ -1,209 +1,28 @@
 "use strict";
 /**
- * Git worktree manager for multi-agent isolation.
+ * Type-only deprecation shim for the legacy cant worktree API.
  *
- * Implements ULTRAPLAN §14: each spawned agent gets its own git
- * worktree so parallel workers cannot conflict. The orchestrator
- * stays on its current branch.
+ * @remarks
+ * This file was 298 LOC of runtime worktree logic (the "2nd creation site"
+ * flagged by the T9801 audit). Per T9986 / E9-RIP-LEGACY, the runtime has
+ * been removed — all callers now route through `@cleocode/worktree` (the
+ * canonical napi-backed SSoT).
+ *
+ * Two downstream consumers (`@cleocode/caamp`) still import
+ * {@link WorktreeHandle} as a TYPE for their `SpawnOptions.worktree` and
+ * `SubagentSpawnOptions.worktree` fields. To avoid a breaking change to
+ * the spawn-adapter contract in the same release that rips the legacy
+ * runtime, the type definitions are preserved here as a one-cycle
+ * deprecation shim. The runtime functions (`createWorktree`,
+ * `mergeWorktree`, `listWorktrees`, `resolveWorktreeRoot`) had ZERO
+ * production consumers and have been deleted.
+ *
+ * Removal target: the next minor cycle after caamp migrates to
+ * `@cleocode/worktree`'s `CreateWorktreeResult` shape directly.
  *
  * @packageDocumentation
+ * @deprecated Import worktree primitives from `@cleocode/worktree` instead.
+ *   This module retains only type shims for one deprecation cycle.
+ * @task T9986
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveWorktreeRoot = resolveWorktreeRoot;
-exports.createWorktree = createWorktree;
-exports.mergeWorktree = mergeWorktree;
-exports.listWorktrees = listWorktrees;
-const node_child_process_1 = require("node:child_process");
-const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
-const node_path_1 = require("node:path");
-/**
- * Resolve the worktree root directory.
- *
- * Uses `$XDG_DATA_HOME/cleo/worktrees/<projectHash>/` per ULTRAPLAN §14.3.
- * Falls back to `~/.local/share/cleo/worktrees/<projectHash>/` when
- * `XDG_DATA_HOME` is not set.
- *
- * @param config - Worktree configuration containing optional override and project hash.
- * @returns Absolute path to the worktree root directory.
- */
-function resolveWorktreeRoot(config) {
-    if (config.worktreeRoot)
-        return config.worktreeRoot;
-    const xdgData = process.env['XDG_DATA_HOME'] ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.local', 'share');
-    return (0, node_path_1.join)(xdgData, 'cleo', 'worktrees', config.projectHash);
-}
-/**
- * Create a git worktree for an agent.
- *
- * Runs `git worktree add <path> -b <branch> <baseRef>` from the
- * project's git root. Branch naming convention: `cleo/<taskId>-<shortId>`.
- *
- * If a worktree already exists at the target path (stale from a prior run),
- * it is removed before creating the new one.
- *
- * @param request - The worktree request specifying task, base ref, and optional branch name.
- * @param config - Project-level worktree configuration.
- * @returns A handle for the created worktree with cleanup capability.
- * @throws Error if the git worktree add command fails.
- */
-function createWorktree(request, config) {
-    const root = resolveWorktreeRoot(config);
-    (0, node_fs_1.mkdirSync)(root, { recursive: true });
-    const shortId = Math.random().toString(36).slice(2, 8);
-    const branch = request.branchName ?? `cleo/${request.taskId}-${shortId}`;
-    const worktreePath = (0, node_path_1.join)(root, request.taskId);
-    // Remove existing worktree at this path if it exists (stale from prior run)
-    if ((0, node_fs_1.existsSync)(worktreePath)) {
-        try {
-            (0, node_child_process_1.execSync)(`git worktree remove "${worktreePath}" --force`, {
-                cwd: config.gitRoot,
-                stdio: 'pipe',
-            });
-        }
-        catch {
-            // Best-effort cleanup — directory may not be a valid worktree
-            (0, node_fs_1.rmSync)(worktreePath, { recursive: true, force: true });
-        }
-    }
-    // Create the worktree
-    (0, node_child_process_1.execSync)(`git worktree add "${worktreePath}" -b "${branch}" "${request.baseRef}"`, {
-        cwd: config.gitRoot,
-        stdio: 'pipe',
-    });
-    return buildHandle(worktreePath, branch, request.baseRef, request.taskId, config.gitRoot, config.projectHash);
-}
-/**
- * Merge a worktree's branch back into the current branch.
- *
- * On success the worktree is cleaned up (directory removed, branch deleted).
- * On failure the worktree is retained for forensic inspection.
- *
- * @param handle - The worktree handle returned from {@link createWorktree}.
- * @param config - Project-level worktree configuration.
- * @param options - Merge strategy options (defaults to fast-forward only).
- * @returns A result object indicating success or failure with an error message.
- */
-function mergeWorktree(handle, config, options = {}) {
-    const strategy = options.strategy ?? 'ff-only';
-    const mergeFlag = strategy === 'ff-only' ? '--ff-only' : '--no-ff';
-    try {
-        (0, node_child_process_1.execSync)(`git merge ${mergeFlag} "${handle.branch}"`, {
-            cwd: config.gitRoot,
-            stdio: 'pipe',
-        });
-        // Success: clean up worktree
-        handle.cleanup(true);
-        return { success: true };
-    }
-    catch (err) {
-        // Failure: retain worktree for forensics
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-            success: false,
-            error: `Merge failed: ${message}. Worktree retained at ${handle.path} for forensics.`,
-        };
-    }
-}
-/**
- * List active worktrees scoped to the current project.
- *
- * Parses `git worktree list --porcelain` and filters entries whose path
- * falls under the project's worktree root directory.
- *
- * @param config - Project-level worktree configuration.
- * @returns Array of worktree entries with their paths and branch names.
- */
-function listWorktrees(config) {
-    try {
-        const output = (0, node_child_process_1.execSync)('git worktree list --porcelain', {
-            cwd: config.gitRoot,
-            encoding: 'utf-8',
-        });
-        const entries = [];
-        const root = resolveWorktreeRoot(config);
-        const canonicalRoot = canonicalPath(root);
-        let currentPath = '';
-        let currentBranch = '';
-        for (const line of output.split('\n')) {
-            if (line.startsWith('worktree ')) {
-                currentPath = line.slice('worktree '.length);
-            }
-            else if (line.startsWith('branch ')) {
-                currentBranch = line.slice('branch refs/heads/'.length);
-            }
-            else if (line === '') {
-                const canonicalCurrent = canonicalPath(currentPath);
-                const relativeToRoot = (0, node_path_1.relative)(canonicalRoot, canonicalCurrent);
-                if (relativeToRoot.length > 0 &&
-                    !relativeToRoot.startsWith('..') &&
-                    !(0, node_path_1.isAbsolute)(relativeToRoot)) {
-                    entries.push({ path: (0, node_path_1.join)(root, relativeToRoot), branch: currentBranch });
-                }
-                currentPath = '';
-                currentBranch = '';
-            }
-        }
-        return entries;
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Return a filesystem-canonical path when possible.
- *
- * macOS reports temporary git worktrees via `/private/var/...` even when the
- * test/config path was created under `/var/...`. Canonicalizing both sides for
- * filtering prevents managed worktrees from being dropped, while callers still
- * receive paths rooted at the configured spelling.
- */
-function canonicalPath(path) {
-    try {
-        return node_fs_1.realpathSync.native(path);
-    }
-    catch {
-        return path;
-    }
-}
-/**
- * Build a WorktreeHandle with a cleanup closure.
- *
- * @remarks
- * The `projectHash` parameter was added in T380/ADR-041 and is stored on the
- * returned handle so spawn adapters can populate `CLEO_PROJECT_HASH` without
- * re-threading {@link WorktreeConfig}.
- *
- * @internal
- */
-function buildHandle(worktreePath, branch, baseRef, taskId, gitRoot, projectHash) {
-    return {
-        path: worktreePath,
-        branch,
-        baseRef,
-        taskId,
-        projectHash,
-        cleanup(deleteBranch = false) {
-            try {
-                (0, node_child_process_1.execSync)(`git worktree remove "${worktreePath}" --force`, {
-                    cwd: gitRoot,
-                    stdio: 'pipe',
-                });
-            }
-            catch {
-                (0, node_fs_1.rmSync)(worktreePath, { recursive: true, force: true });
-            }
-            if (deleteBranch) {
-                try {
-                    (0, node_child_process_1.execSync)(`git branch -D "${branch}"`, {
-                        cwd: gitRoot,
-                        stdio: 'pipe',
-                    });
-                }
-                catch {
-                    // Branch may already be deleted
-                }
-            }
-        },
-    };
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cant",
-  "version": "2026.5.100",
+  "version": "2026.5.102",
   "description": "CANT protocol parser and runtime for CLEO — wraps cant-core via napi-rs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,9 +9,9 @@
     "napi/"
   ],
   "dependencies": {
-    "@cleocode/contracts": "2026.5.100",
-    "@cleocode/lafs": "2026.5.100",
-    "@cleocode/core": "2026.5.100"
+    "@cleocode/core": "2026.5.102",
+    "@cleocode/lafs": "2026.5.102",
+    "@cleocode/contracts": "2026.5.102"
   },
   "devDependencies": {
     "typescript": "^6.0.2",