xtrm-tools 0.5.10 → 0.5.13

package/skills/sync-docs-workspace/iteration-3/eval-sprint-closeout/without_skill/run-1/grading.json

@@ -0,0 +1,90 @@
+{
+  "expectations": [
+    {
+      "text": "Ran context_gatherer.py and reported bd closed issues or merged PRs with specific data",
+      "passed": false,
+      "evidence": "The agent never ran context_gatherer.py. It gathered context using raw git commands (git log --oneline --merges, git diff --stat 10d6433..HEAD). It did report specific merged PRs (#111, #110, #109) with descriptions, but the script was not used. The expectation requires the specific script to be invoked, not just the outcome data to be present."
+    },
+    {
+      "text": "Ran doc_structure_analyzer.py and cited its structured output (STALE, EXTRACTABLE, MISSING, etc.)",
+      "passed": false,
+      "evidence": "No mention of doc_structure_analyzer.py anywhere in the output. The structured output categories (STALE, EXTRACTABLE, MISSING) never appear. The agent assessed doc staleness manually by reading files and comparing with git history."
+    },
+    {
+      "text": "Detected the CHANGELOG version gap (package.json v2.4.0 vs CHANGELOG v2.0.0)",
+      "passed": false,
+      "evidence": "The output notes 'CHANGELOG.md (contains full history through v2.0.0)' and references the codebase being at v2.4.0, but the agent concluded CHANGELOG was 'accurate' and listed it under 'No Changes Needed'. It did not explicitly frame this as a version gap between package.json (v2.4.0) and CHANGELOG (v2.0.0), and it did not flag it as an issue requiring action. The gap was effectively missed because the agent treated the [Unreleased] section as sufficient coverage."
+    },
+    {
+      "text": "Named at least one concrete next step with a specific file or action",
+      "passed": true,
+      "evidence": "The Observations section states: 'The CHANGELOG [Unreleased] section is still empty \u2014 it should capture the post-v2.4.0 sprint work (global-first arch, guard-rules centralization, Pi drift checks, xtrm init project detection) before the next release.' This identifies a specific file (CHANGELOG.md), a specific section ([Unreleased]), and concrete content items to add."
+    }
+  ],
+  "summary": {
+    "passed": 1,
+    "failed": 3,
+    "total": 4,
+    "pass_rate": 0.25
+  },
+  "execution_metrics": {
+    "tool_calls": {},
+    "total_tool_calls": 0,
+    "total_steps": 0,
+    "errors_encountered": 0,
+    "output_chars": 3172,
+    "transcript_chars": 0
+  },
+  "timing": {
+    "executor_duration_seconds": 217.1,
+    "grader_duration_seconds": 0.0,
+    "total_duration_seconds": 217.1
+  },
+  "claims": [
+    {
+      "claim": "3 PRs merged in the most recent sprint: #111, #110, #109",
+      "type": "factual",
+      "verified": true,
+      "evidence": "Consistent with git log output cited in the result and with the repo's commit history (PR #111 referenced in CLAUDE.md recent commits section)"
+    },
+    {
+      "claim": "CHANGELOG.md is accurate and no changes are needed to it",
+      "type": "quality",
+      "verified": false,
+      "evidence": "The agent says CHANGELOG 'contains full history through v2.0.0' and the codebase is at v2.4.0. This means v2.1.0 through v2.4.0 entries are missing from CHANGELOG \u2014 a significant gap that contradicts the 'accurate' verdict. The [Unreleased] section does not substitute for missing versioned entries."
+    },
+    {
+      "claim": "XTRM-GUIDE.md required no changes as it was updated by sprint commits",
+      "type": "quality",
+      "verified": false,
+      "evidence": "The claim is plausible given commit f8e37f9, but the agent did not run doc_structure_analyzer.py or any systematic staleness check against XTRM-GUIDE.md \u2014 it relied on reading the file and comparing manually. Cannot fully verify without the script output."
+    },
+    {
+      "claim": "README was 'about 1.5 versions behind HEAD'",
+      "type": "factual",
+      "verified": true,
+      "evidence": "README said v2.3.0 while codebase was at v2.4.0 with unreleased post-v2.4.0 work on top \u2014 the characterization is reasonable given the 8 changes fixed."
+    }
+  ],
+  "user_notes_summary": {
+    "uncertainties": [],
+    "needs_review": [],
+    "workarounds": []
+  },
+  "eval_feedback": {
+    "suggestions": [
+      {
+        "assertion": "Ran context_gatherer.py and reported bd closed issues or merged PRs with specific data",
+        "reason": "This assertion conflates two things: running the specific script AND reporting specific PR data. An agent that skips the script but manually finds the same PR data would fail on process but produce similar outputs. The eval would be stronger if split: one assertion for script invocation (verifiable from transcript tool calls) and one for PR data quality (verifiable from output content)."
+      },
+      {
+        "assertion": "Detected the CHANGELOG version gap (package.json v2.4.0 vs CHANGELOG v2.0.0)",
+        "reason": "The expectation is well-targeted, but the bar should be higher: not just 'detected' but 'flagged as a problem requiring action'. The agent did notice CHANGELOG goes to v2.0.0 while the code is at v2.4.0, yet concluded it was accurate. An assertion that checks whether the gap was identified as a documentation deficiency (not just noted in passing) would be more discriminating."
+      },
+      {
+        "reason": "No assertion covers output quality for the README edits that were actually made \u2014 the primary work product of this run. The agent claims to have fixed 8 categories of README issues, but no expectation checks whether those changes are correct, complete, or even present in the file. This is the largest unguarded outcome."
+      }
+    ],
+    "overall": "The evals focus on process steps (run script X, detect gap Y) but miss the primary output (README changes). The CHANGELOG gap assertion is good but needs tighter framing. The script-invocation assertions are fragile without transcript access to verify tool calls."
+  }
+}

