@cotal-ai/cli 0.7.0 → 0.8.0

package/dist/lib/manifest/ledger.js

@@ -0,0 +1,213 @@
+/**
+ * The `spawn -f` ownership ledger (`cotal-ledger/v1`, one file per run at
+ * `.cotal/manifests/<runId>.json`): the durable, creation-only record of exactly what a `spawn -f`
+ * deploy added to a shared mesh — the registry keys it created and the agents it spawned (by the
+ * manager-reply **spawned** name + nkey id). `down -f` reads it to tear down *only* those resources.
+ *
+ * Two hard rules, because a tampered ledger could otherwise become arbitrary process/credential/file
+ * deletion (the round-8/9 security review):
+ *   1. **Store IDs, never arbitrary paths.** Cred paths are *derived* from the known auth root at
+ *      teardown ({@link ownedCredPath}); the run dir is `.cotal/run/<runId>`. The ledger never names
+ *      a path to delete.
+ *   2. **Treat the file as untrusted on read.** {@link loadLedger} strictly validates the whole
+ *      ledger (schema, token-safe ids/names, concrete channels, duplicate detection) BEFORE the
+ *      caller takes any destructive action — fail closed, globally.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync, readdirSync, renameSync, lstatSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { z } from "zod";
+import { assertValidChannel, assertValidName, ensureDirNoSymlink, isConcreteChannel, realDirNoSymlink } from "@cotal-ai/core";
+import { authDir } from "@cotal-ai/workspace";
+export const LEDGER_VERSION = "cotal-ledger/v1";
+// Path-/route-safe token (run id, agent name) and an alphanumeric content hash — same shapes the
+// launch spec uses, so the ledger can't smuggle a traversal/injection string into a derived path.
+const TOKEN = /^[A-Za-z0-9_-]+$/;
+const HASH = /^[A-Za-z0-9]+$/;
+const LedgerAgentSchema = z.strictObject({
+    /** The manifest agent key (`agents:` name) — display + the stable key a re-apply matches a declared
+     *  agent against (the spawned name may collision-number, so it can't be that key). */
+    requested: z.string().regex(TOKEN, "requested name must be a path-safe token ([A-Za-z0-9_-])"),
+    /** The manager-reply SPAWNED name (collision-numbered, e.g. `socrates-2`) — what creds are filed
+     *  under; the cred path derives from THIS, never the manifest key. */
+    name: z.string().regex(TOKEN, "agent name must be a path-safe token ([A-Za-z0-9_-])"),
+    /** The spawned agent's nkey id — the immutable identity `down -f` matches before stopping. */
+    id: z.string().min(1),
+    /** The resolved hash at spawn (drift/stale detection on re-apply). */
+    hash: z.string().regex(HASH, "hash must be alphanumeric"),
+});
+const LedgerSchema = z.strictObject({
+    apiVersion: z.literal(LEDGER_VERSION),
+    kind: z.literal("MeshLedger"),
+    runId: z.string().regex(TOKEN, "runId must be a path-safe token ([A-Za-z0-9_-])"),
+    space: z.string().min(1),
+    server: z.string().min(1),
+    /** Content hash of the source manifest — an INDEX for `down -f cotal.yaml` only, never authority. */
+    manifestHash: z.string().regex(HASH, "manifestHash must be alphanumeric"),
+    /** The source manifest path — operator/display context only; never derived from or deleted. */
+    manifestPath: z.string().min(1),
+    teardownMode: z.literal("ledger-scoped"),
+    created: z.strictObject({
+        /** Registry keys this run CREATED (brand-new only — never adopted/pre-existing). */
+        channels: z.array(z.string()),
+        agents: z.array(LedgerAgentSchema),
+    }),
+});
+/** Assemble a ledger from a `spawn -f` apply result. `agents` carry the manager-reply SPAWNED name
+ *  (cred-keying) + manifest `requested` key + nkey id + resolved hash; `channels` are the brand-new
+ *  registry keys this run created. */
+export function buildLedger(opts) {
+    return {
+        apiVersion: LEDGER_VERSION,
+        kind: "MeshLedger",
+        runId: opts.runId,
+        space: opts.space,
+        server: opts.server,
+        manifestHash: opts.manifestHash,
+        manifestPath: opts.manifestPath,
+        teardownMode: "ledger-scoped",
+        created: { channels: opts.channels, agents: opts.agents },
+    };
+}
+/** Stable index hash of the manifest source text — ties a `down -f cotal.yaml` back to its ledger
+ *  (an edited file no longer matches, so `down -f` fails rather than guessing; `--run` is the
+ *  escape hatch). NOT an integrity check and NOT ownership authority — only a lookup key. */
+export function hashManifestSource(src) {
+    return createHash("sha256").update(src).digest("hex").slice(0, 16);
+}
+/** Write the ledger to `<root>/.cotal/manifests/<runId>.json`, `0600`, atomically and refusing a
+ *  symlinked parent. A brand-new ledger is `wx` (exclusive create); an additive update (re-apply)
+ *  goes temp-then-rename so `down -f` never reads a half-written file. */
+export function writeLedger(root, ledger, opts = {}) {
+    const dir = ensureDirNoSymlink(root, ".cotal", "manifests");
+    const path = join(dir, `${ledger.runId}.json`);
+    const body = JSON.stringify(ledger, null, 2);
+    if (opts.update) {
+        // Atomic replace: write a fresh temp (exclusive — never follow a pre-planted symlink), then
+        // rename over the target. `rename` replaces the destination name itself, not a symlink target.
+        const tmp = join(dir, `.${ledger.runId}.${randomBytes(4).toString("hex")}.tmp`);
+        writeFileSync(tmp, body, { mode: 0o600, flag: "wx" });
+        renameSync(tmp, path);
+    }
+    else {
+        writeFileSync(path, body, { mode: 0o600, flag: "wx" });
+    }
+    return path;
+}
+/** Parse + strictly validate a ledger file as **untrusted input** — schema, unknown-key rejection,
+ *  token-safe run id / agent names, concrete channel keys, and duplicate detection — so the WHOLE
+ *  ledger is proven before the caller deletes anything (no partial "validated the class I'm about to
+ *  delete" flow). Throws on any deviation. */
+export function loadLedger(path) {
+    // No-follow: the ledger drives destructive teardown, so refuse a symlinked ledger file (a symlink
+    // could redirect `down -f` to attacker-chosen content). Callers also prove the parent dir chain.
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch (e) {
+        throw new Error(`ledger ${path}: ${e.message}`);
+    }
+    if (st.isSymbolicLink())
+        throw new Error(`refusing to read ledger "${path}": it is a symlink`);
+    if (!st.isFile())
+        throw new Error(`refusing to read ledger "${path}": not a regular file`);
+    let json;
+    try {
+        json = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`ledger ${path}: ${e.message}`);
+    }
+    const r = LedgerSchema.safeParse(json);
+    if (!r.success)
+        throw new Error(`ledger ${path}: ${r.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`);
+    const led = r.data;
+    const agents = new Set();
+    for (const a of led.created.agents) {
+        assertValidName(a.name); // belt-and-suspenders past the regex — it names a derived cred path
+        if (agents.has(a.name))
+            throw new Error(`ledger ${path}: duplicate owned agent "${a.name}"`);
+        agents.add(a.name);
+    }
+    const channels = new Set();
+    for (const ch of led.created.channels) {
+        assertValidChannel(ch);
+        if (!isConcreteChannel(ch))
+            throw new Error(`ledger ${path}: owned channel "${ch}" is not concrete`);
+        if (channels.has(ch))
+            throw new Error(`ledger ${path}: duplicate owned channel "${ch}"`);
+        channels.add(ch);
+    }
+    return led;
+}
+/** Every valid ledger under `<root>/.cotal/manifests/`. Unparseable/foreign files are skipped (a
+ *  targeted `down -f --run <id>` names one directly); used to resolve a `down -f cotal.yaml` to its
+ *  run by `manifestHash`. */
+export function listLedgers(root) {
+    // Prove `.cotal/manifests` is a real (non-symlink) directory chain before reading under it — a
+    // symlinked parent could redirect `down -f` to attacker-chosen ledgers.
+    const dir = realDirNoSymlink(root, ".cotal", "manifests");
+    if (!dir)
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        if (!n.endsWith(".json") || n.startsWith("."))
+            continue;
+        const p = join(dir, n);
+        try {
+            const ledger = loadLedger(p);
+            if (`${ledger.runId}.json` !== n)
+                continue; // filename must match the declared runId (no spoofed authority)
+            out.push({ path: p, ledger });
+        }
+        catch {
+            /* skip — a foreign/corrupt file isn't this run's ledger; `--run` targets a known one */
+        }
+    }
+    return out;
+}
+/** Resolve a `down -f cotal.yaml` to its ledger by the manifest's content hash. Fails (never
+ *  guesses) when nothing matches (edited file) or more than one does — `--run <id>` is the escape. */
+export function findLedgerByHash(root, manifestHash) {
+    const matches = listLedgers(root).filter((l) => l.ledger.manifestHash === manifestHash);
+    if (matches.length === 0)
+        throw new Error(`no ledger matches this manifest's current contents (was it edited since \`spawn -f\`?) — tear down by run id: \`cotal down -f <file> --run <id>\``);
+    if (matches.length > 1)
+        throw new Error(`${matches.length} runs share this manifest — name one: ${matches.map((m) => m.ledger.runId).join(", ")} (\`--run <id>\`)`);
+    return matches[0];
+}
+/** Resolve a ledger by explicit run id (the `--run <id>` path). Validates the id is a safe token
+ *  before deriving the path. */
+export function findLedgerByRun(root, runId) {
+    assertValidName(runId);
+    const dir = realDirNoSymlink(root, ".cotal", "manifests"); // refuse a symlinked manifests parent
+    if (!dir)
+        throw new Error(`no ledger for run ${runId} (.cotal/manifests is absent)`);
+    const path = join(dir, `${runId}.json`);
+    const ledger = loadLedger(path); // loadLedger refuses a symlinked ledger file
+    // Bind the filename to the contents: a tampered `<runId>.json` whose body declares a DIFFERENT
+    // runId must not redirect teardown to that other run's derived run dir / resources.
+    if (ledger.runId !== runId)
+        throw new Error(`ledger ${path}: declares runId "${ledger.runId}", not "${runId}" — refusing`);
+    return { path, ledger };
+}
+/** Derive an owned agent's cred path under the known auth root — `<root>/.cotal/auth/creds/<name>.creds`
+ *  — from the SPAWNED name, rejecting any name that escapes the creds dir. The ledger never stores a
+ *  cred path; teardown derives it here and the caller deletes it no-follow ({@link unlinkFileNoFollow}). */
+export function ownedCredPath(root, spawnedName) {
+    assertValidName(spawnedName);
+    const dir = resolve(authDir(root), "creds");
+    const path = resolve(dir, `${spawnedName}.creds`);
+    if (dirname(path) !== dir)
+        throw new Error(`unsafe owned agent name "${spawnedName}" — cred path escapes ${dir}`);
+    return path;
+}
+//# sourceMappingURL=ledger.js.map

