@eir-labs/coltrane 0.10.0 → 0.11.0

package/dist/src/server.js

@@ -6,15 +6,19 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+// The wire names of the reserved relay↔child methods (restart guard, venue/8). Defined by the
+// relay — the relay owns the conversation — and answered by the child handlers registered below.
+import { RUNNING_GIGS_METHOD, ABORT_FOR_RESTART_METHOD } from "./server_relay.js";
 import { MCP_TOOLS, requiresApproval, AGENT_STATUS_ORDER, STANDARD_STATUS_ORDER, SKILL_STATUS_ORDER, checkPromotion, PromotionError, } from "./mcp.js";
 import { loadRegistry, domainTypeDefect } from "./registry.js";
 import { resolveGenome } from "./loader.js";
-import { SkillSchema, AgentSchema, StandardSchema, DomainTypeSchema, ChartSchema, VenueSchema, venueDefect } from "./genome_schema.js";
+import { SkillSchema, AgentSchema, StandardSchema, DomainTypeSchema, ChartSchema, VenueSchema, VenueObjectSchema, venueDefect } from "./genome_schema.js";
 import { composeChart, runChart, chartHash, chartEntrySeedTypes, dispatchTarget, } from "./chart.js";
 import { runSkillFixtures, executeSkill, loadFixtures } from "./skill_subprocess.js";
 import { evolveSkill } from "./skills.js";
 import { sealAgentDefinition, sealDefinition, sealSkillPackage, recordIdentity } from "./genome_writer.js";
-import { createOutputStore, defaultOutputsPersistDir, } from "./outputs.js";
+import { createOutputStore, defaultOutputsPersistDir, performanceRoot, } from "./outputs.js";
 import { createOutputMirror, defaultMirrorDir, outputPreview, mirrorStorageRef } from "./output_mirror.js";
 import { FileLedger, LedgerError, LEDGER_SCHEMA_VERSION, defaultLedgerPath, } from "./ledger.js";
 import { sealDrill } from "./seal_drill.js";
@@ -22,8 +26,10 @@ import { standardSimulate } from "./simulate.js";
 import { runGig, BudgetExhausted, GigAborted, ResumeRefused, partialGigUsage, partialBudgetState } from "./runtime.js";
 import { createCheckpointStore, createReuseStore } from "./reuse.js";
 import { makeClaudeInvoker, killLiveChairChildren } from "./claude_invoker.js";
+import { dockerComposeRealizer } from "./venue_realizer.js";
 import { isDepth, DEPTHS } from "./pricing.js";
 import { ENGINE_MCP_SERVER } from "./tool_providers.js";
+import { gigScopeRefusal, missingWorkerEnv, } from "./venue_credential.js";
 import { composeStandard, defineAgent, CompositionError } from "./composition.js";
 import { PRIMITIVE_OUTPUT_TYPE } from "./core_types.js";
 import { proposeTypeChange } from "./type_versioning.js";
@@ -526,9 +532,13 @@ async function runImpl(slug, args, deps, approval) {
                         throw new Error(verdict.reason ??
                             `output rejected: "${domain_type || core_type}" did not satisfy its output contract`);
                     }
