@eir-labs/coltrane 0.24.36 → 0.24.38

package/skills/gig-census/fixtures/basic.json

@@ -0,0 +1,33 @@
+{
+  "id": "basic",
+  "description": "contract: the census counts what a gig DID \u2014 one amend round for the chair that sealed the same type twice, the failed verdict, the departure, and the spend \u2014 from records shipped with the skill.",
+  "input": {
+    "gig-target": {
+      "gig_id": "00000000-0000-4000-8000-00000000cens",
+      "outputs_dir": "skills/gig-census/fixtures/outputs",
+      "ledger_path": "skills/gig-census/fixtures/ledger.jsonl"
+    }
+  },
+  "assertions": [
+    {
+      "path": "gig_id",
+      "op": "equals",
+      "value": "00000000-0000-4000-8000-00000000cens"
+    },
+    {
+      "path": "chairs.0.amend_rounds",
+      "op": "equals",
+      "value": 1
+    },
+    {
+      "path": "failed_verdicts",
+      "op": "equals",
+      "value": 1
+    },
+    {
+      "path": "spend.completed",
+      "op": "equals",
+      "value": true
+    }
+  ]
+}

package/skills/gig-census/fixtures/ledger.jsonl

@@ -0,0 +1,3 @@
+{"kind": "chair_spend", "gig_id": "00000000-0000-4000-8000-00000000cens", "role": "make"}
+{"kind": "chair_spend", "gig_id": "00000000-0000-4000-8000-00000000cens", "role": "check"}
+{"kind": "gig", "gig_id": "00000000-0000-4000-8000-00000000cens", "status": "complete"}

package/skills/gig-census/fixtures/outputs/00000000-0000-4000-8000-00000000cens.jsonl

@@ -0,0 +1,4 @@
+{"id": "o1", "gig_id": "00000000-0000-4000-8000-00000000cens", "from_role": "make", "agent_slug": "maker", "domain_type": "artifact", "created_at": "2026-09-19T00:00:00Z", "cost_usd": 1.5, "model": "model-a", "data": {"value": "v1"}}
+{"id": "o2", "gig_id": "00000000-0000-4000-8000-00000000cens", "from_role": "check", "agent_slug": "checker", "domain_type": "verdict", "created_at": "2026-09-19T00:01:00Z", "cost_usd": 0.25, "model": "model-b", "data": {"pass": false}}
+{"id": "o3", "gig_id": "00000000-0000-4000-8000-00000000cens", "from_role": "make", "agent_slug": "maker", "domain_type": "artifact", "created_at": "2026-09-19T00:02:00Z", "cost_usd": 1.0, "model": "model-a", "data": {"value": "v2", "departures": [{"from_step": "P1", "instead": "left red", "why": "the law's fixture could not build"}]}}
+{"id": "o4", "gig_id": "00000000-0000-4000-8000-00000000cens", "from_role": "check", "agent_slug": "checker", "domain_type": "verdict", "created_at": "2026-09-19T00:03:00Z", "cost_usd": 0.25, "model": "model-b", "data": {"pass": true}}

package/skills/gig-census/meta.json

@@ -0,0 +1,20 @@
+{
+  "slug": "gig-census",
+  "version": 1,
+  "skill_type": "analysis",
+  "permission": { "tier": 1 },
+  "determinism_ratio": 1.0,
+  "input_type": "gig-target",
+  "output_type": "gig-census",
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "gig_id": { "type": "string" },
+      "chairs": { "type": "array" },
+      "verdicts": { "type": "array" },
+      "departures": { "type": "array" },
+      "spend": { "type": "object" }
+    },
+    "required": ["gig_id", "chairs", "spend"]
+  }
+}

package/skills/gig-census/skill.mjs