package/dist/lib/manifest/ledger.js.map

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

package/dist/lib/manifest/live.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Live-mesh helpers for `cotal spawn -f` — the network half: a transient, invisible probe endpoint
+ * for reading the roster + membership feed, and the admin-tier control calls that drive the running
+ * manager's `launch` op. (Channel-registry reads use `readChannelRegistry`, which connects itself.)
+ */
+import { CotalEndpoint, type ControlReply, type Presence } from "@cotal-ai/core";
+export interface MeshConn {
+    space: string;
+    server: string;
+    creds?: string;
+}
+/** Connect a transient, presence-invisible endpoint (it watches the roster but doesn't register
+ *  itself) used to read live state + drive control. The caller stops it. */
+export declare function connectProbe(conn: MeshConn): Promise<CotalEndpoint>;
+/** Let the presence KV replay settle (roster count steady across two polls, ≤1s), then snapshot the
+ *  live peers — mirrors the dedup probe in `cotal spawn`. */
+export declare function settleRoster(ep: CotalEndpoint): Promise<Presence[]>;
+/** Poll the manager's control plane until it answers `ps` — it may have just been started detached,
+ *  so it needs a moment to connect + come up. Returns false on timeout. */
+export declare function waitManagerReady(ep: CotalEndpoint, timeoutMs?: number): Promise<boolean>;
+/** Ask the running manager to launch one resolved agent from the run spec, on the ADMIN tier (the
+ *  `launch` op is operator-only — a spawn-capable agent must not reach it). The manager derives
+ *  `.cotal/run/<runId>.json` itself; we pass the runId, never a path. */
+export declare function launchAgent(ep: CotalEndpoint, runId: string, name: string): Promise<ControlReply>;
+//# sourceMappingURL=live.d.ts.map

