@cotal-ai/workspace 0.7.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/auth-paths.d.ts

@@ -0,0 +1,13 @@
+import type { SpaceAuth } from "@cotal-ai/core";
+export declare function authDir(root: 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. */
+export declare function findCotalRoot(start?: string): string;
+/** Persist the space trust material. The file holds the data-account signing seed — treat as a secret.
+ *  The system-account `sys.signingSeed` is STRIPPED before writing: it is broker-admin minting capability,
+ *  so it never lands on disk (it lives only in the in-memory {@link createSpaceAuth} result). */
+export declare function saveSpaceAuth(dir: string, auth: SpaceAuth): void;
+/** Load the space trust material, or undefined if auth was never set up here. */
+export declare function loadSpaceAuth(dir: string): SpaceAuth | undefined;
+//# sourceMappingURL=auth-paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth-paths.d.ts","sourceRoot":"","sources":["../src/auth-paths.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAehD,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"}

package/dist/auth-paths.js

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+/**
+ * On-disk auth-material I/O for a local checkout's `.cotal/` — machine-local path resolution plus
+ * reading/writing the space trust material. Lives in `@cotal-ai/workspace` (not core) because it's a
+ * workstation concern — *where a checkout's `.cotal/` is on THIS disk* — not part of the wire
+ * protocol. The minting / JWT / `nats-server` config machinery stays in `@cotal-ai/core`; these
+ * helpers persist its output. `SpaceAuth` is core's type — imported here, owned there.
+ *
+ * Deliberately explicit-root/path APIs: no ambient `findAndMint()` that fuses root discovery with
+ * signing. File modes (0700 dirs / 0600 files) and the no-arbitrary-delete posture are preserved.
+ */
+const AUTH_FILE = "auth.json";
+export function authDir(root) {
+    return join(root, ".cotal", "auth");
+}
+/** 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. */
+export function findCotalRoot(start = process.cwd()) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, ".cotal")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return resolve(start);
+        dir = parent;
+    }
+}
+/** Persist the space trust material. The file holds the data-account signing seed — treat as a secret.
+ *  The system-account `sys.signingSeed` is STRIPPED before writing: it is broker-admin minting capability,
+ *  so it never lands on disk (it lives only in the in-memory {@link createSpaceAuth} result). */
+export function saveSpaceAuth(dir, auth) {
+    mkdirSync(dir, { recursive: true });
+    const onDisk = { ...auth, sys: { pub: auth.sys.pub, jwt: auth.sys.jwt } };
+    writeFileSync(join(dir, AUTH_FILE), JSON.stringify(onDisk, null, 2), { mode: 0o600 });
+}
+/** Load the space trust material, or undefined if auth was never set up here. */
+export function loadSpaceAuth(dir) {
+    const f = join(dir, AUTH_FILE);
+    if (!existsSync(f))
+        return undefined;
+    return JSON.parse(readFileSync(f, "utf8"));
+}
+//# sourceMappingURL=auth-paths.js.map

