@raquezha/notrace 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @raquezha/notrace
 
+## 0.0.6
+
+### Patch Changes
+
+- d349d36: Refresh the notrace UI and sample session rendering separately from the antigravity billing fix.
+- 51fda83: fix: preserve assistant toolCall blocks in noheadroom compression and expose notrace failure metadata
+- 7afa746: Package updates for antigravity, norpiv, and notrace.
+
+## 0.0.5
+
+### Patch Changes
+
+- 6eac69d: Relocate core configuration files (`mindsets.json`, `settings.json`, `AGENTS.md`) to a dedicated `config/` directory for better maintainability and a cleaner repository root. Updated `bootstrap.sh` and shell integration to support the new layout.
+- c19a93a: Add a machine-readable `notrace.json` run record alongside the existing HTML report to normalize captured session/task metadata, activity metrics, and evidence for future retrospective and comparison workflows.
+
 ## 0.0.4
 
 ### Patch Changes

package/README.md

@@ -1,48 +1,148 @@
+<p align="center">
+  <img src="./assets/notrace-logo.svg" alt="notrace logo" width="240" />
+</p>
+
 # notrace
 
-Phase 0 / POC local-first interactive HTML Trace Viewer for the Pi Coding Agent. It captures execution traces for workflow debugging — LLM calls, tool executions, token usage, costs — and writes an interactive HTML report to your active task workspace at session end.
+**Traces in, lessons out.**
 
-> **Security warning:** notrace is local-first and now redacts common secrets by default, escapes report rendering, blocks network access in generated reports, and writes private report files. Reports can still contain sensitive prompts, tool payloads, outputs, and local paths. Do not publish generated reports.
+`notrace` is a local-first retrospective engine for the Pi Coding Agent.
+It captures session evidence, writes a versioned `notrace.json` run record, renders a human-readable HTML report, and supports review/compare flows for workflow R&D.
 
-## Features
+## What notrace owns
 
-- **Session timeline**: Every turn, tool call, and LLM completion rendered as an expandable card
-- **Metrics dashboard**: Total tokens, input/output split, cache reads, cost (USD), duration
-- **Clickable `file://` link**: Report path printed to console at session end for instant browser access
-- **Active task aware**: Writes the report into `.workflow/tasks/<task>/notrace.html` when a task is active
-- **HTML report**: Self-contained/offline report with a restrictive CSP and no remote font/network loads
-- **Safer defaults**: Secret-key/value redaction, bounded payload sizes, metadata-only mode, private file permissions, and `.workflow`-confined report writes
+When enabled, `notrace` is the durable retrospective layer for a session.
+It aggregates:
+- core Pi session telemetry
+- workflow/task context
+- optional dynamic extension telemetry
 
-## Output
+Today, Pi is the first harness adapter.
+The canonical run schema is designed so other harness adapters can be added later, but multi-harness support is not implemented in this package yet.
 
+## What notrace does not own
+
+`notrace` is **not**:
+- the live Pi footer
+- the Pi resume/session-switch UX
+- a scraper of terminal status strings
+
+Live footer output, resume hints, and extension footer badges may appear near `notrace` output during shutdown, but they are separate producers.
+
+## Retrospective spine
+
+1. **Capture evidence**: `notrace.json`
+2. **Inspect**: `notrace.html`
+3. **Review outcome**: `notrace.review.json`
+4. **Compare attempts**: `compare:notrace`
+
+## Storage
+
+```text
+.notrace/
+  index.json
+  index.html
+  sessions/
+    <session-id>/
+      notrace.json
+      notrace.html
+      notrace.review.json
 ```
