@cotal-ai/cli 0.6.0 → 0.7.0

package/dist/lib/connect.d.ts

@@ -0,0 +1,72 @@
+import { type MeshTarget, type Profile, type SpaceAuth } from "@cotal-ai/core";
+/**
+ * The one way every command that touches a running mesh figures out WHICH mesh + with what creds,
+ * and confirms it's actually up — so `spawn`, `send`/`dm`/`msg`/`ask`, `console`, `join`, `web`,
+ * `channels`, `history`, and `personas --running` all behave identically from any directory instead
+ * of each re-deriving it from a cwd walk-up (which mistook `$HOME/.cotal` for a space and crashed
+ * with a raw NATS auth violation). Two escape hatches take a RAW off-registry connection (no
+ * registry lookup, no stale-prune): explicit `--creds`, and `--server` + an unregistered `--space`
+ * (an open remote mesh that has no creds to pass).
+ */
+export interface ConnectFlags {
+    server?: string;
+    space?: string;
+    /** Explicit creds file — triggers a raw off-registry connection (see {@link connectOrExit}). */
+    creds?: string;
+}
+/** Raw NATS auth for an off-registry connection — a join link / --token / --user+--pass / --creds.
+ *  Structurally matches what `probeConnect` accepts. */
+export interface RawAuth {
+    token?: string;
+    user?: string;
+    pass?: string;
+    creds?: string;
+    tls?: boolean;
+}
+export interface Connection {
+    server: string;
+    space: string;
+    creds?: string;
+    /** The mesh's trust material when resolved from the registry on an auth mesh — undefined for an
+     *  open mesh or a raw off-registry connection (`--creds` or `--server`+unregistered `--space`).
+     *  (web keeps it for its per-delete manager mint.) */
+    auth?: SpaceAuth;
+}
+/**
+ * Resolve where a mesh-touching command connects + with what creds.
+ *  • Explicit `--creds` → a RAW off-registry connection: straight to `--server` (default loopback)
+ *    as `--space`, with those creds. No registry lookup, no stale-prune, plain reachability message
+ *    (the user is deliberately off-registry — e.g. a remote mesh that isn't locally recorded).
+ *  • Otherwise → resolve the running mesh from the registry (works from any dir), mint `role` creds
+ *    on an auth mesh, and preflight with the registry's stale-prune.
+ */
+export declare function connectOrExit(flags: ConnectFlags, role: Profile): Promise<Connection>;
+/** Reachability check for a RAW (off-registry) connection — one plain sentence, never a registry/
+ *  stale-entry message and never a prune. Used by the `--creds` escape hatch and `join`'s explicit
+ *  (link/token/creds) path, both of which connect to a broker the user named, not the registry. */
+export declare function reachableOrExit(server: string, auth?: RawAuth): Promise<void>;
+/** Resolve the mesh a command targets, exiting with one human sentence on an unresolved/ambiguous
+ *  registry rather than a stack trace. Prunes dead registry entries first so a crashed mesh doesn't
+ *  block a bare command or get offered by `--space`. */
+export declare function resolveTargetOrExit(flags: {
+    server?: string;
+    space?: string;
+}): Promise<MeshTarget>;
+/** The five distinct ways a preflight fails. Each also says whether the target OWNS its registry
+ *  entry (→ prune): `fromRegistry` means the server+mode came from a registry record (incl. a
+ *  `local-recorded` project matched by root), so a definitive failure is a stale-entry signal. */
+export type PreflightFailure = "unreachable" | "registry-creds-rejected" | "registry-open-now-auth" | "creds-rejected" | "open-wants-auth";
+/** Pure decision for {@link preflightOrExit} — separated from I/O so the whole branch tree is
+ *  unit-testable (it's the riskiest new logic: a wrong branch prunes a LIVE registry entry). A
+ *  non-registry source (`flag-server`/`local-space`, or a raw `--creds` connection) is NEVER pruned;
+ *  the user owns that diagnosis. */
+export declare function classifyPreflightFailure(source: MeshTarget["source"], reason: "auth-required" | "unreachable", hasAuth: boolean): {
+    prune: boolean;
+    kind: PreflightFailure;
+};
+/** Confirm the resolved mesh is up and accepts these creds — replaces the raw NATS "Authorization
+ *  Violation" trace with one sentence, and prunes the entry if the broker is gone / mismatched.
+ *  Probes with `probeCreds` when given (the caller's `--creds`/minted creds); otherwise mints a
+ *  throwaway identity from the target's own trust material. */
+export declare function preflightOrExit(target: MeshTarget, probeCreds?: string): Promise<void>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/lib/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/lib/connect.ts"],"names":[],"mappings":"AACA,OAAO,EAUL,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAIxB;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;wDACwD;AACxD,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;0DAEsD;IACtD,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAoB3F;AAED;;mGAEmG;AACnG,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,OAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvF;AAED;;wDAEwD;AACxD,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBtB;AAED;;kGAEkG;AAClG,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,yBAAyB,GACzB,wBAAwB,GACxB,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB;;;oCAGoC;AACpC,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC5B,MAAM,EAAE,eAAe,GAAG,aAAa,EACvC,OAAO,EAAE,OAAO,GACf;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAW5C;AAiBD;;;+DAG+D;AAC/D,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS5F"}