+                    // Name what did NOT happen. Validation genuinely succeeded (ok:true, validated:true), but
+                    // the runtime is the one sealer — this branch does NOT persist. A truthful compose chair
+                    // once read `validated` as `sealed` and filed a false completion; `sealed:false` makes
+                    // VALIDATED unmistakable from SEALED so no reader can launder one into the other.
                     return {
                         ok: true, requires_approval: approval,
-                        data: { validated: true, validation_result: { valid: true } },
+                        data: { validated: true, sealed: false, validation_result: { valid: true } },
                     };
                 }
                 const rec = deps.outputs.write({
@@ -585,6 +595,23 @@ async function runImpl(slug, args, deps, approval) {
                 // player; an unseated one produces a gig that can only fail at genome load.
                 const actingFor = args["acting_for"] === undefined || args["acting_for"] === null ? undefined : String(args["acting_for"]);
                 void actingFor; // forwarded to the queue seam via `args` below; named here to be legible.
+                // WHERE it plays, as distinct from what it plays. This is a CEILING, and the whole design is
+                // fail-closed — so the one outcome the contract forbids is proceeding as if no venue was
+                // asked. It is threaded into BOTH runGig calls below (the sync and async paths) via the same
+                // conditional-spread trio the chart path uses (server.ts:935-941), so `runGig`'s own venue
+                // block either realizes the room or refuses fail-closed. It used to be read into this local
+                // and then DISCARDED (`void venue`, with a comment claiming the queue seam forwarded it — it
+                // did not for a local run): gig a77f6f7f dispatched room-probe-v1 with a named venue and got
+                // NO room, NO refusal, and a 'complete' status whose output was byte-identical to the
+                // venue-less control. An unnamed gig carries `undefined` here and is threaded to nothing —
+                // the venue-less path stays byte-identical.
+                const venue = args["venue"] === undefined || args["venue"] === null ? undefined : String(args["venue"]);
+                // WHAT REPOSITORY it works on, as distinct from WHERE it plays. The SUBJECT of the run, named
+                // EXPLICITLY at dispatch and threaded to runGig (the same conditional-spread trio venue uses)
+                // so the realized room's workspace is populated with THIS repository — never process.cwd() or
+                // any ambient host path. A venue is at rest and serves many repositories, so the repository
+                // belongs on the RUN, not the room. Absent → the room declines to populate (empty workspace).
+                const repoUrl = args["repo_url"] === undefined || args["repo_url"] === null ? undefined : String(args["repo_url"]);
                 const target = dispatchTarget({
                     standard_slug: args["standard_slug"] === undefined || args["standard_slug"] === null ? undefined : String(args["standard_slug"]),
                     chart_slug: args["chart_slug"] === undefined || args["chart_slug"] === null ? undefined : String(args["chart_slug"]),
@@ -704,10 +731,18 @@ async function runImpl(slug, args, deps, approval) {
                 if (reuseOn && !deps.reuse) {
                     return { ok: false, requires_approval: approval, error: `gig_dispatch: reuse was requested but this server has no reuse store wired` };
                 }
+                // #20 — the CLI signals an OMITTED --input as a boolean on args, so a human-only resume can
+                // inherit the checkpoint's gig_input_sha instead of drifting to sha256('{}') and refusing.
+                // It is advertised in gig_dispatch's input_schema (src/mcp.ts): a control the handler reads
+                // must be discoverable by a caller (#234). Only true when the caller stated no payload; an
+                // explicit `{}` is a supplied value and leaves this false, so a disagreeing payload still
+                // gates (see src/runtime.ts).
+                const gigInputOmitted = args["gig_input_omitted"] === true;
                 const reuseWiring = {
                     ...(deps.checkpoints ? { checkpoints: deps.checkpoints } : {}),
                     ...(resumeArg !== undefined ? { resume_from: resumeArg } : {}),
                     ...(reuseOn && deps.reuse ? { reuse: deps.reuse } : {}),
+                    ...(gigInputOmitted ? { gig_input_omitted: true } : {}),
                 };
                 // ── the human seat's door ────────────────────────────────────────────────────────
                 // A chair marked `human: true` parks the run until its incumbent's verdict arrives
@@ -758,6 +793,21 @@ async function runImpl(slug, args, deps, approval) {
                         outputs: deps.outputs, ledger: deps.ledger, invoke: deps.invoke,
                         model_version: deps.model_version, skills: deps.skills, skill_dirs: deps.skill_dirs, evals: deps.evals, budget,
                         toolProviders: deps.toolProviders, mcpServerConfigs: deps.mcpServerConfigs, // each movement's preflight resolves against the invoker's environment
+                        // THE ROOM THE ARRANGEMENT NAMED, carried into the run.
+                        //
+                        // Without this the venue branch in `runGig` is unreachable in production: `composeChart`
+                        // checks the ceiling at AUTHORING time (R10) and `deps.venues` is passed here only so it
+                        // can, but the chart's own `venue` was never threaded into the run deps — so no shipped
+                        // caller ever set `deps.venue`, and `resolveAndRealize` ran for tests alone. A room that
+                        // is checked when the chart is written and forgotten when it is performed is a ceiling
+                        // on paper.
+                        ...(chartDef.venue ? { venue: chartDef.venue } : {}),
+                        ...(deps.venues ? { venues: deps.venues } : {}),
+                        // The substrate seam, carried beside the room the arrangement named: when that room
+                        // declares mcp_servers, runGig stands it up on this realizer and threads its transports
+                        // onto each chair's spawn. Absent = the substrate is skipped (server-less venues, or a
+                        // bare deps without a realizer wired).
+                        ...(deps.venueRealizer ? { venueRealizer: deps.venueRealizer } : {}),
                         ...(depth ? { depth } : {}), ...reuseWiring, ...humanWiring,
                     };
                     /** The ARRANGEMENT's manifest. A chart has no single genome_hash or run_fingerprint — it
@@ -916,6 +966,15 @@ async function runImpl(slug, args, deps, approval) {
                             outputs: deps.outputs, ledger: deps.ledger, invoke: deps.invoke,
                             model_version: deps.model_version, skills: deps.skills, skill_dirs: deps.skill_dirs, evals: deps.evals, budget,
                             toolProviders: deps.toolProviders, mcpServerConfigs: deps.mcpServerConfigs, // dispatch preflight resolves against the invoker's environment
+                            // THE ROOM THIS DISPATCH NAMED, threaded so runGig realizes it or refuses fail-closed —
+                            // the same conditional-spread trio the chart path uses (server.ts:935-941). `venue` is
+                            // threaded only when non-empty so runGig's `deps.venue !== undefined` gate is never
+                            // tripped by an absent one; `venues`/`venueRealizer` come from bootstrap (ServerDeps).
+                            ...(venue ? { venue } : {}),
+                            ...(deps.venues ? { venues: deps.venues } : {}),
+                            ...(deps.venueRealizer ? { venueRealizer: deps.venueRealizer } : {}),
+                            // The repository the run names, threaded so runGig populates the room's tree from it.
+                            ...(repoUrl ? { repoUrl } : {}),
                             ...(depth ? { depth } : {}), ...reuseWiring, ...humanWiring,
                         });
                         return {
@@ -1002,6 +1061,15 @@ async function runImpl(slug, args, deps, approval) {
                     outputs: deps.outputs, ledger: deps.ledger, invoke: deps.invoke,
                     model_version: deps.model_version, skills: deps.skills, skill_dirs: deps.skill_dirs, evals: deps.evals, budget,
                     toolProviders: deps.toolProviders, mcpServerConfigs: deps.mcpServerConfigs, // dispatch preflight resolves against the invoker's environment
+                    // Same venue trio as the sync path above — the DEFAULT dispatch mode must honour a named
+                    // room too, or the fix covers only the deterministic wait:true test path and leaves the
+                    // path the product actually dispatches through discarding the venue.
+                    ...(venue ? { venue } : {}),
+                    ...(deps.venues ? { venues: deps.venues } : {}),
+                    ...(deps.venueRealizer ? { venueRealizer: deps.venueRealizer } : {}),
+                    // Same repository wire as the sync path above — the default async dispatch must populate a
+                    // named room's tree too, not only the deterministic wait:true path.
+                    ...(repoUrl ? { repoUrl } : {}),
                     gig_id: gigId, onProgress, signal: controller.signal, ...(depth ? { depth } : {}), ...reuseWiring, ...humanWiring,
                 });
                 // A REFUSED resume must be answered in THIS reply, not discovered later by polling. The
@@ -1104,8 +1172,22 @@ async function runImpl(slug, args, deps, approval) {
                 // Prefer the live state map (async runs). Falls back to the ledger/outputs read for a
                 // synchronously-completed gig (or one from a prior server lifetime, not in the map).
                 const live = deps.gig_runs?.get(gid);
+                // A MOVEMENT SEALS UNDER ITS OWN ID, so a raw `===` can never match a chart's records: a
+                // movement runs as `<performance>.m.<movement_id>` (src/chart.ts `movementGigId`), and the
+                // id an operator holds — the one `gig_dispatch` returned — is the performance's. Resolve
+                // through `performanceRoot`, which src/outputs.ts:142-147 declares the ONE owner of that
+                // scheme, rather than re-deriving the separator here; that second copy is the drift the
+                // note there warns about, and it is what `output_trace` already had to fix (#248,
+                // tests/cross_movement_trace.test.ts). A plain gig id is its own root, so a
+                // single-standard run is unmoved, and a shared PREFIX is not a root — the infix carries
+                // dots on both sides precisely so a uuid cannot be mistaken for a parent of another.
+                // BOTH READINGS RESOLVE, and the exact match is not redundant: asking about a MOVEMENT's
+                // own id must keep naming its own records, and `performanceRoot(<perf>.m.<mv>)` is
+                // `<perf>`, which would not equal the movement id the caller asked about. A root-only
+                // predicate trades one false negative for another.
+                const ofPerformance = (o) => o.gig_id === gid || performanceRoot(o.gig_id) === gid;
                 if (live) {
-                    const outs = deps.outputs.all().filter((o) => o.gig_id === gid);
+                    const outs = deps.outputs.all().filter(ofPerformance);
                     return {
                         ok: true, requires_approval: approval,
                         data: {
@@ -1141,7 +1223,10 @@ async function runImpl(slug, args, deps, approval) {
                         },
                     };
                 }
-                const outs = deps.outputs.all().filter((o) => o.gig_id === gid);
+                // The non-live path is the DAMAGING one: `status` and `phases_complete` below are derived
+                // from this list, so an unresolved chart id did not merely omit the records — it answered
+                // "unknown" and "0 phases" about a performance that had demonstrably done work.
+                const outs = deps.outputs.all().filter(ofPerformance);
                 const entry = deps.ledger.query({ kind: "gig", gig_id: gid })[0];
                 return {
                     ok: true, requires_approval: approval,
@@ -1201,7 +1286,12 @@ async function runImpl(slug, args, deps, approval) {
                     // plain string slugs. Now: when an entry is a string or a slug-only
                     // object, look it up in deps.agents (populated by bootstrap from the
                     // loaded genome). Full Agent objects are passed through unchanged.
-                    const sAgentsRaw = args["agents"] ?? [];
+                    // The input_schema advertises BOTH keys: `agents` is the compose-input shape; `agent_slugs`
+                    // is the shape the PERSISTED standards/<slug>.json file carries (written at line ~1413).
+                    // Reading only `agents` made `agent_slugs` a silent no-op that failed via the misleading
+                    // "agent not found" error — and broke the read-file/re-compose round-trip. Fall back to
+                    // `agent_slugs` when `agents` is absent so the documented parameter actually composes.
+                    const sAgentsRaw = args["agents"] ?? args["agent_slugs"] ?? [];
                     const sAgents = sAgentsRaw.map((a) => {
                         if (typeof a === "string") {
                             const loaded = deps.agents?.get(a);
@@ -1313,6 +1403,20 @@ async function runImpl(slug, args, deps, approval) {
                     ...(args["credential_surface"] !== undefined ? { credential_surface: args["credential_surface"] } : {}),
                     ...(args["lifecycle"] !== undefined ? { lifecycle: args["lifecycle"] } : {}),
                     ...(args["responsible_chair"] !== undefined ? { responsible_chair: args["responsible_chair"] } : {}),
+                    // The worker-contract fields, passed through by the same rule: only what was stated, so the
+                    // schema keeps ownership of every default (an unstated `mcp_servers`/`devices`/`architectures`
+                    // is the EMPTY list, an unstated `substrate`/`floor`/`max_concurrent_chairs` the deployment
+                    // default). Read here so a room authored through this tool actually carries its substrate,
+                    // and so the advertised schema and the handler stay one statement of the same fact (#234).
+                    ...(args["substrate"] !== undefined ? { substrate: args["substrate"] } : {}),
+                    ...(args["mcp_servers"] !== undefined ? { mcp_servers: args["mcp_servers"] } : {}),
+                    ...(args["devices"] !== undefined ? { devices: args["devices"] } : {}),
+                    ...(args["architectures"] !== undefined ? { architectures: args["architectures"] } : {}),
+                    ...(args["max_concurrent_chairs"] !== undefined ? { max_concurrent_chairs: args["max_concurrent_chairs"] } : {}),
+                    ...(args["floor"] !== undefined ? { floor: args["floor"] } : {}),
+                    // NO repo_url here: the repository is the SUBJECT of a RUN, named at dispatch, not an
+                    // at-rest venue field. A venue serves many repositories; pinning one on the room would mint
+                    // a venue per repository. See VenueObjectSchema's gap note.
                 };
                 const parsedVenue = VenueSchema.safeParse(venueInputDef);
                 if (!parsedVenue.success) {
@@ -1391,8 +1495,32 @@ async function runImpl(slug, args, deps, approval) {
                     args["fields_to_add"] ?? {};
                 const nextProps = { ...baseProps, ...addProps };
                 const nextRequired = extension?.schema?.required ?? baseDef.required_fields;
+                // A MUTATION THAT CHANGES NOTHING SAYS SO. `addProps` reads exactly two shapes —
+                // `extension.schema.properties` and `fields_to_add`. An `extension` supplied in any OTHER
+                // shape (top-level JSON Schema keywords, say) matches neither, so addProps is {} and the
+                // caller's intent is DROPPED — while this handler went on to bump the version and seal
+                // content/effective hashes, reporting "additive: +0 field(s)" as success. The caller is told
+                // the genome moved when it did not, and learns otherwise only downstream, when the thing
+                // they authored never fires. Observed 2026-08-20 authoring a conditional constraint.
+                // Sibling of the agent_evolve no-op reported in #325; both refuse here rather than guess.
+                const addedNothing = Object.keys(addProps).length === 0;
+                const requiredUnchanged = JSON.stringify([...nextRequired].sort()) === JSON.stringify([...baseDef.required_fields].sort());
+                if (addedNothing && requiredUnchanged) {
+                    return {
+                        ok: false,
+                        requires_approval: approval,
+                        error: `type_extend would change nothing about "${baseDef.slug}" — no field was added and ` +
+                            `required_fields is unchanged, so no version is warranted. Field additions are read ` +
+                            `from \`extension.schema.properties\` or \`fields_to_add\`; an extension supplied in ` +
+                            `any other shape (e.g. top-level JSON Schema keywords) is not read by this verb.`,
+                    };
+                }
                 const base = {
-                    slug: baseDef.slug, version: 1, extends: baseDef.extends, domain: baseDef.domain,
+                    // Read the base's OWN version (widened onto DomainType) so proposeTypeChange computes
+                    // next_version = base.version + 1 from reality, not a constant. `?? 1` covers the freshly
+                    // registered projection that carries no version (always v1). The hardcoded 1 here forced
+                    // every extend to next_version 2 — the first half of PR #433 AC6's second-extend defect.
+                    slug: baseDef.slug, version: baseDef.version ?? 1, extends: baseDef.extends, domain: baseDef.domain,
                     status: "active", schema: { type: "object", properties: baseProps }, required_fields: baseDef.required_fields,
                 };
                 // THE THIRD DOOR. `{...baseProps, ...addProps}` above is the exact merge #264 is
@@ -1418,10 +1546,37 @@ async function runImpl(slug, args, deps, approval) {
                 };
                 const proposal = proposeTypeChange(base, next);
                 const newFields = Object.keys(nextProps).length - Object.keys(baseProps).length;
-                // substrate seal: the new version's identity is recorded in the ledger (file
-                // materialization of versioned types follows the version-aware loader path).
+                // substrate seal: PERSIST the extended definition the way type_register does, rather
+                // than only recording its identity in the ledger. The prior `recordIdentity` path
+                // deferred file materialization to a "version-aware loader path" that does not exist —
+                // so `ok:true` named a version nothing wrote: a fresh load still resolved the old
+                // definition, and the sealed genome_mutation row asserted a state the genome did not
+                // hold. `sealDefinition` seals-before-writes and materializes a loadable file, so an
+                // `ok:true` now means the type is resolvable. The loader keys domain types by version
+                // from file CONTENT and DomainTypeMap.get returns the highest-version record, so the
+                // in-place overwrite of `domain_types/<slug>.json` at the bumped version resolves today
+                // with no versioned filename — an `@v` file would be the same defect wearing a version
+                // number. The ledger subject stays the VERSIONED identity `<slug>@v<n>` (its content
+                // hash), while the file is the bare `<slug>.json` the loader reads.
                 const versioned = { ...next, version: proposal.next_version };
-                const tx = deps.genome_dir ? recordIdentity("type_extend", `${base.slug}@v${proposal.next_version}`, versioned, deps.ledger, args["reason"] != null ? { reason: args["reason"] } : undefined) : undefined;
+                const tx = deps.genome_dir
+                    ? sealDefinition("type_extend", `${base.slug}@v${proposal.next_version}`, versioned, deps.ledger, deps.genome_dir, "domain_types", args["reason"] != null ? { reason: args["reason"] } : undefined, base.slug)
+                    : undefined;
+                // Refresh the in-memory registry to match what was just sealed to disk. sealDefinition
+                // overwrites domain_types/<slug>.json at the bumped version, but the registry map still
+                // holds the pre-extend entry — so a SECOND type_extend on the same slug would re-read the
+                // stale version and compute next_version from it again (v1→v2→v2 instead of v3). That is
+                // the second half of PR #433 AC6's defect: the write became real, so the collision became
+                // real. Swap just this slug's entry (bumped version + the merged schema/required_fields
+                // just sealed) into a snapshot and replaceTypes it. replaceTypes — not registerType — is
+                // used deliberately: registerType runs reuse enforcement via score(), and an extended type
+                // scores >=80 against its own prior version (score() never inspects slug), so registerType
+                // would REFUSE it. replaceTypes is the existing bypass (genome_reload uses it) and is a
+                // sync, not authorship. See rationale in the sealed change-set re: score()'s slug-blindness.
+                const snapshot = deps.registry.listTypes().map((t) => t.slug === base.slug
+                    ? { ...t, version: proposal.next_version, schema: { type: "object", properties: nextProps }, required_fields: [...nextRequired] }
+                    : t);
+                deps.registry.replaceTypes(snapshot);
                 return { ok: true, requires_approval: proposal.approval_required, data: { new_version: proposal.next_version, changelog_entry: `${proposal.change_class}: +${newFields} field(s)`, change_class: proposal.change_class, effective_hash: tx?.effective_hash, content_hash: tx?.content_hash } };
             }
             case "charter_read": {
@@ -1574,6 +1729,9 @@ async function runImpl(slug, args, deps, approval) {
                     domain: d.domain,
                     schema: d.schema,
                     required_fields: [...d.required_fields],
+                    // Carry the on-disk version through the reload so a version decision reads it (mirrors
+                    // loadRegistry). Editing domain_types/ and reloading must not reset a type to version-less.
+                    version: d.version,
                 }));
                 const typeDiff = deps.registry.replaceTypes(typeDefs);
                 // standards — mutate in place so callers holding deps.standards see updates.
@@ -1948,6 +2106,12 @@ async function runImpl(slug, args, deps, approval) {
                 }
                 // The substrate loop: validate → canonical hash → (if genome_dir) persist + ledger-seal.
                 const sealed = sealAgentDefinition(def, deps.ledger, deps.genome_dir);
+                // Write-through to the LIVE map so a same-session standard_compose resolves this agent
+                // WITHOUT a genome_reload. agent_define wrote agents/<slug>.json but never refreshed
+                // deps.agents, so standard_compose (which resolves slugs from deps.agents) denied an agent
+                // this very tool had just created. This mirrors the write-through standard_compose does for
+                // deps.standards and tool_register does for deps.toolProviders.
+                deps.agents?.set(sealed.agent.slug, sealed.agent);
                 return {
                     ok: true,
                     requires_approval: approval,
@@ -2025,6 +2189,20 @@ async function runImpl(slug, args, deps, approval) {
                 const evolveSlug = typeof args["slug"] === "string" ? args["slug"] : undefined;
                 const changes = (args["changes"] && typeof args["changes"] === "object")
                     ? args["changes"] : undefined;
+                // A MUTATION THAT CHANGES NOTHING SAYS SO (#325). Field edits are read ONLY from a
+                // `changes` object. A caller who puts them at the top level leaves `changes` undefined, the
+                // guarded block below is skipped, and this case used to fall through to `ok: true` with a
+                // `new_version` — success, a version bump, and nothing changed. Refuse instead, naming the
+                // shape, so the caller learns in one call rather than discovering it when the edit is absent.
+                if (evolveSlug && !changes) {
+                    return {
+                        ok: false,
+                        requires_approval: approval,
+                        error: `agent_evolve: no \`changes\` object was supplied for "${evolveSlug}", so nothing ` +
+                            `would be applied. Wrap the field edits in a \`changes\` object — top-level fields are ` +
+                            `not read by this verb, and a call that changes nothing warrants no new version.`,
+                    };
+                }
                 if (evolveSlug && changes && (deps.genome_dir || deps.agents?.has(evolveSlug))) {
                     // The base definition: the genome file when a working tree exists, else the loaded
                     // agents map (a hosted surface has no filesystem — the STORE genome is the base,
@@ -2832,6 +3010,49 @@ async function runImpl(slug, args, deps, approval) {
                     },
                 };
             }
+            case "org_hire": {
+                // NOT the live path — admission is intercepted in callSurfaceTool (which holds the caller
+                // identity and the deps.hireMember backend that dispatchTool never receives). This block
+                // exists, like venue_credential_mint's, so the verb's advertised schema has a matching
+                // handler that reads exactly its two arguments (advertised_args_are_read.test.ts), and it
+                // must live INSIDE this case body so those reads are attributed to org_hire, not the
+                // preceding case. Reaching this at runtime means the surface interception was bypassed —
+                // answer honestly rather than pretend a hire happened.
+                //
+                // ORDER MATTERS: this case sits BEFORE venue_credential_mint so venue_credential_mint stays
+                // the LAST string case in dispatchTool. The advertised_args_are_read parser slices the last
+                // case's body to end-of-file, sweeping in callSurfaceTool's own `args["…"]` reads; keeping
+                // venue last means that slurped tail's bracket reads stay {org_slug, instance} — exactly
+                // venue's schema. (The org_hire callSurfaceTool intercept reads its args by dot access for
+                // the same reason, so it contributes nothing to that tail.)
+                const org_slug = String(args["org_slug"] ?? "");
+                const agent_slug = String(args["agent_slug"] ?? "");
+                return {
+                    ok: false, refusal: "no_backend", requires_approval: approval,
+                    error: `org_hire is served by the tool surface (createToolSurface), which wires the caller and ` +
+                        `the deps.hireMember backend; the bare dispatcher cannot admit agent "${agent_slug}" to ` +
+                        `org "${org_slug}". Call it through the surface.`,
+                };
+            }
+            case "venue_credential_mint": {
+                // NOT the live path — minting is intercepted in callSurfaceTool (which holds the caller
+                // identity and the deps.mintVenueCredential backend that dispatchTool never receives).
+                // This block exists so the verb's advertised schema has a matching handler reading exactly
+                // its two arguments, and so it must live INSIDE this case body, not before the label:
+                // tests/advertised_args_are_read.test.ts slices each case's body from its own label to the
+                // next one, so any argument-read text placed above this label would be attributed to the
+                // PRECEDING case (learning_synthesize) — a control reported against a tool that never took
+                // it. Reaching this block at runtime means the surface interception was bypassed — answer
+                // honestly rather than pretend a mint happened.
+                const org_slug = String(args["org_slug"] ?? "");
+                const instance = String(args["instance"] ?? "");
+                return {
+                    ok: false, refusal: "no_backend", requires_approval: approval,
+                    error: `venue_credential_mint is served by the tool surface (createToolSurface), which wires the ` +
+                        `caller and the deps.mintVenueCredential backend; the bare dispatcher cannot mint for ` +
+                        `org "${org_slug}" instance "${instance}". Call it through the surface.`,
+                };
+            }
             default:
                 return { ok: false, not_implemented: true, requires_approval: approval, error: `"${slug}" has no v0 handler` };
         }
@@ -2876,9 +3097,147 @@ const HOSTED_UPSERT = {
     // class travels the port it is supposed to travel, and the missing half announces itself instead
     // of the engine quietly declining to try. (Store-side work: two tables + two upsert branches.)
     chart_define: { cls: "chart", keys: Object.keys(ChartSchema.shape) },
-    venue_define: { cls: "venue", keys: Object.keys(VenueSchema.shape) },
+    venue_define: { cls: "venue", keys: Object.keys(VenueObjectSchema.shape) },
 };
 async function callSurfaceTool(slug, args, deps) {
+    if (slug === "venue_credential_mint") {
+        // The engine half of the venue credential: shape validation and the three refusals around
+        // whatever backend a deployment injects. This fires for ALL callers, not only hosted, because
+        // its refusals are structural facts about the credential — not a hosted-transport concern.
+        //
+        // (a) A gig-scoped caller may NOT mint a venue credential. This is decided from caller identity
+        //     alone, BEFORE the backend is reached, because the escalation (a one-lease gig token
+        //     minting an org-scoped key that outlives every gig) is a credential-scope fact no store-side
+        //     gate catches. A refused mint must never touch the backend.
+        const escalation = gigScopeRefusal(deps.caller);
+        if (escalation) {
+            return {
+                ok: false,
+                refusal: escalation,
+                error: "a gig-scoped credential may not mint a venue credential: a gig token is issued to one " +
+                    "agent for one gig and expires with that gig's lease, while a venue credential is " +
+                    "org-scoped and outlives every gig. Mint from a member or venue credential instead.",
+            };
+        }
+        // (b) No backend wired → the verb answers honestly rather than throwing, naming the seam to
+        //     wire (the same shape gig_dispatch/gig_approve/gig_cancel use when their store seams are
+        //     absent). A caller that cannot tell "minting is unwired here" from "your request was bad"
+        //     retries the wrong thing forever.
+        if (!deps.mintVenueCredential) {
+            return {
+                ok: false,
+                refusal: "no_backend",
+                error: "no minting backend is wired on this surface — venue_credential_mint ships its schema " +
+                    "and refusals, but a deployment supplies the credential. Wire deps.mintVenueCredential " +
+                    "(parallel to deps.queueGig) to stand up the worker environment.",
+            };
+        }
+        // (c) Mint, then check the grant is COMPLETE. A backend that answers with a half-set is refused,
+        //     not forwarded — handing an incomplete environment back moves the assembly problem to the
+        //     caller while looking like success, which is the failure this verb exists to end.
+        let grant;
+        try {
+            grant = await deps.mintVenueCredential({
+                org_slug: String(args["org_slug"] ?? ""),
+                instance: String(args["instance"] ?? ""),
+            });
+        }
+        catch (e) {
+            return { ok: false, error: e instanceof Error ? e.message : String(e) };
+        }
+        const missing = missingWorkerEnv(grant.env);
+        if (missing.length) {
+            return {
+                ok: false,
+                refusal: "incomplete_env",
+                error: `the minted grant is missing required worker environment: ${missing.join(", ")}. A grant ` +
+                    "that is not complete is refused, not returned — a half-set moves the assembly problem to " +
+                    "the caller while looking like success.",
+            };
+        }
+        // (d) The class names pass through UNCHANGED — the engine does not validate class vocabulary
+        //     (that is the room contract's job, checked by realize before dispatch). The grant is the
+        //     answer, returned exactly once; the engine does not persist it and there is no read-back.
+        return { ok: true, data: grant };
+    }
+    if (slug === "org_hire") {
+        // The engine half of org admission: the two engine-decided refusals and the ledger seal around
+        // whatever backend a deployment injects. Intercepted here (like venue_credential_mint) for ALL
+        // callers, BEFORE the hosted check, so its refusals are structural facts about the act — not a
+        // hosted-transport concern — and so it never reaches a store upsert path.
+        //
+        // These two args are read by DOT access, not `args["…"]`, on purpose: the
+        // advertised_args_are_read parser slurps the LAST dispatchTool case's body to end-of-file and
+        // counts every bracket-with-string-literal read in it as that case's reads (this comment must
+        // not spell that pattern out, or the parser counts the EXPLANATION as an instance of the thing
+        // it explains — which is exactly how it first went red). venue_credential_mint is the last
+        // case (org_hire sits before it precisely to keep it so); a bracket read of `agent_slug` here
+        // would be miscounted as venue reading an arg it does not advertise. Dot access is invisible to
+        // that parser and keeps the slurped tail's reads honestly {org_slug, instance}.
+        const org_slug = String(args.org_slug ?? "");
+        const agent_slug = String(args.agent_slug ?? "");
+        // (a) HIRING IS NEVER SELF-SERVICE. Only a human 'member' caller may admit an agent; a
+        //     player/venue/gig token is an AGENT token, and an agent may not admit an agent — that is
+        //     the whole point of the verb. Decided from caller identity ALONE, before the backend is
+        //     reached, so a refused hire never touches deps.hireMember. Absent caller (a bare surface)
+        //     is not a member either, so it is refused too — the gate fails closed.
+        if (deps.caller?.kind !== "member") {
+            return {
+                ok: false,
+                refusal: "not_a_human_member",
+                error: "hiring is never self-service: only a human member may admit an agent to an org. This " +
+                    "caller presented an agent token, and an agent may not hire an agent. ADMISSION IS NOT " +
+                    "AUTHORITY — a member performs the hire.",
+            };
+        }
+        // (b) No backend wired → the verb answers honestly rather than throwing, naming the seam to
+        //     wire (the same shape venue_credential_mint uses). A caller that cannot tell "hiring is
+        //     unwired here" from "your request was bad" retries the wrong thing forever.
+        if (!deps.hireMember) {
+            return {
+                ok: false,
+                refusal: "no_backend",
+                error: "no admission backend is wired on this surface — org_hire ships its schema and refusals, " +
+                    "but a deployment supplies the insert. Wire deps.hireMember (parallel to " +
+                    "deps.mintVenueCredential) to admit the agent to the org.",
+            };
+        }
+        // (c) Admit, then map the store's TYPED answer. Existence (`unknown_agent`) and idempotency
+        //     (`already_member`) are facts only the store holds — the engine never checks the
+        //     agent_record's status ('named'/'active'), because governance and naming are separate acts
+        //     (coltrane-proposer is active yet was never named). Existence is the ONLY precondition, and
+        //     it is the store's answer, not the engine's.
+        let result;
+        try {
+            result = await deps.hireMember({ org_slug, agent_slug });
+        }
+        catch (e) {
+            return { ok: false, error: e instanceof Error ? e.message : String(e) };
+        }
+        if (!result.ok) {
+            // A refused hire seals NOTHING — the ledger row is written only inside the {ok:true} branch
+            // below, so a hire that did not happen leaves no trace claiming it did.
+            return { ok: false, refusal: result.code };
+        }
+        // (d) SEAL THE ACT to the ledger BEFORE reporting success — a kind:"genome_mutation" row via
+        //     recordIdentity (ledger-only, NOT sealDefinition: a hire writes no genome file), so
+        //     who-hired-whom, when, and on whose authority lives in the append-only chain rather than
+        //     only in a database row. subject_slug is the agent admitted; event is 'org_hire'; org_slug
+        //     rides in the hashed detail. #218 — if the audit row does not land, say so (the store row
+        //     may already exist), rather than reporting a success whose seal never happened.
+        try {
+            recordIdentity("org_hire", agent_slug, { org_slug, agent_slug }, deps.ledger, { org_slug });
+        }
+        catch (e) {
+            if (e instanceof LedgerError) {
+                return { ok: false, audit_write_failed: true, error: `audit write failed — "org_hire" was NOT sealed: ${e.message}` };
+            }
+            throw e;
+        }
+        // (e) Admission REPORTS the belonging it created — the {org_slug, agent_slug} pair, and nothing
+        //     carrying authority.
+        return { ok: true, data: { org_slug, agent_slug } };
+    }
     if (deps.hosted) {
         const blocked = HOSTED_BLOCKED[slug];
         if (blocked)
@@ -2984,6 +3343,13 @@ export function createToolSurface(deps) {
         call: (args) => callSurfaceTool(t.slug, args, deps),
     }));
 }
+// Reserved relay↔child request schemas (restart guard, venue/8). The MCP SDK keys a request
+// handler by the `method` literal in its schema; `.passthrough()` lets the full JSON-RPC envelope
+// (jsonrpc/id/params) pass validation. These carry no params — the relay asks, the child answers
+// from deps.gig_runs. Registering them as request handlers (not tools) is what keeps them off
+// tools/list, so they are invisible to Claude Code and callable only by the parent relay.
+const RunningGigsRequestSchema = z.object({ method: z.literal(RUNNING_GIGS_METHOD) }).passthrough();
+const AbortForRestartRequestSchema = z.object({ method: z.literal(ABORT_FOR_RESTART_METHOD) }).passthrough();
 /** Build the low-level MCP Server with ListTools + CallTool wired to the tool surface. */
 export function createColtraneServer(deps, recorder) {
     const server = new Server({ name: "coltrane", version: COLTRANE_VERSION }, { capabilities: { tools: {} } });
@@ -3011,6 +3377,45 @@ export function createColtraneServer(deps, recorder) {
             isError: !result.ok,
         };
     });
+    // ── Restart guard (venue/8): the child's half of the relay↔child conversation ──────────────
+    // The stdio relay (src/server_relay.ts) holds NO gig state, so before it kills this child to pick
+    // up new bytes it ASKS the child what a restart would destroy. These two reserved methods answer.
+    // They are deliberately NOT MCP tools — they are not in `createToolSurface`, so they never appear
+    // in tools/list and Claude Code cannot call them; only the parent relay, over the same stdio pipe,
+    // does. That is what keeps the relay's blindness structural: it asks, the child answers from the
+    // ONE authority (deps.gig_runs), the relay acts on the answer.
+    const runningGigIds = () => [...(deps.gig_runs?.entries() ?? [])]
+        .filter(([, s]) => s.status === "running")
+        .map(([id]) => id);
+    // "Which gigs are running right now?" — the pre-restart check. Answering with the empty list is a
+    // POSITIVE statement ("nothing in flight, restart freely"); the relay only treats a NON-answer
+    // (timeout) as unhealthy, never an empty answer.
+    server.setRequestHandler(RunningGigsRequestSchema, async () => ({ running: runningGigIds() }));
+    // The FORCE path: the operator chose to restart with gigs in flight. Abort each running gig and —
+    // the whole point — LEDGER the abort BEFORE this child dies, so a killed gig is a recorded fact
+    // rather than an absence (the defect: two publish seats, gigs 8146142e / 18726459, died mid-phase
+    // with sealed outputs banked and no row saying they were killed). This reuses the EXACT sanctioned
+    // gig_abort path: mark the run, abort its controller, then governanceRow('gig_abort', …).
+    server.setRequestHandler(AbortForRestartRequestSchema, async () => {
+        const aborted = [];
+        for (const [gid, live] of deps.gig_runs?.entries() ?? []) {
+            if (live.status !== "running")
+                continue;
+            live.abort_requested = true;
+            live.abort_reason = "server_restart override";
+            let cancelled = false;
+            if (live.controller) {
+                try {
+                    live.controller.abort(live.abort_reason);
+                }
+                catch { /* an already-aborted signal is fine */ }
+                cancelled = true;
+            }
+            deps.ledger.append(governanceRow("gig_abort", gid, { reason: "server_restart override", status: "aborting", cancelled }, gid));
+            aborted.push(gid);
+        }
+        return { aborted };
+    });
     return server;
 }
 /**
@@ -3101,6 +3506,12 @@ export function bootstrapServerDeps(genomeRoot) {
         standards: genome.standards, // ← gig_dispatch can now resolve file-defined standards
         charts: genome.charts, // ← gig_dispatch resolves a chart_slug; chart_browse lists them
         venues: genome.venues, // ← the ceiling a chart's venue imposes has to resolve to something
+        // The production construction of a realizer — the wire from dispatch to the container substrate.
+        // A venue-with-mcp_servers gig is stood up on this (real docker by default; the seam's `run` is
+        // the daemon-free test substitute). Before this, dockerComposeRealizer was defined and reachable
+        // from nowhere in src/, so a venue-named gig got no room. runGig only realizes when the venue
+        // declares servers, so wiring it here changes no server-less venue's behaviour.
+        venueRealizer: dockerComposeRealizer(),
         invoke: makeClaudeInvoker({
             registry,
             model: process.env["COLTRANE_MODEL"],