@eir-labs/coltrane 0.4.0

package/dist/src/genome_schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genome_schema.js","sourceRoot":"","sources":["../../src/genome_schema.ts"],"names":[],"mappings":"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"}

package/dist/src/genome_writer.d.ts

@@ -0,0 +1,67 @@
+import { type Agent, type AgentDef } from "./composition.js";
+import { type Ledger } from "./ledger.js";
+/**
+ * Write a genome file, preserving any prior version's BYTES before a destructive
+ * overwrite. The ledger already keeps the content-hash *identity* of every seal;
+ * this keeps the actual prior *content*, so a re-compose / re-define / evolve over
+ * an existing slug is recoverable, not just provably-changed.
+ *
+ * When <subdir>/<slug>.json already exists with DIFFERENT bytes, the old bytes are
+ * snapshotted to .coltrane/history/<subdir>/<slug>/<oldContentHash>.json (gitignored,
+ * local) before the overwrite. Identical bytes → no snapshot (idempotent no-op).
+ * Returns the prior content hash when an overwrite displaced real content.
+ */
+export declare function writeGenomeFileVersioned(genome_dir: string, subdir: string, slug: string, jsonText: string): {
+    overwritten: boolean;
+    prior_content_hash?: string;
+};
+export interface SealResult {
+    agent: Agent;
+    content_hash: string;
+    dependency_hash: string;
+    effective_hash: string;
+}
+/** Generic substrate seal for ANY genome definition (agent / standard / type / skill).
+ *  Computes the canonical identity, and when a genome_dir is given, writes the
+ *  content-addressed file under <subdir>/<slug>.json AND appends the ledger seal keyed
+ *  standard_slug=<kind>, genome_hash=effective_hash. The single blessed write path. */
+export declare function sealDefinition(kind: string, slug: string, def: unknown, ledger: Ledger, genome_dir: string | undefined, subdir: string): {
+    content_hash: string;
+    dependency_hash: string;
+    effective_hash: string;
+};
+/** Ledger-only identity seal — for version-producing mutations (type_extend, agent_evolve)
+ *  whose new-version FILE materialization needs version-aware loader support (the one named
+ *  boundary). The identity is still sealed in the append-only ledger, so the mutation is
+ *  never a contract lie: its effective_hash is recorded even before the file lands. */
+export declare function recordIdentity(kind: string, slug: string, def: unknown, ledger: Ledger): {
+    content_hash: string;
+    dependency_hash: string;
+    effective_hash: string;
+};
+/** The canonical identity of an agent definition. PURE + deterministic from the def, so
+ *  the same input always yields the same effective_hash (cross-machine interoperable). */
+export declare function agentIdentity(def: AgentDef): {
+    content_hash: string;
+    dependency_hash: string;
+    effective_hash: string;
+};
+/** Validate, hash, and (when a genome_dir is provided) PERSIST + LEDGER-SEAL. Without a
+ *  genome_dir the identity is still computed + returned (validation path); with one, the
+ *  agent is written to agents/<slug>.json and the effective_hash is recorded in the
+ *  append-only ledger — the only way an agent enters the substrate of truth. */
+export declare function sealAgentDefinition(def: AgentDef, ledger: Ledger, genome_dir?: string): SealResult;
+/** Persist a skill as the LOADABLE PACKAGE the loader reads — skills/<slug>/{meta.json, skill.mjs?,
+ *  skill.md?, fixtures/*.json} — not a flat skills/<slug>.json the loader skips. The content fields
+ *  (`code` → skill.mjs, `md` → skill.md) and each fixture become their own files; meta.json holds the
+ *  remaining declared fields. Identity is hashed over the full canonical def, so the content_hash is
+ *  stable regardless of the on-disk split. Closes the skill_define → reload roundtrip (audit E).
+ *  The caller MUST pre-validate completeness (≥1 fixture + a code/reasoning half) — the loader
+ *  hard-fails an incomplete package, so an incomplete write would crash the next genome load. */
+export declare function sealSkillPackage(def: Record<string, unknown> & {
+    slug: string;
+}, ledger: Ledger, genome_dir?: string): {
+    content_hash: string;
+    dependency_hash: string;
+    effective_hash: string;
+};

package/dist/src/genome_writer.js