package/dist/lib/connect.js

@@ -0,0 +1,115 @@
+import { readFileSync } from "node:fs";
+import { DEFAULT_SERVER, DEFAULT_SPACE, findMesh, getCurrent, mintCreds, newIdentity, probeConnect, removeMesh, resolveMeshTarget, } from "@cotal-ai/core";
+import { c } from "../ui.js";
+import { pruneStaleMeshes } from "./meshes.js";
+/**
+ * Resolve where a mesh-touching command connects + with what creds.
+ *  • Explicit `--creds` → a RAW off-registry connection: straight to `--server` (default loopback)
+ *    as `--space`, with those creds. No registry lookup, no stale-prune, plain reachability message
+ *    (the user is deliberately off-registry — e.g. a remote mesh that isn't locally recorded).
+ *  • Otherwise → resolve the running mesh from the registry (works from any dir), mint `role` creds
+ *    on an auth mesh, and preflight with the registry's stale-prune.
+ */
+export async function connectOrExit(flags, role) {
+    if (flags.creds) {
+        const server = flags.server ?? DEFAULT_SERVER;
+        const space = flags.space ?? DEFAULT_SPACE;
+        const creds = readFileSync(flags.creds, "utf8");
+        await reachableOrExit(server, { creds });
+        return { server, space, creds };
+    }
+    // A raw OPEN remote mesh: explicit `--server` + a `--space` that isn't locally registered. Naming
+    // both is as deliberate as `--creds`, but an open broker has no creds to pass — connect bare,
+    // off-registry (no registry lookup, no prune). A registered `--space` still goes through the
+    // resolver below (which honors `--server` as an override); `--server` alone resolves there too.
+    if (flags.server && flags.space && !findMesh(flags.space)) {
+        await reachableOrExit(flags.server, {});
+        return { server: flags.server, space: flags.space };
+    }
+    const target = await resolveTargetOrExit({ server: flags.server, space: flags.space });
+    const creds = target.auth ? await mintCreds(target.auth, newIdentity(), role) : undefined;
+    await preflightOrExit(target, creds);
+    return { server: target.server, space: target.space, creds, auth: target.auth };
+}
+/** Reachability check for a RAW (off-registry) connection — one plain sentence, never a registry/
+ *  stale-entry message and never a prune. Used by the `--creds` escape hatch and `join`'s explicit
+ *  (link/token/creds) path, both of which connect to a broker the user named, not the registry. */
+export async function reachableOrExit(server, auth = {}) {
+    const probe = await probeConnect(server, auth);
+    if (probe.ok)
+        return;
+    console.error(c.red(probe.reason === "auth-required"
+        ? `✗ credentials rejected at ${server} — check your creds, or the broker wants different auth`
+        : `✗ can't reach a broker at ${server} — is it running? (\`cotal up\`)`));
+    process.exit(1);
+}
+/** Resolve the mesh a command targets, exiting with one human sentence on an unresolved/ambiguous
+ *  registry rather than a stack trace. Prunes dead registry entries first so a crashed mesh doesn't
+ *  block a bare command or get offered by `--space`. */
+export async function resolveTargetOrExit(flags) {
+    await pruneStaleMeshes();
+    let target;
+    try {
+        target = resolveMeshTarget(process.cwd(), flags);
+    }
+    catch (e) {
+        console.error(c.red(`✗ ${e.message}`));
+        process.exit(1);
+    }
+    // If a dangling `current` was silently bypassed — it named a mesh that's since gone and we fell
+    // back to the only live one — say so. The N>1 case errors loudly; this is the one spot that would
+    // otherwise quietly redirect a stale default.
+    const cur = getCurrent();
+    if (cur && !findMesh(cur) && target.source === "registry")
+        console.error(c.dim(`note: default mesh "${cur}" is down — using "${target.space}"`));
+    return target;
+}
+/** Pure decision for {@link preflightOrExit} — separated from I/O so the whole branch tree is
+ *  unit-testable (it's the riskiest new logic: a wrong branch prunes a LIVE registry entry). A
+ *  non-registry source (`flag-server`/`local-space`, or a raw `--creds` connection) is NEVER pruned;
+ *  the user owns that diagnosis. */
+export function classifyPreflightFailure(source, reason, hasAuth) {
+    const fromRegistry = source === "registry" ||
+        source === "current" ||
+        source === "flag-space" ||
+        source === "local-recorded";
+    if (reason === "unreachable")
+        return { prune: fromRegistry, kind: "unreachable" };
+    if (fromRegistry && hasAuth)
+        return { prune: true, kind: "registry-creds-rejected" };
+    if (fromRegistry)
+        return { prune: true, kind: "registry-open-now-auth" };
+    if (hasAuth)
+        return { prune: false, kind: "creds-rejected" };
+    return { prune: false, kind: "open-wants-auth" };
+}
+function preflightMessage(kind, t, pruned) {
+    switch (kind) {
+        case "unreachable":
+            return `✗ no mesh running at ${t.server}${pruned ? " (stale registry entry — removed)" : ""} — run \`cotal up\``;
+        case "registry-creds-rejected":
+            return `✗ mesh "${t.space}" at ${t.server} no longer matches its registry entry (credentials rejected — port reused?) — re-run \`cotal up\` from ${t.root}, or \`cotal meshes\` to see what's live`;
+        case "registry-open-now-auth":
+            return `✗ open mesh "${t.space}" at ${t.server} no longer matches its registry entry (broker now requires auth — port reused?) — re-run \`cotal up\` from ${t.root}, or \`cotal meshes\` to see what's live`;
+        case "creds-rejected":
+            return `✗ credentials for "${t.space}" were rejected at ${t.server} — a different mesh may be running there. Run \`cotal meshes\` to check, or \`cotal up\` here to start yours`;
+        case "open-wants-auth":
+            return `✗ broker at ${t.server} requires auth, but this mesh is open (no trust material) — use \`--space <name>\` for an auth mesh, or run \`cotal up\` here without \`--open\``;
+    }
+}
+/** Confirm the resolved mesh is up and accepts these creds — replaces the raw NATS "Authorization
+ *  Violation" trace with one sentence, and prunes the entry if the broker is gone / mismatched.
+ *  Probes with `probeCreds` when given (the caller's `--creds`/minted creds); otherwise mints a
+ *  throwaway identity from the target's own trust material. */
+export async function preflightOrExit(target, probeCreds) {
+    const creds = probeCreds ?? (target.auth ? await mintCreds(target.auth, newIdentity(), "manager") : undefined);
+    const probe = await probeConnect(target.server, creds ? { creds } : {});
+    if (probe.ok)
+        return;
+    const { prune, kind } = classifyPreflightFailure(target.source, probe.reason, Boolean(target.auth));
+    if (prune)
+        removeMesh(target.space);
+    console.error(c.red(preflightMessage(kind, target, prune)));
+    process.exit(1);
+}
+//# sourceMappingURL=connect.js.map

