patchwarden 0.6.1 → 1.1.0

package/dist/tools/diagnoseTask.d.ts

@@ -0,0 +1,45 @@
+import { type PatchWardenConfig } from "../config.js";
+export type DiagnosisType = "active_running" | "stale_running" | "possibly_stale_running" | "orphaned_running" | "artifact_collection_stuck" | "done_candidate" | "unknown" | "terminal";
+export type DiagnosisConfidence = "high" | "medium" | "low";
+export type SafeAction = "leave_unchanged" | "mark_failed_stale" | "mark_orphaned" | "mark_done_by_agent" | "collect_artifacts" | "recollect_artifacts" | "needs_fix";
+export interface DiagnosisEvidence {
+    heartbeat_age_seconds: number | null;
+    stdout_age_seconds: number | null;
+    stderr_age_seconds: number | null;
+    stdout_size_bytes: number | null;
+    stderr_size_bytes: number | null;
+    child_pid: number | null;
+    child_pid_alive: boolean | null;
+    child_started_at: string | null;
+    pid_reuse_suspected: boolean;
+    watcher_instance_id: string | null;
+    current_watcher_instance_id: string | null;
+    watcher_owns_task: boolean;
+    watcher_ownership_reason: string;
+    has_result_md: boolean;
+    has_test_log: boolean;
+    has_git_diff: boolean;
+    has_artifact_manifest: boolean;
+    task_started_at: string | null;
+    status_updated_at: string | null;
+    collecting_artifacts_phase: boolean;
+}
+export interface DiagnoseTaskOutput {
+    task_id: string;
+    status: string;
+    phase: string | null;
+    diagnosis: DiagnosisType;
+    confidence: DiagnosisConfidence;
+    reasons: string[];
+    safe_actions: SafeAction[];
+    evidence: DiagnosisEvidence;
+    logs: {
+        stdout_tail: string | null;
+        stderr_tail: string | null;
+    } | null;
+}
+export interface DiagnoseTaskInput {
+    task_id: string;
+    include_logs?: boolean;
+}
+export declare function diagnoseTask(input: DiagnoseTaskInput, config?: PatchWardenConfig): DiagnoseTaskOutput;

package/dist/tools/diagnoseTask.js

