@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/core/runtime-builder.js

@@ -32,9 +32,11 @@
  * load / unload / reconcile API and for `getAllTools` / `getToolDefinition`, and a private
  * `_refreshToolRegistry` delegation for its internal callers.
  */
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { DEFAULT_ACTIVE_TOOL_NAMES, mapToolNamesForPlatform } from "./default-tool-surface.js";
+import { acknowledgeWorkerClaimReview } from "./delegation/session-worker-claim.js";
 import { createCoreDiagnosticsToolDefinitions } from "./extensions/builtin.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { disposeExtensionEventSubscriptions } from "./extensions/loader.js";
@@ -42,23 +44,68 @@ import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { resolveCliModel } from "./model-resolver.js";
 import { evaluateSurfaceFitness } from "./model-router/fitness-gate.js";
 import { FitnessStore } from "./models/fitness-store.js";
+import { describeInFlightWorkUnit, getInFlightWorkUnits } from "./reload-blockers.js";
 import { ScoutController } from "./scout-controller.js";
+import { getSessionRole, isWorkerSession, WORKER_FORBIDDEN_TOOLS } from "./session-role.js";
 import { matchesResourceProfilePattern, } from "./settings-manager.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
+import { projectOpenTaskSteps } from "./tasks/task-projection.js";
 import { buildReflexUserPrompt, parseReflexPlan, REFLEX_INTERPRETER_SYSTEM_PROMPT, } from "./toolkit/reflex-interpreter.js";
 import { executeToolkitScript } from "./toolkit/script-runner.js";
+import { createAskQuestionToolDefinition } from "./tools/ask-question.js";
 import { createContextScoutToolDefinition } from "./tools/context-scout.js";
 import { createDelegateToolDefinition } from "./tools/delegate.js";
 import { createDelegateStatusToolDefinition } from "./tools/delegate-status.js";
 import { createFindTool } from "./tools/find.js";
 import { createGoalToolDefinition } from "./tools/goal.js";
 import { createGrepTool } from "./tools/grep.js";
-import { createAllToolDefinitions } from "./tools/index.js";
+import { allToolNames, createToolDefinition } from "./tools/index.js";
 import { createModelFitnessToolDefinition } from "./tools/model-fitness.js";
+import { resolveToCwd } from "./tools/path-utils.js";
 import { createReadTool } from "./tools/read.js";
+import { createRunProcessToolDefinition } from "./tools/run-process.js";
 import { createRunToolkitScriptToolDefinition } from "./tools/run-toolkit-script.js";
 import { createTaskStepsToolDefinition } from "./tools/task-steps.js";
