@isaacriehm/cairn-core 0.1.10 → 0.3.0

package/dist/session-start/templates.js

@@ -1,38 +1,48 @@
 /**
- * Static text fragments for the SessionStart payload.
+ * Static text fragments for the SessionStart payload. Kept compact —
+ * every static byte here ships in `additionalContext` on every session
+ * open, so verbosity scales linearly with operator session count.
+ *
+ * The agent's MCP client already receives full tool descriptions from
+ * the server's `registerTool` calls; SessionStart does NOT need to
+ * duplicate them. Bare `§DEC-NNNN` and `§INV-NNNN` citations resolve
+ * via the PostToolUse(Read) enricher hook.
  */
-export const TWO_ZONE_REMINDER_BASE = `## Two-zone reminder
-
-Default reads/grep/glob hit the **canonical zone** only:
-- AGENTS.md, CLAUDE.md, .claude/{rules,agents,skills}, docs/**,
-  .cairn/config/**, .cairn/ground/** (excluding _inbox/),
-  .cairn/tasks/active/**
-
-Historical content lives under .archive/, .cairn/runs/terminal/,
-.cairn/tasks/{done,archived}/, .cairn/ground/decisions/_inbox/. The
-cairn walkers and search tooling already exclude these paths — you do
-not need to filter manually. If you genuinely need to consult historical
-context, call \`mcp__cairn__cairn_query_history(scope, question)\`. It
-returns LLM-summarized claims with supersedes-pointers; raw archive
-content never enters your context.`;
-export const TOOL_QUICK_REFERENCE = `## Cairn MCP tools (quick reference)
-
-Read:
-  cairn_decision_get(id)                  — full ADR + assertions
-  cairn_decisions_in_scope(path_globs[])  — decisions overlapping a path
-  cairn_invariant_get(id)                 — §V invariant body + sensor
-  cairn_canonical_for_topic(topic)        — authoritative path + verified-at
-  cairn_get_full(id, kind)                — fetch any artifact by id
-  cairn_search(query, scope[]?)           — substring index over ground+docs
-  cairn_query_history(scope, question)    — Tier-1 summary of .archive/
-
-Write:
-  cairn_record_decision(...)              — drop draft to _inbox/ for operator confirm
-  cairn_archive(path, reason)             — move canonical → .archive/
-`;
-export const SESSION_START_HEADER = `# Cairn state context
-
-This Claude Code session is running inside a cairn-adopted project. The
-cairn state layer has prepared the following grounding context for you.
-Treat each section as authoritative for the duration of this session.`;
+export const TWO_ZONE_REMINDER_BASE = "## Two-zone reminder\n\n" +
+    "Reads/grep/glob default to the canonical zone (AGENTS.md, CLAUDE.md, " +
+    "docs/**, .cairn/ground/**, .cairn/tasks/active/**). Historical content " +
+    "(.archive/, .cairn/tasks/done/) is excluded by cairn's walkers — call " +
+    "`cairn_query_history(scope, question)` when you need a summarized read.";
+export const SESSION_START_HEADER = "# Cairn ground state — authoritative for this session";
+/**
+ * The code-change contract — system-level rule injected on every
+ * SessionStart so it sits above any skill body in the agent's context
+ * window. This is the operator-facing equivalent of the cairn-direction
+ * skill's "Hard contract" section, restated as a plain instruction
+ * Claude reads BEFORE the user prompt. Bypass detection in
+ * write-guardian remains the deterministic enforcement; this section
+ * is the up-front guidance.
+ */
+export const CODE_CHANGE_CONTRACT = "## Cairn — code-change contract (BLOCKING)\n\n" +
+    "Source mutations (`Edit`/`Write` on tracked files) require a tightened " +
+    "spec first. Bypass → `PostToolUse` hook returns `decision: \"block\"`.\n\n" +
+    "Workflow on any code-change prompt:\n\n" +
+    "1. `ToolSearch(select:mcp__plugin_cairn_cairn__cairn_task_create," +
+    "mcp__plugin_cairn_cairn__cairn_decisions_in_scope," +
+    "mcp__plugin_cairn_cairn__cairn_invariants_in_scope,AskUserQuestion)` — " +
+    "load deferred schemas. Required first call; without it `AskUserQuestion` " +
+    "is unavailable and clarifications fall back to inline prose.\n" +
+    "2. `cairn_decisions_in_scope({path_globs})` + `cairn_invariants_in_scope({path_globs})`.\n" +
+    "3. Forks unresolved → `AskUserQuestion` (≤3 options/round, A/B/C, cite " +
+    "DEC/§INV per option). Loop until deterministic.\n" +
+    "4. `cairn_task_create({slug, title, goal, target_path_globs, " +
+    "in_scope_decisions, in_scope_invariants, constraints, out_of_scope, " +
+    "acceptance, module})` — server allocates `task_id` + atomically writes " +
+    "`spec.tightened.md` + `status.yaml`. Format-locked. **`title`** ≤50 " +
+    "chars renders in the statusline + lens (e.g. \"Fix token expiry\"). " +
+    "**`goal`** is the full 1–2 sentence description for the spec body.\n" +
+    "5. Edit/Write. Hook passes (active tightened task on disk).\n\n" +
+    "`/cairn-direction` is the long-form variant (multi-chunk dispatch, " +
+    "rich tightening). Above 5 steps = entire flow for straight bug fixes. " +
+    "NEVER skip Step 1 or Step 4.";
 //# sourceMappingURL=templates.js.map