@@ -0,0 +1,347 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getTasksDir, getConfig } from "../config.js";
+import { guardReadPath } from "../security/pathGuard.js";
+import { guardSensitivePath } from "../security/sensitiveGuard.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
+import { readTaskRuntime } from "../taskRuntime.js";
+import { isWatcherOwningTask, readWatcherInstanceId } from "../watcherStatus.js";
+// ── Thresholds (seconds) ──────────────────────────────────────────
+//
+// These are intentionally conservative. A task is only "stale" when multiple
+// signals agree. A single stale signal produces "possibly_stale_running" or
+// "unknown", never an automatic safe_fix.
+const HEARTBEAT_STALE_SECONDS = 300; // 5 min: heartbeat this old is a strong stale signal
+const HEARTBEAT_POSSIBLY_STALE_SECONDS = 120; // 2 min: heartbeat this old is a weak stale signal
+const LOG_STALE_SECONDS = 300; // 5 min: stdout/stderr unchanged this long is stale
+const LOG_TAIL_LINES = 40;
+// ── PID liveness check ─────────────────────────────────────────────
+/**
+ * Check whether a PID is alive without sending a signal that could disturb it.
+ * Returns null when the check itself fails (e.g., permission denied),
+ * so callers can avoid treating "couldn't check" as "process is dead".
+ */
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        // process.kill(pid, 0) does not actually kill; it just checks liveness.
+        // It throws if the process does not exist or the caller lacks permission.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false; // No such process
+        if (code === "EPERM")
+            return null; // Alive but not ours — treat as unknown
+        return null;
+    }
+}
+// ── File age helper ────────────────────────────────────────────────
+function fileAgeSeconds(filePath, nowMs) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const stat = statSync(filePath);
+        return { age: Math.max(0, Math.round((nowMs - stat.mtimeMs) / 1000)), size: stat.size };
+    }
+    catch {
+        return null;
+    }
+}
+function readTailLines(filePath, lines) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        const tail = raw.split("\n").slice(-lines).join("\n");
+        return redactSensitiveContent(tail).content;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Main diagnosis entry point ─────────────────────────────────────
+export function diagnoseTask(input, config = getConfig()) {
+    const taskId = input.task_id;
+    const tasksDir = getTasksDir(config);
+    const taskDir = resolve(tasksDir, taskId);
+    const statusFile = join(taskDir, "status.json");
+    guardReadPath(statusFile, config.workspaceRoot, config.tasksDir);
+    guardSensitivePath(statusFile);
+    if (!existsSync(statusFile)) {
+        throw new Error(`Task not found: "${taskId}". Check the task ID or call list_tasks.`);
+    }
+    const raw = readFileSync(statusFile, "utf-8");
+    const status = JSON.parse(raw);
+    const runtime = readTaskRuntime(taskDir);
+    const nowMs = Date.now();
+    const statusStr = typeof status.status === "string" ? status.status : "unknown";
+    const phaseStr = (runtime.phase || (typeof status.phase === "string" ? status.phase : "queued"));
+    // ── Terminal tasks: no diagnosis needed ──
+    const terminalStatuses = new Set([
+        "done", "done_by_agent", "failed", "failed_verification",
+        "failed_scope_violation", "failed_policy_violation",
+        "failed_stale", "orphaned", "canceled",
+    ]);
+    if (terminalStatuses.has(statusStr)) {
+        return buildTerminalDiagnosis(taskId, statusStr, phaseStr);
+    }
+    // ── Only diagnose running / collecting_artifacts / pending ──
+    if (statusStr !== "running" && statusStr !== "collecting_artifacts" && statusStr !== "pending") {
+        return buildUnknownDiagnosis(taskId, statusStr, phaseStr, [`unexpected status "${statusStr}" for diagnosis`]);
+    }
+    // ── Gather evidence ──
+    const heartbeatStr = (typeof runtime.last_heartbeat_at === "string" && runtime.last_heartbeat_at) ||
+        (typeof status.last_heartbeat_at === "string" && status.last_heartbeat_at) ||
+        (typeof status.updated_at === "string" && status.updated_at) ||
+        null;
+    const heartbeatMs = heartbeatStr ? Date.parse(heartbeatStr) : NaN;
+    const heartbeatAgeSeconds = Number.isFinite(heartbeatMs)
+        ? Math.max(0, Math.round((nowMs - heartbeatMs) / 1000))
+        : null;
+    const stdoutPath = join(taskDir, "stdout.log");
+    const stderrPath = join(taskDir, "stderr.log");
+    const stdoutStat = fileAgeSeconds(stdoutPath, nowMs);
+    const stderrStat = fileAgeSeconds(stderrPath, nowMs);
+    const resultMdPath = join(taskDir, "result.md");
+    const testLogPath = join(taskDir, "test.log");
+    const gitDiffPath = join(taskDir, "git.diff");
+    const artifactManifestPath = join(taskDir, "artifact_manifest.json");
+    const hasResultMd = existsSync(resultMdPath);
+    const hasTestLog = existsSync(testLogPath);
+    const hasGitDiff = existsSync(gitDiffPath);
+    const hasArtifactManifest = existsSync(artifactManifestPath);
+    const childPid = typeof runtime.child_pid === "number" ? runtime.child_pid : null;
+    const childStartedAt = typeof runtime.child_started_at === "string" ? runtime.child_started_at : null;
+    const childPidAlive = childPid !== null ? isPidAlive(childPid) : null;
+    // PID reuse heuristic: PID is alive but child_started_at is much older than
+    // the heartbeat threshold AND logs are stale. We cannot reliably read the
+    // OS process start time without platform-specific code, so we treat
+    // "PID alive + everything else stale" as a PID-reuse signal rather than
+    // "active". This is the conservative choice required by the safety contract.
+    const pidReuseSuspected = childPidAlive === true &&
+        heartbeatAgeSeconds !== null &&
+        heartbeatAgeSeconds > HEARTBEAT_STALE_SECONDS &&
+        (stdoutStat === null || stdoutStat.age > LOG_STALE_SECONDS) &&
+        (stderrStat === null || stderrStat.age > LOG_STALE_SECONDS);
+    const ownership = isWatcherOwningTask(taskDir, config);
+    const currentWatcherInstanceId = readWatcherInstanceId(config);
+    const collectingArtifactsPhase = phaseStr === "collecting_artifacts" || statusStr === "collecting_artifacts";
+    const taskStartedAt = typeof runtime.task_started_at === "string"
+        ? runtime.task_started_at
+        : typeof status.started_at === "string"
+            ? status.started_at
+            : null;
+    const statusUpdatedAt = typeof status.updated_at === "string" ? status.updated_at : null;
+    const evidence = {
+        heartbeat_age_seconds: heartbeatAgeSeconds,
+        stdout_age_seconds: stdoutStat?.age ?? null,
+        stderr_age_seconds: stderrStat?.age ?? null,
+        stdout_size_bytes: stdoutStat?.size ?? null,
+        stderr_size_bytes: stderrStat?.size ?? null,
+        child_pid: childPid,
+        child_pid_alive: childPidAlive,
+        child_started_at: childStartedAt,
+        pid_reuse_suspected: pidReuseSuspected,
+        watcher_instance_id: ownership.task_watcher_instance_id,
+        current_watcher_instance_id: currentWatcherInstanceId,
+        watcher_owns_task: ownership.owned,
+        watcher_ownership_reason: ownership.reason,
+        has_result_md: hasResultMd,
+        has_test_log: hasTestLog,
+        has_git_diff: hasGitDiff,
+        has_artifact_manifest: hasArtifactManifest,
+        task_started_at: taskStartedAt,
+        status_updated_at: statusUpdatedAt,
+        collecting_artifacts_phase: collectingArtifactsPhase,
+    };
+    // ── Decision tree ──
+    //
+    // The diagnosis must NEVER rely on a single signal. Each branch below
+    // combines at least two signals before producing a high-confidence
+    // conclusion. When signals conflict, confidence drops to medium/low.
+    const reasons = [];
+    const heartbeatStale = heartbeatAgeSeconds !== null && heartbeatAgeSeconds > HEARTBEAT_STALE_SECONDS;
+    const heartbeatPossiblyStale = heartbeatAgeSeconds !== null &&
+        heartbeatAgeSeconds > HEARTBEAT_POSSIBLY_STALE_SECONDS &&
+        heartbeatAgeSeconds <= HEARTBEAT_STALE_SECONDS;
+    const heartbeatFresh = heartbeatAgeSeconds !== null && heartbeatAgeSeconds <= HEARTBEAT_POSSIBLY_STALE_SECONDS;
+    const logsStale = (stdoutStat === null || stdoutStat.age > LOG_STALE_SECONDS) &&
+        (stderrStat === null || stderrStat.age > LOG_STALE_SECONDS);
+    const logsGrowing = stdoutStat !== null && stdoutStat.age <= HEARTBEAT_POSSIBLY_STALE_SECONDS;
+    // Collect artifact evidence strings
+    if (heartbeatStale)
+        reasons.push(`heartbeat older than ${HEARTBEAT_STALE_SECONDS}s (age: ${heartbeatAgeSeconds}s)`);
+    if (heartbeatPossiblyStale)
+        reasons.push(`heartbeat older than ${HEARTBEAT_POSSIBLY_STALE_SECONDS}s (age: ${heartbeatAgeSeconds}s)`);
+    if (stdoutStat && stdoutStat.age > LOG_STALE_SECONDS)
+        reasons.push(`stdout.log unchanged for ${stdoutStat.age}s`);
+    if (stderrStat && stderrStat.age > LOG_STALE_SECONDS)
+        reasons.push(`stderr.log unchanged for ${stderrStat.age}s`);
+    if (childPidAlive === false)
+        reasons.push(`child_pid ${childPid} is not alive`);
+    if (pidReuseSuspected)
+        reasons.push(`PID ${childPid} is alive but all other signals are stale — suspected PID reuse`);
+    if (!ownership.owned && ownership.reason === "instance_mismatch") {
+        reasons.push(`watcher_instance_id mismatch: task=${ownership.task_watcher_instance_id}, current=${ownership.current_watcher_instance_id}`);
+    }
+    if (!ownership.owned && ownership.reason === "watcher_missing") {
+        reasons.push("watcher heartbeat is missing — no live watcher owns this task");
+    }
+    if (!ownership.owned && ownership.reason === "no_runtime_record") {
+        reasons.push("task runtime has no watcher_instance_id recorded — ownership cannot be confirmed");
+    }
+    if (hasResultMd)
+        reasons.push("result.md already exists while status is still running");
+    if (hasTestLog)
+        reasons.push("test.log already exists while status is still running");
+    // ── done_candidate: artifacts exist but status not converged ──
+    // Strong signal: result.md + test.log + git.diff all exist, status still running.
+    // Medium signal: only result.md exists.
+    if (hasResultMd && (hasTestLog || hasGitDiff)) {
+        return buildResult(taskId, statusStr, phaseStr, "done_candidate", "high", reasons, [
+            "mark_done_by_agent",
+            "leave_unchanged",
+        ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+    }
+    if (hasResultMd && collectingArtifactsPhase) {
+        return buildResult(taskId, statusStr, phaseStr, "done_candidate", "medium", reasons, [
+            "mark_done_by_agent",
+            "collect_artifacts",
+            "leave_unchanged",
+        ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+    }
+    // ── orphaned_running: watcher does not own the task ──
+    if (!ownership.owned && (ownership.reason === "instance_mismatch" || ownership.reason === "watcher_missing")) {
+        return buildResult(taskId, statusStr, phaseStr, "orphaned_running", "high", reasons, [
+            "mark_orphaned",
+            "leave_unchanged",
+        ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+    }
+    // ── artifact_collection_stuck: in collecting_artifacts phase and stuck ──
+    if (collectingArtifactsPhase) {
+        const collectionStuck = (heartbeatStale || heartbeatPossiblyStale) && (logsStale || childPidAlive === false);
+        if (collectionStuck) {
+            return buildResult(taskId, statusStr, phaseStr, "artifact_collection_stuck", "high", reasons, [
+                "recollect_artifacts",
+                "mark_failed_stale",
+                "leave_unchanged",
+            ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+        }
+        // Collecting but not clearly stuck — possibly still active
+        if (heartbeatFresh || logsGrowing) {
+            return buildResult(taskId, statusStr, phaseStr, "active_running", "medium", reasons, [
+                "leave_unchanged",
+            ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+        }
+        return buildResult(taskId, statusStr, phaseStr, "artifact_collection_stuck", "medium", reasons, [
+            "recollect_artifacts",
+            "leave_unchanged",
+        ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+    }
+    // ── active_running: heartbeat fresh, watcher owns, logs growing or PID alive ──
+    if (heartbeatFresh && ownership.owned && (logsGrowing || childPidAlive === true)) {
+        return buildResult(taskId, statusStr, phaseStr, "active_running", "high", reasons, [
+            "leave_unchanged",
+        ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+    }
+    // ── stale_running: heartbeat stale, PID dead, watcher doesn't own ──
+    if (heartbeatStale && (childPidAlive === false || !ownership.owned) && logsStale) {
+        return buildResult(taskId, statusStr, phaseStr, "stale_running", "high", reasons, [
+            "mark_failed_stale",
+            "collect_artifacts",
+            "leave_unchanged",
+        ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+    }
+    // ── possibly_stale_running: some stale signals but not enough for high confidence ──
+    // This branch catches the PID-reuse-suspected case as well: PID is alive
+    // but everything else is stale. We refuse to call it "active".
+    if (pidReuseSuspected) {
+        return buildResult(taskId, statusStr, phaseStr, "possibly_stale_running", "medium", reasons, [
+            "leave_unchanged",
+            "mark_failed_stale",
+        ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+    }
+    if (heartbeatStale || (heartbeatPossiblyStale && (logsStale || !ownership.owned))) {
+        return buildResult(taskId, statusStr, phaseStr, "possibly_stale_running", "medium", reasons, [
+            "leave_unchanged",
+            "mark_failed_stale",
+        ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+    }
+    // ── unknown: insufficient evidence ──
+    return buildResult(taskId, statusStr, phaseStr, "unknown", "low", reasons, [
+        "leave_unchanged",
+    ], evidence, input.include_logs ? { stdoutPath, stderrPath } : null);
+}
+// ── Result builders ─────────────────────────────────────────────────
+function buildResult(taskId, status, phase, diagnosis, confidence, reasons, safeActions, evidence, logPaths) {
+    return {
+        task_id: taskId,
+        status,
+        phase,
+        diagnosis,
+        confidence,
+        reasons,
+        safe_actions: safeActions,
+        evidence,
+        logs: logPaths
+            ? {
+                stdout_tail: readTailLines(logPaths.stdoutPath, LOG_TAIL_LINES),
+                stderr_tail: readTailLines(logPaths.stderrPath, Math.min(LOG_TAIL_LINES, 20)),
+            }
+            : null,
+    };
+}
+function buildTerminalDiagnosis(taskId, status, phase) {
+    return {
+        task_id: taskId,
+        status,
+        phase,
+        diagnosis: "terminal",
+        confidence: "high",
+        reasons: [`status "${status}" is already terminal; no reconciliation needed`],
+        safe_actions: ["leave_unchanged"],
+        evidence: emptyEvidence(),
+        logs: null,
+    };
+}
+function buildUnknownDiagnosis(taskId, status, phase, extraReasons) {
+    return {
+        task_id: taskId,
+        status,
+        phase,
+        diagnosis: "unknown",
+        confidence: "low",
+        reasons: ["insufficient evidence to diagnose", ...extraReasons],
+        safe_actions: ["leave_unchanged"],
+        evidence: emptyEvidence(),
+        logs: null,
+    };
+}
+function emptyEvidence() {
+    return {
+        heartbeat_age_seconds: null,
+        stdout_age_seconds: null,
+        stderr_age_seconds: null,
+        stdout_size_bytes: null,
+        stderr_size_bytes: null,
+        child_pid: null,
+        child_pid_alive: null,
+        child_started_at: null,
+        pid_reuse_suspected: false,
+        watcher_instance_id: null,
+        current_watcher_instance_id: null,
+        watcher_owns_task: false,
+        watcher_ownership_reason: "no_runtime_record",
+        has_result_md: false,
+        has_test_log: false,
+        has_git_diff: false,
+        has_artifact_manifest: false,
+        task_started_at: null,
+        status_updated_at: null,
+        collecting_artifacts_phase: false,
+    };
+}

package/dist/tools/discardWorktree.d.ts

@@ -0,0 +1,24 @@
+/**
+ * v1.0.0 Part B: discard_worktree MCP 工具 handler — 移除隔离 worktree 与临时
+ * branch，并将最终状态归档到 .patchwarden/worktree-archive/。
+ *
+ * 参考 src/tools/auditTask.ts 的导出/返回风格。
+ */
+export interface DiscardWorktreeInput {
+    worktree_id: string;
+    repo_path: string;
+}
+export interface DiscardWorktreeOutput {
+    worktree_id: string;
+    status: "discarded";
+    discarded_at: string;
+}
+/**
+ * 丢弃指定 worktree：移除 worktree 目录、删除临时 branch、归档状态。
+ *
+ * @throws PatchWardenError("workspace_path_escape") 当 repo_path 逃逸出 workspaceRoot
+ * @throws PatchWardenError("worktree_not_found") 当 worktree 不存在
+ * @throws PatchWardenError("invalid_worktree_state") 当 worktree 非 active
+ * @throws PatchWardenError("worktree_discard_failed") 当 git worktree remove 失败
+ */
+export declare function discardWorktreeTool(input: DiscardWorktreeInput): DiscardWorktreeOutput;

package/dist/tools/discardWorktree.js

@@ -0,0 +1,27 @@
+/**
+ * v1.0.0 Part B: discard_worktree MCP 工具 handler — 移除隔离 worktree 与临时
+ * branch，并将最终状态归档到 .patchwarden/worktree-archive/。
+ *
+ * 参考 src/tools/auditTask.ts 的导出/返回风格。
+ */
+import { getConfig } from "../config.js";
+import { guardWorkspacePath } from "../security/pathGuard.js";
+import { discardWorktree } from "../goal/worktreeManager.js";
+/**
+ * 丢弃指定 worktree：移除 worktree 目录、删除临时 branch、归档状态。
+ *
+ * @throws PatchWardenError("workspace_path_escape") 当 repo_path 逃逸出 workspaceRoot
+ * @throws PatchWardenError("worktree_not_found") 当 worktree 不存在
+ * @throws PatchWardenError("invalid_worktree_state") 当 worktree 非 active
+ * @throws PatchWardenError("worktree_discard_failed") 当 git worktree remove 失败
+ */
+export function discardWorktreeTool(input) {
+    const config = getConfig();
+    const repoPathSafe = guardWorkspacePath(input.repo_path, config.workspaceRoot);
+    discardWorktree(input.worktree_id, repoPathSafe);
+    return {
+        worktree_id: input.worktree_id,
+        status: "discarded",
+        discarded_at: new Date().toISOString(),
+    };
+}

package/dist/tools/discoverTools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * v0.7.1: discover_tools MCP 工具封装。
+ *
+ * 搜索候选工具，返回压缩摘要和风险等级。
+ * 不加入 chatgpt_core，仅 full profile。
+ * v0.8.1: 为每个搜索结果生成 discoveryToken（server-side 保存）。
+ * v0.9.0: 传入 usageStatsProvider，从 invocation.log 聚合历史成功率用于混合排序。
+ */
+import type { ToolDef } from "./registry.js";
+import { discoverTools as searchDiscover, type DiscoverToolsInput } from "./toolSearch.js";
+export declare function discoverTools(input: DiscoverToolsInput, tools: ToolDef[]): ReturnType<typeof searchDiscover>;

package/dist/tools/discoverTools.js

@@ -0,0 +1,39 @@
+/**
+ * v0.7.1: discover_tools MCP 工具封装。
+ *
+ * 搜索候选工具，返回压缩摘要和风险等级。
+ * 不加入 chatgpt_core，仅 full profile。
+ * v0.8.1: 为每个搜索结果生成 discoveryToken（server-side 保存）。
+ * v0.9.0: 传入 usageStatsProvider，从 invocation.log 聚合历史成功率用于混合排序。
+ */
+import { join } from "node:path";
+import { buildToolRegistry } from "./toolRegistry.js";
+import { discoverTools as searchDiscover } from "./toolSearch.js";
+import { issueToken } from "../security/discoveryTokenStore.js";
+import { aggregateUsageStats } from "./toolUsageStats.js";
+import { getConfig } from "../config.js";
+export function discoverTools(input, tools) {
+    const registry = buildToolRegistry(tools);
+    // v0.9.0: 从 invocation.log 聚合历史成功率，用于混合排序公式
+    let usageMap = null;
+    try {
+        const workspaceRoot = getConfig().workspaceRoot;
+        const logsDir = join(workspaceRoot, ".patchwarden", "logs");
+        usageMap = aggregateUsageStats(logsDir);
+    }
+    catch {
+        // 配置读取失败或日志目录不存在时，无历史数据（不阻断搜索）
+        usageMap = null;
+    }
+    return searchDiscover(input, registry, (tool) => {
+        return issueToken({
+            toolName: tool.name,
+            risk: tool.risk,
+            query: input.query,
+            schemaDigest: tool.inputSchemaDigest,
+            profile: input.profile ?? "full",
+        });
+    }, usageMap
+        ? (toolName) => usageMap.get(toolName) ?? null
+        : undefined);
+}

package/dist/tools/explainTool.d.ts

@@ -0,0 +1,11 @@
+/**
+ * v0.7.1: explain_tool MCP 工具封装。
+ *
+ * 展开单个工具详情，可选包含完整 inputSchema。
+ * 不加入 chatgpt_core，仅 full profile。
+ * v0.8.1: includeSchema=true 时通过 tokenPeeker 二次确认 schema digest，
+ *         检测 registry 与实际 toolDef 之间的 schema drift。
+ */
+import type { ToolDef } from "./registry.js";
+import { explainTool as searchExplain, type ExplainToolInput } from "./toolSearch.js";
+export declare function explainTool(input: ExplainToolInput, tools: ToolDef[]): ReturnType<typeof searchExplain>;

package/dist/tools/explainTool.js

@@ -0,0 +1,21 @@
+/**
+ * v0.7.1: explain_tool MCP 工具封装。
+ *
+ * 展开单个工具详情，可选包含完整 inputSchema。
+ * 不加入 chatgpt_core，仅 full profile。
+ * v0.8.1: includeSchema=true 时通过 tokenPeeker 二次确认 schema digest，
+ *         检测 registry 与实际 toolDef 之间的 schema drift。
+ */
+import { buildToolRegistry, computeSchemaDigest } from "./toolRegistry.js";
+import { explainTool as searchExplain } from "./toolSearch.js";
+export function explainTool(input, tools) {
+    const registry = buildToolRegistry(tools);
+    const toolDefsMap = new Map(tools.map((t) => [t.name, t]));
+    return searchExplain(input, registry, toolDefsMap, (toolName) => {
+        const toolDef = toolDefsMap.get(toolName);
+        if (!toolDef)
+            return null;
+        const currentDigest = computeSchemaDigest(toolDef.inputSchema);
+        return { schemaDigest: currentDigest };
+    });
+}

package/dist/tools/getTaskSummary.js

@@ -6,6 +6,7 @@ import { getTaskStatus } from "./getTaskStatus.js";
 import { redactSensitiveValue } from "../security/contentRedaction.js";
 const TERMINAL_STATUSES = new Set([
     "done",
+    "done_by_agent",
     "failed",
     "failed_verification",
     "failed_scope_violation",
@@ -80,7 +81,7 @@ export function getTaskSummary(taskId, options = {}) {
         }
     }
     else if (terminal) {
-        if (status.status !== "done" || outOfScope.length > 0 || verifyStatus === "failed") {
+        if ((status.status !== "done" && status.status !== "done_by_agent") || outOfScope.length > 0 || verifyStatus === "failed") {
             acceptanceStatus = "failed";
         }
         else if (verifyStatus === "passed") {

package/dist/tools/goalSubgoalTask.d.ts

@@ -0,0 +1,51 @@
+/**
+ * v0.8.0: createSubgoalTask — 原子地将一个新 subgoal 关联到一个新任务。
+ *
+ * 流程（原子语义）：
+ *   1. 读取 goal_status.json（不存在则抛 goal_not_found）
+ *   2. addSubgoal（校验 depends_on 引用已有 subgoal）
+ *   3. createTask 创建关联任务（写入 goal_id / subgoal_id 到 task status.json）
+ *   4. linkTaskToSubgoal（将 task_id 关联到 subgoal）
+ *   5. updateSubgoalStatus(running)（ready → running）
+ *   6. 写回 goal_status.json
+ *
+ * 注意：
+ *   - createSubgoalTask 强制 execution_mode 为 "execute"，因为 assess_only 不产生可关联的 task。
+ *   - createTask 内部使用 getConfig()，因此 workspaceRoot 由全局配置决定。
+ */
+import { type CreateTaskInput } from "./createTask.js";
+export interface CreateSubgoalTaskInput {
+    goal_id: string;
+    subgoal_title: string;
+    depends_on?: string[];
+    plan_id?: string;
+    inline_plan?: string;
+    plan_title?: string;
+    template?: CreateTaskInput["template"];
+    goal?: string;
+    agent?: string;
+    repo_path: string;
+    test_command?: string;
+    verify_commands?: string[];
+    timeout_seconds?: number;
+    execution_mode?: "assess_only" | "execute";
+    assessment_id?: string;
+    scope?: string[];
+    forbidden?: string[];
+    verification?: string[];
+    done_evidence?: string[];
+    isolate_worktree?: boolean;
+}
+export interface CreateSubgoalTaskOutput {
+    subgoal_id: string;
+    task_id: string;
+    subgoal_status: "running";
+}
+/**
+ * 原子地创建一个 subgoal 并关联到一个新任务。
+ *
+ * @throws PatchWardenError("goal_not_found") 当 goal_id 不存在
+ * @throws PatchWardenError("invalid_dependency") 当 depends_on 引用不存在的 subgoal
+ * @throws PatchWardenError("invalid_execution_mode") 当 execution_mode 为 "assess_only"
+ */
+export declare function createSubgoalTask(input: CreateSubgoalTaskInput): CreateSubgoalTaskOutput;