@@ -0,0 +1,114 @@
+// What a gig ACTUALLY did (determinism 1.0): read the sealed outputs and the ledger rows for one
+// gig_id and count them. This is the evidence half of reconciliation, and it exists so the question
+// "what happened" is never put to the agent that did it — a seat asked to recall its own run will
+// answer with a story, and a story is what a ledger must not accrue.
+//
+// What the agent CAN answer — why, and what it would do differently — is the other half, and it is a
+// hypothesis marked as one, never a finding.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const readJsonl = (path) => {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch { /* a torn line is not a record */ }
+  }
+  return out;
+};
+
+const ms = (a, b) => (a && b ? Math.max(0, Date.parse(b) - Date.parse(a)) : null);
+
+export default async function run(input) {
+  const target = (input && typeof input === "object" && input["gig-target"]) || input || {};
+  const gig_id = target.gig_id ? String(target.gig_id) : "";
+  if (!gig_id) throw new Error("gig-census: no `gig_id` in the input");
+
+  const outputsDir = target.outputs_dir
+    ? String(target.outputs_dir)
+    : join(process.env.COLTRANE_OUTPUTS_DIR ?? join(homedir(), ".eir", "coltrane_outputs"), "outputs");
+  const ledgerPath = target.ledger_path ? String(target.ledger_path) : join(process.cwd(), ".coltrane", "ledger.jsonl");
+
+  const outPath = join(outputsDir, `${gig_id}.jsonl`);
+  if (!existsSync(outPath)) throw new Error(`gig-census: no sealed outputs for gig "${gig_id}" at ${outPath}`);
+  const records = readJsonl(outPath);
+
+  // Every sealed record, in order, by the chair that sealed it. A role appearing more than once is an
+  // AMEND ROUND, which is the single most informative fact about how a gig went.
+  const byRole = new Map();
+  const seals = [];
+  for (const r of records) {
+    const role = r.from_role ?? "(none)";
+    const slot = byRole.get(role) ?? { role, agent: r.agent_slug, seals: 0, cost_usd: 0, models: new Set(), types: new Set(), perType: new Map() };
+    slot.seals += 1;
+    // An AMEND ROUND is the same chair sealing the same TYPE again — not the same chair sealing two
+    // different types once each. A builder that seals a change-set and a primer in one round is not a
+    // builder that ran twice, and counting it as one would put a failure in the ledger that never
+    // happened.
+    if (r.domain_type) slot.perType.set(r.domain_type, (slot.perType.get(r.domain_type) ?? 0) + 1);
+    if (typeof r.cost_usd === "number") slot.cost_usd += r.cost_usd;
+    if (r.model) slot.models.add(r.model);
+    if (r.domain_type) slot.types.add(r.domain_type);
+    byRole.set(role, slot);
+    const d = r.data ?? {};
+    seals.push({
+      at: r.created_at, role, agent: r.agent_slug, type: r.domain_type,
+      cost_usd: typeof r.cost_usd === "number" ? r.cost_usd : null,
+      model: r.model ?? null,
+      ...(typeof d.pass === "boolean" ? { pass: d.pass } : {}),
+      ...(Array.isArray(d.departures) && d.departures.length > 0 ? { departures: d.departures.length } : {}),
+    });
+  }
+
+  // A verdict that failed, and the departures a maker recorded rather than bridging: the two places a
+  // gig says out loud that it did not go cleanly.
+  const verdicts = records
+    .filter((r) => typeof (r.data ?? {}).pass === "boolean")
+    .map((r) => ({ at: r.created_at, role: r.from_role, pass: r.data.pass }));
+  const departures = [];
+  for (const r of records) {
+    for (const dep of (r.data ?? {}).departures ?? []) {
+      departures.push({ role: r.from_role, from_step: dep.from_step ?? null, instead: dep.instead ?? null, why: dep.why ?? null });
+    }
+  }
+
+  const primers = records
+    .filter((r) => r.domain_type === "seat-primer")
+    .map((r) => ({ role: r.from_role, agent: r.data?.agent_slug, area: r.data?.area, context_tokens: r.data?.context_tokens ?? null, frontier: r.data?.frontier ?? null, files: (r.data?.files ?? []).length }));
+
+  const ledgerRows = readJsonl(ledgerPath).filter((row) => row.gig_id === gig_id);
+  const spendRows = ledgerRows.filter((row) => row.kind === "chair_spend");
+  const gigRows = ledgerRows.filter((row) => row.kind === "gig");
+
+  const first = records[0]?.created_at ?? null;
+  const last = records[records.length - 1]?.created_at ?? null;
+  const sealedCost = records.reduce((a, r) => a + (typeof r.cost_usd === "number" ? r.cost_usd : 0), 0);
+
+  return {
+    source: `gig-census://${gig_id}`,
+    gig_id,
+    span: { first, last, duration_ms: ms(first, last) },
+    chairs: [...byRole.values()].map((s) => ({
+      role: s.role, agent: s.agent, seals: s.seals,
+      amend_rounds: Math.max(0, Math.max(...[...s.perType.values()], 1) - 1),
+      cost_usd: Number(s.cost_usd.toFixed(4)),
+      models: [...s.models], output_types: [...s.types],
+    })),
+    seals,
+    verdicts,
+    failed_verdicts: verdicts.filter((v) => v.pass === false).length,
+    departures,
+    primers,
+    spend: {
+      sealed_cost_usd: Number(sealedCost.toFixed(4)),
+      chair_spend_rows: spendRows.length,
+      gig_rows: gigRows.length,
+      // A gig row missing while sealed outputs exist means the gig did not complete — the absence IS
+      // the signal (#236), so it is reported rather than defaulted to "complete".
+      completed: gigRows.length > 0,
+    },
+  };
+}

