agentwrangler 0.1.0

package/dist/outcomes/sync.js

@@ -0,0 +1,276 @@
+/**
+ * src/outcomes/sync.ts — GitHub → work_items sync.
+ *
+ * Fetches PRs from GitHub and upserts into the work_items table.
+ * Watermark in user_config (key: "gh_watermark:<owner>/<repo>") prevents
+ * re-fetching already-processed PRs.
+ *
+ * Body and diff are parsed in-memory only — never stored (SEC-101).
+ * Skip workspaces without repo_owner/repo_name.
+ */
+import { DEFAULT_CONCURRENCY, mapWithConcurrency } from "./pool.js";
+/**
+ * Sync PRs for one workspace into work_items.
+ * Idempotent — ON CONFLICT DO UPDATE safe to call repeatedly.
+ * Skips workspace silently if client is disabled.
+ */
+export async function syncWorkItems(db, client, workspace) {
+    if (!client.enabled)
+        return;
+    const { workspace_id, repo_owner, repo_name } = workspace;
+    const watermarkKey = `gh_watermark:${repo_owner}/${repo_name}`;
+    // Read watermark
+    const wmRow = db.prepare("SELECT value FROM user_config WHERE key = ?").get(watermarkKey);
+    const since = wmRow?.value ?? undefined;
+    const listResult = await client.listPRs(repo_owner, repo_name, since);
+    if (!listResult.ok) {
+        console.warn(`syncWorkItems: listPRs failed — ${listResult.reason}`);
+        return;
+    }
+    const prs = listResult.data;
+    if (prs.length === 0)
+        return;
+    const upsert = db.prepare(`
+    INSERT INTO work_items
+      (work_item_id, workspace_id, number, state, final_commit,
+       checks_conclusion, opened_at, merged_at, closed_at, synced_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(work_item_id) DO UPDATE SET
+      state             = excluded.state,
+      final_commit      = excluded.final_commit,
+      checks_conclusion = COALESCE(excluded.checks_conclusion, work_items.checks_conclusion),
+      merged_at         = excluded.merged_at,
+      closed_at         = excluded.closed_at,
+      synced_at         = excluded.synced_at
+  `);
+    const ensureConfig = db.prepare(`
+    INSERT OR IGNORE INTO user_config (key, value, updated_at) VALUES (?, ?, ?)
+  `);
+    const updateConfig = db.prepare("UPDATE user_config SET value = ?, updated_at = ? WHERE key = ?");
+    const upsertBranchKey = db.prepare(`
+    INSERT INTO work_item_branch_keys
+      (work_item_id, head_ref_key, normalization_version, synced_at)
+    VALUES (?, ?, 'branch-v1', ?)
+    ON CONFLICT(work_item_id) DO UPDATE SET
+      head_ref_key          = excluded.head_ref_key,
+      normalization_version = excluded.normalization_version,
+      synced_at             = excluded.synced_at
+  `);
+    const deleteBranchKey = db.prepare("DELETE FROM work_item_branch_keys WHERE work_item_id = ?");
+    const now = new Date().toISOString();
+    let newestUpdated = since ?? "1970-01-01T00:00:00Z";
+    // Compute per-PR row fields synchronously, then fetch check conclusions with
+    // bounded concurrency (~0.77s per call; serially that was ~97s across a
+    // 126-PR page — pooled at DEFAULT_CONCURRENCY it drops proportionally).
+    const rows = prs.map((pr) => {
+        const workItemId = `gh:${repo_owner}/${repo_name}#${pr.number}`;
+        const state = pr.merged_at !== null ? "MERGED" : pr.state === "closed" ? "CLOSED" : "OPEN";
+        const finalCommit = pr.merge_commit_sha ?? pr.head.sha;
+        return { pr, workItemId, state, finalCommit };
+    });
+    const conclusions = await mapWithConcurrency(rows, DEFAULT_CONCURRENCY, (row) => client.getCheckConclusion(repo_owner, repo_name, row.pr.head.sha));
+    const writePR = db.transaction((row, checksConclusion, syncedAt) => {
+        upsert.run(row.workItemId, workspace_id, row.pr.number, row.state, row.finalCommit, checksConclusion, row.pr.created_at, row.pr.merged_at, row.pr.closed_at, syncedAt);
+        if (row.pr.head.refKey === null) {
+            deleteBranchKey.run(row.workItemId);
+        }
+        else {
+            upsertBranchKey.run(row.workItemId, row.pr.head.refKey, syncedAt);
+        }
+    });
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        // Get check conclusion for the HEAD SHA.
+        // If the call fails (rate-limit, truncation, transient error), pass null so the
+        // COALESCE in the upsert preserves any previously-correct value rather than
+        // overwriting it — preventing a false OBSERVED_SUCCESS from a transient failure.
+        const checkResult = conclusions[i];
+        const checksConclusion = checkResult?.ok === true ? checkResult.data : null;
+        // The work-item projection and privacy-safe branch key are one unit: a
+        // changed head SHA can never commit alongside a stale branch key.
+        writePR(row, checksConclusion, now);
+        // Track newest updated_at for watermark
+        const updatedAt = row.pr.merged_at ?? row.pr.closed_at ?? row.pr.created_at;
+        if (updatedAt > newestUpdated)
+            newestUpdated = updatedAt;
+    }
+    // Advance watermark
+    ensureConfig.run(watermarkKey, newestUpdated, now);
+    updateConfig.run(newestUpdated, now, watermarkKey);
+}
+const STRICT_UTC_RFC3339 = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,3}))?Z$/u;
+const EVIDENCE_SCAN_CHUNK = 256;
+function parseStrictUtcTimestamp(value, code) {
+    const match = STRICT_UTC_RFC3339.exec(value);
+    if (match === null)
+        throw new Error(code);
+    const milliseconds = (match[2] ?? "").padEnd(3, "0");
+    const canonical = `${match[1]}.${milliseconds}Z`;
+    const epoch = Date.parse(canonical);
+    if (!Number.isFinite(epoch) || new Date(epoch).toISOString() !== canonical)
+        throw new Error(code);
+    return epoch;
+}
+function assertEvidenceRepositories(db, evidence) {
+    if (evidence.repositories.length === 0 ||
+        evidence.asOf.length === 0 ||
+        evidence.syncedAt.length === 0 ||
+        !Number.isFinite(parseStrictUtcTimestamp(evidence.asOf, "branch_backfill_as_of_invalid")) ||
+        !Number.isFinite(parseStrictUtcTimestamp(evidence.syncedAt, "branch_backfill_synced_at_invalid"))) {
+        throw new Error("branch_backfill_evidence_options_invalid");
+    }
+    const seen = new Set();
+    const findWorkspace = db.prepare("SELECT repo_owner, repo_name FROM workspaces WHERE workspace_id = ?");
+    for (const repository of evidence.repositories) {
+        if (seen.has(repository.workspaceId))
+            throw new Error("branch_backfill_allowlist_duplicate");
+        seen.add(repository.workspaceId);
+        const row = findWorkspace.get(repository.workspaceId);
+        if (row === undefined ||
+            row.repo_owner !== repository.owner ||
+            row.repo_name !== repository.repo) {
+            throw new Error("branch_backfill_allowlist_mismatch");
+        }
+    }
+}
+/**
+ * Validation-only, bounded backfill for historical work items missed by the
+ * 100-row incremental listing. It is deliberately not wired into the daemon.
+ * Existing keys are never fetched or overwritten, and failed/ineligible rows
+ * remain missing so a later traversal from the start can retry them.
+ */
+export async function backfillMissingWorkItemBranchKeys(db, client, options = {}) {
+    const requestedLimit = options.limit ?? 100;
+    const limit = Math.max(1, Math.min(1000, Math.trunc(requestedLimit)));
+    const requestedConcurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+    const concurrency = Math.max(1, Math.min(32, Math.trunc(requestedConcurrency)));
+    const evidence = options.evidence;
+    if (evidence !== undefined)
+        assertEvidenceRepositories(db, evidence);
+    const cursor = evidence?.resumeFromStart === true ? "" : (options.cursor ?? "");
+    const allowlistClause = evidence === undefined
+        ? ""
+        : ` AND (${evidence.repositories
+            .map(() => "(wi.workspace_id = ? AND ws.repo_owner = ? AND ws.repo_name = ?)")
+            .join(" OR ")})`;
+    const queryArguments = [cursor];
+    if (evidence !== undefined) {
+        for (const repository of evidence.repositories) {
+            queryArguments.push(repository.workspaceId, repository.owner, repository.repo);
+        }
+    }
+    queryArguments.push(evidence === undefined ? limit + 1 : EVIDENCE_SCAN_CHUNK);
+    const queriedCandidates = db
+        .prepare(`SELECT wi.work_item_id, wi.workspace_id, ws.repo_owner, ws.repo_name, wi.number,
+              wi.synced_at
+         FROM work_items wi
+         JOIN workspaces ws ON ws.workspace_id = wi.workspace_id
+         LEFT JOIN work_item_branch_keys bk ON bk.work_item_id = wi.work_item_id
+        WHERE bk.work_item_id IS NULL
+          AND ws.repo_owner IS NOT NULL
+          AND ws.repo_name IS NOT NULL
+          AND wi.work_item_id =
+              'gh:' || ws.repo_owner || '/' || ws.repo_name || '#' || wi.number
+          AND wi.work_item_id > ?
+          ${allowlistClause}
+        ORDER BY wi.work_item_id
+        LIMIT ?`)
+        .all(...queryArguments);
+    const candidates = evidence === undefined
+        ? queriedCandidates
+        : queriedCandidates
+            .filter((row) => parseStrictUtcTimestamp(row.synced_at, "branch_backfill_work_item_timestamp_invalid") <= parseStrictUtcTimestamp(evidence.asOf, "branch_backfill_as_of_invalid"))
+            .slice(0, limit + 1);
+    const eligibleOverflow = candidates.length > limit;
+    const page = eligibleOverflow ? candidates.slice(0, limit) : candidates;
+    const results = await mapWithConcurrency(page, concurrency, async (row) => {
+        try {
+            const result = await client.getPRHeadKey(row.repo_owner, row.repo_name, row.number);
+            return result.ok
+                ? result
+                : { ok: false, failureReason: "GITHUB_READ_FAILED" };
+        }
+        catch {
+            return { ok: false, failureReason: "GITHUB_READ_THREW" };
+        }
+    });
+    const insertKey = db.prepare(`
+    INSERT OR IGNORE INTO work_item_branch_keys
+      (work_item_id, head_ref_key, normalization_version, synced_at)
+    VALUES (?, ?, 'branch-v1', ?)
+  `);
+    let keyed = 0;
+    let ineligible = 0;
+    let failed = 0;
+    const classifications = {
+        KEYED: 0,
+        INELIGIBLE: 0,
+        FETCH_FAILED: 0,
+    };
+    const failureReasonCounts = {
+        GITHUB_READ_FAILED: 0,
+        GITHUB_READ_THREW: 0,
+    };
+    const commitClassifications = db.transaction(() => {
+        for (let i = 0; i < page.length; i++) {
+            const result = results[i];
+            if (result?.ok !== true) {
+                failed += 1;
+                classifications.FETCH_FAILED += 1;
+                const reason = result?.failureReason ?? "GITHUB_READ_THREW";
+                failureReasonCounts[reason] = (failureReasonCounts[reason] ?? 0) + 1;
+                continue;
+            }
+            if (result.data === null) {
+                ineligible += 1;
+                classifications.INELIGIBLE += 1;
+                continue;
+            }
+            const info = insertKey.run(page[i]?.work_item_id, result.data, evidence?.syncedAt ?? new Date().toISOString());
+            if (info.changes === 1) {
+                keyed += 1;
+                classifications.KEYED += 1;
+            }
+        }
+    });
+    commitClassifications();
+    const scanMayContinue = evidence !== undefined && queriedCandidates.length === EVIDENCE_SCAN_CHUNK;
+    const checkpointCursor = eligibleOverflow
+        ? (page.at(-1)?.work_item_id ?? null)
+        : (queriedCandidates.at(-1)?.work_item_id ?? null);
+    const nextCursor = eligibleOverflow || scanMayContinue ? checkpointCursor : null;
+    if (evidence?.onPageCheckpoint !== undefined) {
+        await evidence.onPageCheckpoint({
+            afterWorkItemId: checkpointCursor,
+            scanned: queriedCandidates.length,
+            selected: page.length,
+            keyed,
+            ineligible,
+            failed,
+        });
+    }
+    return {
+        selected: page.length,
+        keyed,
+        ineligible,
+        failed,
+        missing: ineligible + failed,
+        nextCursor,
+        ...(evidence === undefined
+            ? {}
+            : { scanned: queriedCandidates.length, classifications, failureReasonCounts }),
+    };
+}
+/**
+ * Sync all mapped workspaces (those with repo_owner and repo_name set).
+ */
+export async function syncAllWorkspaces(db, client) {
+    if (!client.enabled)
+        return;
+    const workspaces = db
+        .prepare("SELECT workspace_id, repo_owner, repo_name FROM workspaces WHERE repo_owner IS NOT NULL AND repo_name IS NOT NULL")
+        .all();
+    for (const ws of workspaces) {
+        await syncWorkItems(db, client, ws);
+    }
+}

