@nexrall/code-core 1.4.59 → 1.4.60

package/dist/agent/sharedTasks.js

@@ -0,0 +1,284 @@
+"use strict";
+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._sharedTasksInternal = void 0;
+exports.listSharedTasks = listSharedTasks;
+exports.createSharedTask = createSharedTask;
+exports.claimTask = claimTask;
+exports.updateSharedTaskStatus = updateSharedTaskStatus;
+/**
+ * Shared task list — lets MULTIPLE independent sessions (two CLI windows, or
+ * CLI + VS Code + Desktop, all working the same project) coordinate who is
+ * doing what, mirroring Claude Code's agent-teams task list
+ * (`~/.claude/tasks/{team-name}/`, `pending/in_progress/completed/blocked`
+ * status, atomic claim-by-write).
+ *
+ * WHERE THIS FITS relative to the other two isolation mechanisms already in
+ * this codebase — they solve DIFFERENT problems and this module deliberately
+ * does not try to replace either:
+ *   - crossProcessLock.ts:  prevents two processes from corrupting the SAME
+ *     FILE if they write it at the same instant. Reactive, byte-level.
+ *   - worktree.ts:          prevents two sessions from touching the same
+ *     directory tree AT ALL. Preventive, physical.
+ *   - sharedTasks.ts (here): lets sessions agree in ADVANCE on who is
+ *     working on what, so they mostly never NEED the other two mechanisms
+ *     to fire — this is social coordination, not a hard technical
+ *     guarantee. A session can still ignore the task list; nothing here
+ *     enforces claims the way worktreeEnforcement.ts enforces isolation.
+ *     That's intentional and matches Claude Code's own docs: the task list
+ *     is a coordination aid ("Assign different folders/files to different
+ *     agents" is still the human's job), not a lock.
+ *
+ * STORAGE
+ * -------
+ *   ~/.nexrall/peers/tasks/<workDirHash>/<taskId>.json
+ *
+ * One file per task. `workDirHash` scopes tasks to the project they belong
+ * to (same reasoning as crossProcessLock's opaque-key scoping) so two
+ * unrelated projects on the same machine never see each other's task lists.
+ *
+ * CLAIMING (the one operation that must be race-free)
+ * ----------------------------------------------------
+ * `claimTask` reads the task, checks it is claimable (pending, not blocked
+ * by an incomplete task), and writes `status: in_progress` + `claimedBy` —
+ * all while holding crossProcessLock.ts's OS-level lock for that exact task
+ * file. Two sessions racing to claim the same task: exactly one lock winner
+ * proceeds through the read-check-write; the loser's lock acquisition
+ * unblocks AFTER the winner has already written `in_progress`, so the
+ * loser's own claimability check (re-read after acquiring the lock) sees the
+ * task is no longer pending and returns 'already-claimed'. This is the exact
+ * race Claude Code's docs describe being solved "via file locking at the
+ * write layer" for their own task list.
+ *
+ * STALE CLAIMS
+ * ------------
+ * Claude Code's own docs list "status can become stale... requiring manual
+ * intervention" as a known limitation of their task list. This module goes
+ * one step further with a TTL + liveness check (same pattern as
+ * crossProcessLock's stale-lock detection): a claim whose owning session's
+ * process is no longer running, or whose claim is older than
+ * CLAIM_STALE_MS with no heartbeat, is treated as abandoned and can be
+ * reclaimed — still requiring the reclaiming session to go through the
+ * same race-free claim path above.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const crossProcessLock_1 = require("./crossProcessLock");
+// A claim older than this with no update is treated the same as a dead-pid
+// claim — reclaimable. Longer than crossProcessLock's STALE_MS (that guards a
+// single tool call; this guards an entire unit of work a session might
+// legitimately spend minutes on).
+const CLAIM_STALE_MS = 30 * 60 * 1000; // 30 minutes
+// Minimum age a claim must have before a DEAD-PID signal is trusted to mean
+// "abandoned" (as opposed to CLAIM_STALE_MS above, which is the fallback for
+// a claim whose pid is still alive but has gone quiet). Real bug this closes
+// (caught by sharedTasks.test.mjs's genuine two-process claim race, which
+// failed intermittently until this existed): a session can legitimately exit
+// within milliseconds of successfully claiming a task — e.g. a short-lived
+// worker that claims, does a tiny unit of work, and exits — and
+// `process.kill(pid, 0)` reports that pid as dead the instant it's reaped, NOT
+// only once it's been dead a while. A second session racing to claim the same
+// task, arriving microseconds later, would see "pid dead" and treat a claim
+// that is completely valid (its owner exited normally, having done exactly
+// what it claimed the task to do) as abandoned trash to steal. A REAL crash
+// is still caught by this — just after MIN_CLAIM_AGE_FOR_DEATH_CHECK_MS have
+// passed, not instantly — which is an acceptable trade because the failure
+// mode of "wait a couple seconds longer to reclaim a genuinely dead claim" is
+// far cheaper than "two sessions think they both own the same unit of work".
+const MIN_CLAIM_AGE_FOR_DEATH_CHECK_MS = 2000;
+function tasksRoot() {
+    return process.env.NEXRALL_SHARED_TASKS_DIR || path.join(os.homedir(), '.nexrall', 'peers', 'tasks');
+}
+function scopeDir(workDir) {
+    const hash = crypto.createHash('sha256').update(path.resolve(workDir)).digest('hex').slice(0, 24);
+    return path.join(tasksRoot(), hash);
+}
+function taskPath(workDir, taskId) {
+    return path.join(scopeDir(workDir), `${taskId}.json`);
+}
+function readTask(workDir, taskId) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(taskPath(workDir, taskId), 'utf-8'));
+        if (raw && typeof raw.id === 'string' && typeof raw.status === 'string')
+            return raw;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeTask(workDir, task) {
+    const dir = scopeDir(workDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const p = taskPath(workDir, task.id);
+    // Same atomic-write-via-temp-then-rename reasoning as core's
+    // atomicWritePreservingMode: a crash mid-write must never leave a
+    // half-written JSON file that the next reader chokes on.
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(task));
+    fs.renameSync(tmp, p);
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A claimed task whose owning process is gone, or whose claim has gone stale with no update, is treated as abandoned. */
+function isClaimAbandoned(task) {
+    if (task.status !== 'in_progress')
+        return false;
+    const age = typeof task.claimedAt === 'number' ? Date.now() - task.claimedAt : Infinity;
+    // See MIN_CLAIM_AGE_FOR_DEATH_CHECK_MS's own comment for why a dead-pid
+    // verdict is withheld until the claim has existed for a minimum age —
+    // without this guard, a session that legitimately claims-then-exits
+    // quickly can have its still-valid claim stolen out from under it.
+    if (age >= MIN_CLAIM_AGE_FOR_DEATH_CHECK_MS && typeof task.claimedByPid === 'number' && !isPidAlive(task.claimedByPid))
+        return true;
+    if (age > CLAIM_STALE_MS)
+        return true;
+    return false;
+}
+/** Whether every task ID in `blockedBy` is `completed` — i.e. this task is actually claimable right now. */
+function isUnblocked(workDir, task) {
+    if (!task.blockedBy?.length)
+        return true;
+    return task.blockedBy.every((id) => readTask(workDir, id)?.status === 'completed');
+}
+/** List every task registered for `workDir`, newest first isn't guaranteed — sort by createdAt if display order matters to the caller. */
+function listSharedTasks(workDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(scopeDir(workDir));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        if (!name.endsWith('.json'))
+            continue;
+        const id = name.slice(0, -'.json'.length);
+        const t = readTask(workDir, id);
+        if (t)
+            out.push(t);
+    }
+    return out;
+}
+/** Create a new pending task. `id` auto-generated (short random) unless the caller supplies a stable one (e.g. re-registering from a static plan). */
+function createSharedTask(workDir, content, opts = {}) {
+    const id = opts.id ?? crypto.randomBytes(6).toString('hex');
+    const now = Date.now();
+    const task = {
+        id, content, status: 'pending',
+        blockedBy: opts.blockedBy?.length ? opts.blockedBy : undefined,
+        createdAt: now, updatedAt: now,
+    };
+    writeTask(workDir, task);
+    return task;
+}
+/**
+ * Atomically claim `taskId` for `claimedBy` (a peer/session name). Race-free
+ * against another process calling this at the same instant — see this
+ * module's header comment for exactly why.
+ */
+async function claimTask(workDir, taskId, claimedBy) {
+    // Lock scoped to (workDir, taskId) specifically — via crossProcessLock's
+    // opaque-key + workDir scoping (see its own header) — so claiming task A
+    // never blocks a concurrent claim of unrelated task B in the same project.
+    return (0, crossProcessLock_1.withCrossProcessLock)(`shared-task:${taskId}`, async () => {
+        const task = readTask(workDir, taskId);
+        if (!task)
+            return { ok: false, reason: 'not-found' };
+        // A task is claimable when it is 'pending' (the only status
+        // createSharedTask ever sets — 'blocked' is reserved for a future
+        // producer that wants to record the reason explicitly, but is treated
+        // identically to 'pending' here) OR an abandoned 'in_progress' claim
+        // (dead pid / stale timestamp — see isClaimAbandoned).
+        const claimable = task.status === 'pending' || task.status === 'blocked' || isClaimAbandoned(task);
+        if (!claimable) {
+            return { ok: false, reason: task.status === 'completed' ? 'not-pending' : 'already-claimed' };
+        }
+        if (!isUnblocked(workDir, task))
+            return { ok: false, reason: 'blocked' };
+        const now = Date.now();
+        const updated = {
+            ...task,
+            status: 'in_progress',
+            claimedBy,
+            claimedByPid: process.pid,
+            claimedAt: now,
+            updatedAt: now,
+        };
+        writeTask(workDir, updated);
+        return { ok: true, task: updated };
+    }, workDir);
+}
+/**
+ * Update a task's status. Used for both normal progress (in_progress →
+ * completed) and releasing a claim early (in_progress → pending, e.g. a
+ * session that claimed a task then decided not to do it after all). Also
+ * lock-guarded — a status update racing a claim attempt must not corrupt
+ * either operation's view of the task.
+ */
+async function updateSharedTaskStatus(workDir, taskId, status, opts = {}) {
+    return (0, crossProcessLock_1.withCrossProcessLock)(`shared-task:${taskId}`, async () => {
+        const task = readTask(workDir, taskId);
+        if (!task)
+            return { ok: false, reason: 'not-found' };
+        // A task can only be marked done/reopened by whoever holds the claim —
+        // prevents session B from marking session A's in-progress task
+        // completed out from under it. Not enforced for a task with NO current
+        // claim (status pending/blocked → anyone may set it, e.g. un-blocking).
+        if (task.status === 'in_progress' && task.claimedBy && opts.claimedBy && task.claimedBy !== opts.claimedBy) {
+            return { ok: false, reason: 'already-claimed' };
+        }
+        const updated = {
+            ...task,
+            status,
+            updatedAt: Date.now(),
+            ...(status === 'pending' || status === 'completed' ? { claimedBy: undefined, claimedByPid: undefined, claimedAt: undefined } : {}),
+        };
+        writeTask(workDir, updated);
+        return { ok: true, task: updated };
+    }, workDir);
+}
+exports._sharedTasksInternal = { tasksRoot, scopeDir, taskPath, isClaimAbandoned, isUnblocked, CLAIM_STALE_MS, MIN_CLAIM_AGE_FOR_DEATH_CHECK_MS };
+//# sourceMappingURL=sharedTasks.js.map