+import { dispatchTmuxWorker } from "./tools/tmux-dispatch.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
+import { createWorktreeSyncToolDefinition } from "./tools/worktree-sync.js";
+import { createLane } from "./worktree-sync/git-engine.js";
+import { WorktreeLaneGate } from "./worktree-sync/lane-gate.js";
+import { buildWorktreeSyncEngineDeps, getBoundWorktreeLaneKey } from "./worktree-sync/runtime.js";
+/**
+ * Deterministic `addSpawnedUsage` reportId: `kind` + session id + a content hash of `identity`
+ * (never `Date.now`/random). Same identity on a retry of the same logical work unit yields the same
+ * id, so the ledger's `seenSubagentReportIds` dedupe catches a duplicate report instead of
+ * double-counting spend.
+ */
+function deriveSpawnedUsageReportId(kind, sessionId, identity) {
+    const digest = createHash("sha256").update(identity).digest("hex").slice(0, 16);
+    return `${kind}:${sessionId}:${digest}`;
+}
+/**
+ * Is `toolCallId` a real, answered tool call on `sessionManager`'s active branch? A
+ * toolCallId is "real" iff a toolResult message on that branch responded to it -- the same
+ * toolResult/toolCallId match `context-pipeline.ts`'s `_buildSessionEntryIdLookup` uses, and
+ * branch-scoped (via `getBranch()`) so a sibling branch's tool calls never count. Exported (pure,
+ * no `this`) so the goal tool's `hasToolCallId` wiring below is directly testable against a real
+ * `SessionManager` without constructing the whole `RuntimeBuilder`.
+ */
+export function hasAnsweredToolCallOnBranch(sessionManager, toolCallId) {
+    return sessionManager
+        .getBranch()
+        .some((entry) => entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolCallId === toolCallId);
+}
+/**
+ * Goal-tool adapter over the canonical open-task projection. Exported (pure, no `this`) so the
+ * production `getOpenTaskSteps` wiring below remains directly testable without another filter.
+ */
+export function deriveOpenTaskStepRefs(taskStepsState) {
+    return projectOpenTaskSteps(taskStepsState).map((step) => ({
+        id: step.id,
+        content: step.content,
+        ...(step.requirementIds?.length ? { requirementIds: step.requirementIds } : {}),
+    }));
+}
 /**
  * Owns the tool-registry build and the self-modification-safe extension reload extracted from
  * {@link AgentSession}. See the module header for the snapshot-ownership and host-binding boundaries.
@@ -76,6 +123,50 @@ export class RuntimeBuilder {
     constructor(deps) {
         this.deps = deps;
     }
+    /**
+     * Resolve the construction and activation policy once for a runtime generation. This is the
+     * UAC choke point: callers must consult it before invoking a tool factory, not merely before
+     * placing an already-created definition in the live registry.
+     */
+    _createToolAccessPolicy() {
+        const role = getSessionRole();
+        const configuredAllowedToolNames = this.deps.getAllowedToolNames();
+        const allowedToolNames = configuredAllowedToolNames
+            ? new Set(mapToolNamesForPlatform([...configuredAllowedToolNames]))
+            : undefined;
+        const configuredExcludedToolNames = this.deps.getExcludedToolNames();
+        const excludedToolNames = configuredExcludedToolNames
+            ? new Set(mapToolNamesForPlatform([...configuredExcludedToolNames]))
+            : undefined;
+        const configuredToolProfileFilter = this.deps.getToolProfileFilter();
+        const toolProfileFilter = configuredToolProfileFilter
+            ? {
+                allow: mapToolNamesForPlatform(configuredToolProfileFilter.allow),
+                block: mapToolNamesForPlatform(configuredToolProfileFilter.block),
+            }
+            : undefined;
+        return {
+            allowedToolNames,
+            toolProfileFilter,
+            allows: (name) => {
+                // Strict worker UAC ceiling wins over every explicit grant.
+                if (role === "worker" && WORKER_FORBIDDEN_TOOLS.has(name))
+                    return false;
+                if (allowedToolNames && !allowedToolNames.has(name))
+                    return false;
+                if (excludedToolNames?.has(name))
+                    return false;
+                if (!toolProfileFilter)
+                    return true;
+                if (toolProfileFilter.allow.length > 0 && !matchesResourceProfilePattern(name, toolProfileFilter.allow)) {
+                    return false;
+                }
+                if (matchesResourceProfilePattern(name, toolProfileFilter.block))
+                    return false;
+                return true;
+            },
+        };
+    }
     async _runContextScout(query, maxTurns, artifactStore) {
         const cwd = this.deps.getCwd();
         const controller = new ScoutController({
@@ -89,6 +180,9 @@ export class RuntimeBuilder {
             streamFn: this.deps.getAgent().streamFn,
             fileExists: (path) => existsSync(resolveCwdPath(cwd, path)),
             countLines: (path) => countFileLines(resolveCwdPath(cwd, path)),
+            // Lets the scout register itself in the reload-gate quiesce registry (see
+            // reload-blockers.ts) for its own agentDir — the same key `_assertReloadQuiescent` reads.
+            getAgentDir: () => this.deps.getAgentDir(),
         });
         return controller.run(query, maxTurns);
     }
@@ -129,35 +223,9 @@ export class RuntimeBuilder {
         // capability/profile-filtered, so feeding it back through setActiveToolsByName would
         // permanently shrink what a later switch to a larger model (or permissive profile) restores.
         const previousActiveToolNames = mapToolNamesForPlatform(this.deps.getRequestedActiveToolNames() ?? this.deps.getActiveToolNames());
-        const configuredAllowedToolNames = this.deps.getAllowedToolNames();
-        const allowedToolNames = configuredAllowedToolNames
-            ? new Set(mapToolNamesForPlatform([...configuredAllowedToolNames]))
-            : undefined;
-        const configuredExcludedToolNames = this.deps.getExcludedToolNames();
-        const excludedToolNames = configuredExcludedToolNames
-            ? new Set(mapToolNamesForPlatform([...configuredExcludedToolNames]))
-            : undefined;
-        const configuredToolProfileFilter = this.deps.getToolProfileFilter();
-        const toolProfileFilter = configuredToolProfileFilter
-            ? {
-                allow: mapToolNamesForPlatform(configuredToolProfileFilter.allow),
-                block: mapToolNamesForPlatform(configuredToolProfileFilter.block),
-            }
-            : undefined;
-        const isAllowedTool = (name) => {
-            if (allowedToolNames && !allowedToolNames.has(name))
-                return false;
-            if (excludedToolNames?.has(name))
-                return false;
-            if (!toolProfileFilter)
-                return true;
-            if (toolProfileFilter.allow.length > 0 && !matchesResourceProfilePattern(name, toolProfileFilter.allow)) {
-                return false;
-            }
-            if (matchesResourceProfilePattern(name, toolProfileFilter.block))
-                return false;
-            return true;
-        };
+        const toolAccess = this._createToolAccessPolicy();
+        const { allowedToolNames, toolProfileFilter } = toolAccess;
+        const isAllowedTool = toolAccess.allows;
         const registeredTools = this.deps.getExtensionRunner().getAllRegisteredTools();
         const allCustomTools = [
             ...registeredTools,
@@ -262,7 +330,7 @@ export class RuntimeBuilder {
                     nextActiveToolNames.push(toolName);
                 }
             }
-            // G13: an explicit grant that binds to NO registered tool is a silent no-op — typo'd
+            // An explicit grant that binds to NO registered tool is a silent no-op — typo'd
             // name, or the owning extension is not granted/loaded. Surface it.
             this.deps.setUnboundToolGrantWarnings(explicitAllowPatterns
                 .filter((pattern) => !boundPatterns.has(pattern))
@@ -371,95 +439,252 @@ export class RuntimeBuilder {
         const shellCommandPrefix = settingsManager.getShellCommandPrefix();
         const shellPath = settingsManager.getShellPath();
         const baseToolsOverride = this.deps.getBaseToolsOverride();
+        const toolAccess = this._createToolAccessPolicy();
         // Artifact-producing tools must not emit a "Full output: artifact tool-output:<id>" handle
         // that nothing can resolve. If artifact_retrieve is explicitly excluded/blocked/outside
         // an active allowlist, don't hand grep/find/run_toolkit_script an artifact store at all:
         // they fall back to their bounded preview/truncation behavior, with no payload/meta files
         // ever written and no retrieval promise made.
-        const toolArtifactStore = this.deps.isToolOrCommandAllowedByProfile("artifact_retrieve")
-            ? this.deps.getToolArtifactStore()
-            : undefined;
-        const baseToolDefinitions = baseToolsOverride
-            ? Object.fromEntries(Object.entries(baseToolsOverride).map(([name, tool]) => [name, createToolDefinitionFromAgentTool(tool)]))
-            : createAllToolDefinitions(this.deps.getCwd(), {
-                read: { autoResizeImages },
-                bash: { commandPrefix: shellCommandPrefix, shellPath },
-                grep: { artifactStore: toolArtifactStore },
-                find: { artifactStore: toolArtifactStore },
-                artifact_retrieve: { artifactStore: toolArtifactStore },
-            });
-        this._baseToolDefinitions = new Map(Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool]));
+        const toolArtifactStore = !baseToolsOverride && toolAccess.allows("artifact_retrieve") ? this.deps.getToolArtifactStore() : undefined;
+        const toolOptions = {
+            read: { autoResizeImages },
+            bash: {
+                commandPrefix: shellCommandPrefix,
+                shellPath,
+                sessionKey: this.deps.getShellSessionKey(),
+                platform: process.platform,
+            },
+            grep: { artifactStore: toolArtifactStore },
+            find: { artifactStore: toolArtifactStore },
+            artifact_retrieve: { artifactStore: toolArtifactStore },
+        };
+        this._baseToolDefinitions = baseToolsOverride
+            ? new Map(Object.entries(baseToolsOverride)
+                .filter(([name]) => toolAccess.allows(name))
+                .map(([name, tool]) => [name, createToolDefinitionFromAgentTool(tool)]))
+            : new Map([...allToolNames]
+                .filter((name) => toolAccess.allows(name))
+                .map((name) => [name, createToolDefinition(name, this.deps.getCwd(), toolOptions)]));
         if (!baseToolsOverride) {
-            for (const definition of createCoreDiagnosticsToolDefinitions(() => this.deps.getActiveToolNames(), () => this.getAllTools(), (messages) => this.deps.getContextGcReport(messages), () => this.deps.getMemoryAuditDiagnostics())) {
-                this._baseToolDefinitions.set(definition.name, definition);
+            if (toolAccess.allows("run_process")) {
+                const orchestrationProfile = this.deps.getOrchestrationProfile?.();
+                if (orchestrationProfile?.executionPolicy) {
+                    this._baseToolDefinitions.set("run_process", createRunProcessToolDefinition(this.deps.getCwd(), {
+                        policy: orchestrationProfile.executionPolicy,
+                        maxWallClockMs: orchestrationProfile.budget.maxWallClockMs ?? 0,
+                    }));
+                }
             }
-            const goalToolDefinition = createGoalToolDefinition({
-                getGoalState: () => this.deps.getGoalStateSnapshot(),
-                saveGoalState: (state) => {
-                    this.deps.saveGoalStateSnapshot(state);
-                },
-            });
-            this._baseToolDefinitions.set(goalToolDefinition.name, goalToolDefinition);
-            const taskStepsToolDefinition = createTaskStepsToolDefinition({
-                getTaskStepsState: () => this.deps.getTaskStepsStateSnapshot(),
-                saveTaskStepsState: (state) => {
-                    this.deps.saveTaskStepsStateSnapshot(state);
-                },
-            });
-            this._baseToolDefinitions.set(taskStepsToolDefinition.name, taskStepsToolDefinition);
-            const delegateToolDefinition = createDelegateToolDefinition({
-                startWorkerDelegation: (args) => this.deps.startWorkerDelegation(args),
-                runWorkerDelegation: (args) => this.deps.runWorkerDelegationOnce(args),
-            });
-            const delegateStatusToolDefinition = createDelegateStatusToolDefinition({
-                getLaneRecords: () => this.deps.getWorkerLaneRecords(),
-                getWorkerResultSnapshots: () => this.deps.getWorkerResultSnapshots(),
+            if (toolAccess.allows("context_audit")) {
+                for (const definition of createCoreDiagnosticsToolDefinitions(() => this.deps.getActiveToolNames(), () => this.getAllTools(), (messages) => this.deps.getContextGcReport(messages), () => this.deps.getMemoryAuditDiagnostics())) {
+                    this._baseToolDefinitions.set(definition.name, definition);
+                }
+            }
+            // Hoisted above the goal-tool registration (rather than declared only inside the
+            // worktreeSync-enabled block further below) so the SAME settings/deps factory backs both
+            // the goal->tmux lane-first dispatch dep (`createLaneWorktree`, immediately below) and the
+            // `worktree_sync` tool registration later in this method -- one source of truth, no drift.
+            const worktreeSyncSettings = toolAccess.allows("goal") || toolAccess.allows("worktree_sync")
+                ? settingsManager.getWorktreeSyncSettings()
+                : undefined;
+            const worktreeSyncEngineDeps = () => buildWorktreeSyncEngineDeps({
+                cwd: this.deps.getCwd(),
+                agentDir: this.deps.getAgentDir(),
+                settingsManager: this.deps.getSettingsManager(),
+                sessionId: this.deps.getSessionManager().getSessionId(),
             });
-            this._baseToolDefinitions.set(delegateToolDefinition.name, delegateToolDefinition);
-            this._baseToolDefinitions.set(delegateStatusToolDefinition.name, delegateStatusToolDefinition);
+            if (toolAccess.allows("goal")) {
+                const goalToolDefinition = createGoalToolDefinition({
+                    getGoalState: () => this.deps.getGoalStateSnapshot(),
+                    saveGoalState: (state) => {
+                        this.deps.saveGoalStateSnapshot(state);
+                    },
+                    // kind:"tool" evidence refs verify against real session records.
+                    hasToolCallId: (toolCallId) => hasAnsweredToolCallOnBranch(this.deps.getSessionManager(), toolCallId),
+                    // kind:"worker" evidence refs verify against the SAME live lane/claim accessors the
+                    // delegate_status tool already uses below -- live wiring (these were declared optional
+                    // and read-defensive on the goal-tool deps type).
+                    getLaneRecords: () => this.deps.getWorkerLaneRecords(),
+                    getWorkerClaimSnapshots: () => this.deps.getWorkerClaimSnapshots(),
+                    // dispatch_worker's tool-layer side effect for the default (in_process) route: starts a
+                    // real in-process worker lane through the SAME starter the delegate tool uses (below),
+                    // adapted from its `{started:true;record}|{started:false;skipReason}` shape onto this
+                    // tool's narrower `{laneId}|{skipReason}` shape.
+                    startWorkerDelegation: (args) => {
+                        const outcome = this.deps.startWorkerDelegation({ instructions: args.instructions });
+                        return outcome.started ? { laneId: outcome.record.laneId } : { skipReason: outcome.skipReason };
+                    },
+                    // dispatch_worker's tool-layer side effect for `dispatchTarget:"tmux"`: core structurally
+                    // invokes the SAME tmux_agent_manager fire_task call the model itself would make (no
+                    // extension change, no faked launch/laneId) -- see tmux-dispatch.ts's doc comment.
+                    dispatchTmuxWorker: (args) => dispatchTmuxWorker({
+                        getToolDefinition: (name) => this.getToolDefinition(name),
+                        createExtensionContext: () => this.deps.getExtensionRunner().createContext(),
+                        resolveManagedLaneId: (id) => this.deps.resolveManagedLaneId(id),
+                        getGoalId: () => this.deps.getGoalStateSnapshot()?.goalId,
+                        evaluateWorkerLaneRefusal: () => this.deps.getLaneWorkerRefusal(),
+                        // Lane-first dispatch, wired ONLY when worktree-sync is enabled -- absent otherwise,
+                        // so a disabled/default session gets the existing byte-identical fire_task params.
+                        createLaneWorktree: worktreeSyncSettings?.enabled
+                            ? async (laneArgs) => {
+                                const created = await createLane(worktreeSyncEngineDeps(), {
+                                    ...(laneArgs.goalId !== undefined ? { goalId: laneArgs.goalId } : {}),
+                                    requirementId: laneArgs.requirementId,
+                                });
+                                // Never fake a lane: any non-"ok" engine code (max lanes, invalid key, git
+                                // error, ...) is refused, mapped by the caller onto the stable
+                                // "worktree_create_failed" skip reason before any fire_task call runs.
+                                if (created.code !== "ok")
+                                    return { skipReason: created.code };
+                                return { laneKey: created.lane.laneKey, worktreePath: created.lane.worktreePath };
+                            }
+                            : undefined,
+                    }, args),
+                    cwd: () => this.deps.getCwd(),
+                    // Reuses the already branch-scoped getTaskStepsStateSnapshot dep -- no new
+                    // SessionManager access needed for the cross-visibility nudge.
+                    getOpenTaskSteps: () => deriveOpenTaskStepRefs(this.deps.getTaskStepsStateSnapshot()),
+                });
+                this._baseToolDefinitions.set(goalToolDefinition.name, goalToolDefinition);
+            }
+            if (toolAccess.allows("task_steps")) {
+                const taskStepsToolDefinition = createTaskStepsToolDefinition({
+                    getTaskStepsState: () => this.deps.getTaskStepsStateSnapshot(),
+                    saveTaskStepsState: (state) => {
+                        this.deps.saveTaskStepsStateSnapshot(state);
+                    },
+                });
+                this._baseToolDefinitions.set(taskStepsToolDefinition.name, taskStepsToolDefinition);
+            }
+            if (toolAccess.allows("ask_question")) {
+                const askQuestionToolDefinition = createAskQuestionToolDefinition({
+                    sessionManager: this.deps.getSessionManager(),
+                    artifactStore: toolArtifactStore,
+                    getImageStore: () => this.deps.getSessionImageStore(),
+                });
+                this._baseToolDefinitions.set(askQuestionToolDefinition.name, askQuestionToolDefinition);
+            }
+            if (toolAccess.allows("delegate")) {
+                const delegateToolDefinition = createDelegateToolDefinition({
+                    startWorkerDelegation: (args) => this.deps.startWorkerDelegation(args),
+                    runWorkerDelegation: (args) => this.deps.runWorkerDelegationOnce(args),
+                    orchestrationProfiles: this.deps.getOrchestrationProfileCatalog(),
+                });
+                this._baseToolDefinitions.set(delegateToolDefinition.name, delegateToolDefinition);
+            }
+            if (toolAccess.allows("delegate_status")) {
+                const delegateStatusToolDefinition = createDelegateStatusToolDefinition({
+                    getLaneRecords: () => this.deps.getWorkerLaneRecords(),
+                    getWorkerClaimSnapshots: () => this.deps.getWorkerClaimSnapshots(),
+                    // Durable ack persists straight through the session log; routed here (rather than
+                    // a new agent-session dep) because getSessionManager() is already a stable, generic
+                    // passthrough dep, so no other package needs to change for this to work.
+                    acknowledgeWorkerReview: (requestId) => acknowledgeWorkerClaimReview(this.deps.getSessionManager(), requestId),
+                });
+                this._baseToolDefinitions.set(delegateStatusToolDefinition.name, delegateStatusToolDefinition);
+            }
             // Registered but not default-active: probes spend tokens on the probed model, so
             // activation is an explicit choice (settings/profile/setActiveTools or /autonomy fitness).
-            const modelFitnessToolDefinition = createModelFitnessToolDefinition({
-                runProbe: (args) => this.deps.runModelFitness(args),
-            });
-            this._baseToolDefinitions.set(modelFitnessToolDefinition.name, modelFitnessToolDefinition);
-            if (settingsManager.getScoutSettings().enabled) {
+            if (toolAccess.allows("model_fitness")) {
+                const modelFitnessToolDefinition = createModelFitnessToolDefinition({
+                    runProbe: (args) => this.deps.runModelFitness(args),
+                });
+                this._baseToolDefinitions.set(modelFitnessToolDefinition.name, modelFitnessToolDefinition);
+            }
+            if (toolAccess.allows("context_scout") && settingsManager.getScoutSettings().enabled) {
                 const contextScoutToolDefinition = createContextScoutToolDefinition({
                     runScout: (input) => this._runContextScout(input.query, input.maxTurns, toolArtifactStore),
                 });
                 this._baseToolDefinitions.set(contextScoutToolDefinition.name, contextScoutToolDefinition);
             }
-            const runToolkitScriptToolDefinition = createRunToolkitScriptToolDefinition({
-                getScripts: () => this.deps.getSettingsManager().getToolkitScripts(),
-                execute: (script, scriptArgs) => executeToolkitScript({ script, scriptArgs, cwd: this.deps.getCwd() }),
-                artifactStore: toolArtifactStore,
-                // Reflex brain (fitness-gated local model): resolves ambiguous requests into a
-                // registry pick. Best-effort — absent/unfit brain keeps the shortlist behavior.
-                interpret: async (request, scripts) => {
-                    const model = this.deps.resolveCurationModelIfFit();
-                    if (!model)
-                        return undefined;
-                    const completion = await this.deps.runIsolatedCompletion({
-                        systemPrompt: REFLEX_INTERPRETER_SYSTEM_PROMPT,
-                        messages: [
-                            {
-                                role: "user",
-                                content: [{ type: "text", text: buildReflexUserPrompt(request, scripts) }],
-                                timestamp: Date.now(),
-                            },
-                        ],
-                        model,
-                        thinkingLevel: "off",
-                        maxTokens: 256,
-                        cacheRetention: "short",
+            if (toolAccess.allows("run_toolkit_script")) {
+                const runToolkitScriptToolDefinition = createRunToolkitScriptToolDefinition({
+                    getScripts: () => this.deps.getSettingsManager().getToolkitScripts(),
+                    execute: (script, scriptArgs) => executeToolkitScript({ script, scriptArgs, cwd: this.deps.getCwd() }),
+                    artifactStore: toolArtifactStore,
+                    // Reflex brain (fitness-gated local model): resolves ambiguous requests into a
+                    // registry pick. Best-effort — absent/unfit brain keeps the shortlist behavior.
+                    interpret: async (request, scripts) => {
+                        const model = this.deps.resolveCurationModelIfFit();
+                        if (!model)
+                            return undefined;
+                        const completion = await this.deps.runIsolatedCompletion({
+                            systemPrompt: REFLEX_INTERPRETER_SYSTEM_PROMPT,
+                            messages: [
+                                {
+                                    role: "user",
+                                    content: [{ type: "text", text: buildReflexUserPrompt(request, scripts) }],
+                                    timestamp: Date.now(),
+                                },
+                            ],
+                            model,
+                            thinkingLevel: "off",
+                            maxTokens: 256,
+                            cacheRetention: "short",
+                            // Stable per-lane synthetic affinity key so repeat ambiguous-request
+                            // interpretations hit the same cache-warm backend.
+                            laneKind: "toolkit-brain",
+                        });
+                        if (completion.usage.cost.total > 0 || completion.usage.totalTokens > 0) {
+                            // `reportId` keyed on the ambiguous request text driving THIS interpretation —
+                            // stable across a retry of the same tool call, distinct across genuinely
+                            // different requests.
+                            const reportId = deriveSpawnedUsageReportId("toolkit-brain", this.deps.getSessionManager().getSessionId(), request);
+                            this.deps.addSpawnedUsage(completion.usage, { label: "toolkit-brain", reportId });
+                        }
+                        return parseReflexPlan(completion.text);
+                    },
+                });
+                this._baseToolDefinitions.set(runToolkitScriptToolDefinition.name, runToolkitScriptToolDefinition);
+            }
+            // Worktree-sync (opt-in): the closed-action lane workflow tool, plus -- for a session
+            // launched lane-bound (PI_WORKTREE_LANE) -- the G8/G10 lane gate wrapped UNDER the
+            // file-mutation tools (edit/write, plus cooperative bash only for interactive lanes), so a sync_required lane fails closed with the
+            // exact recovery step rather than relying on prompt compliance. `worktreeSyncSettings` /
+            // `worktreeSyncEngineDeps` are hoisted above (declared before the goal-tool registration)
+            // so the goal->tmux lane-first dispatch dep and this tool share one settings/deps source.
+            if (toolAccess.allows("worktree_sync") && worktreeSyncSettings?.enabled) {
+                const worktreeSyncToolDefinition = createWorktreeSyncToolDefinition({
+                    engineDeps: worktreeSyncEngineDeps,
+                    settings: () => this.deps.getSettingsManager().getWorktreeSyncSettings(),
+                    boundLaneKey: () => getBoundWorktreeLaneKey(),
+                    isWorker: () => isWorkerSession(),
+                });
+                this._baseToolDefinitions.set(worktreeSyncToolDefinition.name, worktreeSyncToolDefinition);
+                const boundLaneKey = getBoundWorktreeLaneKey();
+                if (boundLaneKey) {
+                    const laneGate = new WorktreeLaneGate({
+                        laneKey: boundLaneKey,
+                        engineDeps: worktreeSyncEngineDeps,
+                        policy: () => this.deps.getSettingsManager().getWorktreeSyncSettings().syncPolicy,
+                        hardShell: isWorkerSession(),
+                        trustedGateCommand: () => this.deps.getSettingsManager().getWorktreeSyncSettings().gateCommand,
                     });
-                    if (completion.usage.cost.total > 0 || completion.usage.totalTokens > 0) {
-                        this.deps.addSpawnedUsage(completion.usage, { label: "toolkit-brain" });
+                    for (const gatedToolName of ["edit", "write", "bash"]) {
+                        const original = this._baseToolDefinitions.get(gatedToolName);
+                        if (!original)
+                            continue;
+                        this._baseToolDefinitions.set(gatedToolName, {
+                            ...original,
+                            execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+                                const bashCommand = gatedToolName === "bash" ? params?.command : undefined;
+                                const rawPath = gatedToolName === "edit" || gatedToolName === "write"
+                                    ? params?.path
+                                    : undefined;
+                                const targetPath = rawPath !== undefined ? resolveToCwd(rawPath, this.deps.getCwd()) : undefined;
+                                const check = await laneGate.checkMutation(gatedToolName, bashCommand, targetPath);
+                                if (!check.allowed) {
+                                    return {
+                                        content: [{ type: "text", text: check.message }],
+                                        details: { code: check.code },
+                                    };
+                                }
+                                return original.execute(toolCallId, params, signal, onUpdate, ctx);
+                            },
+                        });
                     }
-                    return parseReflexPlan(completion.text);
-                },
-            });
-            this._baseToolDefinitions.set(runToolkitScriptToolDefinition.name, runToolkitScriptToolDefinition);
+                }
+            }
         }
         const extensionsResult = this.deps.getResourceLoader().getExtensions();
         if (options.flagValues) {
@@ -482,10 +707,21 @@ export class RuntimeBuilder {
             throw error;
         }
         this.deps.applyExtensionBindings(runner);
+        const boundLaneKey = getBoundWorktreeLaneKey();
+        const hardLaneWorker = boundLaneKey !== undefined && isWorkerSession();
+        const explicitlyRequestedTools = options.activeToolNames ?? (baseToolsOverride ? Object.keys(baseToolsOverride) : undefined);
+        if (hardLaneWorker && explicitlyRequestedTools?.includes("bash")) {
+            throw new Error("hard lane workers cannot request unrestricted bash; use typed worktree_sync actions");
+        }
         const defaultActiveToolNames = mapToolNamesForPlatform(baseToolsOverride
             ? Object.keys(baseToolsOverride)
             : [...DEFAULT_ACTIVE_TOOL_NAMES, ...(settingsManager.getScoutSettings().enabled ? ["context_scout"] : [])]);
-        const baseActiveToolNames = mapToolNamesForPlatform(options.activeToolNames ?? defaultActiveToolNames);
+        const baseActiveToolNames = mapToolNamesForPlatform(options.activeToolNames ?? defaultActiveToolNames).filter((name) => !hardLaneWorker || name !== "bash");
+        if (hardLaneWorker &&
+            settingsManager.getWorktreeSyncSettings().enabled &&
+            !baseActiveToolNames.includes("worktree_sync")) {
+            baseActiveToolNames.push("worktree_sync");
+        }
         this.refreshToolRegistry({
             activeToolNames: baseActiveToolNames,
             includeAllExtensionTools: options.includeAllExtensionTools,
@@ -525,13 +761,29 @@ export class RuntimeBuilder {
             this._reloadRequested = false;
         }
     }
-    async _reloadOnce() {
+    /**
+     * Unified reload-gate quiescence check: refuses the caller's action (message-prefixed by
+     * `action`) while the agent is streaming, is compacting, or ANY background work unit is still
+     * registered in the in-process quiesce registry — background lanes (research/worker/
+     * model-fitness), a context-scout run, or an isolated completion (see reload-blockers.ts). Every
+     * live-op entry point below calls this so they refuse identically; this is a synchronous refusal
+     * (not a wait/poll) — callers retry via the same coalescing `reload()` already provides.
+     */
+    _assertReloadQuiescent(action) {
         if (this.deps.isStreaming()) {
-            throw new Error("Cannot reload while the agent is streaming or a tool call is active");
+            throw new Error(`Cannot ${action} while the agent is streaming or a tool call is active`);
         }
         if (this.deps.isCompacting()) {
-            throw new Error("Cannot reload while context compaction or branch summarization is active");
+            throw new Error(`Cannot ${action} while context compaction or branch summarization is active`);
+        }
+        const units = getInFlightWorkUnits(this.deps.getAgentDir());
+        if (units.length > 0) {
+            const summary = units.map(describeInFlightWorkUnit).join(", ");
+            throw new Error(`Cannot ${action} while background work is in flight: ${summary}`);
         }
+    }
+    async _reloadOnce() {
+        this._assertReloadQuiescent("reload");
         const previousRunner = this.deps.getExtensionRunner();
         const snapshot = this._createReloadRuntimeSnapshot();
         // Preserve the pre-filter tool REQUEST across the rebuild, not the capability/profile-filtered
@@ -600,6 +852,9 @@ export class RuntimeBuilder {
             await this.deps.getResourceLoader().commitReload?.();
             // Re-derive the memory subsystem from the reloaded settings/providers.
             await this.deps.initializeMemory();
+            // This generation has fully committed (no rollback below this point), so any local
+            // runtime the host no longer routes to under the new configuration can be stopped now.
+            this.deps.reconcileLocalRuntimes?.();
         }
         catch (error) {
             offReloadErrors?.();
@@ -618,12 +873,7 @@ export class RuntimeBuilder {
      * Falls back to full reload on error.
      */
     async unloadExtensionLive(extensionPath) {
-        if (this.deps.isStreaming()) {
-            throw new Error("Cannot unload extension while the agent is streaming or a tool call is active");
-        }
-        if (this.deps.isCompacting()) {
-            throw new Error("Cannot unload extension while context compaction or branch summarization is active");
-        }
+        this._assertReloadQuiescent("unload extension");
         const ext = this.deps.getResourceLoader().getLoadedExtension(extensionPath);
         if (!ext) {
             return; // Nothing to unload
@@ -682,11 +932,9 @@ export class RuntimeBuilder {
      * Falls back to full reload on error.
      */
     async loadExtensionLive(extensionPath) {
-        if (this.deps.isStreaming()) {
-            throw new Error("Cannot load extension while the agent is streaming or a tool call is active");
-        }
-        if (this.deps.isCompacting()) {
-            throw new Error("Cannot load extension while context compaction or branch summarization is active");
+        this._assertReloadQuiescent("load extension");
+        if (!this.deps.getSettingsManager().isResourceAllowedByProfile("extensions", extensionPath)) {
+            throw new Error(`Cannot load extension outside the active resource profile: ${extensionPath}`);
         }
         const previousRunner = this.deps.getExtensionRunner();
         try {
@@ -728,12 +976,7 @@ export class RuntimeBuilder {
      * Falls back to full reload if any individual load/unload fails.
      */
     async reconcileLoadedExtensions() {
-        if (this.deps.isStreaming()) {
-            throw new Error("Cannot reconcile extensions while the agent is streaming or a tool call is active");
-        }
-        if (this.deps.isCompacting()) {
-            throw new Error("Cannot reconcile extensions while context compaction or branch summarization is active");
-        }
+        this._assertReloadQuiescent("reconcile extensions");
         try {
             // Get all discoverable extension paths
             const allDiscoverablePaths = await this.deps.getResourceLoader().getDiscoverableExtensionPaths();