package/skills/session-census/fixtures/basic.json

@@ -0,0 +1,10 @@
+{
+  "id": "basic",
+  "description": "contract: the census counts a transcript held in the package itself — records, assistant turns, the tool histogram, and the operator's messages with repeats collapsed.",
+  "input": { "session-target": { "transcript": "skills/session-census/fixtures/sample.jsonl" } },
+  "assertions": [
+    { "path": "records", "op": "equals", "value": 6 },
+    { "path": "turns.assistant", "op": "equals", "value": 2 },
+    { "path": "operator_messages.0.count", "op": "equals", "value": 2 }
+  ]
+}

package/skills/session-census/fixtures/sample.jsonl

@@ -0,0 +1,6 @@
+{"type": "user", "timestamp": "2026-09-19T00:00:00Z", "message": {"content": "do the thing"}}
+{"type": "assistant", "timestamp": "2026-09-19T00:00:01Z", "message": {"id": "m1", "usage": {"input_tokens": 10, "output_tokens": 5, "cache_read_input_tokens": 100}, "content": [{"type": "tool_use", "name": "Bash", "input": {}}]}}
+{"type": "user", "timestamp": "2026-09-19T00:00:02Z", "message": {"content": [{"type": "tool_result", "content": "ok"}]}}
+{"type": "assistant", "timestamp": "2026-09-19T00:00:03Z", "message": {"id": "m2", "usage": {"input_tokens": 12, "output_tokens": 6}, "content": [{"type": "tool_use", "name": "Bash", "input": {}}]}}
+{"type": "user", "timestamp": "2026-09-19T00:00:04Z", "message": {"content": "do the thing"}}
+{"type": "user", "timestamp": "2026-09-19T00:00:05Z", "message": {"content": "<system-reminder>ignored</system-reminder>"}}

package/skills/session-census/meta.json

@@ -0,0 +1,25 @@
+{
+  "slug": "session-census",
+  "version": 1,
+  "skill_type": "analysis",
+  "permission": { "tier": 1 },
+  "determinism_ratio": 1.0,
+  "input_type": "session-target",
+  "output_type": "session-census",
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "transcript": { "type": "string" },
+      "bytes": { "type": "number" },
+      "records": { "type": "number" },
+      "span": { "type": "object" },
+      "turns": { "type": "object" },
+      "tools": { "type": "array" },
+      "operator_messages": { "type": "array" },
+      "interruptions": { "type": "number" },
+      "denials": { "type": "array" },
+      "errors": { "type": "array" }
+    },
+    "required": ["transcript", "records", "turns", "tools", "operator_messages"]
+  }
+}

package/skills/session-census/skill.mjs