package/dist/query/api/agents-liveness.js

@@ -0,0 +1,182 @@
+/** Live Claude Code agent measurements and confirm-gated session termination. */
+import { spawn, spawnSync } from "node:child_process";
+import { capWeightExprSql, resolveCapReadCoeff } from "../cap-weighted.js";
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+const LIVENESS_UNAVAILABLE = "liveness unknown: Claude Code CLI not found or too old";
+const CACHE_MS = 30_000;
+let cached = null;
+function stringValue(value) {
+    return typeof value === "string" ? value : "";
+}
+function unavailable() {
+    const result = {
+        available: false,
+        reason: LIVENESS_UNAVAILABLE,
+        agents: [],
+    };
+    return buildResponse(result, { claim_kind: "OBS_PROXY", n: result.agents.length });
+}
+function runAgentsCommand() {
+    const childEnv = { ...process.env };
+    // biome-ignore lint/performance/noDelete: the child must not inherit Claude's nesting guard.
+    delete childEnv.CLAUDECODE;
+    for (const key of Object.keys(childEnv)) {
+        if (key.startsWith("CLAUDE_CODE_"))
+            delete childEnv[key];
+    }
+    let child;
+    try {
+        child = spawn("claude", ["agents", "--json"], {
+            env: childEnv,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return Promise.resolve(null);
+    }
+    const stdoutStream = child.stdout;
+    if (stdoutStream === null)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let stdout = "";
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            resolve(value);
+        };
+        const timeout = setTimeout(() => {
+            child.kill();
+            settle(null);
+        }, 5_000);
+        stdoutStream.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.once("error", () => settle(null));
+        child.once("close", (code) => settle(code === 0 ? stdout : null));
+    });
+}
+function isAlive(pid) {
+    process.kill(pid, 0);
+    return true;
+}
+function isProcessNotFound(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ESRCH";
+}
+function pause(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+/** End an agent process only after an explicit user confirmation. */
+export function endSession(pid, confirm) {
+    if (confirm !== true)
+        return { ok: false, reason: "confirmation required", status: 400 };
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+        return { ok: false, reason: "invalid pid", status: 400 };
+    }
+    try {
+        isAlive(pid);
+    }
+    catch (error) {
+        if (isProcessNotFound(error))
+            return { ok: false, reason: "process not found", status: 404 };
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : "unable to probe process",
+            status: 500,
+        };
+    }
+    try {
+        if (process.platform === "win32") {
+            const result = spawnSync("taskkill", ["/pid", String(pid), "/t", "/f"], {
+                stdio: "ignore",
+            });
+            if (result.error)
+                throw result.error;
+            if (result.status !== 0)
+                throw new Error("taskkill failed");
+        }
+        else {
+            process.kill(pid, "SIGTERM");
+            pause(100);
+            try {
+                isAlive(pid);
+            }
+            catch (error) {
+                if (isProcessNotFound(error))
+                    return { ok: true, ended: pid, status: 200 };
+                throw error;
+            }
+            process.kill(pid, "SIGKILL");
+        }
+        return { ok: true, ended: pid, status: 200 };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : "failed to end process",
+            status: 500,
+        };
+    }
+}
+/** Return active Claude Code agents enriched with local, read-only usage measurements. */
+export async function getAgentsLiveness() {
+    if (cached !== null && Date.now() - cached.at < CACHE_MS)
+        return cached.result;
+    const stdout = await runAgentsCommand();
+    if (stdout === null)
+        return unavailable();
+    let rawAgents;
+    try {
+        rawAgents = JSON.parse(stdout);
+    }
+    catch {
+        return unavailable();
+    }
+    if (!Array.isArray(rawAgents))
+        return unavailable();
+    try {
+        const db = getQueryDb();
+        const expr = capWeightExprSql("turns", resolveCapReadCoeff(db));
+        const usage = db.prepare(`SELECT MAX(workspace_id) AS workspace_id,
+              MAX(ts) AS last_activity_ts,
+              COALESCE(SUM(${expr}), 0) AS cap_weighted_raw
+         FROM turns
+        WHERE session_id = ?`);
+        const now = Date.now();
+        const agents = [];
+        for (const rawAgent of rawAgents) {
+            if (typeof rawAgent !== "object" || rawAgent === null)
+                continue;
+            const agent = rawAgent;
+            const sessionId = stringValue(agent.sessionId);
+            if (sessionId.length === 0)
+                continue;
+            const usageRow = usage.get(sessionId);
+            const lastActivityMs = Date.parse(usageRow.last_activity_ts ?? "");
+            agents.push({
+                session_id: sessionId,
+                pid: typeof agent.pid === "number" && Number.isInteger(agent.pid) ? agent.pid : null,
+                workspace_id: usageRow.workspace_id,
+                cwd: stringValue(agent.cwd),
+                kind: stringValue(agent.kind),
+                status: stringValue(agent.status) || stringValue(agent.state),
+                name: stringValue(agent.name),
+                started_at: stringValue(agent.startedAt),
+                idle_seconds: Number.isFinite(lastActivityMs)
+                    ? Math.floor(Math.max(0, now - lastActivityMs) / 1_000)
+                    : 0,
+                cap_weighted_context_held: Math.round(usageRow.cap_weighted_raw ?? 0),
+            });
+        }
+        const result = { available: true, reason: null, agents };
+        const response = buildResponse(result, { claim_kind: "OBS_PROXY", n: result.agents.length });
+        cached = { at: now, result: response };
+        return response;
+    }
+    catch {
+        return unavailable();
+    }
+}