package/dist/lib/manifest/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../../../src/lib/manifest/live.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAiB,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEhG,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;4EAC4E;AAC5E,wBAAsB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAczE;AAED;6DAC6D;AAC7D,wBAAsB,YAAY,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CASzE;AAED;2EAC2E;AAC3E,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,aAAa,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAY9F;AAED;;yEAEyE;AACzE,wBAAsB,WAAW,CAAC,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAEvG"}

package/dist/lib/manifest/live.js

@@ -0,0 +1,61 @@
+/**
+ * Live-mesh helpers for `cotal spawn -f` — the network half: a transient, invisible probe endpoint
+ * for reading the roster + membership feed, and the admin-tier control calls that drive the running
+ * manager's `launch` op. (Channel-registry reads use `readChannelRegistry`, which connects itself.)
+ */
+import { CotalEndpoint, CONTROL_ADMIN } from "@cotal-ai/core";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Connect a transient, presence-invisible endpoint (it watches the roster but doesn't register
+ *  itself) used to read live state + drive control. The caller stops it. */
+export async function connectProbe(conn) {
+    const ep = new CotalEndpoint({
+        space: conn.space,
+        servers: conn.server,
+        creds: conn.creds,
+        channels: [],
+        consume: false,
+        registerPresence: false, // an invisible probe — don't add ourselves to the roster we read
+        watchPresence: true,
+        card: { name: "spawn-f", kind: "endpoint" },
+    });
+    ep.on("error", () => { }); // a presence/control hiccup must never crash the deploy
+    await ep.start();
+    return ep;
+}
+/** Let the presence KV replay settle (roster count steady across two polls, ≤1s), then snapshot the
+ *  live peers — mirrors the dedup probe in `cotal spawn`. */
+export async function settleRoster(ep) {
+    let prev = -1;
+    for (let i = 0; i < 10; i++) {
+        await sleep(100);
+        const n = ep.getRoster().length;
+        if (n === prev)
+            break;
+        prev = n;
+    }
+    return ep.getRoster();
+}
+/** Poll the manager's control plane until it answers `ps` — it may have just been started detached,
+ *  so it needs a moment to connect + come up. Returns false on timeout. */
+export async function waitManagerReady(ep, timeoutMs = 20_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const r = await ep.requestControl(CONTROL_ADMIN, { op: "ps" });
+            if (r.ok)
+                return true;
+        }
+        catch {
+            /* manager not answering yet */
+        }
+        await sleep(500);
+    }
+    return false;
+}
+/** Ask the running manager to launch one resolved agent from the run spec, on the ADMIN tier (the
+ *  `launch` op is operator-only — a spawn-capable agent must not reach it). The manager derives
+ *  `.cotal/run/<runId>.json` itself; we pass the runId, never a path. */
+export async function launchAgent(ep, runId, name) {
+    return ep.requestControl(CONTROL_ADMIN, { op: "launch", args: { runId, name } });
+}
+//# sourceMappingURL=live.js.map

