@pencil-agent/nano-pencil 1.13.5 → 1.13.6

package/dist/build-meta.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.13.6",
+  "commitHash": "d5ae966",
+  "branch": "main",
+  "builtAt": "2026-04-23T04:35:24.822Z"
+}

package/dist/extensions/defaults/CLAUDE.md

@@ -42,14 +42,14 @@ plan/exit-plan-mode-tool.ts: createExitPlanModeTool() - ExitPlanMode tool with p
 plan/plan-agents.ts: Explore/Plan subagent definitions with read-only tools for plan mode workflow
 plan/plan-validation.ts: validatePlan() - validates plan has required sections (Context, Approach, Files, Verification)
 plan/teammate-approval.ts: isInTeammateContext(), submitPlanToLeader(), formatPlanSubmittedMessage() - teammate plan approval integration
-sal/index.ts: SAL extension entry, enabled by default, registers --nosal/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/agent_end hooks; /sal:setup writes ~/.memory-experiments/credentials.json with adapter inference (insforge/jsonl/noop); publishes structuralAnchor via core/runtime/turn-context (no SAL-specific globals); emits run_start/turn_anchor/memory_recalls/run_end eval events through pluggable EvalSink; reads memoryRecallSnapshot from turn-context bus in agent_end; runtime no-op when --nosal is set
+sal/index.ts: SAL extension entry, enabled by default, registers --nosal/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_end hooks; /sal:setup writes ~/.memory-experiments/credentials.json with adapter inference (insforge/jsonl/noop); publishes structuralAnchor via core/runtime/turn-context (no SAL-specific globals); emits run_start/turn_anchor/memory_recalls/tool_trace/run_end eval events through pluggable EvalSink; reads memoryRecallSnapshot from turn-context bus in agent_end; runtime no-op when --nosal is set; auto-injects pencil_version from build-meta.json into run_start; emergency flush on beforeExit/SIGHUP/SIGTERM; stale run cleanup is opt-in via NANOPENCIL_EVAL_CLEANUP_STALE_RUNS / credentials cleanup_stale_runs; tool_trace is a bounded per-turn summary and includes no-tool turns
 sal/terrain.ts: TerrainSnapshot/TerrainNode/TerrainEdge model, async buildTerrainIndex()/isSnapshotStale() (fs/promises + periodic yields so TUI can flush under block terminals like Warp), checkDipCoverage(), moduleIdForPath(), parses P2 CLAUDE.md and P3 file headers
 sal/anchors.ts: StructuralAnchor/AnchorResolution model, locateTask(), locateAction(), evidence-driven scoring with tunable SalWeights, CJK bigram tokenization
 sal/weights.ts: SalWeights interface, SAL_DEFAULT_WEIGHTS, loadSalWeights() reads sal-config.json from workspace or .memory-experiments/sal/
 sal/eval/index.ts: createEvalSink() factory + barrel re-exports; adapter selection via options.adapter or endpoint scheme inference (http(s)→insforge, file://|/|./|../→jsonl, missing→noop); ONLY entry point SAL imports from
 sal/eval/types.ts: EvalSink interface, EvalEventEnvelope/EvalEventType (run_start/run_end/turn_anchor/memory_recalls), EvalAdapterId ("insforge"|"jsonl"|"noop"), CreateEvalSinkOptions, createEvalEvent factory; zero-dependency type surface
 sal/eval/noop-sink.ts: noopSink — silent EvalSink used when eval disabled or no adapter configured
-sal/eval/insforge-sink.ts: InsForgeEvalSink — PostgREST adapter, routes run_start→eval_runs INSERT (merge-duplicates), turn_anchor→eval_turns + eval_sal_anchors×2, memory_recalls→eval_memory_recalls batch INSERT, run_end→eval_runs PATCH; allowSelfSigned TLS option, batching with default 2000ms interval
+sal/eval/insforge-sink.ts: InsForgeEvalSink — PostgREST adapter, routes run_start→eval_runs INSERT (merge-duplicates), turn_anchor→eval_turns + eval_sal_anchors×2, tool_trace→eval_tool_traces bounded per-turn summaries (including no-tool turns and truncation counters), memory_recalls→eval_memory_recalls batch INSERT, run_end→eval_runs PATCH; allowSelfSigned TLS option, batching with default 2000ms interval
 sal/eval/jsonl-sink.ts: JsonlEvalSink — append-only filesystem adapter, one JSON object per line, accepts file:// URLs or plain paths, auto-creates parent dir, batched writes
 sal/README.md: SAL extension usage, sidecar output layout, weights override, pluggability contract
 team/index.ts: AgentTeam extension entry, /team:/team:spawn/:send/:status/:stop/:terminate/:approve/:mode commands, TEAM_MESSAGE_TYPE renderer
@@ -64,4 +64,4 @@ team/TESTING.md: Manual & smoke-test guide for Phase B AgentTeam
 
 Rule: Members complete, one item per line, parent links valid, precise terms first
 
-[COVENANT]: Update this file header on changes and verify against parent CLAUDE.md
+[COVENANT]: Update this file header on changes and verify against parent CLAUDE.md

package/dist/extensions/defaults/sal/eval/insforge-sink.d.ts

@@ -2,7 +2,7 @@
  * [WHO]: Provides InsForgeEvalSink (PostgREST-backed adapter)
  * [FROM]: Depends on node:https, node:http, node:url; ./types.js for EvalSink/EvalEventEnvelope/CreateEvalSinkOptions
  * [TO]: Constructed by eval/index.ts factory when adapter resolves to "insforge"
- * [HERE]: extensions/defaults/sal/eval/insforge-sink.ts - InsForge-specific routing: run_start→eval_runs INSERT (merge-duplicates), turn_anchor→eval_turns + eval_sal_anchors×2, run_end→eval_runs PATCH
+ * [HERE]: extensions/defaults/sal/eval/insforge-sink.ts - InsForge-specific routing: run_start→eval_runs INSERT (merge-duplicates, includes pencil_version), turn_anchor→eval_turns + eval_sal_anchors×2, tool_trace→eval_tool_traces, memory_recalls→eval_memory_recalls, run_end→eval_runs PATCH
  *
  * Pluggable: nothing in this file may be imported from outside the eval/ directory.
  * To add a new backend, write a sibling file with the same EvalSink interface.
@@ -29,6 +29,7 @@ export declare class InsForgeEvalSink implements EvalSink {
     private handleTurnAnchor;
     private handleRunEnd;
     private handleMemoryRecalls;
+    private handleToolTrace;
     private postJson;
     private patchJson;
     private httpJson;

package/dist/extensions/defaults/sal/eval/insforge-sink.js

@@ -2,7 +2,7 @@
  * [WHO]: Provides InsForgeEvalSink (PostgREST-backed adapter)
  * [FROM]: Depends on node:https, node:http, node:url; ./types.js for EvalSink/EvalEventEnvelope/CreateEvalSinkOptions
  * [TO]: Constructed by eval/index.ts factory when adapter resolves to "insforge"
- * [HERE]: extensions/defaults/sal/eval/insforge-sink.ts - InsForge-specific routing: run_start→eval_runs INSERT (merge-duplicates), turn_anchor→eval_turns + eval_sal_anchors×2, run_end→eval_runs PATCH
+ * [HERE]: extensions/defaults/sal/eval/insforge-sink.ts - InsForge-specific routing: run_start→eval_runs INSERT (merge-duplicates, includes pencil_version), turn_anchor→eval_turns + eval_sal_anchors×2, tool_trace→eval_tool_traces, memory_recalls→eval_memory_recalls, run_end→eval_runs PATCH
  *
  * Pluggable: nothing in this file may be imported from outside the eval/ directory.
  * To add a new backend, write a sibling file with the same EvalSink interface.
@@ -103,6 +103,9 @@ export class InsForgeEvalSink {
                 case "memory_recalls":
                     await this.handleMemoryRecalls(event);
                     break;
+                case "tool_trace":
+                    await this.handleToolTrace(event);
+                    break;
                 case "run_end":
                     await this.handleRunEnd(event);
                     break;
@@ -123,6 +126,7 @@ export class InsForgeEvalSink {
                 task_file: strOrNull(p.task_file),
                 model: strOrNull(p.model),
                 thinking: p.thinking === true,
+                pencil_version: strOrNull(p.pencil_version),
                 commit_hash: strOrNull(p.commit, "unknown"),
                 branch_name: strOrNull(p.branch, "unknown"),
                 workspace_root: strOrNull(p.workspace_root),
@@ -213,6 +217,31 @@ export class InsForgeEvalSink {
         }));
         await this.postJson(`${this.base}/api/database/records/eval_memory_recalls`, rows, { prefer: "resolution=ignore-duplicates" });
     }
+    // INSERT into eval_tool_traces — one row per turn with tool usage summary
+    // InsForge columns are all TEXT; JSONB fields must be serialized to strings.
+    async handleToolTrace(ev) {
+        const p = ev.payload;
+        const taskSignals = p.task_signals;
+        await this.postJson(`${this.base}/api/database/records/eval_tool_traces`, [{
+                run_id: ev.run_id,
+                turn_id: String(p.turn_id ?? 0),
+                event_id: ev.event_id,
+                tool_calls: p.tool_calls ? JSON.stringify(p.tool_calls) : null,
+                tool_sequence: p.tool_sequence ? JSON.stringify(p.tool_sequence) : null,
+                intent: strOrNull(taskSignals?.intent),
+                prompt_length: String(taskSignals?.prompt_length ?? 0),
+                has_error_trace: String(taskSignals?.has_error_trace === true),
+                has_file_reference: String(taskSignals?.has_file_reference === true),
+                has_tool_usage: String(p.has_tool_usage === true),
+                total_tool_calls: String(p.total_tool_calls ?? 0),
+                total_errors: String(p.total_errors ?? 0),
+                completed_tool_calls: String(p.completed_tool_calls ?? 0),
+                truncated_tool_calls: String(p.truncated_tool_calls ?? 0),
+                truncated_tool_summary: String(p.truncated_tool_summary ?? 0),
+                duration_ms: String(p.duration_ms ?? 0),
+                recorded_at: ev.ts,
+            }], { prefer: "resolution=ignore-duplicates" });
+    }
     // ------------------------------------------------------------------
     // HTTP helpers
     // ------------------------------------------------------------------

package/dist/extensions/defaults/sal/eval/types.d.ts

@@ -5,7 +5,7 @@
  * [HERE]: extensions/defaults/sal/eval/types.ts - transport-agnostic event types and the EvalSink contract; concrete adapters live in sibling files
  */
 export type EvalVariant = "sal" | "control" | "baseline";
-export type EvalEventType = "run_start" | "run_end" | "turn_anchor" | "memory_recalls";
+export type EvalEventType = "run_start" | "run_end" | "turn_anchor" | "memory_recalls" | "tool_trace";
 /** Wire format for eval events. Adapter implementations decide how to materialize. */
 export interface EvalEventEnvelope {
     run_id: string;

package/dist/extensions/defaults/sal/index.d.ts

@@ -1,12 +1,46 @@
 /**
- * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/agent_end hooks; runtime no-op when --nosal is set
- * [FROM]: Depends on core/extensions/types.ts, core/runtime/turn-context.ts (publishes structuralAnchor), extensions/defaults/sal/terrain.ts, anchors.ts, weights.ts, eval/index.ts (pluggable adapters)
+ * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_end hooks; runtime no-op when --nosal is set
+ * [FROM]: Depends on core/extensions/types.ts (ToolExecutionStartEvent, ToolExecutionEndEvent), core/runtime/turn-context.ts (publishes structuralAnchor), extensions/defaults/sal/terrain.ts, anchors.ts, weights.ts, eval/index.ts (pluggable adapters)
  * [TO]: Loaded by builtin-extensions.ts as a default extension entry point
- * [HERE]: extensions/defaults/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/run_end eval events; /sal:setup writes ~/.memory-experiments/credentials.json
+ * [HERE]: extensions/defaults/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/tool_trace/run_end eval events; tool_trace captures per-turn tool usage profile (call counts, sequences, intent, errors) for self-awareness analytics
  */
+import { type EvalAdapterId } from "./eval/index.js";
 import type { ExtensionAPI } from "../../../core/extensions/types.js";
+import { type AnchorResolution } from "./anchors.js";
 import { SAL_DEFAULT_WEIGHTS } from "./weights.js";
+interface ToolCallRecord {
+    toolCallId: string;
+    tool: string;
+    startMs: number;
+    endMs?: number;
+    isError?: boolean;
+}
+interface TurnState {
+    turnId: number;
+    startedAtMs: number;
+    taskResolution?: AnchorResolution;
+    touchedFiles: Set<string>;
+    toolCalls: ToolCallRecord[];
+    prompt?: string;
+}
+interface EvalCredentials {
+    insforge_url?: string;
+    endpoint?: string;
+    api_key?: string;
+    anon_key?: string;
+    api_key_header?: string;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+    allow_self_signed?: boolean;
+    cleanup_stale_runs?: boolean;
+    /** Adapter selector. When omitted, inferred from endpoint scheme (http→insforge, file/path→jsonl). */
+    adapter?: EvalAdapterId;
+}
+declare function resolveStaleCleanupEnabled(envValue: string | undefined, credentials: EvalCredentials | undefined): boolean;
 declare function normalizeExperimentId(experimentId?: string): string | undefined;
 declare function resolveSalSidecarDir(workspaceRoot: string, experimentId?: string): string;
+type TaskIntent = "fix" | "feat" | "refactor" | "explain" | "explore" | "unknown";
+declare function inferIntent(prompt: string): TaskIntent;
+declare function buildToolTracePayload(turn: TurnState, turnDuration: number): Record<string, unknown>;
 export default function salExtension(api: ExtensionAPI): Promise<void>;
-export { SAL_DEFAULT_WEIGHTS, normalizeExperimentId, resolveSalSidecarDir };
+export { SAL_DEFAULT_WEIGHTS, buildToolTracePayload, inferIntent, normalizeExperimentId, resolveSalSidecarDir, resolveStaleCleanupEnabled, };

package/dist/extensions/defaults/sal/index.js

@@ -1,17 +1,53 @@
 /**
- * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/agent_end hooks; runtime no-op when --nosal is set
- * [FROM]: Depends on core/extensions/types.ts, core/runtime/turn-context.ts (publishes structuralAnchor), extensions/defaults/sal/terrain.ts, anchors.ts, weights.ts, eval/index.ts (pluggable adapters)
+ * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_end hooks; runtime no-op when --nosal is set
+ * [FROM]: Depends on core/extensions/types.ts (ToolExecutionStartEvent, ToolExecutionEndEvent), core/runtime/turn-context.ts (publishes structuralAnchor), extensions/defaults/sal/terrain.ts, anchors.ts, weights.ts, eval/index.ts (pluggable adapters)
  * [TO]: Loaded by builtin-extensions.ts as a default extension entry point
- * [HERE]: extensions/defaults/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/run_end eval events; /sal:setup writes ~/.memory-experiments/credentials.json
+ * [HERE]: extensions/defaults/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/tool_trace/run_end eval events; tool_trace captures per-turn tool usage profile (call counts, sequences, intent, errors) for self-awareness analytics
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, join, relative } from "node:path";
+import { isAbsolute, join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createEvalEvent, createEvalSink, } from "./eval/index.js";
 import { getTurnContext, resetTurnContext, setTurnContext } from "../../../core/runtime/turn-context.js";
 import { locateAction, locateTask } from "./anchors.js";
 import { buildTerrainIndex, checkDipCoverage, isSnapshotStale, toPosixPath, } from "./terrain.js";
 import { loadSalWeights, SAL_DEFAULT_WEIGHTS } from "./weights.js";
+function loadBuildMeta() {
+    const fallback = { version: "dev" };
+    try {
+        const thisFile = fileURLToPath(import.meta.url);
+        const thisDir = dirname(thisFile);
+        // dist layout: dist/extensions/defaults/sal/index.js → dist/build-meta.json
+        const distMeta = join(thisDir, "..", "..", "..", "build-meta.json");
+        if (existsSync(distMeta)) {
+            const parsed = JSON.parse(readFileSync(distMeta, "utf-8"));
+            return {
+                version: parsed.version ?? fallback.version,
+                commitHash: parsed.commitHash,
+                branch: parsed.branch,
+            };
+        }
+        // Dev fallback: project root package.json
+        const pkgCandidates = [
+            join(thisDir, "..", "..", "..", "package.json"), // from extensions/defaults/sal/
+            join(thisDir, "..", "..", "..", "..", "package.json"), // one more level in case
+        ];
+        for (const p of pkgCandidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.name === "@pencil-agent/nano-pencil") {
+                    return { version: pkg.version ?? fallback.version };
+                }
+            }
+        }
+    }
+    catch {
+        // non-fatal — return fallback
+    }
+    return fallback;
+}
+const BUILD_META = loadBuildMeta();
 const NOSAL_FLAG = "nosal";
 const SAL_REBUILD_FLAG = "sal-rebuild-terrain";
 const SAL_CONTEXT_BUDGET_TOKENS = 800;
@@ -25,6 +61,14 @@ const EVAL_API_KEY_ENV = "NANOPENCIL_EVAL_API_KEY";
 const EVAL_API_KEY_HEADER_ENV = "NANOPENCIL_EVAL_API_KEY_HEADER";
 const EVAL_HEADERS_JSON_ENV = "NANOPENCIL_EVAL_HEADERS_JSON";
 const EVAL_CREDENTIALS_FILE_ENV = "NANOPENCIL_EVAL_CREDENTIALS_FILE";
+const EVAL_STALE_CLEANUP_ENV = "NANOPENCIL_EVAL_CLEANUP_STALE_RUNS";
+const MAX_TOOL_SEQUENCE = 32;
+const MAX_TOOL_SUMMARY_TOOLS = 16;
+function resolveStaleCleanupEnabled(envValue, credentials) {
+    if (envValue !== undefined)
+        return isTruthy(envValue);
+    return credentials?.cleanup_stale_runs === true;
+}
 function isTruthy(value) {
     if (!value)
         return false;
@@ -202,6 +246,86 @@ function extractToolFilePaths(toolName, args, workspaceRoot) {
     }
     return out;
 }
+const INTENT_PATTERNS = [
+    ["fix", [
+            /\b(fix|bug|error|issue|broken|crash|fail|wrong|debug|patch|repair)\b/i,
+            /(修复|报错|问题|异常|崩溃|失败|错误)/,
+        ]],
+    ["refactor", [
+            /\b(refactor|rename|extract|move|split|merge|clean\s?up|restructure)\b/i,
+            /(重构|整理|拆分|重命名|抽取)/,
+        ]],
+    ["explain", [
+            /\b(explain|how does|what is|why does|understand|read|review|audit|tell me|describe)\b/i,
+            /(解释|为什么|怎么|什么|看一下|看下|评审|核审|说明)/,
+        ]],
+    ["feat", [
+            /\b(add|implement|create|build|new|feature|support|enable|integrate)\b/i,
+            /(增加|新增|实现|添加|功能|支持|接入)/,
+        ]],
+    ["explore", [
+            /\b(find|search|look for|where|locate|explore|check|investigate|list)\b/i,
+            /(查找|找|搜|在哪|检查|排查)/,
+        ]],
+];
+function inferIntent(prompt) {
+    if (!prompt || prompt.length < 4)
+        return "unknown";
+    for (const [intent, patterns] of INTENT_PATTERNS) {
+        for (const pattern of patterns) {
+            if (pattern.test(prompt))
+                return intent;
+        }
+    }
+    return "unknown";
+}
+function buildToolTracePayload(turn, turnDuration) {
+    const toolSummary = new Map();
+    let totalErrors = 0;
+    for (const tc of turn.toolCalls) {
+        const entry = toolSummary.get(tc.tool) ?? { count: 0, errors: 0, totalMs: 0, completed: 0 };
+        entry.count += 1;
+        if (tc.isError) {
+            entry.errors += 1;
+            totalErrors += 1;
+        }
+        if (tc.endMs != null) {
+            entry.totalMs += tc.endMs - tc.startMs;
+            entry.completed += 1;
+        }
+        toolSummary.set(tc.tool, entry);
+    }
+    const summarizedTools = Array.from(toolSummary.entries())
+        .sort((a, b) => b[1].count - a[1].count || a[0].localeCompare(b[0]))
+        .slice(0, MAX_TOOL_SUMMARY_TOOLS)
+        .map(([tool, stats]) => ({
+        tool,
+        count: stats.count,
+        errors: stats.errors,
+        avg_ms: stats.completed > 0 ? Math.round(stats.totalMs / stats.completed) : null,
+        completed_calls: stats.completed,
+    }));
+    const sequence = turn.toolCalls.slice(0, MAX_TOOL_SEQUENCE).map((tc) => tc.tool);
+    const completedToolCalls = turn.toolCalls.filter((tc) => tc.endMs != null).length;
+    return {
+        turn_id: turn.turnId,
+        tool_calls: summarizedTools,
+        tool_sequence: sequence,
+        task_signals: {
+            prompt_length: (turn.prompt ?? "").length,
+            has_error_trace: /\b(error|exception|stack\s?trace|traceback|panic)\b/i.test(turn.prompt ?? ""),
+            has_file_reference: /[\w./-]+\.(ts|tsx|js|jsx|py|go|rs|md|json)/.test(turn.prompt ?? ""),
+            intent: inferIntent(turn.prompt ?? ""),
+        },
+        has_tool_usage: turn.toolCalls.length > 0,
+        total_tool_calls: turn.toolCalls.length,
+        total_errors: totalErrors,
+        completed_tool_calls: completedToolCalls,
+        truncated_tool_calls: Math.max(0, turn.toolCalls.length - sequence.length),
+        truncated_tool_summary: Math.max(0, toolSummary.size - summarizedTools.length),
+        duration_ms: turnDuration,
+    };
+}
 function buildContextInjection(resolution, snapshot) {
     if (!resolution.selected || resolution.candidates.length === 0)
         return undefined;
@@ -298,6 +422,63 @@ async function emitEval(runtime, eventType, salEnabled, payload) {
         console.error("[sal][eval] failed to emit event:", err.message);
     }
 }
+/**
+ * Fire-and-forget PATCH to mark stale "running" eval runs as "abandoned".
+ * Uses raw HTTP so it stays independent of the EvalSink batching pipeline.
+ * Fully async — callers should void-call this and never await on the hot path.
+ */
+async function cleanupStaleRuns(runtime) {
+    if (!runtime.evalEndpoint)
+        return;
+    const base = runtime.evalEndpoint.replace(/\/+$/, "");
+    // Mark runs from this workspace that are still "running" (but not the current run)
+    const url = `${base}/api/database/records/eval_runs?` +
+        `status=eq.running&` +
+        `workspace_root=eq.${encodeURIComponent(runtime.workspaceRoot)}&` +
+        `run_id=neq.${encodeURIComponent(runtime.evalRunId)}`;
+    const headers = { "Content-Type": "application/json" };
+    if (runtime.evalAnonKey) {
+        headers["apikey"] = runtime.evalAnonKey;
+        headers["Authorization"] = `Bearer ${runtime.evalAnonKey}`;
+    }
+    if (runtime.evalApiKey) {
+        headers[runtime.evalApiKeyHeader ?? "x-api-key"] = runtime.evalApiKey;
+        if (!runtime.evalAnonKey) {
+            headers["Authorization"] = `Bearer ${runtime.evalApiKey}`;
+        }
+    }
+    Object.assign(headers, runtime.evalHeaders);
+    const body = JSON.stringify({
+        status: "abandoned",
+        ended_at: new Date().toISOString(),
+    });
+    const { request: httpsRequest } = await import("node:https");
+    const { request: httpRequest } = await import("node:http");
+    const { URL } = await import("node:url");
+    const parsed = new URL(url);
+    const isHttps = parsed.protocol === "https:";
+    const reqFn = isHttps ? httpsRequest : httpRequest;
+    const port = parsed.port ? Number(parsed.port) : (isHttps ? 443 : 80);
+    return new Promise((resolve) => {
+        const req = reqFn({
+            hostname: parsed.hostname,
+            port,
+            path: parsed.pathname + parsed.search,
+            method: "PATCH",
+            headers: { ...headers, "Content-Length": Buffer.byteLength(body) },
+            timeout: 5000,
+            ...(isHttps && runtime.evalAllowSelfSigned ? { rejectUnauthorized: false } : {}),
+        }, (res) => {
+            // Drain response body (required to free the socket)
+            res.resume();
+            res.on("end", () => resolve());
+        });
+        req.on("error", () => resolve());
+        req.on("timeout", () => { req.destroy(); resolve(); });
+        req.write(body);
+        req.end();
+    });
+}
 export default async function salExtension(api) {
     api.registerFlag(NOSAL_FLAG, {
         type: "boolean",
@@ -345,6 +526,7 @@ export default async function salExtension(api) {
     }
     const evalAllowSelfSigned = isTruthy(process.env["NANOPENCIL_EVAL_ALLOW_SELF_SIGNED"]) ||
         (credentials?.allow_self_signed ?? false);
+    const allowStaleCleanup = resolveStaleCleanupEnabled(process.env[EVAL_STALE_CLEANUP_ENV], credentials);
     const evalSink = createEvalSink({
         enabled: evalCollectionEnabled && !!evalEndpoint,
         adapter: evalAdapter,
@@ -360,7 +542,7 @@ export default async function salExtension(api) {
         workspaceRoot,
         weights,
         weightsSource,
-        turn: { turnId: 0, startedAtMs: Date.now(), touchedFiles: new Set() },
+        turn: { turnId: 0, startedAtMs: Date.now(), touchedFiles: new Set(), toolCalls: [] },
         sidecarDir,
         evalSink,
         evalAdapter,
@@ -369,16 +551,21 @@ export default async function salExtension(api) {
         evalAnonKey,
         evalApiKeyHeader,
         evalHeaders,
+        evalAllowSelfSigned,
         evalEnabled: evalSink.enabled,
         evalRunId,
         evalVariantOverride,
         evalStartedAtMs: Date.now(),
         evalRunStarted: false,
         turnCounter: 0,
+        allowStaleCleanup,
         evalMetadata: {
             workspace_root: workspaceRoot,
             session_id: evalRunId,
         },
+        buildMeta: BUILD_META,
+        staleCleanupDone: false,
+        pendingRebuild: false,
     };
     const isEnabled = () => !api.getFlag(NOSAL_FLAG);
     api.registerCommand("sal:coverage", {
@@ -506,11 +693,24 @@ export default async function salExtension(api) {
         },
     });
     api.on("before_agent_start", async (event, ctx) => {
+        // ---------------------------------------------------------------
+        // ZERO-I/O CONTRACT: this handler must NEVER await filesystem work.
+        // runner.ts enforces a 1500ms timeout on before_agent_start; any
+        // I/O (terrain build, staleness probe, HTTP) risks timeout which
+        // silently drops SAL's appendSystemPrompt injection.
+        //
+        // All terrain building and refresh happens in the background:
+        //   1. Extension load → setImmediate prewarm
+        //   2. agent_end     → async staleness check + rebuild
+        //   3. --sal-rebuild-terrain → flag read here, rebuild in agent_end
+        //
+        // This handler only reads runtime.snapshot (in-memory) and runs
+        // locateTask() (pure computation, <5ms).
+        // ---------------------------------------------------------------
         // Yield once so any UI frame queued via process.nextTick right before
-        // session.prompt() (notably the user-message bubble) flushes to stdout
-        // BEFORE we start the terrain work below. Without this, GPU block
-        // terminals (Warp) can coalesce the whole turn's render into one block
-        // that only paints when the turn ends.
+        // session.prompt() (notably the user-message bubble) flushes to stdout.
+        // Without this, GPU block terminals (Warp) coalesce the whole turn's
+        // render into one block that only paints when the turn ends.
         await new Promise((resolve) => setImmediate(resolve));
         resetTurnContext();
         runtime.turnCounter += 1;
@@ -518,20 +718,25 @@ export default async function salExtension(api) {
             turnId: runtime.turnCounter,
             startedAtMs: Date.now(),
             touchedFiles: new Set(),
+            toolCalls: [],
             prompt: event.prompt,
         };
         if (!runtime.evalRunStarted && runtime.evalEnabled) {
             runtime.evalRunStarted = true;
             runtime.evalMetadata.model = runtime.evalMetadata.model ?? ctx.model?.id ?? ctx.model?.name;
-            await emitEval(runtime, "run_start", isEnabled(), {
+            // emitEval pushes to a batching queue; does NOT await HTTP.
+            void emitEval(runtime, "run_start", isEnabled(), {
                 task_description: (event.prompt ?? "").slice(0, 500),
                 task_file: process.env.NANOPENCIL_EXPERIMENT_TASK_FILE,
                 model: runtime.evalMetadata.model ?? "unknown",
                 thinking: false,
-                commit: process.env.NANOPENCIL_EVAL_COMMIT ?? "unknown",
-                branch: process.env.NANOPENCIL_EVAL_BRANCH ?? "unknown",
+                pencil_version: runtime.buildMeta.version,
+                commit: process.env.NANOPENCIL_EVAL_COMMIT ?? runtime.buildMeta.commitHash ?? "unknown",
+                branch: process.env.NANOPENCIL_EVAL_BRANCH ?? runtime.buildMeta.branch ?? "unknown",
                 workspace_root: runtime.workspaceRoot,
             });
+            // Strategy B: optional fire-and-forget stale run cleanup.
+            scheduleStaleCleanup();
         }
         if (!isEnabled())
             return undefined;
@@ -541,10 +746,15 @@ export default async function salExtension(api) {
         const prompt = (event.prompt ?? "").trim();
         if (prompt.length < 12)
             return undefined;
-        const forceRebuild = Boolean(api.getFlag(SAL_REBUILD_FLAG));
-        const snapshot = await ensureSnapshot(runtime, forceRebuild);
+        // Pure memory read — if prewarm hasn't finished yet, snapshot is
+        // undefined and we gracefully skip SAL for this turn.
+        const snapshot = runtime.snapshot;
         if (!snapshot)
             return undefined;
+        // Record if user wants a rebuild; agent_end will act on it.
+        if (api.getFlag(SAL_REBUILD_FLAG)) {
+            runtime.pendingRebuild = true;
+        }
         const resolution = locateTask({
             prompt,
             cwd: runtime.workspaceRoot,
@@ -572,6 +782,18 @@ export default async function salExtension(api) {
         const paths = extractToolFilePaths(event.toolName, event.args, runtime.workspaceRoot);
         for (const p of paths)
             runtime.turn.touchedFiles.add(p);
+        runtime.turn.toolCalls.push({
+            toolCallId: event.toolCallId,
+            tool: event.toolName,
+            startMs: Date.now(),
+        });
+    });
+    api.on("tool_execution_end", async (event, _ctx) => {
+        const record = runtime.turn.toolCalls.find((tc) => tc.toolCallId === event.toolCallId);
+        if (record) {
+            record.endMs = Date.now();
+            record.isError = event.isError;
+        }
     });
     api.on("agent_end", async (_event, _ctx) => {
         const turnDuration = Math.max(0, Date.now() - runtime.turn.startedAtMs);
@@ -612,6 +834,9 @@ export default async function salExtension(api) {
                 });
             }
         }
+        // Emit tool usage trace for self-awareness analytics.
+        // Always emit a bounded summary, including no-tool turns.
+        await emitEval(runtime, "tool_trace", isEnabled(), buildToolTracePayload(runtime.turn, turnDuration));
         if (actionRes) {
             persistTurnRecord(runtime, taskRes, actionRes);
         }
@@ -619,7 +844,32 @@ export default async function salExtension(api) {
             turnId: runtime.turn.turnId,
             startedAtMs: Date.now(),
             touchedFiles: new Set(),
+            toolCalls: [],
         };
+        // ---------------------------------------------------------------
+        // Background terrain refresh — runs AFTER the turn is done.
+        // agent_end has no timeout, so async I/O is safe here.
+        // This keeps the snapshot fresh for the NEXT before_agent_start
+        // without ever blocking the hook that has the 1500ms deadline.
+        // ---------------------------------------------------------------
+        if (isEnabled()) {
+            const wantRebuild = runtime.pendingRebuild;
+            runtime.pendingRebuild = false;
+            // Fire-and-forget: don't block agent_end from finishing.
+            void (async () => {
+                try {
+                    if (wantRebuild) {
+                        await ensureSnapshot(runtime, true);
+                    }
+                    else if (runtime.snapshot && await isSnapshotStale(runtime.snapshot)) {
+                        await ensureSnapshot(runtime, true);
+                    }
+                }
+                catch {
+                    // Non-fatal; snapshotErrored flag is set inside ensureSnapshot.
+                }
+            })();
+        }
     });
     api.on("session_shutdown", async () => {
         if (!runtime.evalEnabled)
@@ -632,6 +882,56 @@ export default async function salExtension(api) {
         await runtime.evalSink.flush();
         await runtime.evalSink.close();
     });
+    // ------------------------------------------------------------------
+    // Strategy A: Emergency flush on abnormal exit.
+    // Best-effort — these may not complete if the process is killed hard,
+    // but they cover uncaught exceptions and natural event-loop drain.
+    // IMPORTANT: no sync I/O — all async, fire-and-forget.
+    // ------------------------------------------------------------------
+    let emergencyFlushed = false;
+    const emergencyFlush = () => {
+        if (emergencyFlushed || !runtime.evalEnabled || !runtime.evalRunStarted)
+            return;
+        emergencyFlushed = true;
+        void emitEval(runtime, "run_end", isEnabled(), {
+            status: "interrupted",
+            turn_count: runtime.turnCounter,
+            total_duration_ms: Math.max(0, Date.now() - runtime.evalStartedAtMs),
+        })
+            .then(() => runtime.evalSink.flush())
+            .catch(() => { });
+    };
+    process.on("beforeExit", emergencyFlush);
+    // SIGINT is already handled by interactive-mode (double Ctrl+C → shutdown).
+    // We only add SIGHUP/SIGTERM as secondary safety nets; they do not replace
+    // the primary session_shutdown flow.
+    const signalFlush = () => { emergencyFlush(); };
+    process.on("SIGHUP", signalFlush);
+    process.on("SIGTERM", signalFlush);
+    // ------------------------------------------------------------------
+    // Strategy B: Opt-in stale run cleanup on first turn.
+    // Disabled by default because workspace_root alone cannot distinguish
+    // a dead run from another live nanoPencil instance in the same repo.
+    // Operators may re-enable it explicitly in single-run environments.
+    //
+    // When enabled, on the first before_agent_start, fire-and-forget a PATCH
+    // to mark stale "running" runs from the same workspace as "abandoned".
+    // Runs fully async — does NOT block the before_agent_start return,
+    // so the TUI renders the user's message immediately in GPU block
+    // terminals (Warp, etc.).
+    // ------------------------------------------------------------------
+    function scheduleStaleCleanup() {
+        if (runtime.staleCleanupDone ||
+            !runtime.evalEnabled ||
+            !runtime.evalEndpoint ||
+            !runtime.allowStaleCleanup)
+            return;
+        runtime.staleCleanupDone = true;
+        // Defer to next tick so the current hook returns instantly.
+        setImmediate(() => {
+            void cleanupStaleRuns(runtime).catch(() => { });
+        });
+    }
     // Background prewarm: start the first terrain build as soon as the TUI has
     // painted the initial frame. setImmediate defers it past the current stack
     // and any process.nextTick callbacks, so startup rendering is untouched.
@@ -646,4 +946,4 @@ export default async function salExtension(api) {
         });
     });
 }
-export { SAL_DEFAULT_WEIGHTS, normalizeExperimentId, resolveSalSidecarDir };
+export { SAL_DEFAULT_WEIGHTS, buildToolTracePayload, inferIntent, normalizeExperimentId, resolveSalSidecarDir, resolveStaleCleanupEnabled, };