package/dist/query/api/burn-status.js

@@ -0,0 +1,50 @@
+/** OAuth-backed Claude Code burn status for the local dashboard. */
+import { fetchOAuthUsage } from "../../oauth/usage.js";
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+/**
+ * Persist the latest per-model utilization snapshot to user_config so the D4
+ * detector can read it synchronously (async→sync bridge, R12 calibration
+ * pattern). The dashboard's recurring GET /api/burn-status poll IS the recurring
+ * write. Never throws — a persist failure must not fail the burn-status response,
+ * and we only overwrite when live per-model data is present (absence leaves the
+ * last-known snapshot in place; D4's 24h staleness bound handles the rest).
+ */
+function persistPerModelSnapshot(five_hour, seven_day, per_model) {
+    try {
+        const snapshot = JSON.stringify({
+            captured_at: new Date().toISOString(),
+            seven_day_util: seven_day.utilization,
+            five_hour_util: five_hour.utilization,
+            per_model,
+        });
+        getQueryDb()
+            .prepare(`INSERT INTO user_config (key, value, updated_at) VALUES ('per_model_snapshot', ?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`)
+            .run(snapshot, new Date().toISOString());
+    }
+    catch {
+        // Best-effort: a persist failure never fails the response.
+    }
+}
+export async function getBurnStatus(reader = fetchOAuthUsage) {
+    try {
+        const result = await reader();
+        if (!result.ok) {
+            return buildResponse({ available: false, reason: result.reason }, { claim_kind: "OBS_PROXY", n: 0 });
+        }
+        const { five_hour, seven_day, per_model } = result.data;
+        if (per_model !== undefined && per_model.length > 0) {
+            persistPerModelSnapshot(five_hour, seven_day, per_model);
+        }
+        return buildResponse({
+            available: true,
+            five_hour,
+            seven_day,
+            ...(per_model !== undefined && per_model.length > 0 ? { per_model } : {}),
+        }, { claim_kind: "OBS_PROXY", n: 1 });
+    }
+    catch {
+        return buildResponse({ available: false, reason: "OAuth usage is unavailable." }, { claim_kind: "OBS_PROXY", n: 0 });
+    }
+}

