mixdog 0.9.23 → 0.9.25

package/scripts/mcp-grace-deferred-test.mjs

@@ -0,0 +1,149 @@
+// Regression tests for turn-time deferred-manifest construction (claude-code
+// style). An MCP server that finishes its handshake BETWEEN session-create and
+// the user's FIRST send is folded — on the first turn, synchronously, with no
+// boot await — into the INITIAL <available-deferred-tools> manifest (BP1) and
+// pre-marked announced, so the first-turn tool-catalog reconcile emits NO late
+// <system-reminder> for it. A server that connects AFTER the first turn keeps
+// the append-only late-reminder path. Unit-style: exercise the tool-catalog
+// exports directly (no runtime, no spawn) the way session-turn-api/runtime-core
+// wire them.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+    applyDeferredToolSurface,
+    refreshInitialDeferredMcpSurface,
+    reconcileDeferredMcpToolCatalog,
+} from '../src/session-runtime/tool-catalog.mjs';
+
+function baseSession() {
+    return {
+        provider: 'legacy',
+        tools: [{ name: 'read', description: 'read a file' }, { name: 'grep', description: 'search' }],
+        messages: [{ role: 'system', content: 'BASE PROMPT' }],
+    };
+}
+
+// A freshly-created session: the create-time surface is baked WITHOUT any MCP
+// (server still mid-handshake at create). `shell` is a deferred (non-active)
+// standalone tool so BP1 carries a manifest block even before MCP arrives.
+function createdSession() {
+    const session = baseSession();
+    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }], { provider: 'legacy' });
+    return session;
+}
+
+function systemContent(session) {
+    return session.messages.find((m) => m.role === 'system').content;
+}
+
+const mcpTool = { name: 'mcp__unity__get_scene', description: 'Return the active Unity scene graph.' };
+const mcpTool2 = { name: 'mcp__unity__run_tests', description: 'Run the Unity test runner.' };
+
+// Mirror the session-turn-api first-turn gate: refresh runs ONCE, only for a
+// session flagged fresh (deferredInitialRefreshPending) at create; a resumed
+// session (reloaded transcript, flag absent) takes the late-reconcile path and
+// its already-baked BP1 is never rebuilt or re-announced.
+function firstTurnGate(session, liveMcp) {
+    if (session.deferredInitialRefreshPending) {
+        session.deferredInitialRefreshPending = false;
+        return refreshInitialDeferredMcpSurface(session, liveMcp) ? 'refreshed' : 'refresh-noop';
+    }
+    return 'late';
+}
+
+test('MCP connecting between session-create and first send lands in the INITIAL manifest, not a late reminder', () => {
+    const session = createdSession();
+    assert.ok(!systemContent(session).includes('mcp__unity__get_scene'), 'MCP absent from create-time BP1');
+
+    // First-turn refresh: the live registry now includes the connected server.
+    const changed = refreshInitialDeferredMcpSurface(session, [mcpTool]);
+    assert.equal(changed, true, 'first-turn refresh folded the newly-connected MCP tool');
+
+    const sys = systemContent(session);
+    assert.ok(sys.includes('<available-deferred-tools>'), 'manifest block present');
+    assert.ok(sys.includes('mcp__unity__get_scene'), 'MCP tool in the INITIAL manifest');
+    assert.ok(session.deferredAnnouncedTools.includes('mcp__unity__get_scene'), 'MCP tool pre-marked announced');
+
+    let enqueued = null;
+    const result = reconcileDeferredMcpToolCatalog(session, [mcpTool], {
+        enqueue: (text) => { enqueued = text; return true; },
+    });
+    assert.equal(result, null, 'no late-tool announcement for a first-turn-folded tool');
+    assert.equal(enqueued, null, 'nothing enqueued for a first-turn-folded tool');
+});
+
+test('an MCP server connecting AFTER the first turn is still announced via the late reminder', () => {
+    const session = createdSession();
+    // First turn: no MCP connected yet — nothing to fold.
+    assert.equal(refreshInitialDeferredMcpSurface(session, []), false, 'no live MCP => first-turn no-op');
+    assert.ok(!(session.deferredAnnouncedTools || []).includes('mcp__unity__get_scene'), 'MCP not pre-announced');
+
+    // A later turn: the server has since connected → late path fires.
+    let enqueued = null;
+    const result = reconcileDeferredMcpToolCatalog(session, [mcpTool], {
+        enqueue: (text) => { enqueued = text; return true; },
+    });
+    assert.deepEqual(result, ['mcp__unity__get_scene'], 'late tool announced');
+    assert.ok(enqueued && enqueued.includes('mcp__unity__get_scene'), 'late reminder enqueued');
+    assert.ok(enqueued.includes('connected after this session started'), 'reminder carries the late-tool sentinel');
+});
+
+test('recreated session (MCP already connected at create) seeds its manifest, no late re-announce', () => {
+    // Recreate/reset path: createCurrentSession folds the live MCP tools into the
+    // surface at create time, so a cwd-change recreate seeds its BP1 directly and
+    // never needs the first-turn refresh.
+    const session = baseSession();
+    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }, mcpTool], { provider: 'legacy' });
+    assert.ok(systemContent(session).includes('mcp__unity__get_scene'), 'MCP in recreated BP1');
+    assert.ok(session.deferredAnnouncedTools.includes('mcp__unity__get_scene'), 'recreated MCP pre-marked announced');
+
+    let enqueued = null;
+    const result = reconcileDeferredMcpToolCatalog(session, [mcpTool], {
+        enqueue: (text) => { enqueued = text; return true; },
+    });
+    assert.equal(result, null, 'no late announcement on recreate');
+    assert.equal(enqueued, null, 'nothing enqueued on recreate');
+});
+
+test('first-turn refresh is idempotent: a re-render with no new MCP is a no-op and keeps ONE manifest block', () => {
+    const session = createdSession();
+    assert.equal(refreshInitialDeferredMcpSurface(session, [mcpTool]), true, 'first fold applies');
+    const once = systemContent(session);
+    assert.equal(refreshInitialDeferredMcpSurface(session, [mcpTool]), false, 'no genuinely-new MCP => no-op');
+    const twice = systemContent(session);
+    assert.equal(once, twice, 'BP1 byte-identical on re-render');
+    assert.equal((twice.match(/<available-deferred-tools>/g) || []).length, 1, 'exactly one manifest block (no duplicate)');
+});
+
+test('a second newly-connected MCP tool re-renders BP1 in place (both listed, still one block)', () => {
+    const session = createdSession();
+    refreshInitialDeferredMcpSurface(session, [mcpTool]);
+    assert.equal(refreshInitialDeferredMcpSurface(session, [mcpTool, mcpTool2]), true, 're-fold applies the new tool');
+    const sys = systemContent(session);
+    assert.ok(sys.includes('mcp__unity__get_scene') && sys.includes('mcp__unity__run_tests'), 'both MCP tools listed');
+    assert.equal((sys.match(/<available-deferred-tools>/g) || []).length, 1, 'still exactly one block (rebuilt in place)');
+    assert.ok(session.deferredAnnouncedTools.includes('mcp__unity__run_tests'), 'the new tool is pre-announced too');
+});
+
+test('a resumed session (no fresh flag, prior baked BP1) is NOT refreshed on its next turn', () => {
+    // A prior run baked BP1 with the MCP tool; resume reloads that transcript.
+    const session = baseSession();
+    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }, mcpTool], { provider: 'legacy' });
+    const before = systemContent(session);
+    const announcedBefore = [...session.deferredAnnouncedTools];
+    // Resume path never sets the per-session fresh flag.
+    assert.equal(session.deferredInitialRefreshPending, undefined, 'resumed session carries no fresh flag');
+    const route = firstTurnGate(session, [mcpTool, mcpTool2]);
+    assert.equal(route, 'late', 'resumed session takes the late-reconcile path, not the initial refresh');
+    assert.equal(systemContent(session), before, 'BP1 untouched on resume (no rebuild)');
+    assert.deepEqual([...session.deferredAnnouncedTools], announcedBefore, 'announced set unchanged on resume');
+});
+
+test('a fresh session (flagged) is refreshed exactly once, then falls to the late path', () => {
+    const session = createdSession();
+    session.deferredInitialRefreshPending = true;
+    assert.equal(firstTurnGate(session, [mcpTool]), 'refreshed', 'fresh session refreshes on its first turn');
+    assert.equal(session.deferredInitialRefreshPending, false, 'fresh flag consumed (one-shot)');
+    assert.ok(session.deferredAnnouncedTools.includes('mcp__unity__get_scene'), 'first-turn MCP pre-announced');
+    assert.equal(firstTurnGate(session, [mcpTool2]), 'late', 'second turn no longer refreshes');
+});