package/dist/session-start/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/session-start/templates.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;mCAaH,CAAC;AAEpC,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;CAcnC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;sEAIkC,CAAC"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/session-start/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GACjC,0BAA0B;IAC1B,uEAAuE;IACvE,yEAAyE;IACzE,wEAAwE;IACxE,yEAAyE,CAAC;AAE5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,uDAAuD,CAAC;AAE5F;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,gDAAgD;IAChD,yEAAyE;IACzE,4EAA4E;IAC5E,yCAAyC;IACzC,mEAAmE;IACnE,oDAAoD;IACpD,yEAAyE;IACzE,2EAA2E;IAC3E,gEAAgE;IAChE,4FAA4F;IAC5F,yEAAyE;IACzE,mDAAmD;IACnD,+DAA+D;IAC/D,sEAAsE;IACtE,yEAAyE;IACzE,sEAAsE;IACtE,sEAAsE;IACtE,sEAAsE;IACtE,iEAAiE;IACjE,qEAAqE;IACrE,wEAAwE;IACxE,8BAA8B,CAAC"}

package/dist/status-line/format.d.ts

@@ -1,14 +1,25 @@
 import type { StatusJson } from "./index.js";
 /**
- * Render a StatusJson as the single-line string Claude Code's status_line hook
- * displays. Pure function; no I/O.
+ * Render a single-line status string for Claude Code's status_line hook.
  *
- * Field priority for the "state" slot (single field):
- *   daemon down  >  attention > 0  >  gc running  >  task_state
+ * Layout: `⬡ cairn  [signal]  [ctx-meter]`
  *
- * Health icon:
- *   daemon down  → ○
- *   attention    → ⚑
- *   else         → ●
+ * Signal priority (first match wins, blank when nothing applies):
+ *   bypass_count > 0     → `⚠ N unattested`
+ *   attention_count > 0  → `⚑ N draft[s]`
+ *   gc_running           → `◐ gc`
+ *   task_state != idle   → `${task_id} ${task_module}` (or fallbacks)
+ *
+ * Ctx meter is omitted when no payload is supplied. Color thresholds are
+ * keyed on absolute used tokens (not percentage) so a 1M-window Opus
+ * session and a 200k-window Sonnet session signal danger at comparable
+ * absolute exhaustion points.
  */
-export declare function formatStatus(s: StatusJson): string;
+export interface CtxMeterInput {
+    /** raw used % matches Claude Code's /context display (no buffer normalization). */
+    usedPct: number;
+    /** absolute used tokens — keys the color threshold. */
+    usedTokens: number;
+}
+export declare function renderCtxMeter(ctx: CtxMeterInput): string;
+export declare function formatStatus(s: StatusJson, ctx?: CtxMeterInput): string;

package/dist/status-line/format.js

