@cotal-ai/manager 0.6.0 → 0.8.0

package/dist/launch.js

@@ -0,0 +1,151 @@
+import { readFileSync, writeFileSync, lstatSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+import { assertValidChannel, assertValidName, ensureDirNoSymlink, isConcreteChannel, realDirNoSymlink } from "@cotal-ai/core";
+/**
+ * Load + materialize a resolved launch spec for `supervise --launch`.
+ *
+ * The CLI's manifest resolver produces the spec (`cotal-launch/v1`); the manager treats it as
+ * **untrusted input** — strict schema, path-safe run id + agent names — then materializes each
+ * agent's persona to a **transient, non-authoritative** file under `.cotal/run/<runId>/agents/`
+ * (never `.cotal/agents/`, never persona-discoverable). Creds are minted from the spec's `policy`,
+ * not from this file, so the file carries no ACL/capability frontmatter.
+ */
+// A NATS-/path-safe token: connector type, role (a route token), capability, run id. Keeps a
+// hand-edited/malicious launch spec from feeding rewritten route/capability strings into the manager
+// path (channel policies are re-validated at provision time; these complete the untrusted contract).
+const TOKEN = /^[A-Za-z0-9_-]+$/;
+const RunId = z.string().regex(TOKEN, "runId must be a path-safe token ([A-Za-z0-9_-])");
+const LaunchAgentSchema = z.strictObject({
+    name: z.string().min(1),
+    agent: z.string().regex(TOKEN, "agent must be a connector token ([A-Za-z0-9_-])"),
+    role: z.string().regex(TOKEN, "role must be a route-safe token ([A-Za-z0-9_-])").optional(),
+    model: z.string().optional(),
+    description: z.string().optional(),
+    body: z.string().optional(),
+    capabilities: z.array(z.string().regex(TOKEN, "capability must be a safe token ([A-Za-z0-9_-])")).optional(),
+    subscribe: z.array(z.string()),
+    allowSubscribe: z.array(z.string()),
+    allowPublish: z.array(z.string()),
+    personaPath: z.string().optional(),
+    hash: z.string().regex(/^[A-Za-z0-9]+$/, "hash must be alphanumeric"),
+});
+const LaunchSpecSchema = z.strictObject({
+    apiVersion: z.literal("cotal-launch/v1"),
+    space: z.string().min(1),
+    runId: RunId,
+    agents: z.array(LaunchAgentSchema),
+});
+/** Parse + strictly validate a launch spec file. Throws on any deviation (it's untrusted, local
+ *  though it is) — including an agent name that isn't a safe mesh/file token (no path traversal). */
+export function loadLaunchSpec(path) {
+    let json;
+    try {
+        json = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`launch spec ${path}: ${e.message}`);
+    }
+    const r = LaunchSpecSchema.safeParse(json);
+    if (!r.success)
+        throw new Error(`launch spec ${path}: ${r.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`);
+    for (const a of r.data.agents) {
+        assertValidName(a.name); // names the transient file → must be safe
+        validateLaunchPolicy(a); // don't let --launch be a looser second manifest format
+    }
+    return r.data;
+}
+/** Resolve + load the launch spec for a run id, deriving the path from a known root rather than
+ *  accepting one. The `launch` control op (`spawn -f` onto a running manager) passes a `runId`, NOT a
+ *  path — so a (admin-only) caller can never make the manager read an arbitrary host-local JSON: the
+ *  id must be a safe token, `.cotal/run` must be a real (non-symlink) dir chain, and the spec file
+ *  itself must not be a symlink. Then the usual untrusted-input validation ({@link loadLaunchSpec})
+ *  applies, and the spec's self-declared `runId` must match the requested one. */
+export function launchSpecForRun(root, runId) {
+    if (!TOKEN.test(runId))
+        throw new Error(`unsafe runId ${JSON.stringify(runId)} (allowed: letters, digits, _ -)`);
+    const runDir = realDirNoSymlink(root, ".cotal", "run"); // refuse a symlinked .cotal / run parent
+    if (!runDir)
+        throw new Error(`no launch spec for run ${runId} (.cotal/run is absent)`);
+    const path = join(runDir, `${runId}.json`);
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch {
+        throw new Error(`no launch spec for run ${runId} at ${path}`);
+    }
+    if (st.isSymbolicLink())
+        throw new Error(`refusing to read launch spec "${path}": it is a symlink`);
+    const spec = loadLaunchSpec(path);
+    if (spec.runId !== runId)
+        throw new Error(`launch spec runId "${spec.runId}" does not match requested "${runId}"`);
+    return spec;
+}
+// Capabilities that actually grant anything in v1 (provisionAgent only acts on `spawn`); an unknown
+// capability is inert downstream, so reject it at the boundary rather than carry a no-op grant.
+const KNOWN_CAPABILITIES = new Set(["spawn"]);
+/** Re-enforce the v1 manifest's policy constraints at the manager boundary so a hand-edited/malicious
+ *  launch spec can't smuggle in what the CLI schema would reject: concrete channels only (no wildcard
+ *  scopes — the v1 wildcard deferral), `subscribe ⊆ allowSubscribe`, and known capabilities. Channel
+ *  policies are re-checked again at provision time, but this fails BEFORE any provisioning side effect. */
+function validateLaunchPolicy(a) {
+    const where = `launch agent "${a.name}"`;
+    for (const [field, list] of [["subscribe", a.subscribe], ["allowSubscribe", a.allowSubscribe], ["allowPublish", a.allowPublish]])
+        for (const ch of list) {
+            try {
+                assertValidChannel(ch);
+            }
+            catch (e) {
+                throw new Error(`${where}: ${field}: ${e.message}`);
+            }
+            if (!isConcreteChannel(ch))
+                throw new Error(`${where}: ${field} "${ch}" is a wildcard — not allowed in a v1 launch spec`);
+        }
+    const missing = a.subscribe.filter((c) => !a.allowSubscribe.includes(c));
+    if (missing.length)
+        throw new Error(`${where}: subscribe [${missing.join(", ")}] not within allowSubscribe`);
+    for (const cap of a.capabilities ?? [])
+        if (!KNOWN_CAPABILITIES.has(cap))
+            throw new Error(`${where}: unknown capability "${cap}" (known: ${[...KNOWN_CAPABILITIES].join(", ")})`);
+}
+/** Materialize one resolved agent's persona to a transient file the connector reads, and return its
+ *  path. Carries only what a connector needs (identity/role/model/description + body) plus a loud
+ *  generated-artifact header — never ACL/capability frontmatter (creds come from the spec's policy). */
+export function materializePersona(root, runId, a) {
+    // 0700 dirs created component-by-component, refusing a symlinked parent (writes can't escape the
+    // run tree); plus a lexical direct-child check on the final path as belt-and-suspenders.
+    const dir = ensureDirNoSymlink(root, ".cotal", "run", runId, "agents");
+    const path = resolve(dir, `${a.name}.md`);
+    if (dirname(path) !== dir)
+        throw new Error(`unsafe agent name "${a.name}" — persona path escapes ${dir}`);
+    const fm = ["---", `name: ${a.name}`];
+    if (a.role)
+        fm.push(`role: ${scalar(a.role)}`);
+    if (a.model)
+        fm.push(`model: ${scalar(a.model)}`);
+    if (a.description)
+        fm.push(`description: ${scalar(a.description)}`);
+    fm.push("---", "");
+    const src = a.personaPath ?? "the manifest";
+    const header = `<!-- Generated runtime artifact from a cotal mesh manifest (run ${runId}). Do NOT edit — regenerated on each launch and deleted by \`cotal down\`. Edit ${src} instead. This file is not a reusable persona and carries no access authority. -->`;
+    const body = a.body ? `${a.body.trim()}\n` : "";
+    // `wx`: exclusive create — fails rather than following a symlink pre-planted at the path.
+    writeFileSync(path, `${fm.join("\n")}${header}\n\n${body}`, { mode: 0o600, flag: "wx" });
+    return path;
+}
+/** Build the manager spawn opts for a launch agent: identity/role/model + the resolved object
+ *  (which carries the ACL authority) + the materialized configPath. */
+export function launchAgentToStartOpts(a, configPath) {
+    return { name: a.name, agent: a.agent, role: a.role, model: a.model, config: configPath, resolved: a };
+}
+/** Quote a frontmatter scalar so the agent-file parser reads it back unchanged (it strips a matching
+ *  outer quote pair). Plain tokens pass through; anything with structural chars is double-quoted. */
+function scalar(v) {
+    if (v === v.trim() && !/^\[/.test(v) && !/[:#"'\r\n]/.test(v))
+        return v;
+    if (!v.includes('"') && !/[\r\n]/.test(v))
+        return `"${v}"`;
+    return JSON.stringify(v.replace(/[\r\n]+/g, " "));
+}
+//# sourceMappingURL=launch.js.map

package/dist/launch.js.map

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

package/dist/manager.d.ts

@@ -1,10 +1,10 @@
-import type { ControlReply } from "@cotal-ai/core";
+import type { ControlReply, MeshLaunchAgent } from "@cotal-ai/core";
 import { type RuntimeMode } from "./runtime/index.js";
 export interface ManagerOptions {
     space: string;
     servers?: string;
     name?: string;
-    /** Spawn backend. `auto` (default) → pty, or tmux when already inside tmux. */
+    /** Spawn backend. `auto` (default) → pty; tmux/cmux are explicit-only (fail loud if unimported). */
     runtime?: RuntimeMode;
     workspaceRoot?: string;
     /** Port for the console + attach HTTP/WS endpoint (loopback). 0 → ephemeral. */
@@ -13,15 +13,26 @@ export interface ManagerOptions {
 /** A spawn request, typed. The control-plane `start` op parses one of these out of an
  *  untyped request; roster boot constructs them directly. Both funnel into {@link Manager.startAgent}. */
 export interface StartAgentOpts {
+    /** The persona REF to spawn — a filename in `.cotal/agents` (the unique spawn key), discovered as
+     *  `.cotal/agents/<name>.md`. NOT the mesh identity: the spawned peer presents under the file's
+     *  own `name:` (auto-numbered on collision). The file must exist (no silent default-ACL fallback). */
     name: string;
     /** Connector / agent type — resolved from the registry. Defaults to `"cotal"`. */
     agent?: string;
     role?: string;
-    /** Explicit agent-file name-or-path; otherwise `.cotal/agents/<name>.md` is discovered if present. */
+    /** Explicit agent-file path that overrides the `name` ref for *which file to load* (identity still
+     *  comes from that file's `name:`). The file must exist. */
     config?: string;
+    /** Model override (the `--model` flag). Takes precedence over the agent file's `model:`. */
+    model?: string;
     /** Mirror the session's transcript to `tr-<name>`. Defaults to off; `true` (the
      *  `--transcript` flag) opts in. */
     transcript?: boolean;
+    /** A fully-resolved launch profile (from a mesh manifest via `supervise --launch`). When present,
+     *  `startAgent` takes identity/role/ACLs/capabilities/model from here — NOT from a persona file —
+     *  and `config` points at the materialized transient persona the connector reads. The persona file
+     *  is never the access authority in this path. */
+    resolved?: MeshLaunchAgent;
 }
 /**
  * The agent supervisor: a long-lived mesh node that owns agent process lifecycle.
@@ -87,8 +98,9 @@ export declare class Manager {
      *  in-flight (reserved) slots. Lets a colliding spawn auto-number instead of being rejected, so
      *  callers never have to invent a unique name. */
     private uniqueName;
-    /** Spawn a teammate by name (loads `.cotal/agents/<name>.md`), as if a peer asked via the
-     *  control plane. Used to pre-spawn the demo's experts at startup so the manager owns them. */
+    /** Spawn a teammate by persona ref (`name` loads `.cotal/agents/<name>.md`; the peer presents
+     *  under that file's own `name:`), as if a peer asked via the control plane. Used to pre-spawn the
+     *  demo's experts at startup so the manager owns them. */
     startByName(name: string): Promise<ControlReply>;
     /** Resolve once `name` shows up on the mesh roster (presence registered), or after `timeoutMs`.
      *  Lets the pre-spawn loop stagger heavy agent cold-starts so they don't all boot at once.
@@ -98,6 +110,15 @@ export declare class Manager {
     waitForPresence(name: string, timeoutMs?: number): Promise<boolean>;
     /** Parse an untyped control-plane `start` request into {@link StartAgentOpts}. */
     private opStart;
+    /** Boot one resolved agent from a mesh-manifest launch spec, for `cotal spawn -f` onto a RUNNING
+     *  manager. The request carries a `{ runId, name }`, NEVER a path: the manager derives + validates
+     *  `.cotal/run/<runId>.json` itself ({@link launchSpecForRun} — token-safe id, no-follow,
+     *  `loadLaunchSpec`'s untrusted-input + `validateLaunchPolicy` contract), materializes the named
+     *  agent's transient persona, and spawns via the same `startAgent({ resolved })` path as
+     *  `supervise --launch`. The reply is enriched for the ownership ledger: the SPAWNED
+     *  (collision-numbered) name + nkey id creds are filed under, plus the manifest `requested` name,
+     *  `runId`, and resolved `hash`. */
+    private opLaunch;
     /** Spawn and supervise one agent. The single spawn path: both the control-plane
      *  `start` op and declarative roster boot call this. Mints scoped creds in auth mode,
      *  resolves the agent file, launches via the connector + runtime, and records the handle.

package/dist/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAuB,YAAY,EAA0C,MAAM,gBAAgB,CAAC;AAChH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAW5B,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;0GAC0G;AAC1G,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;wCACoC;IACpC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAkBD;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D;gGAC4F;IAC5F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C;gGAC4F;IAC5F,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,EAAE,CAAiB;IAC3B;+FAC2F;IAC3F,OAAO,CAAC,IAAI,CAAC,CAAY;gBAEb,IAAI,EAAE,cAAc;IAehC,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,uDAAuD;IACvD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+CtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAKb,MAAM;IAkDpB;;;;yEAIqE;IACrE,OAAO,CAAC,cAAc;IAMtB;;;;6DAIyD;IACzD,OAAO,CAAC,UAAU;IAclB;;;;uGAImG;IACnG,OAAO,CAAC,QAAQ;IAMhB;;uGAEmG;IACnG,OAAO,CAAC,cAAc;IAStB;;oGAEgG;IAChG,OAAO,CAAC,WAAW;IAKnB;iGAC6F;IAC7F,OAAO,CAAC,SAAS;IAMjB;;sDAEkD;IAClD,OAAO,CAAC,UAAU;IAIlB;mGAC+F;IACzF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAItD;;;;0EAIsE;IAChE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IASzE,kFAAkF;IAClF,OAAO,CAAC,OAAO;IAaf;;;;;+DAK2D;IACrD,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAyG/E;;;;;kGAK8F;IAC9F,OAAO,CAAC,SAAS;IAQjB;0GACsG;IACtG,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,MAAM;IAYd;;qGAEiG;YACnF,OAAO;IAgBrB;;;;;;;;4GAQwG;IACxG,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,QAAQ;IAqBhB,wFAAwF;IACxF,OAAO,CAAC,IAAI;CAab"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAuB,YAAY,EAA+B,eAAe,EAAa,MAAM,gBAAgB,CAAC;AACjI,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAqC5B,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;0GAC0G;AAC1G,MAAM,WAAW,cAAc;IAC7B;;0GAEsG;IACtG,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;gEAC4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;wCACoC;IACpC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;sDAGkD;IAClD,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAkBD;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D;gGAC4F;IAC5F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C;gGAC4F;IAC5F,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,EAAE,CAAiB;IAC3B;+FAC2F;IAC3F,OAAO,CAAC,IAAI,CAAC,CAAY;gBAEb,IAAI,EAAE,cAAc;IAehC,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,uDAAuD;IACvD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+CtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAKb,MAAM;IA0DpB;;;;yEAIqE;IACrE,OAAO,CAAC,cAAc;IAMtB;;;;6DAIyD;IACzD,OAAO,CAAC,UAAU;IAclB;;;;uGAImG;IACnG,OAAO,CAAC,QAAQ;IAMhB;;uGAEmG;IACnG,OAAO,CAAC,cAAc;IAStB;;oGAEgG;IAChG,OAAO,CAAC,WAAW;IAKnB;iGAC6F;IAC7F,OAAO,CAAC,SAAS;IAMjB;;sDAEkD;IAClD,OAAO,CAAC,UAAU;IAIlB;;8DAE0D;IACpD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAItD;;;;0EAIsE;IAChE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IASzE,kFAAkF;IAClF,OAAO,CAAC,OAAO;IAcf;;;;;;;wCAOoC;YACtB,QAAQ;IA0BtB;;;;;+DAK2D;IACrD,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAmK/E;;;;;kGAK8F;IAC9F,OAAO,CAAC,SAAS;IAQjB;0GACsG;IACtG,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,MAAM;IAYd;;qGAEiG;YACnF,OAAO;IAgBrB;;;;;;;;4GAQwG;IACxG,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,QAAQ;IAqBhB,wFAAwF;IACxF,OAAO,CAAC,IAAI;CAgBb"}

package/dist/manager.js

@@ -1,8 +1,10 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { CotalEndpoint, DEFAULT_SERVER, agentFilePath, authDir, clearSpaceHistory, connectorServers, findCotalRoot, firstFreeName, loadAgentFile, loadCotalConfig, loadSpaceAuth, mintCreds, newIdentity, provisionAgent, registry, saveAgentFile, subjectMatches, CONTROL_PRIVILEGED, CONTROL_SELF_SERVICE, CONTROL_ADMIN, } from "@cotal-ai/core";
+import { accessSync, constants, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, dirname, delimiter } from "node:path";
+import { CotalEndpoint, DEFAULT_SERVER, agentFilePath, clearSpaceHistory, connectorServers, firstFreeName, loadAgentFile, loadCotalConfig, mintCreds, newIdentity, provisionAgent, registry, saveAgentFile, subjectMatches, CONTROL_PRIVILEGED, CONTROL_SELF_SERVICE, CONTROL_ADMIN, } from "@cotal-ai/core";
+import { authDir, findCotalRoot, loadSpaceAuth } from "@cotal-ai/workspace";
 import { createRuntime, } from "./runtime/index.js";
 import { AttachEndpoint } from "./attach-endpoint.js";
+import { launchSpecForRun, materializePersona, launchAgentToStartOpts } from "./launch.js";
 /** Concurrency ceiling — the manager refuses to hold more than this many live + in-flight +
  *  cooling slots at once (P4a). Bounds a fork-bomb: spawn is a full agent process per call. */
 const MAX_AGENTS = 50;
@@ -10,6 +12,33 @@ const MAX_AGENTS = 50;
  *  before living this long leaves a cooling stamp that still counts toward the ceiling until it
  *  expires — so churn (spawn↔despawn or spawn↔fast-exit) can't outrun the concurrency bound. */
 const MIN_LIFETIME = 10_000;
+/** Is `bin` an executable on PATH? A side-effect-free preflight for a connector's `requires` —
+ *  scans PATH directly with `accessSync(X_OK)` rather than shelling out to `which`, so it can't
+ *  hang or run the harness. An absolute/relative path is checked as-is; a bare name is looked up
+ *  across PATH entries (empty entries skipped). POSIX-only (macOS/Linux); no PATHEXT handling. */
+function binOnPath(bin) {
+    if (bin.includes("/")) {
+        try {
+            accessSync(bin, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        try {
+            accessSync(join(dir, bin), constants.X_OK);
+            return true;
+        }
+        catch {
+            // not here — keep scanning
+        }
+    }
+    return false;
+}
 /**
  * The agent supervisor: a long-lived mesh node that owns agent process lifecycle.
  * It serves control requests on the "manager" service and spawns/kills agents
@@ -129,6 +158,15 @@ export class Manager {
             case "start":
                 // Spawn is a privileged-tier op; reaching it via admin is fine (admin ⊇ privileged powers).
                 return this.opStart(args, caller);
+            case "launch":
+                // SECURITY: manifest launch is operator-only (admin tier). It is higher-power than `start`
+                // — it boots an operator-authored, coordinated policy set from a run spec and underpins the
+                // ownership ledger — so a merely spawn-capable agent (which CAN publish to the privileged
+                // subject) must not reach it. Gate at the handler like `purge`; the subject alone isn't a
+                // boundary because `spawn` grants privileged-subject publish and dispatch is by op here.
+                if (!admin)
+                    return { ok: false, error: "launch is admin-only; not allowed on the privileged subject" };
+                return this.opLaunch(args, caller);
             case "stop": {
                 if (!name)
                     return { ok: false, error: "self-stop not allowed on privileged subject; send it on the self-service subject" };
@@ -228,8 +266,9 @@ export class Manager {
     uniqueName(base) {
         return firstFreeName(base, (n) => this.agents.has(n) || this.reserved.has(n));
     }
-    /** Spawn a teammate by name (loads `.cotal/agents/<name>.md`), as if a peer asked via the
-     *  control plane. Used to pre-spawn the demo's experts at startup so the manager owns them. */
+    /** Spawn a teammate by persona ref (`name` loads `.cotal/agents/<name>.md`; the peer presents
+     *  under that file's own `name:`), as if a peer asked via the control plane. Used to pre-spawn the
+     *  demo's experts at startup so the manager owns them. */
     async startByName(name) {
         return this.startAgent({ name });
     }
@@ -254,9 +293,47 @@ export class Manager {
             agent: args.agent ? String(args.agent) : undefined,
             role: args.role ? String(args.role) : undefined,
             config: args.config ? String(args.config) : undefined,
+            model: args.model ? String(args.model) : undefined,
             transcript: typeof args.transcript === "boolean" ? args.transcript : undefined,
         }, caller);
     }
+    /** Boot one resolved agent from a mesh-manifest launch spec, for `cotal spawn -f` onto a RUNNING
+     *  manager. The request carries a `{ runId, name }`, NEVER a path: the manager derives + validates
+     *  `.cotal/run/<runId>.json` itself ({@link launchSpecForRun} — token-safe id, no-follow,
+     *  `loadLaunchSpec`'s untrusted-input + `validateLaunchPolicy` contract), materializes the named
+     *  agent's transient persona, and spawns via the same `startAgent({ resolved })` path as
+     *  `supervise --launch`. The reply is enriched for the ownership ledger: the SPAWNED
+     *  (collision-numbered) name + nkey id creds are filed under, plus the manifest `requested` name,
+     *  `runId`, and resolved `hash`. */
+    async opLaunch(args, caller) {
+        const runId = String(args.runId ?? "").trim();
+        const name = String(args.name ?? "").trim();
+        if (!runId || !name)
+            return { ok: false, error: "launch requires runId + name" };
+        let spec;
+        try {
+            spec = launchSpecForRun(this.workspaceRoot, runId);
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+        const la = spec.agents.find((a) => a.name === name);
+        if (!la)
+            return { ok: false, error: `no agent "${name}" in launch spec for run ${runId}` };
+        let configPath;
+        try {
+            configPath = materializePersona(this.workspaceRoot, runId, la);
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+        const reply = await this.startAgent(launchAgentToStartOpts(la, configPath), caller);
+        if (reply.ok)
+            // `data.name` stays the spawned (numbered) identity — what creds are filed under and the ledger
+            // keys on; `requested`/`runId`/`hash` give the CLI the manifest name + drift hash for the ledger.
+            reply.data = { ...reply.data, requested: la.name, runId, hash: la.hash, newlyStarted: true };
+        return reply;
+    }
     /** Spawn and supervise one agent. The single spawn path: both the control-plane
      *  `start` op and declarative roster boot call this. Mints scoped creds in auth mode,
      *  resolves the agent file, launches via the connector + runtime, and records the handle.
@@ -264,96 +341,147 @@ export class Manager {
      *  defaulting to the manager's own id for roster/pre-spawn — recorded for the spawner
      *  ledger (own-children despawn + reap-on-parent-exit). */
     async startAgent(opts, spawner) {
-        const base = opts.name.trim();
-        if (!base)
+        // The spawn argument is a persona REF — a filename in `.cotal/agents` (the unique spawn KEY), or
+        // a path via `--config`. It is NOT the mesh identity: the identity comes from inside the file
+        // (`name:`), so a persona can be filed descriptively (review-critic.md) yet present under a
+        // free-form name (socrates) — the same model `cotal spawn` already uses. You always spawn by
+        // filename (unique on disk); two files can't collide on the key.
+        const ref = opts.name.trim();
+        if (!ref)
             return { ok: false, error: "name required" };
-        const nameErr = this.nameError(base);
-        if (nameErr)
-            return { ok: false, error: nameErr };
+        // A bare ref maps to `.cotal/agents/<ref>.md`, so it must be a safe token (no path traversal); a
+        // `--config` path is validated by existsSync below instead.
+        if (!opts.config) {
+            const refErr = this.nameError(ref);
+            if (refErr)
+                return { ok: false, error: refErr };
+        }
         const agent = opts.agent ?? "cotal";
-        // Synchronous availability gate (P4a/P4c) — the free-name pick and the reserve run in one tick
-        // BEFORE any await, so two concurrent spawns can't land on the same name (no TOCTOU between the
-        // pick and the reserve), and the ceiling can't be overshot by fan-out racing the provision await.
+        // Capacity check first (cheap, fail-fast). Everything from here to the reserve below is
+        // SYNCHRONOUS (existsSync / registry / accessSync / readFileSync — no await), so the gate stays
+        // atomic: the capacity snapshot and the reserve land in one tick (P4a/P4c), and two concurrent
+        // spawns can't overshoot the ceiling or pick the same name.
         const cooling = this.coolingCount(); // prune expired stamps, then count live cooling slots
         if (this.agents.size + this.reserved.size + cooling >= MAX_AGENTS)
             return { ok: false, error: `at capacity (${MAX_AGENTS} agents incl. in-flight + cooling); despawn one or wait` };
-        // A taken name auto-numbers (reviewer → reviewer-2 → reviewer-3…) so callers never collide; the
-        // persona file is still discovered from the requested base name below, so reviewer-2 wears it.
-        // Deliberate semantics: this is create-new, not ensure-exists — a retried/redelivered identical
-        // spawn from the same caller yields a fresh numbered agent, not a no-op. Accepted (MAX_AGENTS
-        // bounds the blast radius). Follow-up: add a short per-(spawner,base,role) idempotency window if
-        // autonomous orchestration ever produces phantom spawns.
-        const name = this.uniqueName(base);
-        this.reserved.add(name);
+        // Resolve the persona file (fail loud — NO silent default-ACL fallback). A missing persona used
+        // to mint DEFAULT creds (read `general` only, default-deny publish, no capabilities), so a
+        // typo'd / renamed / spawned-by-display-name agent became live with silently-wrong ACLs — a
+        // behavioral/security bug. Fail loud instead, matching `cotal spawn` (loadAgentFile throws).
+        let configPath;
+        if (opts.config) {
+            configPath = agentFilePath(this.workspaceRoot, opts.config);
+            if (!existsSync(configPath))
+                return { ok: false, error: `agent file not found: ${configPath}` };
+        }
+        else {
+            configPath = agentFilePath(this.workspaceRoot, ref);
+            if (!existsSync(configPath))
+                return { ok: false, error: `no persona "${ref}" — ${configPath} not found; create it or pass --config (see \`cotal personas list\`)` };
+        }
+        // Connector + harness preflight before reserving a slot or minting — a missing connector or a
+        // missing `claude`/`opencode` binary fails here with a clear name, not obscurely at process
+        // spawn. No fallback. All synchronous, so the reserve gate stays atomic.
+        let connector;
         try {
-            // Resolve an agent file from the manager's own workspace — an explicit
-            // --config must exist; otherwise discover .cotal/agents/<name>.md if present.
-            let configPath;
-            if (opts.config) {
-                configPath = agentFilePath(this.workspaceRoot, opts.config);
-                if (!existsSync(configPath))
-                    return { ok: false, error: `agent file not found: ${configPath}` };
+            connector = registry.resolve("connector", agent);
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+        const missing = (connector.requires ?? []).filter((bin) => !binOnPath(bin));
+        if (missing.length)
+            return { ok: false, error: `${agent} harness needs ${missing.join(", ")} on PATH — not found` };
+        // Resolve the launch profile: IDENTITY (free-form `name:`) + role + read/post ACL + capabilities
+        // + model. Either from a fully-resolved manifest launch object (`opts.resolved`, whose `config`
+        // is a materialized transient persona — the file is NOT the access authority), or from the
+        // persona file. The number rides the IDENTITY (socrates → socrates-2), not the file ref — a
+        // redelivered identical spawn yields a fresh numbered agent (MAX_AGENTS bounds the blast radius).
+        let identityName;
+        let role;
+        let subscribe;
+        let allowSubscribe;
+        let allowPublish;
+        let capabilities;
+        let model = opts.model;
+        if (opts.resolved) {
+            const r = opts.resolved;
+            identityName = r.name;
+            role = opts.role ?? r.role;
+            subscribe = r.subscribe;
+            allowSubscribe = r.allowSubscribe?.length ? r.allowSubscribe : r.subscribe;
+            allowPublish = r.allowPublish;
+            capabilities = r.capabilities;
+            model = opts.model ?? r.model;
+        }
+        else {
+            let def;
+            try {
+                def = loadAgentFile(configPath);
             }
-            else {
-                const f = agentFilePath(this.workspaceRoot, base);
-                if (existsSync(f))
-                    configPath = f;
+            catch (e) {
+                return { ok: false, error: e.message };
             }
-            // --role overrides the file; the file fills it in for bookkeeping otherwise.
-            let role = opts.role;
-            // A stable nkey identity assigned at spawn: the public key is the agent's card.id
-            // (threaded via COTAL_ID); the seed is retained to mint matching creds later.
+            identityName = def.name;
+            role = opts.role ?? def.role;
+            subscribe = def.subscribe;
+            // Defaulted the same way the loader/provisioner do — minted into the creds (the broker
+            // boundary); runtime durable joins are re-authorized against the committed ACL by the daemon.
+            allowSubscribe = def.allowSubscribe ?? def.subscribe ?? ["general"];
+            allowPublish = def.allowPublish;
+            capabilities = def.capabilities;
+        }
+        const idErr = this.nameError(identityName);
+        if (idErr)
+            return { ok: false, error: opts.resolved ? `launch agent: ${idErr}` : `persona ${configPath}: ${idErr}` };
+        const name = this.uniqueName(identityName);
+        this.reserved.add(name);
+        try {
+            // A stable nkey identity assigned at spawn: the public key is the agent's card.id (threaded via
+            // COTAL_ID); the seed is retained to mint matching creds later.
             const identity = newIdentity();
-            // The agent's read ACL, defaulted the same way the loader/provisioner do — retained on the
-            // managed record so the mediated join/leave op can validate channels ⊆ allowSubscribe.
-            let allowSubscribe = ["general"];
-            let handle;
-            try {
-                const connector = registry.resolve("connector", agent);
-                const def = configPath ? loadAgentFile(configPath) : undefined;
-                if (!role)
-                    role = def?.role;
-                allowSubscribe = def?.allowSubscribe ?? def?.subscribe ?? ["general"];
-                // In auth mode, mint the agent's creds from the space signing key and write them where the
-                // spawned session reads them (COTAL_CREDS path). Open mesh → no creds. Read scope = the
-                // file's subscribe/allowSubscribe; post scope = its allowPublish (default-deny).
-                let credsPath;
-                if (this.auth) {
-                    // Pre-create the agent's bind-only chat (+ DM + role TASK) durables and mint its scoped
-                    // creds — the shared onboarding step (provisionAgent), the manager just supplies its
-                    // own connected endpoint as the privileged provisioner.
-                    const creds = await provisionAgent(this.ep, this.auth, identity, {
-                        subscribe: def?.subscribe,
-                        allowSubscribe,
-                        allowPublish: def?.allowPublish,
-                        role,
-                        capabilities: def?.capabilities,
-                    });
-                    credsPath = join(authDir(this.workspaceRoot), "creds", `${name}.creds`);
-                    mkdirSync(dirname(credsPath), { recursive: true });
-                    writeFileSync(credsPath, creds, { mode: 0o600 });
-                }
-                // Personal MCP servers the operator opted to share with manager-spawned agents of this
-                // type (cotal config; default none → isolated, the memory-safe default this guards).
-                const mcpServers = connectorServers(loadCotalConfig(this.workspaceRoot), agent);
-                const spec = connector.buildLaunch({
-                    space: this.space,
-                    name,
+            // In auth mode, mint the agent's creds from the space signing key and write them where the
+            // spawned session reads them (COTAL_CREDS path). Open mesh → no creds. Scope = the resolved
+            // subscribe/allowSubscribe (read) + allowPublish (post, default-deny).
+            let credsPath;
+            if (this.auth) {
+                // Pre-create the agent's bind-only chat (+ DM + role TASK) durables and mint its scoped creds
+                // — the shared onboarding step (provisionAgent); the manager supplies its own connected
+                // endpoint as the privileged provisioner.
+                const creds = await provisionAgent(this.ep, this.auth, identity, {
+                    subscribe,
+                    allowSubscribe,
+                    allowPublish,
                     role,
-                    id: identity.id,
-                    creds: credsPath,
-                    servers: this.servers,
-                    configPath,
-                    transcript: opts.transcript,
-                    mcpServers,
+                    capabilities,
                 });
-                handle = this.runtime.spawn(name, spec, this.workspaceRoot);
-            }
-            catch (e) {
-                // Pre-set failure: the slot was never live, so no cold-start was paid — the reserved
-                // rollback (finally) is enough, no cooling stamp.
-                return { ok: false, error: e.message };
+                credsPath = join(authDir(this.workspaceRoot), "creds", `${name}.creds`);
+                mkdirSync(dirname(credsPath), { recursive: true });
+                writeFileSync(credsPath, creds, { mode: 0o600 });
             }
+            // Personal MCP servers the operator opted to share with manager-spawned agents of this type
+            // (cotal config; default none → isolated, the memory-safe default this guards).
+            const mcpServers = connectorServers(loadCotalConfig(this.workspaceRoot), agent);
+            const spec = connector.buildLaunch({
+                space: this.space,
+                name,
+                role,
+                id: identity.id,
+                creds: credsPath,
+                servers: this.servers,
+                configPath,
+                model,
+                // The SAME access set the creds were minted from (above) — forwarded so the session's
+                // runtime read/post set matches its credentials. Without this a manifest-spawned agent
+                // (materialized persona has no access frontmatter) falls back to `["general"]`, which its
+                // scoped creds deny, and it joins nothing.
+                subscribe,
+                allowSubscribe,
+                allowPublish,
+                transcript: opts.transcript,
+                mcpServers,
+            });
+            const handle = this.runtime.spawn(name, spec, this.workspaceRoot);
             const managed = {
                 name,
                 role,
@@ -370,6 +498,11 @@ export class Manager {
             this.watchExit(managed);
             return { ok: true, data: { name, role, agent, id: identity.id, mode: handle.kind } };
         }
+        catch (e) {
+            // Failure after reserve (provision / launch threw): the slot was never live, so no cold-start
+            // was paid — the reserved rollback (finally) is enough, no cooling stamp.
+            return { ok: false, error: e.message };
+        }
         finally {
             this.reserved.delete(name);
         }
@@ -507,6 +640,9 @@ export class Manager {
         const roster = new Map(this.ep.getRoster().map((p) => [p.card.name, p]));
         return [...this.agents.values()].map((a) => ({
             name: a.name,
+            // The spawned agent's nkey — lets an operator tool (e.g. `cotal down -f`) match a ledger entry
+            // by name AND id before stopping, so it never stops a same-named foreign agent.
+            id: a.id,
             role: a.role,
             agent: a.agent,
             space: this.space,