@caupulican/pi-adaptative 0.81.32 → 0.81.37

package/CHANGELOG.md

@@ -1,3 +1,49 @@
+## [0.81.37] - 2026-07-16
+
+### Fixed
+
+- Updated release validation for the native Python/task-step surface, update preflight, platform-shell output, and prompt-cost growth, and made the Windows binary smoke test prove the stable Bash-like contract executes through PowerShell.
+
+## [0.81.36] - 2026-07-16
+
+### Added
+
+- Added native session-persisted task steps with the built-in `task_steps` tool and `/task`/`/steps` commands, replacing the machine-local checklist extension.
+- Added one stable `bash` tool contract on every platform, with deterministic finite-grammar conversion to UTF-8 PowerShell execution on Windows, fail-closed handling for unsupported shell constructs, and legacy `powershell` tool-name remapping.
+- Added a native uv-managed `python` tool with pinned/checksummed runtime provisioning, direct cross-platform execution, bounded process-tree deadlines, streamed output artifacts, doctor/update/postinstall integration, and native UAC/profile registration.
+
+### Changed
+
+- Agent, interactive, and RPC shell calls now have a 120-second wall-clock default, including continuously producing commands; agent-tool overrides cap at one hour. Removed the unbounded synchronous full-file/recursive optimizer path and added scoped paths-first search guidance.
+
+### Fixed
+
+- Made the platform-limited FFF native binding optional so clean Android/Termux installs use the supported fallback instead of failing with `EBADPLATFORM`.
+- Listed the native `python` and `task_steps` surfaces in CLI help for clean-install discovery.
+- Updated `undici` to 8.5.0 to resolve current TLS, WebSocket, header, cache, and connection-reuse advisories.
+
+## [0.81.35] - 2026-07-15
+
+## [0.81.34] - 2026-07-15
+
+## [0.81.33] - 2026-07-15
+
+### Added
+
+- Added a profile-selectable bundled tmux agent manager with portable team templates, event-driven terminal result signals, exactly-once parent wake handoffs, startup reconciliation, and packaged binary resources.
+- Added a leased multi-tenant transient workspace under `~/.pi/agent/work/<category>/<tenant>/<run-id>` with ownership manifests and bounded age, count, byte, scan, and depth retention.
+- Added native Windows x64 and ARM64 build, test, smoke, and release gates.
+
+### Fixed
+
+- Added in-settings profile model editing, including returning an existing profile to session/default-model inheritance and immediate transactional reload for active profiles.
+- Made profile extension choices use collision-safe path identities and description/folder labels, so separate folder-based `index.ts` extensions can be enabled independently.
+- Made goal ledgers user-recoverable with manual status, resume, reopen, complete, close, and override controls while retaining evidence-gated agent completion.
+- Removed redundant approval waits and unbounded repair loops from the bundled skill/extension authoring and harness-learning workflows.
+- Made delegated worker terminal events queue bounded, serialized parent wake handoffs without injecting untrusted worker output, status polling, or debounce-timer races.
+- Made child-process waits settle when attached after a fast child already emitted its terminal event, and routed exec cancellation through event-driven process-tree escalation.
+- Removed Unix-only temporary-path, shell, editor, clipboard, package, and runtime assumptions from Windows execution paths.
+
 ## [0.81.32] - 2026-07-13
 
 ### Fixed

package/dist/bundled-resources/extensions/tmux-agent-manager/README.md

@@ -0,0 +1,69 @@
+# tmux Agent Manager
+
+Portable bundled extension for event-driven external-provider teams in tmux. Enable it from a resource profile with `extensions.allow: ["tmux-agent-manager"]` (or `"*"`).
+
+## Platform policy
+
+- Use this extension on Linux, Windows-through-WSL/MSYS/Cygwin, and macOS when `tmux` is on `PATH`.
+- Do not use `cmux` on Windows/Linux. The cmux manager is manual-only and disabled outside macOS.
+- Gemini is intentionally not a native provider here; Agy covers that lane. Claude remains native Claude.
+
+## Tool
+
+`tmux_agent_manager`
+
+Important actions:
+
+- `status` — detect `tmux`, current session, and known sessions.
+- `setup_help` — show install hints.
+- `list_templates` / `show_template` — inspect reusable owner templates.
+- `workspace_plan` — dry-run a tmux session/pane layout.
+- `launch_workspace` — launch panes immediately; pass `dryRun:true` only when a preview is useful.
+- `fire_task` — open provider CLIs in tmux panes, inject prompts, stream pane output through event-driven DONE/BLOCKED watchers, write result files, and wake the parent with a bounded terminal handoff.
+- `job_status`, `list_jobs`, `set_variable`, `list_variables` — inspect and steer managed jobs.
+- `stop_job`, `stop_session` — dry-run/confirmed tmux cleanup.
+- `notify`, `set_status`, `clear_status` — tmux UI/status metadata.
+
+## Built-in team templates
+
+Templates are embedded in the tool and loaded at runtime from JSON under `templates/` / `~/.pi/agent/work/background/tmux-agent-manager/state/templates`. JSON templates with the same name override embedded defaults.
+
+- `provider-prompt-smoke` — real minimal interactive prompt smoke for native Claude, Agy, and Pi. Consumes provider/model tokens.
+- `full-provider-review` — Pi lead + Claude reviewer + Agy validator + Agy reviewer. Uses native provider CLIs and consumes model/provider tokens.
+- `builder-validator` — Agy builder + Claude reviewer + Agy validator + Pi coordinator for scoped implementation/QA.
+
+Example:
+
+```ts
+tmux_agent_manager({ action: "list_templates" })
+tmux_agent_manager({ action: "show_template", teamTemplate: "builder-validator" })
+tmux_agent_manager({
+  action: "fire_task",
+  teamTemplate: "builder-validator",
+  task: "Implement the scoped fix, then independently review and validate. Report PASS/BLOCKED with evidence."
+})
+```
+
+Custom commands are CLI-start commands, not non-interactive `--print` runners:
+
+```ts
+tmux_agent_manager({
+  action: "fire_task",
+  task: "Run through my local Claude wrapper CLI, then report PASS/BLOCKED.",
+  agents: [
+    { provider: "claude", name: "claude-wrapper", command: "my-claude-wrapper" },
+    { provider: "agy", name: "agy-validator" },
+    { provider: "pi", name: "pi-coordinator" }
+  ]
+})
+```
+
+## Safety
+
+Launch actions type commands into tmux panes and execute provider CLIs without an extra approval dialog. Use `dryRun:true` when the task or provider choice is still ambiguous. Stop actions are destructive to running pane work, so they remain previews by default and require `confirm:"yes-tmux-stop"` for real cleanup.
+
+The tool refuses existing tmux sessions. Existing job directories are refused unless `force:true`, which archives the old job directory under `~/.pi/agent/work/background/tmux-agent-manager/state/archives` before launching.
+
+Do not put secrets in task text or command strings. Prompts, commands, captured pane logs, and result files persist under `~/.pi/agent/work/background/tmux-agent-manager/state/jobs` until work retention removes the inactive run.
+
+Terminal result-file events wake the parent exactly once with a bounded, untrusted handoff. Do not poll or peek into panes to detect completion; inspect `job_status` or terminal artifacts afterward only when the bounded handoff is insufficient for a material claim.

package/dist/bundled-resources/extensions/tmux-agent-manager/index.d.ts

