@eir-labs/coltrane 0.24.35 → 0.24.37

package/dist/src/version.d.ts

@@ -1,5 +1,5 @@
 /** Engine semver. Keep in lockstep with package.json `version` (enforced by test). */
-export declare const COLTRANE_VERSION = "0.24.35";
+export declare const COLTRANE_VERSION = "0.24.37";
 /**
  * The commit this engine checkout is sitting on, or null when it can't be determined.
  *

package/dist/src/version.js

@@ -17,7 +17,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 /** Engine semver. Keep in lockstep with package.json `version` (enforced by test). */
-export const COLTRANE_VERSION = "0.24.35";
+export const COLTRANE_VERSION = "0.24.37";
 /**
  * The commit this engine checkout is sitting on, or null when it can't be determined.
  *

package/domain_types/session-analysis.json

@@ -0,0 +1,59 @@
+{
+  "slug": "session-analysis",
+  "version": 1,
+  "extends": "Interpretation",
+  "domain": "session-review",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "where_the_cost_went": {
+        "type": "array",
+        "description": "each finding {finding, evidence, value} — which token class, which tool, which phase carried the bill",
+        "items": {
+          "type": "object"
+        }
+      },
+      "where_the_time_went": {
+        "type": "array",
+        "items": {
+          "type": "object"
+        }
+      },
+      "rework": {
+        "type": "array",
+        "description": "work that had to be done twice, with the census evidence that shows it (errors, denials, repeated operator corrections)",
+        "items": {
+          "type": "object"
+        }
+      },
+      "said_vs_done": {
+        "type": "array",
+        "description": "where the operator's messages and the tool histogram disagree — what was asked for versus what the session spent itself on",
+        "items": {
+          "type": "object"
+        }
+      },
+      "turning_points": {
+        "type": "array",
+        "description": "the moments the session changed direction, each anchored to an operator message",
+        "items": {
+          "type": "object"
+        }
+      },
+      "caveats": {
+        "type": "array",
+        "description": "what the census cannot show, stated so the writer does not fill the gap",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required_fields": [
+    "where_the_cost_went",
+    "rework",
+    "turning_points",
+    "caveats"
+  ]
+}

package/domain_types/session-census.json

@@ -0,0 +1,72 @@
+{
+  "slug": "session-census",
+  "version": 1,
+  "extends": "Signal",
+  "domain": "session-review",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "transcript": {
+        "type": "string"
+      },
+      "bytes": {
+        "type": "number"
+      },
+      "records": {
+        "type": "number"
+      },
+      "span": {
+        "type": "object",
+        "description": "{first, last} timestamps of the transcript"
+      },
+      "turns": {
+        "type": "object",
+        "description": "assistant turns and the token classes they reported, plus the peak context"
+      },
+      "tools": {
+        "type": "array",
+        "description": "{name, calls}, most-called first",
+        "items": {
+          "type": "object"
+        }
+      },
+      "operator_messages": {
+        "type": "array",
+        "description": "the operator's own messages, identical ones collapsed to {text, count, first, last} — a repeated cron prompt is one decision said many times",
+        "items": {
+          "type": "object"
+        }
+      },
+      "interruptions": {
+        "type": "number"
+      },
+      "denials": {
+        "type": "array",
+        "items": {
+          "type": "object"
+        }
+      },
+      "errors": {
+        "type": "array",
+        "items": {
+          "type": "object"
+        }
+      },
+      "error": {
+        "type": "string",
+        "description": "set when the transcript could not be read; the census is then a refusal, not an empty count"
+      },
+      "source": {
+        "type": "string"
+      }
+    }
+  },
+  "required_fields": [
+    "transcript",
+    "records",
+    "turns",
+    "tools",
+    "operator_messages"
+  ]
+}

package/domain_types/session-review-verdict.json

@@ -0,0 +1,48 @@
+{
+  "slug": "session-review-verdict",
+  "version": 1,
+  "extends": "Verdict",
+  "domain": "session-review",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "pass": {
+        "type": "boolean"
+      },
+      "unsupported_claims": {
+        "type": "array",
+        "description": "claims whose evidence path is absent from the census, or whose value disagrees with it",
+        "items": {
+          "type": "object"
+        }
+      },
+      "misquoted_decisions": {
+        "type": "array",
+        "description": "decisions whose quote does not appear verbatim in the census's operator messages",
+        "items": {
+          "type": "object"
+        }
+      },
+      "omissions": {
+        "type": "array",
+        "description": "what the census carries that the review does not mention and should",
+        "items": {
+          "type": "string"
+        }
+      },
+      "checks": {
+        "type": "array",
+        "items": {
+          "type": "object"
+        }
+      }
+    }
+  },
+  "required_fields": [
+    "pass",
+    "checks",
+    "unsupported_claims",
+    "misquoted_decisions"
+  ]
+}

package/domain_types/session-review.json

@@ -0,0 +1,86 @@
+{
+  "slug": "session-review",
+  "version": 1,
+  "extends": "Artifact",
+  "domain": "session-review",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "title": {
+        "type": "string"
+      },
+      "span": {
+        "type": "string",
+        "description": "the session's start and end, from the census"
+      },
+      "what_happened": {
+        "type": "string",
+        "description": "the arc of the session in plain prose: what was asked, what was built, what was decided"
+      },
+      "what_it_cost": {
+        "type": "string",
+        "description": "the measured shape of the spend and the context, from the census and the ledger rows carried in"
+      },
+      "what_went_wrong": {
+        "type": "string",
+        "description": "defects, dead ends, wasted work and their causes — named, not softened"
+      },
+      "decisions": {
+        "type": "array",
+        "description": "the operator's decisions, each quoted from their own message in the census",
+        "items": {
+          "type": "object",
+          "properties": {
+            "decision": {
+              "type": "string"
+            },
+            "quote": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "decision",
+            "quote"
+          ]
+        }
+      },
+      "open": {
+        "type": "array",
+        "description": "what the session left open",
+        "items": {
+          "type": "string"
+        }
+      },
+      "claims": {
+        "type": "array",
+        "description": "every factual claim the prose makes, paired with the census path or ledger field that supports it",
+        "items": {
+          "type": "object",
+          "properties": {
+            "text": {
+              "type": "string"
+            },
+            "evidence": {
+              "type": "string"
+            },
+            "value": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "text",
+            "evidence"
+          ]
+        }
+      }
+    }
+  },
+  "required_fields": [
+    "title",
+    "what_happened",
+    "what_it_cost",
+    "what_went_wrong",
+    "claims"
+  ]
+}

package/domain_types/session-target.json

@@ -0,0 +1,26 @@
+{
+  "slug": "session-target",
+  "version": 1,
+  "extends": "Signal",
+  "domain": "session-review",
+  "status": "active",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "transcript": {
+        "type": "string",
+        "description": "absolute path to one Claude Code session transcript (.jsonl)"
+      },
+      "label": {
+        "type": "string",
+        "description": "what this session was, in the operator's words — carried, never inferred"
+      },
+      "source": {
+        "type": "string"
+      }
+    }
+  },
+  "required_fields": [
+    "transcript"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eir-labs/coltrane",
-  "version": "0.24.35",
+  "version": "0.24.37",
   "description": "A methodology engine \u2014 a typed substrate for defining agents, composing multi-phase standards, dispatching gigs, and sealing every output to a content-addressed ledger. Ships as an MCP server.",
   "type": "module",
   "license": "Apache-2.0",

package/releases.json

@@ -1,6 +1,88 @@
 {
   "generated_from": "compileReleases",
   "releases": [
+    {
+      "version": "0.24.36",
+      "tag": "v0.24.36",
+      "date": "2026-09-18T17:21:59+02:00",
+      "commits": [
+        {
+          "sha": "158770e08b12936f976133f8b450d3129107e4b7",
+          "subject": "the hosted door validates the payload at post time (#542)"
+        }
+      ],
+      "bump": "patch",
+      "laws": {
+        "before": 3925,
+        "after": 3933,
+        "files": 410
+      },
+      "surface": {
+        "mcp_tools": {
+          "added": [],
+          "removed": []
+        },
+        "mcp_tool_args": {
+          "added": [],
+          "removed": []
+        },
+        "cli_flags": {
+          "added": [],
+          "removed": []
+        },
+        "env_vars": {
+          "added": [],
+          "removed": []
+        },
+        "domain_types": {
+          "added": [],
+          "removed": []
+        }
+      },
+      "surface_unread": [],
+      "pending": false
+    },
+    {
+      "version": "0.24.35",
+      "tag": "v0.24.35",
+      "date": "2026-09-18T15:08:15+02:00",
+      "commits": [
+        {
+          "sha": "5693588c2ca04935d120ac8da32ae925ce0e5afe",
+          "subject": "no dispatch payload key is silently ignored (#541)"
+        }
+      ],
+      "bump": "patch",
+      "laws": {
+        "before": 3918,
+        "after": 3925,
+        "files": 409
+      },
+      "surface": {
+        "mcp_tools": {
+          "added": [],
+          "removed": []
+        },
+        "mcp_tool_args": {
+          "added": [],
+          "removed": []
+        },
+        "cli_flags": {
+          "added": [],
+          "removed": []
+        },
+        "env_vars": {
+          "added": [],
+          "removed": []
+        },
+        "domain_types": {
+          "added": [],
+          "removed": []
+        }
+      },
+      "surface_unread": [],
+      "pending": false
+    },
     {
       "version": "0.24.34",
       "tag": "v0.24.34",

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"]
+  }
+}