package/dist/query/api/context-budget.js

@@ -0,0 +1,114 @@
+/** Fail-open context-budget measurement for the local hook. */
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+import { DEFAULT_HOOK_CONFIG, readHookConfig } from "./hook-config.js";
+const STANDARD_WINDOW = 200_000;
+const LARGE_WINDOW = 1_000_000;
+/**
+ * The transcript records only a base model id (e.g. `claude-opus-4-8`), never the
+ * context-window variant, so the true window is unknowable from the data alone. We take
+ * the user-declared window and floor it to a tier at least as large as the biggest context
+ * the session has actually reached — a 200k-window model can never exceed 200k tokens, so a
+ * session that has is provably a larger-window variant. This prevents false "near the limit"
+ * warnings when the declared window is left at the standard default on a large-window model.
+ */
+function effectiveWindow(declaredWindow, maxObserved) {
+    let floor;
+    if (maxObserved > LARGE_WINDOW)
+        floor = maxObserved;
+    else if (maxObserved > STANDARD_WINDOW)
+        floor = LARGE_WINDOW;
+    else
+        floor = STANDARD_WINDOW;
+    return Math.max(declaredWindow, floor);
+}
+function okBudget(sessionId, reason, config) {
+    const window = config.context_window;
+    return {
+        stage: "ok",
+        context_tokens: 0,
+        soft_at: Math.round(config.soft_pct * window),
+        hard_at: Math.round(config.hard_pct * window),
+        window,
+        usage_pct: 0,
+        model: null,
+        recommended_action: "compact",
+        reason,
+        ts: null,
+        stale_s: null,
+        session_id: sessionId,
+    };
+}
+function response(data) {
+    return buildResponse(data, {
+        claim_kind: "OBS_PROXY",
+        n: data.ts === null ? 0 : 1,
+        drilldown_ids: { session_id: data.session_id },
+    });
+}
+/**
+ * Return a strictly fail-open budget result. This endpoint exposes only session
+ * identifiers and measured numbers; it never reads or returns transcript text.
+ */
+export function getContextBudget(sessionId) {
+    try {
+        const db = getQueryDb();
+        const config = readHookConfig(db);
+        const latest = db
+            .prepare(`SELECT ts, model, context_tokens
+           FROM turns
+          WHERE session_id = ?
+          ORDER BY ts DESC, rowid DESC
+          LIMIT 1`)
+            .get(sessionId);
+        if (latest === undefined) {
+            const session = db
+                .prepare("SELECT 1 AS present FROM sessions WHERE session_id = ? LIMIT 1")
+                .get(sessionId);
+            return response(okBudget(sessionId, session === undefined ? "unknown_session" : "no_turns", config));
+        }
+        const timestamp = Date.parse(latest.ts);
+        if (!Number.isFinite(timestamp)) {
+            return response(okBudget(sessionId, "invalid_timestamp", config));
+        }
+        const staleSeconds = Math.max(0, (Date.now() - timestamp) / 1_000);
+        const maxRow = db
+            .prepare(`SELECT COALESCE(MAX(context_tokens), 0) AS max_ctx
+           FROM turns
+          WHERE session_id = ?`)
+            .get(sessionId);
+        const maxObserved = Math.max(0, maxRow.max_ctx ?? 0);
+        const window = effectiveWindow(config.context_window, maxObserved);
+        const softAt = Math.round(config.soft_pct * window);
+        const hardAt = Math.round(config.hard_pct * window);
+        if (staleSeconds > config.stale_s) {
+            const stale = okBudget(sessionId, "stale", config);
+            stale.soft_at = softAt;
+            stale.hard_at = hardAt;
+            stale.window = window;
+            stale.ts = latest.ts;
+            stale.model = latest.model;
+            stale.stale_s = staleSeconds;
+            return response(stale);
+        }
+        const contextTokens = Math.max(0, latest.context_tokens ?? 0);
+        const stage = contextTokens >= hardAt ? "hard" : contextTokens >= softAt ? "soft" : "ok";
+        return response({
+            stage,
+            context_tokens: contextTokens,
+            soft_at: softAt,
+            hard_at: hardAt,
+            window,
+            usage_pct: contextTokens / window,
+            model: latest.model,
+            recommended_action: stage === "hard" ? "clear" : "compact",
+            reason: stage,
+            ts: latest.ts,
+            stale_s: staleSeconds,
+            session_id: sessionId,
+        });
+    }
+    catch {
+        return response(okBudget(sessionId, "unavailable", DEFAULT_HOOK_CONFIG));
+    }
+}