@@ -1,40 +1,50 @@
-/**
- * Render a StatusJson as the single-line string Claude Code's status_line hook
- * displays. Pure function; no I/O.
- *
- * Field priority for the "state" slot (single field):
- *   daemon down  >  attention > 0  >  gc running  >  task_state
- *
- * Health icon:
- *   daemon down  → ○
- *   attention    → ⚑
- *   else         → ●
- */
-export function formatStatus(s) {
-    const parts = ["⬡ cairn"];
-    parts.push(`ctx:${s.ctx_tokens_used}/${s.ctx_tokens_budget}`);
-    parts.push(`decisions:${s.decisions_in_scope}`);
-    parts.push(`inv:${s.invariants_in_scope}`);
-    let stateField;
-    let icon;
-    if (!s.daemon_alive) {
-        stateField = "daemon:down";
-        icon = "○";
-    }
-    else if (s.attention_count > 0) {
-        stateField = `attention:${s.attention_count}`;
-        icon = "⚑";
-    }
-    else if (s.gc_running) {
-        stateField = "gc:active";
-        icon = "●";
+const ANSI_RESET = "\x1b[0m";
+const ANSI_GREEN = "\x1b[32m";
+const ANSI_YELLOW = "\x1b[33m";
+const ANSI_ORANGE = "\x1b[38;5;208m";
+const ANSI_RED = "\x1b[31m";
+function ctxColor(usedTokens) {
+    if (usedTokens < 100_000)
+        return ANSI_GREEN;
+    if (usedTokens < 300_000)
+        return ANSI_YELLOW;
+    if (usedTokens < 600_000)
+        return ANSI_ORANGE;
+    return ANSI_RED;
+}
+export function renderCtxMeter(ctx) {
+    const pct = Math.max(0, Math.min(100, Math.round(ctx.usedPct)));
+    const filled = Math.floor(pct / 10);
+    const bar = "█".repeat(filled) + "░".repeat(10 - filled);
+    return `${ctxColor(ctx.usedTokens)}${bar} ${pct}%${ANSI_RESET}`;
+}
+function renderSignal(s) {
+    if (s.bypass_count > 0)
+        return `⚠ ${s.bypass_count} unattested`;
+    if (s.attention_count > 0) {
+        const noun = s.attention_count === 1 ? "draft" : "drafts";
+        return `⚑ ${s.attention_count} ${noun}`;
     }
-    else {
-        stateField = `task:${s.task_state}`;
-        icon = "●";
+    if (s.gc_running)
+        return "◐ gc";
+    if (s.task_state !== "idle") {
+        if (s.task_id && s.task_module)
+            return `${s.task_id} ${s.task_module}`;
+        if (s.task_id)
+            return s.task_id;
+        if (s.task_module)
+            return s.task_module;
+        return `task: ${s.task_state}`;
     }
-    parts.push(stateField);
-    parts.push(icon);
+    return null;
+}
+export function formatStatus(s, ctx) {
+    const parts = ["⬡ cairn"];
+    const signal = renderSignal(s);
+    if (signal)
+        parts.push(signal);
+    if (ctx)
+        parts.push(renderCtxMeter(ctx));
     return parts.join("  ");
 }
 //# sourceMappingURL=format.js.map

package/dist/status-line/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/status-line/format.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,CAAa;IACxC,MAAM,KAAK,GAAa,CAAC,SAAS,CAAC,CAAC;IAEpC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAC9D,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAChD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAE3C,IAAI,UAAkB,CAAC;IACvB,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC;QACpB,UAAU,GAAG,aAAa,CAAC;QAC3B,IAAI,GAAG,GAAG,CAAC;IACb,CAAC;SAAM,IAAI,CAAC,CAAC,eAAe,GAAG,CAAC,EAAE,CAAC;QACjC,UAAU,GAAG,aAAa,CAAC,CAAC,eAAe,EAAE,CAAC;QAC9C,IAAI,GAAG,GAAG,CAAC;IACb,CAAC;SAAM,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;QACxB,UAAU,GAAG,WAAW,CAAC;QACzB,IAAI,GAAG,GAAG,CAAC;IACb,CAAC;SAAM,CAAC;QACN,UAAU,GAAG,QAAQ,CAAC,CAAC,UAAU,EAAE,CAAC;QACpC,IAAI,GAAG,GAAG,CAAC;IACb,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/status-line/format.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,GAAG,SAAS,CAAC;AAC7B,MAAM,UAAU,GAAG,UAAU,CAAC;AAC9B,MAAM,WAAW,GAAG,UAAU,CAAC;AAC/B,MAAM,WAAW,GAAG,gBAAgB,CAAC;AACrC,MAAM,QAAQ,GAAG,UAAU,CAAC;AAE5B,SAAS,QAAQ,CAAC,UAAkB;IAClC,IAAI,UAAU,GAAG,OAAO;QAAE,OAAO,UAAU,CAAC;IAC5C,IAAI,UAAU,GAAG,OAAO;QAAE,OAAO,WAAW,CAAC;IAC7C,IAAI,UAAU,GAAG,OAAO;QAAE,OAAO,WAAW,CAAC;IAC7C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAkB;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IACpC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;IACzD,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,GAAG,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,YAAY,CAAC,CAAa;IACjC,IAAI,CAAC,CAAC,YAAY,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,YAAY,aAAa,CAAC;IAChE,IAAI,CAAC,CAAC,eAAe,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,CAAC,CAAC,eAAe,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC1D,OAAO,KAAK,CAAC,CAAC,eAAe,IAAI,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,MAAM,CAAC;IAChC,IAAI,CAAC,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;QAC5B,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,WAAW;YAAE,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QACvE,IAAI,CAAC,CAAC,OAAO;YAAE,OAAO,CAAC,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,CAAC,WAAW;YAAE,OAAO,CAAC,CAAC,WAAW,CAAC;QACxC,OAAO,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC;IACjC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,CAAa,EAAE,GAAmB;IAC7D,MAAM,KAAK,GAAa,CAAC,SAAS,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/B,IAAI,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/status-line/index.d.ts

@@ -12,18 +12,17 @@ export type TaskState = "idle" | "running" | "queued" | "tightening" | "sensing"
 export interface StatusJson {
     /** ISO timestamp of last write. */
     updated_at: string;
-    daemon_alive: boolean;
-    ctx_tokens_used: number;
-    ctx_tokens_budget: number;
     decisions_in_scope: number;
     invariants_in_scope: number;
     task_state: TaskState;
+    task_id: string | null;
     task_module: string | null;
     gc_running: boolean;
     attention_count: number;
+    bypass_count: number;
     last_run_result: "succeeded" | "failed" | null;
     last_run_at: string | null;
 }
 export { defaultStatusJson, statusJsonPath, writeStatusJson, } from "./writer.js";
 export { readStatusForCLI } from "./reader.js";
-export { formatStatus } from "./format.js";
+export { formatStatus, renderCtxMeter, type CtxMeterInput } from "./format.js";

package/dist/status-line/index.js

@@ -10,5 +10,5 @@
  */
 export { defaultStatusJson, statusJsonPath, writeStatusJson, } from "./writer.js";
 export { readStatusForCLI } from "./reader.js";
-export { formatStatus } from "./format.js";
+export { formatStatus, renderCtxMeter } from "./format.js";
 //# sourceMappingURL=index.js.map

package/dist/status-line/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/status-line/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA2BH,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/status-line/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0BH,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAsB,MAAM,aAAa,CAAC"}

package/dist/status-line/reader.d.ts

@@ -1,13 +1,16 @@
+import { type CtxMeterInput } from "./format.js";
 /**
  * Render the current status-line string for a session inside the
  * adopted repo at `repoRoot`. `sessionId` is the Claude Code session id
- * (passed via the status-line hook's stdin payload).
+ * (passed via the status-line hook's stdin payload). `ctx` is the
+ * decoded `context_window` block from the same payload.
  *
- * Returns the placeholder `⬡ cairn  daemon:down  ○` when:
- *   - `sessionId` is null/empty (status-line invoked outside a session)
- *   - the per-session status.json is missing
- *   - the file is unreadable, malformed JSON, or fails shape validation
+ * Falls back to ground-state summary when:
+ *   - `sessionId` is null/empty
+ *   - the per-session status.json is missing, unreadable, or malformed
+ *
+ * Returns empty string when `.cairn/` doesn't exist (cairn not adopted).
  *
  * Hot path — invoked on every Claude Code prompt. Keep this cheap.
  */
-export declare function readStatusForCLI(repoRoot: string, sessionId: string | null): string;
+export declare function readStatusForCLI(repoRoot: string, sessionId: string | null, ctx?: CtxMeterInput): string;

package/dist/status-line/reader.js

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
-import { formatStatus } from "./format.js";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { formatStatus, renderCtxMeter } from "./format.js";
 import { statusJsonPath } from "./writer.js";
-const PLACEHOLDER = "⬡ cairn  daemon:down  ○";
 const TASK_STATES = [
     "idle",
     "running",
@@ -25,52 +25,84 @@ function isStatusJson(x) {
         return false;
     const o = x;
     return (typeof o["updated_at"] === "string" &&
-        typeof o["daemon_alive"] === "boolean" &&
-        typeof o["ctx_tokens_used"] === "number" &&
-        typeof o["ctx_tokens_budget"] === "number" &&
         typeof o["decisions_in_scope"] === "number" &&
         typeof o["invariants_in_scope"] === "number" &&
         isTaskState(o["task_state"]) &&
+        isStringOrNull(o["task_id"]) &&
         isStringOrNull(o["task_module"]) &&
         typeof o["gc_running"] === "boolean" &&
         typeof o["attention_count"] === "number" &&
+        typeof o["bypass_count"] === "number" &&
         isLastRunResult(o["last_run_result"]) &&
         isStringOrNull(o["last_run_at"]));
 }
+/**
+ * Ground-state fallback when no per-session status.json is available.
+ * Counts pending drafts from `_inbox/`; renders `⬡ cairn  ⚑ N drafts` or
+ * just `⬡ cairn`. Returns empty string when `.cairn/` is absent.
+ *
+ * Ctx meter is appended when supplied — operator-side dropdown stays
+ * informative even when the session hook hasn't written status yet.
+ */
+function groundStateFallback(repoRoot, ctx) {
+    const cairnDir = join(repoRoot, ".cairn");
+    if (!existsSync(cairnDir))
+        return "";
+    let drafts = 0;
+    const inboxDir = join(cairnDir, "ground", "decisions", "_inbox");
+    if (existsSync(inboxDir)) {
+        try {
+            drafts = readdirSync(inboxDir, { encoding: "utf8" }).filter((f) => f.endsWith(".draft.md")).length;
+        }
+        catch {
+            drafts = 0;
+        }
+    }
+    const parts = ["⬡ cairn"];
+    if (drafts > 0) {
+        const noun = drafts === 1 ? "draft" : "drafts";
+        parts.push(`⚑ ${drafts} ${noun}`);
+    }
+    if (ctx)
+        parts.push(renderCtxMeter(ctx));
+    return parts.join("  ");
+}
 /**
  * Render the current status-line string for a session inside the
  * adopted repo at `repoRoot`. `sessionId` is the Claude Code session id
- * (passed via the status-line hook's stdin payload).
+ * (passed via the status-line hook's stdin payload). `ctx` is the
+ * decoded `context_window` block from the same payload.
+ *
+ * Falls back to ground-state summary when:
+ *   - `sessionId` is null/empty
+ *   - the per-session status.json is missing, unreadable, or malformed
  *
- * Returns the placeholder `⬡ cairn  daemon:down  ○` when:
- *   - `sessionId` is null/empty (status-line invoked outside a session)
- *   - the per-session status.json is missing
- *   - the file is unreadable, malformed JSON, or fails shape validation
+ * Returns empty string when `.cairn/` doesn't exist (cairn not adopted).
  *
  * Hot path — invoked on every Claude Code prompt. Keep this cheap.
  */
-export function readStatusForCLI(repoRoot, sessionId) {
+export function readStatusForCLI(repoRoot, sessionId, ctx) {
     if (sessionId === null || sessionId.length === 0)
-        return PLACEHOLDER;
+        return groundStateFallback(repoRoot, ctx);
     const filePath = statusJsonPath(repoRoot, sessionId);
     if (!existsSync(filePath))
-        return PLACEHOLDER;
+        return groundStateFallback(repoRoot, ctx);
     let raw;
     try {
         raw = readFileSync(filePath, "utf8");
     }
     catch {
-        return PLACEHOLDER;
+        return groundStateFallback(repoRoot, ctx);
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        return PLACEHOLDER;
+        return groundStateFallback(repoRoot, ctx);
     }
     if (!isStatusJson(parsed))
-        return PLACEHOLDER;
-    return formatStatus(parsed);
+        return groundStateFallback(repoRoot, ctx);
+    return formatStatus(parsed, ctx);
 }
 //# sourceMappingURL=reader.js.map

package/dist/status-line/reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/status-line/reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,GAAG,yBAAyB,CAAC;AAE9C,MAAM,WAAW,GAAyB;IACxC,MAAM;IACN,SAAS;IACT,QAAQ;IACR,YAAY;IACZ,SAAS;IACT,WAAW;IACX,UAAU;CACX,CAAC;AAEF,SAAS,WAAW,CAAC,CAAU;IAC7B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAK,WAAiC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,cAAc,CAAC,CAAU;IAChC,OAAO,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC;AAC7C,CAAC;AAED,SAAS,eAAe,CAAC,CAAU;IACjC,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,QAAQ,CAAC;AAC3D,CAAC;AAED,SAAS,YAAY,CAAC,CAAU;IAC9B,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,CAA4B,CAAC;IACvC,OAAO,CACL,OAAO,CAAC,CAAC,YAAY,CAAC,KAAK,QAAQ;QACnC,OAAO,CAAC,CAAC,cAAc,CAAC,KAAK,SAAS;QACtC,OAAO,CAAC,CAAC,iBAAiB,CAAC,KAAK,QAAQ;QACxC,OAAO,CAAC,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAC1C,OAAO,CAAC,CAAC,oBAAoB,CAAC,KAAK,QAAQ;QAC3C,OAAO,CAAC,CAAC,qBAAqB,CAAC,KAAK,QAAQ;QAC5C,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QAC5B,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;QAChC,OAAO,CAAC,CAAC,YAAY,CAAC,KAAK,SAAS;QACpC,OAAO,CAAC,CAAC,iBAAiB,CAAC,KAAK,QAAQ;QACxC,eAAe,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;QACrC,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CACjC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,SAAwB;IACzE,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,WAAW,CAAC;IACrE,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACrD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,WAAW,CAAC;IAE9C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC;QAAE,OAAO,WAAW,CAAC;IAE9C,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/status-line/reader.ts"],"names":[],"mappings":"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"}

package/dist/status-line/writer.d.ts

@@ -12,6 +12,11 @@ export declare function statusJsonPath(repoRoot: string, sessionId: string): str
  * the pretty-printed result back. Creates the per-session directory if
  * missing.
  *
+ * Refuses to write when the repo's `.cairn/` directory is missing — a
+ * caller that forgot to gate on `resolveRepoRoot` would otherwise
+ * `mkdir -p` a phantom `.cairn/sessions/` tree in a non-adopted
+ * project.
+ *
  * Best-effort write; no atomic-rename ceremony. The status file is
  * cosmetic — torn writes self-heal on the next hook tick.
  */
@@ -21,13 +26,5 @@ export declare function writeStatusJson(repoRoot: string, sessionId: string, pat
  * Subsequent patches (heartbeat updated_at, attention_count, etc.)
  * merge over this baseline so the shape-validating reader always sees
  * a complete object.
- *
- * `ctx_tokens_budget` defaults to 4000 — the SessionStart
- * additionalContext cap (Section 0–7 budget). Hooks may overwrite once
- * a tighter per-session value is computed.
- *
- * `daemon_alive` is retained on the wire for status-line format
- * back-compat; the daemon itself is dormant. SessionStart writes
- * `true` to indicate the session is live.
  */
-export declare function defaultStatusJson(sessionAlive: boolean): StatusJson;
+export declare function defaultStatusJson(): StatusJson;

package/dist/status-line/writer.js

@@ -16,10 +16,17 @@ export function statusJsonPath(repoRoot, sessionId) {
  * the pretty-printed result back. Creates the per-session directory if
  * missing.
  *
+ * Refuses to write when the repo's `.cairn/` directory is missing — a
+ * caller that forgot to gate on `resolveRepoRoot` would otherwise
+ * `mkdir -p` a phantom `.cairn/sessions/` tree in a non-adopted
+ * project.
+ *
  * Best-effort write; no atomic-rename ceremony. The status file is
  * cosmetic — torn writes self-heal on the next hook tick.
  */
 export function writeStatusJson(repoRoot, sessionId, patch) {
+    if (!existsSync(join(repoRoot, ".cairn")))
+        return;
     const stateDir = sessionStateDir(repoRoot, sessionId);
     const filePath = join(stateDir, "status.json");
     let existing = {};
@@ -44,27 +51,18 @@ export function writeStatusJson(repoRoot, sessionId, patch) {
  * Subsequent patches (heartbeat updated_at, attention_count, etc.)
  * merge over this baseline so the shape-validating reader always sees
  * a complete object.
- *
- * `ctx_tokens_budget` defaults to 4000 — the SessionStart
- * additionalContext cap (Section 0–7 budget). Hooks may overwrite once
- * a tighter per-session value is computed.
- *
- * `daemon_alive` is retained on the wire for status-line format
- * back-compat; the daemon itself is dormant. SessionStart writes
- * `true` to indicate the session is live.
  */
-export function defaultStatusJson(sessionAlive) {
+export function defaultStatusJson() {
     return {
         updated_at: new Date().toISOString(),
-        daemon_alive: sessionAlive,
-        ctx_tokens_used: 0,
-        ctx_tokens_budget: 4000,
         decisions_in_scope: 0,
         invariants_in_scope: 0,
         task_state: "idle",
+        task_id: null,
         task_module: null,
         gc_running: false,
         attention_count: 0,
+        bypass_count: 0,
         last_run_result: null,
         last_run_at: null,
     };

package/dist/status-line/writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/status-line/writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,SAAiB;IAChE,OAAO,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,aAAa,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,SAAiB,EACjB,KAA0B;IAE1B,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAE/C,IAAI,QAAQ,GAAwB,EAAE,CAAC;IACvC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;YAC1C,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAClD,QAAQ,GAAG,MAA6B,CAAC;YAC3C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAwB,EAAE,GAAG,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC;IAE9D,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAqB;IACrD,OAAO;QACL,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,YAAY,EAAE,YAAY;QAC1B,eAAe,EAAE,CAAC;QAClB,iBAAiB,EAAE,IAAI;QACvB,kBAAkB,EAAE,CAAC;QACrB,mBAAmB,EAAE,CAAC;QACtB,UAAU,EAAE,MAAM;QAClB,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,KAAK;QACjB,eAAe,EAAE,CAAC;QAClB,eAAe,EAAE,IAAI;QACrB,WAAW,EAAE,IAAI;KAClB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/status-line/writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,SAAiB;IAChE,OAAO,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,aAAa,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,SAAiB,EACjB,KAA0B;IAE1B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAAE,OAAO;IAElD,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAE/C,IAAI,QAAQ,GAAwB,EAAE,CAAC;IACvC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;YAC1C,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAClD,QAAQ,GAAG,MAA6B,CAAC;YAC3C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAwB,EAAE,GAAG,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC;IAE9D,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,kBAAkB,EAAE,CAAC;QACrB,mBAAmB,EAAE,CAAC;QACtB,UAAU,EAAE,MAAM;QAClB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,KAAK;QACjB,eAAe,EAAE,CAAC;QAClB,YAAY,EAAE,CAAC;QACf,eAAe,EAAE,IAAI;QACrB,WAAW,EAAE,IAAI;KAClB,CAAC;AACJ,CAAC"}

package/dist/trace/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Unified trace log for live-session debugging.
+ *
+ * Every cairn surface (Claude Code hooks, MCP tools, `claude --print`
+ * subprocess calls, init phases) appends a single jsonl row per event
+ * to `~/.local/cairn/trace/trace-<YYYY-MM-DD>.jsonl`. The `cairn trace`
+ * CLI subcommand reads them back time-sorted across the most recent
+ * day(s) so the operator can post-mortem an entire live session in one
+ * pane.
+ *
+ * Best-effort: trace failures NEVER throw — debug logging that breaks
+ * the surface it's monitoring is worse than no logging.
+ */
+export type TraceSource = "hook" | "mcp" | "claude" | "init-phase" | "subagent";
+export interface TraceEvent {
+    /** ISO 8601 with millisecond precision. */
+    ts: string;
+    /** Top-level surface emitting the event. */
+    source: TraceSource;
+    /** Event-specific kind ("session-start", "tool-call", "claude-request", …). */
+    kind: string;
+    /** Adopted-repo root, when known. */
+    repo_root: string | null;
+    /** Claude Code session id, when known. */
+    session_id: string | null;
+    /** Wall time spent, when applicable. */
+    duration_ms?: number;
+    /** Success / failure outcome, when applicable. */
+    ok?: boolean;
+    /** Free-form payload — keep small; large bodies should be stored separately. */
+    payload: Record<string, unknown>;
+}
+export declare function traceDir(): string;
+export declare function traceFilePath(now?: Date): string;
+/**
+ * Append one trace row. Best-effort — swallows any IO error so callers
+ * never break their primary surface on trace-write failure.
+ */
+export declare function appendTrace(event: TraceEvent): void;
+/**
+ * Build a TraceEvent with `ts` set to now. Convenience for callsites
+ * that build the rest of the row inline.
+ */
+export declare function nowEvent(args: Omit<TraceEvent, "ts">): TraceEvent;

package/dist/trace/index.js

@@ -0,0 +1,51 @@
+/**
+ * Unified trace log for live-session debugging.
+ *
+ * Every cairn surface (Claude Code hooks, MCP tools, `claude --print`
+ * subprocess calls, init phases) appends a single jsonl row per event
+ * to `~/.local/cairn/trace/trace-<YYYY-MM-DD>.jsonl`. The `cairn trace`
+ * CLI subcommand reads them back time-sorted across the most recent
+ * day(s) so the operator can post-mortem an entire live session in one
+ * pane.
+ *
+ * Best-effort: trace failures NEVER throw — debug logging that breaks
+ * the surface it's monitoring is worse than no logging.
+ */
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function traceDir() {
+    return join(homedir(), ".local", "cairn", "trace");
+}
+function todayFilename(now) {
+    const y = now.getUTCFullYear();
+    const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(now.getUTCDate()).padStart(2, "0");
+    return `trace-${y}-${m}-${d}.jsonl`;
+}
+export function traceFilePath(now = new Date()) {
+    return join(traceDir(), todayFilename(now));
+}
+/**
+ * Append one trace row. Best-effort — swallows any IO error so callers
+ * never break their primary surface on trace-write failure.
+ */
+export function appendTrace(event) {
+    try {
+        const dir = traceDir();
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        appendFileSync(traceFilePath(), `${JSON.stringify(event)}\n`, "utf8");
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Build a TraceEvent with `ts` set to now. Convenience for callsites
+ * that build the rest of the row inline.
+ */
+export function nowEvent(args) {
+    return { ts: new Date().toISOString(), ...args };
+}
+//# sourceMappingURL=index.js.map

package/dist/trace/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/trace/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAuBjC,MAAM,UAAU,QAAQ;IACtB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,aAAa,CAAC,GAAS;IAC9B,MAAM,CAAC,GAAG,GAAG,CAAC,cAAc,EAAE,CAAC;IAC/B,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAY,IAAI,IAAI,EAAE;IAClD,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;QACvB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,cAAc,CAAC,aAAa,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,cAAc;IAChB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,IAA4B;IACnD,OAAO,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC;AACnD,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@isaacriehm/cairn-core",
-  "version": "0.1.10",
-  "description": "Cairn core — state + context layer. Curated `.cairn/ground/` (decisions, §V invariants, canonical-map, brand, quality-grades), MCP server, init wizard, hook runners, sensors, GC drift sweep.",
+  "version": "0.3.0",
+  "description": "Cairn core — state + context layer. Curated `.cairn/ground/` (decisions, §INV invariants, canonical-map, brand, quality-grades), MCP server, init wizard, hook runners, sensors, GC drift sweep.",
   "author": "Isaac Riehm",
   "license": "MIT",
   "homepage": "https://github.com/isaacriehm/cairn",
@@ -43,7 +43,6 @@
   "devDependencies": {
     "@types/cli-progress": "^3.11.6",
     "@types/node": "^25.6.0",
-    "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   },
   "scripts": {