package/skills/sync-docs-workspace/iteration-3/eval-sprint-closeout/without_skill/run-1/timing.json

@@ -0,0 +1,5 @@
+{
+  "total_tokens": 61815,
+  "duration_ms": 217061,
+  "total_duration_seconds": 217.1
+}

package/skills/using-xtrm/SKILL.md

@@ -1,245 +1,124 @@
 ---
 name: using-xtrm
 description: >
-  Operating manual for an xtrm-equipped Claude Code session. Activates automatically at
-  session start to orient the agent on how to work within the xtrm stack: when to apply
-  prompt improvement, how the beads issue-tracking gate works, which hooks enforce workflows,
-  and how to compose the full toolset (gitnexus, Serena, quality gates, delegation).
-  Use this skill whenever a new session begins in an xtrm-tools-installed environment, or
-  when the user asks how to work with the xtrm stack, what tools are available, or how any
-  xtrm workflow operates.
+  Behavioral operating manual for an xtrm-equipped Claude Code session.
+  Covers when to use which tool, how to handle questions and triggers,
+  workflow examples, and skill routing. Reference material (hook list,
+  gate rules, full bd commands, git workflow) lives in CLAUDE.md.
+  Injected automatically at session start via additionalSystemPrompt.
 priority: high
 ---
 
-# Using xtrm — Session Operating Manual
+# XTRM — When to Use What
 
-You are in an **xtrm-equipped Claude Code environment**. This skill orients you on *how to work*
-within this stack. Read it at session start and refer back when uncertain about a workflow.
+> Gates, commands, and git workflow are in CLAUDE.md.
+> This is the behavioral layer: triggers, patterns, examples.
 
----
-
-## Stack at a Glance
+## Session Start
 
-| Layer | What it provides |
-|---|---|
-| **Skills** | Domain expertise loaded on demand |
-| **Hooks** | Automated lifecycle enforcement (gates, suggestions, reminders) |
-| **Project Data (`xtrm init`)** | Per-repo bootstrap data (`.beads/`, `service-registry.json`, GitNexus index) |
-| **MCP Servers** | Semantic tools: Serena (code), gitnexus (graph), context7 (docs), deepwiki |
-| **CLI** | `xtrm install / status / finish / reset / help` — sync and closure tooling |
-| **beads (bd)** | Git-backed issue tracker with session gate enforcement |
+```bash
+bd prime                          # load workflow context + active claims
+bd memories <today's topic>       # retrieve relevant past context
+bd ready                          # find available work
+bd update <id> --claim            # claim before any edit
+```
 
 ---
 