package/dist/auth-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-paths.js","sourceRoot":"","sources":["../src/auth-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGnD;;;;;;;;;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,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,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,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACxF,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/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./auth-paths.js";
+export * from "./mesh-registry.js";
+export * from "./mesh-target.js";
+export * from "./preflight.js";
+export * from "./render.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./auth-paths.js";
+export * from "./mesh-registry.js";
+export * from "./mesh-target.js";
+export * from "./preflight.js";
+export * from "./render.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/mesh-registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The registry of running meshes: one record per broker `cotal up` started on this machine, so a
+ * `cotal spawn` from *any* directory can find which mesh to join, with which creds and personas.
+ *
+ * Stored as **one JSON file per mesh** (`~/.cotal/meshes/<space>.json`) rather than a single
+ * `meshes.json`: concurrent `up`/`down` never read-modify-write the same file (no lost-update race),
+ * a crash damages at most one entry, and it mirrors the existing per-process pid files under
+ * `~/.cotal`. A separate `~/.cotal/current-mesh` holds the default space for the N-running case
+ * (the kubectl `current-context` analogue).
+ *
+ * Each record stores the mesh's **root path**, not its secrets — trust material stays in that
+ * project's `.cotal/auth`; the registry just makes it findable from elsewhere.
+ */
+export interface MeshEntry {
+    /** The space name — also the registry filename stem. */
+    space: string;
+    /** The broker URL, e.g. `nats://127.0.0.1:4222`. */
+    server: string;
+    /** Absolute path whose `.cotal/{auth,agents}` hold this mesh's trust material + personas. */
+    root: string;
+    mode: "auth" | "open";
+    /** ISO timestamp of when the record was written. */
+    ts: string;
+}
+/** The cotal machine-home dir (`~/.cotal`), overridable via `COTAL_HOME` so tests sandbox it and
+ *  never touch the real one. The single source of that path for the registry, the current pointer,
+ *  and the onboard marker. */
+export declare function homeCotalDir(): string;
+/** Directory holding the per-mesh registry files (`~/.cotal/meshes`). */
+export declare function meshesDir(): string;
+/** Record (or refresh) a running mesh — atomic write, 0600 (the file points at a secrets dir). */
+export declare function recordMesh(m: MeshEntry): void;
+/** Drop a mesh from the registry (on `cotal down` / a stale-entry prune). Absent ⇒ no-op. */
+export declare function removeMesh(space: string): void;
+/** All currently-recorded meshes. An unparseable/partially-written entry is skipped, not fatal —
+ *  one bad file must not hide the rest. */
+export declare function loadMeshes(): MeshEntry[];
+export declare function findMesh(space: string): MeshEntry | undefined;
+/** The default mesh's space name, set by `cotal use` (and by the first `cotal up`). Undefined when
+ *  unset or empty. The pointer can dangle (its mesh went down); callers treat a `findMesh` miss as
+ *  "no current". */
+export declare function getCurrent(): string | undefined;
+export declare function setCurrent(space: string): void;
+export declare function clearCurrent(): void;
+//# sourceMappingURL=mesh-registry.d.ts.map

package/dist/mesh-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-registry.d.ts","sourceRoot":"","sources":["../src/mesh-registry.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;8BAE8B;AAC9B,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,yEAAyE;AACzE,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAUD,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAU7C;AAED,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED;2CAC2C;AAC3C,wBAAgB,UAAU,IAAI,SAAS,EAAE,CAgBxC;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAE7D;AAED;;oBAEoB;AACpB,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAM/C;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAG9C;AAED,wBAAgB,YAAY,IAAI,IAAI,CAEnC"}

package/dist/mesh-registry.js