package/dist/lib/connect.js.map

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

package/dist/lib/meshes.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Drop registry entries whose broker is gone — a `cotal up` that crashed or was `kill -9`'d without
+ * `cotal down` leaves a record behind. Probe each in parallel; only `unreachable` (refused/timeout)
+ * is stale, an auth broker answering `auth-required` is alive. Called by `spawn`/`use`/`meshes`
+ * before they act on the registry — never by completion (a `<TAB>` must not open the network).
+ */
+export declare function pruneStaleMeshes(): Promise<void>;
+//# sourceMappingURL=meshes.d.ts.map

package/dist/lib/meshes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meshes.d.ts","sourceRoot":"","sources":["../../src/lib/meshes.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOtD"}

package/dist/lib/meshes.js

@@ -0,0 +1,15 @@
+import { loadMeshes, probeConnect, removeMesh } from "@cotal-ai/core";
+/**
+ * Drop registry entries whose broker is gone — a `cotal up` that crashed or was `kill -9`'d without
+ * `cotal down` leaves a record behind. Probe each in parallel; only `unreachable` (refused/timeout)
+ * is stale, an auth broker answering `auth-required` is alive. Called by `spawn`/`use`/`meshes`
+ * before they act on the registry — never by completion (a `<TAB>` must not open the network).
+ */
+export async function pruneStaleMeshes() {
+    await Promise.all(loadMeshes().map(async (m) => {
+        const r = await probeConnect(m.server);
+        if (!r.ok && r.reason === "unreachable")
+            removeMesh(m.space);
+    }));
+}
+//# sourceMappingURL=meshes.js.map