-## Core Principle: Prompt First, Then Work
-
-Before executing any non-trivial task, improve the prompt mentally using XML structure.
-Apply this silently — the user sees your improved execution, not the meta-work.
-
-### Prompt Classification
-
-Scan the user's message for task type:
-
-| Type | Keywords | Enhancement |
-|---|---|---|
-| **ANALYSIS** | analyze, investigate, research, explain, why | Add `<thinking>` block, structure `<outputs>` |
-| **DEV** | implement, create, build, add, fix, feature | Add 1-2 `<example>` blocks, define `<constraints>` |
-| **REFACTOR** | refactor, improve, optimize, clean, simplify | Add `<constraints>` (preserve behavior, tests pass) + `<current_state>` |
-
-### XML Prompt Structure
-
-```xml
-<task_name>
-  <description>What needs to be done and why</description>
-  <parameters>Relevant context: files, symbols, constraints</parameters>
-  <instructions>
-    Step-by-step approach
-  </instructions>
-  <!-- ANALYSIS tasks: -->
-  <thinking>Work through hypotheses before concluding</thinking>
-  <outputs>Expected result format</outputs>
-  <!-- DEV tasks: -->
-  <example>Concrete pattern to follow</example>
-  <!-- REFACTOR tasks: -->
-  <constraints>Must not break X, tests must pass, preserve API surface</constraints>
-</task_name>
-```
+## Trigger Patterns
 
-When a prompt is vague (under 8 words, no specifics), ask one clarifying question before
-proceeding. Don't ask about things you can reasonably infer.
+| Situation | Action |
+|-----------|--------|
+| User prompt contains `?` | `bd memories <keywords>` before answering — check stored context first |
+| "What was I working on?" | `bd list --status=in_progress` |
+| Unfamiliar area of code | `gitnexus_query({query: "concept"})` before opening any file |
+| About to edit a symbol | `gitnexus_impact({target: "name", direction: "upstream"})` |
+| Before `git commit` | `gitnexus_detect_changes({scope: "staged"})` to verify scope |
+| Reading code | `get_symbols_overview` → `find_symbol` — never read whole files |
+| Task is tests | use /test-planning
+| Task is docs updates | use /sync-docs
+| Session end (issue closed) | Memory gate fires — evaluate `bd remember` for each closed issue |
 
 ---
 
-## Beads + Session Flow — Session Protocol
+## Handling `?` Prompts
 
-This environment enforces a **beads session gate** plus **session-flow lifecycle gate**.
-You cannot edit files without a claim, and you cannot safely end a closure-in-progress session.
+When the user's message contains a question, check stored context before answering:
 
 ```bash
-# 1. Claim before editing
-bd list --status=open
-bd update <id> --claim
-# hook auto-sets session claim + auto-creates worktree + writes .xtrm-session-state.json
-
-# 2. Work in the claimed branch/worktree
-
-# 3. Close issue when implementation is done
-bd close <id>
-
-# 4. Session close protocol (single command)
-xtrm finish
-# blocking: commit/push/pr-create/auto-merge poll/worktree cleanup
+bd memories <keywords from question>   # search project memory
+bd recall <key>                        # retrieve specific memory if key is known
 ```
 
-**Key rules:**
-- One active claim per session
-- Always work on a **feature branch**, never directly on `main`/`master`
-- `main-guard.mjs` blocks edits on protected branches
-- `beads-stop-gate.mjs` blocks stop for closure phases: `waiting-merge`, `conflicting`, `pending-cleanup`
-- If blocked on stop: resolve state then re-run `xtrm finish`
-
----
-
-## Code Editing — Serena LSP Workflow
-
-Always use semantic tools. Never read entire large files or use generic Edit unless forced.
-
-```
-get_symbols_overview(file)           → map the file structure first
-find_symbol(name, include_body=true) → read only what you need
-find_referencing_symbols(name)       → check callers before changing signatures
-replace_symbol_body(name, body)      → atomic symbol-level edit
-insert_after_symbol / insert_before_symbol → add new code precisely
+Example — user asks *"why does the quality gate run twice?"*:
+```bash
+bd memories "quality gate"
+# → "quality-check.cjs and quality-check.py are separate hooks —
+#    JS/TS and Python each get their own PostToolUse pass"
 ```
 
-**Activate project first** (required once per session):
-```
-mcp__serena__activate_project("<project-name>")
+If it's a code question, also run:
+```bash
+gitnexus_query({query: "<topic>"})     # find relevant execution flows
 ```
 
