@nathapp/nax-agent 0.88.0-canary.1 → 0.88.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
 release may change the public API.
 
+## [0.88.0] - 2026-10-16
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [0.88.0-canary.2] - 2026-10-15
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
 ## [0.88.0-canary.1] - 2026-10-13
 
 - Bash guard for nax run state (#2490): `git update-index --skip-worktree` / `--assume-unchanged` (and the `--no-` forms) on a `.nax` path, `git stash` / `push` / `pop` / `apply` in a repo that holds a `.nax/` directory (unless the pathspec excludes `.nax`), and `git checkout` / `restore` of a `.nax` path are now refused in every segment of a compound command, in gated and raw mode, also behind `git -C`/`-c`, env assignments, `env`/`command`/`nice`/`timeout`/`xargs` wrappers and `bash -c`/`eval`, plus a coarse text backstop for wrappers it cannot enumerate. `RULE_SET_VERSION` is now 4 (git global options, `-c alias.*` and more wrappers are resolved when locating the subcommand).

package/dist/coding-tools/coding-tool-support.d.ts

@@ -32,6 +32,16 @@ export interface CodingToolSupport {
         readonly tools: readonly CodingTool[];
         readonly surface: ToolSurfaceDraft;
     };
+    /** nax#2500: the dispatch launcher's sandbox as data, attached by the nax resolver for ACP opens. */
+    readonly acpSandbox?: import("#src/sandbox/types").SessionSandbox;
+    /**
+     * The rendered `## MCP servers` section (nax#2517), built by the nax resolver
+     * with `renderProviderInstructions` from this hop's resolved provider
+     * instructions. The session open folds it into the session's `system` field
+     * (native) or hands it to the ACP tool host. ABSENT when no attached provider
+     * contributed instructions, so "no section" and "an empty one" stay distinct.
+     */
+    readonly providerInstructions?: string;
 }
 export declare function buildCodingToolSupport(args: {
     root?: string;
@@ -134,6 +144,12 @@ export declare function buildCodingToolSupport(args: {
     launcher?: CommandLauncher;
     /** US-001: forwarded into ToolRunContext so Bash/Exec can SIGKILL on cancel. */
     abortSignal?: AbortSignal;
+    /**
+     * The rendered `## MCP servers` section for this hop (nax#2517), produced by
+     * the resolver from `ResolvedProviderTools.instructions`; returned on the
+     * support unchanged.
+     */
+    providerInstructions?: string;
 }): CodingToolSupport | undefined;
 /**
  * Ledger session name.

package/dist/coding-tools/coding-tool-support.js

@@ -144,8 +144,20 @@ export function buildCodingToolSupport(args) {
         auditSink: sink,
         declaredTools: args.declared,
         ...(args.toolSurface !== undefined ? { toolSurface: args.toolSurface } : {}),
+        ...providerInstructionsField(args),
     };
 }
+/**
+ * The support's optional `providerInstructions` (#2517) as a spreadable field —
+ * ABSENT when unset, so `"providerInstructions" in support` answers "is there
+ * an MCP section?". A helper rather than an inline conditional because
+ * `buildCodingToolSupport` sits at its complexity baseline.
+ */
+function providerInstructionsField(args) {
+    if (args.providerInstructions === undefined)
+        return {};
+    return { providerInstructions: args.providerInstructions };
+}
 /** The audit sink a support resolution records through; no dir ⇒ a non-recording sink. */
 function supportSink(args) {
     if (args.auditDir === undefined)

package/dist/config/schemas-sandbox.d.ts

@@ -24,6 +24,7 @@ export declare const SandboxConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     network: z.ZodPrefault<z.ZodObject<{
         allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;

package/dist/config/schemas-sandbox.js

@@ -38,6 +38,15 @@ export const SandboxConfigSchema = z.object({
         .object({
         /** absent = unrestricted (spec S2); [] = no network; a list = allow-list. */
         allowedDomains: z.array(z.string()).optional(),
+        /**
+         * US-002 (#2538): let a sandboxed command reach loopback ports.
+         *
+         * Off when absent, and it only changes anything alongside an
+         * `allowedDomains` list: with an open network srt's macOS profile already
+         * allows all traffic. srt reads it once per process, from the config given
+         * to `SandboxManager.initialize`.
+         */
+        allowLocalBinding: z.boolean().optional(),
     })
         .prefault({}),
 });

package/dist/index.d.ts

@@ -26,7 +26,7 @@ export type { AfterResponsePatch, AfterResponsePayload, AfterToolPatch, AfterToo
 export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";
 export { type ApprovalAuditRow, type ApprovalEntry, type ApprovalsFile, type ApprovalsFileRead, type ApprovalsFileState, type ApprovalsTaint, ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, type AskControl, type AskDecidedBy, type AskDecision, type AskLink, type AskLinkOutcome, type AskRequest, type AskResolver, type AskVerdict, appendApproval, appendApprovalAudit, approvalId, approvalsPath, type BashLexResult, type BashRedirect, type BashSegment, type BashSegmentSeparator, type BashToken, type ClearTaintOutcome, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, type MaskResult, maskForPrompt, type PrepareApprovalsStoreOptions, parseRuleList, parseToolExpression, prepareApprovalsStore, type RemovalDecision, type RemovalResult, type ResolvedPermissions, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, type SecretSpan, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
 export { type AgentGlobOptions, type AgentRuntime, type AgentSpawnOptions, type AgentSpawnResult, type AgentSpawnStdin, getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
-export { buildSandboxPolicy, type CommandLauncher, type CommandLauncherOptions, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, type GitLayout, type LaunchRequest, type LaunchResult, type LaunchSpec, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, type ProbeResult, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, type SandboxBackend, type SandboxBackendName, type SandboxNetworkPolicy, type SandboxPolicy, type SandboxPolicyInput, type SandboxRecord, type SandboxState, type SandboxWrapRequest, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
+export { buildSandboxPolicy, type CommandLauncher, type CommandLauncherOptions, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, type GitLayout, type LaunchRequest, type LaunchResult, type LaunchSpec, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, type ProbeResult, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, type SandboxBackend, type SandboxBackendName, type SandboxNetworkPolicy, type SandboxPolicy, type SandboxPolicyInput, type SandboxRecord, type SandboxState, type SandboxWrapRequest, type SessionSandbox, sessionSandboxFrom, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
 export type { AdapterFailure } from "#src/session/adapter-failure";
 export { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 export { AgentSessionError, type AgentSessionErrorCode } from "#src/session/agent-session-errors";
@@ -42,5 +42,5 @@ export { attachTurnSpend, type FailedTurnSpend, readTurnSpend } from "#src/sessi
 export type { JSONSchema, ToolDescriptor, } from "#src/session/tool-descriptor";
 export { createTurnDeadline, type TurnDeadline, } from "#src/session/turn-deadline";
 export type { TurnEvent, TurnEventSink } from "#src/session/turn-event";
-export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, type CodingTool, type CodingToolName, type CodingToolOutcome, type CodingToolRuntime, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, type DeclaredCommandRequest, type DeclaredCommandResult, type DeclaredCommandRunner, deleteTool, EXEC_TOOL_NAME, type ExecTarget, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, type ModelTruncationOptions, mcpRuleAdmits, type NormalizeInput, type NormalizeResult, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, type PolicyVerdict, PROVIDER_ID_RE, type ProtectedPathsPolicy, type ProviderGrantEntry, type ProviderKind, type ProviderTool, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, type ReadFileSliceOptions, type ReadFileSliceResult, type RegisteredSink, type ResolvedProviderTools, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, type SpillRequest, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, type ToolAuditHeader, type ToolAuditSink, type ToolCallContext, type ToolCallRecord, type ToolGrant, type ToolPatternNarrowing, type ToolPolicy, type ToolPolicyOptions, type ToolProvider, type ToolResult, type ToolRunContext, type ToolScope, type ToolSurfaceDraft, type ToolSurfaceRecord, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
+export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, type CodingTool, type CodingToolName, type CodingToolOutcome, type CodingToolRuntime, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, type DeclaredCommandRequest, type DeclaredCommandResult, type DeclaredCommandRunner, deleteTool, EXEC_TOOL_NAME, type ExecTarget, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER, MCP_INSTRUCTIONS_MAX_CHARS_TOTAL, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, type ModelTruncationOptions, mcpRuleAdmits, type NormalizeInput, type NormalizeResult, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, type PolicyVerdict, PROVIDER_ID_RE, type ProtectedPathsPolicy, type ProviderGrantEntry, type ProviderKind, type ProviderTool, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, type ReadFileSliceOptions, type ReadFileSliceResult, type RegisteredSink, type ResolvedProviderTools, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, renderProviderInstructions, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, type SpillRequest, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, type ToolAuditHeader, type ToolAuditSink, type ToolCallContext, type ToolCallRecord, type ToolGrant, type ToolPatternNarrowing, type ToolPolicy, type ToolPolicyOptions, type ToolProvider, type ToolResult, type ToolRunContext, type ToolScope, type ToolSurfaceDraft, type ToolSurfaceRecord, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
 export { EMPTY_OWNED_PATHS_POLICY, type OwnedBashCandidate, type OwnedPathsPolicy, } from "#src/tools/owned-paths";

package/dist/index.js

@@ -21,7 +21,7 @@ export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOut
 export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";
 export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, appendApproval, appendApprovalAudit, approvalId, approvalsPath, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, maskForPrompt, parseRuleList, parseToolExpression, prepareApprovalsStore, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
 export { getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
-export { buildSandboxPolicy, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
+export { buildSandboxPolicy, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, sessionSandboxFrom, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
 export { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 export { AgentSessionError } from "#src/session/agent-session-errors";
 export { NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
@@ -29,5 +29,5 @@ export { nativeBackend } from "#src/session/native-backend";
 export { SessionTurnError, } from "#src/session/session-types";
 export { attachTurnSpend, readTurnSpend } from "#src/session/turn-spend";
 export { createTurnDeadline, } from "#src/session/turn-deadline";
-export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, deleteTool, EXEC_TOOL_NAME, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, mcpRuleAdmits, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, PROVIDER_ID_RE, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
+export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, deleteTool, EXEC_TOOL_NAME, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER, MCP_INSTRUCTIONS_MAX_CHARS_TOTAL, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, mcpRuleAdmits, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, PROVIDER_ID_RE, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, renderProviderInstructions, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
 export { EMPTY_OWNED_PATHS_POLICY, } from "#src/tools/owned-paths";

package/dist/internal/process-kill.d.ts

@@ -12,7 +12,9 @@
  * 2. Falls back to killing the single process if group kill fails
  *
  * @param pid - Process ID (positive, not negative)
- * @param signal - Signal to send (SIGTERM, SIGKILL, etc.)
+ * @param signal - Signal to send (SIGTERM, SIGKILL, etc.); `0` probes whether the group still has a member
+ * @param opts - `singleProcessFallback: false` skips step 2. Pass it once the group leader is known to have
+ *   exited: the bare pid may have been reused by an unrelated process by then.
  * @returns true if kill was sent successfully, false if process already exited
  *
  * @example
@@ -24,4 +26,6 @@
  * }
  * ```
  */
-export declare function killProcessGroup(pid: number, signal: NodeJS.Signals | number): boolean;
+export declare function killProcessGroup(pid: number, signal: NodeJS.Signals | number, opts?: {
+    readonly singleProcessFallback?: boolean;
+}): boolean;

package/dist/internal/process-kill.js

@@ -12,7 +12,9 @@
  * 2. Falls back to killing the single process if group kill fails
  *
  * @param pid - Process ID (positive, not negative)
- * @param signal - Signal to send (SIGTERM, SIGKILL, etc.)
+ * @param signal - Signal to send (SIGTERM, SIGKILL, etc.); `0` probes whether the group still has a member
+ * @param opts - `singleProcessFallback: false` skips step 2. Pass it once the group leader is known to have
+ *   exited: the bare pid may have been reused by an unrelated process by then.
  * @returns true if kill was sent successfully, false if process already exited
  *
  * @example
@@ -24,7 +26,7 @@
  * }
  * ```
  */
-export function killProcessGroup(pid, signal) {
+export function killProcessGroup(pid, signal, opts = {}) {
     // A pid that is not a real child reaches other processes: 0 is our own group,
     // 1 (as -1) is every process we may signal, and a negative pid is init or a
     // foreign group. A spawn that failed has no pid, so refuse rather than signal.
@@ -39,6 +41,8 @@ export function killProcessGroup(pid, signal) {
         const err = error;
         // ESRCH = no such process — process group doesn't exist, try single process
         if (err.code === "ESRCH") {
+            if (opts.singleProcessFallback === false)
+                return false;
             try {
                 process.kill(pid, signal);
                 return true;

package/dist/internal.d.ts

@@ -93,6 +93,7 @@ export * from "#src/tools/git-commit";
 export * from "#src/tools/grep";
 export * from "#src/tools/index";
 export { _instructionAccessDeps } from "#src/tools/instruction-access";
+export { _naxStateGuardDeps } from "#src/tools/nax-stash-restore";
 export * from "#src/tools/owned-paths";
 export * from "#src/tools/package-managers";
 export * from "#src/tools/policy";

package/dist/internal.js

@@ -93,6 +93,7 @@ export * from "#src/tools/git-commit";
 export * from "#src/tools/grep";
 export * from "#src/tools/index";
 export { _instructionAccessDeps } from "#src/tools/instruction-access";
+export { _naxStateGuardDeps } from "#src/tools/nax-stash-restore";
 // S3-2: the port (nax supplies the policy behind it from its own module).
 export * from "#src/tools/owned-paths";
 export * from "#src/tools/package-managers";

package/dist/mcp/connect.js

@@ -83,6 +83,15 @@ function createHandle(config) {
         throw new McpConnectError(`MCP connect failed: ${messageOf(error)}`);
     }
 }
+/**
+ * The server's `initialize` instructions (#2517), or `undefined` for anything
+ * that is not a non-empty string: an empty one would render an empty prompt
+ * section, and a `getInstructions()` that returns nothing is the same silence.
+ */
+function serverInstructions(client) {
+    const text = client.getInstructions();
+    return typeof text === "string" && text !== "" ? text : undefined;
+}
 export async function connectMcp(config, opts) {
     const handle = createHandle(config);
     const client = new Client({ name: opts.clientInfo.name, version: opts.clientInfo.version });
@@ -93,9 +102,25 @@ export async function connectMcp(config, opts) {
     try {
         if (signal.aborted)
             throw new McpConnectError("MCP connect failed: aborted");
+        if (config.kind === "stdio" && opts.onSpawn !== undefined) {
+            const start = handle.transport.start;
+            let notified = false;
+            handle.transport.start = async function () {
+                await start.call(this);
+                const pid = handle.pid();
+                if (pid !== null && !notified) {
+                    notified = true;
+                    opts.onSpawn?.(pid);
+                }
+            };
+        }
         await client.connect(handle.transport, { signal, timeout: opts.timeoutMs });
         const tools = await listAll(client, signal, opts.timeoutMs);
-        return liveConnection(config, client, handle, tools, { graceMs, life });
+        return liveConnection(config, client, handle, tools, {
+            graceMs,
+            life,
+            instructions: serverInstructions(client),
+        });
     }
     catch (error) {
         await closeTransport(client, handle, graceMs, life);
@@ -127,6 +152,7 @@ function liveConnection(config, client, handle, tools, state) {
             return handle.pid();
         },
         tools,
+        ...(state.instructions !== undefined ? { instructions: state.instructions } : {}),
         call(name, input, opts) {
             if (closing !== undefined || life.exited)
                 return Promise.reject(new McpCallError(`MCP call ${name} failed: the connection is closed`));

package/dist/mcp/types.d.ts

@@ -31,6 +31,12 @@ export interface McpConnection {
     /** The stdio child process pid; null for HTTP. Read before close() — the SDK may clear it after. */
     readonly pid: number | null;
     readonly tools: readonly McpToolInfo[];
+    /**
+     * The server's own `initialize` instructions — how to use it, in its words
+     * (#2517). Absent when it sent none (or an empty string): an MCP server that
+     * says nothing must not produce an empty prompt section.
+     */
+    readonly instructions?: string;
     /** Server-side tool errors are `isError` results; transport failures throw McpCallError. */
     call(name: string, input: unknown, opts: McpCallOptions): Promise<McpCallResult>;
     /** stdio only: called once when the process exits without close() having been called. */
@@ -45,6 +51,8 @@ export interface ConnectMcpOptions {
         readonly name: string;
         readonly version: string;
     };
+    /** stdio only: called once after spawn, before the initialize request is sent. */
+    readonly onSpawn?: (pid: number) => void;
     /** stdio: how long close() waits for the process before SIGKILL. Default 3000. */
     readonly closeGraceMs?: number;
 }

package/dist/native/auth.d.ts

@@ -29,8 +29,8 @@ export declare const _authDeps: {
     ambientAuthAvailable: typeof ambientAuthAvailable;
     providerIds: () => Promise<string[]>;
     /**
-     * Injectable timer pair — lets tests drive `anyAmbientCredential`'s
-     * expiry branch off a virtual clock instead of waiting the full 2s
+     * Injectable timer pair — lets tests drive ambient credential probes'
+     * expiry branches off a virtual clock instead of waiting the full 2s
      * production timeout. Mirrors `_heartbeatDeps` / `_idleWatchdogDeps`.
      *
      * @internal

package/dist/native/auth.js

@@ -41,8 +41,8 @@ export const _authDeps = {
     ambientAuthAvailable,
     providerIds: async () => (await defaultProviders()).map((provider) => provider.id),
     /**
-     * Injectable timer pair — lets tests drive `anyAmbientCredential`'s
-     * expiry branch off a virtual clock instead of waiting the full 2s
+     * Injectable timer pair — lets tests drive ambient credential probes'
+     * expiry branches off a virtual clock instead of waiting the full 2s
      * production timeout. Mirrors `_heartbeatDeps` / `_idleWatchdogDeps`.
      *
      * @internal
@@ -301,14 +301,14 @@ export async function providersWithoutCredentials(providerIds) {
     })).then((missing) => missing.filter((id) => id !== undefined));
     let timer;
     const expiry = new Promise((resolve) => {
-        timer = setTimeout(() => resolve([]), AMBIENT_PROBE_TIMEOUT_MS);
+        timer = _authDeps.setTimeout(() => resolve([]), AMBIENT_PROBE_TIMEOUT_MS);
     });
     try {
         return await Promise.race([sweep, expiry]);
     }
     finally {
         if (timer !== undefined)
-            clearTimeout(timer);
+            _authDeps.clearTimeout(timer);
     }
 }
 /**

package/dist/native/failed-round-trip-spend.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Prices the tokens a failed or aborted round trip was billed for and attaches
+ * them to the thrown error (`session/partial-spend.ts`), where the turn loop's
+ * `completeWithRecovery` folds them into the turn's accumulated usage.
+ *
+ * nax-ai's `collectStream` hands the partial usage over on the error
+ * (`partialUsageOf`); only the adapter holds the rate card, so pricing happens
+ * here, once, with the same `priceCall` the success path uses.
+ */
+import type { Pricing } from "#src/cost/standard-types";
+/**
+ * Runs one round trip; if it throws, prices whatever it was billed first and
+ * attaches that to the error, which is rethrown untouched. A wrapper (rather
+ * than a catch at the call site) keeps `sendTurn` under the complexity ratchet.
+ */
+export declare function billedOnFailure<T>(rates: Pricing, roundTrip: () => Promise<T>): Promise<T>;

package/dist/native/failed-round-trip-spend.js

@@ -0,0 +1,33 @@
+/**
+ * Prices the tokens a failed or aborted round trip was billed for and attaches
+ * them to the thrown error (`session/partial-spend.ts`), where the turn loop's
+ * `completeWithRecovery` folds them into the turn's accumulated usage.
+ *
+ * nax-ai's `collectStream` hands the partial usage over on the error
+ * (`partialUsageOf`); only the adapter holds the rate card, so pricing happens
+ * here, once, with the same `priceCall` the success path uses.
+ */
+import { partialUsageOf } from "@nathapp/nax-ai";
+import { priceCall } from "#src/cost/core/index";
+import { attachPartialSpend } from "./session/partial-spend.js";
+function recordFailedRoundTripSpend(err, rates) {
+    const usage = partialUsageOf(err);
+    if (usage === undefined)
+        return;
+    const { costUsd, resolvedRates } = priceCall(usage, rates);
+    attachPartialSpend(err, { usage, costUsd, rates: resolvedRates });
+}
+/**
+ * Runs one round trip; if it throws, prices whatever it was billed first and
+ * attaches that to the error, which is rethrown untouched. A wrapper (rather
+ * than a catch at the call site) keeps `sendTurn` under the complexity ratchet.
+ */
+export async function billedOnFailure(rates, roundTrip) {
+    try {
+        return await roundTrip();
+    }
+    catch (err) {
+        recordFailedRoundTripSpend(err, rates);
+        throw err;
+    }
+}

package/dist/native/session/partial-spend.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Spend billed by a round trip that then failed.
+ *
+ * A failed or aborted request still bills the tokens it streamed (nax-ai's
+ * `partialUsageOf`). The adapter's `complete` closure is the only place that
+ * can price them, but it can only throw, so the priced spend rides on the
+ * thrown error's identity (a WeakMap, like `turn-spend.ts`) and the turn loop's
+ * `completeWithRecovery` folds it into the turn accumulator. `take` removes the
+ * entry, so an error reaching the fold twice cannot count twice.
+ */
+import type { PricingRates, TokenUsage } from "#src/cost/standard-types";
+export interface PartialSpend {
+    readonly usage: TokenUsage;
+    readonly costUsd: number;
+    readonly rates?: PricingRates;
+}
+/** Attaches the priced partial spend of a failed round trip to the error it threw. */
+export declare function attachPartialSpend(err: unknown, spend: PartialSpend): void;
+/** Removes and returns the partial spend attached to `err`, if any. */
+export declare function takePartialSpend(err: unknown): PartialSpend | undefined;

package/dist/native/session/partial-spend.js

@@ -0,0 +1,14 @@
+const partialByError = new WeakMap();
+/** Attaches the priced partial spend of a failed round trip to the error it threw. */
+export function attachPartialSpend(err, spend) {
+    if (typeof err === "object" && err !== null)
+        partialByError.set(err, spend);
+}
+/** Removes and returns the partial spend attached to `err`, if any. */
+export function takePartialSpend(err) {
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const spend = partialByError.get(err);
+    partialByError.delete(err);
+    return spend;
+}

package/dist/native/session/session.js

@@ -83,12 +83,19 @@ function openTranscriptStore(name, opts) {
 /**
  * Records, or clears, the session's system prompt at open. A helper so that
  * openNativeSession gains no branch.
+ *
+ * `providerInstructions` (the rendered `## MCP servers` section, #2517) is
+ * folded in HERE rather than kept in a map of its own: the model sees one
+ * `system` string, and every consumer of `state.systemPrompts`
+ * (`systemFieldFor`, the adapter's context-budget setup) keeps working
+ * unchanged.
  */
-function recordSystemPrompt(state, name, systemPrompt) {
-    if (systemPrompt === undefined)
+function recordSystemPrompt(state, name, prompts) {
+    const parts = [prompts.systemPrompt, prompts.providerInstructions].filter((part) => part !== undefined && part !== "");
+    if (parts.length === 0)
         state.systemPrompts.delete(name);
     else
-        state.systemPrompts.set(name, systemPrompt);
+        state.systemPrompts.set(name, parts.join("\n\n"));
 }
 /** The request field for the session's system prompt: `{ system }`, or `{}` when it has none. */
 export function systemFieldFor(state, sessionName) {
@@ -119,7 +126,7 @@ export async function openNativeSession(state, name, opts) {
         state.carryHistoryAcrossModels.add(name);
     else
         state.carryHistoryAcrossModels.delete(name);
-    recordSystemPrompt(state, name, opts.systemPrompt);
+    recordSystemPrompt(state, name, opts);
     const instructions = await openRepositoryInstructions(name, opts, store);
     state.repositoryInstructions.set(name, instructions);
     state.transcripts.set(name, {

package/dist/native/session/turn-complete-step.js

@@ -20,6 +20,8 @@
  */
 import { getSafeLogger } from "#src/infra/index";
 import { applyHistoryPatch } from "./loop-events/cache-boundary.js";
+import { takePartialSpend } from "./partial-spend.js";
+import { usageBeat } from "./turn-accumulator.js";
 import { runOverflowCompaction } from "./turn-compaction-step.js";
 import { realSleep, retryTransportFault } from "./turn-retry.js";
 /**
@@ -89,8 +91,26 @@ export async function completeWithRecovery(args) {
         honoured = wire.honoured;
         return deps.complete(wire.messages, tools, options, turnEvents.deltaSink(roundTrip));
     };
+    // A failed round trip was still billed for what it streamed. Folding it in
+    // here, per attempt, is what makes a retry count both attempts and an
+    // aborted or timed-out one count what it cost; `takePartialSpend` consumes
+    // the entry, and the retry loop rethrows the error it was given without
+    // re-entering this wrapper, so nothing counts twice.
+    const countedRequest = async (msgs) => {
+        try {
+            return await request(msgs);
+        }
+        catch (err) {
+            const spend = takePartialSpend(err);
+            if (spend !== undefined) {
+                usage.add(spend.usage, spend.costUsd, spend.rates);
+                deps.onActivity?.(usageBeat(spend.usage, spend.costUsd));
+            }
+            throw err;
+        }
+    };
     try {
-        res = await request(messages);
+        res = await countedRequest(messages);
     }
     catch (err) {
         // Written as one guarded `if` (not a separate `canRetry` boolean) so
@@ -109,7 +129,7 @@ export async function completeWithRecovery(args) {
             if (deps.transportRetry === undefined)
                 throw err;
             res = await retryTransportFault(err, {
-                attempt: () => request(messages),
+                attempt: () => countedRequest(messages),
                 config: deps.transportRetry,
                 deadline: deps.deadline,
                 signal,
@@ -161,7 +181,7 @@ export async function completeWithRecovery(args) {
             turnEvents.emit({ type: "compaction", reason: "overflow" });
             // Retried once. A second overflow propagates: compacting further would be
             // guessing, and the failure now carries a correct diagnosis.
-            res = await request(messages);
+            res = await countedRequest(messages);
         }
     }
     return { res, messages, compacted, honoured, boundary: compacted };

package/dist/native/session/turn-retry.d.ts

@@ -80,9 +80,9 @@ export declare function turnRetryFitsBudget(delayMs: number, remainingMs: number
  * nax-ai's retry.ts `abortableSleep` so a pending backoff cannot outlive the
  * caller's own cancellation and go on to start a request nobody wants.
  */
-export declare function abortableSleep(ms: number, sleep: (ms: number) => Promise<void>, signal?: AbortSignal): Promise<void>;
+export declare function abortableSleep(ms: number, sleep: (ms: number, signal?: AbortSignal) => Promise<void>, signal?: AbortSignal): Promise<void>;
 /** The real timer. Named and exported so the only production wiring of it is one reference. */
-export declare function realSleep(ms: number): Promise<void>;
+export declare function realSleep(ms: number, signal?: AbortSignal): Promise<void>;
 export interface TurnRetryDeps<T> {
     /** Re-issues the round trip. Called once per retry, never for the triggering attempt. */
     readonly attempt: () => Promise<T>;
@@ -99,7 +99,7 @@ export interface TurnRetryDeps<T> {
      * and leaving it optional let a test omit it and silently wait out a real
      * multi-second backoff. Required makes that a compile error instead.
      */
-    readonly sleep: (ms: number) => Promise<void>;
+    readonly sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
     /** Injectable jitter source, for deterministic tests. Defaults to Math.random. */
     readonly random?: () => number;
     /** Fired once per retry, before the backoff delay, with a 1-based retry number. */

package/dist/native/session/turn-retry.js

@@ -104,7 +104,7 @@ export function turnRetryFitsBudget(delayMs, remainingMs) {
     return remainingMs === undefined || delayMs <= remainingMs;
 }
 function abortError(signal) {
-    return signal.reason ?? new DOMException("Aborted", "AbortError");
+    return signal?.reason ?? new DOMException("Aborted", "AbortError");
 }
 /**
  * A sleep that resolves early, and rejects, when `signal` fires — mirrors
@@ -113,21 +113,40 @@ function abortError(signal) {
  */
 export function abortableSleep(ms, sleep, signal) {
     if (signal === undefined)
-        return sleep(ms);
+        return sleep(ms, signal);
     if (signal.aborted)
         return Promise.reject(abortError(signal));
     return new Promise((resolve, reject) => {
         const onAbort = () => reject(abortError(signal));
         signal.addEventListener("abort", onAbort, { once: true });
-        sleep(ms).then(() => {
+        // Keep the race for injected sleeps that do not honour cancellation.
+        Promise.resolve()
+            .then(() => sleep(ms, signal))
+            .then(() => {
             signal.removeEventListener("abort", onAbort);
             resolve();
-        }, reject);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
     });
 }
 /** The real timer. Named and exported so the only production wiring of it is one reference. */
-export function realSleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export function realSleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(abortError(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        // Cancellable timer: abort must release the pending backoff immediately.
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
 }
 /**
  * Retries `attempt` while the thrown error is a transport/overloaded fault,

package/dist/native/session/turn-types.d.ts

@@ -97,7 +97,7 @@ export interface TurnDeps {
      * actually wait (forbidden-patterns-tests.md). Absent uses a real timer —
      * a real session always wants to actually wait.
      */
-    sleep?: (ms: number) => Promise<void>;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     /**
      * Live repetition-breaker instance (nax#2013, session-lifetime since #2047). Absent disables the breaker.
      */

package/dist/native/session-adapter.js

@@ -15,6 +15,7 @@ import { _adapterDeps, authFields, isProtocolStreamError } from "./adapter-deps.
 import { _clientDeps, getNativeClient } from "./client.js";
 import { createSessionCredentialStore } from "./credentials/session-source.js";
 import { toAdapterFailure } from "./errors.js";
+import { billedOnFailure } from "./failed-round-trip-spend.js";
 import { buildRateCard, NATIVE_AGENT, parseNativeModel, resolveContextWindow, toThinkingLevel } from "./models.js";
 import { createInstructionInteraction } from "./session/instruction-interaction.js";
 import { closeNativeSession, createNativeSessionState, markNativeTurnOutcome, openNativeSession, systemFieldFor, } from "./session/session.js";
@@ -305,7 +306,7 @@ export class NativeSessionAdapter {
                     const requestThinking = requestOptions?.thinking === false ? undefined : thinking;
                     try {
                         instructionInteraction.acknowledge();
-                        const res = await streamComplete(client, resolved, {
+                        const res = await billedOnFailure(rates, () => streamComplete(client, resolved, {
                             messages,
                             ...(tools.length > 0 ? { tools } : {}),
                             sessionId,
@@ -324,7 +325,7 @@ export class NativeSessionAdapter {
                             // to reuse the entry, so a cache write there costs more than it
                             // saves.
                             cacheRetention: "short",
-                        }, onDelta);
+                        }, onDelta));
                         const usage = res.usage;
                         // Single `priceCall` invocation: `costUsd` and `resolvedRates`
                         // come from the same call so they cannot diverge — the