package/dist/lib/manifest/live.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.js","sourceRoot":"","sources":["../../../src/lib/manifest/live.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAoC,MAAM,gBAAgB,CAAC;AAQhG,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEnF;4EAC4E;AAC5E,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAc;IAC/C,MAAM,EAAE,GAAG,IAAI,aAAa,CAAC;QAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,IAAI,CAAC,MAAM;QACpB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,gBAAgB,EAAE,KAAK,EAAE,iEAAiE;QAC1F,aAAa,EAAE,IAAI;QACnB,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE;KAC5C,CAAC,CAAC;IACH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,wDAAwD;IAClF,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACjB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;6DAC6D;AAC7D,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EAAiB;IAClD,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QACjB,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,KAAK,IAAI;YAAE,MAAM;QACtB,IAAI,GAAG,CAAC,CAAC;IACX,CAAC;IACD,OAAO,EAAE,CAAC,SAAS,EAAE,CAAC;AACxB,CAAC;AAED;2EAC2E;AAC3E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EAAiB,EAAE,SAAS,GAAG,MAAM;IAC1E,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,cAAc,CAAC,aAAa,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,IAAI,CAAC,CAAC,EAAE;gBAAE,OAAO,IAAI,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;QACD,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;yEAEyE;AACzE,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAAiB,EAAE,KAAa,EAAE,IAAY;IAC9E,OAAO,EAAE,CAAC,cAAc,CAAC,aAAa,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;AACnF,CAAC"}