package/dist/agent/worktree.d.ts

@@ -0,0 +1,111 @@
+export interface WorktreeState {
+    /** Absolute path to the isolated worktree directory the session is confined to. */
+    worktreePath: string;
+    /** Absolute path to the main checkout / original workDir the isolation protects. */
+    mainCheckout: string;
+    /** Which backend created this worktree — determines how EnterWorktree enforcement and cleanup behave. */
+    backend: 'git' | 'copy' | 'hook';
+    /** Branch name, only meaningful for the git backend. */
+    branch?: string;
+    /** Human-facing name (also the directory's basename under .nexrall/worktrees/). */
+    name: string;
+}
+declare function isGitRepo(dir: string): {
+    ok: boolean;
+    root?: string;
+};
+/** Generate a readable random name, same shape Claude Code uses ("bright-running-fox"). */
+export declare function randomWorktreeName(): string;
+declare function safeName(name: string): string;
+/**
+ * Look for a project-supplied override hook: `.nexrall/hooks/worktree-<phase>`
+ * (an executable script/command), same escape hatch Claude Code's docs
+ * describe for non-git version control. Returns the command string to run,
+ * or null if the project hasn't defined one for this phase.
+ */
+declare function findWorktreeHook(workDir: string, phase: 'create' | 'enter' | 'exit'): string | null;
+declare function copyRecursive(src: string, dest: string): void;
+export interface CreateWorktreeResult {
+    ok: boolean;
+    state?: WorktreeState;
+    error?: string;
+}
+/**
+ * Create an isolated worktree for `workDir`, choosing the best backend
+ * automatically:
+ *   1. A project-supplied `.nexrall/hooks` override for 'create', if defined
+ *      (works for ANY VCS, or a fully custom isolation scheme).
+ *   2. Git-native `git worktree add`, if workDir is inside a git repo.
+ *   3. Plain recursive copy (skips COPY_SKIP_DIRS), as a zero-config
+ *      fallback that always works.
+ */
+export declare function createWorktree(workDir: string, requestedName?: string): CreateWorktreeResult;
+export interface RemoveWorktreeOptions {
+    /** Force removal even if the worktree has uncommitted/untracked changes. Mirrors Claude Code's own confirm-before-destroy default. */
+    force?: boolean;
+}
+export interface RemoveWorktreeResult {
+    ok: boolean;
+    /** True when the worktree had real work in it (dirty git tree, or ANY file, for copy-based) and removal was skipped without `force`. */
+    hadWork?: boolean;
+    error?: string;
+}
+/** Whether a worktree has anything in it worth not silently discarding. */
+export declare function worktreeHasWork(state: WorktreeState): boolean;
+export declare function removeWorktree(state: WorktreeState, opts?: RemoveWorktreeOptions): RemoveWorktreeResult;
+/**
+ * Called when a session ENTERS an already-created worktree (including
+ * re-entering across a resume). Fires the project's 'enter' hook if defined
+ * — informational only for the git/copy backends (nothing to actually do:
+ * the directory already exists and is already the session's cwd), but
+ * REQUIRED for the 'hook' backend, which may need to check out/refresh
+ * VCS-specific state each time.
+ */
+export declare function enterWorktree(state: WorktreeState): {
+    ok: boolean;
+    error?: string;
+};
+/**
+ * True when `absPath` resolves to somewhere inside the MAIN CHECKOUT that
+ * isolation is meant to protect, while NOT being inside the currently active
+ * worktree — the check `blockOutsideWorktree` (in executor.ts) uses to
+ * refuse a write/bash-cwd that targets the wrong tree. This is exactly the
+ * check Claude Code's own worktree docs describe: "blocks an Edit, Write, or
+ * NotebookEdit that targets a path in the main checkout" — NOT "any path
+ * outside the worktree" (a write to some unrelated directory elsewhere on
+ * disk isn't the hazard this specific check exists to prevent; ordinary
+ * sandbox/permission rules still govern that separately).
+ *
+ * The git/copy backends nest the worktree INSIDE the main checkout
+ * (`<mainCheckout>/.nexrall/worktrees/<name>`), so "inside mainCheckout" on
+ * its own would wrongly flag every path inside a perfectly legitimate
+ * worktree — this function excludes the active worktree's own subtree first.
+ *
+ * Deliberately resolves symlinks (fs.realpathSync) so a symlink planted
+ * INSIDE the worktree that points back at the main checkout can't be used to
+ * defeat the check — the same class of bypass Claude Code's own worktree
+ * docs call out for git redirects.
+ */
+export declare function pathEscapesWorktree(absPath: string, state: WorktreeState): boolean;
+declare function metadataPath(worktreePath: string): string;
+/**
+ * List every worktree registered under `workDir`'s `.nexrall/worktrees/`,
+ * reconstructed from each one's metadata file. Skips (rather than throws on)
+ * a directory with no readable metadata — e.g. one a user created by hand,
+ * or debris from an older version — since one bad entry must not hide every
+ * legitimate one from a session picker.
+ */
+export declare function listWorktrees(workDir: string): WorktreeState[];
+/** Find a previously created worktree by name, for resuming into it in a fresh process. */
+export declare function findWorktreeByName(workDir: string, name: string): WorktreeState | null;
+export declare const _worktreeInternal: {
+    isGitRepo: typeof isGitRepo;
+    safeName: typeof safeName;
+    copyRecursive: typeof copyRecursive;
+    findWorktreeHook: typeof findWorktreeHook;
+    COPY_SKIP_DIRS: Set<string>;
+    WORKTREE_ROOT_DIRNAME: string;
+    metadataPath: typeof metadataPath;
+};
+export {};
+//# sourceMappingURL=worktree.d.ts.map

package/dist/agent/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/agent/worktree.ts"],"names":[],"mappings":"AAgDA,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,yGAAyG;IACzG,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;CACd;AAiBD,iBAAS,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAQ9D;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAED,iBAAS,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtC;AAED;;;;;GAKG;AACH,iBAAS,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAW5F;AAuBD,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CActD;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAiD5F;AAED,MAAM,WAAW,qBAAqB;IACpC,sIAAsI;IACtI,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,wIAAwI;IACxI,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAmC7D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,GAAE,qBAA0B,GAAG,oBAAoB,CAgD3G;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAMnF;AA6CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAMlF;AAgBD,iBAAS,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAElD;AA2BD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CAY9D;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAEtF;AAED,eAAO,MAAM,iBAAiB;;;;;;;;CAAgH,CAAC"}