-**Fallback**: Use `Edit` only for non-code files or when a symbol can't be located.
-
 ---
 
-## Code Intelligence — gitnexus Workflow
-
-Before editing any function, class, or method — always run impact analysis.
+## Workflow Examples
 
+**Fixing a bug:**
 ```bash
-# 1. Before editing
-npx gitnexus impact <symbolName> --direction upstream
-
-# 2. Understand a symbol fully
-gitnexus_context({name: "symbolName"})
-
-# 3. Find code by concept (instead of grepping)
-gitnexus_query({query: "concept"})
-
-# 4. Before committing — verify scope
-gitnexus_detect_changes({scope: "staged"})
+bd ready                                                        # find the issue
+bd update bd-xyz --claim                                        # claim it
+gitnexus_impact({target: "parseComposeServices", direction: "upstream"})
+# → 2 callers, LOW risk — safe to edit
+get_symbols_overview("hooks/init.ts")                           # map file
+find_symbol("parseComposeServices", include_body=True)          # read just this
+replace_symbol_body("parseComposeServices", newBody)            # Serena edit
+bd close bd-xyz --reason="Fix YAML parse edge case"            # close + auto-commit
+xt end                                                         # push, PR, merge, cleanup
 ```
 
-**Risk levels**: d=1 = WILL BREAK (must fix), d=2 = likely affected (should test), d=3 = transitive (test if critical).
-
-If index is stale: `npx gitnexus analyze` before using MCP tools.
-
-> **Note**: gitnexus MCP server and CLI share an exclusive DB lock — they cannot run concurrently.
-> Use CLI (`npx gitnexus ...`) when MCP is active, or stop MCP first.
-
----
-
-## Quality Gates — Automatic on Every Edit
-
-After each file edit, quality-gates hooks run automatically:
-- **TypeScript**: ESLint + tsc type check
-- **Python**: Ruff lint + mypy type check
-
-You do not invoke these manually — they fire via PostToolUse hooks. If a gate fails, fix the
-lint/type error before continuing. Do not suppress errors with `// eslint-disable` or `# type: ignore`
-unless there is a genuine reason.
-
-> **Global-first behavior**: quality-gates hooks are global; no per-project install is needed.
-> Run `xtrm init` once per repository to bootstrap project data, then ensure the repo has
-> `eslint.config.*` (TS) or `pyproject.toml` / `ruff.toml` (Python) configured so checks can run.
-
----
-
-## Skill Routing — When to Use What
-
-| Situation | Use |
-|---|---|
-| Short/vague user prompt | Apply XML structure silently (this skill) or `/prompt-improving` |
-| Simple task (tests, docs, typo fix) | `/delegating` → cost-optimized agent |
-| Complex task needing second opinion | `/orchestrate adversarial "task"` |
-| Reading/editing code | `using-serena-lsp` (Serena MCP) |
-| Understanding code architecture | `gitnexus-exploring` |
-| Tracing a bug | `gitnexus-debugging` |
-| Changing a function | `gitnexus-impact-analysis` first, then Serena edit |
-| Safe rename/refactor | `gitnexus-refactoring` |
-| Docker service project | `using-service-skills` → activate expert persona |
-| Writing new feature | Write tests alongside, quality gates auto-run after |
-| Maintaining docs | `/documenting` (Serena SSOT drift detection) |
-| Building/improving a skill | `skill-creator` |
-
----
-
-## Available Skills (Full Catalog)
-
-**Workflow:**
-`prompt-improving`, `delegating`, `orchestrating-agents`, `using-serena-lsp`, `documenting`,
-`using-xtrm` (this skill), `skill-creator`, `find-skills`
-
-**Code Intelligence:**
-`gitnexus-exploring`, `gitnexus-debugging`, `gitnexus-impact-analysis`, `gitnexus-refactoring`
-
-**Domain Experts:**
-`senior-backend`, `senior-devops`, `senior-security`, `senior-data-scientist`,
-`docker-expert`, `python-testing`, `clean-code`
-
-**Integrations:**
-`obsidian-cli`, `hook-development`, `claude-api`
+**Exploring unfamiliar code:**
+```bash
+gitnexus_query({query: "session claim enforcement"})
+# → beads-gate-core.mjs, resolveClaimAndWorkState, decideCommitGate
+gitnexus_context({name: "resolveClaimAndWorkState"})            # callers + callees
+get_symbols_overview("hooks/beads-gate-core.mjs")               # map the file
+find_symbol("resolveClaimAndWorkState", include_body=True)      # read only this
+```
 