package/dist/lib/manifest/model.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The resolved manifest model — the typed output of the pure pipeline (parse → schema →
+ * normalize/invert → semantic), with channel-centric membership inverted into per-agent ACLs.
+ * Preflight (persona reads + the `include` merge) and the plan/apply stages consume this.
+ */
+import type { ChannelDefaults, DeliveryClass } from "@cotal-ai/core";
+export type PersonaPermissions = "reject" | "include";
+/** A channel after normalization: `allowSubscribe` defaulted to `subscribe`, dedup'd. The
+ *  registry-card fields (description/instructions/replay…) seed the channel registry verbatim. */
+export interface ResolvedChannel {
+    name: string;
+    description?: string;
+    instructions?: string;
+    /** Active read set (boot subscription). */
+    subscribe: string[];
+    /** Read ACL — may read/join. Defaults to {@link subscribe}; always a superset of it. */
+    allowSubscribe: string[];
+    /** Post ACL (default-deny: empty ⇒ nobody posts). */
+    allowPublish: string[];
+    replay?: boolean;
+    replayWindow?: string;
+    deliveryClass?: DeliveryClass;
+}
+/** Per-agent ACLs inverted from the channel membership lists — the manifest-declared access only
+ *  (a persona's own grants, under `include`, are merged on top in preflight). 1:1 with AgentDef. */
+export interface AgentPolicy {
+    subscribe: string[];
+    allowSubscribe: string[];
+    allowPublish: string[];
+}
+/** A resolved agent: its identity/behavior source (a persona file or fully inline) plus the
+ *  manifest-declared policy. Behavior fields here are the manifest's overrides; the persona
+ *  default is filled in during preflight (which reads the file). */
+export interface ResolvedAgent {
+    /** The `agents:` key — also the requested spawn name in v1. */
+    name: string;
+    /** Connector type to spawn with (agent-entry `agent:` ?? top-level `agent:`). */
+    agentType: string;
+    /** Resolved persona path (absolute), or undefined for an inline agent. */
+    persona?: string;
+    /** Manifest override of the persona's model (or the inline model). */
+    model?: string;
+    role?: string;
+    /** Manifest card blurb (override / inline). */
+    description?: string;
+    /** Manifest persona body (REPLACES the file body when set; the sole body for inline). */
+    instructions?: string;
+    /** Manifest capabilities — win over the persona's when present. */
+    capabilities?: string[];
+    /** Effective policy for THIS agent: per-agent override ?? top-level ?? "reject". */
+    personaPermissions: PersonaPermissions;
+    /** ACLs inverted from the channels this agent appears in (pre persona-merge). */
+    policy: AgentPolicy;
+}
+/** The fully resolved, validated manifest — channel-centric on disk, per-agent here. */
+export interface ResolvedManifest {
+    space: string;
+    broker?: {
+        servers?: string;
+        host?: string;
+        auth?: boolean;
+    };
+    runtime?: "pty" | "tmux" | "cmux";
+    personaPermissions: PersonaPermissions;
+    defaults?: ChannelDefaults;
+    agents: ResolvedAgent[];
+    channels: ResolvedChannel[];
+    /** Absolute path the manifest was loaded from — anchors relative persona refs + error output. */
+    sourcePath: string;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/lib/manifest/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/lib/manifest/model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAErE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtD;kGACkG;AAClG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,wFAAwF;IACxF,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,qDAAqD;IACrD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;oGACoG;AACpG,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;oEAEoE;AACpE,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,oFAAoF;IACpF,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,iFAAiF;IACjF,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7D,OAAO,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,iGAAiG;IACjG,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/lib/manifest/model.js

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

package/dist/lib/manifest/model.js.map

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

package/dist/lib/manifest/preflight.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedManifest } from "./model.js";
+import { type AgentWarning, type PreparedAgent } from "./prepare.js";
+export interface PreparedManifest {
+    manifest: ResolvedManifest;
+    agents: PreparedAgent[];
+    /** Non-fatal diagnostics to render in dry-run / topology view. */
+    warnings: AgentWarning[];
+}
+/** Read personas + merge. Behavior defaults always come from the file (under both policies); only
+ *  the persona's *permissions* are gated by `personaPermissions`. */
+export declare function preparePersonas(manifest: ResolvedManifest): PreparedManifest;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/lib/manifest/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../../src/lib/manifest/preflight.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAgB,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAGnF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,kEAAkE;IAClE,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;qEACqE;AACrE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,CA4B5E"}

