@caupulican/pi-adaptative 0.81.38 → 0.81.39

package/dist/core/tools/task-steps.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { addTaskStep, clearTaskSteps, compactTaskSteps, createTaskStepsState, formatTaskSteps, MAX_TASK_STEPS, setTaskSteps, updateTaskStep, } from "../tasks/task-state.js";
+import { addTaskStep, clearTaskSteps, compactTaskSteps, createTaskStepsState, findOpenDuplicateStep, formatTaskSteps, hasUnverifiedCompletedStep, MAX_TASK_STEPS, resolveTaskStepSelector, setTaskSteps, updateTaskStep, } from "../tasks/task-state.js";
 const statusSchema = Type.Union([
     Type.Literal("pending"),
     Type.Literal("in_progress"),
@@ -61,9 +61,31 @@ function counts(state) {
     return {
         stepCount: state.steps.length,
         openStepCount,
-        verificationNudgeNeeded: state.steps.some((step) => step.status === "completed" && step.evidence.length === 0),
+        verificationNudgeNeeded: hasUnverifiedCompletedStep(state),
     };
 }
+/** Ids (from `resultSteps`, index-aligned with `inputs`) whose status was set explicitly by the caller. */
+function explicitStatusStepIds(inputs, resultSteps) {
+    const ids = new Set();
+    inputs.forEach((stepInput, index) => {
+        if (stepInput.status !== undefined) {
+            const id = resultSteps[index]?.id;
+            if (id)
+                ids.add(id);
+        }
+    });
+    return ids;
+}
+/**
+ * Steps that were in_progress before this call and are pending after, excluding any step whose
+ * new status was set explicitly by the caller (an explicit change is not a "silent" demotion).
+ */
+function computeDemotedStepIds(before, after, excludeIds) {
+    const beforeActiveIds = new Set(before.steps.filter((step) => step.status === "in_progress").map((step) => step.id));
+    return after.steps
+        .filter((step) => beforeActiveIds.has(step.id) && step.status === "pending" && !excludeIds.has(step.id))
+        .map((step) => step.id);
+}
 function errorResult(action, error, state) {
     return {
         content: [{ type: "text", text: `task_steps ${action} failed: ${error}` }],
@@ -89,25 +111,36 @@ export function createTaskStepsToolDefinition(deps) {
         async execute(_toolCallId, input) {
             const timestamp = now();
             const current = deps.getTaskStepsState();
-            let state = current ?? createTaskStepsState(timestamp);
+            const before = current ?? createTaskStepsState(timestamp);
+            let state = before;
+            let duplicateStepId;
+            let demotedStepIds = [];
             try {
                 switch (input.action) {
                     case "set":
                         if (!input.steps)
                             return errorResult(input.action, "set requires steps[].", current);
                         state = setTaskSteps(state, input.steps, timestamp);
+                        demotedStepIds = computeDemotedStepIds(before, state, explicitStatusStepIds(input.steps, state.steps));
                         break;
                     case "intake":
                         if (!input.steps)
                             return errorResult(input.action, "intake requires a complete steps[] list.", current);
                         state = setTaskSteps(state, input.steps, timestamp);
+                        demotedStepIds = computeDemotedStepIds(before, state, explicitStatusStepIds(input.steps, state.steps));
                         break;
                     case "add":
                         state = addTaskStep(state, toTaskStepInput(input), timestamp);
+                        if (state === before) {
+                            // The reducer returned the unchanged state: an open step already carries this
+                            // content, so nothing was created. Name the existing step in the response.
+                            duplicateStepId = findOpenDuplicateStep(before.steps, input.content ?? "")?.id;
+                        }
                         break;
-                    case "update":
+                    case "update": {
                         if (!input.id?.trim())
                             return errorResult(input.action, "update requires id or a unique selector.", current);
+                        const selected = resolveTaskStepSelector(before.steps, input.id);
                         state = updateTaskStep(state, input.id, {
                             content: input.content,
                             activeForm: input.activeForm,
@@ -117,7 +150,11 @@ export function createTaskStepsToolDefinition(deps) {
                             note: input.note,
                             evidence: input.evidence,
                         }, timestamp);
+                        // Exclude the explicitly targeted step: its own status change was requested by
+                        // the caller, so it is never a "silent" demotion even if it moved to pending.
+                        demotedStepIds = computeDemotedStepIds(before, state, new Set([selected.id]));
                         break;
+                    }
                     case "clear":
                         state = clearTaskSteps(state, timestamp);
                         break;
@@ -129,25 +166,43 @@ export function createTaskStepsToolDefinition(deps) {
                             state = compactTaskSteps(state, timestamp);
                         break;
                 }
-                const mutated = input.action !== "list" || input.clearCompleted === true;
+                const isNoopDuplicateAdd = input.action === "add" && state === before;
+                const mutated = (input.action !== "list" || input.clearCompleted === true) && !isNoopDuplicateAdd;
                 if (mutated)
                     deps.saveTaskStepsState(state);
+                const stateCounts = counts(state);
+                const noticeLines = [];
+                if (duplicateStepId) {
+                    noticeLines.push(`Duplicate open step ignored; existing ${duplicateStepId} already tracks this content.`);
+                }
+                if (demotedStepIds.length > 0) {
+                    noticeLines.push(`Demoted to pending because another step became active: ${demotedStepIds.join(", ")}.`);
+                }
+                if (stateCounts.verificationNudgeNeeded) {
+                    noticeLines.push("Reminder: a completed step has no evidence attached; attach evidence via update before treating it as verified.");
+                }
+                const notices = noticeLines.length > 0 ? `\n${noticeLines.join("\n")}` : "";
+                const headerAction = input.action === "list"
+                    ? ""
+                    : `task_steps ${input.action} ${duplicateStepId ? "ignored (duplicate)" : "recorded"}.\n`;
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `${input.action === "list" ? "" : `task_steps ${input.action} recorded.\n`}${formatTaskSteps(state, {
+                            text: `${headerAction}${formatTaskSteps(state, {
                                 includeTerminal: input.showCompleted,
                                 maxItems: input.maxItems,
-                            })}`,
+                            })}${notices}`,
                         },
                     ],
                     details: {
                         action: input.action,
                         applied: true,
                         state,
-                        ...counts(state),
+                        ...stateCounts,
                         showCompleted: input.showCompleted,
+                        duplicateOfStepId: duplicateStepId,
+                        demotedStepIds: demotedStepIds.length > 0 ? demotedStepIds : undefined,
                     },
                 };
             }

package/dist/core/tools/task-steps.js.map

@@ -1 +1 @@
-{"version":3,"file":"task-steps.js","sourceRoot":"","sources":["../../../src/core/tools/task-steps.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Static, Type } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport {\n\taddTaskStep,\n\tclearTaskSteps,\n\tcompactTaskSteps,\n\tcreateTaskStepsState,\n\tformatTaskSteps,\n\tMAX_TASK_STEPS,\n\tsetTaskSteps,\n\ttype TaskStepInput,\n\ttype TaskStepsState,\n\tupdateTaskStep,\n} from \"../tasks/task-state.ts\";\n\nconst statusSchema = Type.Union([\n\tType.Literal(\"pending\"),\n\tType.Literal(\"in_progress\"),\n\tType.Literal(\"completed\"),\n\tType.Literal(\"blocked\"),\n\tType.Literal(\"cancelled\"),\n]);\n\nconst prioritySchema = Type.Union([Type.Literal(\"low\"), Type.Literal(\"normal\"), Type.Literal(\"high\")]);\n\nconst stepInputSchema = Type.Object(\n\t{\n\t\tcontent: Type.String({ minLength: 1, maxLength: 2_000, description: \"Imperative task step text.\" }),\n\t\tactiveForm: Type.Optional(\n\t\t\tType.String({ minLength: 1, maxLength: 2_000, description: \"Short present-progress label for active UI.\" }),\n\t\t),\n\t\tstatus: Type.Optional(statusSchema),\n\t\tpriority: Type.Optional(prioritySchema),\n\t\towner: Type.Optional(Type.String({ maxLength: 200 })),\n\t\tnote: Type.Optional(Type.String({ maxLength: 4_000 })),\n\t\tevidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), { maxItems: 32 })),\n\t},\n\t{ additionalProperties: false },\n);\n\nconst taskStepsSchema = Type.Object(\n\t{\n\t\taction: Type.Union(\n\t\t\t[\n\t\t\t\tType.Literal(\"set\"),\n\t\t\t\tType.Literal(\"add\"),\n\t\t\t\tType.Literal(\"update\"),\n\t\t\t\tType.Literal(\"list\"),\n\t\t\t\tType.Literal(\"clear\"),\n\t\t\t\tType.Literal(\"compact\"),\n\t\t\t\tType.Literal(\"intake\"),\n\t\t\t],\n\t\t\t{ description: \"Checklist action. Use list to read without mutation.\" },\n\t\t),\n\t\tsteps: Type.Optional(\n\t\t\tType.Array(stepInputSchema, {\n\t\t\t\tmaxItems: MAX_TASK_STEPS,\n\t\t\t\tdescription: \"Complete replacement list for set/intake. Intake preserves every supplied item in order.\",\n\t\t\t}),\n\t\t),\n\t\tid: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"For update: current/active, exact step id, unique id prefix, or unique content selector.\",\n\t\t\t}),\n\t\t),\n\t\tcontent: Type.Optional(Type.String({ minLength: 1, maxLength: 2_000 })),\n\t\tactiveForm: Type.Optional(Type.String({ maxLength: 2_000 })),\n\t\tstatus: Type.Optional(statusSchema),\n\t\tpriority: Type.Optional(prioritySchema),\n\t\towner: Type.Optional(Type.String({ maxLength: 200 })),\n\t\tnote: Type.Optional(Type.String({ maxLength: 4_000 })),\n\t\tevidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), { maxItems: 32 })),\n\t\tclearCompleted: Type.Optional(\n\t\t\tType.Boolean({ description: \"For list: compact completed and cancelled steps before rendering.\" }),\n\t\t),\n\t\tshowCompleted: Type.Optional(Type.Boolean({ description: \"Include completed and cancelled steps in output.\" })),\n\t\tmaxItems: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_TASK_STEPS })),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport type TaskStepsToolInput = Static<typeof taskStepsSchema>;\nexport type TaskStepsAction = TaskStepsToolInput[\"action\"];\n\nexport interface TaskStepsToolDetails {\n\taction: TaskStepsAction;\n\tapplied: boolean;\n\terror?: string;\n\tstate?: TaskStepsState;\n\tstepCount?: number;\n\topenStepCount?: number;\n\tverificationNudgeNeeded?: boolean;\n\tshowCompleted?: boolean;\n}\n\nexport interface TaskStepsToolDependencies {\n\tgetTaskStepsState: () => TaskStepsState | undefined;\n\tsaveTaskStepsState: (state: TaskStepsState) => void;\n\tnow?: () => string;\n}\n\nfunction toTaskStepInput(input: TaskStepsToolInput): TaskStepInput {\n\treturn {\n\t\tcontent: input.content ?? \"\",\n\t\tactiveForm: input.activeForm,\n\t\tstatus: input.status,\n\t\tpriority: input.priority,\n\t\towner: input.owner,\n\t\tnote: input.note,\n\t\tevidence: input.evidence,\n\t};\n}\n\nfunction counts(\n\tstate: TaskStepsState,\n): Pick<TaskStepsToolDetails, \"stepCount\" | \"openStepCount\" | \"verificationNudgeNeeded\"> {\n\tconst openStepCount = state.steps.filter(\n\t\t(step) => step.status !== \"completed\" && step.status !== \"cancelled\",\n\t).length;\n\treturn {\n\t\tstepCount: state.steps.length,\n\t\topenStepCount,\n\t\tverificationNudgeNeeded: state.steps.some((step) => step.status === \"completed\" && step.evidence.length === 0),\n\t};\n}\n\nfunction errorResult(action: TaskStepsAction, error: string, state?: TaskStepsState) {\n\treturn {\n\t\tcontent: [{ type: \"text\" as const, text: `task_steps ${action} failed: ${error}` }],\n\t\tdetails: { action, applied: false, error, state, ...(state ? counts(state) : {}) } satisfies TaskStepsToolDetails,\n\t};\n}\n\nexport function createTaskStepsToolDefinition(deps: TaskStepsToolDependencies): ToolDefinition {\n\tconst now = deps.now ?? (() => new Date().toISOString());\n\treturn {\n\t\tname: \"task_steps\",\n\t\tlabel: \"Task Steps\",\n\t\tdescription:\n\t\t\t\"Maintain the current session's native ordered checklist for multi-step work. Supports pending, in_progress, completed, blocked, and cancelled steps with notes and evidence. State is isolated to and persisted with the active session; use native goal for durable outcome requirements and native delegate/delegate_status for background workers.\",\n\t\tpromptSnippet: \"Track and drain multi-step work with a native session checklist.\",\n\t\tpromptGuidelines: [\n\t\t\t\"Use task_steps for complex work, explicit task-tracking requests, and harness/self-improvement work; keep exactly one step in_progress while actively working.\",\n\t\t\t\"Always address the first open task step before unrelated work: start it, complete/block/cancel it with evidence, ask one clarifying question, or explicitly defer or reorder it.\",\n\t\t\t\"Mark steps completed as soon as evidence is gathered, and attach concise evidence or a blocker reason through update.\",\n\t\t\t\"Use action=intake with a complete steps array when preserving a raw multi-item dump; retain every item and do not silently drop entries.\",\n\t\t\t\"Drain task_steps before final responses: leave no stale in_progress step, and explicitly discuss or defer remaining pending or blocked work.\",\n\t\t\t\"Use goal for the durable goal ledger and delegate/delegate_status for worker lanes; do not emulate background execution inside task_steps.\",\n\t\t],\n\t\tparameters: taskStepsSchema,\n\t\tasync execute(_toolCallId, input: TaskStepsToolInput) {\n\t\t\tconst timestamp = now();\n\t\t\tconst current = deps.getTaskStepsState();\n\t\t\tlet state = current ?? createTaskStepsState(timestamp);\n\t\t\ttry {\n\t\t\t\tswitch (input.action) {\n\t\t\t\t\tcase \"set\":\n\t\t\t\t\t\tif (!input.steps) return errorResult(input.action, \"set requires steps[].\", current);\n\t\t\t\t\t\tstate = setTaskSteps(state, input.steps, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"intake\":\n\t\t\t\t\t\tif (!input.steps)\n\t\t\t\t\t\t\treturn errorResult(input.action, \"intake requires a complete steps[] list.\", current);\n\t\t\t\t\t\tstate = setTaskSteps(state, input.steps, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"add\":\n\t\t\t\t\t\tstate = addTaskStep(state, toTaskStepInput(input), timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"update\":\n\t\t\t\t\t\tif (!input.id?.trim())\n\t\t\t\t\t\t\treturn errorResult(input.action, \"update requires id or a unique selector.\", current);\n\t\t\t\t\t\tstate = updateTaskStep(\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tinput.id,\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tcontent: input.content,\n\t\t\t\t\t\t\t\tactiveForm: input.activeForm,\n\t\t\t\t\t\t\t\tstatus: input.status,\n\t\t\t\t\t\t\t\tpriority: input.priority,\n\t\t\t\t\t\t\t\towner: input.owner,\n\t\t\t\t\t\t\t\tnote: input.note,\n\t\t\t\t\t\t\t\tevidence: input.evidence,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\ttimestamp,\n\t\t\t\t\t\t);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"clear\":\n\t\t\t\t\t\tstate = clearTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"compact\":\n\t\t\t\t\t\tstate = compactTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"list\":\n\t\t\t\t\t\tif (input.clearCompleted) state = compactTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t}\n\n\t\t\t\tconst mutated = input.action !== \"list\" || input.clearCompleted === true;\n\t\t\t\tif (mutated) deps.saveTaskStepsState(state);\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `${input.action === \"list\" ? \"\" : `task_steps ${input.action} recorded.\\n`}${formatTaskSteps(\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\t\tincludeTerminal: input.showCompleted,\n\t\t\t\t\t\t\t\t\tmaxItems: input.maxItems,\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t)}`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\taction: input.action,\n\t\t\t\t\t\tapplied: true,\n\t\t\t\t\t\tstate,\n\t\t\t\t\t\t...counts(state),\n\t\t\t\t\t\tshowCompleted: input.showCompleted,\n\t\t\t\t\t} satisfies TaskStepsToolDetails,\n\t\t\t\t};\n\t\t\t} catch (error) {\n\t\t\t\treturn errorResult(input.action, error instanceof Error ? error.message : String(error), current);\n\t\t\t}\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"task-steps.js","sourceRoot":"","sources":["../../../src/core/tools/task-steps.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Static, Type } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport {\n\taddTaskStep,\n\tclearTaskSteps,\n\tcompactTaskSteps,\n\tcreateTaskStepsState,\n\tfindOpenDuplicateStep,\n\tformatTaskSteps,\n\thasUnverifiedCompletedStep,\n\tMAX_TASK_STEPS,\n\tresolveTaskStepSelector,\n\tsetTaskSteps,\n\ttype TaskStep,\n\ttype TaskStepInput,\n\ttype TaskStepsState,\n\tupdateTaskStep,\n} from \"../tasks/task-state.ts\";\n\nconst statusSchema = Type.Union([\n\tType.Literal(\"pending\"),\n\tType.Literal(\"in_progress\"),\n\tType.Literal(\"completed\"),\n\tType.Literal(\"blocked\"),\n\tType.Literal(\"cancelled\"),\n]);\n\nconst prioritySchema = Type.Union([Type.Literal(\"low\"), Type.Literal(\"normal\"), Type.Literal(\"high\")]);\n\nconst stepInputSchema = Type.Object(\n\t{\n\t\tcontent: Type.String({ minLength: 1, maxLength: 2_000, description: \"Imperative task step text.\" }),\n\t\tactiveForm: Type.Optional(\n\t\t\tType.String({ minLength: 1, maxLength: 2_000, description: \"Short present-progress label for active UI.\" }),\n\t\t),\n\t\tstatus: Type.Optional(statusSchema),\n\t\tpriority: Type.Optional(prioritySchema),\n\t\towner: Type.Optional(Type.String({ maxLength: 200 })),\n\t\tnote: Type.Optional(Type.String({ maxLength: 4_000 })),\n\t\tevidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), { maxItems: 32 })),\n\t},\n\t{ additionalProperties: false },\n);\n\nconst taskStepsSchema = Type.Object(\n\t{\n\t\taction: Type.Union(\n\t\t\t[\n\t\t\t\tType.Literal(\"set\"),\n\t\t\t\tType.Literal(\"add\"),\n\t\t\t\tType.Literal(\"update\"),\n\t\t\t\tType.Literal(\"list\"),\n\t\t\t\tType.Literal(\"clear\"),\n\t\t\t\tType.Literal(\"compact\"),\n\t\t\t\tType.Literal(\"intake\"),\n\t\t\t],\n\t\t\t{ description: \"Checklist action. Use list to read without mutation.\" },\n\t\t),\n\t\tsteps: Type.Optional(\n\t\t\tType.Array(stepInputSchema, {\n\t\t\t\tmaxItems: MAX_TASK_STEPS,\n\t\t\t\tdescription: \"Complete replacement list for set/intake. Intake preserves every supplied item in order.\",\n\t\t\t}),\n\t\t),\n\t\tid: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"For update: current/active, exact step id, unique id prefix, or unique content selector.\",\n\t\t\t}),\n\t\t),\n\t\tcontent: Type.Optional(Type.String({ minLength: 1, maxLength: 2_000 })),\n\t\tactiveForm: Type.Optional(Type.String({ maxLength: 2_000 })),\n\t\tstatus: Type.Optional(statusSchema),\n\t\tpriority: Type.Optional(prioritySchema),\n\t\towner: Type.Optional(Type.String({ maxLength: 200 })),\n\t\tnote: Type.Optional(Type.String({ maxLength: 4_000 })),\n\t\tevidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), { maxItems: 32 })),\n\t\tclearCompleted: Type.Optional(\n\t\t\tType.Boolean({ description: \"For list: compact completed and cancelled steps before rendering.\" }),\n\t\t),\n\t\tshowCompleted: Type.Optional(Type.Boolean({ description: \"Include completed and cancelled steps in output.\" })),\n\t\tmaxItems: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_TASK_STEPS })),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport type TaskStepsToolInput = Static<typeof taskStepsSchema>;\nexport type TaskStepsAction = TaskStepsToolInput[\"action\"];\n\nexport interface TaskStepsToolDetails {\n\taction: TaskStepsAction;\n\tapplied: boolean;\n\terror?: string;\n\tstate?: TaskStepsState;\n\tstepCount?: number;\n\topenStepCount?: number;\n\tverificationNudgeNeeded?: boolean;\n\tshowCompleted?: boolean;\n\t/** Set when `add` was a no-op because an open step already carries this content. */\n\tduplicateOfStepId?: string;\n\t/** Step ids silently demoted to pending because another step became active in this call. */\n\tdemotedStepIds?: readonly string[];\n}\n\nexport interface TaskStepsToolDependencies {\n\tgetTaskStepsState: () => TaskStepsState | undefined;\n\tsaveTaskStepsState: (state: TaskStepsState) => void;\n\tnow?: () => string;\n}\n\nfunction toTaskStepInput(input: TaskStepsToolInput): TaskStepInput {\n\treturn {\n\t\tcontent: input.content ?? \"\",\n\t\tactiveForm: input.activeForm,\n\t\tstatus: input.status,\n\t\tpriority: input.priority,\n\t\towner: input.owner,\n\t\tnote: input.note,\n\t\tevidence: input.evidence,\n\t};\n}\n\nfunction counts(\n\tstate: TaskStepsState,\n): Pick<TaskStepsToolDetails, \"stepCount\" | \"openStepCount\" | \"verificationNudgeNeeded\"> {\n\tconst openStepCount = state.steps.filter(\n\t\t(step) => step.status !== \"completed\" && step.status !== \"cancelled\",\n\t).length;\n\treturn {\n\t\tstepCount: state.steps.length,\n\t\topenStepCount,\n\t\tverificationNudgeNeeded: hasUnverifiedCompletedStep(state),\n\t};\n}\n\n/** Ids (from `resultSteps`, index-aligned with `inputs`) whose status was set explicitly by the caller. */\nfunction explicitStatusStepIds(inputs: readonly TaskStepInput[], resultSteps: readonly TaskStep[]): Set<string> {\n\tconst ids = new Set<string>();\n\tinputs.forEach((stepInput, index) => {\n\t\tif (stepInput.status !== undefined) {\n\t\t\tconst id = resultSteps[index]?.id;\n\t\t\tif (id) ids.add(id);\n\t\t}\n\t});\n\treturn ids;\n}\n\n/**\n * Steps that were in_progress before this call and are pending after, excluding any step whose\n * new status was set explicitly by the caller (an explicit change is not a \"silent\" demotion).\n */\nfunction computeDemotedStepIds(\n\tbefore: TaskStepsState,\n\tafter: TaskStepsState,\n\texcludeIds: ReadonlySet<string>,\n): string[] {\n\tconst beforeActiveIds = new Set(before.steps.filter((step) => step.status === \"in_progress\").map((step) => step.id));\n\treturn after.steps\n\t\t.filter((step) => beforeActiveIds.has(step.id) && step.status === \"pending\" && !excludeIds.has(step.id))\n\t\t.map((step) => step.id);\n}\n\nfunction errorResult(action: TaskStepsAction, error: string, state?: TaskStepsState) {\n\treturn {\n\t\tcontent: [{ type: \"text\" as const, text: `task_steps ${action} failed: ${error}` }],\n\t\tdetails: { action, applied: false, error, state, ...(state ? counts(state) : {}) } satisfies TaskStepsToolDetails,\n\t};\n}\n\nexport function createTaskStepsToolDefinition(deps: TaskStepsToolDependencies): ToolDefinition {\n\tconst now = deps.now ?? (() => new Date().toISOString());\n\treturn {\n\t\tname: \"task_steps\",\n\t\tlabel: \"Task Steps\",\n\t\tdescription:\n\t\t\t\"Maintain the current session's native ordered checklist for multi-step work. Supports pending, in_progress, completed, blocked, and cancelled steps with notes and evidence. State is isolated to and persisted with the active session; use native goal for durable outcome requirements and native delegate/delegate_status for background workers.\",\n\t\tpromptSnippet: \"Track and drain multi-step work with a native session checklist.\",\n\t\tpromptGuidelines: [\n\t\t\t\"Use task_steps for complex work, explicit task-tracking requests, and harness/self-improvement work; keep exactly one step in_progress while actively working.\",\n\t\t\t\"Always address the first open task step before unrelated work: start it, complete/block/cancel it with evidence, ask one clarifying question, or explicitly defer or reorder it.\",\n\t\t\t\"Mark steps completed as soon as evidence is gathered, and attach concise evidence or a blocker reason through update.\",\n\t\t\t\"Use action=intake with a complete steps array when preserving a raw multi-item dump; retain every item and do not silently drop entries.\",\n\t\t\t\"Drain task_steps before final responses: leave no stale in_progress step, and explicitly discuss or defer remaining pending or blocked work.\",\n\t\t\t\"Use goal for the durable goal ledger and delegate/delegate_status for worker lanes; do not emulate background execution inside task_steps.\",\n\t\t],\n\t\tparameters: taskStepsSchema,\n\t\tasync execute(_toolCallId, input: TaskStepsToolInput) {\n\t\t\tconst timestamp = now();\n\t\t\tconst current = deps.getTaskStepsState();\n\t\t\tconst before = current ?? createTaskStepsState(timestamp);\n\t\t\tlet state = before;\n\t\t\tlet duplicateStepId: string | undefined;\n\t\t\tlet demotedStepIds: readonly string[] = [];\n\t\t\ttry {\n\t\t\t\tswitch (input.action) {\n\t\t\t\t\tcase \"set\":\n\t\t\t\t\t\tif (!input.steps) return errorResult(input.action, \"set requires steps[].\", current);\n\t\t\t\t\t\tstate = setTaskSteps(state, input.steps, timestamp);\n\t\t\t\t\t\tdemotedStepIds = computeDemotedStepIds(\n\t\t\t\t\t\t\tbefore,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\texplicitStatusStepIds(input.steps, state.steps),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"intake\":\n\t\t\t\t\t\tif (!input.steps)\n\t\t\t\t\t\t\treturn errorResult(input.action, \"intake requires a complete steps[] list.\", current);\n\t\t\t\t\t\tstate = setTaskSteps(state, input.steps, timestamp);\n\t\t\t\t\t\tdemotedStepIds = computeDemotedStepIds(\n\t\t\t\t\t\t\tbefore,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\texplicitStatusStepIds(input.steps, state.steps),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"add\":\n\t\t\t\t\t\tstate = addTaskStep(state, toTaskStepInput(input), timestamp);\n\t\t\t\t\t\tif (state === before) {\n\t\t\t\t\t\t\t// The reducer returned the unchanged state: an open step already carries this\n\t\t\t\t\t\t\t// content, so nothing was created. Name the existing step in the response.\n\t\t\t\t\t\t\tduplicateStepId = findOpenDuplicateStep(before.steps, input.content ?? \"\")?.id;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"update\": {\n\t\t\t\t\t\tif (!input.id?.trim())\n\t\t\t\t\t\t\treturn errorResult(input.action, \"update requires id or a unique selector.\", current);\n\t\t\t\t\t\tconst selected = resolveTaskStepSelector(before.steps, input.id);\n\t\t\t\t\t\tstate = updateTaskStep(\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tinput.id,\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tcontent: input.content,\n\t\t\t\t\t\t\t\tactiveForm: input.activeForm,\n\t\t\t\t\t\t\t\tstatus: input.status,\n\t\t\t\t\t\t\t\tpriority: input.priority,\n\t\t\t\t\t\t\t\towner: input.owner,\n\t\t\t\t\t\t\t\tnote: input.note,\n\t\t\t\t\t\t\t\tevidence: input.evidence,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\ttimestamp,\n\t\t\t\t\t\t);\n\t\t\t\t\t\t// Exclude the explicitly targeted step: its own status change was requested by\n\t\t\t\t\t\t// the caller, so it is never a \"silent\" demotion even if it moved to pending.\n\t\t\t\t\t\tdemotedStepIds = computeDemotedStepIds(before, state, new Set([selected.id]));\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"clear\":\n\t\t\t\t\t\tstate = clearTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"compact\":\n\t\t\t\t\t\tstate = compactTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"list\":\n\t\t\t\t\t\tif (input.clearCompleted) state = compactTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t}\n\n\t\t\t\tconst isNoopDuplicateAdd = input.action === \"add\" && state === before;\n\t\t\t\tconst mutated = (input.action !== \"list\" || input.clearCompleted === true) && !isNoopDuplicateAdd;\n\t\t\t\tif (mutated) deps.saveTaskStepsState(state);\n\n\t\t\t\tconst stateCounts = counts(state);\n\t\t\t\tconst noticeLines: string[] = [];\n\t\t\t\tif (duplicateStepId) {\n\t\t\t\t\tnoticeLines.push(\n\t\t\t\t\t\t`Duplicate open step ignored; existing ${duplicateStepId} already tracks this content.`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tif (demotedStepIds.length > 0) {\n\t\t\t\t\tnoticeLines.push(`Demoted to pending because another step became active: ${demotedStepIds.join(\", \")}.`);\n\t\t\t\t}\n\t\t\t\tif (stateCounts.verificationNudgeNeeded) {\n\t\t\t\t\tnoticeLines.push(\n\t\t\t\t\t\t\"Reminder: a completed step has no evidence attached; attach evidence via update before treating it as verified.\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst notices = noticeLines.length > 0 ? `\\n${noticeLines.join(\"\\n\")}` : \"\";\n\n\t\t\t\tconst headerAction =\n\t\t\t\t\tinput.action === \"list\"\n\t\t\t\t\t\t? \"\"\n\t\t\t\t\t\t: `task_steps ${input.action} ${duplicateStepId ? \"ignored (duplicate)\" : \"recorded\"}.\\n`;\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `${headerAction}${formatTaskSteps(state, {\n\t\t\t\t\t\t\t\tincludeTerminal: input.showCompleted,\n\t\t\t\t\t\t\t\tmaxItems: input.maxItems,\n\t\t\t\t\t\t\t})}${notices}`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\taction: input.action,\n\t\t\t\t\t\tapplied: true,\n\t\t\t\t\t\tstate,\n\t\t\t\t\t\t...stateCounts,\n\t\t\t\t\t\tshowCompleted: input.showCompleted,\n\t\t\t\t\t\tduplicateOfStepId: duplicateStepId,\n\t\t\t\t\t\tdemotedStepIds: demotedStepIds.length > 0 ? demotedStepIds : undefined,\n\t\t\t\t\t} satisfies TaskStepsToolDetails,\n\t\t\t\t};\n\t\t\t} catch (error) {\n\t\t\t\treturn errorResult(input.action, error instanceof Error ? error.message : String(error), current);\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/core/tools/tmux-dispatch.d.ts

@@ -0,0 +1,86 @@
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+import type { LaneWorkerRefusal } from "../model-capability.ts";
+/**
+ * Dependencies for {@link dispatchTmuxWorker}, injected from the construction site
+ * (`RuntimeBuilder`) so the adapter itself stays a small, unit-testable, faux-tool-driven module
+ * with no direct dependency on `AgentSession`/`ExtensionRunner`/`BackgroundLaneController`.
+ */
+export interface TmuxDispatchDeps {
+    /** Look up a registered tool by name -- the SAME seam the model's own tool calls resolve
+     * through (`AgentSession.getToolDefinition` -> `RuntimeBuilder.getToolDefinition`). `undefined`
+     * when the tmux extension is not loaded in this session -- an honest, non-fatal skip, not a
+     * crash and not a silent no-op. */
+    getToolDefinition: (name: string) => ToolDefinition | undefined;
+    /** Build a fresh, non-turn-bound `ExtensionContext` for this call
+     * (`ExtensionRunner.createContext()`) -- safe to invoke from the goal/idle path, outside any
+     * live model turn. */
+    createExtensionContext: () => ExtensionContext;
+    /**
+     * Resolve the tmux extension's own caller-chosen lane id (reconstructed below from the
+     * `fire_task` result's `details.job`) to the host's internal `LaneTracker` id -- the id
+     * `Requirement.boundLaneId` / `inFlightGoalLaneIds` actually match
+     * (`BackgroundLaneController.resolveManagedLaneId`). A deterministic keyed lookup against the
+     * dispatch this same call just minted, NOT a racy `getLaneRecords()` diff.
+     */
+    resolveManagedLaneId: (callerLaneId: string) => string | undefined;
+    /** Active goal id, threaded onto the `fire_task` call so the dispatched lane is goal-tagged
+     * (`ManagedLaneEvent.goalId`) -- `undefined` when no goal is active (dispatch still proceeds;
+     * the resulting lane is simply untagged). */
+    getGoalId: () => string | undefined;
+    /**
+     * Worktree-sync lane-first dispatch (opt-in -- wired ONLY inside `runtime-builder.ts`'s
+     * `worktreeSync.enabled` block, via the engine's `createLane`): when present, `dispatchTmuxWorker`
+     * creates a fresh worktree-sync lane for this requirement BEFORE issuing any `fire_task` call, so
+     * a creation refusal aborts cleanly before any tmux/pane side effect ever runs -- never a
+     * half-made lane, never a fabricated worktree. On success the dispatched agent's `cwd` is the new
+     * lane worktree and it carries `worktreeLane` (threaded to the tmux extension's launch profile --
+     * see `dispatch-grant.ts`'s `buildLaunchProfileFlags`). Absent dep -> existing byte-identical
+     * `params.agents` (no `cwd`/`worktreeLane`), exactly as before this field existed.
+     */
+    createLaneWorktree?: (args: {
+        goalId?: string;
+        requirementId: string;
+    }) => Promise<{
+        laneKey: string;
+        worktreePath: string;
+    } | {
+        skipReason: string;
+    }>;
+    /**
+     * Lane-worker capability eligibility (opt-in -- wired only from `runtime-builder.ts`, backed by
+     * `AgentSession.getLaneWorkerRefusal`): checked FIRST, before `createLaneWorktree`, so an
+     * ineligible model's dispatch is refused before any lane/pane side effect ever runs. This is the
+     * parent's best-effort check only -- the dispatched child session refuses authoritatively at its
+     * own startup (main.ts) regardless of what the parent decides here. Absent dep -> no capability
+     * check runs, byte-identical to before this field existed.
+     */
+    evaluateWorkerLaneRefusal?: () => LaneWorkerRefusal | undefined;
+}
+/**
+ * Classify a `fire_task` launch failure into an honest, stable skip reason. For an UNATTENDED
+ * caller (`ctx.hasUI === false`, always true from the goal/idle path) `authorizeLaunch`'s ONLY
+ * refusal throw is the no-standing-grant error (`tmux-agent-manager/index.ts`'s `authorizeLaunch`,
+ * message containing the stable phrase "no standing grant") -- matched here by substring since the
+ * extension throws a plain `Error`, not a tagged error code (documented follow-up hardening, not
+ * blocking). Every other thrown error (a bad jobId, a live session-name collision,
+ * an environment failure) maps onto the generic `"tmux_dispatch_failed"` -- still surfaced through
+ * the existing `dispatchSkipReason` contract, never a crash and never a silently-ignored failure.
+ */
+export declare function classifyDispatchError(error: unknown): string;
+/**
+ * Structurally dispatch ONE persistent tmux worker agent for a single goal requirement, by
+ * invoking the SAME `tmux_agent_manager` `fire_task` tool call the model itself would make. Core
+ * -- not model discretion -- decides WHEN this fires (the goal tool's `dispatchTarget:"tmux"`
+ * routing gates the call); the launch itself always still goes through the extension's own
+ * grant-gated `authorizeLaunch`, so an ungranted unattended call is honestly refused here (never a
+ * silent launch, never a fabricated laneId) and the refusal is surfaced through the existing
+ * `dispatchSkipReason` contract on the goal tool's response.
+ */
+export declare function dispatchTmuxWorker(deps: TmuxDispatchDeps, args: {
+    requirementId: string;
+    instructions: string;
+}): Promise<{
+    laneId?: string;
+    skipReason?: string;
+}>;
+//# sourceMappingURL=tmux-dispatch.d.ts.map

package/dist/core/tools/tmux-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux-dispatch.d.ts","sourceRoot":"","sources":["../../../src/core/tools/tmux-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;uCAGmC;IACnC,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;IAChE;;0BAEsB;IACtB,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;IAC/C;;;;;;OAMG;IACH,oBAAoB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACnE;;iDAE6C;IAC7C,SAAS,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACpC;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACtB,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF;;;;;;;OAOG;IACH,yBAAyB,CAAC,EAAE,MAAM,iBAAiB,GAAG,SAAS,CAAC;CAChE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG5D;AASD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAqEnD","sourcesContent":["import type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\nimport type { LaneWorkerRefusal } from \"../model-capability.ts\";\n\n/**\n * Dependencies for {@link dispatchTmuxWorker}, injected from the construction site\n * (`RuntimeBuilder`) so the adapter itself stays a small, unit-testable, faux-tool-driven module\n * with no direct dependency on `AgentSession`/`ExtensionRunner`/`BackgroundLaneController`.\n */\nexport interface TmuxDispatchDeps {\n\t/** Look up a registered tool by name -- the SAME seam the model's own tool calls resolve\n\t * through (`AgentSession.getToolDefinition` -> `RuntimeBuilder.getToolDefinition`). `undefined`\n\t * when the tmux extension is not loaded in this session -- an honest, non-fatal skip, not a\n\t * crash and not a silent no-op. */\n\tgetToolDefinition: (name: string) => ToolDefinition | undefined;\n\t/** Build a fresh, non-turn-bound `ExtensionContext` for this call\n\t * (`ExtensionRunner.createContext()`) -- safe to invoke from the goal/idle path, outside any\n\t * live model turn. */\n\tcreateExtensionContext: () => ExtensionContext;\n\t/**\n\t * Resolve the tmux extension's own caller-chosen lane id (reconstructed below from the\n\t * `fire_task` result's `details.job`) to the host's internal `LaneTracker` id -- the id\n\t * `Requirement.boundLaneId` / `inFlightGoalLaneIds` actually match\n\t * (`BackgroundLaneController.resolveManagedLaneId`). A deterministic keyed lookup against the\n\t * dispatch this same call just minted, NOT a racy `getLaneRecords()` diff.\n\t */\n\tresolveManagedLaneId: (callerLaneId: string) => string | undefined;\n\t/** Active goal id, threaded onto the `fire_task` call so the dispatched lane is goal-tagged\n\t * (`ManagedLaneEvent.goalId`) -- `undefined` when no goal is active (dispatch still proceeds;\n\t * the resulting lane is simply untagged). */\n\tgetGoalId: () => string | undefined;\n\t/**\n\t * Worktree-sync lane-first dispatch (opt-in -- wired ONLY inside `runtime-builder.ts`'s\n\t * `worktreeSync.enabled` block, via the engine's `createLane`): when present, `dispatchTmuxWorker`\n\t * creates a fresh worktree-sync lane for this requirement BEFORE issuing any `fire_task` call, so\n\t * a creation refusal aborts cleanly before any tmux/pane side effect ever runs -- never a\n\t * half-made lane, never a fabricated worktree. On success the dispatched agent's `cwd` is the new\n\t * lane worktree and it carries `worktreeLane` (threaded to the tmux extension's launch profile --\n\t * see `dispatch-grant.ts`'s `buildLaunchProfileFlags`). Absent dep -> existing byte-identical\n\t * `params.agents` (no `cwd`/`worktreeLane`), exactly as before this field existed.\n\t */\n\tcreateLaneWorktree?: (args: {\n\t\tgoalId?: string;\n\t\trequirementId: string;\n\t}) => Promise<{ laneKey: string; worktreePath: string } | { skipReason: string }>;\n\t/**\n\t * Lane-worker capability eligibility (opt-in -- wired only from `runtime-builder.ts`, backed by\n\t * `AgentSession.getLaneWorkerRefusal`): checked FIRST, before `createLaneWorktree`, so an\n\t * ineligible model's dispatch is refused before any lane/pane side effect ever runs. This is the\n\t * parent's best-effort check only -- the dispatched child session refuses authoritatively at its\n\t * own startup (main.ts) regardless of what the parent decides here. Absent dep -> no capability\n\t * check runs, byte-identical to before this field existed.\n\t */\n\tevaluateWorkerLaneRefusal?: () => LaneWorkerRefusal | undefined;\n}\n\n/**\n * Classify a `fire_task` launch failure into an honest, stable skip reason. For an UNATTENDED\n * caller (`ctx.hasUI === false`, always true from the goal/idle path) `authorizeLaunch`'s ONLY\n * refusal throw is the no-standing-grant error (`tmux-agent-manager/index.ts`'s `authorizeLaunch`,\n * message containing the stable phrase \"no standing grant\") -- matched here by substring since the\n * extension throws a plain `Error`, not a tagged error code (documented follow-up hardening, not\n * blocking). Every other thrown error (a bad jobId, a live session-name collision,\n * an environment failure) maps onto the generic `\"tmux_dispatch_failed\"` -- still surfaced through\n * the existing `dispatchSkipReason` contract, never a crash and never a silently-ignored failure.\n */\nexport function classifyDispatchError(error: unknown): string {\n\tconst message = error instanceof Error ? error.message : String(error);\n\treturn message.includes(\"no standing grant\") ? \"no_standing_grant\" : \"tmux_dispatch_failed\";\n}\n\ninterface FireTaskResultDetails {\n\tjob?: {\n\t\tid?: string;\n\t\tagents?: ReadonlyArray<{ id?: string }>;\n\t};\n}\n\n/**\n * Structurally dispatch ONE persistent tmux worker agent for a single goal requirement, by\n * invoking the SAME `tmux_agent_manager` `fire_task` tool call the model itself would make. Core\n * -- not model discretion -- decides WHEN this fires (the goal tool's `dispatchTarget:\"tmux\"`\n * routing gates the call); the launch itself always still goes through the extension's own\n * grant-gated `authorizeLaunch`, so an ungranted unattended call is honestly refused here (never a\n * silent launch, never a fabricated laneId) and the refusal is surfaced through the existing\n * `dispatchSkipReason` contract on the goal tool's response.\n */\nexport async function dispatchTmuxWorker(\n\tdeps: TmuxDispatchDeps,\n\targs: { requirementId: string; instructions: string },\n): Promise<{ laneId?: string; skipReason?: string }> {\n\t// Capability check FIRST -- before the tool-definition lookup and before createLaneWorktree --\n\t// so an ineligible model's dispatch is refused with zero lane/pane/tool side effect. The coarse\n\t// \"worker_capability_insufficient\" skip reason is the stable contract code on the goal tool's\n\t// response; the granular reason (class/window/tool-calling) lives only in the refusal object\n\t// itself, surfaced by the caller for logging (see model-capability.ts's formatLaneWorkerRefusal).\n\tif (deps.evaluateWorkerLaneRefusal?.() !== undefined) {\n\t\treturn { skipReason: \"worker_capability_insufficient\" };\n\t}\n\n\tconst toolDef = deps.getToolDefinition(\"tmux_agent_manager\");\n\tif (!toolDef) return { skipReason: \"tmux_extension_not_loaded\" };\n\n\tconst goalId = deps.getGoalId();\n\tconst ctx = deps.createExtensionContext();\n\n\t// Lane-first: when worktree-sync is wired, create the lane BEFORE any fire_task call so a\n\t// creation refusal (max lanes, invalid key, git error, ...) aborts cleanly with no tmux/pane side\n\t// effect ever having run. The specific engine refusal code is deliberately collapsed onto the one\n\t// stable `worktree_create_failed` skip reason -- same narrow `{laneId?, skipReason?}` contract\n\t// every other skip path here already uses; the engine's own detail lives in its audit log, not in\n\t// this narrow return.\n\tlet laneWorktree: { laneKey: string; worktreePath: string } | undefined;\n\tif (deps.createLaneWorktree) {\n\t\tconst created = await deps.createLaneWorktree({ goalId, requirementId: args.requirementId });\n\t\tif (\"skipReason\" in created) return { skipReason: \"worktree_create_failed\" };\n\t\tlaneWorktree = created;\n\t}\n\n\t// Single-agent 1:1 mapping: a bare fire_task with no `agents` defaults to a THREE-agent\n\t// team (pi/agy/codex -- `DEFAULT_AGENT_PROVIDERS`), which would mint three lanes for one\n\t// requirement. A goal-bound dispatch must map to exactly one lane, so `agents` is always\n\t// passed explicitly here.\n\tconst params = {\n\t\taction: \"fire_task\",\n\t\ttask: args.instructions,\n\t\tgoalId,\n\t\tagents: [\n\t\t\tlaneWorktree\n\t\t\t\t? {\n\t\t\t\t\t\tprovider: \"pi\",\n\t\t\t\t\t\tname: \"goal-worker\",\n\t\t\t\t\t\tcwd: laneWorktree.worktreePath,\n\t\t\t\t\t\tworktreeLane: laneWorktree.laneKey,\n\t\t\t\t\t}\n\t\t\t\t: { provider: \"pi\", name: \"goal-worker\" },\n\t\t],\n\t};\n\tconst toolCallId = `goal-dispatch:${goalId ?? \"?\"}:${args.requirementId}`;\n\n\tlet result: Awaited<ReturnType<ToolDefinition[\"execute\"]>>;\n\ttry {\n\t\tresult = await toolDef.execute(toolCallId, params, ctx.signal, undefined, ctx);\n\t} catch (error) {\n\t\treturn { skipReason: classifyDispatchError(error) };\n\t}\n\n\t// Correlate: the extension reports its dispatch under its OWN caller-chosen laneId\n\t// (`tmux:${job.id}:${agent.id}`, reconstructed here from the tool result's `details.job` --\n\t// the same format `agentLaneId` builds extension-side) which the host's `recordManagedLane`\n\t// bridge keys `_managedLaneDispatches` by; `resolveManagedLaneId` reads that keyed map for the\n\t// internal id the reducer/continuation machinery actually match on.\n\tconst job = (result.details as FireTaskResultDetails | undefined)?.job;\n\tconst primary = job?.agents?.[0];\n\tif (!job?.id || !primary?.id) return { skipReason: \"tmux_dispatch_incomplete\" };\n\n\tconst callerLaneId = `tmux:${job.id}:${primary.id}`;\n\tconst laneId = deps.resolveManagedLaneId(callerLaneId);\n\treturn laneId ? { laneId } : { skipReason: \"lane_correlation_failed\" };\n}\n"]}

package/dist/core/tools/tmux-dispatch.js

@@ -0,0 +1,91 @@
+/**
+ * Classify a `fire_task` launch failure into an honest, stable skip reason. For an UNATTENDED
+ * caller (`ctx.hasUI === false`, always true from the goal/idle path) `authorizeLaunch`'s ONLY
+ * refusal throw is the no-standing-grant error (`tmux-agent-manager/index.ts`'s `authorizeLaunch`,
+ * message containing the stable phrase "no standing grant") -- matched here by substring since the
+ * extension throws a plain `Error`, not a tagged error code (documented follow-up hardening, not
+ * blocking). Every other thrown error (a bad jobId, a live session-name collision,
+ * an environment failure) maps onto the generic `"tmux_dispatch_failed"` -- still surfaced through
+ * the existing `dispatchSkipReason` contract, never a crash and never a silently-ignored failure.
+ */
+export function classifyDispatchError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("no standing grant") ? "no_standing_grant" : "tmux_dispatch_failed";
+}
+/**
+ * Structurally dispatch ONE persistent tmux worker agent for a single goal requirement, by
+ * invoking the SAME `tmux_agent_manager` `fire_task` tool call the model itself would make. Core
+ * -- not model discretion -- decides WHEN this fires (the goal tool's `dispatchTarget:"tmux"`
+ * routing gates the call); the launch itself always still goes through the extension's own
+ * grant-gated `authorizeLaunch`, so an ungranted unattended call is honestly refused here (never a
+ * silent launch, never a fabricated laneId) and the refusal is surfaced through the existing
+ * `dispatchSkipReason` contract on the goal tool's response.
+ */
+export async function dispatchTmuxWorker(deps, args) {
+    // Capability check FIRST -- before the tool-definition lookup and before createLaneWorktree --
+    // so an ineligible model's dispatch is refused with zero lane/pane/tool side effect. The coarse
+    // "worker_capability_insufficient" skip reason is the stable contract code on the goal tool's
+    // response; the granular reason (class/window/tool-calling) lives only in the refusal object
+    // itself, surfaced by the caller for logging (see model-capability.ts's formatLaneWorkerRefusal).
+    if (deps.evaluateWorkerLaneRefusal?.() !== undefined) {
+        return { skipReason: "worker_capability_insufficient" };
+    }
+    const toolDef = deps.getToolDefinition("tmux_agent_manager");
+    if (!toolDef)
+        return { skipReason: "tmux_extension_not_loaded" };
+    const goalId = deps.getGoalId();
+    const ctx = deps.createExtensionContext();
+    // Lane-first: when worktree-sync is wired, create the lane BEFORE any fire_task call so a
+    // creation refusal (max lanes, invalid key, git error, ...) aborts cleanly with no tmux/pane side
+    // effect ever having run. The specific engine refusal code is deliberately collapsed onto the one
+    // stable `worktree_create_failed` skip reason -- same narrow `{laneId?, skipReason?}` contract
+    // every other skip path here already uses; the engine's own detail lives in its audit log, not in
+    // this narrow return.
+    let laneWorktree;
+    if (deps.createLaneWorktree) {
+        const created = await deps.createLaneWorktree({ goalId, requirementId: args.requirementId });
+        if ("skipReason" in created)
+            return { skipReason: "worktree_create_failed" };
+        laneWorktree = created;
+    }
+    // Single-agent 1:1 mapping: a bare fire_task with no `agents` defaults to a THREE-agent
+    // team (pi/agy/codex -- `DEFAULT_AGENT_PROVIDERS`), which would mint three lanes for one
+    // requirement. A goal-bound dispatch must map to exactly one lane, so `agents` is always
+    // passed explicitly here.
+    const params = {
+        action: "fire_task",
+        task: args.instructions,
+        goalId,
+        agents: [
+            laneWorktree
+                ? {
+                    provider: "pi",
+                    name: "goal-worker",
+                    cwd: laneWorktree.worktreePath,
+                    worktreeLane: laneWorktree.laneKey,
+                }
+                : { provider: "pi", name: "goal-worker" },
+        ],
+    };
+    const toolCallId = `goal-dispatch:${goalId ?? "?"}:${args.requirementId}`;
+    let result;
+    try {
+        result = await toolDef.execute(toolCallId, params, ctx.signal, undefined, ctx);
+    }
+    catch (error) {
+        return { skipReason: classifyDispatchError(error) };
+    }
+    // Correlate: the extension reports its dispatch under its OWN caller-chosen laneId
+    // (`tmux:${job.id}:${agent.id}`, reconstructed here from the tool result's `details.job` --
+    // the same format `agentLaneId` builds extension-side) which the host's `recordManagedLane`
+    // bridge keys `_managedLaneDispatches` by; `resolveManagedLaneId` reads that keyed map for the
+    // internal id the reducer/continuation machinery actually match on.
+    const job = result.details?.job;
+    const primary = job?.agents?.[0];
+    if (!job?.id || !primary?.id)
+        return { skipReason: "tmux_dispatch_incomplete" };
+    const callerLaneId = `tmux:${job.id}:${primary.id}`;
+    const laneId = deps.resolveManagedLaneId(callerLaneId);
+    return laneId ? { laneId } : { skipReason: "lane_correlation_failed" };
+}
+//# sourceMappingURL=tmux-dispatch.js.map

package/dist/core/tools/tmux-dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux-dispatch.js","sourceRoot":"","sources":["../../../src/core/tools/tmux-dispatch.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\nimport type { LaneWorkerRefusal } from \"../model-capability.ts\";\n\n/**\n * Dependencies for {@link dispatchTmuxWorker}, injected from the construction site\n * (`RuntimeBuilder`) so the adapter itself stays a small, unit-testable, faux-tool-driven module\n * with no direct dependency on `AgentSession`/`ExtensionRunner`/`BackgroundLaneController`.\n */\nexport interface TmuxDispatchDeps {\n\t/** Look up a registered tool by name -- the SAME seam the model's own tool calls resolve\n\t * through (`AgentSession.getToolDefinition` -> `RuntimeBuilder.getToolDefinition`). `undefined`\n\t * when the tmux extension is not loaded in this session -- an honest, non-fatal skip, not a\n\t * crash and not a silent no-op. */\n\tgetToolDefinition: (name: string) => ToolDefinition | undefined;\n\t/** Build a fresh, non-turn-bound `ExtensionContext` for this call\n\t * (`ExtensionRunner.createContext()`) -- safe to invoke from the goal/idle path, outside any\n\t * live model turn. */\n\tcreateExtensionContext: () => ExtensionContext;\n\t/**\n\t * Resolve the tmux extension's own caller-chosen lane id (reconstructed below from the\n\t * `fire_task` result's `details.job`) to the host's internal `LaneTracker` id -- the id\n\t * `Requirement.boundLaneId` / `inFlightGoalLaneIds` actually match\n\t * (`BackgroundLaneController.resolveManagedLaneId`). A deterministic keyed lookup against the\n\t * dispatch this same call just minted, NOT a racy `getLaneRecords()` diff.\n\t */\n\tresolveManagedLaneId: (callerLaneId: string) => string | undefined;\n\t/** Active goal id, threaded onto the `fire_task` call so the dispatched lane is goal-tagged\n\t * (`ManagedLaneEvent.goalId`) -- `undefined` when no goal is active (dispatch still proceeds;\n\t * the resulting lane is simply untagged). */\n\tgetGoalId: () => string | undefined;\n\t/**\n\t * Worktree-sync lane-first dispatch (opt-in -- wired ONLY inside `runtime-builder.ts`'s\n\t * `worktreeSync.enabled` block, via the engine's `createLane`): when present, `dispatchTmuxWorker`\n\t * creates a fresh worktree-sync lane for this requirement BEFORE issuing any `fire_task` call, so\n\t * a creation refusal aborts cleanly before any tmux/pane side effect ever runs -- never a\n\t * half-made lane, never a fabricated worktree. On success the dispatched agent's `cwd` is the new\n\t * lane worktree and it carries `worktreeLane` (threaded to the tmux extension's launch profile --\n\t * see `dispatch-grant.ts`'s `buildLaunchProfileFlags`). Absent dep -> existing byte-identical\n\t * `params.agents` (no `cwd`/`worktreeLane`), exactly as before this field existed.\n\t */\n\tcreateLaneWorktree?: (args: {\n\t\tgoalId?: string;\n\t\trequirementId: string;\n\t}) => Promise<{ laneKey: string; worktreePath: string } | { skipReason: string }>;\n\t/**\n\t * Lane-worker capability eligibility (opt-in -- wired only from `runtime-builder.ts`, backed by\n\t * `AgentSession.getLaneWorkerRefusal`): checked FIRST, before `createLaneWorktree`, so an\n\t * ineligible model's dispatch is refused before any lane/pane side effect ever runs. This is the\n\t * parent's best-effort check only -- the dispatched child session refuses authoritatively at its\n\t * own startup (main.ts) regardless of what the parent decides here. Absent dep -> no capability\n\t * check runs, byte-identical to before this field existed.\n\t */\n\tevaluateWorkerLaneRefusal?: () => LaneWorkerRefusal | undefined;\n}\n\n/**\n * Classify a `fire_task` launch failure into an honest, stable skip reason. For an UNATTENDED\n * caller (`ctx.hasUI === false`, always true from the goal/idle path) `authorizeLaunch`'s ONLY\n * refusal throw is the no-standing-grant error (`tmux-agent-manager/index.ts`'s `authorizeLaunch`,\n * message containing the stable phrase \"no standing grant\") -- matched here by substring since the\n * extension throws a plain `Error`, not a tagged error code (documented follow-up hardening, not\n * blocking). Every other thrown error (a bad jobId, a live session-name collision,\n * an environment failure) maps onto the generic `\"tmux_dispatch_failed\"` -- still surfaced through\n * the existing `dispatchSkipReason` contract, never a crash and never a silently-ignored failure.\n */\nexport function classifyDispatchError(error: unknown): string {\n\tconst message = error instanceof Error ? error.message : String(error);\n\treturn message.includes(\"no standing grant\") ? \"no_standing_grant\" : \"tmux_dispatch_failed\";\n}\n\ninterface FireTaskResultDetails {\n\tjob?: {\n\t\tid?: string;\n\t\tagents?: ReadonlyArray<{ id?: string }>;\n\t};\n}\n\n/**\n * Structurally dispatch ONE persistent tmux worker agent for a single goal requirement, by\n * invoking the SAME `tmux_agent_manager` `fire_task` tool call the model itself would make. Core\n * -- not model discretion -- decides WHEN this fires (the goal tool's `dispatchTarget:\"tmux\"`\n * routing gates the call); the launch itself always still goes through the extension's own\n * grant-gated `authorizeLaunch`, so an ungranted unattended call is honestly refused here (never a\n * silent launch, never a fabricated laneId) and the refusal is surfaced through the existing\n * `dispatchSkipReason` contract on the goal tool's response.\n */\nexport async function dispatchTmuxWorker(\n\tdeps: TmuxDispatchDeps,\n\targs: { requirementId: string; instructions: string },\n): Promise<{ laneId?: string; skipReason?: string }> {\n\t// Capability check FIRST -- before the tool-definition lookup and before createLaneWorktree --\n\t// so an ineligible model's dispatch is refused with zero lane/pane/tool side effect. The coarse\n\t// \"worker_capability_insufficient\" skip reason is the stable contract code on the goal tool's\n\t// response; the granular reason (class/window/tool-calling) lives only in the refusal object\n\t// itself, surfaced by the caller for logging (see model-capability.ts's formatLaneWorkerRefusal).\n\tif (deps.evaluateWorkerLaneRefusal?.() !== undefined) {\n\t\treturn { skipReason: \"worker_capability_insufficient\" };\n\t}\n\n\tconst toolDef = deps.getToolDefinition(\"tmux_agent_manager\");\n\tif (!toolDef) return { skipReason: \"tmux_extension_not_loaded\" };\n\n\tconst goalId = deps.getGoalId();\n\tconst ctx = deps.createExtensionContext();\n\n\t// Lane-first: when worktree-sync is wired, create the lane BEFORE any fire_task call so a\n\t// creation refusal (max lanes, invalid key, git error, ...) aborts cleanly with no tmux/pane side\n\t// effect ever having run. The specific engine refusal code is deliberately collapsed onto the one\n\t// stable `worktree_create_failed` skip reason -- same narrow `{laneId?, skipReason?}` contract\n\t// every other skip path here already uses; the engine's own detail lives in its audit log, not in\n\t// this narrow return.\n\tlet laneWorktree: { laneKey: string; worktreePath: string } | undefined;\n\tif (deps.createLaneWorktree) {\n\t\tconst created = await deps.createLaneWorktree({ goalId, requirementId: args.requirementId });\n\t\tif (\"skipReason\" in created) return { skipReason: \"worktree_create_failed\" };\n\t\tlaneWorktree = created;\n\t}\n\n\t// Single-agent 1:1 mapping: a bare fire_task with no `agents` defaults to a THREE-agent\n\t// team (pi/agy/codex -- `DEFAULT_AGENT_PROVIDERS`), which would mint three lanes for one\n\t// requirement. A goal-bound dispatch must map to exactly one lane, so `agents` is always\n\t// passed explicitly here.\n\tconst params = {\n\t\taction: \"fire_task\",\n\t\ttask: args.instructions,\n\t\tgoalId,\n\t\tagents: [\n\t\t\tlaneWorktree\n\t\t\t\t? {\n\t\t\t\t\t\tprovider: \"pi\",\n\t\t\t\t\t\tname: \"goal-worker\",\n\t\t\t\t\t\tcwd: laneWorktree.worktreePath,\n\t\t\t\t\t\tworktreeLane: laneWorktree.laneKey,\n\t\t\t\t\t}\n\t\t\t\t: { provider: \"pi\", name: \"goal-worker\" },\n\t\t],\n\t};\n\tconst toolCallId = `goal-dispatch:${goalId ?? \"?\"}:${args.requirementId}`;\n\n\tlet result: Awaited<ReturnType<ToolDefinition[\"execute\"]>>;\n\ttry {\n\t\tresult = await toolDef.execute(toolCallId, params, ctx.signal, undefined, ctx);\n\t} catch (error) {\n\t\treturn { skipReason: classifyDispatchError(error) };\n\t}\n\n\t// Correlate: the extension reports its dispatch under its OWN caller-chosen laneId\n\t// (`tmux:${job.id}:${agent.id}`, reconstructed here from the tool result's `details.job` --\n\t// the same format `agentLaneId` builds extension-side) which the host's `recordManagedLane`\n\t// bridge keys `_managedLaneDispatches` by; `resolveManagedLaneId` reads that keyed map for the\n\t// internal id the reducer/continuation machinery actually match on.\n\tconst job = (result.details as FireTaskResultDetails | undefined)?.job;\n\tconst primary = job?.agents?.[0];\n\tif (!job?.id || !primary?.id) return { skipReason: \"tmux_dispatch_incomplete\" };\n\n\tconst callerLaneId = `tmux:${job.id}:${primary.id}`;\n\tconst laneId = deps.resolveManagedLaneId(callerLaneId);\n\treturn laneId ? { laneId } : { skipReason: \"lane_correlation_failed\" };\n}\n"]}

package/dist/core/tools/windows-shell-engine.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `python-engine` tier: per-command spawn of the bundled `pi-shell-engine` (D3 in the
+ * blueprint). Wires the frozen §1.2/§1.3 stdin-JSON-request / 0x1e-framed-stdout protocol into a
+ * `BashOperations`, threads `WindowsShellState` through both directions (D4), and degrades to a
+ * named, actionable error when the Python runtime is not ready — the PowerShell floor keeps
+ * working regardless (the router never routes simple commands here when the engine is off).
+ */
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+import { type PythonRuntimeOutcome } from "../python-runtime.ts";
+import type { BashOperations } from "./bash.ts";
+import { type WindowsShellState } from "./windows-shell-state.ts";
+/** The full §1.3 control-frame shape. */
+export interface WindowsShellEngineFrame {
+    exitCode: number;
+    cwd: string;
+    envDelta: Record<string, string | null>;
+    unsupported: {
+        code: "unsupported";
+        construct: string;
+        message: string;
+    } | null;
+}
+export declare class WindowsShellEngineFailure extends Error {
+    readonly capturedOutput: string;
+    constructor(message: string, capturedOutput: string);
+}
+export interface WindowsShellEngineOptions {
+    /** Override for tests: resolves the Python runtime outcome. Default: `ensurePythonRuntime`. */
+    resolveRuntime?: () => Promise<PythonRuntimeOutcome>;
+    /** Override for tests: absolute path to the engine's `main.py`. Default: the bundled runtime. */
+    engineScriptPath?: string;
+    /** Override for tests: the per-session state store lookup. Default: the shared module store. */
+    getState?: (sessionKey: string) => WindowsShellState;
+    /** Override for tests: spawns the engine child process. Default: `spawnProcess` (cross-spawn on win32). */
+    spawn?: (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+}
+/**
+ * Create the `python-engine` tier `BashOperations` for one bash-tool session. `exec`'s `command`
+ * argument is the RAW Bash source from the `python-engine` route (never PowerShell-translated).
+ */
+export declare function createWindowsShellEngineOperations(sessionKey: string, options?: WindowsShellEngineOptions): BashOperations;
+//# sourceMappingURL=windows-shell-engine.d.ts.map

package/dist/core/tools/windows-shell-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-shell-engine.d.ts","sourceRoot":"","sources":["../../../src/core/tools/windows-shell-engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKrE,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAKN,KAAK,iBAAiB,EACtB,MAAM,0BAA0B,CAAC;AAIlC,0CAAyC;AACzC,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,WAAW,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChF;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,YAAY,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAIlD;CACD;AAuCD,MAAM,WAAW,yBAAyB;IACzC,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACrD,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACrD,2GAA2G;IAC3G,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;CACjF;AAUD;;;GAGG;AACH,wBAAgB,kCAAkC,CACjD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,yBAA8B,GACrC,cAAc,CAwFhB","sourcesContent":["/**\n * The `python-engine` tier: per-command spawn of the bundled `pi-shell-engine` (D3 in the\n * blueprint). Wires the frozen §1.2/§1.3 stdin-JSON-request / 0x1e-framed-stdout protocol into a\n * `BashOperations`, threads `WindowsShellState` through both directions (D4), and degrades to a\n * named, actionable error when the Python runtime is not ready — the PowerShell floor keeps\n * working regardless (the router never routes simple commands here when the engine is off).\n */\n\nimport type { ChildProcess, SpawnOptions } from \"node:child_process\";\nimport { join } from \"node:path\";\nimport { getBundledResourcesDir } from \"../../config.ts\";\nimport { spawnProcess, waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport { getShellEnv, trackDetachedChildPid, untrackDetachedChildPid } from \"../../utils/shell.ts\";\nimport { ensurePythonRuntime, type PythonRuntimeOutcome } from \"../python-runtime.ts\";\nimport type { BashOperations } from \"./bash.ts\";\nimport {\n\tapplyEngineFrame,\n\tgetOrCreateWindowsShellState,\n\tmergeEffectiveEnv,\n\tresolveEffectiveCwd,\n\ttype WindowsShellState,\n} from \"./windows-shell-state.ts\";\n\nconst ENGINE_FRAME_SENTINEL = 0x1e;\n\n/** The full §1.3 control-frame shape. */\nexport interface WindowsShellEngineFrame {\n\texitCode: number;\n\tcwd: string;\n\tenvDelta: Record<string, string | null>;\n\tunsupported: { code: \"unsupported\"; construct: string; message: string } | null;\n}\n\nexport class WindowsShellEngineFailure extends Error {\n\treadonly capturedOutput: string;\n\n\tconstructor(message: string, capturedOutput: string) {\n\t\tsuper(message);\n\t\tthis.name = \"WindowsShellEngineFailure\";\n\t\tthis.capturedOutput = capturedOutput;\n\t}\n}\n\nfunction resolveEngineScriptPath(): string {\n\treturn join(getBundledResourcesDir(), \"runtimes\", \"pi-shell-engine\", \"main.py\");\n}\n\nconst MAX_CONTROL_FRAME_BYTES = 64 * 1024;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** Parse the terminal frame from the dedicated control stream. Command output is never retained here. */\nfunction parseControlFrame(buffer: Buffer): WindowsShellEngineFrame | undefined {\n\tif (buffer.length < 2 || buffer[buffer.length - 1] !== ENGINE_FRAME_SENTINEL) return undefined;\n\tconst openIndex = buffer.lastIndexOf(ENGINE_FRAME_SENTINEL, buffer.length - 2);\n\tif (openIndex === -1) return undefined;\n\ttry {\n\t\tconst raw: unknown = JSON.parse(buffer.subarray(openIndex + 1, buffer.length - 1).toString(\"utf8\"));\n\t\tif (!isRecord(raw)) return undefined;\n\t\tif (typeof raw.exitCode !== \"number\" || !Number.isInteger(raw.exitCode)) return undefined;\n\t\tif (typeof raw.cwd !== \"string\" || !isRecord(raw.envDelta)) return undefined;\n\t\tif (raw.unsupported !== null && !isRecord(raw.unsupported)) return undefined;\n\t\tif (\n\t\t\traw.unsupported !== null &&\n\t\t\t(raw.unsupported.code !== \"unsupported\" ||\n\t\t\t\ttypeof raw.unsupported.construct !== \"string\" ||\n\t\t\t\ttypeof raw.unsupported.message !== \"string\")\n\t\t)\n\t\t\treturn undefined;\n\t\tfor (const value of Object.values(raw.envDelta)) {\n\t\t\tif (value !== null && typeof value !== \"string\") return undefined;\n\t\t}\n\t\treturn raw as unknown as WindowsShellEngineFrame;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nexport interface WindowsShellEngineOptions {\n\t/** Override for tests: resolves the Python runtime outcome. Default: `ensurePythonRuntime`. */\n\tresolveRuntime?: () => Promise<PythonRuntimeOutcome>;\n\t/** Override for tests: absolute path to the engine's `main.py`. Default: the bundled runtime. */\n\tengineScriptPath?: string;\n\t/** Override for tests: the per-session state store lookup. Default: the shared module store. */\n\tgetState?: (sessionKey: string) => WindowsShellState;\n\t/** Override for tests: spawns the engine child process. Default: `spawnProcess` (cross-spawn on win32). */\n\tspawn?: (command: string, args: string[], options: SpawnOptions) => ChildProcess;\n}\n\nfunction degradationError(\n\toutcome: Extract<PythonRuntimeOutcome, { status: \"offline\" | \"uv-unavailable\" | \"python-unavailable\" }>,\n) {\n\treturn new Error(\n\t\t`The Windows shell engine (Python) is unavailable: ${outcome.reason} The simple-command PowerShell floor still works; fix the Python runtime (uv/network) to restore pipelines, redirection, expansion, and chaining.`,\n\t);\n}\n\n/**\n * Create the `python-engine` tier `BashOperations` for one bash-tool session. `exec`'s `command`\n * argument is the RAW Bash source from the `python-engine` route (never PowerShell-translated).\n */\nexport function createWindowsShellEngineOperations(\n\tsessionKey: string,\n\toptions: WindowsShellEngineOptions = {},\n): BashOperations {\n\tconst resolveRuntime = options.resolveRuntime ?? (() => ensurePythonRuntime({ silent: true }));\n\tconst engineScriptPath = options.engineScriptPath ?? resolveEngineScriptPath();\n\tconst getState = options.getState ?? getOrCreateWindowsShellState;\n\tconst spawn = options.spawn ?? spawnProcess;\n\n\treturn {\n\t\tasync exec(command, cwd, { onData, signal, timeout, env }) {\n\t\t\tconst runtime = await resolveRuntime();\n\t\t\tif (runtime.status !== \"ready\") throw degradationError(runtime);\n\n\t\t\tconst state = getState(sessionKey);\n\t\t\tconst effectiveCwd = resolveEffectiveCwd(state, cwd);\n\t\t\tconst effectiveEnv = mergeEffectiveEnv(state, env ?? getShellEnv());\n\t\t\tconst timeoutMs = timeout !== undefined && timeout > 0 ? timeout * 1000 : undefined;\n\t\t\t// The engine's own soft deadline must fire and emit its cooperative exit-124 frame (which\n\t\t\t// preserves partial output) BEFORE the hard tree-kill backstop below, or the hard kill\n\t\t\t// always wins the race and the soft path never gets to run. Give it a head start; the hard\n\t\t\t// kill still bounds a hung engine that never reads its own deadline.\n\t\t\tconst requestTimeoutMs = timeoutMs !== undefined ? Math.max(timeoutMs - 500, 500) : undefined;\n\n\t\t\tconst request = {\n\t\t\t\tcommand,\n\t\t\t\tcwd: effectiveCwd,\n\t\t\t\tenv: effectiveEnv,\n\t\t\t\t...(requestTimeoutMs !== undefined ? { timeoutMs: requestTimeoutMs } : {}),\n\t\t\t};\n\n\t\t\tconst child = spawn(runtime.pythonPath, [\"-B\", engineScriptPath], {\n\t\t\t\tcwd: effectiveCwd,\n\t\t\t\tenv: {\n\t\t\t\t\t...effectiveEnv,\n\t\t\t\t\tPYTHONDONTWRITEBYTECODE: \"1\",\n\t\t\t\t\tPYTHONIOENCODING: \"utf-8\",\n\t\t\t\t\tPYTHONUNBUFFERED: \"1\",\n\t\t\t\t\tPYTHONUTF8: \"1\",\n\t\t\t\t},\n\t\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\t});\n\t\t\tif (child.pid) trackDetachedChildPid(child.pid);\n\n\t\t\tlet controlBuffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);\n\t\t\tlet controlOverflow = false;\n\n\t\t\t// Command output is the data stream: forward it immediately and never retain a\n\t\t\t// second full copy merely to find the terminal frame.\n\t\t\tchild.stdout?.on(\"data\", (chunk: Buffer) => {\n\t\t\t\tonData(chunk);\n\t\t\t});\n\t\t\t// stderr is the bounded control stream. The Python engine routes command stderr\n\t\t\t// into stdout, so this channel contains only the terminal frame/diagnostics.\n\t\t\tchild.stderr?.on(\"data\", (chunk: Buffer) => {\n\t\t\t\tif (controlOverflow) return;\n\t\t\t\tif (controlBuffer.length + chunk.length > MAX_CONTROL_FRAME_BYTES) {\n\t\t\t\t\tcontrolOverflow = true;\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tcontrolBuffer = Buffer.concat([controlBuffer, chunk]);\n\t\t\t});\n\n\t\t\ttry {\n\t\t\t\tchild.stdin?.end(JSON.stringify(request), \"utf8\");\n\t\t\t\tconst terminal = await waitForChildProcessWithTermination(child, {\n\t\t\t\t\tsignal,\n\t\t\t\t\ttimeoutMs,\n\t\t\t\t\tkillGraceMs: 2_000,\n\t\t\t\t});\n\t\t\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\n\t\t\t\tconst frame = controlOverflow ? undefined : parseControlFrame(controlBuffer);\n\t\t\t\tif (!frame) {\n\t\t\t\t\tconst capturedOutput = controlOverflow\n\t\t\t\t\t\t? `control frame exceeded ${MAX_CONTROL_FRAME_BYTES} bytes`\n\t\t\t\t\t\t: controlBuffer.toString(\"utf8\");\n\t\t\t\t\tthrow new WindowsShellEngineFailure(\n\t\t\t\t\t\t`Windows shell engine failed (process exit ${terminal.code ?? \"null\"}) without a parseable control frame.\\n${capturedOutput}`,\n\t\t\t\t\t\tcapturedOutput,\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tapplyEngineFrame(state, frame);\n\t\t\t\tif (frame.unsupported) throw new Error(frame.unsupported.message);\n\t\t\t\treturn { exitCode: frame.exitCode };\n\t\t\t} finally {\n\t\t\t\tif (child.pid) untrackDetachedChildPid(child.pid);\n\t\t\t}\n\t\t},\n\t};\n}\n"]}