@cotal-ai/workspace 0.10.1 → 0.11.1

package/dist/agent-health.d.ts

@@ -0,0 +1,20 @@
+export interface AgentAuthHealth {
+    state: "ok" | "failed";
+    /** The operator-exact failure sentence (the bearer command's own copy), when failed. */
+    reason?: string;
+    /** ISO timestamp of the attempt. */
+    at: string;
+}
+/** A live managed agent's health, as `ps` should render it. Absence/malformation is AMBIGUOUS, not
+ *  healthy (the preflight writes the first `ok` record before launch, so a live agent always has
+ *  one — a missing file means someone removed it or the record never landed): `auth-unknown`.
+ *  A record past `staleMs` on a live agent means refreshes stopped happening at all (the refresh
+ *  cadence is a few minutes): `auth-stale`. Never silent-healthy. */
+export declare function agentAuthState(path: string, staleMs?: number): {
+    state: "ok" | "auth-renewal-failed" | "auth-unknown" | "auth-stale";
+    reason?: string;
+};
+/** Read + validate an {@link AgentAuthHealth} file. Undefined when absent (no attempt yet) or
+ *  unreadable/malformed (surfaced as unknown by {@link agentAuthState}, never a crash in `ps`). */
+export declare function readAgentAuthHealth(path: string): AgentAuthHealth | undefined;
+//# sourceMappingURL=agent-health.d.ts.map

package/dist/agent-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-health.d.ts","sourceRoot":"","sources":["../src/agent-health.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,IAAI,GAAG,QAAQ,CAAC;IACvB,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;qEAIqE;AACrE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,SAAc,GACpB;IAAE,KAAK,EAAE,IAAI,GAAG,qBAAqB,GAAG,cAAc,GAAG,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAQ1F;AAED;mGACmG;AACnG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAS7E"}

package/dist/agent-health.js