@@ -0,0 +1,141 @@
+// The deterministic half of a session review (determinism 1.0): read one Claude Code transcript and
+// COUNT it. No model, no judgement — every number here is a fact a reviewer can be held to, and the
+// review seat downstream may claim nothing this census does not carry.
+//
+// A transcript is JSONL, one record per line, and large (this session's is 23MB), so it is streamed
+// line by line and never held whole. What comes out is small enough for a seat to read.
+import { createReadStream, statSync } from "node:fs";
+import { createInterface } from "node:readline";
+
+const TOOL_BUCKET = (name) =>
+  name.startsWith("mcp__") ? `mcp:${name.split("__")[1] ?? "?"}` : name;
+
+export default async function run(input) {
+  // A ROOT skill chair is handed the gig payload as the runtime holds it: keyed by type slug
+  // (`{"session-target": {transcript}}`). A chair fed by upstream outputs gets the merged data
+  // instead. Accept both rather than depending on where in a standard this chair happens to sit.
+  const target = (input && typeof input === "object" && input["session-target"]) || input || {};
+  const path = target && target.transcript ? String(target.transcript) : "";
+  // A census that cannot read its transcript THROWS: returning an explanation object would fail the
+  // seal's schema check instead, and the caller would read "required property 'records' missing"
+  // rather than the reason. Fail with the reason.
+  if (!path) throw new Error("session-census: no `transcript` path in the input");
+
+  let bytes = 0;
+  try {
+    bytes = statSync(path).size;
+  } catch {
+    throw new Error(`session-census: cannot read "${path}"`);
+  }
+
+  const tools = new Map();
+  const operatorByText = new Map();
+  const denials = [];
+  const errors = [];
+  let records = 0;
+  let assistantTurns = 0;
+  let firstTs = null;
+  let lastTs = null;
+  let interruptions = 0;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheRead = 0;
+  let cacheWrite = 0;
+  let maxContext = 0;
+  const seenMessageIds = new Set();
+
+  const rl = createInterface({ input: createReadStream(path, { encoding: "utf8" }), crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    let r;
+    try { r = JSON.parse(line); } catch { continue; }
+    records += 1;
+    const ts = typeof r.timestamp === "string" ? r.timestamp : null;
+    if (ts) { if (firstTs === null) firstTs = ts; lastTs = ts; }
+
+    if (r.type === "user") {
+      const c = r.message?.content;
+      // A STRING content is the operator typing; a list is a tool result coming back.
+      if (typeof c === "string") {
+        const text = c.trim();
+        // The harness injects its own user-shaped records (command output, reminders). An operator
+        // message is what is left once those are excluded — named, so the exclusion is auditable.
+        const injected =
+          text.startsWith("<command-") || text.startsWith("<local-command") ||
+          text.startsWith("[Request interrupted") || text.includes("<system-reminder>") ||
+          // Harness-delivered, not typed by the operator: a background task reporting in, and a message
+          // from another session. Counting either as the operator's would credit them with decisions
+          // nobody made.
+          text.startsWith("<task-notification>") || text.startsWith("<cross-session-message");
+        if (text.startsWith("[Request interrupted")) interruptions += 1;
+        // A repeated message (a cron firing the same prompt) is ONE decision said many times, not many
+        // decisions: collapse it to a count, first and last seen. Otherwise the census is mostly echo,
+        // and a seat reading it would weigh the loop's cadence as if it were the operator's attention.
+        if (!injected && text) {
+          const key = text.length > 400 ? `${text.slice(0, 400)}…` : text;
+          const prior = operatorByText.get(key);
+          if (prior) { prior.count += 1; prior.last = ts; }
+          else operatorByText.set(key, { text: key, count: 1, first: ts, last: ts });
+        }
+      }
+    }
+
+    if (r.type === "assistant") {
+      const msg = r.message ?? {};
+      const id = msg.id;
+      if (id && !seenMessageIds.has(id)) {
+        seenMessageIds.add(id);
+        assistantTurns += 1;
+        const u = msg.usage ?? {};
+        inputTokens += u.input_tokens ?? 0;
+        outputTokens += u.output_tokens ?? 0;
+        cacheRead += u.cache_read_input_tokens ?? 0;
+        cacheWrite += u.cache_creation_input_tokens ?? 0;
+        const ctx = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+        if (ctx > maxContext) maxContext = ctx;
+      }
+      for (const b of msg.content ?? []) {
+        if (b && b.type === "tool_use" && typeof b.name === "string") {
+          const k = TOOL_BUCKET(b.name);
+          tools.set(k, (tools.get(k) ?? 0) + 1);
+        }
+      }
+    }
+
+    // A tool result carrying a refusal or an error is evidence a reviewer should not have to find.
+    if (r.type === "user" && Array.isArray(r.message?.content)) {
+      for (const b of r.message.content) {
+        if (!b || b.type !== "tool_result") continue;
+        const text = typeof b.content === "string" ? b.content : JSON.stringify(b.content ?? "");
+        if (/permission[^\n]{0,40}denied|Blocked by classifier/i.test(text)) {
+          denials.push({ at: ts, text: text.slice(0, 300) });
+        } else if (b.is_error) {
+          errors.push({ at: ts, text: text.slice(0, 300) });
+        }
+      }
+    }
+  }
+
+  return {
+    // The Signal core requires a non-empty `source`: what this reading is OF. For a census that is the
+    // transcript it counted, named so a sealed census can be traced back to the file it read.
+    source: `session-census://${path}`,
+    transcript: path,
+    bytes,
+    records,
+    span: { first: firstTs, last: lastTs },
+    turns: {
+      assistant: assistantTurns,
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      cache_read_tokens: cacheRead,
+      cache_write_tokens: cacheWrite,
+      max_context_tokens: maxContext,
+    },
+    tools: [...tools.entries()].sort((a, b) => b[1] - a[1]).map(([name, calls]) => ({ name, calls })),
+    operator_messages: [...operatorByText.values()],
+    interruptions,
+    denials,
+    errors: errors.slice(0, 40),
+  };
+}

package/standards/session-review-v0.json

@@ -0,0 +1,104 @@
+{
+  "slug": "session-review-v0",
+  "domain": "session-review",
+  "agent_slugs": [
+    "session-analyst",
+    "session-reviewer",
+    "session-review-verifier"
+  ],
+  "phases": [
+    {
+      "name": "census",
+      "chairs": [
+        {
+          "role": "census",
+          "skill_slug": "session-census",
+          "depends_on": [],
+          "input_contract": [
+            "session-target"
+          ],
+          "output_contract": [
+            "session-census"
+          ],
+          "required_skills": []
+        }
+      ]
+    },
+    {
+      "name": "analyse",
+      "chairs": [
+        {
+          "role": "analyse",
+          "agent_slug": "session-analyst",
+          "depends_on": [
+            "census"
+          ],
+          "input_contract": [
+            "session-census"
+          ],
+          "output_contract": [
+            "session-analysis"
+          ],
+          "required_skills": [],
+          "turn_reserve": 4
+        }
+      ]
+    },
+    {
+      "name": "review",
+      "chairs": [
+        {
+          "role": "write-review",
+          "agent_slug": "session-reviewer",
+          "depends_on": [
+            "census",
+            "analyse"
+          ],
+          "input_contract": [
+            "session-census",
+            "session-analysis"
+          ],
+          "output_contract": [
+            "session-review"
+          ],
+          "required_skills": [],
+          "turn_reserve": 4
+        }
+      ]
+    },
+    {
+      "name": "check",
+      "chairs": [
+        {
+          "role": "check-review",
+          "agent_slug": "session-review-verifier",
+          "depends_on": [
+            "census",
+            "write-review"
+          ],
+          "input_contract": [
+            "session-census",
+            "session-review"
+          ],
+          "output_contract": [
+            "session-review-verdict"
+          ],
+          "required_skills": [],
+          "turn_reserve": 4
+        }
+      ]
+    }
+  ],
+  "status": "draft",
+  "input_types": [
+    "session-target"
+  ],
+  "output_types": [
+    "session-census",
+    "session-analysis",
+    "session-review",
+    "session-review-verdict"
+  ],
+  "max_examine_rounds": 2,
+  "description": "A formal review of one working session, from a census counted by code rather than from anyone's memory. The input is a session-target: the path to a Claude Code transcript. The census chair is SKILL-BACKED (session-census, determinism 1.0, no model): it streams the .jsonl — 23MB and 13,000 records for the session this was built on — and emits counts, the tool histogram, the token classes and peak context, the operator's own messages with identical ones collapsed to a count, the interruptions, the denials and the errors. Nothing a model has to summarize, and nothing a model may contradict. An INTERPRET seat sits between the counts and the prose — composeStandard refuses a CREATE seat fed only by sensing, and it is right: the patterns (where the cost went, what was done twice, where what was ASKED FOR diverges from what the session SPENT ITSELF ON) are a separate judgement from the prose that reports them. The review seat then writes what the session was: the arc, the measured cost, what went wrong, the operator's decisions quoted from their own words, and every claim paired with the census path behind it. The verify seat resolves each path, checks each quote VERBATIM against the operator's messages, and names what the census carries that the review ignored; a failing verdict re-runs the writer with the verdict fed back. A review that flatters the work is a failed review, and a quote the operator never wrote is the failure the verify seat exists to catch."
+}