@cotal-ai/workspace 0.9.1 → 0.10.1

package/dist/colors.d.ts

@@ -0,0 +1,16 @@
+/** ANSI color helpers for operator-facing terminal output — shared by every command surface
+ *  (@cotal-ai/cli, cotal-web) so they render identically. Workstation-layer
+ *  concern: the wire protocol in core never prints. */
+export declare const c: {
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    green: (s: string) => string;
+    cyan: (s: string) => string;
+    yellow: (s: string) => string;
+    red: (s: string) => string;
+    magenta: (s: string) => string;
+    gray: (s: string) => string;
+};
+/** 256-color foreground wrapper (xterm color index 0-255). */
+export declare const color256: (n: number) => (s: string) => string;
+//# sourceMappingURL=colors.d.ts.map

package/dist/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;uDAEuD;AACvD,eAAO,MAAM,CAAC;aACH,MAAM;cACL,MAAM;eACL,MAAM;cACP,MAAM;gBACJ,MAAM;aACT,MAAM;iBACF,MAAM;cACT,MAAM;CACjB,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,MAAM,GAAG,MAAM,WAAiC,CAAC"}

package/dist/colors.js

@@ -0,0 +1,16 @@
+/** ANSI color helpers for operator-facing terminal output — shared by every command surface
+ *  (@cotal-ai/cli, cotal-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`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    magenta: (s) => `\x1b[35m${s}\x1b[0m`,
+    gray: (s) => `\x1b[90m${s}\x1b[0m`,
+};
+/** 256-color foreground wrapper (xterm color index 0-255). */
+export const color256 = (n) => (s) => `\x1b[38;5;${n}m${s}\x1b[0m`;
+//# sourceMappingURL=colors.js.map

package/dist/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;uDAEuD;AACvD,MAAM,CAAC,MAAM,CAAC,GAAG;IACf,GAAG,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS;IACxC,IAAI,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS;IACzC,KAAK,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS;IAC3C,IAAI,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS;IAC1C,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS;IAC5C,GAAG,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS;IACzC,OAAO,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS;IAC7C,IAAI,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS;CAC3C,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC"}

package/dist/connect.d.ts

@@ -0,0 +1,75 @@
+import { type Profile, type SpaceAuth } from "@cotal-ai/core";
+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)
+ * 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
+ * deliberate: this is the workstation layer, not the wire library (core never prints or exits).
+ * 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;
+    /** The resolved mesh's recorded checkout root, for a REGISTERED mesh — undefined for a raw
+     *  off-registry connection (`--creds`, or `--server`+unregistered `--space`). `spawn -f`/`down -f`
+     *  use it to enforce the same-checkout invariant: local launch artifacts + the ledger live under
+     *  this checkout, so deploying onto a mesh recorded by another checkout would decouple them. */
+    root?: string;
+    /** How the target was resolved (registry / current / flag-space / …) — undefined for raw. */
+    source?: MeshTarget["source"];
+}
+/**
+ * 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 appear in the "pick one" list — but ONLY when resolving without an
+ *  explicit `--space`. A named `--space` is resolved + preflighted directly, so pre-pruning can't
+ *  erase a dead-recorded mesh the operator is recovering with a live `--server` override; preflight
+ *  still prunes it (with the friendly message) when no override revives it. */
+export declare function resolveTargetOrExit(flags: {
+    server?: string;
+    space?: string;
+}): Promise<MeshTarget>;
+/** 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.
+ *  The probe + classify + render live beside this file; this wrapper owns the operator I/O — it
+ *  acts on the prune decision, colours, and exits. Probes with `probeCreds` when given (the
+ *  caller's `--creds`/minted creds); otherwise a throwaway identity is minted from the target's
+ *  own trust material. */
+export declare function preflightOrExit(target: MeshTarget, probeCreds?: string): Promise<void>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +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"}

package/dist/connect.js