@@ -0,0 +1,53 @@
+import { type ExtensionAPI } from "@caupulican/pi-adaptative";
+export declare const piConfig: {
+    tools: string[];
+};
+type Provider = "pi" | "codex" | "agy" | "claude" | "opencode" | "custom";
+type AgentResult = {
+    status: string;
+    marker?: string;
+    detectedAt?: string;
+    reason?: string;
+};
+type VariableState = {
+    updatedAt: string | null;
+    variables: Record<string, unknown>;
+};
+type FireAgentPlan = {
+    id: string;
+    name: string;
+    provider: Provider;
+    command?: string;
+    cwd: string;
+    doneMarker: string;
+    blockedMarker: string;
+    promptPath: string;
+    logPath: string;
+    resultPath: string;
+    paneId?: string;
+    result?: AgentResult;
+};
+type FireTaskPlan = {
+    id: string;
+    createdAt: string;
+    notifiedAt?: string;
+    parentSessionFile?: string;
+    workspaceName: string;
+    sessionName: string;
+    cwd: string;
+    task: string;
+    teamTemplate?: string;
+    deadlineSeconds: number;
+    jobDir: string;
+    jobPath: string;
+    varsPath: string;
+    watcherPath: string;
+    agents: FireAgentPlan[];
+    launchCommands: string[];
+    variables?: VariableState;
+};
+export declare function getTmuxAgentManagerDataRoot(): string;
+export declare function makePaneWatcherScript(job: FireTaskPlan): string;
+export default function tmuxAgentManagerExtension(pi: ExtensionAPI): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/bundled-resources/extensions/tmux-agent-manager/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundled-resources/extensions/tmux-agent-manager/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,YAAY,EAA4C,MAAM,2BAA2B,CAAC;AAIxG,eAAO,MAAM,QAAQ;;CAAoC,CAAC;AAoB1D,KAAK,QAAQ,GAAG,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AA4C1E,KAAK,WAAW,GAAG;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AACF,KAAK,aAAa,GAAG;IAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AACtF,KAAK,aAAa,GAAG;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AACF,KAAK,YAAY,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAGF,wBAAgB,2BAA2B,IAAI,MAAM,CAQpD;AA0XD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CA4G/D;AAklBD,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAAC,EAAE,EAAE,YAAY,QAwPjE","sourcesContent":["import { spawnSync } from \"node:child_process\";\nimport * as crypto from \"node:crypto\";\nimport * as fs from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { type ExtensionAPI, type ExtensionContext, getProcessWorkRun } from \"@caupulican/pi-adaptative\";\nimport type { AgentToolResult } from \"@caupulican/pi-agent-core\";\nimport { Type } from \"typebox\";\n\nexport const piConfig = { tools: [\"tmux_agent_manager\"] };\n\ntype Action =\n\t| \"status\"\n\t| \"setup_help\"\n\t| \"guard\"\n\t| \"notify\"\n\t| \"set_status\"\n\t| \"clear_status\"\n\t| \"workspace_plan\"\n\t| \"launch_workspace\"\n\t| \"fire_task\"\n\t| \"job_status\"\n\t| \"list_jobs\"\n\t| \"set_variable\"\n\t| \"list_variables\"\n\t| \"list_templates\"\n\t| \"show_template\"\n\t| \"stop_job\"\n\t| \"stop_session\";\ntype Provider = \"pi\" | \"codex\" | \"agy\" | \"claude\" | \"opencode\" | \"custom\";\n\ntype AgentSpec = { provider?: Provider; name?: string; command?: string; cwd?: string; tools?: string[] };\ntype TeamTemplate = {\n\tname: string;\n\tdescription: string;\n\tagents: AgentSpec[];\n\tdeadlineSeconds?: number;\n\tnotes?: string[];\n};\ntype Params = {\n\taction?: Action;\n\ttitle?: string;\n\tbody?: string;\n\tsubtitle?: string;\n\tstatusKey?: string;\n\tstatus?: string;\n\ticon?: string;\n\tcolor?: string;\n\tworkspaceName?: string;\n\tcwd?: string;\n\tagents?: AgentSpec[];\n\tteamTemplate?: string;\n\ttask?: string;\n\tjobId?: string;\n\tvariableName?: string;\n\tvariableValue?: string;\n\tdeadlineSeconds?: number;\n\tdryRun?: boolean;\n\tforce?: boolean;\n\tconfirm?: string;\n};\n\ntype RunResult = { ok: boolean; status: number | null; stdout: string; stderr: string; error?: string; args: string[] };\ntype TmuxDetection = {\n\tinsideTmux: boolean;\n\ttmuxBin?: string;\n\tcliAvailable: boolean;\n\tversion?: string;\n\tcurrentSession?: string;\n\tsessions: string[];\n\tenv: { tmux?: string; term?: string };\n\terrors: string[];\n};\ntype AgentResult = {\n\tstatus: string;\n\tmarker?: string;\n\tdetectedAt?: string;\n\treason?: string;\n};\ntype VariableState = { updatedAt: string | null; variables: Record<string, unknown> };\ntype FireAgentPlan = {\n\tid: string;\n\tname: string;\n\tprovider: Provider;\n\tcommand?: string;\n\tcwd: string;\n\tdoneMarker: string;\n\tblockedMarker: string;\n\tpromptPath: string;\n\tlogPath: string;\n\tresultPath: string;\n\tpaneId?: string;\n\tresult?: AgentResult;\n};\ntype FireTaskPlan = {\n\tid: string;\n\tcreatedAt: string;\n\tnotifiedAt?: string;\n\tparentSessionFile?: string;\n\tworkspaceName: string;\n\tsessionName: string;\n\tcwd: string;\n\ttask: string;\n\tteamTemplate?: string;\n\tdeadlineSeconds: number;\n\tjobDir: string;\n\tjobPath: string;\n\tvarsPath: string;\n\twatcherPath: string;\n\tagents: FireAgentPlan[];\n\tlaunchCommands: string[];\n\tvariables?: VariableState;\n};\n\nconst EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));\nexport function getTmuxAgentManagerDataRoot(): string {\n\tconst agentDir =\n\t\tprocess.env.PI_ADAPTATIVE_CODING_AGENT_DIR ||\n\t\tprocess.env[\"PI-ADAPTATIVE_CODING_AGENT_DIR\"] ||\n\t\tprocess.env.PI_CODING_AGENT_DIR ||\n\t\tprocess.env.PI_AGENT_DIR ||\n\t\tpath.join(homedir(), \".pi\", \"agent\");\n\treturn getProcessWorkRun(agentDir, \"background\", \"tmux-agent-manager\", \"state\").path;\n}\nfunction jobsRoot(): string {\n\treturn path.join(getTmuxAgentManagerDataRoot(), \"jobs\");\n}\nfunction archiveRoot(): string {\n\treturn path.join(getTmuxAgentManagerDataRoot(), \"archives\");\n}\nfunction templateDirs(): string[] {\n\treturn [path.join(EXTENSION_ROOT, \"templates\"), path.join(getTmuxAgentManagerDataRoot(), \"templates\")];\n}\nconst MAX_OUTPUT = 12_000;\nconst DEFAULT_AGENT_PROVIDERS: Provider[] = [\"pi\", \"agy\", \"codex\"];\nconst PROVIDER_COMMANDS: Record<Provider, string> = {\n\tpi: \"pi\",\n\tcodex: \"codex\",\n\tagy: \"agy\",\n\tclaude: \"claude\",\n\topencode: \"opencode\",\n\tcustom: \"\",\n};\nconst DEFAULT_DEADLINE_SECONDS = 20 * 60;\nconst MAX_DEADLINE_SECONDS = 24 * 60 * 60;\nconst TEAM_TEMPLATES: TeamTemplate[] = [\n\t{\n\t\tname: \"provider-prompt-smoke\",\n\t\tdescription:\n\t\t\t\"Real minimal interactive prompt smoke for native Claude, Agy, and Pi. Consumes provider/model tokens.\",\n\t\tdeadlineSeconds: 10 * 60,\n\t\tagents: [\n\t\t\t{ provider: \"claude\", name: \"claude-prompt-smoke\" },\n\t\t\t{ provider: \"agy\", name: \"agy-prompt-smoke\" },\n\t\t\t{ provider: \"pi\", name: \"pi-prompt-smoke\" },\n\t\t],\n\t\tnotes: [\n\t\t\t\"Use only when model-token/auth validation is intended.\",\n\t\t\t\"The manager opens each CLI in tmux, injects the prompt, captures pane output, and watches DONE/BLOCKED markers.\",\n\t\t],\n\t},\n\t{\n\t\tname: \"full-provider-review\",\n\t\tdescription:\n\t\t\t\"Interactive native-provider review team: Pi lead, Claude reviewer, Agy validator, Agy reviewer. Consumes provider/model tokens.\",\n\t\tdeadlineSeconds: 30 * 60,\n\t\tagents: [\n\t\t\t{ provider: \"pi\", name: \"pi-lead\" },\n\t\t\t{ provider: \"claude\", name: \"claude-reviewer\" },\n\t\t\t{ provider: \"agy\", name: \"agy-validator\" },\n\t\t\t{ provider: \"agy\", name: \"agy-reviewer\" },\n\t\t],\n\t\tnotes: [\n\t\t\t\"Best for non-trivial review/QA where independent native CLIs help.\",\n\t\t\t\"Keep the task objective bounded; inspect captured panes/result files before accepting PASS.\",\n\t\t],\n\t},\n\t{\n\t\tname: \"builder-validator\",\n\t\tdescription:\n\t\t\t\"Interactive implementation loop: Agy builder, Claude reviewer, Agy validator, Pi coordinator. Good default for scoped code work.\",\n\t\tdeadlineSeconds: 25 * 60,\n\t\tagents: [\n\t\t\t{ provider: \"agy\", name: \"builder\" },\n\t\t\t{ provider: \"claude\", name: \"code-reviewer\" },\n\t\t\t{ provider: \"agy\", name: \"validator\" },\n\t\t\t{ provider: \"pi\", name: \"coordinator\" },\n\t\t],\n\t\tnotes: [\n\t\t\t\"Use for owner-approved implementation/QA batches; never claim complete until result files and validation evidence are inspected.\",\n\t\t],\n\t},\n];\n\nfunction cap(text: string, max = MAX_OUTPUT): string {\n\treturn text.length <= max ? text : `${text.slice(0, max)}\\n...[truncated ${text.length - max} chars]`;\n}\nfunction firstString(...values: unknown[]): string | undefined {\n\tfor (const value of values) if (typeof value === \"string\" && value.trim()) return value.trim();\n\treturn undefined;\n}\nfunction errorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\nfunction clampInt(value: unknown, fallback: number, min: number, max: number): number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value)) return fallback;\n\treturn Math.max(min, Math.min(max, Math.trunc(value)));\n}\nfunction findExecutable(name: string): string | undefined {\n\tfor (const dir of (process.env.PATH || \"\").split(path.delimiter)) {\n\t\tif (!dir) continue;\n\t\tconst candidate = path.join(dir, process.platform === \"win32\" ? `${name}.exe` : name);\n\t\ttry {\n\t\t\tif (fs.statSync(candidate).isFile()) return candidate;\n\t\t} catch {\n\t\t\t/* ignore */\n\t\t}\n\t}\n\treturn undefined;\n}\nfunction quoteShell(value: string): string {\n\treturn `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\nfunction ensureDir(dir: string): void {\n\tfs.mkdirSync(dir, { recursive: true, mode: 0o700 });\n}\nfunction resolveCwd(ctx: ExtensionContext, requested?: string): string {\n\tconst cwd = path.resolve(ctx.cwd || process.cwd(), requested?.trim() || \".\");\n\tconst stat = fs.statSync(cwd);\n\tif (!stat.isDirectory()) throw new Error(`cwd is not a directory: ${cwd}`);\n\treturn cwd;\n}\nfunction safeName(value: string, fallback = \"pi-agents\"): string {\n\tconst safe = value\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9_.:-]+/g, \"-\")\n\t\t.replace(/^-+|-+$/g, \"\")\n\t\t.slice(0, 60);\n\treturn safe || fallback;\n}\nfunction makeJobId(): string {\n\treturn `tmux-${Date.now().toString(36)}-${crypto.randomBytes(4).toString(\"hex\")}`;\n}\nfunction safeStatusKey(value?: string): string {\n\tconst raw = value?.trim() || \"pi-agents\";\n\tif (!/^[a-zA-Z0-9_.:-]{1,80}$/.test(raw))\n\t\tthrow new Error(\"statusKey must be 1-80 chars: letters, numbers, _, ., :, or -\");\n\treturn raw;\n}\n\nfunction runTmux(args: string[], timeoutMs = 5_000): RunResult {\n\tconst tmux = process.env.PI_TMUX_MANAGER_TMUX_BIN || findExecutable(\"tmux\") || \"tmux\";\n\tconst result = spawnSync(tmux, args, {\n\t\tencoding: \"utf8\",\n\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\ttimeout: timeoutMs,\n\t\tmaxBuffer: 256 * 1024,\n\t});\n\treturn {\n\t\tok: !result.error && result.status === 0,\n\t\tstatus: result.status,\n\t\tstdout: cap(result.stdout || \"\"),\n\t\tstderr: cap(result.stderr || \"\"),\n\t\terror: result.error ? String(result.error.message || result.error) : undefined,\n\t\targs: [tmux, ...args],\n\t};\n}\nfunction detectTmux(): TmuxDetection {\n\tconst tmuxBin = process.env.PI_TMUX_MANAGER_TMUX_BIN || findExecutable(\"tmux\");\n\tconst errors: string[] = [];\n\tlet version: string | undefined;\n\tlet currentSession: string | undefined;\n\tlet sessions: string[] = [];\n\tconst insideTmux = Boolean(process.env.TMUX);\n\tif (!tmuxBin) errors.push(\"tmux CLI not found on PATH.\");\n\telse {\n\t\tconst versionRun = runTmux([\"-V\"], 2_000);\n\t\tif (versionRun.ok) version = versionRun.stdout.trim();\n\t\telse errors.push(`tmux -V failed: ${versionRun.error || versionRun.stderr || `exit ${versionRun.status}`}`);\n\t\tconst listRun = runTmux([\"list-sessions\", \"-F\", \"#{session_name}\"]);\n\t\tif (listRun.ok) sessions = listRun.stdout.trim() ? listRun.stdout.trim().split(/\\n+/) : [];\n\t\telse if (!/no server running/i.test(listRun.stderr))\n\t\t\terrors.push(`tmux list-sessions failed: ${listRun.error || listRun.stderr || `exit ${listRun.status}`}`);\n\t\tif (insideTmux) {\n\t\t\tconst sessionRun = runTmux([\"display-message\", \"-p\", \"#S\"], 2_000);\n\t\t\tif (sessionRun.ok) currentSession = sessionRun.stdout.trim();\n\t\t}\n\t}\n\treturn {\n\t\tinsideTmux,\n\t\ttmuxBin,\n\t\tcliAvailable: Boolean(tmuxBin),\n\t\tversion,\n\t\tcurrentSession,\n\t\tsessions,\n\t\tenv: { tmux: process.env.TMUX, term: process.env.TERM },\n\t\terrors,\n\t};\n}\nfunction formatDetection(d: TmuxDetection): string {\n\treturn [\n\t\t`tmux: ${d.cliAvailable ? \"available\" : \"missing\"}`,\n\t\td.tmuxBin ? `bin: ${d.tmuxBin}` : undefined,\n\t\td.version ? `version: ${d.version}` : undefined,\n\t\t`insideTmux: ${d.insideTmux}`,\n\t\td.currentSession ? `currentSession: ${d.currentSession}` : undefined,\n\t\td.sessions.length ? `sessions: ${d.sessions.join(\", \")}` : \"sessions: none\",\n\t\td.errors.length ? `errors:\\n- ${d.errors.join(\"\\n- \")}` : undefined,\n\t]\n\t\t.filter(Boolean)\n\t\t.join(\"\\n\");\n}\nfunction setupHelp(d: TmuxDetection): string {\n\tif (d.cliAvailable)\n\t\treturn `tmux CLI available: ${d.tmuxBin || \"tmux\"}\\nUse tmux_agent_manager action=workspace_plan or fire_task. Set dryRun=true only when a preview is useful.`;\n\treturn [\n\t\t\"tmux CLI not found.\",\n\t\t\"Install tmux for your environment, then reload Pi:\",\n\t\t\"- Debian/Ubuntu/WSL: sudo apt-get install tmux\",\n\t\t\"- Fedora: sudo dnf install tmux\",\n\t\t\"- Arch: sudo pacman -S tmux\",\n\t\t\"- macOS: brew install tmux\",\n\t\t\"- Windows: use WSL/MSYS2/Cygwin where a real tmux binary is available on PATH.\",\n\t\t\"cmux is macOS-only and intentionally not used by this tmux manager.\",\n\t].join(\"\\n\");\n}\nasync function guardTmux(_ctx: ExtensionContext, detection: TmuxDetection, purpose: string) {\n\tif (detection.cliAvailable) return { allowed: true, text: `tmux available for ${purpose}.` };\n\treturn { allowed: false, text: `${setupHelp(detection)}\\n\\nCannot run tmux-managed work until tmux is on PATH.` };\n}\nfunction tmuxManagerInstructions(toolName: string, detection: TmuxDetection): string {\n\treturn [\n\t\t`tmux is available (${detection.version || detection.tmuxBin || \"tmux\"}). For managed ${toolName} work, use tmux_agent_manager instead of direct foreground/background dispatch.`,\n\t\t\"Suggested next call:\",\n\t\t'tmux_agent_manager({ action: \"fire_task\", teamTemplate: \"builder-validator\", task: \"<objective>\" })',\n\t\t\"The launch returns immediately after panes, event watchers, and prompt handoffs are armed.\",\n\t\t\"Managed mode creates panes, prompt files, result files, event-driven terminal handoffs, tmux display-message notifications, @pi_* status options, shared variables, and one-shot deadlines.\",\n\t].join(\"\\n\");\n}\nfunction validateTemplate(value: unknown, source: string): TeamTemplate {\n\tif (!value || typeof value !== \"object\") throw new Error(`${source}: template must be an object`);\n\tconst template = value as TeamTemplate;\n\tif (!firstString(template.name)) throw new Error(`${source}: missing name`);\n\tif (!firstString(template.description)) throw new Error(`${source}: missing description`);\n\tif (!Array.isArray(template.agents) || template.agents.length < 1)\n\t\tthrow new Error(`${source}: agents must be a non-empty array`);\n\tif (template.agents.length > 12) throw new Error(`${source}: agents max is 12`);\n\ttemplate.agents.forEach((agent, index) => {\n\t\tconst provider = agent.provider || \"custom\";\n\t\tif (!Object.hasOwn(PROVIDER_COMMANDS, provider))\n\t\t\tthrow new Error(`${source}: unsupported provider at agents[${index}]: ${provider}`);\n\t\tif (provider === \"custom\" && !firstString(agent.command))\n\t\t\tthrow new Error(`${source}: custom agent ${agent.name || index} needs command`);\n\t});\n\treturn template;\n}\nfunction loadTemplateFiles(): { templates: TeamTemplate[]; errors: string[] } {\n\tconst templates: TeamTemplate[] = [];\n\tconst errors: string[] = [];\n\tfor (const dir of templateDirs()) {\n\t\tlet entries: fs.Dirent[] = [];\n\t\ttry {\n\t\t\tentries = fs.readdirSync(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const entry of entries) {\n\t\t\tif (!entry.isFile() || !entry.name.endsWith(\".json\")) continue;\n\t\t\tconst filePath = path.join(dir, entry.name);\n\t\t\ttry {\n\t\t\t\tconst parsed = JSON.parse(fs.readFileSync(filePath, \"utf8\"));\n\t\t\t\ttemplates.push(validateTemplate(parsed, filePath));\n\t\t\t} catch (error: unknown) {\n\t\t\t\terrors.push(`${filePath}: ${errorMessage(error)}`);\n\t\t\t}\n\t\t}\n\t}\n\treturn { templates, errors };\n}\nfunction getTeamTemplates(): { templates: TeamTemplate[]; errors: string[] } {\n\tconst byName = new Map<string, TeamTemplate>();\n\tfor (const template of TEAM_TEMPLATES) byName.set(template.name.toLowerCase(), template);\n\tconst loaded = loadTemplateFiles();\n\tfor (const template of loaded.templates) byName.set(template.name.toLowerCase(), template);\n\treturn { templates: Array.from(byName.values()), errors: loaded.errors };\n}\nfunction findTeamTemplate(name?: string): TeamTemplate | undefined {\n\tif (!name) return undefined;\n\tconst wanted = name.trim().toLowerCase();\n\treturn getTeamTemplates().templates.find((template) => template.name.toLowerCase() === wanted);\n}\nfunction requireTeamTemplate(name?: string): TeamTemplate {\n\tconst { templates, errors } = getTeamTemplates();\n\tconst wanted = name?.trim().toLowerCase();\n\tconst template = wanted ? templates.find((item) => item.name.toLowerCase() === wanted) : undefined;\n\tif (!template)\n\t\tthrow new Error(\n\t\t\t`unknown teamTemplate '${name || \"\"}'. Use action=list_templates.${errors.length ? ` Template load errors: ${errors.join(\"; \")}` : \"\"}`,\n\t\t);\n\treturn template;\n}\nfunction templateSummary(): { text: string; templates: TeamTemplate[]; errors: string[] } {\n\tconst loaded = getTeamTemplates();\n\tconst lines = loaded.templates.map((template) => `- ${template.name}: ${template.description}`);\n\tif (loaded.errors.length) lines.push(\"\", \"Template load errors:\", ...loaded.errors.map((error) => `- ${error}`));\n\treturn { text: lines.join(\"\\n\"), ...loaded };\n}\nfunction formatTemplate(template: TeamTemplate): string {\n\treturn JSON.stringify(template, null, 2);\n}\nfunction templateDefaults(params: Params): Partial<TeamTemplate> {\n\treturn findTeamTemplate(params.teamTemplate) || {};\n}\n\nfunction normalizeAgents(params: Params): AgentSpec[] {\n\tconst template = findTeamTemplate(params.teamTemplate);\n\tconst input: AgentSpec[] = params.agents?.length\n\t\t? params.agents\n\t\t: template?.agents?.length\n\t\t\t? template.agents\n\t\t\t: DEFAULT_AGENT_PROVIDERS.map((provider) => ({ provider }));\n\tif (input.length < 1) throw new Error(\"agents must contain at least one agent\");\n\tif (input.length > 12) throw new Error(\"agents max is 12\");\n\treturn input.map((agent, index) => {\n\t\tconst provider = agent.provider || \"custom\";\n\t\tif (!Object.hasOwn(PROVIDER_COMMANDS, provider)) throw new Error(`unsupported provider: ${provider}`);\n\t\tconst name =\n\t\t\tfirstString(agent.name, provider === \"custom\" ? `custom-${index + 1}` : provider) || `agent-${index + 1}`;\n\t\tconst baseCommand = firstString(agent.command, PROVIDER_COMMANDS[provider]);\n\t\tif (!baseCommand) throw new Error(`agent ${name} needs command when provider=custom`);\n\t\tconst tools = Array.isArray(agent.tools) && agent.tools.length > 0 ? agent.tools : undefined;\n\t\tconst command = tools ? `${baseCommand} --tools ${tools.join(\",\")}` : baseCommand;\n\t\treturn { provider, name, command, cwd: agent.cwd, tools };\n\t});\n}\nfunction defaultProviderInvocation(provider: Provider): string {\n\tswitch (provider) {\n\t\tcase \"pi\":\n\t\t\treturn \"pi\";\n\t\tcase \"agy\":\n\t\t\treturn \"agy\";\n\t\tcase \"codex\":\n\t\t\treturn \"codex\";\n\t\tcase \"claude\":\n\t\t\treturn \"claude\";\n\t\tcase \"opencode\":\n\t\t\treturn \"opencode\";\n\t\tcase \"custom\":\n\t\t\treturn \"\";\n\t}\n}\nfunction interactivePromptText(prompt: string): string {\n\treturn prompt.replace(/\\r?\\n/g, \"\\\\n\");\n}\nfunction spellMarker(marker: string): string {\n\treturn marker.split(\"\").join(\" \");\n}\nfunction managedPrompt(\n\ttask: string,\n\tjobId: string,\n\tagent: { name: string; provider: Provider },\n\tdoneMarker: string,\n\tblockedMarker: string,\n\tvarsPath: string,\n): string {\n\treturn [\n\t\t`You are ${agent.name} (${agent.provider}) working inside a tmux-managed Pi worker pane.`,\n\t\t`Job id: ${jobId}`,\n\t\t`Shared variable file: ${varsPath}`,\n\t\t\"\",\n\t\t\"Objective:\",\n\t\ttask,\n\t\t\"\",\n\t\t\"Rules:\",\n\t\t\"- Work autonomously until honest PASS or BLOCKED.\",\n\t\t\"- Verify important claims before PASS; include concise evidence.\",\n\t\t\"- If user input, credentials, destructive approval, publishing, or unavailable dependency blocks you, report BLOCKED instead of waiting silently.\",\n\t\t\"- Never print secrets/tokens. Prompts, commands, and logs persist under ~/.pi/agent/work/background/tmux-agent-manager/state/jobs.\",\n\t\t\"- If a task names an external decision variable, read it only at the decision point; never loop or poll the shared JSON file.\",\n\t\t\"\",\n\t\t\"Completion contract:\",\n\t\t\"Your final response must contain exactly one marker line. Build it by removing spaces from one of these character sequences:\",\n\t\t`  DONE: ${spellMarker(doneMarker)}`,\n\t\t`  BLOCKED: ${spellMarker(blockedMarker)}`,\n\t\t\"If BLOCKED, print a short reason on the next line. Do not print either marker until the final answer. After marker, stop.\",\n\t].join(\"\\n\");\n}\nfunction buildWorkspacePlan(ctx: ExtensionContext, params: Params) {\n\tconst cwd = resolveCwd(ctx, params.cwd);\n\tconst agents = normalizeAgents(params).map((agent, index) => ({\n\t\t...agent,\n\t\tcwd: resolveCwd(ctx, agent.cwd || cwd),\n\t\tid: `${safeName(agent.name || agent.provider || \"agent\")}-${index + 1}`,\n\t}));\n\tconst workspaceName = firstString(params.workspaceName, `pi-agents-${Date.now().toString(36)}`) || \"pi-agents\";\n\tconst sessionName = safeName(workspaceName, \"pi-agents\");\n\tconst launchCommands = agents.map(\n\t\t(agent) => `tmux pane: ${agent.name} -> cd ${quoteShell(agent.cwd)} && ${agent.command}`,\n\t);\n\treturn { workspaceName, sessionName, cwd, agents, launchCommands };\n}\nexport function makePaneWatcherScript(job: FireTaskPlan): string {\n\tconst agentCases = job.agents.flatMap((agent) => [\n\t\t`  ${agent.id})`,\n\t\t`    agent_name=${quoteShell(agent.name)}`,\n\t\t`    agent_id_json=${quoteShell(JSON.stringify(agent.id))}`,\n\t\t`    agent_name_json=${quoteShell(JSON.stringify(agent.name))}`,\n\t\t`    done_marker=${quoteShell(agent.doneMarker)}`,\n\t\t`    blocked_marker=${quoteShell(agent.blockedMarker)}`,\n\t\t`    log_path=${quoteShell(agent.logPath)}`,\n\t\t`    log_path_json=${quoteShell(JSON.stringify(agent.logPath))}`,\n\t\t`    result_path=${quoteShell(agent.resultPath)}`,\n\t\t`    stop_request_path=${quoteShell(`${agent.resultPath}.stop-requested`)}`,\n\t\t`    pane_id=${quoteShell(agent.paneId || \"\")}`,\n\t\t`    pane_id_json=${quoteShell(JSON.stringify(agent.paneId || null))}`,\n\t\t\"    ;;\",\n\t]);\n\treturn [\n\t\t\"#!/bin/sh\",\n\t\t\"set -eu\",\n\t\t\"umask 077\",\n\t\t\"LC_ALL=C\",\n\t\t\"export LC_ALL\",\n\t\t`job_id=${quoteShell(job.id)}`,\n\t\t`job_id_json=${quoteShell(JSON.stringify(job.id))}`,\n\t\t`session_name=${quoteShell(job.sessionName)}`,\n\t\t`deadline=${Math.max(1, job.deadlineSeconds)}`,\n\t\t// biome-ignore lint/suspicious/noTemplateCurlyInString: POSIX shell parameter expansion.\n\t\t\"agent_id=${1:-}\",\n\t\t'case \"$agent_id\" in',\n\t\t...agentCases,\n\t\t\"  *) printf 'unknown tmux agent id: %s\\\\n' \\\"$agent_id\\\" >&2; exit 2 ;;\",\n\t\t\"esac\",\n\t\t\"lock_path=$result_path.lock\",\n\t\t\"status_path=$result_path.status.$$\",\n\t\t\"timer_pid=\",\n\t\t\"awk_pid=\",\n\t\t\"finish() {\",\n\t\t\"  status=$1\",\n\t\t\"  notified_by=$2\",\n\t\t'  [ ! -e \"$result_path\" ] || return 0',\n\t\t'  mkdir \"$lock_path\" 2>/dev/null || return 0',\n\t\t\"  finished_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\n\t\t\"  temporary=$result_path.tmp.$$\",\n\t\t'  printf \\'{\\\\n  \"jobId\": %s,\\\\n  \"agentId\": %s,\\\\n  \"agentName\": %s,\\\\n  \"status\": \"%s\",\\\\n  \"exitCode\": null,\\\\n  \"logPath\": %s,\\\\n  \"paneId\": %s,\\\\n  \"finishedAt\": \"%s\",\\\\n  \"notifiedBy\": \"%s\"\\\\n}\\\\n\\' \\\\',\n\t\t'    \"$job_id_json\" \"$agent_id_json\" \"$agent_name_json\" \"$status\" \"$log_path_json\" \"$pane_id_json\" \"$finished_at\" \"$notified_by\" > \"$temporary\"',\n\t\t'  mv \"$temporary\" \"$result_path\"',\n\t\t'  rm -f \"$stop_request_path\"',\n\t\t\"  option_suffix=$(printf '%s' \\\"$job_id-$agent_id\\\" | tr -c 'A-Za-z0-9_.:-' '-')\",\n\t\t'  tmux set-option -t \"$session_name\" \"@pi_$option_suffix\" \"$status\" >/dev/null 2>&1 || true',\n\t\t'  tmux set-option -t \"$session_name\" \"@pi_$job_id\" \"$status:$agent_name\" >/dev/null 2>&1 || true',\n\t\t'  tmux display-message -t \"$session_name\" \"tmux agent $agent_name: $status (job $job_id)\" >/dev/null 2>&1 || true',\n\t\t\"}\",\n\t\t\"cleanup() {\",\n\t\t'  [ -z \"$timer_pid\" ] || kill \"$timer_pid\" 2>/dev/null || true',\n\t\t'  [ -z \"$awk_pid\" ] || kill \"$awk_pid\" 2>/dev/null || true',\n\t\t'  rm -f \"$status_path\"',\n\t\t\"}\",\n\t\t\"terminate() { cleanup; exit 0; }\",\n\t\t\"trap terminate TERM INT HUP\",\n\t\t\"trap cleanup EXIT\",\n\t\t\"parent_pid=$$\",\n\t\t\"exec 3<&0\",\n\t\t\"(\",\n\t\t\"  sleep_pid=\",\n\t\t'  stop_timer() { [ -z \"$sleep_pid\" ] || kill \"$sleep_pid\" 2>/dev/null || true; exit 0; }',\n\t\t\"  trap stop_timer TERM INT HUP\",\n\t\t'  sleep \"$deadline\" &',\n\t\t\"  sleep_pid=$!\",\n\t\t'  wait \"$sleep_pid\" 2>/dev/null || exit 0',\n\t\t\"  sleep_pid=\",\n\t\t'  if [ -e \"$stop_request_path\" ]; then finish stopped stop-requested-event; else finish timeout deadline-event; fi',\n\t\t'  kill -TERM \"$parent_pid\" 2>/dev/null || true',\n\t\t\") &\",\n\t\t\"timer_pid=$!\",\n\t\t\"logged_bytes=0\",\n\t\t'[ ! -f \"$log_path\" ] || logged_bytes=$(wc -c < \"$log_path\" | tr -d \\' \\')',\n\t\t'awk -v done=\"$done_marker\" -v blocked=\"$blocked_marker\" -v log_file=\"$log_path\" -v status_file=\"$status_path\" -v logged=\"$logged_bytes\" -v max=4194304 -v esc=\"$(printf \\'\\\\033\\')\" \\'',\n\t\t'function settle(status, reason) { print status \"|\" reason > status_file; close(status_file); settled = 1; exit }',\n\t\t\"{\",\n\t\t\"  raw = $0 ORS\",\n\t\t\"  remaining = max - logged\",\n\t\t'  if (remaining > 0) { if (length(raw) > remaining) raw = substr(raw, 1, remaining); printf \"%s\", raw >> log_file; logged += length(raw) }',\n\t\t\"  clean = $0\",\n\t\t'  gsub(esc \"\\\\\\\\[[0-9;?]*[ -/]*[@-~]\", \"\", clean)',\n\t\t'  gsub(/\\\\r/, \"\", clean)',\n\t\t'  sub(/^[ \\\\t]+/, \"\", clean); sub(/[ \\\\t]+$/, \"\", clean)',\n\t\t'  if (clean == done) settle(\"done\", \"pane-output-event\")',\n\t\t'  if (clean == blocked) settle(\"blocked\", \"pane-output-event\")',\n\t\t\"}\",\n\t\t'END { if (!settled) { print \"failed|pane-stream-ended\" > status_file; close(status_file) } }',\n\t\t\"' <&3 &\",\n\t\t\"awk_pid=$!\",\n\t\t'wait \"$awk_pid\" || true',\n\t\t\"awk_pid=\",\n\t\t'kill \"$timer_pid\" 2>/dev/null || true',\n\t\t'wait \"$timer_pid\" 2>/dev/null || true',\n\t\t\"timer_pid=\",\n\t\t'if [ -e \"$stop_request_path\" ]; then',\n\t\t\"  finish stopped stop-requested-event\",\n\t\t'elif [ -f \"$status_path\" ]; then',\n\t\t'  terminal=$(cat \"$status_path\")',\n\t\t// biome-ignore lint/suspicious/noTemplateCurlyInString: POSIX shell parameter expansion.\n\t\t'  finish \"${terminal%%|*}\" \"${terminal#*|}\"',\n\t\t\"else\",\n\t\t\"  finish failed watcher-status-missing\",\n\t\t\"fi\",\n\t\t\"exit 0\",\n\t].join(\"\\n\");\n}\nfunction buildFireTaskPlan(ctx: ExtensionContext, params: Params): FireTaskPlan {\n\tconst defaults = templateDefaults(params);\n\tconst task = firstString(params.task, params.body);\n\tif (!task) throw new Error(\"fire_task requires task (or body) with the worker objective\");\n\tconst cwd = resolveCwd(ctx, params.cwd);\n\tconst id = firstString(params.jobId) || makeJobId();\n\tif (!/^[a-zA-Z0-9_.:-]{4,80}$/.test(id))\n\t\tthrow new Error(\"jobId must be 4-80 chars: letters, numbers, _, ., :, or -\");\n\tconst jobDir = path.join(jobsRoot(), id);\n\tconst workspaceName = firstString(params.workspaceName, `Pi job ${id}`) || `Pi job ${id}`;\n\tconst sessionName = safeName(workspaceName, id);\n\tconst rawAgents = normalizeAgents(params);\n\tconst agents: FireAgentPlan[] = rawAgents.map((agent, index) => {\n\t\tconst provider = agent.provider || \"custom\";\n\t\tconst slug = `${safeName(agent.name || provider)}-${index + 1}`;\n\t\tconst markerBase = `TMUX_${crypto.createHash(\"sha1\").update(`${id}:${slug}`).digest(\"hex\").slice(0, 10).toUpperCase()}`;\n\t\tconst doneMarker = `${markerBase}_DONE`;\n\t\tconst blockedMarker = `${markerBase}_BLOCKED`;\n\t\treturn {\n\t\t\tid: slug,\n\t\t\tname: firstString(agent.name, provider) || slug,\n\t\t\tprovider,\n\t\t\tcommand: firstString(agent.command, PROVIDER_COMMANDS[provider]),\n\t\t\tcwd: resolveCwd(ctx, agent.cwd || cwd),\n\t\t\t// tools already baked into command by normalizeAgents\n\t\t\tdoneMarker,\n\t\t\tblockedMarker,\n\t\t\tpromptPath: path.join(jobDir, `${slug}.prompt.md`),\n\t\t\tlogPath: path.join(jobDir, `${slug}.log`),\n\t\t\tresultPath: path.join(jobDir, `${slug}.result.json`),\n\t\t};\n\t});\n\tconst job: FireTaskPlan = {\n\t\tid,\n\t\tcreatedAt: new Date().toISOString(),\n\t\tparentSessionFile: ctx.sessionManager.getSessionFile(),\n\t\tworkspaceName,\n\t\tsessionName,\n\t\tcwd,\n\t\ttask,\n\t\tteamTemplate: params.teamTemplate,\n\t\tdeadlineSeconds: clampInt(\n\t\t\tparams.deadlineSeconds,\n\t\t\tdefaults.deadlineSeconds || DEFAULT_DEADLINE_SECONDS,\n\t\t\t5,\n\t\t\tMAX_DEADLINE_SECONDS,\n\t\t),\n\t\tjobDir,\n\t\tjobPath: path.join(jobDir, \"job.json\"),\n\t\tvarsPath: path.join(jobDir, \"variables.json\"),\n\t\twatcherPath: path.join(jobDir, \"pane-watcher.sh\"),\n\t\tagents,\n\t\tlaunchCommands: [],\n\t};\n\tjob.launchCommands = agents.map(\n\t\t(agent) =>\n\t\t\t`${agent.command || defaultProviderInvocation(agent.provider)} then inject ${path.basename(agent.promptPath)}`,\n\t);\n\treturn job;\n}\nfunction archiveExistingJobDir(jobDir: string): string {\n\tconst root = archiveRoot();\n\tensureDir(root);\n\tconst target = path.join(root, `${path.basename(jobDir)}-${new Date().toISOString().replace(/[:.]/g, \"-\")}`);\n\tfs.renameSync(jobDir, target);\n\treturn target;\n}\nfunction prepareJobDirForLaunch(job: FireTaskPlan, force?: boolean): string | undefined {\n\tif (!fs.existsSync(job.jobDir)) return undefined;\n\tif (!force)\n\t\tthrow new Error(\n\t\t\t`tmux job already exists: ${job.id}. Use a new jobId, or pass force:true to archive the old job before launching.`,\n\t\t);\n\treturn archiveExistingJobDir(job.jobDir);\n}\nfunction writeFireTaskFiles(job: FireTaskPlan): void {\n\tensureDir(job.jobDir);\n\tif (!fs.existsSync(job.varsPath))\n\t\tfs.writeFileSync(job.varsPath, `${JSON.stringify({ updatedAt: null, variables: {} }, null, 2)}\\n`, {\n\t\t\tmode: 0o600,\n\t\t});\n\tfor (const agent of job.agents) {\n\t\tfs.writeFileSync(\n\t\t\tagent.promptPath,\n\t\t\t`${managedPrompt(job.task, job.id, agent, agent.doneMarker, agent.blockedMarker, job.varsPath)}\\n`,\n\t\t\t{ mode: 0o600 },\n\t\t);\n\t\tfs.writeFileSync(\n\t\t\tagent.logPath,\n\t\t\t`[tmux-agent-manager] waiting for captured pane output\\njob=${job.id} agent=${agent.name} pane=${agent.paneId || \"pending\"} command=${agent.command || defaultProviderInvocation(agent.provider)}\\n`,\n\t\t\t{ mode: 0o600 },\n\t\t);\n\t}\n\tfs.writeFileSync(job.watcherPath, makePaneWatcherScript(job), { mode: 0o700 });\n\tfs.chmodSync(job.watcherPath, 0o700);\n\tfs.writeFileSync(\n\t\tjob.jobPath,\n\t\t`${JSON.stringify({ ...job, agents: job.agents.map((agent) => ({ ...agent, result: null })) }, null, 2)}\\n`,\n\t\t{ mode: 0o600 },\n\t);\n}\nfunction startPaneWatchers(job: FireTaskPlan): Array<{ agentId: string; paneId: string }> {\n\tconst started: Array<{ agentId: string; paneId: string }> = [];\n\tfor (const agent of job.agents) {\n\t\tif (!agent.paneId) throw new Error(`Missing pane id for tmux agent ${agent.name}`);\n\t\tconst command = `sh ${quoteShell(job.watcherPath)} ${quoteShell(agent.id)}`;\n\t\tconst result = runTmux([\"pipe-pane\", \"-O\", \"-t\", agent.paneId, command]);\n\t\tif (!result.ok) {\n\t\t\tthrow new Error(\n\t\t\t\t`Failed to arm completion watcher for ${agent.name}: ${result.error || result.stderr || result.stdout}`,\n\t\t\t);\n\t\t}\n\t\tstarted.push({ agentId: agent.id, paneId: agent.paneId });\n\t}\n\treturn started;\n}\nfunction targetDisplayName(agent: AgentSpec, index: number): string {\n\treturn firstString(agent.name, agent.provider, `agent-${index + 1}`) || `agent-${index + 1}`;\n}\nfunction tmuxSessionExists(name: string): boolean {\n\treturn runTmux([\"has-session\", \"-t\", name], 2_000).ok;\n}\nfunction sendCommandToPane(paneId: string, command: string): void {\n\trunTmux([\"send-keys\", \"-t\", paneId, \"-l\", command]);\n\trunTmux([\"send-keys\", \"-t\", paneId, \"Enter\"]);\n}\nfunction launchTmuxSession(\n\tsessionName: string,\n\tcwd: string,\n\tpanes: Array<{ title: string; cwd: string; command: string }>,\n): { runs: RunResult[]; paneIds: string[] } {\n\tif (tmuxSessionExists(sessionName))\n\t\tthrow new Error(\n\t\t\t`tmux session already exists: ${sessionName}. Use stop_session/stop_job first or choose a different workspaceName.`,\n\t\t);\n\tconst runs: RunResult[] = [];\n\tconst paneIds: string[] = [];\n\tconst first = panes[0];\n\tconst create = runTmux(\n\t\t[\"new-session\", \"-d\", \"-P\", \"-F\", \"#{pane_id}\", \"-s\", sessionName, \"-n\", \"agents\", \"-c\", first.cwd || cwd],\n\t\t5_000,\n\t);\n\truns.push(create);\n\tif (!create.ok)\n\t\tthrow new Error(`tmux new-session failed: ${create.error || create.stderr || `exit ${create.status}`}`);\n\tconst firstPane = create.stdout.trim();\n\tpaneIds.push(firstPane);\n\tsendCommandToPane(firstPane, first.command);\n\tfor (const pane of panes.slice(1)) {\n\t\tconst split = runTmux(\n\t\t\t[\"split-window\", \"-d\", \"-P\", \"-F\", \"#{pane_id}\", \"-t\", `${sessionName}:0`, \"-c\", pane.cwd || cwd],\n\t\t\t5_000,\n\t\t);\n\t\truns.push(split);\n\t\tif (!split.ok)\n\t\t\tthrow new Error(`tmux split-window failed: ${split.error || split.stderr || `exit ${split.status}`}`);\n\t\tconst paneId = split.stdout.trim();\n\t\tpaneIds.push(paneId);\n\t\tsendCommandToPane(paneId, pane.command);\n\t}\n\truns.push(runTmux([\"select-layout\", \"-t\", `${sessionName}:0`, \"tiled\"], 3_000));\n\treturn { runs, paneIds };\n}\nfunction injectPromptToPane(paneId: string, prompt: string, provider: Provider): void {\n\tconst text = interactivePromptText(prompt);\n\tif (provider === \"claude\") {\n\t\tconst bufferName = `pi-tmux-${crypto.randomBytes(4).toString(\"hex\")}`;\n\t\trunTmux([\"set-buffer\", \"-b\", bufferName, text], 10_000);\n\t\trunTmux([\"paste-buffer\", \"-b\", bufferName, \"-t\", paneId], 10_000);\n\t\trunTmux([\"send-keys\", \"-t\", paneId, \"Enter\"], 3_000);\n\t\trunTmux([\"delete-buffer\", \"-b\", bufferName], 3_000);\n\t\treturn;\n\t}\n\trunTmux([\"send-keys\", \"-t\", paneId, \"-l\", text], 10_000);\n\trunTmux([\"send-keys\", \"-t\", paneId, provider === \"agy\" ? \"C-m\" : \"Enter\"], 3_000);\n}\nfunction stopTmuxSession(\n\tsessionName: string,\n\tdryRun: boolean,\n\tconfirm?: string,\n): { text: string; run?: RunResult; existed: boolean } {\n\tif (!sessionName) throw new Error(\"session name required\");\n\tconst existed = tmuxSessionExists(sessionName);\n\tif (!existed) return { text: `tmux session not running: ${sessionName}`, existed: false };\n\tif (dryRun) return { text: `DRY RUN would stop tmux session: ${sessionName}`, existed: true };\n\tif (confirm !== \"yes-tmux-stop\") throw new Error(\"real stop requires confirm=yes-tmux-stop\");\n\tconst run = runTmux([\"kill-session\", \"-t\", sessionName], 5_000);\n\tif (!run.ok) throw new Error(`tmux kill-session failed: ${run.error || run.stderr || `exit ${run.status}`}`);\n\treturn { text: `Stopped tmux session: ${sessionName}`, run, existed: true };\n}\nfunction isAlreadyExistsError(error: unknown): boolean {\n\treturn typeof error === \"object\" && error !== null && \"code\" in error && error.code === \"EEXIST\";\n}\nfunction markStopRequested(job: FireTaskPlan): void {\n\tfor (const agent of job.agents) {\n\t\tif (fs.existsSync(agent.resultPath)) continue;\n\t\ttry {\n\t\t\tfs.writeFileSync(`${agent.resultPath}.stop-requested`, `${new Date().toISOString()}\\n`, {\n\t\t\t\tencoding: \"utf8\",\n\t\t\t\tmode: 0o600,\n\t\t\t\tflag: \"wx\",\n\t\t\t});\n\t\t} catch (error: unknown) {\n\t\t\tif (!isAlreadyExistsError(error)) throw error;\n\t\t}\n\t}\n}\nfunction clearStopRequested(job: FireTaskPlan): void {\n\tfor (const agent of job.agents) fs.rmSync(`${agent.resultPath}.stop-requested`, { force: true });\n}\nfunction persistStoppedResults(job: FireTaskPlan): void {\n\tfor (const agent of job.agents) {\n\t\tif (!fs.existsSync(agent.resultPath)) {\n\t\t\tconst result = {\n\t\t\t\tjobId: job.id,\n\t\t\t\tagentId: agent.id,\n\t\t\t\tagentName: agent.name,\n\t\t\t\tstatus: \"stopped\",\n\t\t\t\texitCode: null,\n\t\t\t\tlogPath: agent.logPath,\n\t\t\t\tpaneId: agent.paneId || null,\n\t\t\t\tfinishedAt: new Date().toISOString(),\n\t\t\t\tnotifiedBy: \"stop-action-event\",\n\t\t\t};\n\t\t\ttry {\n\t\t\t\tfs.writeFileSync(agent.resultPath, `${JSON.stringify(result, null, 2)}\\n`, {\n\t\t\t\t\tencoding: \"utf8\",\n\t\t\t\t\tmode: 0o600,\n\t\t\t\t\tflag: \"wx\",\n\t\t\t\t});\n\t\t\t} catch (error: unknown) {\n\t\t\t\tif (!isAlreadyExistsError(error)) throw error;\n\t\t\t}\n\t\t}\n\t\tfs.rmSync(`${agent.resultPath}.stop-requested`, { force: true });\n\t}\n}\nfunction stopTmuxSessionWithJobSignals(\n\tsessionName: string,\n\tjobs: FireTaskPlan[],\n\tdryRun: boolean,\n\tconfirm?: string,\n): { text: string; run?: RunResult; existed: boolean } {\n\tif (!dryRun && confirm !== \"yes-tmux-stop\") throw new Error(\"real stop requires confirm=yes-tmux-stop\");\n\tif (!dryRun) for (const job of jobs) markStopRequested(job);\n\ttry {\n\t\tconst result = stopTmuxSession(sessionName, dryRun, confirm);\n\t\tif (!dryRun) for (const job of jobs) persistStoppedResults(job);\n\t\treturn result;\n\t} catch (error: unknown) {\n\t\tfor (const job of jobs) clearStopRequested(job);\n\t\tthrow error;\n\t}\n}\nfunction formatWorkspacePreview(plan: ReturnType<typeof buildWorkspacePlan>): string {\n\treturn [\n\t\t`Session: ${plan.sessionName}`,\n\t\t`Cwd: ${plan.cwd}`,\n\t\t\"Panes:\",\n\t\t...plan.agents.map((agent, index) => `- ${targetDisplayName(agent, index)}: ${agent.command} (cwd ${agent.cwd})`),\n\t].join(\"\\n\");\n}\nfunction formatFireTaskPreview(job: FireTaskPlan): string {\n\treturn [\n\t\t`Job: ${job.id}`,\n\t\t`Session: ${job.sessionName}`,\n\t\t`Cwd: ${job.cwd}`,\n\t\t`State: ${job.jobPath}`,\n\t\t`Deadline: ${job.deadlineSeconds}s enforced by each event-driven pane watcher`,\n\t\t\"Workers:\",\n\t\t...job.agents.map((agent) => `- ${agent.name}: ${agent.command || defaultProviderInvocation(agent.provider)}`),\n\t].join(\"\\n\");\n}\nfunction loadJob(id: string): FireTaskPlan {\n\tconst jobPath = path.join(jobsRoot(), id, \"job.json\");\n\tif (!fs.existsSync(jobPath)) throw new Error(`tmux job not found: ${id}`);\n\tconst parsed = JSON.parse(fs.readFileSync(jobPath, \"utf8\")) as FireTaskPlan;\n\tif (!Array.isArray(parsed.agents)) throw new Error(`tmux job has invalid agents: ${id}`);\n\tfor (const agent of parsed.agents) {\n\t\ttry {\n\t\t\tagent.result = JSON.parse(fs.readFileSync(agent.resultPath, \"utf8\")) as AgentResult;\n\t\t} catch {\n\t\t\tdelete agent.result;\n\t\t}\n\t}\n\ttry {\n\t\tparsed.variables = readVariables(parsed.varsPath);\n\t} catch {\n\t\tparsed.variables = { updatedAt: null, variables: {} };\n\t}\n\treturn parsed;\n}\nfunction loadJobPlans(): FireTaskPlan[] {\n\ttry {\n\t\treturn fs\n\t\t\t.readdirSync(jobsRoot(), { withFileTypes: true })\n\t\t\t.filter((entry) => entry.isDirectory())\n\t\t\t.flatMap((entry) => {\n\t\t\t\ttry {\n\t\t\t\t\treturn [loadJob(entry.name)];\n\t\t\t\t} catch {\n\t\t\t\t\treturn [];\n\t\t\t\t}\n\t\t\t});\n\t} catch {\n\t\treturn [];\n\t}\n}\nfunction listJobs(): unknown[] {\n\ttry {\n\t\treturn fs\n\t\t\t.readdirSync(jobsRoot(), { withFileTypes: true })\n\t\t\t.filter((d) => d.isDirectory())\n\t\t\t.map((d) => {\n\t\t\t\ttry {\n\t\t\t\t\tconst job = loadJob(d.name);\n\t\t\t\t\treturn {\n\t\t\t\t\t\tid: job.id,\n\t\t\t\t\t\tworkspaceName: job.workspaceName,\n\t\t\t\t\t\tsessionName: job.sessionName,\n\t\t\t\t\t\tcreatedAt: job.createdAt,\n\t\t\t\t\t\tagents: job.agents.map((agent) => ({ name: agent.name, status: agent.result?.status || \"pending\" })),\n\t\t\t\t\t};\n\t\t\t\t} catch (error: unknown) {\n\t\t\t\t\treturn { id: d.name, error: errorMessage(error) };\n\t\t\t\t}\n\t\t\t});\n\t} catch {\n\t\treturn [];\n\t}\n}\nfunction readVariables(varsPath: string): { updatedAt: string | null; variables: Record<string, unknown> } {\n\ttry {\n\t\treturn JSON.parse(fs.readFileSync(varsPath, \"utf8\"));\n\t} catch {\n\t\treturn { updatedAt: null, variables: {} };\n\t}\n}\nfunction setVariable(jobId: string, name: string, value: string) {\n\tif (!/^[a-zA-Z0-9_.:-]{1,80}$/.test(name))\n\t\tthrow new Error(\"variableName must be 1-80 chars: letters, numbers, _, ., :, or -\");\n\tconst job = loadJob(jobId);\n\tconst current = readVariables(job.varsPath);\n\tcurrent.variables[name] = value;\n\tcurrent.updatedAt = new Date().toISOString();\n\tfs.writeFileSync(job.varsPath, `${JSON.stringify(current, null, 2)}\\n`, { mode: 0o600 });\n\treturn { varsPath: job.varsPath, variables: current.variables, updatedAt: current.updatedAt };\n}\nasync function executeTool(\n\t_toolCallId: string,\n\tparams: Params,\n\t_signal: AbortSignal | undefined,\n\t_onUpdate: unknown,\n\tctx: ExtensionContext,\n): Promise<AgentToolResult<unknown>> {\n\tconst action = params.action || \"status\";\n\tconst detection = detectTmux();\n\tif (action === \"status\")\n\t\treturn { content: [{ type: \"text\", text: formatDetection(detection) }], details: { action, detection } };\n\tif (action === \"setup_help\")\n\t\treturn { content: [{ type: \"text\", text: setupHelp(detection) }], details: { action, detection } };\n\tif (action === \"guard\") {\n\t\tconst guard = await guardTmux(ctx, detection, \"tmux-managed interactive subagent/provider orchestration\");\n\t\treturn { content: [{ type: \"text\", text: guard.text }], details: { action, detection, guard } };\n\t}\n\tif (action === \"list_jobs\")\n\t\treturn { content: [{ type: \"text\", text: JSON.stringify(listJobs(), null, 2) }], details: { action } };\n\tif (action === \"list_templates\") {\n\t\tconst summary = templateSummary();\n\t\treturn {\n\t\t\tcontent: [{ type: \"text\", text: summary.text }],\n\t\t\tdetails: { action, templates: summary.templates, errors: summary.errors, templateDirs: templateDirs() },\n\t\t};\n\t}\n\tif (action === \"show_template\") {\n\t\tconst template = requireTeamTemplate(params.teamTemplate || params.title);\n\t\treturn { content: [{ type: \"text\", text: formatTemplate(template) }], details: { action, template } };\n\t}\n\tif (action === \"job_status\") {\n\t\tif (!params.jobId) throw new Error(\"job_status requires jobId\");\n\t\tconst job = loadJob(params.jobId);\n\t\treturn { content: [{ type: \"text\", text: JSON.stringify(job, null, 2) }], details: { action, job } };\n\t}\n\tif (action === \"list_variables\") {\n\t\tif (!params.jobId) throw new Error(\"list_variables requires jobId\");\n\t\tconst job = loadJob(params.jobId);\n\t\treturn {\n\t\t\tcontent: [{ type: \"text\", text: JSON.stringify(job.variables || { variables: {} }, null, 2) }],\n\t\t\tdetails: { action, jobId: params.jobId, variables: job.variables },\n\t\t};\n\t}\n\tif (action === \"set_variable\") {\n\t\tif (!params.jobId) throw new Error(\"set_variable requires jobId\");\n\t\tif (!params.variableName) throw new Error(\"set_variable requires variableName\");\n\t\tconst value = firstString(params.variableValue, params.body, params.status, \"\") || \"\";\n\t\tconst result = setVariable(params.jobId, params.variableName, value);\n\t\treturn {\n\t\t\tcontent: [\n\t\t\t\t{\n\t\t\t\t\ttype: \"text\",\n\t\t\t\t\ttext: `Set tmux job variable ${params.variableName} for ${params.jobId}. Workers read ${result.varsPath} only at the named decision point.`,\n\t\t\t\t},\n\t\t\t],\n\t\t\tdetails: { action, jobId: params.jobId, variableName: params.variableName, result },\n\t\t};\n\t}\n\tconst guard = await guardTmux(ctx, detection, `tmux ${action}`);\n\tif (!guard.allowed)\n\t\treturn { content: [{ type: \"text\", text: guard.text }], details: { action, detection, guard, skipped: true } };\n\tif (action === \"stop_job\") {\n\t\tif (!params.jobId) throw new Error(\"stop_job requires jobId\");\n\t\tconst job = loadJob(params.jobId);\n\t\tconst result = stopTmuxSessionWithJobSignals(job.sessionName, [job], params.dryRun !== false, params.confirm);\n\t\treturn {\n\t\t\tcontent: [{ type: \"text\", text: result.text }],\n\t\t\tdetails: {\n\t\t\t\taction,\n\t\t\t\tdetection,\n\t\t\t\tjobId: params.jobId,\n\t\t\t\tsessionName: job.sessionName,\n\t\t\t\tdryRun: params.dryRun !== false,\n\t\t\t\tresult,\n\t\t\t},\n\t\t};\n\t}\n\tif (action === \"stop_session\") {\n\t\tconst sessionName = firstString(params.workspaceName, params.title);\n\t\tif (!sessionName) throw new Error(\"stop_session requires workspaceName or title with the tmux session name\");\n\t\tconst jobs = loadJobPlans().filter((job) => job.sessionName === sessionName);\n\t\tconst result = stopTmuxSessionWithJobSignals(sessionName, jobs, params.dryRun !== false, params.confirm);\n\t\treturn {\n\t\t\tcontent: [{ type: \"text\", text: result.text }],\n\t\t\tdetails: { action, detection, sessionName, dryRun: params.dryRun !== false, result },\n\t\t};\n\t}\n\tif (action === \"workspace_plan\" || action === \"launch_workspace\") {\n\t\tconst plan = buildWorkspacePlan(ctx, params);\n\t\tconst preview = formatWorkspacePreview(plan);\n\t\tif (action === \"workspace_plan\" || params.dryRun === true)\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: `DRY RUN tmux workspace plan\\n${preview}` }],\n\t\t\t\tdetails: { action, detection, dryRun: true, plan },\n\t\t\t};\n\t\tconst panes = plan.agents.map((agent, index) => ({\n\t\t\ttitle: targetDisplayName(agent, index),\n\t\t\tcwd: agent.cwd || plan.cwd,\n\t\t\tcommand: agent.command || PROVIDER_COMMANDS[agent.provider || \"custom\"],\n\t\t}));\n\t\tconst launch = launchTmuxSession(plan.sessionName, plan.cwd, panes);\n\t\treturn {\n\t\t\tcontent: [\n\t\t\t\t{\n\t\t\t\t\ttype: \"text\",\n\t\t\t\t\ttext: `Launched tmux session '${plan.sessionName}'. Attach with: tmux attach -t ${plan.sessionName}`,\n\t\t\t\t},\n\t\t\t],\n\t\t\tdetails: { action, detection, runs: launch.runs, paneIds: launch.paneIds, plan },\n\t\t};\n\t}\n\tif (action === \"fire_task\") {\n\t\tconst job = buildFireTaskPlan(ctx, params);\n\t\tif (params.dryRun === true)\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: `DRY RUN tmux interactive task\\n${formatFireTaskPreview(job)}` }],\n\t\t\t\tdetails: { action, detection, dryRun: true, job },\n\t\t\t};\n\t\tif (tmuxSessionExists(job.sessionName))\n\t\t\tthrow new Error(\n\t\t\t\t`tmux session already exists: ${job.sessionName}. Use stop_job/stop_session first or choose a different workspaceName.`,\n\t\t\t);\n\t\tconst archivedJobDir = prepareJobDirForLaunch(job, params.force);\n\t\tconst panes = job.agents.map((agent) => ({\n\t\t\ttitle: agent.name,\n\t\t\tcwd: agent.cwd,\n\t\t\tcommand: agent.command || defaultProviderInvocation(agent.provider),\n\t\t}));\n\t\tconst launch = launchTmuxSession(job.sessionName, job.cwd, panes);\n\t\tjob.agents.forEach((agent, index) => {\n\t\t\tagent.paneId = launch.paneIds[index];\n\t\t});\n\t\twriteFireTaskFiles(job);\n\t\tconst watcherPanes = startPaneWatchers(job);\n\t\tfor (const agent of job.agents) {\n\t\t\tif (!agent.paneId) continue;\n\t\t\tinjectPromptToPane(agent.paneId, fs.readFileSync(agent.promptPath, \"utf8\"), agent.provider);\n\t\t}\n\t\treturn {\n\t\t\tcontent: [\n\t\t\t\t{\n\t\t\t\t\ttype: \"text\",\n\t\t\t\t\ttext: [\n\t\t\t\t\t\t`Launched tmux interactive fire-and-forget job ${job.id}.`,\n\t\t\t\t\t\t`Session: ${job.sessionName}`,\n\t\t\t\t\t\t`Attach: tmux attach -t ${job.sessionName}`,\n\t\t\t\t\t\t`Job state: ${job.jobPath}`,\n\t\t\t\t\t\tarchivedJobDir ? `Archived previous job dir: ${archivedJobDir}` : undefined,\n\t\t\t\t\t\t\"Completion: event-driven pane output watchers armed (no polling).\",\n\t\t\t\t\t]\n\t\t\t\t\t\t.filter(Boolean)\n\t\t\t\t\t\t.join(\"\\n\"),\n\t\t\t\t},\n\t\t\t],\n\t\t\tdetails: { action, detection, job, runs: launch.runs, paneIds: launch.paneIds, watcherPanes, archivedJobDir },\n\t\t};\n\t}\n\tif (action === \"notify\") {\n\t\tconst title = firstString(params.title, \"Pi\") || \"Pi\";\n\t\tconst body = firstString(params.body, \"Pi needs attention\") || \"Pi needs attention\";\n\t\tconst target = firstString(params.workspaceName, detection.currentSession, detection.sessions[0]);\n\t\tif (!target) throw new Error(\"notify requires an active tmux session or workspaceName target\");\n\t\tconst run = runTmux([\"display-message\", \"-t\", target, `${title}: ${body}`], 3_000);\n\t\tif (!run.ok) throw new Error(`tmux display-message failed: ${run.error || run.stderr || `exit ${run.status}`}`);\n\t\treturn {\n\t\t\tcontent: [{ type: \"text\", text: `Sent tmux display-message to ${target}: ${title}` }],\n\t\t\tdetails: { action, detection, run },\n\t\t};\n\t}\n\tif (action === \"set_status\") {\n\t\tconst key = safeStatusKey(params.statusKey);\n\t\tconst value = firstString(params.status, params.body, \"\") || \"\";\n\t\tconst target = firstString(params.workspaceName, detection.currentSession, detection.sessions[0]);\n\t\tconst args = target\n\t\t\t? [\"set-option\", \"-t\", target, `@pi_${key}`, value]\n\t\t\t: [\"set-option\", \"-g\", `@pi_${key}`, value];\n\t\tconst run = runTmux(args, 3_000);\n\t\tif (!run.ok) throw new Error(`tmux set-option failed: ${run.error || run.stderr || `exit ${run.status}`}`);\n\t\treturn {\n\t\t\tcontent: [{ type: \"text\", text: `Set tmux user option @pi_${key}=${value}` }],\n\t\t\tdetails: { action, detection, run },\n\t\t};\n\t}\n\tif (action === \"clear_status\") {\n\t\tconst key = safeStatusKey(params.statusKey);\n\t\tconst target = firstString(params.workspaceName, detection.currentSession, detection.sessions[0]);\n\t\tconst args = target ? [\"set-option\", \"-u\", \"-t\", target, `@pi_${key}`] : [\"set-option\", \"-gu\", `@pi_${key}`];\n\t\tconst run = runTmux(args, 3_000);\n\t\tif (!run.ok) throw new Error(`tmux clear status failed: ${run.error || run.stderr || `exit ${run.status}`}`);\n\t\treturn {\n\t\t\tcontent: [{ type: \"text\", text: `Cleared tmux user option @pi_${key}` }],\n\t\t\tdetails: { action, detection, run },\n\t\t};\n\t}\n\tthrow new Error(`unsupported action: ${action}`);\n}\n\nfunction isFireTaskTerminal(job: FireTaskPlan): boolean {\n\treturn job.agents.length > 0 && job.agents.every((agent) => agent.result !== undefined);\n}\n\nfunction readBoundedLogTail(filePath: string, maxBytes = 2048): string {\n\ttry {\n\t\tconst size = fs.statSync(filePath).size;\n\t\tconst length = Math.min(size, maxBytes);\n\t\tconst buffer = Buffer.alloc(length);\n\t\tconst descriptor = fs.openSync(filePath, \"r\");\n\t\ttry {\n\t\t\tfs.readSync(descriptor, buffer, 0, length, Math.max(0, size - length));\n\t\t} finally {\n\t\t\tfs.closeSync(descriptor);\n\t\t}\n\t\treturn buffer.toString(\"utf8\").replace(/<(?=\\/?untrusted_content\\b)/gi, \"&lt;\");\n\t} catch {\n\t\treturn \"(no captured output)\";\n\t}\n}\n\nfunction formatFireTaskHandoff(job: FireTaskPlan): string {\n\tconst included = job.agents.slice(0, 4);\n\treturn [\n\t\t`tmux background task terminal handoff: ${job.id}`,\n\t\t`session: ${job.sessionName}`,\n\t\t...included.flatMap((agent) => [\n\t\t\t`- ${agent.name}: ${agent.result?.status ?? \"unknown\"}`,\n\t\t\t`<untrusted_content source=\"tmux_agent:${job.id}:${agent.id}\">`,\n\t\t\treadBoundedLogTail(agent.logPath),\n\t\t\t\"</untrusted_content>\",\n\t\t]),\n\t\t...(job.agents.length > included.length\n\t\t\t? [`- ${job.agents.length - included.length} additional agent handoff(s) omitted.`]\n\t\t\t: []),\n\t\t\"This event woke the parent; do not poll. Continue safe scoped work from the bounded handoff and inspect terminal artifacts only if needed for a material claim.\",\n\t].join(\"\\n\");\n}\n\nfunction markFireTaskNotified(job: FireTaskPlan): void {\n\tconst current = JSON.parse(fs.readFileSync(job.jobPath, \"utf8\")) as FireTaskPlan;\n\tcurrent.notifiedAt = new Date().toISOString();\n\tconst temporaryPath = `${job.jobPath}.tmp-${process.pid}-${Date.now()}`;\n\tfs.writeFileSync(temporaryPath, `${JSON.stringify(current, null, 2)}\\n`, { encoding: \"utf8\", mode: 0o600 });\n\tfs.renameSync(temporaryPath, job.jobPath);\n\tjob.notifiedAt = current.notifiedAt;\n}\n\nexport default function tmuxAgentManagerExtension(pi: ExtensionAPI) {\n\tlet handoffContext: ExtensionContext | undefined;\n\tlet handoffTail = Promise.resolve();\n\tconst jobWatchers = new Map<string, fs.FSWatcher>();\n\n\tconst closeJobWatchers = () => {\n\t\tfor (const watcher of jobWatchers.values()) watcher.close();\n\t\tjobWatchers.clear();\n\t};\n\n\tconst refreshJobHandoffs = async (ctx: ExtensionContext): Promise<void> => {\n\t\tconst sessionFile = ctx.sessionManager.getSessionFile();\n\t\tconst jobs = loadJobPlans().filter((job) => !job.parentSessionFile || job.parentSessionFile === sessionFile);\n\t\tfor (const job of jobs) {\n\t\t\tif (!isFireTaskTerminal(job) || job.notifiedAt) continue;\n\t\t\tpi.sendMessage(\n\t\t\t\t{\n\t\t\t\t\tcustomType: \"tmux-background-completion\",\n\t\t\t\t\tcontent: formatFireTaskHandoff(job),\n\t\t\t\t\tdisplay: true,\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\tjobId: job.id,\n\t\t\t\t\t\tsessionName: job.sessionName,\n\t\t\t\t\t\tagents: job.agents.map((agent) => ({ id: agent.id, name: agent.name, status: agent.result?.status })),\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\t{ triggerTurn: true, deliverAs: \"followUp\" },\n\t\t\t);\n\t\t\tmarkFireTaskNotified(job);\n\t\t\tif (ctx.hasUI) ctx.ui.notify(`tmux background task ${job.id} completed.`, \"info\");\n\t\t}\n\n\t\tconst activeIds = new Set(jobs.filter((job) => !isFireTaskTerminal(job)).map((job) => job.id));\n\t\tfor (const [jobId, watcher] of jobWatchers) {\n\t\t\tif (activeIds.has(jobId)) continue;\n\t\t\twatcher.close();\n\t\t\tjobWatchers.delete(jobId);\n\t\t}\n\t\tfor (const job of jobs) {\n\t\t\tif (isFireTaskTerminal(job) || jobWatchers.has(job.id)) continue;\n\t\t\ttry {\n\t\t\t\tconst watcher = fs.watch(job.jobDir, { persistent: false }, (_event, fileName) => {\n\t\t\t\t\tif (fileName && !String(fileName).endsWith(\".result.json\") && String(fileName) !== \"job.json\") return;\n\t\t\t\t\tif (handoffContext) void queueJobHandoffRefresh(handoffContext);\n\t\t\t\t});\n\t\t\t\twatcher.on(\"error\", (error) => {\n\t\t\t\t\twatcher.close();\n\t\t\t\t\tjobWatchers.delete(job.id);\n\t\t\t\t\tif (ctx.hasUI) ctx.ui.notify(`tmux completion signal failed for ${job.id}: ${error.message}`, \"warning\");\n\t\t\t\t});\n\t\t\t\tjobWatchers.set(job.id, watcher);\n\t\t\t} catch (error: unknown) {\n\t\t\t\tif (ctx.hasUI)\n\t\t\t\t\tctx.ui.notify(`tmux completion signal failed for ${job.id}: ${errorMessage(error)}`, \"warning\");\n\t\t\t}\n\t\t}\n\t};\n\n\tfunction queueJobHandoffRefresh(ctx: ExtensionContext): Promise<void> {\n\t\tconst refresh = handoffTail.then(() => refreshJobHandoffs(ctx));\n\t\tconst guarded = refresh.catch((error: unknown) => {\n\t\t\tif (ctx.hasUI) {\n\t\t\t\tctx.ui.notify(\n\t\t\t\t\t`tmux terminal handoff failed: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t\t\t\"warning\",\n\t\t\t\t);\n\t\t\t}\n\t\t});\n\t\thandoffTail = guarded;\n\t\treturn guarded;\n\t}\n\n\tpi.on(\"session_start\", async (_event, ctx) => {\n\t\thandoffContext = ctx;\n\t\tcloseJobWatchers();\n\t\tawait queueJobHandoffRefresh(ctx);\n\t});\n\tpi.on(\"session_shutdown\", async () => {\n\t\thandoffContext = undefined;\n\t\tcloseJobWatchers();\n\t\thandoffTail = Promise.resolve();\n\t});\n\n\tpi.registerTool({\n\t\tname: \"tmux_agent_manager\",\n\t\tlabel: \"tmux Agent Manager\",\n\t\tdescription:\n\t\t\t\"tmux-exclusive interactive agent/workspace manager for Windows/Linux/macOS environments where tmux is on PATH. Opens real provider CLIs in panes, injects prompts, captures output, and replaces cmux outside iOS/macOS cmux use.\",\n\t\tpromptSnippet:\n\t\t\t\"Use tmux to launch managed interactive agent/provider panes with prompt injection, captured output, completion markers, shared variables, and final notifications.\",\n\t\tpromptGuidelines: [\n\t\t\t\"Use tmux_agent_manager for Windows/Linux tmux-managed workers. Do not use cmux on Windows/Linux; cmux is macOS-only and manual-disabled there.\",\n\t\t\t\"Prefer action=fire_task for interactive worker batches. It returns after event watchers and prompts are armed; do not wait, poll, or peek for completion.\",\n\t\t\t\"Use action=list_templates/show_template before assembling repeated teams; pass teamTemplate when a built-in team fits.\",\n\t\t\t\"Use action=workspace_plan before launch_workspace when designing a pane layout.\",\n\t\t\t\"Use stop_job/stop_session dry-run first, then confirm=yes-tmux-stop for real cleanup.\",\n\t\t\t\"Do not put secrets in task text or command strings; prompts, commands, and logs persist under ~/.pi/agent/work/background/tmux-agent-manager/state/jobs.\",\n\t\t\t\"tmux display/status actions are metadata only; validate worker result/log files before claiming task completion.\",\n\t\t],\n\t\tparameters: Type.Object({\n\t\t\taction: Type.Optional(\n\t\t\t\tType.Union(\n\t\t\t\t\t[\n\t\t\t\t\t\tType.Literal(\"status\"),\n\t\t\t\t\t\tType.Literal(\"setup_help\"),\n\t\t\t\t\t\tType.Literal(\"guard\"),\n\t\t\t\t\t\tType.Literal(\"notify\"),\n\t\t\t\t\t\tType.Literal(\"set_status\"),\n\t\t\t\t\t\tType.Literal(\"clear_status\"),\n\t\t\t\t\t\tType.Literal(\"workspace_plan\"),\n\t\t\t\t\t\tType.Literal(\"launch_workspace\"),\n\t\t\t\t\t\tType.Literal(\"fire_task\"),\n\t\t\t\t\t\tType.Literal(\"job_status\"),\n\t\t\t\t\t\tType.Literal(\"list_jobs\"),\n\t\t\t\t\t\tType.Literal(\"set_variable\"),\n\t\t\t\t\t\tType.Literal(\"list_variables\"),\n\t\t\t\t\t\tType.Literal(\"list_templates\"),\n\t\t\t\t\t\tType.Literal(\"show_template\"),\n\t\t\t\t\t\tType.Literal(\"stop_job\"),\n\t\t\t\t\t\tType.Literal(\"stop_session\"),\n\t\t\t\t\t],\n\t\t\t\t\t{\n\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\"status, setup_help, guard, notify, set_status, clear_status, workspace_plan, launch_workspace, fire_task, job_status, list_jobs, set_variable, list_variables, list_templates, show_template, stop_job, or stop_session. Default status.\",\n\t\t\t\t\t},\n\t\t\t\t),\n\t\t\t),\n\t\t\ttitle: Type.Optional(Type.String({ description: \"Notification title or workspace title context.\" })),\n\t\t\tbody: Type.Optional(\n\t\t\t\tType.String({ description: \"Notification body/status text, or fallback task text for fire_task.\" }),\n\t\t\t),\n\t\t\tsubtitle: Type.Optional(\n\t\t\t\tType.String({ description: \"Accepted for cmux parity; tmux display-message ignores subtitle.\" }),\n\t\t\t),\n\t\t\tstatusKey: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription: \"Status key for tmux set_status/clear_status. Stored as @pi_<key>. Default pi-agents.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tstatus: Type.Optional(Type.String({ description: \"Status value for set_status.\" })),\n\t\t\ticon: Type.Optional(\n\t\t\t\tType.String({ description: \"Accepted for cmux parity; tmux display-message/user options ignore icon.\" }),\n\t\t\t),\n\t\t\tcolor: Type.Optional(\n\t\t\t\tType.String({ description: \"Accepted for cmux parity; tmux display-message/user options ignore color.\" }),\n\t\t\t),\n\t\t\tworkspaceName: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"tmux session name/title for workspace_plan/launch_workspace/fire_task, or target for notify/status.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tcwd: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription: \"Working directory for planned/launched agent workspace. Defaults to current cwd.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tteamTemplate: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"Built-in team template name for workspace/fire_task, or target for show_template. Use list_templates first. Current templates include provider-prompt-smoke, full-provider-review, builder-validator, plus JSON templates under templates/.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\ttask: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription: \"Fire-and-forget worker objective. Required for fire_task unless body is provided.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tjobId: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription: \"Job id for fire_task (optional), job_status/list_variables/set_variable (required).\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tvariableName: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"For set_variable: named condition/decision variable workers read only at the decision point.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tvariableValue: Type.Optional(\n\t\t\t\tType.String({ description: \"For set_variable: value to write. body/status can also supply the value.\" }),\n\t\t\t),\n\t\t\tdeadlineSeconds: Type.Optional(\n\t\t\t\tType.Number({\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"For fire_task: seconds before each event-driven pane watcher records a timeout. Default 1200.\",\n\t\t\t\t\tminimum: 5,\n\t\t\t\t\tmaximum: MAX_DEADLINE_SECONDS,\n\t\t\t\t}),\n\t\t\t),\n\t\t\tagents: Type.Optional(\n\t\t\t\tType.Array(\n\t\t\t\t\tType.Object({\n\t\t\t\t\t\tprovider: Type.Optional(\n\t\t\t\t\t\t\tType.Union([\n\t\t\t\t\t\t\t\tType.Literal(\"pi\"),\n\t\t\t\t\t\t\t\tType.Literal(\"codex\"),\n\t\t\t\t\t\t\t\tType.Literal(\"agy\"),\n\t\t\t\t\t\t\t\tType.Literal(\"claude\"),\n\t\t\t\t\t\t\t\tType.Literal(\"opencode\"),\n\t\t\t\t\t\t\t\tType.Literal(\"custom\"),\n\t\t\t\t\t\t\t]),\n\t\t\t\t\t\t),\n\t\t\t\t\t\tname: Type.Optional(Type.String({ description: \"Pane/worker name.\" })),\n\t\t\t\t\t\tcommand: Type.Optional(\n\t\t\t\t\t\t\tType.String({\n\t\t\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\t\t\"Interactive CLI start command for this pane, e.g. claude, agy, pi, or a custom wrapper CLI. The manager injects the prompt after launch and captures pane output.\",\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t\tcwd: Type.Optional(Type.String({ description: \"Optional per-agent cwd.\" })),\n\t\t\t\t\t}),\n\t\t\t\t\t{ description: \"Agents/providers to lay out in tmux. Default: pi, agy, codex.\" },\n\t\t\t\t),\n\t\t\t),\n\t\t\tdryRun: Type.Optional(\n\t\t\t\tType.Boolean({\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"Preview only when true. Launch actions run by default; stop actions remain previews by default.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tforce: Type.Optional(\n\t\t\t\tType.Boolean({\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"For fire_task only: archive an existing job directory with the same jobId before launch. Existing tmux sessions are still refused; stop them first.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tconfirm: Type.Optional(\n\t\t\t\tType.String({ description: \"Required for real stop_job/stop_session: yes-tmux-stop.\" }),\n\t\t\t),\n\t\t}),\n\t\tasync execute(toolCallId, params, signal, onUpdate, ctx) {\n\t\t\tconst result = await executeTool(toolCallId, params as Params, signal, onUpdate, ctx);\n\t\t\tawait queueJobHandoffRefresh(ctx);\n\t\t\treturn result;\n\t\t},\n\t});\n\n\tpi.registerCommand(\"tmux-agents\", {\n\t\tdescription: \"Check tmux availability and show managed-agent guidance.\",\n\t\thandler: async (_args, ctx) => {\n\t\t\tconst detection = detectTmux();\n\t\t\tconst text = detection.cliAvailable\n\t\t\t\t? tmuxManagerInstructions(\"agent/provider\", detection)\n\t\t\t\t: setupHelp(detection);\n\t\t\tctx.ui.notify(text, detection.cliAvailable ? \"info\" : \"warning\");\n\t\t},\n\t});\n}\n"]}