@caupulican/pi-adaptative 0.81.37 → 0.81.39

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 { acknowledgeWorkerResultReview } from "./delegation/session-worker-result.js";
 import { createCoreDiagnosticsToolDefinitions } from "./extensions/builtin.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { disposeExtensionEventSubscriptions } from "./extensions/loader.js";
@@ -42,7 +44,9 @@ 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 { buildReflexUserPrompt, parseReflexPlan, REFLEX_INTERPRETER_SYSTEM_PROMPT, } from "./toolkit/reflex-interpreter.js";
@@ -55,10 +59,51 @@ import { createGoalToolDefinition } from "./tools/goal.js";
 import { createGrepTool } from "./tools/grep.js";
 import { createAllToolDefinitions } 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 { 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);
+}
+/**
+ * Project a task-steps snapshot down to the OPEN (non-terminal) steps the goal tool's
+ * cross-visibility nudge needs. Mirrors `goal-runtime-snapshot.ts`'s `openTaskSteps` filter
+ * (status not "completed"/"cancelled", `activeForm || content`) so the two read the same
+ * "open" definition, narrowed to `OpenTaskStepRef`'s id+content shape. Exported (pure, no
+ * `this`) so the goal tool's `getOpenTaskSteps` wiring below is directly testable.
+ */
+export function deriveOpenTaskStepRefs(taskStepsState) {
+    return (taskStepsState?.steps ?? [])
+        .filter((step) => step.status !== "completed" && step.status !== "cancelled")
+        .map((step) => ({ id: step.id, content: step.activeForm || step.content }));
+}
 /**
  * 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.
@@ -89,6 +134,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);
     }
@@ -124,6 +172,7 @@ export class RuntimeBuilder {
         return this._toolDefinitions.get(name)?.definition;
     }
     refreshToolRegistry(options) {
+        const role = getSessionRole();
         const previousRegistryNames = new Set(this._toolRegistry.keys());
         // Re-derive from the pre-filter REQUEST, never from agent.state.tools: the active set is
         // capability/profile-filtered, so feeding it back through setActiveToolsByName would
@@ -145,6 +194,11 @@ export class RuntimeBuilder {
             }
             : undefined;
         const isAllowedTool = (name) => {
+            // Strict worker UAC ceiling: wins over allow-list/exclude/profile -- a worker session
+            // (lane-bound or dispatched) can never activate this tool no matter how permissively the
+            // active profile or an explicit request names it. See session-role.ts.
+            if (role === "worker" && WORKER_FORBIDDEN_TOOLS.has(name))
+                return false;
             if (allowedToolNames && !allowedToolNames.has(name))
                 return false;
             if (excludedToolNames?.has(name))
@@ -262,7 +316,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))
@@ -383,7 +437,7 @@ export class RuntimeBuilder {
             ? Object.fromEntries(Object.entries(baseToolsOverride).map(([name, tool]) => [name, createToolDefinitionFromAgentTool(tool)]))
             : createAllToolDefinitions(this.deps.getCwd(), {
                 read: { autoResizeImages },
-                bash: { commandPrefix: shellCommandPrefix, shellPath },
+                bash: { commandPrefix: shellCommandPrefix, shellPath, sessionKey: this.deps.getShellSessionKey() },
                 grep: { artifactStore: toolArtifactStore },
                 find: { artifactStore: toolArtifactStore },
                 artifact_retrieve: { artifactStore: toolArtifactStore },
@@ -393,11 +447,67 @@ export class RuntimeBuilder {
             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 = settingsManager.getWorktreeSyncSettings();
+            const worktreeSyncEngineDeps = () => buildWorktreeSyncEngineDeps({
+                cwd: this.deps.getCwd(),
+                agentDir: this.deps.getAgentDir(),
+                settingsManager: this.deps.getSettingsManager(),
+                sessionId: this.deps.getSessionManager().getSessionId(),
+            });
             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/result 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(),
+                getWorkerResultSnapshots: () => this.deps.getWorkerResultSnapshots(),
+                // 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);
             const taskStepsToolDefinition = createTaskStepsToolDefinition({
@@ -414,6 +524,10 @@ export class RuntimeBuilder {
             const delegateStatusToolDefinition = createDelegateStatusToolDefinition({
                 getLaneRecords: () => this.deps.getWorkerLaneRecords(),
                 getWorkerResultSnapshots: () => this.deps.getWorkerResultSnapshots(),
+                // 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) => acknowledgeWorkerResultReview(this.deps.getSessionManager(), requestId),
             });
             this._baseToolDefinitions.set(delegateToolDefinition.name, delegateToolDefinition);
             this._baseToolDefinitions.set(delegateStatusToolDefinition.name, delegateStatusToolDefinition);
@@ -452,14 +566,69 @@ export class RuntimeBuilder {
                         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) {
-                        this.deps.addSpawnedUsage(completion.usage, { label: "toolkit-brain" });
+                        // `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 (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,
+                    });
+                    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);
+                            },
+                        });
+                    }
+                }
+            }
         }
         const extensionsResult = this.deps.getResourceLoader().getExtensions();
         if (options.flagValues) {
@@ -482,10 +651,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 +705,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 +796,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 +817,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,12 +876,7 @@ 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");
         const previousRunner = this.deps.getExtensionRunner();
         try {
             // Load the extension with fresh import
@@ -728,12 +917,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();