@@ -0,0 +1,40 @@
+/**
+ * A managed user-mode agent's last bearer-refresh outcome — written by the auth provider's bearer
+ * command after EVERY attempt (`--health-file <path>`, the path composed by the manager), read by
+ * the manager's `ps` path. WORKSTATION-layer state (this module is exactly why the workspace tier
+ * exists): the auth implementation writes it, the manager renders it, neither may import the
+ * other, and it is not wire/protocol substance — so it lives here, not in core. A detached agent's
+ * silent bearer death has exactly one operator window — `ps` — and this file is what makes that
+ * window see it.
+ */
+import { readFileSync } from "node:fs";
+/** A live managed agent's health, as `ps` should render it. Absence/malformation is AMBIGUOUS, not
+ *  healthy (the preflight writes the first `ok` record before launch, so a live agent always has
+ *  one — a missing file means someone removed it or the record never landed): `auth-unknown`.
+ *  A record past `staleMs` on a live agent means refreshes stopped happening at all (the refresh
+ *  cadence is a few minutes): `auth-stale`. Never silent-healthy. */
+export function agentAuthState(path, staleMs = 15 * 60_000) {
+    const rec = readAgentAuthHealth(path);
+    if (!rec)
+        return { state: "auth-unknown", reason: "no readable bearer-refresh record - if this persists, respawn the agent" };
+    if (rec.state === "failed")
+        return { state: "auth-renewal-failed", ...(rec.reason ? { reason: rec.reason } : {}) };
+    const age = Date.now() - Date.parse(rec.at);
+    if (!Number.isFinite(age) || age > staleMs)
+        return { state: "auth-stale", reason: `last successful bearer refresh was ${Number.isFinite(age) ? Math.round(age / 60_000) + " min" : "an unreadable time"} ago - the agent may be wedged; respawn it` };
+    return { state: "ok" };
+}
+/** Read + validate an {@link AgentAuthHealth} file. Undefined when absent (no attempt yet) or
+ *  unreadable/malformed (surfaced as unknown by {@link agentAuthState}, never a crash in `ps`). */
+export function readAgentAuthHealth(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if ((parsed.state === "ok" || parsed.state === "failed") && typeof parsed.at === "string")
+            return { state: parsed.state, at: parsed.at, ...(typeof parsed.reason === "string" ? { reason: parsed.reason } : {}) };
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=agent-health.js.map

package/dist/agent-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-health.js","sourceRoot":"","sources":["../src/agent-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAUvC;;;;qEAIqE;AACrE,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,OAAO,GAAG,EAAE,GAAG,MAAM;IAErB,MAAM,GAAG,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,yEAAyE,EAAE,CAAC;IAC9H,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,qBAAqB,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACnH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,OAAO;QACxC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,sCAAsC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,oBAAoB,4CAA4C,EAAE,CAAC;IAC5M,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;mGACmG;AACnG,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAoB,CAAC;QACzE,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ;YACvF,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QACzH,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/auth-paths.d.ts

@@ -1,5 +1,11 @@
 import { type SpaceAuth } from "@cotal-ai/core";
 export declare function authDir(root: string): string;
+/** The SPACE-SCOPED user-auth state dir (`<root>/.cotal/auth/<space>`) — the one layout fact the
+ *  workstation layer owns about user auth: the auth provider persists its material under this dir
+ *  (opaque to us), and its EXISTENCE marks the space as user-auth-enabled on disk. Space-keyed now
+ *  so multi-space-per-root is a caller change, never an on-disk migration; a (broker, space) key
+ *  later extends the same shape. */
+export declare function userAuthStateDir(root: string, space: string): string;
 /** Find the project's `.cotal/` by walking up from `start` (like git finds `.git`), returning the
  *  directory that *contains* `.cotal/`. Falls back to `start` when none is found up the tree (a
  *  fresh setup creates `.cotal/` there). Lets `cotal` run from any subdirectory of a project. */

package/dist/auth-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-paths.d.ts","sourceRoot":"","sources":["../src/auth-paths.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAe9E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;iGAEiG;AACjG,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,CAQnE;AAED;;iGAEiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAIhE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAIhE"}
+{"version":3,"file":"auth-paths.d.ts","sourceRoot":"","sources":["../src/auth-paths.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAe9E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;oCAIoC;AACpC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;iGAEiG;AACjG,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,CAQnE;AAED;;iGAEiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAIhE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAIhE"}

package/dist/auth-paths.js

@@ -15,6 +15,14 @@ const AUTH_FILE = "auth.json";
 export function authDir(root) {
     return join(root, ".cotal", "auth");
 }
+/** The SPACE-SCOPED user-auth state dir (`<root>/.cotal/auth/<space>`) — the one layout fact the
+ *  workstation layer owns about user auth: the auth provider persists its material under this dir
+ *  (opaque to us), and its EXISTENCE marks the space as user-auth-enabled on disk. Space-keyed now
+ *  so multi-space-per-root is a caller change, never an on-disk migration; a (broker, space) key
+ *  later extends the same shape. */
+export function userAuthStateDir(root, space) {
+    return join(authDir(root), encodeURIComponent(space));
+}
 /** Find the project's `.cotal/` by walking up from `start` (like git finds `.git`), returning the
  *  directory that *contains* `.cotal/`. Falls back to `start` when none is found up the tree (a
  *  fresh setup creates `.cotal/` there). Lets `cotal` run from any subdirectory of a project. */

package/dist/auth-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-paths.js","sourceRoot":"","sources":["../src/auth-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAkB,MAAM,gBAAgB,CAAC;AAE9E;;;;;;;;;GASG;AAEH,MAAM,SAAS,GAAG,WAAW,CAAC;AAE9B,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC;AAED;;iGAEiG;AACjG,MAAM,UAAU,aAAa,CAAC,QAAgB,OAAO,CAAC,GAAG,EAAE;IACzD,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;QAC1C,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED;;iGAEiG;AACjG,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAe;IACxD,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,iFAAiF;IACnG,MAAM,MAAM,GAAc,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC;IACrF,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/B,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAc,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"auth-paths.js","sourceRoot":"","sources":["../src/auth-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAkB,MAAM,gBAAgB,CAAC;AAE9E;;;;;;;;;GASG;AAEH,MAAM,SAAS,GAAG,WAAW,CAAC;AAE9B,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC;AAED;;;;oCAIoC;AACpC,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,KAAa;IAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;iGAEiG;AACjG,MAAM,UAAU,aAAa,CAAC,QAAgB,OAAO,CAAC,GAAG,EAAE;IACzD,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;QAC1C,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED;;iGAEiG;AACjG,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAe;IACxD,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,iFAAiF;IACnG,MAAM,MAAM,GAAc,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC;IACrF,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/B,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAc,CAAC;AAC1D,CAAC"}

package/dist/colors.d.ts

@@ -1,5 +1,5 @@
 /** ANSI color helpers for operator-facing terminal output — shared by every command surface
- *  (@cotal-ai/cli, cotal-web) so they render identically. Workstation-layer
+ *  (@cotal-ai/cli, @cotal-ai/web) so they render identically. Workstation-layer
  *  concern: the wire protocol in core never prints. */
 export declare const c: {
     dim: (s: string) => string;

package/dist/colors.js

@@ -1,5 +1,5 @@
 /** ANSI color helpers for operator-facing terminal output — shared by every command surface
- *  (@cotal-ai/cli, cotal-web) so they render identically. Workstation-layer
+ *  (@cotal-ai/cli, @cotal-ai/web) so they render identically. Workstation-layer
  *  concern: the wire protocol in core never prints. */
 export const c = {
     dim: (s) => `\x1b[2m${s}\x1b[0m`,

package/dist/connect.d.ts

@@ -1,8 +1,9 @@
 import { type Profile, type SpaceAuth } from "@cotal-ai/core";
+import { type UserAuthInfo } from "./mesh-registry.js";
 import { type MeshTarget } from "./mesh-target.js";
 /**
  * The one way every command that touches a running mesh figures out WHICH mesh + with what creds,
- * and confirms it's actually up — shared by every command surface (@cotal-ai/cli, cotal-web)
+ * and confirms it's actually up — shared by every command surface (@cotal-ai/cli, @cotal-ai/web)
  * so `spawn`, `send`, `console`, `web`, … all behave identically from any
  * directory. The pure resolution/probe/classify/render steps live beside this file; these wrappers
  * own the OPERATOR I/O — they colour, print the command-copy line, and exit the process. That is
@@ -30,6 +31,13 @@ export interface Connection {
     server: string;
     space: string;
     creds?: string;
+    /** USER-MODE connect material (mode `"user"` only): the Cotal user bearer + the deny-all
+     *  sentinel creds, exactly what `EndpointOptions.bearer`/`sentinelCreds` consume. Mutually
+     *  exclusive with `creds` — spread {@link endpointAuth} instead of reading either directly. */
+    bearer?: string;
+    sentinelCreds?: string;
+    /** The user-auth registry metadata, when this is a user-mode connection. */
+    userAuth?: UserAuthInfo;
     /** 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.) */
@@ -42,11 +50,48 @@ export interface Connection {
     /** How the target was resolved (registry / current / flag-space / …) — undefined for raw. */
     source?: MeshTarget["source"];
 }
+/** The one way a command turns a {@link Connection} into endpoint auth options — spread this into
+ *  `new CotalEndpoint({...})` instead of passing `creds:` directly, so a user-mode connection
+ *  (bearer + sentinel) and a static/raw one (creds) ride the same call sites without each command
+ *  re-learning the mode split. */
+export declare function endpointAuth(conn: Connection): {
+    creds?: string;
+    bearer?: string;
+    sentinelCreds?: string;
+};
+/** The ledger actor a HUMAN CLI connect runs as on a user-auth space (v1: one well-known name).
+ *  Grant it once per user: `cotal actor grant cli --sub <your IdP subject>`. */
+export declare const CLI_USER_ACTOR = "cli";
+/** The auth material for one ELEVATED user-mode connection (a "view"): bearer + sentinel for the
+ *  endpoint or a standalone helper, the bearer's own principal (a bearer-SOURCE endpoint needs it
+ *  pinned up front), and a fresh-mint source for standing taps (each call is a full login→exchange
+ *  round, so every refresh is a fresh ledger check). */
+export interface UserViewAuth {
+    bearer: string;
+    sentinelCreds: string;
+    owner: string;
+    actor: string;
+    source: () => Promise<string>;
+}
+/** Mint an elevated-view bearer over an existing user-mode {@link Connection} — the user-mode
+ *  path for the operator surfaces (`web`, `console`, `history clear`, `channels`, `spawn -f`).
+ *  The view is authorized server-side against the fresh ledger row; a refusal THROWS the exact
+ *  re-grant sentence. Call ONLY with a user-mode connection (`conn.bearer` set) — anything else
+ *  is a caller bug. Long-running servers (the web delete handler) call THIS and surface the
+ *  thrown sentence; CLI startup paths use {@link userViewAuthOrExit}. */
+export declare function userViewAuth(conn: Connection, view: string): Promise<UserViewAuth>;
+/** {@link userViewAuth}, workstation-flavoured: colour the thrown sentence and exit. */
+export declare function userViewAuthOrExit(conn: Connection, view: string): Promise<UserViewAuth>;
+/** Fail-closed guard for the flip: explicit raw creds are still useful for true off-registry/static
+ *  meshes, but not for a user-auth mesh this machine KNOWS about. Otherwise an old static
+ *  `local.<nkey>` creds file can bypass the user-mode branch and publish/join through raw `--creds`.
+ *  Registry match covers cross-directory use; the on-disk marker covers a lost/stale registry. */
+export declare function refuseStaticCredsForKnownUserAuthOrExit(space: string, server: string | undefined, what: string): void;
 /**
  * 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).
+ *  • Explicit `--creds` → a RAW off-registry connection, except when the target is a known
+ *    per-user-auth mesh. Those refuse static creds fail-closed because old local creds remain
+ *    broker-valid but are the wrong identity plane after the flip.
  *  • 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.
  */

package/dist/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAI9F;;;;;;;;;;GAUG;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;IACjB;;;oGAGgG;IAChG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;CAC/B;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,CAKvF;AAED;;;;;+EAK+E;AAC/E,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBtB;AAED;;;;;0BAK0B;AAC1B,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5F"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"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"}

package/dist/connect.js

@@ -1,22 +1,109 @@
-import { readFileSync } from "node:fs";
-import { DEFAULT_SERVER, DEFAULT_SPACE, mintCreds, newIdentity, probeConnect, } from "@cotal-ai/core";
+import { existsSync, readFileSync } from "node:fs";
+import { DEFAULT_SERVER, DEFAULT_SPACE, isReachable, mintCreds, newIdentity, probeConnect, registry, } from "@cotal-ai/core";
 import { c } from "./colors.js";
+import { findCotalRoot, userAuthStateDir } from "./auth-paths.js";
 import { findMesh, getCurrent, removeMesh } from "./mesh-registry.js";
 import { isWorkspaceTargetError, resolveMeshTarget } from "./mesh-target.js";
 import { preflightTarget, pruneStaleMeshes } from "./preflight.js";
 import { renderWorkspaceError } from "./render.js";
+/** The one way a command turns a {@link Connection} into endpoint auth options — spread this into
+ *  `new CotalEndpoint({...})` instead of passing `creds:` directly, so a user-mode connection
+ *  (bearer + sentinel) and a static/raw one (creds) ride the same call sites without each command
+ *  re-learning the mode split. */
+export function endpointAuth(conn) {
+    if (conn.bearer && conn.sentinelCreds)
+        return { bearer: conn.bearer, sentinelCreds: conn.sentinelCreds };
+    return conn.creds !== undefined ? { creds: conn.creds } : {};
+}
+/** The ledger actor a HUMAN CLI connect runs as on a user-auth space (v1: one well-known name).
+ *  Grant it once per user: `cotal actor grant cli --sub <your IdP subject>`. */
+export const CLI_USER_ACTOR = "cli";
+/** Mint an elevated-view bearer over an existing user-mode {@link Connection} — the user-mode
+ *  path for the operator surfaces (`web`, `console`, `history clear`, `channels`, `spawn -f`).
+ *  The view is authorized server-side against the fresh ledger row; a refusal THROWS the exact
+ *  re-grant sentence. Call ONLY with a user-mode connection (`conn.bearer` set) — anything else
+ *  is a caller bug. Long-running servers (the web delete handler) call THIS and surface the
+ *  thrown sentence; CLI startup paths use {@link userViewAuthOrExit}. */
+export async function userViewAuth(conn, view) {
+    if (!conn.bearer || !conn.userAuth || !conn.root)
+        throw new Error(`userViewAuth: not a user-mode registry connection (view "${view}")`);
+    const ua = conn.userAuth;
+    let provider;
+    try {
+        provider = registry.resolve("auth-provider", ua.provider);
+    }
+    catch {
+        throw new Error(`space "${conn.space}" uses the "${ua.provider}" auth provider, which this build does not register - user-auth spaces need it (the official cotal binary includes @cotal-ai/auth)`);
+    }
+    const dir = userAuthStateDir(conn.root, conn.space);
+    const mint = () => provider.userCredentials({ dir, space: conn.space, actor: CLI_USER_ACTOR, view });
+    const { bearer, sentinelCreds } = await mint();
+    const { owner, actor } = principalFromBearer(bearer);
+    return { bearer, sentinelCreds, owner, actor, source: () => mint().then((r) => r.bearer) };
+}
+/** {@link userViewAuth}, workstation-flavoured: colour the thrown sentence and exit. */
+export async function userViewAuthOrExit(conn, view) {
+    try {
+        return await userViewAuth(conn, view);
+    }
+    catch (e) {
+        console.error(c.red(`✗ ${e instanceof Error ? e.message : String(e)}`));
+        process.exit(1);
+    }
+}
+/** The (owner, actor) principal a minted bearer is bound to — read from the JWT payload WITHOUT
+ *  verification (client side; the broker verifies). A bearer-source endpoint requires the principal
+ *  pinned at construction, and the bearer is the one authoritative place it lives. */
+function principalFromBearer(bearer) {
+    try {
+        const mid = bearer.split(".")[1];
+        if (!mid)
+            throw new Error("not a compact JWS");
+        const payload = JSON.parse(Buffer.from(mid, "base64url").toString("utf8"));
+        if (typeof payload.sub !== "string" || !payload.sub || typeof payload.act?.actor !== "string" || !payload.act.actor)
+            throw new Error("missing sub/act.actor");
+        return { owner: payload.sub, actor: payload.act.actor };
+    }
+    catch (e) {
+        throw new Error(`could not read the principal from the minted bearer (${e instanceof Error ? e.message : String(e)}) - the auth service's build may be stale; restart it with \`cotal up\``);
+    }
+}
+/** Fail-closed guard for the flip: explicit raw creds are still useful for true off-registry/static
+ *  meshes, but not for a user-auth mesh this machine KNOWS about. Otherwise an old static
+ *  `local.<nkey>` creds file can bypass the user-mode branch and publish/join through raw `--creds`.
+ *  Registry match covers cross-directory use; the on-disk marker covers a lost/stale registry. */
+export function refuseStaticCredsForKnownUserAuthOrExit(space, server, what) {
+    const recorded = findMesh(space);
+    const knownRecordedUser = recorded?.mode === "user" && (server === undefined || recorded.server === server);
+    const knownLocalUser = existsSync(userAuthStateDir(findCotalRoot(), space));
+    if (!knownRecordedUser && !knownLocalUser)
+        return;
+    console.error(c.red(`✗ ${what} tried to authenticate with a static creds file, but space "${space}" is a per-user-auth mesh - old --creds files are refused here so they can't bypass user accounts.`));
+    console.error(c.dim(`  Sign in with \`cotal login\` and use the user-mode path instead (for agents: \`cotal spawn\`).`));
+    process.exit(1);
+}
 /**
  * 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).
+ *  • Explicit `--creds` → a RAW off-registry connection, except when the target is a known
+ *    per-user-auth mesh. Those refuse static creds fail-closed because old local creds remain
+ *    broker-valid but are the wrong identity plane after the flip.
  *  • 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;
+        // Run the flip guard with the RAW `--server` (may be undefined). The guard treats "no --server"
+        // as "any recorded server for this space", so a user mesh on a NON-default port is still
+        // recognized when the caller omits --server. Defaulting the server BEFORE the guard would make
+        // its `recorded.server === server` match miss every non-4222 user mesh, letting a static --creds
+        // slip past the flip.
+        refuseStaticCredsForKnownUserAuthOrExit(space, flags.server, "--creds");
+        const server = flags.server ?? DEFAULT_SERVER;
+        if (!existsSync(flags.creds)) {
+            console.error(c.red(`✗ creds file not found: ${flags.creds}`));
+            process.exit(1);
+        }
         const creds = readFileSync(flags.creds, "utf8");
         await reachableOrExit(server, { creds });
         return { server, space, creds };
@@ -26,14 +113,64 @@ export async function connectOrExit(flags, role) {
     // 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)) {
+        // Fail-closed marker, same posture as the resolver's: this machine may hold USER-AUTH state
+        // for that very space even when the registry lost (or never had) the entry — treating it as an
+        // open broker would credless-connect into a callout denial whose copy sends the operator
+        // port-hunting. Name the real state and the recovery instead.
+        if (existsSync(userAuthStateDir(findCotalRoot(), flags.space))) {
+            console.error(c.red(`✗ space "${flags.space}" has user auth enabled on disk but no usable registry entry - re-record it with \`cotal up\` from its project folder, then sign in (\`cotal login\`)`));
+            process.exit(1);
+        }
         await reachableOrExit(flags.server, {});
         return { server: flags.server, space: flags.space };
     }
     const target = await resolveTargetOrExit({ server: flags.server, space: flags.space });
+    // USER MODE is a HARD branch: it never mints from on-disk trust material (static creds DO work
+    // on a user-auth broker — minting here would silently connect the operator on the wrong identity
+    // plane) and never connects credlessly. Everything it needs comes from the login cache + the
+    // provider's space-scoped state; every failure is one sentence with the exact operator action.
+    if (target.mode === "user")
+        return userConnectOrExit(target);
     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, root: target.root, source: target.source };
 }
+/** The user-mode connect: resolve the space's auth provider from the registry (composition-root
+ *  supplied — never imported here), exchange this machine's login session for a bearer, and hand
+ *  back bearer + sentinel. The provider owns the failure copy for its own steps (not logged in,
+ *  service down, actor ungranted) — each is already an exact recovery sentence; this wrapper only
+ *  colours and exits (the workstation-layer contract). */
+async function userConnectOrExit(target) {
+    const ua = target.userAuth; // mode "user" guarantees it (targetFromEntry throws otherwise)
+    let provider;
+    try {
+        provider = registry.resolve("auth-provider", ua.provider);
+    }
+    catch {
+        console.error(c.red(`✗ space "${target.space}" uses the "${ua.provider}" auth provider, which this build does not register - user-auth spaces need it (the official cotal binary includes @cotal-ai/auth)`));
+        process.exit(1);
+    }
+    try {
+        const { bearer, sentinelCreds } = await provider.userCredentials({
+            dir: userAuthStateDir(target.root, target.space),
+            space: target.space,
+            actor: CLI_USER_ACTOR,
+        });
+        return {
+            server: target.server,
+            space: target.space,
+            bearer,
+            sentinelCreds,
+            userAuth: ua,
+            root: target.root,
+            source: target.source,
+        };
+    }
+    catch (e) {
+        console.error(c.red(`✗ ${e instanceof Error ? e.message : String(e)}`));
+        process.exit(1);
+    }
+}
 /** 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. */
@@ -69,7 +206,7 @@ export async function resolveTargetOrExit(flags) {
     // 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}"`));
+        console.error(c.dim(`note: default mesh "${cur}" is down - using "${target.space}"`));
     return target;
 }
 /** Confirm the resolved mesh is up and accepts these creds — replaces the raw NATS "Authorization
@@ -79,6 +216,17 @@ export async function resolveTargetOrExit(flags) {
  *  caller's `--creds`/minted creds); otherwise a throwaway identity is minted from the target's
  *  own trust material. */
 export async function preflightOrExit(target, probeCreds) {
+    // USER-mode targets are never credless-probed here: the callout denies a bare connect, the
+    // classifier reads that as a stale registry entry, and the PRUNE deletes a healthy mesh's
+    // record (found live: foreground `spawn` did exactly this and every later command fell into
+    // raw-path copy). Liveness is the only mode-blind read; the real auth preflight for a user
+    // target is the user connect / bearer chain itself.
+    if (target.mode === "user") {
+        if (await isReachable(target.server))
+            return;
+        console.error(c.red(`✗ mesh "${target.space}" at ${target.server} is not reachable - start it with \`cotal up\` from its project folder`));
+        process.exit(1);
+    }
     const r = await preflightTarget(target, probeCreds);
     if (r.ok)
         return;

package/dist/connect.js.map

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

package/dist/extensions.js

@@ -19,7 +19,7 @@ export function loadExtensionsManifest() {
         parsed = JSON.parse(readFileSync(p, "utf8"));
     }
     catch (e) {
-        throw new Error(`corrupt extensions manifest ${p}: ${e.message} — fix or delete it, then \`cotal ext add\` again`);
+        throw new Error(`corrupt extensions manifest ${p}: ${e.message} - fix or delete it, then \`cotal ext add\` again`);
     }
     const m = parsed;
     if (!Array.isArray(m.extensions))

package/dist/flags.d.ts

@@ -79,6 +79,12 @@ export declare const launchFlags: readonly [{
     readonly type: "string";
     readonly value: "<v>";
     readonly description: "model variant override (connector-defined; wins over the agent file's variant:)";
+}, {
+    readonly name: "opt";
+    readonly type: "string";
+    readonly multiple: true;
+    readonly value: "<k=v>";
+    readonly description: "connector-specific launch option (repeatable); wins per-key over the agent file's launchOptions:";
 }, {
     readonly name: "cwd";
     readonly type: "string";
@@ -123,4 +129,13 @@ export declare const launchFlags: readonly [{
     readonly value: "<a,b>";
     readonly description: "post ACL override";
 }];
+/** Parse repeated `--opt key=value` pairs into the opaque launch-options map. The key is the text
+ *  before the first `=`; the value is the remainder (may itself contain `=`). Fails loud on a
+ *  missing `=`, an empty key, or a duplicate key — never silent last-wins. Values are strings (the
+ *  CLI has no types); the consuming connector coerces. Returns undefined when there are none. */
+export declare function parseLaunchOptions(pairs: string[] | undefined): Record<string, string> | undefined;
+/** Merge two opaque launch-option maps per key — `override` (e.g. a `--opt` flag) wins over `base`
+ *  (e.g. the persona file's `launchOptions:`), mirroring how `--model`/`--variant` beat the file.
+ *  Returns undefined when the result is empty, so an absent bag never becomes an empty object. */
+export declare function mergeLaunchOptions(base: Record<string, unknown> | undefined, override: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
 //# sourceMappingURL=flags.d.ts.map

package/dist/flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;;;;CAAwI,CAAC;AAC/J,eAAO,MAAM,UAAU;;;;;CAAgJ,CAAC;AACxK,eAAO,MAAM,SAAS;;;;;CAA2I,CAAC;AAElK;;+BAE+B;AAC/B,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;EAA4E,CAAC;AAErG;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBgB,CAAC"}
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;;;;CAAwI,CAAC;AAC/J,eAAO,MAAM,UAAU;;;;;CAAgJ,CAAC;AACxK,eAAO,MAAM,SAAS;;;;;CAA2I,CAAC;AAElK;;+BAE+B;AAC/B,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;EAA4E,CAAC;AAErG;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBgB,CAAC;AAEzC;;;iGAGiG;AACjG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAYlG;AAED;;kGAEkG;AAClG,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAIrC"}

package/dist/flags.js

@@ -26,6 +26,7 @@ export const launchFlags = [
     { name: "role", type: "string", value: "<r>", description: "role override (wins over the agent file's role:)" },
     { name: "model", type: "string", value: "<m>", description: "model override (wins over the agent file's model:)" },
     { name: "variant", type: "string", value: "<v>", description: "model variant override (connector-defined; wins over the agent file's variant:)" },
+    { name: "opt", type: "string", multiple: true, value: "<k=v>", description: "connector-specific launch option (repeatable); wins per-key over the agent file's launchOptions:" },
     { name: "cwd", type: "string", value: "<dir>", description: "working directory to root the agent at" },
     { name: "prompt", type: "string", value: "<text>", description: "initial prompt auto-submitted at start" },
     { name: "resume", type: "string", value: "<id>", description: "fork an existing session id into the mesh (claude only; detached: pair with --cwd)" },
@@ -36,4 +37,34 @@ export const launchFlags = [
     { name: "allow-subscribe", type: "string", value: "<a,b>", description: "read ACL override" },
     { name: "allow-publish", type: "string", value: "<a,b>", description: "post ACL override" },
 ];
+/** Parse repeated `--opt key=value` pairs into the opaque launch-options map. The key is the text
+ *  before the first `=`; the value is the remainder (may itself contain `=`). Fails loud on a
+ *  missing `=`, an empty key, or a duplicate key — never silent last-wins. Values are strings (the
+ *  CLI has no types); the consuming connector coerces. Returns undefined when there are none. */
+export function parseLaunchOptions(pairs) {
+    if (!pairs?.length)
+        return undefined;
+    const out = {};
+    for (const raw of pairs) {
+        const eq = raw.indexOf("=");
+        if (eq === -1)
+            throw new Error(`--opt must be key=value (got "${raw}")`);
+        const key = raw.slice(0, eq).trim();
+        if (!key)
+            throw new Error(`--opt has an empty key (got "${raw}")`);
+        if (key in out)
+            throw new Error(`--opt "${key}" given more than once`);
+        out[key] = raw.slice(eq + 1);
+    }
+    return out;
+}
+/** Merge two opaque launch-option maps per key — `override` (e.g. a `--opt` flag) wins over `base`
+ *  (e.g. the persona file's `launchOptions:`), mirroring how `--model`/`--variant` beat the file.
+ *  Returns undefined when the result is empty, so an absent bag never becomes an empty object. */
+export function mergeLaunchOptions(base, override) {
+    if (!base && !override)
+        return undefined;
+    const merged = { ...base, ...override };
+    return Object.keys(merged).length ? merged : undefined;
+}
 //# sourceMappingURL=flags.js.map

package/dist/flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,2CAA2C,EAA8B,CAAC;AAC/J,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,gDAAgD,EAA8B,CAAC;AACxK,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,2CAA2C,EAA8B,CAAC;AAElK;;+BAE+B;AAC/B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAwC,CAAC;AAErG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,qDAAqD,EAAE;IAClH,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,wEAAwE,EAAE;IACrJ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,gFAAgF,EAAE;IAC9I,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,kDAAkD,EAAE;IAC/G,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,oDAAoD,EAAE;IAClH,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,iFAAiF,EAAE;IACjJ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,wCAAwC,EAAE;IACtG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,wCAAwC,EAAE;IAC1G,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,oFAAoF,EAAE;IACpJ,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,4CAA4C,EAAE;IAClG,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,wCAAwC,EAAE;IACjG,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,iDAAiD,EAAE;IACvH,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,2BAA2B,EAAE;IAC/F,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE;IAC7F,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE;CACrD,CAAC"}
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,2CAA2C,EAA8B,CAAC;AAC/J,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,gDAAgD,EAA8B,CAAC;AACxK,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,2CAA2C,EAA8B,CAAC;AAElK;;+BAE+B;AAC/B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAwC,CAAC;AAErG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,qDAAqD,EAAE;IAClH,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,wEAAwE,EAAE;IACrJ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,gFAAgF,EAAE;IAC9I,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,kDAAkD,EAAE;IAC/G,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,oDAAoD,EAAE;IAClH,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,iFAAiF,EAAE;IACjJ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,kGAAkG,EAAE;IAChL,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,wCAAwC,EAAE;IACtG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,wCAAwC,EAAE;IAC1G,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,oFAAoF,EAAE;IACpJ,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,4CAA4C,EAAE;IAClG,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,wCAAwC,EAAE;IACjG,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,iDAAiD,EAAE;IACvH,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,2BAA2B,EAAE;IAC/F,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE;IAC7F,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE;CACrD,CAAC;AAEzC;;;iGAGiG;AACjG,MAAM,UAAU,kBAAkB,CAAC,KAA2B;IAC5D,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,IAAI,CAAC,CAAC;QACzE,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;QACnE,IAAI,GAAG,IAAI,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAAC;QACvE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;kGAEkG;AAClG,MAAM,UAAU,kBAAkB,CAChC,IAAyC,EACzC,QAA6C;IAE7C,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./auth-paths.js";
+export * from "./agent-health.js";
 export * from "./bin-path.js";
 export * from "./colors.js";
 export * from "./connect.js";
@@ -10,5 +11,6 @@ export * from "./mesh-registry.js";
 export * from "./mesh-target.js";
 export * from "./preflight.js";
 export * from "./render.js";
+export * from "./renewal.js";
 export * from "./space.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./auth-paths.js";
+export * from "./agent-health.js";
 export * from "./bin-path.js";
 export * from "./colors.js";
 export * from "./connect.js";
@@ -10,5 +11,6 @@ export * from "./mesh-registry.js";
 export * from "./mesh-target.js";
 export * from "./preflight.js";
 export * from "./render.js";
+export * from "./renewal.js";
 export * from "./space.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}