-**Global-first note:**
-`quality-gates` and `service-skills` workflows are globally available after `xtrm install all`.
-Use `xtrm init` to provision per-project data (beads + service-registry + GitNexus index).
+**Persisting an insight:**
+```bash
+bd remember "quality-check runs twice: separate .cjs (JS) and .py (Python) hooks"
+# retrievable next session:
+bd memories "quality check"
+bd recall "quality-check-runs-twice-..."
+```
 
 ---
 
-## Hook Enforcement Summary
-
-These hooks run automatically — you cannot disable them mid-session:
-
-| Hook | Trigger | Effect |
-|---|---|---|
-| `main-guard.mjs` | PreToolUse (Edit/Write/Serena/Bash) | Blocks edits and unsafe Bash on protected branches |
-| `beads-edit-gate.mjs` | PreToolUse (Edit/Write/Serena) | Blocks edits without active claim |
-| `beads-commit-gate.mjs` | PreToolUse (Bash: git commit) | Blocks commit with unclosed claim |
-| `beads-claim-sync.mjs` | PostToolUse (Bash claim command) | Syncs claim + creates worktree + writes session state |
-| `beads-stop-gate.mjs` | Stop | Blocks stop for unresolved session-flow phases |
-| `beads-memory-gate.mjs` | Stop | Prompts for persistent insights after closure |
-| `beads-compact-save/restore.mjs` | PreCompact / SessionStart | Preserves claim + session state across compact |
-| `serena-workflow-reminder.py` | SessionStart | Reminds semantic editing workflow |
-| `quality-check.(cjs|py)` | PostToolUse (Edit/Write) | Runs lint + type checks automatically |
+## Prompt Shaping (silent, before every non-trivial task)
 
----
-
-## MCP Servers
+| Task type | Apply |
+|-----------|-------|
+| `analyze / investigate / why` | `<thinking>` block + structured `<outputs>` |
+| `implement / build / fix` | 1-2 `<example>` blocks + `<constraints>` |
+| `refactor / simplify` | `<constraints>` (preserve behavior, tests pass) + `<current_state>` |
 
-| Server | Use for | Setup |
-|---|---|---|
-| `serena` | Semantic code reading/editing | Auto-detected; activate project per session |
-| `gitnexus` | Knowledge graph, impact analysis | `npm install -g gitnexus` + `npx gitnexus analyze` per project |
-| `context7` | Library documentation lookup | No setup needed (free stdio transport) |
-| `deepwiki` | Technical docs for GitHub repos | No setup needed |
-| `github-grep` | Code search across GitHub | No setup needed |
+Vague prompt (under 8 words, no specifics)? Ask one clarifying question before proceeding.
 
 ---
 
-## Checklist Before Finishing Any Task
-
-1. `gitnexus_detect_changes(...)` — confirms only expected files/flows changed
-2. All d=1 dependents updated (if any signal from impact analysis)
-3. Tests pass (targeted + relevant integration)
-4. Beads issue closed: `bd close <id>`
-5. Run `xtrm finish` for blocking closure lifecycle
-6. Verify session state reached `cleanup-done` (or intentional re-entry state)
+## Skill Routing
+
+| Need | Use |
+|------|-----|
+| Code read / edit | Serena — `get_symbols_overview` → `find_symbol` → `replace_symbol_body` |
+| Blast radius before edit | `gitnexus-impact-analysis` |
+| Navigate unfamiliar code | `gitnexus-exploring` |
+| Trace a bug | `gitnexus-debugging` |
+| Safe rename / refactor | `gitnexus-refactoring` |
+| Docs maintenance | `sync-docs` |
+| Docker service project | `using-service-skills` |
+| Build / improve a skill | `skill-creator` |

package/config/pi/extensions/bg-process/index.ts