@@ -0,0 +1,78 @@
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** The cotal machine-home dir (`~/.cotal`), overridable via `COTAL_HOME` so tests sandbox it and
+ *  never touch the real one. The single source of that path for the registry, the current pointer,
+ *  and the onboard marker. */
+export function homeCotalDir() {
+    return process.env.COTAL_HOME ?? join(homedir(), ".cotal");
+}
+/** Directory holding the per-mesh registry files (`~/.cotal/meshes`). */
+export function meshesDir() {
+    return join(homeCotalDir(), "meshes");
+}
+function meshFile(space) {
+    return join(meshesDir(), `${encodeURIComponent(space)}.json`);
+}
+function currentFile() {
+    return join(homeCotalDir(), "current-mesh");
+}
+/** Record (or refresh) a running mesh — atomic write, 0600 (the file points at a secrets dir). */
+export function recordMesh(m) {
+    // 0700: the filenames in here ARE the space names, so a world-traversable dir would leak them to
+    // other local users even though the file contents are 0600. Keep the dir readable only by us.
+    mkdirSync(meshesDir(), { recursive: true, mode: 0o700 });
+    const file = meshFile(m.space);
+    // Per-process temp name so two concurrent `up`s for the same space can't stomp each other's
+    // half-written file before the rename.
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(m, null, 2), { mode: 0o600 });
+    renameSync(tmp, file); // atomic replace — a reader never sees a half-written record
+}
+/** Drop a mesh from the registry (on `cotal down` / a stale-entry prune). Absent ⇒ no-op. */
+export function removeMesh(space) {
+    rmSync(meshFile(space), { force: true });
+}
+/** All currently-recorded meshes. An unparseable/partially-written entry is skipped, not fatal —
+ *  one bad file must not hide the rest. */
+export function loadMeshes() {
+    let files;
+    try {
+        files = readdirSync(meshesDir()).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return []; // no registry yet
+    }
+    const out = [];
+    for (const f of files.sort()) {
+        try {
+            out.push(JSON.parse(readFileSync(join(meshesDir(), f), "utf8")));
+        }
+        catch {
+            /* skip a corrupt/half-written entry rather than fail the whole listing */
+        }
+    }
+    return out;
+}
+export function findMesh(space) {
+    return loadMeshes().find((m) => m.space === space);
+}
+/** The default mesh's space name, set by `cotal use` (and by the first `cotal up`). Undefined when
+ *  unset or empty. The pointer can dangle (its mesh went down); callers treat a `findMesh` miss as
+ *  "no current". */
+export function getCurrent() {
+    try {
+        return readFileSync(currentFile(), "utf8").trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function setCurrent(space) {
+    mkdirSync(homeCotalDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(currentFile(), space, { mode: 0o600 });
+}
+export function clearCurrent() {
+    rmSync(currentFile(), { force: true });
+}
+//# sourceMappingURL=mesh-registry.js.map

package/dist/mesh-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-registry.js","sourceRoot":"","sources":["../src/mesh-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,MAAM,EACN,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA2BjC;;8BAE8B;AAC9B,MAAM,UAAU,YAAY;IAC1B,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC7D,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,SAAS;IACvB,OAAO,IAAI,CAAC,YAAY,EAAE,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,WAAW;IAClB,OAAO,IAAI,CAAC,YAAY,EAAE,EAAE,cAAc,CAAC,CAAC;AAC9C,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,UAAU,CAAC,CAAY;IACrC,iGAAiG;IACjG,8FAA8F;IAC9F,SAAS,CAAC,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/B,4FAA4F;IAC5F,uCAAuC;IACvC,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IACzC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAChE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,6DAA6D;AACtF,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED;2CAC2C;AAC3C,MAAM,UAAU,UAAU;IACxB,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,kBAAkB;IAC/B,CAAC;IACD,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAc,CAAC,CAAC;QAChF,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;AACrD,CAAC;AAED;;oBAEoB;AACpB,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,SAAS,CAAC,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5D,aAAa,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,CAAC,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/mesh-target.d.ts

@@ -0,0 +1,81 @@
+import { type SpaceAuth } from "@cotal-ai/core";
+/**
+ * One coherent answer to "which mesh does this command act on, and where do its creds + personas
+ * live" — resolved identically for both, so a spawn can never authenticate to mesh A while loading
+ * mesh B's persona. Replaces the scattered `loadSpaceAuth(authDir(cotalRoot()))` + `resolveSpace` +
+ * `DEFAULT_SERVER` guesswork that silently mistook `~/.cotal` for a space.
+ *
+ * Pure and offline (no network): `<TAB>` completion uses it as-is; `spawn` adds a reachability
+ * preflight (`probeConnect`) on top.
+ */
+export interface MeshTarget {
+    /** Absolute dir whose `.cotal/{auth,agents}` hold trust + personas. */
+    root: string;
+    server: string;
+    space: string;
+    /** Trust material, or undefined for an open mesh. */
+    auth?: SpaceAuth;
+    /** `<root>/.cotal/agents` — the persona catalog for this mesh. */
+    personaRoot: string;
+    /** Where the target came from — this also carries OWNERSHIP for pruning. `registry`/`current`/
+     *  `flag-space`/`local-recorded` mean the server + mode came from a registry record, so a
+     *  stale-broker failure prunes the entry. `local-space`/`flag-server`/`flag-space-override` are the
+     *  non-registry escape hatches — NEVER pruned: the probed server is operator-supplied (a raw
+     *  `--server`, or a `--space` whose `--server` overrides the recorded broker), so a failure against
+     *  it must not delete the recorded entry. `local-recorded` is a local project matched to a registry
+     *  entry by root: registry-owned for pruning, but quiet on the success line (self-evident from cwd). */
+    source: "flag-server" | "flag-space" | "flag-space-override" | "local-space" | "local-recorded" | "registry" | "current";
+}
+export interface ResolveFlags {
+    /** `--server <url>` — raw broker escape hatch. */
+    server?: string;
+    /** `--space <name>` — pick a specific running mesh from the registry. */
+    space?: string;
+}
+/** The distinct, command-agnostic reasons {@link resolveMeshTarget} can't pick a single mesh. Each
+ *  maps 1:1 to a former prose-throw; the recovery copy (`cotal up`/`meshes`/`use`) is the renderer's
+ *  job ({@link renderWorkspaceError}), not the protocol's. */
+export type MeshTargetErrorCode = "no-meshes" | "unknown-space" | "ambiguous-target" | "default-occupied" | "stale-auth-root";
+/** Structured context for a {@link MeshTargetError} — enough for any surface to render its own
+ *  recovery affordance (a CLI sentence, a web button, an SDK embed that wants no command at all). */
+export interface MeshTargetErrorDetails {
+    /** The space/mesh the failure concerns. */
+    space?: string;
+    /** A broker URL involved (e.g. the occupant of the default port). */
+    server?: string;
+    /** A checkout root involved. */
+    root?: string;
+    /** Running meshes, for the ambiguous case — each formatted `"<space> (<root>)"`. */
+    available?: string[];
+    /** What the caller asked for that didn't match (e.g. an unknown `--space`). */
+    requested?: string;
+    /** For `stale-auth-root`: the space the on-disk auth now claims, diverging from the record. */
+    found?: string;
+}
+/**
+ * A typed mesh-target resolution failure. `message` is **log/dev-safe and command-agnostic** — never
+ * the canonical product copy (that's {@link renderWorkspaceError}'s job; don't let `message` become
+ * an accidental string API). `code` + structured `details` are the surfaces consumers read.
+ */
+export declare class MeshTargetError extends Error {
+    /** Brand for cross-package-safe detection — see {@link isWorkspaceTargetError}. */
+    readonly brand = "cotal:workspace:mesh-target-error";
+    readonly code: MeshTargetErrorCode;
+    readonly details: MeshTargetErrorDetails;
+    constructor(code: MeshTargetErrorCode, message: string, details?: MeshTargetErrorDetails, options?: {
+        cause?: unknown;
+    });
+}
+/** Detect a {@link MeshTargetError} across the core/workspace/consumer package boundary without a
+ *  brittle `instanceof` (which breaks if two copies of this package are installed) — a brand check. */
+export declare function isWorkspaceTargetError(e: unknown): e is MeshTargetError;
+/**
+ * Resolve the mesh target by precedence (first match wins):
+ *  1. `--space` — registry lookup (errors if that space isn't running).
+ *  2. `--server` — registry entry on that server (for creds/personas), else the local project.
+ *  3. A genuine local project (`cwd` walks up to a real `.cotal/`) — local wins, like `git config`.
+ *  4. The registry: 0 ⇒ error; 1 ⇒ use it; N ⇒ `current` if set, else error naming each + its root.
+ * No silent fallback — an unresolved target throws one human sentence.
+ */
+export declare function resolveMeshTarget(cwd: string, flags?: ResolveFlags): MeshTarget;
+//# sourceMappingURL=mesh-target.d.ts.map

package/dist/mesh-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-target.d.ts","sourceRoot":"","sources":["../src/mesh-target.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAW/E;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;4GAMwG;IACxG,MAAM,EACF,aAAa,GACb,YAAY,GACZ,qBAAqB,GACrB,aAAa,GACb,gBAAgB,GAChB,UAAU,GACV,SAAS,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;8DAE8D;AAC9D,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,CAAC;AAEtB;qGACqG;AACrG,MAAM,WAAW,sBAAsB;IACrC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,uCAA0B;IACxC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;gBAEvC,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,EACpC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAOhC;AAED;uGACuG;AACvG,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAMvE;AAgDD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,YAAiB,GAAG,UAAU,CAyDnF"}

package/dist/mesh-target.js

@@ -0,0 +1,129 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { DEFAULT_SERVER, DEFAULT_SPACE } from "@cotal-ai/core";
+import { authDir, findCotalRoot, loadSpaceAuth } from "./auth-paths.js";
+import { findMesh, getCurrent, homeCotalDir, loadMeshes, removeMesh, } from "./mesh-registry.js";
+const WORKSPACE_TARGET_ERROR = "cotal:workspace:mesh-target-error";
+/**
+ * A typed mesh-target resolution failure. `message` is **log/dev-safe and command-agnostic** — never
+ * the canonical product copy (that's {@link renderWorkspaceError}'s job; don't let `message` become
+ * an accidental string API). `code` + structured `details` are the surfaces consumers read.
+ */
+export class MeshTargetError extends Error {
+    /** Brand for cross-package-safe detection — see {@link isWorkspaceTargetError}. */
+    brand = WORKSPACE_TARGET_ERROR;
+    code;
+    details;
+    constructor(code, message, details = {}, options) {
+        super(message, options);
+        this.name = "MeshTargetError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Detect a {@link MeshTargetError} across the core/workspace/consumer package boundary without a
+ *  brittle `instanceof` (which breaks if two copies of this package are installed) — a brand check. */
+export function isWorkspaceTargetError(e) {
+    return (typeof e === "object" &&
+        e !== null &&
+        e.brand === WORKSPACE_TARGET_ERROR);
+}
+function personaRoot(root) {
+    return join(root, ".cotal", "agents");
+}
+function targetFromEntry(m, server, source) {
+    // Honor the recorded mode: an OPEN mesh connects credlessly even if its root still has auth
+    // material on disk (e.g. a root that once ran auth mode). Loading it would make `spawn` mint
+    // creds against a broker that takes none.
+    let auth;
+    if (m.mode === "auth") {
+        auth = loadSpaceAuth(authDir(m.root));
+        // Defense in depth: the root's on-disk auth must still be for THIS space. A divergence (the root
+        // was re-`up`ed as a different space without re-recording) would otherwise mint mesh-A creds
+        // against the entry for space B. Prune the stale entry and fail loud rather than connect wrong.
+        if (auth && auth.space !== m.space) {
+            removeMesh(m.space);
+            throw new MeshTargetError("stale-auth-root", `registry entry "${m.space}" points at ${m.root}, whose on-disk auth is now for "${auth.space}"`, { space: m.space, root: m.root, found: auth.space });
+        }
+    }
+    return {
+        root: m.root,
+        server,
+        space: m.space,
+        auth,
+        personaRoot: personaRoot(m.root),
+        source,
+    };
+}
+function localTarget(root, server, source) {
+    const auth = loadSpaceAuth(authDir(root));
+    return { root, server, space: auth?.space ?? DEFAULT_SPACE, auth, personaRoot: personaRoot(root), source };
+}
+/** A `.cotal/` that a user actually created here — not the machine-home dir the cwd walk-up lands on
+ *  from outside any project (which has no space, just the daemon's pid/onboard files). */
+function isGenuineSpace(root) {
+    // Normalize both sides — COTAL_HOME may be relative or non-canonical, and a raw string compare
+    // would then let the real `~/.cotal` masquerade as a project space (or vice-versa).
+    return resolve(join(root, ".cotal")) !== resolve(homeCotalDir()) && existsSync(join(root, ".cotal"));
+}
+/**
+ * Resolve the mesh target by precedence (first match wins):
+ *  1. `--space` — registry lookup (errors if that space isn't running).
+ *  2. `--server` — registry entry on that server (for creds/personas), else the local project.
+ *  3. A genuine local project (`cwd` walks up to a real `.cotal/`) — local wins, like `git config`.
+ *  4. The registry: 0 ⇒ error; 1 ⇒ use it; N ⇒ `current` if set, else error naming each + its root.
+ * No silent fallback — an unresolved target throws one human sentence.
+ */
+export function resolveMeshTarget(cwd, flags = {}) {
+    if (flags.space) {
+        const m = findMesh(flags.space);
+        if (!m)
+            throw new MeshTargetError("unknown-space", `no mesh named "${flags.space}" is running`, {
+                requested: flags.space,
+            });
+        // An explicit `--server` that overrides the recorded broker is an operator-supplied endpoint, not
+        // the registry's — probing IT must never prune the recorded entry (a dead override would otherwise
+        // delete a live registered mesh, and pre-pruning would block a live-override recovery). Mark it so
+        // preflight classifies the failure as non-registry / no-prune.
+        const overriding = flags.server !== undefined && flags.server !== m.server;
+        return targetFromEntry(m, flags.server ?? m.server, overriding ? "flag-space-override" : "flag-space");
+    }
+    if (flags.server) {
+        const m = loadMeshes().find((e) => e.server === flags.server);
+        if (m)
+            return targetFromEntry(m, flags.server, "flag-server");
+        return localTarget(findCotalRoot(cwd), flags.server, "flag-server");
+    }
+    const root = findCotalRoot(cwd);
+    if (isGenuineSpace(root)) {
+        // Local project wins by root — but if its mesh is in the registry, use the RECORDED server +
+        // mode, not DEFAULT_SERVER: a project started with `--server …:4333` must spawn against :4333,
+        // and a recorded OPEN mesh must not mint creds off stale `.cotal/auth` left on disk. Fall back
+        // to the local default only when nothing is recorded for this root.
+        const recorded = loadMeshes().find((m) => resolve(m.root) === resolve(root));
+        if (recorded)
+            return targetFromEntry(recorded, recorded.server, "local-recorded");
+        // No record for this root (migration, or our broker went down and the entry was just pruned).
+        // Before guessing DEFAULT_SERVER, refuse if a DIFFERENT mesh is recorded there — otherwise the
+        // fallback would silently join someone else's mesh on the default port with our persona (the
+        // exact silent-wrong-mesh outcome this feature exists to prevent).
+        const onDefault = loadMeshes().find((m) => m.server === DEFAULT_SERVER && resolve(m.root) !== resolve(root));
+        if (onDefault)
+            throw new MeshTargetError("default-occupied", `another mesh ("${onDefault.space}") is running at ${DEFAULT_SERVER}`, { space: onDefault.space, server: DEFAULT_SERVER });
+        return localTarget(root, DEFAULT_SERVER, "local-space");
+    }
+    const meshes = loadMeshes();
+    if (meshes.length === 0)
+        throw new MeshTargetError("no-meshes", "no mesh running");
+    if (meshes.length === 1)
+        return targetFromEntry(meshes[0], meshes[0].server, "registry");
+    const current = getCurrent();
+    const cur = current ? findMesh(current) : undefined;
+    if (cur)
+        return targetFromEntry(cur, cur.server, "current");
+    const names = meshes.map((m) => `${m.space} (${m.root})`);
+    throw new MeshTargetError("ambiguous-target", `multiple meshes running: ${names.join(", ")}`, {
+        available: names,
+    });
+}
+//# sourceMappingURL=mesh-target.js.map

package/dist/mesh-target.js.map

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

package/dist/preflight.d.ts

@@ -0,0 +1,46 @@
+import type { MeshTarget } from "./mesh-target.js";
+/**
+ * Liveness verification for a resolved mesh target — the companion to {@link resolveMeshTarget}
+ * ("which mesh") that answers "is it actually up, and does the registry still reflect reality".
+ *
+ * Lives in `@cotal-ai/workspace` (beside the registry and target resolution, over core's
+ * `probeConnect`) so every surface shares ONE preflight rule instead of re-deriving it: the CLI's
+ * `connectOrExit` and the manager's control commands both wrap these helpers. It owns the MECHANICS
+ * only — the classify decision and the probe — never the I/O or the copy: the canonical `cotal …`
+ * wording is {@link renderWorkspaceError}'s job, colour and `process.exit` stay at each call site,
+ * and pruning is the caller's explicit act, not a side effect of probing.
+ */
+/** The five distinct ways a preflight fails. Each also carries 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 tree — separated from I/O so the whole branch tree is unit-testable (it's the
+ *  riskiest logic: a wrong branch prunes a LIVE registry entry). Only a registry-OWNED source
+ *  (`registry`/`current`/`flag-space`/`local-recorded`) is ever pruned. A non-registry source —
+ *  `flag-server`/`local-space`, a raw `--creds` connection, or `flag-space-override` (a `--space`
+ *  whose `--server` overrides the recorded broker) — is NEVER pruned: the probed endpoint is
+ *  operator-supplied, so a failure there is the user's to diagnose, not a stale-registry signal. */
+export declare function classifyPreflightFailure(source: MeshTarget["source"], reason: "auth-required" | "unreachable", hasAuth: boolean): {
+    prune: boolean;
+    kind: PreflightFailure;
+};
+/** Probe a resolved target and, on failure, classify it — WITHOUT touching the registry. Returns the
+ *  decision (incl. whether the caller SHOULD prune); the caller owns the `removeMesh` + message +
+ *  exit. Probes with `probeCreds` when given (the caller's `--creds`/minted creds); otherwise mints
+ *  a throwaway identity from the target's own trust material to test mere liveness. */
+export declare function preflightTarget(target: MeshTarget, probeCreds?: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    kind: PreflightFailure;
+    prune: boolean;
+}>;
+/**
+ * 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. An EXPLICIT call (never wired into
+ * resolution itself), so registry mutation stays opt-in: callers that act on the registry
+ * (`spawn`/`use`/`meshes`, the manager control commands) invoke it; `<TAB>` completion must not.
+ */
+export declare function pruneStaleMeshes(): Promise<void>;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;GAUG;AAEH;;kGAEkG;AAClG,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,yBAAyB,GACzB,wBAAwB,GACxB,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB;;;;;oGAKoG;AACpG,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,CAa5C;AAED;;;uFAGuF;AACvF,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAO/E;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOtD"}

package/dist/preflight.js

@@ -0,0 +1,52 @@
+import { mintCreds, newIdentity, probeConnect } from "@cotal-ai/core";
+import { loadMeshes, removeMesh } from "./mesh-registry.js";
+/** Pure decision tree — separated from I/O so the whole branch tree is unit-testable (it's the
+ *  riskiest logic: a wrong branch prunes a LIVE registry entry). Only a registry-OWNED source
+ *  (`registry`/`current`/`flag-space`/`local-recorded`) is ever pruned. A non-registry source —
+ *  `flag-server`/`local-space`, a raw `--creds` connection, or `flag-space-override` (a `--space`
+ *  whose `--server` overrides the recorded broker) — is NEVER pruned: the probed endpoint is
+ *  operator-supplied, so a failure there is the user's to diagnose, not a stale-registry signal. */
+export function classifyPreflightFailure(source, reason, hasAuth) {
+    // `flag-space-override` and `flag-server` are deliberately absent: the probe hit an operator-named
+    // endpoint, not the registry-recorded broker, so its failure must not delete the recorded entry.
+    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" };
+}
+/** Probe a resolved target and, on failure, classify it — WITHOUT touching the registry. Returns the
+ *  decision (incl. whether the caller SHOULD prune); the caller owns the `removeMesh` + message +
+ *  exit. Probes with `probeCreds` when given (the caller's `--creds`/minted creds); otherwise mints
+ *  a throwaway identity from the target's own trust material to test mere liveness. */
+export async function preflightTarget(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 { ok: true };
+    const { prune, kind } = classifyPreflightFailure(target.source, probe.reason, Boolean(target.auth));
+    return { ok: false, kind, prune };
+}
+/**
+ * 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. An EXPLICIT call (never wired into
+ * resolution itself), so registry mutation stays opt-in: callers that act on the registry
+ * (`spawn`/`use`/`meshes`, the manager control commands) invoke it; `<TAB>` completion must not.
+ */
+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=preflight.js.map

package/dist/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAyB5D;;;;;oGAKoG;AACpG,MAAM,UAAU,wBAAwB,CACtC,MAA4B,EAC5B,MAAuC,EACvC,OAAgB;IAEhB,mGAAmG;IACnG,iGAAiG;IACjG,MAAM,YAAY,GAChB,MAAM,KAAK,UAAU;QACrB,MAAM,KAAK,SAAS;QACpB,MAAM,KAAK,YAAY;QACvB,MAAM,KAAK,gBAAgB,CAAC;IAC9B,IAAI,MAAM,KAAK,aAAa;QAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IAClF,IAAI,YAAY,IAAI,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,yBAAyB,EAAE,CAAC;IACrF,IAAI,YAAY;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC;IACzE,IAAI,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;IAC7D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;AACnD,CAAC;AAED;;;uFAGuF;AACvF,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAkB,EAClB,UAAmB;IAEnB,MAAM,KAAK,GACT,UAAU,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACnG,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxE,IAAI,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAClC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,wBAAwB,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACpG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;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/render.d.ts

@@ -0,0 +1,29 @@
+import type { MeshTarget, MeshTargetError } from "./mesh-target.js";
+import type { PreflightFailure } from "./preflight.js";
+/**
+ * The single home for the toolchain's `cotal …` wording — optional and presentation-only.
+ *
+ * This is NOT part of the typed contract. Workspace internals never call it to decide behavior, no
+ * control flow parses its output, and the rendered string is never baked back into a thrown error or
+ * a result. A consumer that wants its own affordance — a web UI with a button, an SDK embed with no
+ * command at all — reads the structured `{code, details}` / `{kind, …}` and ignores this entirely,
+ * losing nothing. It exists so the CLI, the manager, and the delivery daemon speak the canonical
+ * command copy with ONE voice instead of each hand-rolling it (the drift that motivated the split).
+ * No colour, no `process`, no exit — the caller owns those.
+ */
+export type WorkspaceError = {
+    kind: "target";
+    error: MeshTargetError;
+} | {
+    kind: "preflight";
+    failure: PreflightFailure;
+    target: MeshTarget;
+    pruned: boolean;
+} | {
+    kind: "reachable";
+    reason: "auth-required" | "unreachable";
+    server: string;
+};
+/** Render a workspace failure as the canonical one-line `cotal …` sentence. */
+export declare function renderWorkspaceError(e: WorkspaceError): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAS9D"}

package/dist/render.js

@@ -0,0 +1,50 @@
+/** Render a workspace failure as the canonical one-line `cotal …` sentence. */
+export function renderWorkspaceError(e) {
+    switch (e.kind) {
+        case "target":
+            return renderTargetError(e.error);
+        case "preflight":
+            return renderPreflightFailure(e.failure, e.target, e.pruned);
+        case "reachable":
+            return renderReachable(e.reason, e.server);
+    }
+}
+/** "Which mesh" resolution failures — maps a {@link MeshTargetError}'s `{code, details}` to copy. */
+function renderTargetError(err) {
+    const d = err.details;
+    switch (err.code) {
+        case "no-meshes":
+            return "✗ no mesh running — run `cotal up` in a project, or pass `--server`";
+        case "unknown-space":
+            return `✗ no mesh named "${d.requested}" is running — see \`cotal meshes\``;
+        case "ambiguous-target":
+            return `✗ multiple meshes running — ${(d.available ?? []).join(", ")}. Pick one with \`--space <name>\` or set a default with \`cotal use <name>\`.`;
+        case "default-occupied":
+            return `✗ another mesh ("${d.space}") is running at ${d.server} — run \`cotal up\` here to start yours, or \`--space ${d.space}\` to join it`;
+        case "stale-auth-root":
+            return `✗ registry entry "${d.space}" points at ${d.root}, whose auth is now for "${d.found}" — stale entry removed; re-run \`cotal up\` or check \`cotal meshes\``;
+    }
+}
+/** "Is it live" failures on a registry-resolved target — the classified preflight sentence. */
+function renderPreflightFailure(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\``;
+    }
+}
+/** Plain reachability for a RAW (off-registry) probe — the `--creds` / `--server`+unregistered-`--space`
+ *  escape hatch, which never touches the registry (no prune, no stale-entry wording). */
+function renderReachable(reason, server) {
+    return 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\`)`;
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAmBA,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB,CAAC,CAAiB;IACpD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACpC,KAAK,WAAW;YACd,OAAO,sBAAsB,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QAC/D,KAAK,WAAW;YACd,OAAO,eAAe,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED,qGAAqG;AACrG,SAAS,iBAAiB,CAAC,GAAoB;IAC7C,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC;IACtB,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,WAAW;YACd,OAAO,qEAAqE,CAAC;QAC/E,KAAK,eAAe;YAClB,OAAO,oBAAoB,CAAC,CAAC,SAAS,qCAAqC,CAAC;QAC9E,KAAK,kBAAkB;YACrB,OAAO,+BAA+B,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,gFAAgF,CAAC;QACvJ,KAAK,kBAAkB;YACrB,OAAO,oBAAoB,CAAC,CAAC,KAAK,oBAAoB,CAAC,CAAC,MAAM,yDAAyD,CAAC,CAAC,KAAK,eAAe,CAAC;QAChJ,KAAK,iBAAiB;YACpB,OAAO,qBAAqB,CAAC,CAAC,KAAK,eAAe,CAAC,CAAC,IAAI,4BAA4B,CAAC,CAAC,KAAK,wEAAwE,CAAC;IACxK,CAAC;AACH,CAAC;AAED,+FAA+F;AAC/F,SAAS,sBAAsB,CAAC,IAAsB,EAAE,CAAa,EAAE,MAAe;IACpF,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,aAAa;YAChB,OAAO,wBAAwB,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAC,CAAC,EAAE,qBAAqB,CAAC;QACnH,KAAK,yBAAyB;YAC5B,OAAO,WAAW,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,MAAM,0GAA0G,CAAC,CAAC,IAAI,0CAA0C,CAAC;QACtM,KAAK,wBAAwB;YAC3B,OAAO,gBAAgB,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,MAAM,8GAA8G,CAAC,CAAC,IAAI,0CAA0C,CAAC;QAC/M,KAAK,gBAAgB;YACnB,OAAO,sBAAsB,CAAC,CAAC,KAAK,sBAAsB,CAAC,CAAC,MAAM,8GAA8G,CAAC;QACnL,KAAK,iBAAiB;YACpB,OAAO,eAAe,CAAC,CAAC,MAAM,kJAAkJ,CAAC;IACrL,CAAC;AACH,CAAC;AAED;yFACyF;AACzF,SAAS,eAAe,CAAC,MAAuC,EAAE,MAAc;IAC9E,OAAO,MAAM,KAAK,eAAe;QAC/B,CAAC,CAAC,6BAA6B,MAAM,yDAAyD;QAC9F,CAAC,CAAC,6BAA6B,MAAM,kCAAkC,CAAC;AAC5E,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "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.7.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Cotal-AI/Cotal.git",
+    "directory": "packages/workspace"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@cotal-ai/core": "0.7.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.json",
+    "test": "tsx smoke/preflight.smoke.ts"
+  }
+}