@@ -0,0 +1,90 @@
+import { readFileSync } from "node:fs";
+import { DEFAULT_SERVER, DEFAULT_SPACE, mintCreds, newIdentity, probeConnect, } from "@cotal-ai/core";
+import { c } from "./colors.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";
+/**
+ * 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, root: target.root, source: target.source };
+}
+/** 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(renderWorkspaceError({ kind: "reachable", reason: probe.reason, server })));
+    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 appear in the "pick one" list — but ONLY when resolving without an
+ *  explicit `--space`. A named `--space` is resolved + preflighted directly, so pre-pruning can't
+ *  erase a dead-recorded mesh the operator is recovering with a live `--server` override; preflight
+ *  still prunes it (with the friendly message) when no override revives it. */
+export async function resolveTargetOrExit(flags) {
+    if (!flags.space)
+        await pruneStaleMeshes();
+    let target;
+    try {
+        target = resolveMeshTarget(process.cwd(), flags);
+    }
+    catch (e) {
+        if (isWorkspaceTargetError(e)) {
+            console.error(c.red(renderWorkspaceError({ kind: "target", error: e })));
+            process.exit(1);
+        }
+        throw e;
+    }
+    // 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;
+}
+/** 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.
+ *  The probe + classify + render live beside this file; this wrapper owns the operator I/O — it
+ *  acts on the prune decision, colours, and exits. Probes with `probeCreds` when given (the
+ *  caller's `--creds`/minted creds); otherwise a throwaway identity is minted from the target's
+ *  own trust material. */
+export async function preflightOrExit(target, probeCreds) {
+    const r = await preflightTarget(target, probeCreds);
+    if (r.ok)
+        return;
+    if (r.prune)
+        removeMesh(target.space);
+    console.error(c.red(renderWorkspaceError({ kind: "preflight", failure: r.kind, target, pruned: r.prune })));
+    process.exit(1);
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

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

package/dist/default-agent.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_AGENT_ENV = "COTAL_DEFAULT_AGENT";
+export declare const DEFAULT_PERSONA_ENV = "COTAL_DEFAULT_PERSONA";
+/** The operator-level default connector/agent harness, when set. */
+export declare function defaultAgentOverride(env?: NodeJS.ProcessEnv): string | undefined;
+/** Resolve the default connector/agent harness with the product fallback for this launch path. */
+export declare function defaultAgentType(fallback: string, env?: NodeJS.ProcessEnv): string;
+/** The operator-level default persona ref (catalog name or path), when set. */
+export declare function defaultPersonaOverride(env?: NodeJS.ProcessEnv): string | undefined;
+/** Resolve the default persona ref with the product fallback. */
+export declare function defaultPersonaRef(fallback?: string, env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=default-agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"default-agent.d.ts","sourceRoot":"","sources":["../src/default-agent.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AACvD,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAE7F;AAED,kGAAkG;AAClG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE/F;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAE/F;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,QAAQ,SAAY,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEpG"}

package/dist/default-agent.js

@@ -0,0 +1,19 @@
+export const DEFAULT_AGENT_ENV = "COTAL_DEFAULT_AGENT";
+export const DEFAULT_PERSONA_ENV = "COTAL_DEFAULT_PERSONA";
+/** The operator-level default connector/agent harness, when set. */
+export function defaultAgentOverride(env = process.env) {
+    return env[DEFAULT_AGENT_ENV]?.trim() || undefined;
+}
+/** Resolve the default connector/agent harness with the product fallback for this launch path. */
+export function defaultAgentType(fallback, env = process.env) {
+    return defaultAgentOverride(env) ?? fallback;
+}
+/** The operator-level default persona ref (catalog name or path), when set. */
+export function defaultPersonaOverride(env = process.env) {
+    return env[DEFAULT_PERSONA_ENV]?.trim() || undefined;
+}
+/** Resolve the default persona ref with the product fallback. */
+export function defaultPersonaRef(fallback = "default", env = process.env) {
+    return defaultPersonaOverride(env) ?? fallback;
+}
+//# sourceMappingURL=default-agent.js.map

package/dist/default-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-agent.js","sourceRoot":"","sources":["../src/default-agent.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE3D,oEAAoE;AACpE,MAAM,UAAU,oBAAoB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACvE,OAAO,GAAG,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;AACrD,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,MAAyB,OAAO,CAAC,GAAG;IACrF,OAAO,oBAAoB,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC;AAC/C,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACzE,OAAO,GAAG,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;AACvD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,iBAAiB,CAAC,QAAQ,GAAG,SAAS,EAAE,MAAyB,OAAO,CAAC,GAAG;IAC1F,OAAO,sBAAsB,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC;AACjD,CAAC"}

package/dist/extensions.d.ts

@@ -0,0 +1,52 @@
+import type { Command, FlagSpec } from "@cotal-ai/core";
+/**
+ * Operator-installed CLI extensions (`cotal ext add <npm-package>`): the workstation state.
+ *
+ * Extensions install into a cotal-owned npm prefix (`$XDG_CONFIG_HOME/cotal/extensions/`, with
+ * its own package.json) — never the user's project. A MANIFEST records each installed package
+ * plus a CACHE of the command metadata it contributed. Two hard rules from the design review:
+ *
+ *  - The manifest is a DISPLAY/TAB cache ONLY. Help and `__complete` read it (so a <TAB> never
+ *    imports an extension), but at dispatch the freshly-imported command's LIVE specs are
+ *    authoritative — cached specs never drive parsing (version skew would corrupt `run`'s input).
+ *  - `name@version` is pinned at add time and verified at run-import; a mismatch is a loud error
+ *    prescribing `cotal ext add` again — never a silent re-cache.
+ */
+/** One cached command: the JSON-serializable display surface of a {@link Command} (its `run` /
+ *  `complete` functions stay in the package — the cache can render help and offer flag names,
+ *  nothing more). */
+export interface CachedCommand {
+    readonly name: string;
+    readonly summary: string;
+    readonly group?: string;
+    readonly usage?: string;
+    readonly hidden?: boolean;
+    readonly flags?: readonly FlagSpec[];
+    readonly positionals?: string;
+}
+export interface InstalledExtension {
+    /** The npm package name (the import + `node_modules` key). */
+    readonly pkg: string;
+    /** Exact installed version, pinned at add time and verified at run-import. */
+    readonly version: string;
+    /** The spec the operator passed to `ext add` (registry range, file:, tarball…) — for re-adds. */
+    readonly spec: string;
+    readonly commands: readonly CachedCommand[];
+}
+export interface ExtensionsManifest {
+    readonly extensions: readonly InstalledExtension[];
+}
+/** The extensions prefix: `<config>/cotal/extensions` — its own npm installation root. */
+export declare function extensionsDir(): string;
+export declare function extensionsManifestPath(): string;
+/** Load the manifest. Missing file → no extensions. A CORRUPT file is a loud error (never treat
+ *  installed extensions as absent — commands would silently vanish from help). */
+export declare function loadExtensionsManifest(): ExtensionsManifest;
+export declare function saveExtensionsManifest(m: ExtensionsManifest): void;
+/** Strip a live {@link Command} down to its serializable display surface for the cache. */
+export declare function cacheCommand(cmd: Command): CachedCommand;
+/** The installed package's on-disk root inside the prefix. */
+export declare function extensionPackageDir(pkg: string): string;
+/** The installed package's CURRENT version, read from disk (undefined when not installed). */
+export declare function installedExtensionVersion(pkg: string): string | undefined;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAGxD;;;;;;;;;;;;GAYG;AAEH;;qBAEqB;AACrB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;kFACkF;AAClF,wBAAgB,sBAAsB,IAAI,kBAAkB,CAY3D;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAGlE;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAUxD;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,8FAA8F;AAC9F,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKzE"}

package/dist/extensions.js

@@ -0,0 +1,57 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalConfigDir } from "@cotal-ai/core";
+/** The extensions prefix: `<config>/cotal/extensions` — its own npm installation root. */
+export function extensionsDir() {
+    return join(globalConfigDir(), "extensions");
+}
+export function extensionsManifestPath() {
+    return join(extensionsDir(), "extensions.json");
+}
+/** Load the manifest. Missing file → no extensions. A CORRUPT file is a loud error (never treat
+ *  installed extensions as absent — commands would silently vanish from help). */
+export function loadExtensionsManifest() {
+    const p = extensionsManifestPath();
+    if (!existsSync(p))
+        return { extensions: [] };
+    let parsed;
+    try {
+        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`);
+    }
+    const m = parsed;
+    if (!Array.isArray(m.extensions))
+        throw new Error(`corrupt extensions manifest ${p}: no "extensions" array`);
+    return m;
+}
+export function saveExtensionsManifest(m) {
+    mkdirSync(extensionsDir(), { recursive: true });
+    writeFileSync(extensionsManifestPath(), `${JSON.stringify(m, null, 2)}\n`);
+}
+/** Strip a live {@link Command} down to its serializable display surface for the cache. */
+export function cacheCommand(cmd) {
+    return {
+        name: cmd.name,
+        summary: cmd.summary,
+        group: cmd.group,
+        usage: cmd.usage,
+        hidden: cmd.hidden,
+        flags: cmd.flags,
+        positionals: cmd.positionals,
+    };
+}
+/** The installed package's on-disk root inside the prefix. */
+export function extensionPackageDir(pkg) {
+    return join(extensionsDir(), "node_modules", pkg);
+}
+/** The installed package's CURRENT version, read from disk (undefined when not installed). */
+export function installedExtensionVersion(pkg) {
+    const p = join(extensionPackageDir(pkg), "package.json");
+    if (!existsSync(p))
+        return undefined;
+    const v = JSON.parse(readFileSync(p, "utf8")).version;
+    return typeof v === "string" ? v : undefined;
+}
+//# sourceMappingURL=extensions.js.map

package/dist/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AA2CjD,0FAA0F;AAC1F,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,eAAe,EAAE,EAAE,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,iBAAiB,CAAC,CAAC;AAClD,CAAC;AAED;kFACkF;AAClF,MAAM,UAAU,sBAAsB;IACpC,MAAM,CAAC,GAAG,sBAAsB,EAAE,CAAC;IACnC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAC9C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,KAAM,CAAW,CAAC,OAAO,mDAAmD,CAAC,CAAC;IAChI,CAAC;IACD,MAAM,CAAC,GAAG,MAA4B,CAAC;IACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,yBAAyB,CAAC,CAAC;IAC7G,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,CAAqB;IAC1D,SAAS,CAAC,aAAa,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,aAAa,CAAC,sBAAsB,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC7E,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW;KAC7B,CAAC;AACJ,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,MAAM,CAAC,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC;IACzD,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,CAAC,GAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAA0B,CAAC,OAAO,CAAC;IAChF,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC"}

package/dist/flags.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The shared flag vocabulary of the workstation layer. Commands spread these specs instead of
+ * declaring their own copies, so the vocabulary cannot drift between commands; a command that
+ * takes only a SUBSET (e.g. `spawn` foreground has no `--creds`) composes the individual specs.
+ * Declared `as const` so `FlagValues<typeof …>` derives each command's values type — the cast
+ * in `run` is compile-checked against exactly these specs.
+ */
+export declare const spaceFlag: {
+    readonly name: "space";
+    readonly type: "string";
+    readonly value: "<s>";
+    readonly description: "target space (default: the resolved mesh)";
+};
+export declare const serverFlag: {
+    readonly name: "server";
+    readonly type: "string";
+    readonly value: "<url>";
+    readonly description: "broker URL (overrides the mesh registry entry)";
+};
+export declare const credsFlag: {
+    readonly name: "creds";
+    readonly type: "string";
+    readonly value: "<path>";
+    readonly description: "creds file for an off-registry connection";
+};
+/** The mesh-target bundle: which space, which broker, and (off-registry) which credential.
+ *  Resolution order is `resolveMeshTarget`'s: explicit flags > the folder's project > the
+ *  registry/`current` mesh. */
+export declare const targetFlags: readonly [{
+    readonly name: "space";
+    readonly type: "string";
+    readonly value: "<s>";
+    readonly description: "target space (default: the resolved mesh)";
+}, {
+    readonly name: "server";
+    readonly type: "string";
+    readonly value: "<url>";
+    readonly description: "broker URL (overrides the mesh registry entry)";
+}, {
+    readonly name: "creds";
+    readonly type: "string";
+    readonly value: "<path>";
+    readonly description: "creds file for an off-registry connection";
+}];
+/**
+ * The launch grammar: every knob for bringing an agent onto the mesh, shared verbatim by the
+ * foreground and detached (`--detach`, manager-run) paths of `cotal spawn` — one bundle, so the
+ * two launch modes can never again diverge in ability (the old `spawn` vs `start` drift).
+ * The MCP `cotal_spawn` tool mirrors this grammar; a parity smoke (not an import — tier rule)
+ * keeps it honest.
+ */
+export declare const launchFlags: readonly [{
+    readonly name: "name";
+    readonly type: "string";
+    readonly value: "<n>";
+    readonly description: "presence name override; does not choose the persona";
+}, {
+    readonly name: "config";
+    readonly type: "string";
+    readonly value: "<persona-or-path>";
+    readonly description: "persona catalog name or file path; defaults from COTAL_DEFAULT_PERSONA";
+}, {
+    readonly name: "agent";
+    readonly type: "string";
+    readonly value: "<a>";
+    readonly description: "connector type (claude, opencode, hermes …); defaults from COTAL_DEFAULT_AGENT";
+}, {
+    readonly name: "role";
+    readonly type: "string";
+    readonly value: "<r>";
+    readonly description: "role override (wins over the agent file's role:)";
+}, {
+    readonly name: "model";
+    readonly type: "string";
+    readonly value: "<m>";
+    readonly description: "model override (wins over the agent file's model:)";
+}, {
+    readonly name: "variant";
+    readonly type: "string";
+    readonly value: "<v>";
+    readonly description: "model variant override (connector-defined; wins over the agent file's variant:)";
+}, {
+    readonly name: "cwd";
+    readonly type: "string";
+    readonly value: "<dir>";
+    readonly description: "working directory to root the agent at";
+}, {
+    readonly name: "prompt";
+    readonly type: "string";
+    readonly value: "<text>";
+    readonly description: "initial prompt auto-submitted at start";
+}, {
+    readonly name: "resume";
+    readonly type: "string";
+    readonly value: "<id>";
+    readonly description: "fork an existing session id into the mesh (claude only; detached: pair with --cwd)";
+}, {
+    readonly name: "transcript";
+    readonly type: "boolean";
+    readonly description: "mirror the session transcript to tr-<name>";
+}, {
+    readonly name: "no-transcript";
+    readonly type: "boolean";
+    readonly description: "explicit default: no transcript mirror";
+}, {
+    readonly name: "share-tools";
+    readonly type: "string";
+    readonly value: "<sel>";
+    readonly description: "share named operator MCP servers with the agent";
+}, {
+    readonly name: "subscribe";
+    readonly type: "string";
+    readonly value: "<a,b>";
+    readonly description: "channel read set override";
+}, {
+    readonly name: "allow-subscribe";
+    readonly type: "string";
+    readonly value: "<a,b>";
+    readonly description: "read ACL override";
+}, {
+    readonly name: "allow-publish";
+    readonly type: "string";
+    readonly value: "<a,b>";
+    readonly description: "post ACL override";
+}];
+//# sourceMappingURL=flags.d.ts.map

package/dist/flags.d.ts.map

@@ -0,0 +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"}

package/dist/flags.js

@@ -0,0 +1,39 @@
+/**
+ * The shared flag vocabulary of the workstation layer. Commands spread these specs instead of
+ * declaring their own copies, so the vocabulary cannot drift between commands; a command that
+ * takes only a SUBSET (e.g. `spawn` foreground has no `--creds`) composes the individual specs.
+ * Declared `as const` so `FlagValues<typeof …>` derives each command's values type — the cast
+ * in `run` is compile-checked against exactly these specs.
+ */
+export const spaceFlag = { name: "space", type: "string", value: "<s>", description: "target space (default: the resolved mesh)" };
+export const serverFlag = { name: "server", type: "string", value: "<url>", description: "broker URL (overrides the mesh registry entry)" };
+export const credsFlag = { name: "creds", type: "string", value: "<path>", description: "creds file for an off-registry connection" };
+/** The mesh-target bundle: which space, which broker, and (off-registry) which credential.
+ *  Resolution order is `resolveMeshTarget`'s: explicit flags > the folder's project > the
+ *  registry/`current` mesh. */
+export const targetFlags = [spaceFlag, serverFlag, credsFlag];
+/**
+ * The launch grammar: every knob for bringing an agent onto the mesh, shared verbatim by the
+ * foreground and detached (`--detach`, manager-run) paths of `cotal spawn` — one bundle, so the
+ * two launch modes can never again diverge in ability (the old `spawn` vs `start` drift).
+ * The MCP `cotal_spawn` tool mirrors this grammar; a parity smoke (not an import — tier rule)
+ * keeps it honest.
+ */
+export const launchFlags = [
+    { name: "name", type: "string", value: "<n>", description: "presence name override; does not choose the persona" },
+    { name: "config", type: "string", value: "<persona-or-path>", description: "persona catalog name or file path; defaults from COTAL_DEFAULT_PERSONA" },
+    { name: "agent", type: "string", value: "<a>", description: "connector type (claude, opencode, hermes …); defaults from COTAL_DEFAULT_AGENT" },
+    { 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: "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)" },
+    { name: "transcript", type: "boolean", description: "mirror the session transcript to tr-<name>" },
+    { name: "no-transcript", type: "boolean", description: "explicit default: no transcript mirror" },
+    { name: "share-tools", type: "string", value: "<sel>", description: "share named operator MCP servers with the agent" },
+    { name: "subscribe", type: "string", value: "<a,b>", description: "channel read set override" },
+    { name: "allow-subscribe", type: "string", value: "<a,b>", description: "read ACL override" },
+    { name: "allow-publish", type: "string", value: "<a,b>", description: "post ACL override" },
+];
+//# sourceMappingURL=flags.js.map

package/dist/flags.js.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -1,7 +1,14 @@
 export * from "./auth-paths.js";
 export * from "./bin-path.js";
+export * from "./colors.js";
+export * from "./connect.js";
+export * from "./default-agent.js";
+export * from "./extensions.js";
+export * from "./flags.js";
+export * from "./provenance.js";
 export * from "./mesh-registry.js";
 export * from "./mesh-target.js";
 export * from "./preflight.js";
 export * from "./render.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,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"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"}

package/dist/index.js

@@ -1,7 +1,14 @@
 export * from "./auth-paths.js";
 export * from "./bin-path.js";
+export * from "./colors.js";
+export * from "./connect.js";
+export * from "./default-agent.js";
+export * from "./extensions.js";
+export * from "./flags.js";
+export * from "./provenance.js";
 export * from "./mesh-registry.js";
 export * from "./mesh-target.js";
 export * from "./preflight.js";
 export * from "./render.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,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"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"}

package/dist/provenance.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One consistent voice for CLI provenance, on stderr: which on-disk source a command RESOLVED
+ * its configuration from, and what it WROTE where. Commands must never silently pick up state
+ * from a directory or silently drop files — every read of config (persona file, mesh entry,
+ * config.json layer) and every write (creds, seeded files) gets one dim arrow line. stderr so
+ * it never pollutes machine-readable stdout; plain text so this layer needs no color dep.
+ */
+export declare const provenance: {
+    /** `→ using <what>: <source>` — the source that WON resolution (say which layer/path). */
+    read(what: string, source: string): void;
+    /** `→ wrote <what>: <dest>` — announce every file the command created or replaced. */
+    wrote(what: string, dest: string): void;
+};
+//# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;IACrB,0FAA0F;eAC/E,MAAM,UAAU,MAAM,GAAG,IAAI;IAGxC,sFAAsF;gBAC1E,MAAM,QAAQ,MAAM,GAAG,IAAI;CAGxC,CAAC"}

package/dist/provenance.js

@@ -0,0 +1,18 @@
+/**
+ * One consistent voice for CLI provenance, on stderr: which on-disk source a command RESOLVED
+ * its configuration from, and what it WROTE where. Commands must never silently pick up state
+ * from a directory or silently drop files — every read of config (persona file, mesh entry,
+ * config.json layer) and every write (creds, seeded files) gets one dim arrow line. stderr so
+ * it never pollutes machine-readable stdout; plain text so this layer needs no color dep.
+ */
+export const provenance = {
+    /** `→ using <what>: <source>` — the source that WON resolution (say which layer/path). */
+    read(what, source) {
+        process.stderr.write(`→ using ${what}: ${source}\n`);
+    },
+    /** `→ wrote <what>: <dest>` — announce every file the command created or replaced. */
+    wrote(what, dest) {
+        process.stderr.write(`→ wrote ${what}: ${dest}\n`);
+    },
+};
+//# sourceMappingURL=provenance.js.map

package/dist/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,0FAA0F;IAC1F,IAAI,CAAC,IAAY,EAAE,MAAc;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,sFAAsF;IACtF,KAAK,CAAC,IAAY,EAAE,IAAY;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC;IACrD,CAAC;CACF,CAAC"}

package/dist/space.d.ts

@@ -0,0 +1,5 @@
+/** The space this folder operates on: its `.cotal/auth` space if set up, else the default.
+ *  A folder has exactly one space (its auth) — commands resolve it through here so they always
+ *  match the folder's mesh instead of assuming the global default. */
+export declare function resolveSpace(cwd: string): string;
+//# sourceMappingURL=space.d.ts.map

package/dist/space.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space.d.ts","sourceRoot":"","sources":["../src/space.ts"],"names":[],"mappings":"AAGA;;sEAEsE;AACtE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/space.js

@@ -0,0 +1,9 @@
+import { DEFAULT_SPACE } from "@cotal-ai/core";
+import { authDir, findCotalRoot, loadSpaceAuth } from "./auth-paths.js";
+/** The space this folder operates on: its `.cotal/auth` space if set up, else the default.
+ *  A folder has exactly one space (its auth) — commands resolve it through here so they always
+ *  match the folder's mesh instead of assuming the global default. */
+export function resolveSpace(cwd) {
+    return loadSpaceAuth(authDir(findCotalRoot(cwd)))?.space ?? DEFAULT_SPACE;
+}
+//# sourceMappingURL=space.js.map

package/dist/space.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"space.js","sourceRoot":"","sources":["../src/space.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAExE;;sEAEsE;AACtE,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,aAAa,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,aAAa,CAAC;AAC5E,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cotal-ai/workspace",
   "description": "Cotal machine-local workstation layer: the ~/.cotal mesh registry, target resolution, preflight, on-disk auth-path I/O, and the command-copy renderer — operator concerns over a local checkout, kept separate from the wire protocol in @cotal-ai/core.",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
     }
   },
   "dependencies": {
-    "@cotal-ai/core": "0.9.1"
+    "@cotal-ai/core": "0.10.1"
   },
   "files": [
     "dist"