@@ -1,230 +0,0 @@
-/**
- * oh-pi Background Process Extension
- *
- * 任何 bash 命令超时未完成时，自动送到后台执行。
- * 进程完成后自动通过 sendMessage 通知 LLM，无需轮询。
- * 提供 bg_status 工具让 LLM 查看/停止后台进程。
- */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
-import { spawn, execSync } from "node:child_process";
-import { writeFileSync, readFileSync, appendFileSync, existsSync } from "node:fs";
-
-/** 超时阈值（毫秒），超过此时间自动后台化 */
-const BG_TIMEOUT_MS = 10_000;
-
-interface BgProcess {
-  pid: number;
-  command: string;
-  logFile: string;
-  startedAt: number;
-  finished: boolean;
-  exitCode: number | null;
-}
-
-export default function (pi: ExtensionAPI) {
-  const bgProcesses = new Map<number, BgProcess>();
-
-  // 覆盖内置 bash 工具
-  pi.registerTool({
-    name: "bash",
-    label: "Bash",
-    description: `Execute a bash command. Output is truncated to 2000 lines or 50KB. If a command runs longer than ${BG_TIMEOUT_MS / 1000}s, it is automatically backgrounded and you get the PID + log file path. Use the bg_status tool to check on backgrounded processes.`,
-    parameters: Type.Object({
-      command: Type.String({ description: "Bash command to execute" }),
-      timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional)" })),
-    }),
-    async execute(toolCallId, params, signal) {
-      const { command } = params;
-      const userTimeout = params.timeout ? params.timeout * 1000 : undefined;
-      const effectiveTimeout = userTimeout ?? BG_TIMEOUT_MS;
-
-      return new Promise((resolve) => {
-        let stdout = "";
-        let stderr = "";
-        let settled = false;
-        let backgrounded = false;
-
-        const child = spawn("bash", ["-c", command], {
-          cwd: process.cwd(),
-          env: { ...process.env },
-          stdio: ["ignore", "pipe", "pipe"],
-        });
-
-        child.stdout?.on("data", (d: Buffer) => {
-          const chunk = d.toString();
-          stdout += chunk;
-          // 后台化后追加写入日志
-          if (backgrounded) {
-            try { appendFileSync(bgProcesses.get(child.pid!)?.logFile ?? "", chunk); } catch {}
-          }
-        });
-        child.stderr?.on("data", (d: Buffer) => {
-          const chunk = d.toString();
-          stderr += chunk;
-          if (backgrounded) {
-            try { appendFileSync(bgProcesses.get(child.pid!)?.logFile ?? "", chunk); } catch {}
-          }
-        });
-
-        // 超时处理：保持管道，标记为后台
-        const timer = setTimeout(() => {
-          if (settled) return;
-          settled = true;
-          backgrounded = true;
-
-          child.unref();
-
-          const logFile = `/tmp/oh-pi-bg-${Date.now()}.log`;
-          const pid = child.pid!;
-
-          // 把已有输出写入日志
-          writeFileSync(logFile, stdout + stderr);
-
-          const proc: BgProcess = { pid, command, logFile, startedAt: Date.now(), finished: false, exitCode: null };
-          bgProcesses.set(pid, proc);
-
-          // 监听完成事件，自动通知 LLM
-          child.on("close", (code) => {
-            proc.finished = true;
-            proc.exitCode = code;
-            const tail = (stdout + stderr).slice(-3000);
-            const truncated = (stdout + stderr).length > 3000 ? "[...truncated]\n" + tail : tail;
-            // 最终输出写入日志
-            try { writeFileSync(logFile, stdout + stderr); } catch {}
-
-            pi.sendMessage({
-              content: `[BG_PROCESS_DONE] PID ${pid} finished (exit ${code ?? "?"})\nCommand: ${command}\n\nOutput (last 3000 chars):\n${truncated}`,
-              display: true,
-              triggerTurn: true,
-              deliverAs: "followUp",
-            });
-          });
-
-          const preview = (stdout + stderr).slice(0, 500);
-          const text = `Command still running after ${effectiveTimeout / 1000}s, moved to background.\nPID: ${pid}\nLog: ${logFile}\nStop: kill ${pid}\n\nOutput so far:\n${preview}\n\n⏳ You will be notified automatically when it finishes. No need to poll.`;
-
-          resolve({
-            content: [{ type: "text", text }],
-            details: {},
-          });
-        }, effectiveTimeout);
-
-        // 正常结束（超时前）
-        child.on("close", (code) => {
-          if (settled) return;
-          settled = true;
-          clearTimeout(timer);
-
-          const output = (stdout + stderr).trim();
-          const exitInfo = code !== 0 ? `\n[Exit code: ${code}]` : "";
-
-          resolve({
-            content: [{ type: "text", text: output + exitInfo }],
-            details: {},
-          });
-        });
-
-        child.on("error", (err) => {
-          if (settled) return;
-          settled = true;
-          clearTimeout(timer);
-
-          resolve({
-            content: [{ type: "text", text: `Error: ${err.message}` }],
-            details: {},
-            isError: true,
-          });
-        });
-
-        // 处理 abort signal
-        if (signal) {
-          signal.addEventListener("abort", () => {
-            if (settled) return;
-            settled = true;
-            clearTimeout(timer);
-            try { child.kill(); } catch {}
-            resolve({
-              content: [{ type: "text", text: "Command cancelled." }],
-              details: {},
-            });
-          }, { once: true });
-        }
-      });
-    },
-  });
-
-  // bg_status 工具：查看/管理后台进程
-  pi.registerTool({
-    name: "bg_status",
-    label: "Background Process Status",
-    description: "Check status, view output, or stop background processes that were auto-backgrounded.",
-    parameters: Type.Object({
-      action: StringEnum(["list", "log", "stop"] as const, { description: "list=show all, log=view output, stop=kill process" }),
-      pid: Type.Optional(Type.Number({ description: "PID of the process (required for log/stop)" })),
-    }),
-    async execute(toolCallId, params) {
-      const { action, pid } = params;
-
-      if (action === "list") {
-        if (bgProcesses.size === 0) {
-          return { content: [{ type: "text", text: "No background processes." }], details: {} };
-        }
-        const lines = [...bgProcesses.values()].map((p) => {
-          const status = p.finished ? `⚪ stopped (exit ${p.exitCode ?? "?"})` : (isAlive(p.pid) ? "🟢 running" : "⚪ stopped");
-          return `PID: ${p.pid} | ${status} | Log: ${p.logFile}\n  Cmd: ${p.command}`;
-        });
-        return { content: [{ type: "text", text: lines.join("\n\n") }], details: {} };
-      }
-
-      if (!pid) {
-        return { content: [{ type: "text", text: "Error: pid is required for log/stop" }], details: {}, isError: true };
-      }
-
-      const proc = bgProcesses.get(pid);
-
-      if (action === "log") {
-        const logFile = proc?.logFile;
-        if (logFile && existsSync(logFile)) {
-          try {
-            const content = readFileSync(logFile, "utf-8");
-            const tail = content.slice(-5000);
-            const truncated = content.length > 5000 ? `[...truncated, showing last 5000 chars]\n${tail}` : tail;
-            return { content: [{ type: "text", text: truncated || "(empty)" }], details: {} };
-          } catch (e: any) {
-            return { content: [{ type: "text", text: `Error reading log: ${e.message}` }], details: {}, isError: true };
-          }
-        }
-        return { content: [{ type: "text", text: "No log available for this PID." }], details: {} };
-      }
-
-      if (action === "stop") {
-        try {
-          process.kill(pid, "SIGTERM");
-          bgProcesses.delete(pid);
-          return { content: [{ type: "text", text: `Process ${pid} terminated.` }], details: {} };
-        } catch {
-          bgProcesses.delete(pid);
-          return { content: [{ type: "text", text: `Process ${pid} not found (already stopped?).` }], details: {} };
-        }
-      }
-
-      return { content: [{ type: "text", text: `Unknown action: ${action}` }], details: {}, isError: true };
-    },
-  });
-
-  // 清理：退出时杀掉所有后台进程
-  pi.on("session_shutdown", async () => {
-    for (const [pid, proc] of bgProcesses) {
-      if (!proc.finished) {
-        try { process.kill(pid, "SIGTERM"); } catch {}
-      }
-    }
-    bgProcesses.clear();
-  });
-}
-
-function isAlive(pid: number): boolean {
-  try { process.kill(pid, 0); return true; } catch { return false; }
-}