-🔍 [notrace] Observability report generated:
-📂 file:///path/to/.workflow/tasks/my-task/notrace.html
-```
 
-## Usage
+## Canonical run model
+
+Generated `notrace.json` is the source of truth for runtime output, HTML rendering, and downstream tooling.
+The record is versioned and centers on:
+- `kind`
+- `schemaVersion`
+- `traceId`
+- `repository`
+- `session`
+- `task`
+- `captureMode`
+- `conditions`
+- `activity`
+- `telemetry`
+- `events`
+
+Key rule:
+- **consumed tokens** and **saved tokens** are separate metric families
+- optimization telemetry belongs under `telemetry.extensions.*`
+- presentation-only UI strings are not canonical evidence
+
+## Dynamic extension telemetry
+
+`notrace` can include optional structured telemetry from dynamic extensions.
+Current first target is `noheadroom`.
+
+If an extension is absent, `notrace` should still succeed.
+If an extension is present, it can contribute a structured summary such as:
+- loaded / enabled / active state
+- optimization attempts
+- tokens saved
+- last applied compression summary
+
+## Capture modes
+
+Default capture mode is **full**.
 
 ```bash
-# Load directly
 pi --extension ./packages/notrace
+```
 
-# Via nothing mindset (dev, rpiv)
-pi --dev
+Optional modes:
+
+```bash
+NOTRACE_CAPTURE=redacted pi --extension ./packages/notrace
+NOTRACE_CAPTURE=metadata pi --extension ./packages/notrace
+NOTRACE_CAPTURE=full pi --extension ./packages/notrace
 ```
 
-## NPM
+Mode meanings:
+- `full`: full captured payloads; best for local debugging; highest sensitivity
+- `redacted`: captured payloads with common secret-like values redacted
+- `metadata`: minimal capture, no prompt/tool bodies
+
+**Security warning:** even redacted reports can contain sensitive prompts, tool payloads, local paths, and outputs. Do not publish generated reports.
+
+## Review
 
 ```bash
-npm install -g @raquezha/notrace
+npm run review:notrace -- \
+  .notrace/sessions/<id>/notrace.json \
+  --outcome partial \
+  --friction high \
+  --lesson "Headroom reduced tokens but needed manual steering." \
+  --next-change "Try same task with RepoScry enabled."
 ```
 
-## Capture controls
+Review fields:
+- `outcome`: `success`, `partial`, `failed`, `abandoned`, `inconclusive`
+- `friction`: `low`, `medium`, `high`
+- `lesson`
+- `nextChange`
 
-By default, notrace uses `NOTRACE_CAPTURE=redacted`: it captures useful payloads but redacts common secret keys/values and truncates very large values.
+## Compare
 
 ```bash
