@nexrall/code-core 1.4.29 → 1.4.31

package/dist/agent/agentTypes.d.ts

@@ -35,6 +35,20 @@ export interface AgentType {
      *   user    — ~/.nexrall/agent-memory/<name>.md     (follows you everywhere)
      */
     memory?: AgentMemoryScope;
+    /**
+     * Skip the project's nexrall.md for this agent, keeping its prompt lean.
+     *
+     * Claude Code does the same for its two research builtins (Explore and Plan skip
+     * CLAUDE.md and git status to stay fast and cheap), and the reasoning transfers: a
+     * search-and-report agent re-reads the entire project instruction file on EVERY
+     * invocation, on the tier chosen for being cheap, to produce output the main agent
+     * then interprets WITH that context anyway. The rules that must reach it belong in the
+     * delegation prompt instead.
+     *
+     * Only for agents that neither write files nor make judgement calls about conventions
+     * — a reviewer or test-writer needs the project's rules, an explorer does not.
+     */
+    lightPrompt?: boolean;
 }
 /** Where a sub-agent's own persistent notes live. */
 export type AgentMemoryScope = 'project' | 'user' | 'local';

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

@@ -1 +1 @@
-{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACpD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAwS5D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAyKD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAqB5G;AAED,yFAAyF;AACzF,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAE3C;AACD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAY1D;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAIjG"}
+{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACpD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AA4U5D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAyKD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAqB5G;AAED,yFAAyF;AACzF,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAE3C;AACD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAY1D;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAIjG"}

package/dist/agent/agentTypes.js

@@ -115,6 +115,37 @@ const WRITE_TOOLS = [
     'notebook_edit',
 ];
 const BUILTIN_AGENTS = [
+    {
+        // The catch-all, matching Claude Code's `general-purpose`.
+        //
+        // This capability already existed — omitting `subagent_type` gives an unrestricted
+        // sub-agent — but it had no NAME, and that had two consequences worth fixing:
+        //
+        //   1. `permissions.deny: ["task(...)"]` matches on the agent name, so the ONE
+        //      sub-agent that can write files and run bash was the one variant a project
+        //      could not disable individually. Only a blanket `deny: ["task"]` reached it.
+        //   2. The model had to infer that leaving the field blank was even an option, so
+        //      it would sometimes pick a specialist that fitted badly (an unrestricted
+        //      explorer) rather than the general worker it actually wanted.
+        //
+        // `tools` is deliberately UNDEFINED, which means "no allowlist" — full access,
+        // inheriting whatever the session permits. That is the same power an unnamed
+        // sub-task always had; naming it changes only who can see and deny it. The safety
+        // properties elsewhere still apply: plan mode is inherited, the user's permission
+        // gate still runs on every call, and it cannot spawn further sub-agents.
+        name: 'general-purpose',
+        description: 'General-purpose worker for a multi-step task that needs BOTH exploration and changes ' +
+            '(edit files, run commands) and that no specialist above fits. Inherits the session model ' +
+            'and full tool access, so prefer a narrower agent when one matches.',
+        prompt: 'You are a general-purpose engineering sub-agent. Work the task end to end: explore what you ' +
+            'need, make the changes, and verify them with the project\'s own build/test commands.\n\n' +
+            'Rules:\n' +
+            '- Mirror existing conventions; make the smallest correct change.\n' +
+            '- Verify before you claim success. If you could not verify, say so explicitly.\n' +
+            '- Your FINAL MESSAGE is the only thing that reaches the main agent: state what you changed ' +
+            '(with file paths), what you ran and its outcome, and anything you deliberately left undone.',
+        source: 'builtin',
+    },
     {
         name: 'reviewer',
         description: 'Read-only code reviewer — finds correctness bugs, edge cases, and security issues in a diff or file set. Cannot modify files.',
@@ -177,6 +208,9 @@ const BUILTIN_AGENTS = [
     // frontier model, and this is the agent most likely to be spawned in bulk.
     {
         name: 'explorer',
+        // Lean prompt: this agent exists to keep bulk searching cheap, and it reports
+        // findings for the MAIN agent to interpret with full project context.
+        lightPrompt: true,
         description: 'Fast read-only codebase explorer — locates files, symbols, and call sites and reports concise findings. Use to keep bulk searching out of the main context. Cannot modify files.',
         tools: READ_ONLY_TOOLS,
         model: 'turbo',

package/dist/agent/loop.d.ts

@@ -85,12 +85,58 @@ export declare function stopReasonNotice(reason: StopReason, ctx?: {
     repeatError?: string | null;
 }): string | null;
 export declare function resolveMaxIterations(optionValue: number | undefined, settingsRaw: Record<string, unknown>): number;
+/**
+ * Whether a bash command should take the repo-state lock.
+ *
+ * Exported for tests: the failure mode (two concurrent `git commit`) is timing-dependent
+ * and painful to reproduce through the real loop.
+ *
+ * Scans EVERY segment, not just the first word, because the mutating verb is routinely
+ * not leading: `cd packages/core && npm publish`, `FOO=1 git push`, `ls && git commit`.
+ * Checking only the first token would miss most real commands.
+ */
+export declare function bashNeedsRepoLock(command: string): boolean;
+/**
+ * Every path a tool call will touch, so all of them can be locked.
+ *
+ * `move_file`/`copy_file` carry `source` + `destination`, the rest carry `path`. Both
+ * `dest` and `destination` are accepted because the schema has used both spellings and
+ * silently missing the key would mean silently losing the lock — a failure that shows
+ * up as corrupted content rather than an error.
+ *
+ * Exported for tests: getting this wrong is invisible until two writes race.
+ */
+export declare function lockPathsFor(name: string, input: Record<string, unknown>, workDir?: string): string[];
+/**
+ * Resolve the fan-out limit: env → settings.json → default.
+ *
+ * Was env-ONLY, the same gap as the sub-task timeout: a project on a small machine that
+ * wanted 2, or a big one that wanted 6, had to set a shell variable, and nobody reading
+ * settings.json could see what the limit even was. Capped at 16 because this bounds real
+ * shared resources (CPU, the API rate limit, file handles) and a typo like 400 should
+ * degrade to "a lot" rather than fork-bomb the machine.
+ */
+export declare function resolveMaxConcurrentSubtasks(settingsRaw?: Record<string, unknown>): number;
 /**
  * Minimal concurrency gate. Hand-rolled rather than pulling in `p-limit` because
  * the CLI ships as a single esbuild bundle with no node_modules, and this is a
  * dozen lines.
  */
 export declare function createLimiter(max: number): <T>(fn: () => Promise<T>) => Promise<T>;
+/** Test-only: forget the memoised limiter so a new limit can take effect. */
+export declare function _resetSubTaskLimiter(): void;
+/**
+ * How long a sub-agent may make NO progress before it is stopped.
+ *
+ * Precedence matches every other tunable in this file
+ * (env → settings.json → default) — it used to be env-ONLY, which meant a project that
+ * legitimately needed longer sub-tasks had no way to say so in the file where every
+ * other such preference lives, and the limit was invisible to anyone reading settings.
+ *
+ * Exported for tests: the behaviour that matters (a long-but-productive sub-agent is
+ * NOT killed) takes minutes of wall clock to exercise through the real loop.
+ */
+export declare function resolveSubtaskTimeoutMs(settingsRaw: Record<string, unknown>): number;
 /**
  * Thrown by a sub-agent's permission gate when the AGENT DEFINITION forbids a
  * tool — as opposed to the user declining it.
@@ -135,6 +181,16 @@ export declare function capSubTaskText(text: string, max?: number): string;
  * had already been billed in full.
  */
 export declare function summariseSubTaskProgress(messages: Message[]): string;
+/**
+ * The last N tool results from a transcript, newest last, each truncated.
+ *
+ * Pure + exported so the salvage rules are testable without a real sub-agent.
+ *
+ * Truncation keeps the HEAD of each result: tool output is overwhelmingly
+ * front-loaded (a file starts with its imports, a failing command starts with its
+ * error), and a head slice is the half that identifies what was found.
+ */
+export declare function lastToolResults(messages: Message[], count: number, maxChars: number): string;
 /** The context window (tokens) for a model alias — the same lookup runAgentLoop uses internally. */
 export declare function contextWindowFor(model?: 'turbo' | 'pro' | 'ultra'): number;
 /** Auto-prune / auto-compact thresholds as fractions of the context window — for UI display (e.g. `/context`). */

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

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

package/dist/agent/loop.js

@@ -38,10 +38,16 @@ exports.errorRoundSignature = errorRoundSignature;
 exports.executeAgentMemoryWrite = executeAgentMemoryWrite;
 exports.stopReasonNotice = stopReasonNotice;
 exports.resolveMaxIterations = resolveMaxIterations;
+exports.bashNeedsRepoLock = bashNeedsRepoLock;
+exports.lockPathsFor = lockPathsFor;
+exports.resolveMaxConcurrentSubtasks = resolveMaxConcurrentSubtasks;
 exports.createLimiter = createLimiter;
+exports._resetSubTaskLimiter = _resetSubTaskLimiter;
+exports.resolveSubtaskTimeoutMs = resolveSubtaskTimeoutMs;
 exports.extractSubTaskText = extractSubTaskText;
 exports.capSubTaskText = capSubTaskText;
 exports.summariseSubTaskProgress = summariseSubTaskProgress;
+exports.lastToolResults = lastToolResults;
 exports.contextWindowFor = contextWindowFor;
 exports.compactionThresholds = compactionThresholds;
 exports.estimateBodyBytes = estimateBodyBytes;
@@ -385,6 +391,113 @@ async function withFileLock(absPath, fn) {
             _fileLocks.delete(absPath);
     }
 }
+/**
+ * Take several locks at once, always in a globally consistent order.
+ *
+ * Needed because move_file/copy_file touch TWO paths. Locking only one of them (the
+ * old behaviour locked `source` and left `dest` unprotected) leaves exactly the race
+ * the lock exists to prevent: a `move_file{dest:'shared.ts'}` running concurrently with
+ * an `edit_file{path:'shared.ts'}` had nothing serialising them.
+ *
+ * The sort is load-bearing, not tidiness: two callers acquiring {A,B} and {B,A} at the
+ * same time would deadlock, each holding what the other waits for. Sorting means every
+ * caller in the process takes them in the same order, which makes that impossible.
+ */
+async function withFileLocks(absPaths, fn) {
+    const unique = [...new Set(absPaths.filter(Boolean))].sort();
+    if (unique.length === 0)
+        return fn();
+    const [first, ...rest] = unique;
+    return withFileLock(first, () => (rest.length ? withFileLocks(rest, fn) : fn()));
+}
+/** Tools that mutate the filesystem and must be serialised per path. */
+const WRITE_TOOLS = new Set([
+    'write_file', 'edit_file', 'multi_edit', 'delete_file', 'move_file', 'copy_file', 'notebook_edit',
+]);
+/**
+ * Shared lock key for bash commands that mutate repository-wide state.
+ *
+ * Not a path, because these commands do not declare one — `git commit` contends over
+ * `.git/index.lock`, `npm install` over `node_modules` and the lockfile. One key means
+ * they serialise against each other while everything else stays parallel.
+ */
+const REPO_STATE_LOCK = '\u0000repo-state';
+/**
+ * Commands that must not run concurrently with another instance of themselves.
+ *
+ * `bash` was excluded from the write-tool lock entirely, which was the largest hole in
+ * the concurrency story: it is the most mutating tool there is, and with 4 sub-agents
+ * fanned out two of them could run `git commit` simultaneously (one dies on
+ * `.git/index.lock`), or two `npm install` (corrupted node_modules / lockfile), or two
+ * `npm test` writing the same coverage and snapshot files (wrong results, not an error).
+ * The comment above withFileLock explains carefully why two edit_file calls must be
+ * sequenced, then a `bash -c 'echo x > file'` did exactly that with nothing holding it.
+ *
+ * Deliberately a VERB ALLOWLIST rather than serialising all of bash: an explorer's
+ * `grep`/`rg`/`ls`/`cat` are read-only and are precisely the calls that benefit most
+ * from running in parallel. Serialising those would trade a real correctness bug for a
+ * real performance regression. These verbs are the ones that take a global lock, write
+ * a lockfile, or mutate a shared build/dependency directory.
+ */
+const MUTATING_BASH_VERBS = new Set([
+    'git', 'npm', 'pnpm', 'yarn', 'bun', 'cargo', 'go', 'pip', 'pip3', 'poetry', 'uv',
+    'bundle', 'composer', 'gradle', 'mvn', 'make', 'terraform', 'helm', 'docker',
+    'vsce', 'tsc', 'pytest', 'dotnet', 'swift', 'gem',
+]);
+/**
+ * Whether a bash command should take the repo-state lock.
+ *
+ * Exported for tests: the failure mode (two concurrent `git commit`) is timing-dependent
+ * and painful to reproduce through the real loop.
+ *
+ * Scans EVERY segment, not just the first word, because the mutating verb is routinely
+ * not leading: `cd packages/core && npm publish`, `FOO=1 git push`, `ls && git commit`.
+ * Checking only the first token would miss most real commands.
+ */
+function bashNeedsRepoLock(command) {
+    if (!command)
+        return false;
+    // Split on shell separators, then take the first bare word of each segment, skipping
+    // env-var assignments (FOO=bar git push) and `sudo`/`time`-style prefixes.
+    const segments = command.split(/\|\||&&|[;|&\n()]|\$\(/);
+    for (const seg of segments) {
+        for (const tokenRaw of seg.trim().split(/\s+/)) {
+            const token = tokenRaw.replace(/^["']|["']$/g, '');
+            if (!token)
+                continue;
+            if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token))
+                continue; // env assignment
+            if (token === 'sudo' || token === 'time' || token === 'nice' || token === 'env')
+                continue;
+            // Use the basename so `/usr/bin/git` and `./node_modules/.bin/tsc` still match.
+            const verb = token.split('/').pop() ?? token;
+            if (MUTATING_BASH_VERBS.has(verb))
+                return true;
+            break; // only the command word of each segment matters
+        }
+    }
+    return false;
+}
+/**
+ * Every path a tool call will touch, so all of them can be locked.
+ *
+ * `move_file`/`copy_file` carry `source` + `destination`, the rest carry `path`. Both
+ * `dest` and `destination` are accepted because the schema has used both spellings and
+ * silently missing the key would mean silently losing the lock — a failure that shows
+ * up as corrupted content rather than an error.
+ *
+ * Exported for tests: getting this wrong is invisible until two writes race.
+ */
+function lockPathsFor(name, input, workDir) {
+    if (!WRITE_TOOLS.has(name))
+        return [];
+    const raw = [input.path, input.source, input.destination, input.dest]
+        .filter((p) => typeof p === 'string' && p.length > 0);
+    const abs = raw.map((p) => (workDir ? path.resolve(workDir, p) : p));
+    // Fall back to the tool name so a malformed call still serialises against itself
+    // rather than escaping the lock entirely.
+    return abs.length ? abs : [name];
+}
 // ─── Sub-agent fan-out limiter ────────────────────────────────────────────────
 //
 // Tool calls in one turn run via Promise.all with no ceiling. For ordinary tools
@@ -405,10 +518,26 @@ async function withFileLock(absPath, fn) {
 //
 // This is a QUEUE, not a rejection: every sub-task still runs, just at most N at a
 // time. Failing the excess would be worse than serialising it.
-const MAX_CONCURRENT_SUBTASKS = (() => {
-    const raw = Number(process.env.NEXRALL_MAX_CONCURRENT_SUBTASKS);
-    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 4;
-})();
+const DEFAULT_MAX_CONCURRENT_SUBTASKS = 4;
+/**
+ * Resolve the fan-out limit: env → settings.json → default.
+ *
+ * Was env-ONLY, the same gap as the sub-task timeout: a project on a small machine that
+ * wanted 2, or a big one that wanted 6, had to set a shell variable, and nobody reading
+ * settings.json could see what the limit even was. Capped at 16 because this bounds real
+ * shared resources (CPU, the API rate limit, file handles) and a typo like 400 should
+ * degrade to "a lot" rather than fork-bomb the machine.
+ */
+function resolveMaxConcurrentSubtasks(settingsRaw = {}) {
+    const clamp = (n) => Math.min(Math.floor(n), 16);
+    const fromEnv = Number(process.env.NEXRALL_MAX_CONCURRENT_SUBTASKS);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return clamp(fromEnv);
+    const fromSettings = Number(settingsRaw.maxConcurrentSubtasks);
+    if (Number.isFinite(fromSettings) && fromSettings > 0)
+        return clamp(fromSettings);
+    return DEFAULT_MAX_CONCURRENT_SUBTASKS;
+}
 /**
  * Minimal concurrency gate. Hand-rolled rather than pulling in `p-limit` because
  * the CLI ships as a single esbuild bundle with no node_modules, and this is a
@@ -436,7 +565,28 @@ function createLimiter(max) {
 // Process-wide, deliberately: the limit exists to protect shared resources (CPU,
 // the API rate limit, file handles), and those are shared across every concurrent
 // turn in this process, not just the tool calls of one message.
-const _subTaskLimit = createLimiter(MAX_CONCURRENT_SUBTASKS);
+//
+// Built LAZILY on first use rather than at module load, because the limit can now come
+// from settings.json and the workspace is not known when this module is imported.
+// Once created it is reused for the process lifetime — rebuilding it per turn would
+// reset `active` and let the ceiling be exceeded, which is worse than not honouring a
+// mid-session settings change.
+let _subTaskLimitInstance = null;
+let _subTaskLimitMax = 0;
+/** Sub-tasks dispatched but not yet finished — used only to detect queueing. */
+let _inFlightSubTasks = 0;
+function subTaskLimiter(workDir) {
+    if (!_subTaskLimitInstance) {
+        _subTaskLimitMax = resolveMaxConcurrentSubtasks(workDir ? (0, rules_1.loadSettings)(workDir).raw : {});
+        _subTaskLimitInstance = createLimiter(_subTaskLimitMax);
+    }
+    return { run: _subTaskLimitInstance, max: _subTaskLimitMax };
+}
+/** Test-only: forget the memoised limiter so a new limit can take effect. */
+function _resetSubTaskLimiter() {
+    _subTaskLimitInstance = null;
+    _subTaskLimitMax = 0;
+}
 // ─── Human-readable tool descriptions ────────────────────────────────────────
 function humanDescription(name, input) {
     switch (name) {
@@ -539,9 +689,28 @@ let _subTaskCounter = 0; // unique per-process id → per-sub-agent todo scope
 // pointing at it specifically. Give every sub-task an explicit wall-clock cap:
 // if it hasn't finished by then, fail it clearly instead of hanging the parent
 // turn indefinitely. Overridable via env for slow CI machines / huge sub-tasks.
-const SUBTASK_TIMEOUT_MS = Number(process.env.NEXRALL_SUBTASK_TIMEOUT_MS) > 0
-    ? Number(process.env.NEXRALL_SUBTASK_TIMEOUT_MS)
-    : 10 * 60 * 1000; // 10 minutes, matching the general industry norm for a stalled-agent cutoff
+const DEFAULT_SUBTASK_TIMEOUT_MS = 10 * 60 * 1000; // 10 min of NO PROGRESS (see the watchdog)
+/**
+ * How long a sub-agent may make NO progress before it is stopped.
+ *
+ * Precedence matches every other tunable in this file
+ * (env → settings.json → default) — it used to be env-ONLY, which meant a project that
+ * legitimately needed longer sub-tasks had no way to say so in the file where every
+ * other such preference lives, and the limit was invisible to anyone reading settings.
+ *
+ * Exported for tests: the behaviour that matters (a long-but-productive sub-agent is
+ * NOT killed) takes minutes of wall clock to exercise through the real loop.
+ */
+function resolveSubtaskTimeoutMs(settingsRaw) {
+    const fromEnv = Number(process.env.NEXRALL_SUBTASK_TIMEOUT_MS);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return Math.floor(fromEnv);
+    const raw = settingsRaw.subtaskTimeoutMs;
+    const fromSettings = Number(raw);
+    if (Number.isFinite(fromSettings) && fromSettings > 0)
+        return Math.floor(fromSettings);
+    return DEFAULT_SUBTASK_TIMEOUT_MS;
+}
 /** Cap on the text a sub-task hands back, so one verbose sub-agent can't blow up
  *  the PARENT's context in a single tool_result. */
 const SUBTASK_MAX = 48000; // chars (~12k tokens)
@@ -648,6 +817,14 @@ function summariseSubTaskProgress(messages) {
     }
     if (toolNames.length === 0)
         return '';
+    // The FINDINGS, not just the activity log.
+    //
+    // An inventory of tool names ("read_file ×9, bash ×14") tells the parent that work
+    // happened but nothing about what was learned, so it re-derives everything. A stalled
+    // research agent's value is almost entirely in what its last few tool calls RETURNED
+    // — the file it had just read, the command output it was about to interpret — because
+    // its own prose summary is exactly the thing it never got to write.
+    const recentFindings = lastToolResults(messages, SALVAGE_RESULT_COUNT, SALVAGE_RESULT_CHARS);
     // Collapse to "name ×N" so a 40-call run reads as a short inventory rather
     // than forty repeated lines of the same tool name.
     const counts = new Map();
@@ -657,7 +834,71 @@ function summariseSubTaskProgress(messages) {
         .sort((a, b) => b[1] - a[1])
         .map(([name, n]) => (n > 1 ? `${name} ×${n}` : name))
         .join(', ');
-    return `Tool calls completed before it was stopped (${toolNames.length} total): ${inventory}.`;
+    const header = `Tool calls completed before it was stopped (${toolNames.length} total): ${inventory}.`;
+    return recentFindings
+        ? `${header}\n\nWhat its most recent tool calls actually returned (use this instead of repeating them):\n${recentFindings}`
+        : header;
+}
+/** How many trailing tool results to salvage, and how much of each. */
+const SALVAGE_RESULT_COUNT = 4;
+const SALVAGE_RESULT_CHARS = 2000;
+/**
+ * The last N tool results from a transcript, newest last, each truncated.
+ *
+ * Pure + exported so the salvage rules are testable without a real sub-agent.
+ *
+ * Truncation keeps the HEAD of each result: tool output is overwhelmingly
+ * front-loaded (a file starts with its imports, a failing command starts with its
+ * error), and a head slice is the half that identifies what was found.
+ */
+function lastToolResults(messages, count, maxChars) {
+    // Map tool_use id → tool name, so a salvaged result can say WHICH tool produced it.
+    const nameById = new Map();
+    for (const m of messages) {
+        if (m.role !== 'assistant' || !Array.isArray(m.content))
+            continue;
+        for (const b of m.content) {
+            if (b?.type === 'tool_use' && b.id && typeof b.name === 'string')
+                nameById.set(b.id, b.name);
+        }
+    }
+    const out = [];
+    // Walk backwards and stop early: only the most recent results are worth the tokens,
+    // and a long research run may hold hundreds.
+    for (let i = messages.length - 1; i >= 0 && out.length < count; i--) {
+        const m = messages[i];
+        if (m.role !== 'user' || !Array.isArray(m.content))
+            continue;
+        for (const b of [...m.content].reverse()) {
+            if (out.length >= count)
+                break;
+            if (b?.type !== 'tool_result')
+                continue;
+            const text = toolResultText(b);
+            if (!text)
+                continue;
+            const name = nameById.get(String(b.tool_use_id ?? '')) ?? 'tool';
+            const body = text.length > maxChars
+                ? `${sliceSafeEnd(text, maxChars)}\n… [truncated]`
+                : text;
+            out.push(`• ${name}:\n${body}`);
+        }
+    }
+    return out.reverse().join('\n\n');
+}
+/** Extract readable text from a tool_result block, whose content may be string or blocks. */
+function toolResultText(block) {
+    const c = block.content;
+    if (typeof c === 'string')
+        return c.trim();
+    if (Array.isArray(c)) {
+        return c
+            .filter((x) => x?.type === 'text' && typeof x.text === 'string')
+            .map((x) => x.text)
+            .join('\n')
+            .trim();
+    }
+    return '';
 }
 async function runSubTask(input, options, agentTypes) {
     const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
@@ -755,10 +996,14 @@ async function runSubTask(input, options, agentTypes) {
     const agentMemoryNotes = agent && memoryScope
         ? (0, memory_1.agentMemoryPreamble)(agent.name, memoryScope, options.workDir)
         : '';
+    // `lightPrompt` agents skip the project's nexrall.md — see AgentType.lightPrompt for
+    // why. The role prompt and any private notes still apply; only the (potentially very
+    // large) project instruction file is dropped.
+    const inheritedMd = agent?.lightPrompt ? '' : (options.nexrallMd ?? '');
     const subNexrallMd = agent
         ? `# Sub-agent role: ${agent.name}\n${agent.prompt}` +
             (agentMemoryNotes ? `\n\n---\n\n${agentMemoryNotes}` : '') +
-            (options.nexrallMd ? `\n\n---\n\n${options.nexrallMd}` : '')
+            (inheritedMd ? `\n\n---\n\n${inheritedMd}` : '')
         : options.nexrallMd;
     // Optional tool allowlist — deny anything outside it for this sub-agent.
     //
@@ -809,7 +1054,34 @@ async function runSubTask(input, options, agentTypes) {
     // runAgentLoop already checks abortSignal.aborted at every iteration boundary,
     // so this is enough to make it stop promptly without a forceful kill.
     const subAbort = { aborted: false };
-    const timer = setTimeout(() => { subAbort.aborted = true; }, SUBTASK_TIMEOUT_MS);
+    const subtaskTimeoutMs = resolveSubtaskTimeoutMs((0, rules_1.loadSettings)(options.workDir).raw);
+    // ── Stall watchdog, NOT a total-runtime deadline ─────────────────────────────
+    //
+    // This used to be a single setTimeout armed once and never refreshed. Its own
+    // comment called it a "stalled-agent cutoff", but it measured TOTAL LIFETIME: a
+    // sub-agent working hard and calling a tool every few seconds was killed at ten
+    // minutes exactly like one that had hung. That is not a hypothetical — auditing a
+    // handful of 600-2800 line files legitimately exceeds it, and when it fired the
+    // parent got back a fragment ("I'll start by reading the files…") after paying for
+    // 23 tool calls, then typically re-ran the whole thing.
+    //
+    // The main loop already draws this distinction correctly (client.ts's heartbeat vs
+    // progress watchdogs, where only real events bump lastProgressAt). Sub-agents now do
+    // too: the clock resets on every completed tool round, so the cap means "no progress
+    // for N minutes" — which is what catches a genuine hang — while useful work can run
+    // as long as it keeps being useful.
+    //
+    // `stalled` is tracked separately from `subAbort.aborted` because the parent's Ctrl+C
+    // also sets the latter, and the two must be reported differently.
+    let lastProgressAt = Date.now();
+    let stalled = false;
+    const bumpProgress = () => { lastProgressAt = Date.now(); };
+    const stallWatchdog = setInterval(() => {
+        if (Date.now() - lastProgressAt > subtaskTimeoutMs) {
+            stalled = true;
+            subAbort.aborted = true;
+        }
+    }, 1000);
     // Mirror the parent's own abort into the sub-agent's signal so Ctrl+C during
     // a running sub-task still stops it (previously this worked implicitly by
     // sharing the same object via `...options` — now that we own a distinct
@@ -823,11 +1095,27 @@ async function runSubTask(input, options, agentTypes) {
             ...options,
             _depth: depth + 1,
             _agentScope: `sub_${++_subTaskCounter}`, // isolated todo store per sub-agent
-            // Only set when the agent opted in, so the tool is inert for everyone else.
-            ...(agent && memoryScope ? { _agentMemory: { agentName: agent.name, scope: memoryScope } } : {}),
+            // ── Assigned UNCONDITIONALLY, never by conditional spread ────────────────
+            //
+            // These two were previously spread in only when set:
+            //
+            //   ...(agent && memoryScope ? { _agentMemory: … } : {}),
+            //
+            // which does NOT clear the key — it leaves whatever `...options` already had.
+            // So a child WITHOUT its own `memory:` inherited its PARENT's binding and would
+            // have appended to another agent's private notes; likewise an agent with no
+            // `tools:` line inherited the parent's allowlist, making the prompt's capability
+            // claim disagree with its real one.
+            //
+            // MAX_TASK_DEPTH === 1 means no nested spawn can reach this today, so it is
+            // latent rather than live — but the limiter comment below explicitly contemplates
+            // raising that depth, and this is exactly the kind of leak that would come back
+            // as a security bug rather than a visible error. Explicit undefined makes the
+            // child's identity independent of the parent's by construction.
+            _agentMemory: agent && memoryScope ? { agentName: agent.name, scope: memoryScope } : undefined,
             // The same set `gatedPermission` enforces above, so prompt and permission agree
             // by construction instead of by two people remembering to update both.
-            ...(allowed ? { _allowedTools: allowed } : {}),
+            _allowedTools: allowed ?? undefined,
             editorContext: null, // fresh isolated context for sub-agent
             model: agent?.model ?? options.model,
             // Plan mode is inherited, never relaxed. If the main agent could spawn a
@@ -856,13 +1144,20 @@ async function runSubTask(input, options, agentTypes) {
             // Forward tool events with isSubTask=true so the UI can render a badge
             // instead of prepending "[sub-task]" to the tool name (which caused double-prefix
             // when the name was already labelled, and mixed display concerns into the data layer).
-            onToolUse: (n, i) => options.onToolUse(n, i, true),
-            onToolResult: (n, r) => options.onToolResult(n, r, true),
+            // Every tool event is PROGRESS: it proves the sub-agent is still doing work, which
+            // is what the stall watchdog above measures. Bumping on both use and result means a
+            // single very slow tool (a long test run) resets the clock when it starts AND when
+            // it finishes, so it cannot be mistaken for a hang.
+            onToolUse: (n, i) => { bumpProgress(); options.onToolUse(n, i, true); },
+            onToolResult: (n, r) => { bumpProgress(); options.onToolResult(n, r, true); },
             onToolStreamChunk: (n, c) => options.onToolStreamChunk?.(n, c, true),
             // Forward thinking so the UI shows the indicator while sub-agent reasons
-            onThinking: (text) => options.onThinking?.(text),
-            onThinkingDelta: (text) => options.onThinkingDelta?.(text),
-            onThinkingProgress: (tok) => options.onThinkingProgress?.(tok),
+            // Thinking is progress too — a model reasoning for minutes on a hard problem is
+            // working, not stalled. Without this, deep reasoning on an expensive tier would
+            // trip the watchdog precisely when the sub-agent was most valuable.
+            onThinking: (text) => { bumpProgress(); options.onThinking?.(text); },
+            onThinkingDelta: (text) => { bumpProgress(); options.onThinkingDelta?.(text); },
+            onThinkingProgress: (tok) => { bumpProgress(); options.onThinkingProgress?.(tok); },
         });
         // ── Stall timeout: SALVAGE, don't discard ────────────────────────────────
         //
@@ -877,15 +1172,29 @@ async function runSubTask(input, options, agentTypes) {
         // whatever was actually accomplished, not instead of it. `preferLast: false`
         // because a killed sub-agent rarely has a closing summary — its useful output
         // is spread across the assistant turns it did manage to produce.
-        if (subAbort.aborted && !options.abortSignal?.aborted) {
-            const mins = Math.round(SUBTASK_TIMEOUT_MS / 60000);
+        if (stalled && !options.abortSignal?.aborted) {
+            const mins = Math.round(subtaskTimeoutMs / 60000);
             const partial = capSubTaskText(extractSubTaskText(result, false));
             const progress = summariseSubTaskProgress(result);
+            // Keep the transcript so the parent can CONTINUE this run instead of redoing it.
+            //
+            // Previously only a cleanly-finished sub-agent was remembered, on the reasoning
+            // that a transcript ending mid-thought is unsafe to build on. The reasoning is
+            // sound; the conclusion was too strong. Refusing to store it meant a stalled
+            // sub-agent's entire body of work — dozens of tool calls, already billed — was
+            // unreachable, so the parent's only option was the very thing we tell it not to
+            // do: run the whole task again. Resuming is now POSSIBLE but never implied to be
+            // safe: the text below states plainly that the work is unverified, and resumption
+            // re-authorises against current permissions exactly as it does for a clean run.
+            const partialId = (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result);
             const sections = [
-                `Sub-task STOPPED after ${mins} minutes without completing — treat the following as PARTIAL, unverified work, not a finished answer.`,
+                `Sub-task STOPPED after ${mins} minutes with NO PROGRESS (it was not making tool calls or ` +
+                    'producing output) — treat everything below as PARTIAL, unverified work, not a finished answer.',
                 progress,
                 partial ? `Partial output before it was stopped:\n\n${partial}` : '',
-                'Do NOT simply re-run the same sub-task: build on what is above, or split the remaining work into smaller, more focused sub-tasks.',
+                `Do NOT re-run the same sub-task from scratch. Either build on what is above, or continue THIS ` +
+                    `run with resume_agent_id="${partialId}" (it still has everything it read), or split the ` +
+                    'remaining work into smaller, more focused sub-tasks.',
             ].filter(Boolean);
             // Returned as `error` (not `output`) on purpose: the loop's ledger counts an
             // errored call as a non-effect, which is right — nothing here is verified —
@@ -934,7 +1243,7 @@ async function runSubTask(input, options, agentTypes) {
         return { error: `Sub-task failed: ${err.message}` };
     }
     finally {
-        clearTimeout(timer);
+        clearInterval(stallWatchdog);
         clearInterval(parentAbortPoll);
     }
 }
@@ -2265,9 +2574,30 @@ async function runAgentLoop(initialMessages, options) {
                     // waiting on a child that can never be scheduled, the run would wedge
                     // permanently. Keeping the limiter acyclic (a holder never re-enters it)
                     // means raising MAX_TASK_DEPTH later can't silently reintroduce that.
-                    result = depth === 0
-                        ? await _subTaskLimit(() => runSubTask(input, options, agentTypes))
-                        : await runSubTask(input, options, agentTypes);
+                    if (depth === 0) {
+                        const { run: limitRun, max: limitMax } = subTaskLimiter(options.workDir);
+                        // Tell the user when a sub-task is WAITING rather than working.
+                        //
+                        // With a burst of 8 and a ceiling of 4, the last four sat silently in the
+                        // queue. From the outside they looked started, so a long wait read as a
+                        // hang — and the fix for a hang (Ctrl+C and retry) is exactly wrong here,
+                        // since the work was about to run. `_inFlightSubTasks` is only ever
+                        // touched from this single dispatch point, so the count is exact.
+                        if (_inFlightSubTasks >= limitMax) {
+                            (options.onNotice ?? options.onText)(`\u23f3 Queued: ${limitMax} sub-agents are already running, so this one starts when a ` +
+                                `slot frees up (raise "maxConcurrentSubtasks" in .nexrall/settings.json to widen it).`);
+                        }
+                        _inFlightSubTasks++;
+                        try {
+                            result = await limitRun(() => runSubTask(input, options, agentTypes));
+                        }
+                        finally {
+                            _inFlightSubTasks--;
+                        }
+                    }
+                    else {
+                        result = await runSubTask(input, options, agentTypes);
+                    }
                 }
                 else {
                     const pre = runToolHooks(hooks.PreToolUse, 'PreToolUse', name, input, options.workDir);
@@ -2301,22 +2631,28 @@ async function runAgentLoop(initialMessages, options) {
                             else {
                                 // Snapshot pre-mutation state so the user can /rewind this turn.
                                 options.checkpointManager?.recordBeforeMutation(name, input);
-                                // Serialise writes to the same file: if the model emits two
-                                // edit_file/write_file calls for the same path in one turn
-                                // (executed via Promise.all), the second would overwrite the
-                                // first. withFileLock queues them so they apply sequentially.
-                                const WRITE_TOOLS = new Set(['write_file', 'edit_file', 'multi_edit', 'delete_file', 'move_file', 'copy_file', 'notebook_edit']);
                                 const onStream = options.onToolStreamChunk
                                     ? (chunk) => options.onToolStreamChunk(name, chunk)
                                     : undefined;
-                                if (WRITE_TOOLS.has(name)) {
-                                    const targetPath = (typeof input.path === 'string' ? input.path : typeof input.source === 'string' ? input.source : '');
-                                    const absTarget = targetPath && options.workDir ? path.resolve(options.workDir, targetPath) : targetPath;
-                                    result = await withFileLock(absTarget || name, () => (0, executor_1.executeTool)(name, input, options.abortSignal, sandboxCfg, options.workDir, agentScope, onStream));
-                                }
-                                else {
-                                    result = await (0, executor_1.executeTool)(name, input, options.abortSignal, sandboxCfg, options.workDir, agentScope, onStream);
-                                }
+                                const run = () => (0, executor_1.executeTool)(name, input, options.abortSignal, sandboxCfg, options.workDir, agentScope, onStream);
+                                // Serialise anything that would otherwise race. Two sources of races:
+                                //
+                                //  • Writes to the SAME PATH — the model emits multiple tool_use blocks
+                                //    per turn and they run via Promise.all, so two edit_file calls on
+                                //    one file would both read the original and the second would discard
+                                //    the first. Now ALL paths a call touches are locked (move_file and
+                                //    copy_file have two), in a globally consistent order.
+                                //  • Repo-wide state via bash — `git commit`, `npm install`, `npm test`.
+                                //    These declare no path, so they take one shared lock. Read-only
+                                //    commands (grep, ls, cat) are excluded and stay parallel, which is
+                                //    what an explorer agent spends nearly all its calls on.
+                                //
+                                // This matters far more with sub-agents than without: up to 4 run
+                                // concurrently, each issuing its own tool calls into this same process.
+                                const locks = name === 'bash'
+                                    ? (bashNeedsRepoLock(String(input.command ?? '')) ? [REPO_STATE_LOCK] : [])
+                                    : lockPathsFor(name, input, options.workDir);
+                                result = locks.length ? await withFileLocks(locks, run) : await run();
                             }
                         }
                         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexrall/code-core",
-  "version": "1.4.29",
+  "version": "1.4.31",
   "description": "Core agent loop, tools, and extension primitives for Nexrall Code — embed an AI coding agent in any Node.js application.",
   "license": "MIT",
   "author": "Nexrall <support@nexrall.com> (https://nexrall.com)",