package/dist/query/api/context-composition.js

@@ -0,0 +1,67 @@
+/**
+ * Workspace context composition. v1 intentionally attributes only the
+ * always-loaded local files we can measure; tool output stays in the residual.
+ */
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Compare current CLAUDE.md/MEMORY inventory with the inclusive provisional
+ * seven-day context average. This deliberately never reads tool_result_bytes:
+ * it is byte-sized and v1 leaves tool output lumped in the residual.
+ */
+export function getContextComposition(workspaceId) {
+    const db = getQueryDb();
+    const to = new Date();
+    const from = new Date(to.getTime() - 7 * DAY_MS);
+    const fromIso = from.toISOString();
+    const toIso = to.toISOString();
+    const inventory = db
+        .prepare(`SELECT COUNT(*) AS inventory_rows, COALESCE(SUM(tokens), 0) AS always_loaded
+         FROM context_inventory
+        WHERE workspace_id IN (?, '__global__')
+          AND component IN ('CLAUDE_MD', 'MEMORY')`)
+        .get(workspaceId);
+    const observed = db
+        .prepare(`SELECT COUNT(*) AS observed_turns, AVG(context_tokens) AS observed_context_tokens
+         FROM turns
+        WHERE workspace_id = ? AND ts >= ? AND ts < ?`)
+        .get(workspaceId, fromIso, toIso);
+    const alwaysLoaded = Math.max(inventory.always_loaded, 0);
+    const observedContext = observed.observed_context_tokens;
+    const residual = observedContext === null ? 0 : Math.max(observedContext - alwaysLoaded, 0);
+    const total = observedContext === null ? 0 : alwaysLoaded + residual;
+    const share = (tokens) => (total > 0 ? tokens / total : null);
+    const rows = [
+        {
+            key: "always_loaded",
+            label: "always loaded",
+            tokens: alwaysLoaded,
+            share: share(alwaysLoaded),
+        },
+        {
+            key: "session_residual",
+            label: "session history + tool outputs (not itemized in v1)",
+            tokens: residual,
+            share: share(residual),
+        },
+    ];
+    return buildResponse({
+        workspace_id: workspaceId,
+        observed_context_tokens: observedContext,
+        observed_turns: observed.observed_turns,
+        inventory_rows: inventory.inventory_rows,
+        rows,
+    }, {
+        claim_kind: "OBS_PROXY",
+        n: observed.observed_turns,
+        window: { from: fromIso, to: toIso, preset: "7d" },
+        qualification: {
+            provisional_excluded: false,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "Provisional turns are included. v1 uses the current estimated CLAUDE.md and MEMORY inventory (±5–10% tokenizer error), excludes the system prompt and dynamic MCP schemas, and does not itemize the residual.",
+        },
+        drilldown_ids: { workspace_id: workspaceId },
+    });
+}