package/scripts/tool-smoke.mjs

@@ -1050,32 +1050,28 @@ const prevChannelSingleton = process.env.MIXDOG_CHANNEL_SINGLETON;
 const prevChannelWorkerProcess = process.env.MIXDOG_CHANNEL_WORKER_PROCESS;
 const prevRuntimeRoot = process.env.MIXDOG_RUNTIME_ROOT;
 const prevEnvOut = process.env.SMOKE_CHANNEL_ENV_OUT;
+const prevDaemonEntry = process.env.MIXDOG_CHANNEL_DAEMON_ENTRY;
 try {
-  const entry = join(channelWorkerTmp, 'entry.mjs');
+  // Daemon-mode worker env coverage: start() spawn-or-attaches the machine
+  // -global daemon (the stub daemon entry — no Discord token) instead of
+  // forking `entry`, so assert the flags on the SPAWNED DAEMON's env (the stub
+  // dumps them to SMOKE_CHANNEL_ENV_OUT). The old fork-path env assertion died
+  // with the fork path itself; full flip/attach coverage lives in
+  // scripts/channel-daemon-smoke.mjs.
+  const stubEntry = join(root, 'scripts', 'channel-daemon-stub.mjs');
   const dataDir = join(channelWorkerTmp, 'data');
   const runtimeDir = join(channelWorkerTmp, 'runtime');
   const envOut = join(channelWorkerTmp, 'env.json');
   mkdirSync(dataDir, { recursive: true });
   mkdirSync(runtimeDir, { recursive: true });
-  writeFileSync(entry, `
-import { writeFileSync } from 'node:fs';
-writeFileSync(process.env.SMOKE_CHANNEL_ENV_OUT, JSON.stringify({
-  cliOwned: process.env.MIXDOG_CLI_OWNED,
-  daemon: process.env.MIXDOG_CHANNEL_DAEMON,
-}));
-process.send?.({ type: 'ready' });
-process.on('message', (msg) => {
-  if (msg?.type === 'shutdown') process.exit(0);
-});
-setInterval(() => {}, 10000);
-`);
   process.env.MIXDOG_CHANNEL_DAEMON = '1';
   process.env.MIXDOG_CHANNEL_SINGLETON = '1';
   process.env.MIXDOG_CHANNEL_WORKER_PROCESS = '1';
   process.env.MIXDOG_RUNTIME_ROOT = runtimeDir;
   process.env.SMOKE_CHANNEL_ENV_OUT = envOut;
+  process.env.MIXDOG_CHANNEL_DAEMON_ENTRY = stubEntry;
   channelEnvWorker = createStandaloneChannelWorker({
-    entry,
+    entry: stubEntry,
     rootDir: root,
     dataDir,
     cwd: root,
@@ -1100,6 +1096,11 @@ setInterval(() => {}, 10000);
   else process.env.MIXDOG_RUNTIME_ROOT = prevRuntimeRoot;
   if (prevEnvOut == null) delete process.env.SMOKE_CHANNEL_ENV_OUT;
   else process.env.SMOKE_CHANNEL_ENV_OUT = prevEnvOut;
+  if (prevDaemonEntry == null) delete process.env.MIXDOG_CHANNEL_DAEMON_ENTRY;
+  else process.env.MIXDOG_CHANNEL_DAEMON_ENTRY = prevDaemonEntry;
+  // Detach only ends OUR attachment; the stub daemon self-shuts after its
+  // client-grace window. Give it that window before deleting its tmp root.
+  await new Promise((resolveWait) => setTimeout(resolveWait, 700));
   rmSync(channelWorkerTmp, { recursive: true, force: true });
 }
 
@@ -1191,10 +1192,10 @@ if (EXPLORE_TOOL.annotations?.agentHidden === true) {
   }
 }
 const exploreProps = EXPLORE_TOOL.inputSchema?.properties || {};
-if (!/Repo anchor locator/i.test(EXPLORE_TOOL.description || '') || !/broad\/uncertain/i.test(EXPLORE_TOOL.description || '') || !/independent targets/i.test(EXPLORE_TOOL.description || '') || (EXPLORE_TOOL.description || '').length > 90) {
-  throw new Error('explore description must stay compact and anchor-oriented');
+if (!/broad\/uncertain/i.test(EXPLORE_TOOL.description || '') || !/machine-wide/i.test(EXPLORE_TOOL.description || '') || !/independent targets/i.test(EXPLORE_TOOL.description || '') || (EXPLORE_TOOL.description || '').length > 600) {
+  throw new Error('explore description must keep the locator + facet fan-out contract');
 }
-if (!/Narrow locator query/i.test(exploreProps.query?.description || '') || !/independent targets/i.test(exploreProps.query?.description || '') || !/Project\/root/i.test(exploreProps.cwd?.description || '')) {
+if (!/Narrow locator query/i.test(exploreProps.query?.description || '') || !/independent facets/i.test(exploreProps.query?.description || '') || !/Project\/root/i.test(exploreProps.cwd?.description || '')) {
   throw new Error('explore schema must stay compact and preserve query/cwd shape');
 }
 const normalizedExplore = normalizeExploreQueries('["where is model selection?","  ","which file owns agent async?"]');
@@ -1412,7 +1413,11 @@ setInternalToolsProvider({
     const writeTools = (writeAgentSession.tools || []).map((tool) => tool?.name).filter(Boolean);
     const fullTools = (fullAgentSession.tools || []).map((tool) => tool?.name).filter(Boolean);
     const publicExploreTools = (publicExploreSession.tools || []).map((tool) => tool?.name).filter(Boolean);
-    const expectedReadTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'explore', 'search', 'web_fetch', 'Skill'];
+    // Read-role AGENT sessions carry shell/task so review/debug agents can run
+    // their own verification (build/test); the plain readonly preset (public
+    // explore role) still omits them.
+    const expectedReadTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'shell', 'task', 'explore', 'search', 'web_fetch', 'Skill'];
+    const expectedPublicReadTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'explore', 'search', 'web_fetch', 'Skill'];
     const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'shell', 'task', 'explore', 'search', 'web_fetch', 'Skill'];
     if (JSON.stringify(readTools) !== JSON.stringify(expectedReadTools)) {
       throw new Error(`read agent schema must be fixed allow-list: expected=${expectedReadTools.join(', ')} actual=${readTools.join(', ')}`);
@@ -1423,12 +1428,15 @@ setInternalToolsProvider({
     if (readTools.includes('load_tool') || writeTools.includes('load_tool')) {
       throw new Error(`agent session fixed schemas must omit load_tool: read=${readTools.join(', ')} write=${writeTools.join(', ')}`);
     }
-    if (readTools.includes('shell')) {
-      throw new Error(`read agent schema must omit shell: read=${readTools.join(', ')}`);
+    if (readTools.includes('apply_patch')) {
+      throw new Error(`read agent schema must omit apply_patch: read=${readTools.join(', ')}`);
     }
-    for (const name of ['shell', 'apply_patch', 'task']) {
-      if (readTools.includes(name)) {
-        throw new Error(`read agent schema must omit non-read tool ${name}: read=${readTools.join(', ')}`);
+    for (const name of ['shell', 'task']) {
+      if (!readTools.includes(name)) {
+        throw new Error(`read agent schema must carry verification tool ${name}: read=${readTools.join(', ')}`);
+      }
+      if (publicExploreTools.includes(name)) {
+        throw new Error(`public explore role must omit ${name}: explore=${publicExploreTools.join(', ')}`);
       }
     }
     for (const name of ['apply_patch', 'shell', 'task']) {
@@ -1450,13 +1458,13 @@ setInternalToolsProvider({
     if (!fullTools.includes('explore')) {
       throw new Error(`full agent schema must expose explore: full=${fullTools.join(', ')}`);
     }
-    // Unified-shard policy (v0.9.13): the explore wrapper stays IN the schema
-    // for every read role — including the explore agent itself — so the
-    // read-only bundle is bit-identical across roles (one cache group).
-    // Recursion is broken at call time in pre-dispatch-deny.mjs via
-    // recursiveWrapperToolNameForPublicAgent, not by schema stripping.
-    if (JSON.stringify(publicExploreTools) !== JSON.stringify(expectedReadTools)) {
-      throw new Error(`public explore role must ship the shared read-only bundle (incl. explore): expected=${expectedReadTools.join(', ')} actual=${publicExploreTools.join(', ')}`);
+    // The explore wrapper stays IN the schema for every read role — including
+    // the explore agent itself. Recursion is broken at call time in
+    // pre-dispatch-deny.mjs via recursiveWrapperToolNameForPublicAgent, not by
+    // schema stripping. (Read AGENT sessions add shell/task on top, so the
+    // public explore bundle is its own cache group now.)
+    if (JSON.stringify(publicExploreTools) !== JSON.stringify(expectedPublicReadTools)) {
+      throw new Error(`public explore role must ship the readonly bundle (incl. explore): expected=${expectedPublicReadTools.join(', ')} actual=${publicExploreTools.join(', ')}`);
     }
     if (recursiveWrapperToolNameForPublicAgent('explore') !== 'explore') {
       throw new Error('call-time anti-recursion must map public explore agent to its own wrapper tool');

package/src/defaults/cycle3-review-prompt.md

@@ -3,8 +3,10 @@
 You review user-curated CORE memory against the current project memory. Each
 entry is shown with its most-related current memory. Emit ONE verdict line per
 entry id. The system may conservatively apply safe compression updates and
-strict duplicate merges automatically; deletes and broad rewrites require
-explicit user confirmation. Extracting a lesson from a narrative is a BROAD
+strict duplicate merges automatically, and now also auto-applies deletes you
+tag as clear junk (see the delete reasons below), capped per run for safety;
+non-junk or unreasoned deletes and broad rewrites still require explicit user
+confirmation. Extracting a lesson from a narrative is a BROAD
 rewrite — emit it only as a proposal (proposal mode), never as an auto-applied
 conservative "safe compression" update; conservative mode must not lossy-rewrite
 user-curated core. The first character of your response is a digit.
@@ -64,7 +66,12 @@ or inconclusive, keep the CORE entry.
   so a CORE copy is redundant); OR is sourced from code, rules files, or skill
   docs, or is an implementation spec, constant, measurement, resolved-bug
   story, or status snapshot that fits no L1/L2/L3 layer. Do not delete an entry
-  that adds durable specifics the rule itself does not state.
+  that adds durable specifics the rule itself does not state. ALWAYS append a
+  reason tag: `<id>|delete|<reason>` where `<reason>` is one of `duplicate`,
+  `default` (restates a built-in/default rule), `restatement`, `obsolete`,
+  `implemented`, `resolved`, `stale`, `past_event`, or `log`. A bare
+  `<id>|delete` with no reason, or any reason outside that set, is treated as
+  "needs confirmation" and only removed on an explicit APPLY CYCLE3 run.
 
 A verbose durable entry is always `update`, never `keep`.
 Delete is the rarest verdict. Prefer `keep` for durable rules/preferences and
@@ -97,7 +104,7 @@ One line per entry id, any order:
 <id>|update|<element>|<summary>
 <id>|merge|<target_id>|<source_ids_csv>
 <id>|superseded|<newer_id>
-<id>|delete
+<id>|delete|<reason>
 ```
 
 `summary` ≤120 chars, one clause. No literal `|` or newline inside a field

package/src/defaults/memory-promote-prompt.md

@@ -112,6 +112,15 @@ A/B pending rows that encode lasting behavior or map anchors; transient
 When `Active > cap`, contract strictly: any active entry without a concrete
 A/B reason must archive.
 
+**Structural block (enforced, not advisory).** Pending `task`/`issue` rows and
+any row that reads as status/review churn or a benchmark/measurement result
+snapshot are blocked from promotion by the pipeline itself — an `active` verdict
+on them is dropped and the row is **held pending and re-judged on a later
+cycle** (it is neither promoted nor force-archived here). Do NOT archive such a
+row just because it cannot promote now: leave it to be re-confirmed, or promote
+the durable L2 lesson distilled from it under a durable category. Durable
+rules/preferences/constraints promote normally.
+
 If useful content is buried inside work narrative, keep only the durable L2
 behavior lesson (via `update` on an active row, or `active` for a pending row);
 archive the surrounding story.

package/src/rules/agent/30-explorer.md

@@ -22,6 +22,12 @@ synonyms, library/domain names), plus `find` with name fragments, plus `code_gra
 symbol_search when the query names an identifier. A single-pattern,
 single-tool first turn is a defect.
 
+A turn-1 broad grep MUST set `output_mode:"files_with_matches"` — an
+unscoped `content`/`content_with_context` scan reads every match body and is
+a defect (a full-content scan across the tree costs seconds). Use
+`content_with_context` ONLY against a `path` that appeared in an earlier
+result THIS session, and always with `head_limit`.
+
 Search tokens are CODE tokens: first translate natural-language or
 non-English queries into probable English identifiers (e.g. "최대 루프 반복
 횟수" → maxLoop, loop-policy, iterations). Grep non-ASCII text only when

package/src/rules/shared/01-tool.md

@@ -4,12 +4,19 @@
   prior result. Merge equivalent variants/scopes into ONE call wherever the
   schema accepts arrays (`pattern[]`, `path[]`, `symbols[]`, `query[]`).
 - Route by what is already known: known symbol/relation → `code_graph`;
-  exact text in a known scope → `grep`; unknown location or concept-level
-  question → `explore`; name fragment → `find`; exact name pattern → `glob`;
-  known directory → `list`; known file/region → `read`.
+  exact text in a known scope → `grep`; unknown location, machine-wide/
+  out-of-repo whereabouts, or concept-level question → `explore` (which uses
+  the hardened `find` internally); name fragment → `find`; exact name pattern
+  → `glob`; known directory → `list`; known file/region → `read`.
+- `explore` fan-out: at task start, decompose what the task needs to know
+  into independent facets (implementation site, config/load path, tests,
+  error origin, ...) and send them as ONE `query[]` call — facets run in
+  parallel. Never fan out rephrasings of the same target; on
+  EXPLORATION_FAILED, retry once with changed tokens.
 - Valid anchors come from user input or tool output in this session; locate
   anything else with `find` before `grep`/`read`. On ENOENT the next call is
-  `find` on the basename — never a retried guess.
+  `find` on the basename — never a retried guess; and never guess an absolute
+  path outside the project — `find` from a verified broad root instead.
 - Retrieval stops when evidence covers the deliverable: single-answer tasks
   end at the first sufficient anchor; enumeration tasks (review, audit) end
   when the stated scope is covered. Never re-verify a hit already on screen;

package/src/runtime/agent/orchestrator/agent-runtime/agent-progress-watchdog.mjs

@@ -33,6 +33,62 @@ export function isAgentProgressWatchdogAbortError(err) {
     return typeof msg === 'string' && WATCHDOG_ABORT_RE.test(msg);
 }
 
+// Tools that enforce their own execution deadline: 'shell' kills the process
+// at its configured timeout; 'task' wait is bounded by its own wait budget.
+// These are NOT blanket-exempted from the tool-running watchdog — if their own
+// deadline timer dies the session would otherwise hang forever. Instead the
+// watchdog raises the tool-running ceiling to their self-deadline + a grace
+// window (below), so normal long runs are allowed but a dead timer is still
+// caught. Unknown/missing self-deadline falls back to the plain toolRunningMs.
+const SELF_DEADLINE_TOOLS = new Set(['shell', 'task']);
+// Grace added on top of a tool's own deadline before the watchdog steps in, so
+// the tool's in-process kill always fires first under normal operation.
+const TOOL_SELF_DEADLINE_GRACE_MS = 60_000;
+// Fallback deadlines matching the tool implementations (bash-tool.mjs default
+// 120s foreground timeout; task/shell-job wait default 30s budget).
+const SHELL_DEFAULT_TIMEOUT_MS = 120_000;
+const TASK_DEFAULT_WAIT_MS = 30_000;
+
+function bareToolName(toolName) {
+    if (typeof toolName !== 'string' || !toolName) return '';
+    // Strip any MCP/server prefix (e.g. 'server__shell' or 'server.shell').
+    return toolName.split(/[.]|__/).pop();
+}
+
+function isSelfDeadlineTool(toolName) {
+    const bare = bareToolName(toolName);
+    return SELF_DEADLINE_TOOLS.has(bare) || SELF_DEADLINE_TOOLS.has(toolName);
+}
+
+/**
+ * Resolve the self-enforced deadline (ms) for a tool call from its arguments,
+ * recorded into the progress snapshot at dispatch time. Returns a positive
+ * number when the tool enforces its own deadline, or null when unknown/missing
+ * (caller then falls back to the plain toolRunningMs ceiling).
+ *   - shell: explicit `timeout` (ms) if positive, else the 120s default.
+ *   - task:  explicit `timeout_ms` if positive, else 30s for the `wait` action
+ *            (other actions carry no wait budget -> null).
+ */
+export function resolveToolSelfDeadlineMs(toolName, args) {
+    if (!isSelfDeadlineTool(toolName)) return null;
+    const bare = bareToolName(toolName);
+    const a = (args && typeof args === 'object') ? args : {};
+    if (bare === 'shell') {
+        const t = Number(a.timeout);
+        if (Number.isFinite(t) && t > 0) return t;
+        const envDefault = parseInt(process.env.BASH_DEFAULT_TIMEOUT_MS ?? '', 10);
+        return envDefault > 0 ? envDefault : SHELL_DEFAULT_TIMEOUT_MS;
+    }
+    if (bare === 'task') {
+        const t = Number(a.timeout_ms);
+        if (Number.isFinite(t) && t > 0) return t;
+        const action = typeof a.action === 'string' ? a.action : '';
+        if (action === 'wait') return TASK_DEFAULT_WAIT_MS;
+        return null;
+    }
+    return null;
+}
+
 function assistantMessageText(content) {
     if (typeof content === 'string') return content;
     if (!Array.isArray(content)) return '';
@@ -209,7 +265,26 @@ export function evaluateAgentWatchdogAbort(snapshot, now, policy) {
         && policy.toolRunningMs > 0
         && now - snapshot.toolStartedAt > policy.toolRunningMs
     ) {
-        return new AgentStallAbortError(`agent tool running stale (${policy.toolRunningMs}ms)`);
+        // Deadline-aware ceiling for tools that self-enforce their own deadline
+        // ('shell'/'task'). Rather than a blanket exemption (which would hang
+        // forever if the tool's own timer died), raise the tool-running ceiling
+        // to max(toolRunningMs, selfDeadlineMs + grace): normal long runs are
+        // allowed because the tool kills itself first, but a dead deadline timer
+        // is still caught after the grace window. Unknown/missing self-deadline
+        // (selfDeadlineMs <= 0) keeps the plain toolRunningMs behavior. All
+        // other tools are unaffected.
+        let ceilingMs = policy.toolRunningMs;
+        const selfDeadlineMs = Number(snapshot.toolSelfDeadlineMs);
+        if (
+            isSelfDeadlineTool(snapshot.currentTool)
+            && Number.isFinite(selfDeadlineMs)
+            && selfDeadlineMs > 0
+        ) {
+            ceilingMs = Math.max(policy.toolRunningMs, selfDeadlineMs + TOOL_SELF_DEADLINE_GRACE_MS);
+        }
+        if (now - snapshot.toolStartedAt > ceilingMs) {
+            return new AgentStallAbortError(`agent tool running stale (${ceilingMs}ms)`);
+        }
     }
 
     return null;

package/src/runtime/agent/orchestrator/config.mjs

@@ -1,5 +1,5 @@
 import { resolvePluginData } from '../../shared/plugin-paths.mjs';
-import { readSection, updateSection, getAgentApiKey, AGENT_PROVIDER_ENV } from '../../shared/config.mjs';
+import { readSection, updateSection, updateSectionAsync, getAgentApiKey, AGENT_PROVIDER_ENV } from '../../shared/config.mjs';
 import { OPENAI_COMPAT_PRESETS } from './providers/openai-compat-presets.mjs';
 import {
     hasAnthropicOAuthCredentials,
@@ -241,6 +241,14 @@ function persistAgentConfig(build) {
     updateSection('agent', (current) => build(hasKeys(current) ? current : {}));
 }
 
+// Async twin of persistAgentConfig: same in-lock rebase-on-current semantics,
+// but the whole-section RMW runs through updateSectionAsync so a debounced
+// timer flush never blocks the event loop on icacls/backup. Reuses the same
+// config lock file, so it stays linearizable with the sync writers.
+async function persistAgentConfigAsync(build) {
+    await updateSectionAsync('agent', (current) => build(hasKeys(current) ? current : {}));
+}
+
 // Recap toggle (recap.enabled, default true) gates ONLY the background memory
 // cycles. The memory module itself is always-on. On load we fold a legacy
 // `modules.memory === false` flag into recap.enabled=false one time; the caller
@@ -506,23 +514,34 @@ export function loadConfig(options = {}) {
  * concurrent instance's edits are not reverted.
  */
 /** In-lock patch of `skills.disabled` only (avoids whole-config lost-update). */
-export function patchSkillsDisabled(disabledNames) {
+function buildSkillsDisabledPatch(disabledNames) {
     const names = disabledNames instanceof Set
         ? [...disabledNames]
         : (Array.isArray(disabledNames) ? disabledNames : []);
     const nextSkills = normalizeSkillsConfig({ disabled: names });
-    persistAgentConfig((current) => {
+    const build = (current) => {
         const cur = { ...current };
         const target = (cur.agent && cur.agent.providers)
             ? (cur.agent = { ...cur.agent })
             : cur;
         target.skills = nextSkills;
         return cur;
-    });
+    };
+    return { build, nextSkills };
+}
+export function patchSkillsDisabled(disabledNames) {
+    const { build, nextSkills } = buildSkillsDisabledPatch(disabledNames);
+    persistAgentConfig(build);
+    return nextSkills;
+}
+// Async twin used by the debounced skills flush timer.
+export async function patchSkillsDisabledAsync(disabledNames) {
+    const { build, nextSkills } = buildSkillsDisabledPatch(disabledNames);
+    await persistAgentConfigAsync(build);
     return nextSkills;
 }
 
-export function saveConfig(config) {
+function buildAgentSaveBuilder(config) {
     // Strip ephemeral defaults from providers but preserve any unknown
     // per-provider subkey so future schema additions round-trip through the
     // setup UI without changes here. apiKey is intentionally omitted —
@@ -556,7 +575,7 @@ export function saveConfig(config) {
     // Build the replacement from `existingRaw` — the section read INSIDE the
     // file lock — not a snapshot taken before it, so unmanaged keys written by
     // a concurrent instance survive the save (lost-update guard).
-    persistAgentConfig((existingRaw) => ({
+    return (existingRaw) => ({
         ...existingRaw,
         guide: config.guide || existingRaw.guide || undefined,
         providers: persistedProviders,
@@ -582,7 +601,14 @@ export function saveConfig(config) {
         update: config.update || {},
         recap: config.recap || {},
         modules: config.modules || existingRaw.modules || {},
-    }));
+    });
+}
+export function saveConfig(config) {
+    persistAgentConfig(buildAgentSaveBuilder(config));
+}
+// Async twin used by the debounced config-save flush timer.
+export async function saveConfigAsync(config) {
+    await persistAgentConfigAsync(buildAgentSaveBuilder(config));
 }
 // --- Preset helpers ---
 // preset shape: { id, name, type: 'agent', provider, model, effort?, fast?, tools? }

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -407,9 +407,38 @@ export function stripDeferredToolManifestBlock(text) {
         .trimEnd();
 }
 
-/** Inject the skill-style deferred pool (name + description) into BP1 once at session start; never rewrite BP1 after. */
-export function applyInitialDeferredToolManifestToBp1(session, poolNames) {
-    if (!session || !Array.isArray(session.messages) || session.deferredToolBp1Applied) return false;
+// Rebuild path: replace the FIRST previously-injected <available-deferred-tools>
+// block (with its leading `---` separator) with the fresh manifest IN PLACE, so
+// the block keeps its original position and no sibling BP1 block (skills
+// manifest, agent rules, …) is reordered or dropped. The fresh manifest already
+// carries the mcp-instructions companion, so any pre-existing standalone one is
+// removed first to avoid duplication.
+export function rebuildDeferredToolManifestBlock(text, manifest) {
+    let out = String(text || '').replace(MCP_INSTRUCTIONS_BLOCK_RE, '');
+    let replaced = false;
+    out = out.replace(DEFERRED_TOOLS_BLOCK_RE, (match, sep) => {
+        if (replaced) return '';
+        replaced = true;
+        return `${sep || ''}${manifest}`;
+    });
+    if (!replaced) {
+        const base = out.trimEnd();
+        out = base ? `${base}\n\n---\n\n${manifest}` : manifest;
+    }
+    return out;
+}
+
+/**
+ * Inject the skill-style deferred pool (name + description) into BP1 at session
+ * start. Normally once; with `{ rebuild: true }` it strips any existing
+ * <available-deferred-tools>/<mcp-instructions> block and re-injects the fresh
+ * pool in place (used by the first-turn MCP refresh, before the prompt renders,
+ * so late-connected MCP tools land in the INITIAL manifest — never duplicated).
+ */
+export function applyInitialDeferredToolManifestToBp1(session, poolNames, options = {}) {
+    const rebuild = options?.rebuild === true;
+    if (!session || !Array.isArray(session.messages)) return false;
+    if (session.deferredToolBp1Applied && !rebuild) return false;
     const pool = Array.isArray(poolNames) ? poolNames : [];
     const descByName = new Map();
     for (const tool of Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : []) {
@@ -432,15 +461,21 @@ export function applyInitialDeferredToolManifestToBp1(session, poolNames) {
     }
     if (idx === -1) return false;
     const raw = typeof session.messages[idx].content === 'string' ? session.messages[idx].content : '';
-    if (bp1HasDeferredToolManifestBlock(raw)) {
+    if (bp1HasDeferredToolManifestBlock(raw) && !rebuild) {
         session.deferredToolBp1Applied = true;
         return true;
     }
     if (manifest) {
-        const base = stripDeferredToolManifestBlock(raw);
-        session.messages[idx].content = base
-            ? `${base}\n\n---\n\n${manifest}`
-            : manifest;
+        if (rebuild && bp1HasDeferredToolManifestBlock(raw)) {
+            // Anchored in-place rebuild: swap the previously injected manifest
+            // block for the fresh one at its EXISTING position.
+            session.messages[idx].content = rebuildDeferredToolManifestBlock(raw, manifest);
+        } else {
+            const base = stripDeferredToolManifestBlock(raw);
+            session.messages[idx].content = base
+                ? `${base}\n\n---\n\n${manifest}`
+                : manifest;
+        }
     }
     session.deferredToolBp1Applied = true;
     session.updatedAt = Date.now();