package/dist/lib/meshes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meshes.js","sourceRoot":"","sources":["../../src/lib/meshes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,OAAO,CAAC,GAAG,CACf,UAAU,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC3B,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa;YAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/lib/onboard.js

@@ -1,15 +1,15 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { homeCotalDir } from "@cotal-ai/core";
 /** Machine-level "I've onboarded before" marker. Its presence flips `cotal` from the
  *  full first-run flow to the compact ensure+status run. Lives next to the materialized
- *  plugin marketplace under ~/.cotal. */
-const MARKER = join(homedir(), ".cotal", "onboarded.json");
+ *  plugin marketplace under ~/.cotal (COTAL_HOME-overridable, via {@link homeCotalDir}). */
+const MARKER = () => join(homeCotalDir(), "onboarded.json");
 export function isOnboarded() {
-    return existsSync(MARKER);
+    return existsSync(MARKER());
 }
 export function markOnboarded(version) {
-    mkdirSync(join(homedir(), ".cotal"), { recursive: true });
-    writeFileSync(MARKER, JSON.stringify({ version, ts: new Date().toISOString() }, null, 2));
+    mkdirSync(homeCotalDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(MARKER(), JSON.stringify({ version, ts: new Date().toISOString() }, null, 2));
 }
 //# sourceMappingURL=onboard.js.map

package/dist/lib/onboard.js.map

@@ -1 +1 @@
-{"version":3,"file":"onboard.js","sourceRoot":"","sources":["../../src/lib/onboard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;yCAEyC;AACzC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC;AAE3D,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC5F,CAAC"}
+{"version":3,"file":"onboard.js","sourceRoot":"","sources":["../../src/lib/onboard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;4FAE4F;AAC5F,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,gBAAgB,CAAC,CAAC;AAE5D,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,SAAS,CAAC,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5D,aAAa,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC9F,CAAC"}

package/dist/lib/transient.d.ts

@@ -1,18 +1,19 @@
 import { CotalEndpoint } from "@cotal-ai/core";
 /**
  * A one-shot, write-capable connection for the headless commands that touch the live mesh
- * (`dm`/`msg`/`ask`, and `personas list --running`). Resolve space/server/creds the same way
- * everywhere, open a transient endpoint that never joins the roster, do the one thing, stop.
- * Fail-loud throughout — an unreachable server or a space mismatch exits, never degrades.
+ * (`dm`/`msg`/`ask`, and `personas list --running`). Resolution + creds + reachability all go through
+ * the shared `connectOrExit` (so these work from any directory, and an explicit `--creds` is a raw
+ * off-registry connection). Opens a transient endpoint that never joins the roster, does the one
+ * thing, stops.
  */
 export interface ConnectValues {
     space?: string;
     server?: string;
     creds?: string;
 }
-/** Resolve where to connect and with what credentials: an explicit `--creds` wins; else self-mint
- *  from `.cotal/auth` so an AUTH-mode mesh admits us; else connect bare on an open mesh. Exits with
- *  a clear message on a `--space` that contradicts the local auth, or an unreachable server. */
+/** Resolve where to connect + with what credentials (`--creds` → raw off-registry; else the running
+ *  mesh's minted manager creds). Fail-loud — an unresolved registry or an unreachable/auth-mismatched
+ *  broker exits with one sentence, never degrades. */
 export declare function resolveConnect(values: ConnectValues): Promise<{
     server: string;
     space: string;

package/dist/lib/transient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transient.d.ts","sourceRoot":"","sources":["../../src/lib/transient.ts"],"names":[],"mappings":"AACA,OAAO,EACL,aAAa,EAQd,MAAM,gBAAgB,CAAC;AAIxB;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;gGAEgG;AAChG,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAuB5D;AAED;iGACiG;AACjG,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,EAAE,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAe/C"}
+{"version":3,"file":"transient.d.ts","sourceRoot":"","sources":["../../src/lib/transient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;sDAEsD;AACtD,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAG5D;AAED;iGACiG;AACjG,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,EAAE,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAe/C"}

package/dist/lib/transient.js

@@ -1,30 +1,11 @@
-import { readFileSync } from "node:fs";
-import { CotalEndpoint, isReachable, DEFAULT_SERVER, DEFAULT_SPACE, authDir, loadSpaceAuth, mintCreds, newIdentity, } from "@cotal-ai/core";
+import { CotalEndpoint } from "@cotal-ai/core";
 import { c } from "../ui.js";
-import { cotalRoot } from "./paths.js";
-/** Resolve where to connect and with what credentials: an explicit `--creds` wins; else self-mint
- *  from `.cotal/auth` so an AUTH-mode mesh admits us; else connect bare on an open mesh. Exits with
- *  a clear message on a `--space` that contradicts the local auth, or an unreachable server. */
+import { connectOrExit } from "./connect.js";
+/** Resolve where to connect + with what credentials (`--creds` → raw off-registry; else the running
+ *  mesh's minted manager creds). Fail-loud — an unresolved registry or an unreachable/auth-mismatched
+ *  broker exits with one sentence, never degrades. */
 export async function resolveConnect(values) {
-    const server = values.server ?? DEFAULT_SERVER;
-    let creds = values.creds ? readFileSync(values.creds, "utf8") : undefined;
-    let space = values.space;
-    if (!creds) {
-        const auth = loadSpaceAuth(authDir(cotalRoot()));
-        if (auth) {
-            if (space && space !== auth.space) {
-                console.error(c.red(`Auth here is for space "${auth.space}", not "${space}". Use --space ${auth.space} (or pass --creds).`));
-                process.exit(1);
-            }
-            space = auth.space;
-            creds = await mintCreds(auth, newIdentity(), "manager");
-        }
-    }
-    space = space ?? DEFAULT_SPACE;
-    if (!(await isReachable(server, { creds }))) {
-        console.error(c.red(`Can't reach NATS at ${server}. Run: cotal up`));
-        process.exit(1);
-    }
+    const { server, space, creds } = await connectOrExit(values, "manager");
     return { server, space, creds };
 }
 /** Open a transient endpoint: it watches presence (so name→id resolution and the live roster work)

package/dist/lib/transient.js.map

@@ -1 +1 @@
-{"version":3,"file":"transient.js","sourceRoot":"","sources":["../../src/lib/transient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EACL,aAAa,EACb,WAAW,EACX,cAAc,EACd,aAAa,EACb,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,CAAC,EAAE,MAAM,UAAU,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAevC;;gGAEgG;AAChG,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAqB;IAErB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,cAAc,CAAC;IAC/C,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1E,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IACzB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QACjD,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,KAAK,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;gBAClC,OAAO,CAAC,KAAK,CACX,CAAC,CAAC,GAAG,CAAC,2BAA2B,IAAI,CAAC,KAAK,WAAW,KAAK,kBAAkB,IAAI,CAAC,KAAK,qBAAqB,CAAC,CAC9G,CAAC;gBACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;YACnB,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,SAAS,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,KAAK,GAAG,KAAK,IAAI,aAAa,CAAC;IAC/B,IAAI,CAAC,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,MAAM,iBAAiB,CAAC,CAAC,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC;AAED;iGACiG;AACjG,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAqB,EACrB,IAAY;IAEZ,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9D,MAAM,EAAE,GAAG,IAAI,aAAa,CAAC;QAC3B,KAAK;QACL,OAAO,EAAE,MAAM;QACf,KAAK;QACL,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,gBAAgB,EAAE,KAAK;QACvB,aAAa,EAAE,IAAI;QACnB,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE;KACjC,CAAC,CAAC;IACH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACjB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"transient.js","sourceRoot":"","sources":["../../src/lib/transient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,UAAU,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAgB7C;;sDAEsD;AACtD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAqB;IAErB,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACxE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC;AAED;iGACiG;AACjG,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAqB,EACrB,IAAY;IAEZ,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9D,MAAM,EAAE,GAAG,IAAI,aAAa,CAAC;QAC3B,KAAK;QACL,OAAO,EAAE,MAAM;QACf,KAAK;QACL,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,gBAAgB,EAAE,KAAK;QACvB,aAAa,EAAE,IAAI;QACnB,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE;KACjC,CAAC,CAAC;IACH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACjB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AACvB,CAAC"}

package/dist/web/graph.html

@@ -0,0 +1,204 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Cotal · graph</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Work+Sans:wght@400;500;600;700&display=swap"
+      rel="stylesheet"
+    />
+    <style>
+      :root {
+        --bg: #131a26; --panel: #1b2330cc; --line: #38414f; --fg: #eef2f7;
+        --dim: #8b949e; --faint: #6e7681;
+        --chat: #58a6ff; --unicast: #d29922; --anycast: #3fb950;
+        --working: #3fb950; --waiting: #e3b341; --idle: #6e7681; --red: #f85149;
+        --font: "Work Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      }
+      * { box-sizing: border-box; }
+      html, body { height: 100%; margin: 0; }
+      body {
+        font-family: var(--font); font-size: 13px; background: var(--bg); color: var(--fg);
+        overflow: hidden; -webkit-font-smoothing: antialiased;
+      }
+      #graph { position: fixed; inset: 0; display: block; cursor: grab; }
+      #graph.hover { cursor: pointer; }
+
+      /* floating glass surfaces */
+      .glass {
+        background: var(--panel); border: 1px solid var(--line); border-radius: 12px;
+        backdrop-filter: blur(14px); -webkit-backdrop-filter: blur(14px);
+      }
+
+      /* ── header (top, floating) ── */
+      header {
+        position: fixed; top: 14px; left: 14px; right: 14px; z-index: 10;
+        display: flex; align-items: center; gap: 16px; padding: 9px 14px;
+      }
+      .brand { display: flex; align-items: center; gap: 9px; }
+      .brand .mark { width: 9px; height: 9px; border-radius: 50%; background: var(--chat);
+        box-shadow: 0 0 10px var(--chat); }
+      .brand .title { font-size: 16px; font-weight: 700; }
+      .brand .space { font-size: 13px; color: var(--dim); }
+      .navlink {
+        font-size: 12px; font-weight: 600; color: var(--dim); text-decoration: none;
+        padding: 5px 11px; border-radius: 8px; border: 1px solid var(--line);
+      }
+      .navlink:hover { color: var(--fg); border-color: var(--chat); }
+      .pill { display: inline-flex; align-items: center; gap: 6px; padding: 4px 9px;
+        border-radius: 20px; background: #1f2d24; }
+      .pill .d { width: 7px; height: 7px; border-radius: 50%; background: var(--working); }
+      .pill .t { font-size: 11px; font-weight: 600; color: var(--working); }
+      .pill.down { background: #2a1717; } .pill.down .d { background: var(--red); }
+      .pill.down .t { color: var(--red); }
+      /* membership-freshness pill states */
+      .pill.stale { background: #2a2417; } .pill.stale .d { background: var(--waiting); }
+      .pill.stale .t { color: var(--waiting); }
+      .pill.off { background: #1f242c; } .pill.off .d { background: var(--faint); }
+      .pill.off .t { color: var(--dim); }
+
+      .ctrls { margin-left: auto; display: flex; align-items: center; gap: 7px; }
+      .grp { display: flex; align-items: center; gap: 4px; padding-right: 7px;
+        margin-right: 0; border-right: 1px solid var(--line); }
+      .grp:last-child { border-right: 0; padding-right: 0; }
+      .chip {
+        font-size: 11px; padding: 4px 9px; border-radius: 13px; cursor: pointer;
+        color: var(--faint); user-select: none; border: 1px solid transparent; white-space: nowrap;
+      }
+      .chip:hover { color: var(--fg); }
+      .chip.on { background: #ffffff10; border-color: var(--line); color: var(--fg); }
+      .chip.mode.chat.on { color: var(--chat); } .chip.mode.unicast.on { color: var(--unicast); }
+      .chip.mode.anycast.on { color: var(--anycast); }
+      .chip.pause.on { color: var(--waiting); border-color: var(--waiting); }
+
+      /* ── legend (bottom-left, collapsible) ── */
+      #legend { position: fixed; left: 14px; bottom: 14px; z-index: 10; padding: 0;
+        max-width: 200px; overflow: hidden; }
+      #legend .ltoggle {
+        display: flex; align-items: center; justify-content: space-between;
+        width: 100%; padding: 7px 12px; cursor: pointer; appearance: none;
+        font-size: 10px; font-weight: 600; letter-spacing: .6px; color: var(--faint);
+        text-transform: uppercase; background: transparent; border: 0;
+        text-align: left; font-family: inherit;
+      }
+      #legend .ltoggle:hover { color: var(--dim); }
+      #legend .ltoggle .chev { font-size: 9px; opacity: .5; transition: transform .2s ease; }
+      #legend.collapsed .ltoggle .chev { transform: rotate(-90deg); }
+      #legend .lbody { display: flex; flex-direction: column; gap: 5px; padding: 2px 12px 10px; }
+      #legend.collapsed .lbody { display: none; }
+      #legend .ls { font-size: 9px; font-weight: 600; letter-spacing: .5px; color: var(--faint);
+        text-transform: uppercase; opacity: .65; margin-top: 3px; }
+      #legend .ls:first-child { margin-top: 0; }
+      #legend .row { display: flex; align-items: center; gap: 9px; font-size: 11px; color: var(--dim); }
+      #legend .sw { width: 14px; height: 2px; border-radius: 1px; flex: none; }
+      #legend .sw-dot { width: 8px; height: 8px; border-radius: 50%; }
+      #legend .ring { width: 8px; height: 8px; border-radius: 50%; flex: none;
+        background: transparent; box-shadow: 0 0 0 1.5px currentColor inset; }
+
+      /* ── detail panel (right, floating) ── */
+      #detail {
+        position: fixed; top: 64px; right: 14px; bottom: 14px; width: 308px; z-index: 10;
+        padding: 16px 16px 18px; overflow-y: auto; display: none; flex-direction: column; gap: 14px;
+        scrollbar-width: thin; scrollbar-color: var(--line) transparent;
+      }
+      #detail::-webkit-scrollbar { width: 6px; }
+      #detail::-webkit-scrollbar-thumb { background: var(--line); border-radius: 3px; }
+      #detail.open { display: flex; }
+      #detail .x { position: absolute; top: 10px; right: 10px; cursor: pointer; color: var(--faint);
+        font-size: 13px; width: 22px; height: 22px; display: flex; align-items: center;
+        justify-content: center; border-radius: 5px; line-height: 1; }
+      #detail .x:hover { color: var(--fg); background: #ffffff12; }
+      .d-kind { font-size: 10px; font-weight: 600; letter-spacing: .6px; color: var(--faint);
+        text-transform: uppercase; }
+      .d-who { font-size: 16px; font-weight: 700; line-height: 1.25; padding-right: 26px; }
+      .d-who .role { font-size: 11px; font-weight: 500; color: var(--faint); margin-left: 6px; }
+      .d-status { display: inline-flex; align-items: center; gap: 6px; font-size: 11.5px;
+        font-weight: 500; padding: 3px 10px; border-radius: 20px; background: #ffffff08;
+        color: var(--dim); width: fit-content; }
+      .d-status .dot { width: 7px; height: 7px; border-radius: 50%; background: currentColor;
+        box-shadow: 0 0 6px currentColor; }
+      .d-status.working { background: #16231a; color: var(--working); }
+      .d-status.waiting { background: #2a2117; color: var(--waiting); }
+      .d-status.idle { color: var(--dim); }
+      .d-status.offline { color: var(--faint); }
+      .d-section { display: flex; flex-direction: column; gap: 5px; }
+      .d-label { font-size: 9.5px; font-weight: 600; letter-spacing: .5px; color: var(--faint);
+        text-transform: uppercase; }
+      .d-block { font-size: 12px; line-height: 1.55; padding: 9px 11px; border-radius: 7px;
+        background: #ffffff08; border: 1px solid var(--line); white-space: pre-wrap; word-break: break-word; }
+      .d-block.muted { color: var(--dim); font-style: italic; }
+      .d-rows { display: flex; flex-direction: column; gap: 5px; }
+      .d-row { display: flex; gap: 10px; font-size: 11.5px; line-height: 1.4; }
+      .d-row .k { color: var(--faint); min-width: 64px; flex: none; }
+      .d-row .v { color: var(--fg); word-break: break-word; }
+      .d-msgs { display: flex; flex-direction: column; gap: 5px; }
+      .d-msg { font-size: 11px; line-height: 1.45; padding: 7px 10px 8px; border-radius: 6px;
+        background: #ffffff06; border-left: 2px solid var(--line); }
+      .d-msg .mhead { display: flex; align-items: baseline; gap: 6px; margin-bottom: 3px; }
+      .d-msg .m { font-size: 9px; font-weight: 700; letter-spacing: .3px; text-transform: uppercase; }
+      .d-msg .who { color: var(--fg); font-weight: 600; }
+      .d-msg .tgt { color: var(--dim); }
+      .d-msg .body { color: var(--dim); word-break: break-word; }
+      .d-msg.empty { text-align: center; color: var(--faint); font-style: italic; border-left-color: transparent; }
+      /* member / subscription tag rows in the detail panel */
+      .d-tags { display: flex; flex-wrap: wrap; gap: 5px; }
+      .mtag { display: inline-flex; align-items: center; gap: 6px; font-size: 11px; color: var(--fg);
+        padding: 3px 8px; border-radius: 13px; background: #ffffff08; border: 1px solid var(--line); }
+      .mtag .dot { width: 7px; height: 7px; border-radius: 50%; flex: none; box-shadow: 0 0 5px currentColor; }
+      .mtag .act { font-size: 9px; font-weight: 700; letter-spacing: .3px; text-transform: uppercase; color: var(--chat); }
+      .mtag .off { font-size: 9px; font-weight: 600; letter-spacing: .3px; text-transform: uppercase; color: var(--faint); }
+      .ctag { font-size: 11px; color: var(--chat); padding: 3px 8px; border-radius: 13px;
+        background: #58a6ff14; border: 1px solid #58a6ff33; }
+      .ctag.off { color: var(--dim); background: #ffffff06; border-color: var(--line); }
+      .hint { position: fixed; bottom: 16px; left: 50%; transform: translateX(-50%); z-index: 9;
+        font-size: 11.5px; color: var(--faint); pointer-events: none; transition: opacity .4s; }
+    </style>
+  </head>
+  <body>
+    <canvas id="graph"></canvas>
+
+    <header class="glass">
+      <span class="brand">
+        <span class="mark"></span>
+        <span class="title">Cotal</span>
+        <span class="space" id="space"></span>
+      </span>
+      <a class="navlink" href="/">← Monitor</a>
+      <span class="pill down" id="conn"><span class="d"></span><span class="t">connecting</span></span>
+      <span class="pill off" id="feed" hidden><span class="d"></span><span class="t">membership</span></span>
+      <div class="ctrls">
+        <div class="grp" id="modes">
+          <span class="chip mode chat on" data-mode="chat">channel</span>
+          <span class="chip mode unicast on" data-mode="unicast">direct</span>
+          <span class="chip mode anycast on" data-mode="anycast">anycast</span>
+        </div>
+        <span class="chip pause" id="pause">⏸ pause</span>
+      </div>
+    </header>
+
+    <div id="legend" class="glass">
+      <button class="ltoggle" id="legendToggle" type="button"><span>legend</span><span class="chev">▾</span></button>
+      <div class="lbody">
+        <span class="ls">traffic</span>
+        <span class="row"><span class="sw" style="background:var(--chat)"></span> channel post → hub</span>
+        <span class="row"><span class="sw" style="background:var(--unicast)"></span> direct message</span>
+        <span class="row"><span class="sw sw-dot" style="background:var(--anycast)"></span> anycast (to a role)</span>
+        <span class="ls">membership</span>
+        <span class="row"><span class="sw" style="background:#8493a8"></span> subscribed (live)</span>
+        <span class="row"><span class="sw" style="background:#5a6472;opacity:.7"></span> member · offline</span>
+        <span class="ls">agents</span>
+        <span class="row"><span class="ring" style="color:var(--working)"></span> working</span>
+        <span class="row"><span class="ring" style="color:var(--waiting)"></span> waiting · needs input</span>
+        <span class="row"><span class="ring" style="color:var(--idle)"></span> idle / offline</span>
+      </div>
+    </div>
+
+    <aside id="detail" class="glass"></aside>
+    <div class="hint" id="hint">click a node for detail · scroll to zoom · drag to pan</div>
+
+    <script src="/graph.js"></script>
+  </body>
+</html>