-NOTRACE_CAPTURE=metadata pi --dev   # no prompt/tool payload bodies
-NOTRACE_CAPTURE=full pi --dev       # unsafe: raw payloads for local debugging only
+npm run compare:notrace -- \
+  .notrace/sessions/<baseline-id>/notrace.json \
+  .notrace/sessions/<candidate-id>/notrace.json
+```
+
+## Templates
+
+HTML source-of-truth lives in `templates/`:
+- `dashboard.sample.json`
+- `session.sample.json`
+- `dashboard.sample.html`
+- `session.sample.html`
+
+Refresh previews after renderer changes:
+
+```bash
+cd packages/notrace
+npm run render:samples
 ```
 
 ## Build

package/assets/notrace-logo.svg

@@ -0,0 +1,20 @@
+<svg viewBox="0 0 420 138" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="notrace">
+  <title>notrace logo</title>
+  <desc>Signal icon above and slightly overlapping the notrace wordmark.</desc>
+  <defs>
+    <linearGradient id="fadeGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#E2754A"/>
+      <stop offset="100%" stop-color="#EDE2D2"/>
+    </linearGradient>
+  </defs>
+  <g id="trace-icon" transform="translate(1 -5) scale(0.93)">
+    <path d="M6,50 C16,18 26,18 36,50 C46,82 54,82 60,50 C64,30 68,30 71,50"
+      fill="none" stroke="url(#fadeGrad)" stroke-width="4" stroke-linecap="round"/>
+    <line x1="74" y1="50" x2="79" y2="50" stroke="#D9C9B5" stroke-width="4" stroke-linecap="round" stroke-opacity="0.6"/>
+    <circle cx="85" cy="50" r="2.2" fill="#D9C9B5" opacity="0.5"/>
+    <circle cx="90" cy="50" r="1.4" fill="#EDE2D2" opacity="0.32"/>
+    <circle cx="94" cy="50" r="0.9" fill="#EDE2D2" opacity="0.15"/>
+  </g>
+  <text x="0" y="114" fill="#ECE3DA" style="fill:#ECE3DA" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif" font-size="96" font-weight="900" letter-spacing="-7">no</text>
+  <text x="82" y="114" fill="#D88462" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif" font-size="96" font-weight="900" letter-spacing="-7">trace</text>
+</svg>

package/assets/notrace-mark.svg

@@ -0,0 +1,18 @@
+<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg" role="img">
+  <title>notrace logo mark</title>
+  <desc>A wave that smooths into a flat line, then fades into dots — color shifts from trace orange to no cream as it dissolves.</desc>
+  <defs>
+    <linearGradient id="fadeGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#E2754A"/>
+      <stop offset="100%" stop-color="#EDE2D2"/>
+    </linearGradient>
+  </defs>
+  <g id="trace-icon">
+    <path d="M6,50 C16,18 26,18 36,50 C46,82 54,82 60,50 C64,30 68,30 71,50"
+          fill="none" stroke="url(#fadeGrad)" stroke-width="4" stroke-linecap="round"/>
+    <line x1="74" y1="50" x2="79" y2="50" stroke="#D9C9B5" stroke-width="4" stroke-linecap="round" stroke-opacity="0.6"/>
+    <circle cx="85" cy="50" r="2.2" fill="#D9C9B5" opacity="0.5"/>
+    <circle cx="90" cy="50" r="1.4" fill="#EDE2D2" opacity="0.32"/>
+    <circle cx="94" cy="50" r="0.9" fill="#EDE2D2" opacity="0.15"/>
+  </g>
+</svg>

package/assets/notrace-wordmark.svg

@@ -0,0 +1,4 @@
+<svg viewBox="0 0 420 96" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="notrace wordmark">
+  <text x="0" y="76" fill="#ECE3DA" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif" font-size="96" font-weight="900" letter-spacing="-7">no</text>
+  <text x="82" y="76" fill="#D88462" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif" font-size="96" font-weight="900" letter-spacing="-7">trace</text>
+</svg>

package/dist/notrace/adapters.d.ts

@@ -0,0 +1,32 @@
+import type { WorkflowContext } from "./types.js";
+export interface WorkflowAdapter {
+    name: string;
+    detect(cwd: string): boolean;
+    getContext(cwd: string): WorkflowContext | null;
+    attach(context: WorkflowContext, artifacts: {
+        html: string;
+        record: string;
+    }): void;
+}
+export declare class NorpivAdapter implements WorkflowAdapter {
+    name: string;
+    detect(cwd: string): boolean;
+    getContext(cwd: string): WorkflowContext | null;
+    attach(context: WorkflowContext, artifacts: {
+        html: string;
+        record: string;
+    }): void;
+}
+export declare class ResearchAdapter implements WorkflowAdapter {
+    name: string;
+    detect(cwd: string): boolean;
+    getContext(cwd: string): WorkflowContext | null;
+    attach(): void;
+}
+export declare class GenericAdapter implements WorkflowAdapter {
+    name: string;
+    detect(): boolean;
+    getContext(): null;
+    attach(): void;
+}
+export declare function getActiveAdapter(cwd: string): WorkflowAdapter;

package/dist/notrace/adapters.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+function appendWorkLogEntry(taskDir, message) {
+    const workMd = path.join(taskDir, "WORK.md");
+    if (!existsSync(workMd))
+        return;
+    try {
+        const text = readFileSync(workMd, "utf-8");
+        const entry = `- ${new Date().toISOString()}: ${message}`;
+        if (!/^(## )?\[LOG\]\s*$/m.test(text)) {
+            writeFileSync(workMd, `${text.trimEnd()}\n\n## [LOG]\n${entry}\n`);
+            return;
+        }
+        const lines = text.split("\n");
+        const logIndex = lines.findIndex(l => /^(## )?\[LOG\]\s*$/.test(l));
+        let nextSection = lines.length;
+        for (let i = logIndex + 1; i < lines.length; i++) {
+            if (/^(## )?\[[A-Z0-9_-]+\]\s*$/.test(lines[i])) {
+                nextSection = i;
+                break;
+            }
+        }
+        const before = lines.slice(0, nextSection);
+        const after = lines.slice(nextSection);
+        before.push(entry);
+        writeFileSync(workMd, `${before.join("\n")}\n${after.join("\n")}`);
+    }
+    catch { }
+}
+export class NorpivAdapter {
+    name = "norpiv";
+    detect(cwd) {
+        return existsSync(path.join(cwd, ".workflow", "active_task.json"));
+    }
+    getContext(cwd) {
+        try {
+            const workflowDir = path.join(cwd, ".workflow");
+            const content = JSON.parse(readFileSync(path.join(workflowDir, "active_task.json"), "utf-8"));
+            const taskPath = content.taskPath || (content.active_task ? path.join("tasks", content.active_task) : null);
+            return {
+                workflow: this.name,
+                taskId: content.active_task || "unknown",
+                taskPath,
+                taskDir: taskPath ? path.resolve(cwd, taskPath) : null
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    attach(context, artifacts) {
+        if (!context.taskDir)
+            return;
+        appendWorkLogEntry(context.taskDir, `notrace retrospective: ${artifacts.html}`);
+    }
+}
+export class ResearchAdapter {
+    name = "research";
+    detect(cwd) {
+        return existsSync(path.join(cwd, ".git")) && !existsSync(path.join(cwd, ".workflow", "active_task.json"));
+    }
+    getContext(cwd) {
+        try {
+            const head = readFileSync(path.join(cwd, ".git", "HEAD"), "utf-8");
+            const branch = head.split("refs/heads/")[1]?.trim() || "main";
+            return { workflow: this.name, taskId: `branch:${branch}`, taskPath: null, taskDir: null };
+        }
+        catch {
+            return null;
+        }
+    }
+    attach() { }
+}
+export class GenericAdapter {
+    name = "generic";
+    detect() { return true; }
+    getContext() { return null; }
+    attach() { }
+}
+const ADAPTERS = [new NorpivAdapter(), new ResearchAdapter(), new GenericAdapter()];
+export function getActiveAdapter(cwd) {
+    return ADAPTERS.find(a => a.detect(cwd)) || new GenericAdapter();
+}

package/dist/notrace/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;

package/dist/notrace/index.js

@@ -0,0 +1,295 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import * as path from "node:path";
+import { getActiveAdapter } from "./adapters.js";
+import { generateHtmlReport, generateDashboardHtml } from "./renderer.js";
+const REDACTED = "[REDACTED by notrace]";
+const SENSITIVE_VALUE_RE = /(bearer\s+[a-z0-9._~+/=-]{12,}|sk-[a-z0-9_-]{16,}|gh[pousr]_[a-z0-9_]{16,}|AKIA[0-9A-Z]{16})/gi;
+const TELEMETRY_CHANNEL = "notrace.telemetry.extension";
+const SCHEMA_VERSION = 2;
+let currentMode = "full";
+function getInitialMode() {
+    const env = process.env.NOTRACE_CAPTURE?.toLowerCase();
+    if (env === "metadata" || env === "redacted")
+        return env;
+    return "full";
+}
+const SENSITIVE_KEY_RE = /(authorization|cookie|setcookie|password|passwd|pwd|secret|token|apikey|accesskey|accesskeyid|accessid|accesstoken|privatekey|session|credential|refreshtoken|idtoken)/i;
+function isSensitiveKey(key) {
+    const normalized = key.replace(/[^a-z0-9]/gi, "");
+    if (/^(inputtokens|outputtokens|totaltokens|prompttokens|completiontokens|reasoningtokens|cachedtokens|cachecreationinputtokens|cachereadinputtokens|cost|total|input|output|prompt|completion|reasoning|read|write)$/i.test(normalized))
+        return false;
+    return SENSITIVE_KEY_RE.test(normalized);
+}
+function sanitizeTraceValue(value) {
+    if (currentMode === "full")
+        return value;
+    if (value == null || typeof value !== "object") {
+        return typeof value === "string" ? value.replace(SENSITIVE_VALUE_RE, REDACTED).slice(0, 10000) : value;
+    }
+    if (Array.isArray(value))
+        return value.slice(0, 100).map(sanitizeTraceValue);
+    const out = {};
+    for (const [k, v] of Object.entries(value).slice(0, 100))
+        out[k] = isSensitiveKey(k) ? REDACTED : sanitizeTraceValue(v);
+    return out;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function normalizeUsage(raw) {
+    const usage = (raw && typeof raw === "object" ? raw : {});
+    return {
+        inputTokens: asNumber(usage.inputTokens ?? usage.input),
+        outputTokens: asNumber(usage.outputTokens ?? usage.output),
+        cacheReadTokens: asNumber(usage.cacheReadTokens ?? usage.cacheRead),
+        cacheWriteTokens: asNumber(usage.cacheWriteTokens ?? usage.cacheWrite),
+        totalTokens: asNumber(usage.totalTokens),
+        totalCostUsd: asNumber(usage.cost?.total),
+    };
+}
+function collectActivity(events, startedAt, endedAt) {
+    const activity = {
+        turnCount: 0,
+        llmCallCount: 0,
+        toolCallCount: 0,
+        toolErrorCount: 0,
+        durationMs: Math.max(0, endedAt - startedAt),
+        totals: {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+            totalTokens: 0,
+            totalCostUsd: 0,
+        },
+    };
+    for (const e of events) {
+        if (e.type === "turn_start")
+            activity.turnCount++;
+        if (e.type === "tool_start")
+            activity.toolCallCount++;
+        if (e.type === "tool_end" && e.isError)
+            activity.toolErrorCount++;
+        if (e.type === "llm_completion") {
+            activity.llmCallCount++;
+            const usage = normalizeUsage(e.usage);
+            activity.totals.inputTokens += usage.inputTokens;
+            activity.totals.outputTokens += usage.outputTokens;
+            activity.totals.cacheReadTokens += usage.cacheReadTokens;
+            activity.totals.cacheWriteTokens += usage.cacheWriteTokens;
+            activity.totals.totalTokens += usage.totalTokens;
+            activity.totals.totalCostUsd += usage.totalCostUsd;
+        }
+    }
+    return activity;
+}
+function buildConditions(events, telemetry) {
+    const models = new Set();
+    const providers = new Set();
+    for (const event of events) {
+        if (event.type !== "llm_completion")
+            continue;
+        if (typeof event.model === "string" && event.model)
+            models.add(event.model);
+        if (typeof event.provider === "string" && event.provider)
+            providers.add(event.provider);
+    }
+    const extensions = ["notrace", ...Object.keys(telemetry).sort()];
+    return {
+        harness: {
+            name: "pi",
+            adapter: "pi-session-hooks",
+            version: null,
+        },
+        models: [...models],
+        providers: [...providers],
+        extensions,
+    };
+}
+function toTaskInfo(context) {
+    if (!context)
+        return null;
+    return {
+        workflow: context.workflow,
+        id: context.taskId,
+        path: context.taskPath,
+        dir: context.taskDir,
+    };
+}
+function createIndexEntry(record, cwd, htmlPath, recordPath) {
+    return {
+        sessionId: record.traceId,
+        startedAt: record.session.startedAt,
+        endedAt: record.session.endedAt,
+        captureMode: record.captureMode,
+        task: record.task,
+        conditions: record.conditions,
+        activity: record.activity,
+        artifacts: {
+            html: path.relative(cwd, htmlPath),
+            record: path.relative(cwd, recordPath),
+        },
+    };
+}
+function normalizeTelemetryPayload(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const payload = raw;
+    if (typeof payload.extension !== "string" || !payload.extension.trim())
+        return null;
+    const status = payload.status === "absent" ||
+        payload.status === "loaded-disabled" ||
+        payload.status === "loaded-inactive" ||
+        payload.status === "active" ||
+        payload.status === "unknown"
+        ? payload.status
+        : "unknown";
+    return {
+        extension: payload.extension,
+        telemetry: {
+            loaded: payload.loaded !== false,
+            enabled: typeof payload.enabled === "boolean" ? payload.enabled : null,
+            active: typeof payload.active === "boolean" ? payload.active : null,
+            status,
+            summary: typeof payload.summary === "string" ? payload.summary : null,
+            details: payload.details && typeof payload.details === "object" ? payload.details : {},
+        },
+    };
+}
+export default function (pi) {
+    const events = [];
+    const startTime = Date.now();
+    let traceId = "";
+    let activeLlmPayload = null;
+    let shutdownReason = null;
+    const extensionTelemetry = new Map();
+    currentMode = getInitialMode();
+    if (typeof pi.events?.on === "function") {
+        pi.events.on(TELEMETRY_CHANNEL, (raw) => {
+            const normalized = normalizeTelemetryPayload(raw);
+            if (!normalized)
+                return;
+            extensionTelemetry.set(normalized.extension, normalized.telemetry);
+        });
+    }
+    pi.registerCommand("notrace", {
+        description: "Change notrace capture mode (full | redacted | metadata)",
+        handler: async (args, ctx) => {
+            const mode = args?.trim().toLowerCase();
+            if (mode === "full" || mode === "redacted" || mode === "metadata") {
+                currentMode = mode;
+                ctx.ui.notify(`notrace capture mode set to: ${currentMode}`, "info");
+            }
+            else {
+                ctx.ui.notify(`Current notrace mode: ${currentMode}. Usage: /notrace [full|redacted|metadata]`, "info");
+            }
+        }
+    });
+    pi.on("session_start", async (_e, ctx) => {
+        traceId = ctx.sessionManager.getSessionId() || `s-${Date.now()}`;
+        events.push({ type: "session_start", timestamp: Date.now() });
+    });
+    pi.on("turn_start", async () => events.push({ type: "turn_start", timestamp: Date.now() }));
+    pi.on("tool_execution_start", async (e) => {
+        events.push({ type: "tool_start", toolName: e.toolName, args: sanitizeTraceValue(e.args), timestamp: Date.now() });
+    });
+    pi.on("tool_execution_end", async (e) => {
+        events.push({ type: "tool_end", toolName: e.toolName, result: sanitizeTraceValue(e.result), isError: e.isError, timestamp: Date.now() });
+    });
+    pi.on("before_provider_request", async (e) => {
+        activeLlmPayload = sanitizeTraceValue(e.payload);
+    });
+    pi.on("message_end", async (e) => {
+        if (e.message.role === "assistant") {
+            events.push({
+                type: "llm_completion",
+                model: e.message.model,
+                provider: e.message.provider,
+                inputPayload: activeLlmPayload,
+                outputContent: sanitizeTraceValue(e.message.content),
+                usage: e.message.usage,
+                stopReason: typeof e.message.stopReason === "string" ? e.message.stopReason : undefined,
+                errorMessage: typeof e.message.errorMessage === "string" ? sanitizeTraceValue(e.message.errorMessage) : undefined,
+                timestamp: Date.now(),
+            });
+            activeLlmPayload = null;
+        }
+    });
+    pi.on("session_shutdown", async (e, ctx) => {
+        shutdownReason = typeof e?.reason === "string" ? e.reason : null;
+        const endedAt = Date.now();
+        const adapter = getActiveAdapter(ctx.cwd);
+        const context = adapter.getContext(ctx.cwd);
+        const notraceDir = path.resolve(ctx.cwd, ".notrace");
+        const finalTraceId = ctx.sessionManager?.getSessionId?.() || traceId;
+        const outputDir = path.join(notraceDir, "sessions", finalTraceId.replace(/[^a-z0-9]/gi, "-"));
+        const repositoryName = path.basename(ctx.cwd);
+        const recordPath = path.join(outputDir, "notrace.json");
+        let mergedEvents = events;
+        let originalStartedAt = startTime;
+        let originalTask = null;
+        if (existsSync(recordPath)) {
+            try {
+                const oldRecord = JSON.parse(readFileSync(recordPath, "utf-8"));
+                if (Array.isArray(oldRecord.events)) {
+                    mergedEvents = [...oldRecord.events, ...events];
+                }
+                if (oldRecord.session?.startedAt) {
+                    originalStartedAt = new Date(oldRecord.session.startedAt).getTime();
+                }
+                if (oldRecord.task) {
+                    originalTask = oldRecord.task;
+                }
+            }
+            catch (err) {
+                // ignore parse errors
+            }
+        }
+        const activity = collectActivity(mergedEvents, originalStartedAt, endedAt);
+        // Do not index purely empty ghost sessions
+        const isGhostSession = activity.llmCallCount === 0 && activity.toolCallCount === 0 && activity.totals.totalTokens === 0;
+        const telemetry = Object.fromEntries([...extensionTelemetry.entries()].sort(([a], [b]) => a.localeCompare(b)));
+        const record = {
+            kind: "notrace-run",
+            schemaVersion: SCHEMA_VERSION,
+            traceId: finalTraceId,
+            repository: {
+                name: repositoryName,
+                cwd: ctx.cwd,
+            },
+            session: {
+                id: finalTraceId,
+                startedAt: new Date(originalStartedAt).toISOString(),
+                endedAt: new Date(endedAt).toISOString(),
+                durationMs: activity.durationMs,
+                shutdownReason,
+            },
+            task: toTaskInfo(context) || originalTask,
+            captureMode: currentMode,
+            conditions: buildConditions(mergedEvents, telemetry),
+            activity,
+            telemetry: { extensions: telemetry },
+            events: mergedEvents,
+        };
+        const html = generateHtmlReport(record);
+        mkdirSync(outputDir, { recursive: true });
+        const htmlPath = path.join(outputDir, "notrace.html");
+        writeFileSync(htmlPath, html);
+        writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+        const indexPath = path.join(notraceDir, "index.json");
+        const existing = existsSync(indexPath) ? JSON.parse(readFileSync(indexPath, "utf-8")) : { repositoryName, sessions: [] };
+        let sessions = Array.isArray(existing.sessions) ? existing.sessions.filter((s) => s.sessionId !== finalTraceId) : [];
+        if (!isGhostSession) {
+            sessions.push(createIndexEntry(record, ctx.cwd, htmlPath, recordPath));
+        }
+        writeFileSync(indexPath, `${JSON.stringify({ repositoryName, sessions }, null, 2)}\n`);
+        writeFileSync(path.join(notraceDir, "index.html"), generateDashboardHtml(sessions, { repositoryName }));
+        if (context) {
+            adapter.attach(context, {
+                html: path.relative(ctx.cwd, htmlPath),
+                record: path.relative(ctx.cwd, recordPath)
+            });
+        }
+        console.log(`\n\x1b[1m\x1b[38;5;208m[notrace] Session Retrospective: file://${htmlPath}\x1b[0m\n`);
+    });
+}

package/dist/notrace/renderer.d.ts

@@ -0,0 +1,4 @@
+export declare function escapeHtml(v: unknown): string;
+export declare function safeJsonForScript(v: any): string;
+export declare function generateDashboardHtml(sessions: any[], options?: any): string;
+export declare function generateHtmlReport(data: any): string;