package/dist/lib/manifest/preflight.js

@@ -0,0 +1,43 @@
+/**
+ * Preflight — the I/O half of resolution: read each agent's persona file and merge it with the
+ * manifest (via the pure {@link prepareAgent}). Returns the launch-ready {@link PreparedManifest}
+ * (agents + diagnostics) or throws {@link ManifestError} with every persona problem located.
+ *
+ * Live checks that need the network (broker reachability for `up -f` vs `spawn -f`) or the connector
+ * registry stay in the command wiring; this is the fail-fast, file-level half.
+ */
+import { loadAgentFile } from "@cotal-ai/core";
+import { prepareAgent } from "./prepare.js";
+import { ManifestError } from "./errors.js";
+/** Read personas + merge. Behavior defaults always come from the file (under both policies); only
+ *  the persona's *permissions* are gated by `personaPermissions`. */
+export function preparePersonas(manifest) {
+    const declared = new Set(manifest.channels.map((c) => c.name));
+    const issues = [];
+    const warnings = [];
+    const agents = [];
+    for (const a of manifest.agents) {
+        let persona;
+        if (a.persona) {
+            try {
+                persona = loadAgentFile(a.persona);
+            }
+            catch (e) {
+                const code = e.code;
+                issues.push({
+                    message: code === "ENOENT" ? `persona file not found: ${a.persona}` : e.message,
+                    path: ["agents", a.name],
+                });
+                continue;
+            }
+        }
+        const r = prepareAgent(a, persona, declared);
+        issues.push(...r.issues);
+        warnings.push(...r.warnings);
+        agents.push(r.prepared);
+    }
+    if (issues.length)
+        throw new ManifestError(manifest.sourcePath, issues);
+    return { manifest, agents, warnings };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/lib/manifest/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../../src/lib/manifest/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,YAAY,EAAyC,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAC;AAShE;qEACqE;AACrE,MAAM,UAAU,eAAe,CAAC,QAA0B;IACxD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,MAAM,MAAM,GAAoB,EAAE,CAAC;IAEnC,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QAChC,IAAI,OAA6B,CAAC;QAClC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,IAAI,CAAC;gBACH,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,IAAI,GAAI,CAA2B,CAAC,IAAI,CAAC;gBAC/C,MAAM,CAAC,IAAI,CAAC;oBACV,OAAO,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAE,CAAW,CAAC,OAAO;oBAC1F,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC;iBACzB,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;QACH,CAAC;QACD,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,MAAM,CAAC,MAAM;QAAE,MAAM,IAAI,aAAa,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC"}

package/dist/lib/manifest/prepare.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Prepare stage — resolve each agent's effective launch identity + ACLs by merging its persona
+ * (read from disk) with the manifest. Pure: it takes already-loaded {@link AgentDef}s so it stays
+ * unit-testable; the fs/live I/O lives in {@link ./preflight.js}.
+ *
+ * Behavior fields (model/role/description/body) are persona-default + manifest-override. Access is
+ * governed by {@link PersonaPermissions}: under `reject` the manifest is the sole source; under
+ * `include` a persona's own grants are inherited **only for channels the manifest does not declare**
+ * (one authority per channel), concrete-only (wildcards rejected), and surfaced loudly.
+ */
+import { type AgentDef } from "@cotal-ai/core";
+import type { AgentPolicy, ResolvedAgent } from "./model.js";
+import type { ManifestIssue } from "./errors.js";
+/** Persona grants that fall outside the manifest's channels (unmanaged credential scopes) + the
+ *  capabilities inherited from the persona — the data the loud dry-run section renders. */
+export interface InheritedScopes {
+    subscribe: string[];
+    allowSubscribe: string[];
+    allowPublish: string[];
+    capabilities: string[];
+}
+/** A non-fatal diagnostic to surface in dry-run / topology view. `loud` = call it out prominently
+ *  (e.g. an agent with capabilities but no channel access). */
+export interface AgentWarning {
+    agent: string;
+    message: string;
+    loud?: boolean;
+}
+/** The fully resolved launch form for one agent — what the spawn path needs. */
+export interface PreparedAgent {
+    name: string;
+    agentType: string;
+    /** Persona file path (or undefined for an inline agent). */
+    persona?: string;
+    /** Effective values (manifest override ?? persona default). */
+    model?: string;
+    role?: string;
+    description?: string;
+    /** Effective persona body (manifest `instructions` REPLACES the file body; sole body for inline). */
+    body?: string;
+    /** Effective merged capabilities. */
+    capabilities: string[];
+    capabilitySource: "manifest" | "persona" | "none";
+    /** Effective merged per-channel ACLs (manifest + persona-undeclared under `include`). */
+    policy: AgentPolicy;
+    /** Persona grants outside manifest channels + inherited caps (empty under `reject`/inline). */
+    inherited: InheritedScopes;
+}
+export interface PreparedResult {
+    prepared: PreparedAgent;
+    issues: ManifestIssue[];
+    warnings: AgentWarning[];
+}
+/** Merge one resolved agent with its (optional) loaded persona, given the set of channel names the
+ *  manifest declares. Returns the launch form plus any errors/warnings. */
+export declare function prepareAgent(agent: ResolvedAgent, persona: AgentDef | undefined, declared: Set<string>): PreparedResult;
+//# sourceMappingURL=prepare.d.ts.map

package/dist/lib/manifest/prepare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/lib/manifest/prepare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAqB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;2FAC2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;+DAC+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qGAAqG;IACrG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,gBAAgB,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAClD,yFAAyF;IACzF,MAAM,EAAE,WAAW,CAAC;IACpB,+FAA+F;IAC/F,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;2EAC2E;AAC3E,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,GAAG,SAAS,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,cAAc,CAqFvH"}

package/dist/lib/manifest/prepare.js

@@ -0,0 +1,95 @@
+/**
+ * Prepare stage — resolve each agent's effective launch identity + ACLs by merging its persona
+ * (read from disk) with the manifest. Pure: it takes already-loaded {@link AgentDef}s so it stays
+ * unit-testable; the fs/live I/O lives in {@link ./preflight.js}.
+ *
+ * Behavior fields (model/role/description/body) are persona-default + manifest-override. Access is
+ * governed by {@link PersonaPermissions}: under `reject` the manifest is the sole source; under
+ * `include` a persona's own grants are inherited **only for channels the manifest does not declare**
+ * (one authority per channel), concrete-only (wildcards rejected), and surfaced loudly.
+ */
+import { isConcreteChannel } from "@cotal-ai/core";
+/** Merge one resolved agent with its (optional) loaded persona, given the set of channel names the
+ *  manifest declares. Returns the launch form plus any errors/warnings. */
+export function prepareAgent(agent, persona, declared) {
+    const issues = [];
+    const warnings = [];
+    const at = ["agents", agent.name];
+    // Behavior: persona default, manifest override wins. Inline `instructions` REPLACE the body.
+    const model = agent.model ?? persona?.model;
+    const role = agent.role ?? persona?.role;
+    const description = agent.description ?? persona?.description;
+    const body = agent.instructions ?? persona?.persona;
+    // Capabilities: manifest wins; else inherited from the persona only under `include`.
+    let capabilities = [];
+    let capabilitySource = "none";
+    if (agent.capabilities?.length) {
+        capabilities = [...agent.capabilities];
+        capabilitySource = "manifest";
+    }
+    else if (agent.personaPermissions === "include" && persona?.capabilities?.length) {
+        capabilities = [...persona.capabilities];
+        capabilitySource = "persona";
+    }
+    // Access. Start from the manifest-inverted policy (all its channels are declared by construction).
+    const policy = {
+        subscribe: [...agent.policy.subscribe],
+        allowSubscribe: [...agent.policy.allowSubscribe],
+        allowPublish: [...agent.policy.allowPublish],
+    };
+    const inherited = { subscribe: [], allowSubscribe: [], allowPublish: [], capabilities: [] };
+    if (agent.personaPermissions === "include" && persona) {
+        const personaAllowSub = persona.allowSubscribe ?? persona.subscribe ?? [];
+        // Reject persona WILDCARD grants in v1 (they'd re-introduce wildcards via the persona file and
+        // break the per-channel partition).
+        for (const [field, list] of [["subscribe", persona.subscribe], ["allowSubscribe", personaAllowSub], ["allowPublish", persona.allowPublish]])
+            for (const ch of list ?? [])
+                if (!isConcreteChannel(ch))
+                    issues.push({ message: `persona ${field} "${ch}" is a wildcard — not supported in v1 (declare concrete channels)`, path: at });
+        // Persona grants apply ONLY to channels the manifest does not declare (manifest owns its own).
+        const undeclared = (list) => (list ?? []).filter((c) => isConcreteChannel(c) && !declared.has(c));
+        inherited.subscribe = undeclared(persona.subscribe);
+        inherited.allowSubscribe = undeclared(personaAllowSub);
+        inherited.allowPublish = undeclared(persona.allowPublish);
+        inherited.capabilities = capabilitySource === "persona" ? capabilities : [];
+        policy.subscribe = dedupe([...policy.subscribe, ...inherited.subscribe]);
+        policy.allowSubscribe = dedupe([...policy.allowSubscribe, ...inherited.allowSubscribe]);
+        policy.allowPublish = dedupe([...policy.allowPublish, ...inherited.allowPublish]);
+    }
+    // Defensive: the merged read set must stay within the merged read ACL.
+    const missing = policy.subscribe.filter((c) => !policy.allowSubscribe.includes(c));
+    if (missing.length)
+        issues.push({ message: `merged subscribe [${missing.join(", ")}] not within allowSubscribe`, path: at });
+    // Warn on an agent the manifest declares but never grants channel access — likely a typo, but
+    // valid (a DM/control-only peer). Loud when it nonetheless carries capabilities.
+    const noAccess = !policy.subscribe.length && !policy.allowSubscribe.length && !policy.allowPublish.length;
+    if (noAccess)
+        warnings.push({
+            agent: agent.name,
+            loud: capabilities.length > 0,
+            message: capabilities.length
+                ? `declared with capabilities [${capabilities.join(", ")}] but NO channel access (DM/control-only — a powerful non-channel grant)`
+                : `declared but has no channel access from the manifest (DM/control-only unless a persona under \`include\` grants scopes)`,
+        });
+    return {
+        prepared: {
+            name: agent.name,
+            agentType: agent.agentType,
+            persona: agent.persona,
+            model,
+            role,
+            description,
+            body,
+            capabilities,
+            capabilitySource,
+            policy,
+            inherited,
+        },
+        issues,
+        warnings,
+    };
+}
+function dedupe(xs) {
+    return [...new Set(xs)];
+}
+//# sourceMappingURL=prepare.js.map