@@ -0,0 +1,179 @@
+// MCP-sole-writer + canonical identity sealing (the substrate-of-truth loop, O26).
+// A definition's identity is its canonical hash chain (content → dependency → effective),
+// NOT its bytes. sealAgentDefinition is the blessed write path: validate → hash → (when a
+// genome_dir is given) write the content-addressed file AND append a ledger entry keyed
+// standard_slug="agent_define", genome_hash=effective_hash. A hand-edited file with no
+// such ledger entry is an orphan — no identity, outside the substrate.
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { defineAgent } from "./composition.js";
+import { canonJson, sha256Hex, effectiveHash, EMPTY_DEPENDENCY_HASH } from "./canonical_form.js";
+import { LEDGER_SCHEMA_VERSION } from "./ledger.js";
+/**
+ * Write a genome file, preserving any prior version's BYTES before a destructive
+ * overwrite. The ledger already keeps the content-hash *identity* of every seal;
+ * this keeps the actual prior *content*, so a re-compose / re-define / evolve over
+ * an existing slug is recoverable, not just provably-changed.
+ *
+ * When <subdir>/<slug>.json already exists with DIFFERENT bytes, the old bytes are
+ * snapshotted to .coltrane/history/<subdir>/<slug>/<oldContentHash>.json (gitignored,
+ * local) before the overwrite. Identical bytes → no snapshot (idempotent no-op).
+ * Returns the prior content hash when an overwrite displaced real content.
+ */
+export function writeGenomeFileVersioned(genome_dir, subdir, slug, jsonText) {
+    const dir = join(genome_dir, subdir);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${slug}.json`);
+    let result = { overwritten: false };
+    if (existsSync(path)) {
+        const oldBytes = readFileSync(path, "utf-8");
+        if (oldBytes !== jsonText) {
+            const prior = sha256Hex(oldBytes);
+            const histDir = join(genome_dir, ".coltrane", "history", subdir, slug);
+            mkdirSync(histDir, { recursive: true });
+            writeFileSync(join(histDir, `${prior}.json`), oldBytes);
+            result = { overwritten: true, prior_content_hash: prior };
+        }
+    }
+    writeFileSync(path, jsonText);
+    return result;
+}
+/** Generic substrate seal for ANY genome definition (agent / standard / type / skill).
+ *  Computes the canonical identity, and when a genome_dir is given, writes the
+ *  content-addressed file under <subdir>/<slug>.json AND appends the ledger seal keyed
+ *  standard_slug=<kind>, genome_hash=effective_hash. The single blessed write path. */
+export function sealDefinition(kind, slug, def, ledger, genome_dir, subdir) {
+    const content_hash = sha256Hex(canonJson(def));
+    const dependency_hash = EMPTY_DEPENDENCY_HASH;
+    const effective_hash = effectiveHash(content_hash, dependency_hash);
+    if (genome_dir) {
+        // #218 — SEAL BEFORE WRITE. The reverse order manufactures the exact orphan this module's
+        // header calls "outside the substrate": if the append throws (ENOSPC/EACCES — the
+        // LedgerError path at src/ledger.ts), the definition is already on disk and loadable with
+        // no identity, while dispatchTool tells the caller nothing happened. Recording an identity
+        // whose file failed to materialise is the safe direction: the next write retries, and the
+        // ledger never claims less than reality.
+        const now = new Date().toISOString();
+        ledger.append({
+            kind: "genome_mutation",
+            schema_version: LEDGER_SCHEMA_VERSION,
+            entry_id: `${kind}:${slug}:${randomUUID()}`,
+            event: kind,
+            subject_slug: slug,
+            content_hash,
+            dependency_hash,
+            effective_hash,
+            output_hashes: [content_hash],
+            started_at: now,
+            finished_at: now,
+        });
+        writeGenomeFileVersioned(genome_dir, subdir, slug, JSON.stringify(def, null, 2) + "\n");
+    }
+    return { content_hash, dependency_hash, effective_hash };
+}
+/** Ledger-only identity seal — for version-producing mutations (type_extend, agent_evolve)
+ *  whose new-version FILE materialization needs version-aware loader support (the one named
+ *  boundary). The identity is still sealed in the append-only ledger, so the mutation is
+ *  never a contract lie: its effective_hash is recorded even before the file lands. */
+export function recordIdentity(kind, slug, def, ledger) {
+    const content_hash = sha256Hex(canonJson(def));
+    const dependency_hash = EMPTY_DEPENDENCY_HASH;
+    const effective_hash = effectiveHash(content_hash, dependency_hash);
+    const now = new Date().toISOString();
+    ledger.append({
+        kind: "genome_mutation",
+        schema_version: LEDGER_SCHEMA_VERSION,
+        entry_id: `${kind}:${slug}:${randomUUID()}`,
+        event: kind,
+        subject_slug: slug,
+        content_hash,
+        dependency_hash,
+        effective_hash,
+        output_hashes: [content_hash],
+        started_at: now,
+        finished_at: now,
+    });
+    return { content_hash, dependency_hash, effective_hash };
+}
+/** The canonical identity of an agent definition. PURE + deterministic from the def, so
+ *  the same input always yields the same effective_hash (cross-machine interoperable). */
+export function agentIdentity(def) {
+    const content_hash = sha256Hex(canonJson(def)); // canonical JSON → stable across formatting
+    const dependency_hash = EMPTY_DEPENDENCY_HASH; // v0: dependency closure (referenced types) is the next layer
+    const effective_hash = effectiveHash(content_hash, dependency_hash);
+    return { content_hash, dependency_hash, effective_hash };
+}
+/** Validate, hash, and (when a genome_dir is provided) PERSIST + LEDGER-SEAL. Without a
+ *  genome_dir the identity is still computed + returned (validation path); with one, the
+ *  agent is written to agents/<slug>.json and the effective_hash is recorded in the
+ *  append-only ledger — the only way an agent enters the substrate of truth. */
+export function sealAgentDefinition(def, ledger, genome_dir) {
+    const agent = defineAgent(def); // composition-rule validation (throws on illegal pipeline)
+    const { content_hash, dependency_hash, effective_hash } = agentIdentity(def);
+    if (genome_dir) {
+        // #218 — seal before write (see sealDefinition).
+        const now = new Date().toISOString();
+        ledger.append({
+            kind: "genome_mutation",
+            schema_version: LEDGER_SCHEMA_VERSION,
+            entry_id: `agent_define:${def.slug}:${randomUUID()}`,
+            event: "agent_define",
+            subject_slug: def.slug,
+            content_hash,
+            dependency_hash,
+            effective_hash, // the agent's identity claim
+            output_hashes: [content_hash],
+            started_at: now,
+            finished_at: now,
+        });
+        writeGenomeFileVersioned(genome_dir, "agents", def.slug, JSON.stringify(def, null, 2) + "\n");
+    }
+    return { agent, content_hash, dependency_hash, effective_hash };
+}
+/** Persist a skill as the LOADABLE PACKAGE the loader reads — skills/<slug>/{meta.json, skill.mjs?,
+ *  skill.md?, fixtures/*.json} — not a flat skills/<slug>.json the loader skips. The content fields
+ *  (`code` → skill.mjs, `md` → skill.md) and each fixture become their own files; meta.json holds the
+ *  remaining declared fields. Identity is hashed over the full canonical def, so the content_hash is
+ *  stable regardless of the on-disk split. Closes the skill_define → reload roundtrip (audit E).
+ *  The caller MUST pre-validate completeness (≥1 fixture + a code/reasoning half) — the loader
+ *  hard-fails an incomplete package, so an incomplete write would crash the next genome load. */
+export function sealSkillPackage(def, ledger, genome_dir) {
+    const content_hash = sha256Hex(canonJson(def));
+    const dependency_hash = EMPTY_DEPENDENCY_HASH;
+    const effective_hash = effectiveHash(content_hash, dependency_hash);
+    if (genome_dir) {
+        // #218 — seal before write. This helper is the worst offender in the reverse order: it
+        // materialises meta.json, skill.mjs, skill.md and every fixture before appending, so a
+        // failed append left a PARTIAL package plus no identity.
+        const sealedAt = new Date().toISOString();
+        ledger.append({
+            kind: "genome_mutation",
+            schema_version: LEDGER_SCHEMA_VERSION,
+            entry_id: `skill_define:${def.slug}:${randomUUID()}`,
+            event: "skill_define",
+            subject_slug: def.slug,
+            content_hash,
+            dependency_hash,
+            effective_hash,
+            output_hashes: [content_hash],
+            started_at: sealedAt,
+            finished_at: sealedAt,
+        });
+        const pkgDir = join(genome_dir, "skills", def.slug);
+        mkdirSync(pkgDir, { recursive: true });
+        const { fixtures, code, md, ...meta } = def;
+        writeFileSync(join(pkgDir, "meta.json"), JSON.stringify(meta, null, 2) + "\n");
+        if (typeof code === "string")
+            writeFileSync(join(pkgDir, "skill.mjs"), code);
+        if (typeof md === "string")
+            writeFileSync(join(pkgDir, "skill.md"), md);
+        if (Array.isArray(fixtures)) {
+            const fxDir = join(pkgDir, "fixtures");
+            mkdirSync(fxDir, { recursive: true });
+            fixtures.forEach((fx, i) => writeFileSync(join(fxDir, `fixture-${String(i + 1).padStart(3, "0")}.json`), JSON.stringify(fx, null, 2) + "\n"));
+        }
+    }
+    return { content_hash, dependency_hash, effective_hash };
+}
+//# sourceMappingURL=genome_writer.js.map

package/dist/src/genome_writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genome_writer.js","sourceRoot":"","sources":["../../src/genome_writer.ts"],"names":[],"mappings":"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"}

package/dist/src/gig_song.d.ts

@@ -0,0 +1,29 @@
+import { type Tone, type Chord, type Resolution, type Arity } from "./tones.js";
+export type ToneMap = Readonly<Record<string, Tone>>;
+export declare const DEFAULT_TONE_MAP: ToneMap;
+export interface SongStep {
+    agent_slug: string;
+    primitives: readonly string[];
+    phase?: string | undefined;
+}
+export interface AgentChord {
+    agent_slug: string;
+    chord: Chord;
+    arity: Arity;
+    consonance: number;
+}
+export interface GigSong {
+    steps: AgentChord[];
+    progression: Chord[];
+    resolution: Resolution;
+}
+/** Sound one agent: its primitives → a chord (unknown primitives are dropped). */
+export declare function stepToChord(step: SongStep, toneOf?: ToneMap): Chord;
+/** Encode an ordered gig trajectory into a song (progression + resolution). */
+export declare function gigToSong(steps: readonly SongStep[], toneOf?: ToneMap): GigSong;
+/** Render a gig-song to a JSONG observation tick-log — one tick per agent-chord.
+ *  Minimal v0 state packing: index 4 (the C/coherence slot) carries the chord's
+ *  consonance; score = consonance; slug = agent. The full 59-dim fingerprint
+ *  packing is the research-lane concern, deferred — this stays honest about what
+ *  it fills. */
+export declare function songToJsong(song: GigSong, gigId?: Uint8Array): Uint8Array;

package/dist/src/gig_song.js

@@ -0,0 +1,56 @@
+// gig_song — "the sim plays the gig." Encodes a gig's trajectory (its ordered
+// agents, each composed of cognitive primitives) into a chord PROGRESSION, then
+// renders that to a JSONG observation tick-log. This is the generative bridge:
+// engine (gigs/agents/primitives/outputs) → song-substrate (tones/chords) → jsong.
+//
+// The primitive→tone map is a PARAMETER, not a baked-in truth — the song is one
+// read of three, and which tone a primitive sounds as is a spec decision, passed
+// in (DEFAULT_TONE_MAP is a sensible diatonic default, overridable). Output is
+// STRUCTURE (progression + resolution + per-step chords), never a scalar verdict.
+import { chordConsonance, chordArity, resolve } from "./tones.js";
+import { writeAll, emptyState, ROLE_OBSERVATION, FLAG_MUSICAL } from "./jsong.js";
+export const DEFAULT_TONE_MAP = {
+    SENSE: 0, INTERPRET: 2, JUDGE: 4, PLAN: 5, CREATE: 7, VERIFY: 9,
+};
+/** Sound one agent: its primitives → a chord (unknown primitives are dropped). */
+export function stepToChord(step, toneOf = DEFAULT_TONE_MAP) {
+    const tones = [];
+    for (const p of step.primitives) {
+        const t = toneOf[p];
+        if (typeof t === "number")
+            tones.push(t);
+    }
+    return tones;
+}
+/** Encode an ordered gig trajectory into a song (progression + resolution). */
+export function gigToSong(steps, toneOf = DEFAULT_TONE_MAP) {
+    const stepsOut = steps.map((s) => {
+        const chord = stepToChord(s, toneOf);
+        return { agent_slug: s.agent_slug, chord, arity: chordArity(chord), consonance: chordConsonance(chord) };
+    });
+    const progression = stepsOut.map((s) => s.chord);
+    return { steps: stepsOut, progression, resolution: resolve(progression) };
+}
+/** Render a gig-song to a JSONG observation tick-log — one tick per agent-chord.
+ *  Minimal v0 state packing: index 4 (the C/coherence slot) carries the chord's
+ *  consonance; score = consonance; slug = agent. The full 59-dim fingerprint
+ *  packing is the research-lane concern, deferred — this stays honest about what
+ *  it fills. */
+export function songToJsong(song, gigId = new Uint8Array(16)) {
+    const header = { version: 0, gig_id: gigId, agent_id: new Uint8Array(16), start_us: 0n };
+    const ticks = song.steps.map((s, i) => {
+        const state = emptyState();
+        state[4] = s.consonance; // state_59[4] = C (coherence) per the JSONG canonical order
+        return {
+            tick_idx: i,
+            delta_us: 0,
+            role: ROLE_OBSERVATION,
+            flags: FLAG_MUSICAL,
+            state_59: state,
+            score: s.consonance,
+            slug: s.agent_slug,
+        };
+    });
+    return writeAll(header, ticks);
+}
+//# sourceMappingURL=gig_song.js.map

package/dist/src/gig_song.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gig_song.js","sourceRoot":"","sources":["../../src/gig_song.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,mFAAmF;AACnF,EAAE;AACF,gFAAgF;AAChF,iFAAiF;AACjF,+EAA+E;AAC/E,kFAAkF;AAElF,OAAO,EAAyB,eAAe,EAAE,UAAU,EAAE,OAAO,EAA+B,MAAM,YAAY,CAAC;AACtH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAoC,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKpH,MAAM,CAAC,MAAM,gBAAgB,GAAY;IACvC,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;CAChE,CAAC;AAwBF,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAC,IAAc,EAAE,SAAkB,gBAAgB;IAC5E,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,SAAS,CAAC,KAA0B,EAAE,SAAkB,gBAAgB;IACtF,MAAM,QAAQ,GAAiB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7C,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACrC,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;IAC3G,CAAC,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED;;;;gBAIgB;AAChB,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,QAAoB,IAAI,UAAU,CAAC,EAAE,CAAC;IAC/E,MAAM,MAAM,GAAe,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,UAAU,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACrG,MAAM,KAAK,GAAiB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAClD,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,4DAA4D;QACrF,OAAO;YACL,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,CAAC;YACX,IAAI,EAAE,gBAAgB;YACtB,KAAK,EAAE,YAAY;YACnB,QAAQ,EAAE,KAAK;YACf,KAAK,EAAE,CAAC,CAAC,UAAU;YACnB,IAAI,EAAE,CAAC,CAAC,UAAU;SACnB,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACjC,CAAC"}

package/dist/src/gig_tracker.d.ts

@@ -0,0 +1,54 @@
+import type { GigProgressEvent, BudgetState } from "./runtime.js";
+import type { GigUsage } from "./ledger.js";
+export interface GigChairState {
+    role: string;
+    phase: string;
+    status: "running" | "complete" | "failed";
+    producer?: string;
+    output_types?: string[];
+    duration_ms?: number;
+    tool_calls: string[];
+    error?: string;
+}
+/** The outcomes a tracked gig can reach. `aborted` is first-class (#251): without it a
+ *  cancelled run could only surface as `failed` carrying a kill-shaped error string —
+ *  indistinguishable from a genuine crash, which is the opposite of what an operator who
+ *  just cancelled it needs to see. */
+export type GigStatus = "running" | "complete" | "failed" | "aborted";
+export interface GigRunState {
+    gig_id: string;
+    standard_slug: string;
+    status: GigStatus;
+    started_at: string;
+    finished_at?: string;
+    phases_total: number;
+    current_phase?: string;
+    phases_seen: string[];
+    chairs: Record<string, GigChairState>;
+    outputs_count: number;
+    run_fingerprint?: string;
+    genome_hash?: string;
+    error?: string;
+    usage?: GigUsage;
+    budget_state?: BudgetState;
+    controller?: AbortController | undefined;
+    /** An operator asked for this run to stop (set even when no controller could be reached). */
+    abort_requested?: boolean;
+    /** Why. Surfaced by gig_monitor so `aborted` reads as a decision, not a mystery. */
+    abort_reason?: string;
+}
+export declare function newGigRun(gig_id: string, standard_slug: string, phases_total: number, now: string): GigRunState;
+export declare function applyGigProgress(state: GigRunState, ev: GigProgressEvent): void;
+/**
+ * Retention bound for the live-run map (#253). `gig_runs` had three call sites and no
+ * `delete` — every dispatch added an entry retained for the server's lifetime, including
+ * per-chair `tool_calls` arrays that grow per call.
+ *
+ * Only SETTLED runs are eligible: a running gig's entry holds the AbortController, so
+ * pruning one would silently make that gig uncancellable — trading a memory leak for the
+ * very bug #249 is about. Oldest-settled-first, so the runs an operator is most likely to
+ * ask about survive. Returns how many were dropped.
+ */
+export declare const DEFAULT_GIG_RUN_RETENTION = 200;
+export declare function pruneGigRuns(runs: Map<string, GigRunState>, max?: number): number;
+export declare function gigEventLogLine(gig_id: string, ev: GigProgressEvent): string | null;

package/dist/src/gig_tracker.js

@@ -0,0 +1,109 @@
+// Live gig state — the coltrane-layer observability the async dispatcher exposes.
+//
+// gig_dispatch (async) starts a gig in the background and returns its id immediately; the
+// runtime fires GigProgressEvents as it walks the phase graph; this module folds those into
+// a GigRunState that gig_monitor reads. State is in-memory (per server lifetime): a restart
+// drops in-flight tracking — acceptable for v0, and a restart mid-gig is its own problem.
+export function newGigRun(gig_id, standard_slug, phases_total, now) {
+    return {
+        gig_id, standard_slug, status: "running", started_at: now,
+        phases_total, phases_seen: [], chairs: {}, outputs_count: 0,
+    };
+}
+// Fold one progress event into the state (mutating). Pure w.r.t. side effects — file/stderr
+// teeing is the caller's job; this only updates the queryable snapshot.
+export function applyGigProgress(state, ev) {
+    switch (ev.type) {
+        case "phase_start":
+            state.current_phase = ev.phase;
+            if (!state.phases_seen.includes(ev.phase))
+                state.phases_seen.push(ev.phase);
+            for (const role of ev.roles) {
+                if (!state.chairs[role])
+                    state.chairs[role] = { role, phase: ev.phase, status: "running", tool_calls: [] };
+            }
+            break;
+        case "chair_start":
+            state.chairs[ev.role] = { role: ev.role, phase: ev.phase, status: "running", producer: ev.producer, tool_calls: [] };
+            break;
+        case "agent_event": {
+            const c = state.chairs[ev.role];
+            if (c && ev.event.type === "tool_use" && ev.event.tool)
+                c.tool_calls.push(ev.event.tool);
+            break;
+        }
+        case "chair_complete": {
+            const c = state.chairs[ev.role] ?? (state.chairs[ev.role] = { role: ev.role, phase: ev.phase, status: "running", tool_calls: [] });
+            c.status = "complete";
+            c.producer = ev.producer;
+            c.output_types = ev.output_types;
+            c.duration_ms = ev.duration_ms;
+            state.outputs_count += ev.output_types.length;
+            break;
+        }
+        case "chair_failed": {
+            const c = state.chairs[ev.role] ?? (state.chairs[ev.role] = { role: ev.role, phase: ev.phase, status: "running", tool_calls: [] });
+            c.status = "failed";
+            c.error = ev.error;
+            break;
+        }
+        case "gig_complete":
+            state.outputs_count = ev.outputs;
+            break;
+        case "gig_failed":
+            state.error = ev.error;
+            break;
+        case "gig_aborted":
+            // A cancelled run is not a crashed run. Recording it as its own terminal status is what
+            // lets gig_monitor answer "did my abort land?" instead of showing a kill-shaped error.
+            state.status = "aborted";
+            state.abort_reason = ev.reason;
+            state.finished_at ??= new Date().toISOString();
+            break;
+    }
+}
+/**
+ * Retention bound for the live-run map (#253). `gig_runs` had three call sites and no
+ * `delete` — every dispatch added an entry retained for the server's lifetime, including
+ * per-chair `tool_calls` arrays that grow per call.
+ *
+ * Only SETTLED runs are eligible: a running gig's entry holds the AbortController, so
+ * pruning one would silently make that gig uncancellable — trading a memory leak for the
+ * very bug #249 is about. Oldest-settled-first, so the runs an operator is most likely to
+ * ask about survive. Returns how many were dropped.
+ */
+export const DEFAULT_GIG_RUN_RETENTION = 200;
+export function pruneGigRuns(runs, max = DEFAULT_GIG_RUN_RETENTION) {
+    const settled = [...runs.values()].filter((s) => s.status !== "running");
+    if (settled.length <= max)
+        return 0;
+    const at = (s) => s.finished_at ?? s.started_at;
+    settled.sort((a, b) => (at(a) < at(b) ? -1 : at(a) > at(b) ? 1 : 0));
+    const drop = settled.slice(0, settled.length - max);
+    for (const s of drop)
+        runs.delete(s.gig_id);
+    return drop.length;
+}
+// A compact one-line summary of an event for the stderr/MCP log (skips per-token noise).
+export function gigEventLogLine(gig_id, ev) {
+    const base = { t: new Date().toISOString(), gig: gig_id };
+    switch (ev.type) {
+        case "phase_start": return JSON.stringify({ ...base, ev: "phase_start", phase: ev.phase, chairs: ev.roles });
+        case "chair_start": return JSON.stringify({ ...base, ev: "chair_start", phase: ev.phase, role: ev.role, producer: ev.producer });
+        case "chair_complete": return JSON.stringify({ ...base, ev: "chair_complete", role: ev.role, sealed: ev.output_types, ms: ev.duration_ms });
+        case "chair_failed": return JSON.stringify({ ...base, ev: "chair_failed", role: ev.role, error: ev.error });
+        // #241 — a dangling (non-required) skill binding. Surfaced live because an unskilled run
+        // is otherwise indistinguishable from a skilled one: same genome_hash, run_fingerprint,
+        // content_sha. This log line is the only place the difference shows up while it happens.
+        case "skills_unresolved": return JSON.stringify({ ...base, ev: "skills_unresolved", phase: ev.phase, role: ev.role, agent: ev.agent, missing: ev.missing });
+        case "gig_complete": return JSON.stringify({ ...base, ev: "gig_complete", outputs: ev.outputs });
+        case "gig_failed": return JSON.stringify({ ...base, ev: "gig_failed", error: ev.error });
+        case "gig_aborted": return JSON.stringify({ ...base, ev: "gig_aborted", reason: ev.reason });
+        case "agent_event":
+            // only surface tool calls live, not every assistant token
+            return ev.event.type === "tool_use"
+                ? JSON.stringify({ ...base, ev: "tool_use", role: ev.role, tool: ev.event.tool })
+                : null;
+    }
+}
+//# sourceMappingURL=gig_tracker.js.map

package/dist/src/gig_tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gig_tracker.js","sourceRoot":"","sources":["../../src/gig_tracker.ts"],"names":[],"mappings":"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"}

package/dist/src/harmonic_validation.d.ts

@@ -0,0 +1,11 @@
+export interface SongReading {
+    resolution: number;
+    tonic: number;
+    density: number;
+}
+export declare function songChannel(r: SongReading): number[];
+export declare function coupling(a: number[], b: number[]): number;
+export declare function channelCoupling(channels: Record<string, number[]>): Array<{
+    pair: [string, string];
+    coupling: number;
+}>;

package/dist/src/harmonic_validation.js

@@ -0,0 +1,35 @@
+// The song channel — ONE of three reads (score / output / song). It is a TENSOR, never a
+// verdict: validation does not collapse to a scalar "truth." The signal is cross-channel
+// COUPLING — real = the channels stay coupled (move together); illusion = they decouple
+// (each looks internally fine, but they diverge from one another). This module produces the
+// song channel's reading as a vector + the coupling structure. It does NOT judge, and never
+// reduces the channels to one answer.
+// the song channel as a vector — its slice of the validation tensor. never a verdict.
+export function songChannel(r) {
+    return [r.resolution, r.tonic, r.density];
+}
+// pairwise coupling between two channel vectors (cosine: 1 = fully coupled, 0 = decoupled).
+// a primitive — the SIGNAL is the full set of pairwise couplings preserved as structure,
+// never reduced to one number.
+export function coupling(a, b) {
+    const dot = a.reduce((s, x, i) => s + x * (b[i] ?? 0), 0);
+    const na = Math.sqrt(a.reduce((s, x) => s + x * x, 0));
+    const nb = Math.sqrt(b.reduce((s, x) => s + x * x, 0));
+    return na === 0 || nb === 0 ? 0 : dot / (na * nb);
+}
+// the coupling STRUCTURE across channels — every pair, preserved. an illusion shows as a
+// pair that DECOUPLES while each channel stays internally fine; a real result keeps every
+// pair coupled. returns the structure, never a collapsed verdict.
+export function channelCoupling(channels) {
+    const names = Object.keys(channels);
+    const out = [];
+    for (let i = 0; i < names.length; i++) {
+        for (let j = i + 1; j < names.length; j++) {
+            const a = names[i];
+            const b = names[j];
+            out.push({ pair: [a, b], coupling: coupling(channels[a], channels[b]) });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=harmonic_validation.js.map

package/dist/src/harmonic_validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harmonic_validation.js","sourceRoot":"","sources":["../../src/harmonic_validation.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,yFAAyF;AACzF,wFAAwF;AACxF,4FAA4F;AAC5F,4FAA4F;AAC5F,sCAAsC;AAQtC,sFAAsF;AACtF,MAAM,UAAU,WAAW,CAAC,CAAc;IACxC,OAAO,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,4FAA4F;AAC5F,yFAAyF;AACzF,+BAA+B;AAC/B,MAAM,UAAU,QAAQ,CAAC,CAAW,EAAE,CAAW;IAC/C,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1D,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvD,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvD,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,yFAAyF;AACzF,0FAA0F;AAC1F,kEAAkE;AAClE,MAAM,UAAU,eAAe,CAC7B,QAAkC;IAElC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,GAAG,GAAwD,EAAE,CAAC;IACpE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YACpB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YACpB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAE,EAAE,QAAQ,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/src/hooks.d.ts

@@ -0,0 +1,27 @@
+import type { ServerDeps, ToolResult } from "./server.js";
+/** What a hook sees about the call it's wrapping. `args` is the CURRENT args — i.e. whatever a prior
+ *  before-hook rewrote them to — so a later hook (and the impl) act on the threaded value. */
+export interface ToolCallContext {
+    readonly slug: string;
+    readonly args: Record<string, unknown>;
+    readonly deps: ServerDeps;
+    /** the engine's own computed approval flag, for the hook to consult — NOT enforced by the engine. */
+    readonly requires_approval: boolean;
+}
+/** A before-hook either lets the call proceed (optionally rewriting args) or halts it with a result.
+ *  `halt` means "the call never ran": the impl, the remaining before-hooks, and ALL after-hooks are
+ *  skipped, and `result` is returned verbatim. */
+export type PreOutcome = {
+    action: "continue";
+    args?: Record<string, unknown>;
+} | {
+    action: "halt";
+    result: ToolResult;
+};
+/** A pre/post interceptor on dispatchTool. `name` is for diagnostics/telemetry only. A hook that
+ *  throws fails the call CLOSED (a gate that errors must never let the call through). */
+export interface ToolHook {
+    readonly name: string;
+    before?(ctx: ToolCallContext): Promise<PreOutcome> | PreOutcome;
+    after?(ctx: ToolCallContext, result: ToolResult): Promise<ToolResult> | ToolResult;
+}

package/dist/src/hooks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.js.map

package/dist/src/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/hooks.ts"],"names":[],"mappings":""}