@cotal-ai/workspace 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/build/Release/win32-arm64/build.json +1 -1
  2. package/build/Release/win32-x64/build.json +1 -1
  3. package/dist/agent-secrets.d.ts +2 -2
  4. package/dist/agent-secrets.d.ts.map +1 -1
  5. package/dist/agent-secrets.js +2 -2
  6. package/dist/agent-secrets.js.map +1 -1
  7. package/dist/auth-paths.d.ts +8 -2
  8. package/dist/auth-paths.d.ts.map +1 -1
  9. package/dist/auth-paths.js +12 -5
  10. package/dist/auth-paths.js.map +1 -1
  11. package/dist/broker-display.d.ts +4 -0
  12. package/dist/broker-display.d.ts.map +1 -0
  13. package/dist/broker-display.js +29 -0
  14. package/dist/broker-display.js.map +1 -0
  15. package/dist/colors.d.ts +11 -4
  16. package/dist/colors.d.ts.map +1 -1
  17. package/dist/colors.js +36 -9
  18. package/dist/colors.js.map +1 -1
  19. package/dist/connect.d.ts +64 -6
  20. package/dist/connect.d.ts.map +1 -1
  21. package/dist/connect.js +170 -74
  22. package/dist/connect.js.map +1 -1
  23. package/dist/control-target.d.ts +2 -2
  24. package/dist/control-target.js +2 -2
  25. package/dist/credential-actions.d.ts +91 -0
  26. package/dist/credential-actions.d.ts.map +1 -0
  27. package/dist/credential-actions.js +74 -0
  28. package/dist/credential-actions.js.map +1 -0
  29. package/dist/deprecated-daemon-entries.d.ts +30 -0
  30. package/dist/deprecated-daemon-entries.d.ts.map +1 -0
  31. package/dist/deprecated-daemon-entries.js +37 -0
  32. package/dist/deprecated-daemon-entries.js.map +1 -0
  33. package/dist/endpoint-actions.d.ts +31 -0
  34. package/dist/endpoint-actions.d.ts.map +1 -0
  35. package/dist/endpoint-actions.js +2 -0
  36. package/dist/endpoint-actions.js.map +1 -0
  37. package/dist/endpoint-caller.d.ts +74 -0
  38. package/dist/endpoint-caller.d.ts.map +1 -0
  39. package/dist/endpoint-caller.js +118 -0
  40. package/dist/endpoint-caller.js.map +1 -0
  41. package/dist/endpoint-contract.d.ts +32 -0
  42. package/dist/endpoint-contract.d.ts.map +1 -0
  43. package/dist/endpoint-contract.js +92 -0
  44. package/dist/endpoint-contract.js.map +1 -0
  45. package/dist/extension-mutation.d.ts.map +1 -1
  46. package/dist/extension-mutation.js +4 -1
  47. package/dist/extension-mutation.js.map +1 -1
  48. package/dist/extensions.d.ts +28 -8
  49. package/dist/extensions.d.ts.map +1 -1
  50. package/dist/extensions.js +20 -8
  51. package/dist/extensions.js.map +1 -1
  52. package/dist/flags.d.ts +8 -1
  53. package/dist/flags.d.ts.map +1 -1
  54. package/dist/flags.js +9 -7
  55. package/dist/flags.js.map +1 -1
  56. package/dist/index.d.ts +25 -0
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +25 -0
  59. package/dist/index.js.map +1 -1
  60. package/dist/launch-persona.d.ts +10 -0
  61. package/dist/launch-persona.d.ts.map +1 -0
  62. package/dist/launch-persona.js +34 -0
  63. package/dist/launch-persona.js.map +1 -0
  64. package/dist/local-process.d.ts +16 -12
  65. package/dist/local-process.d.ts.map +1 -1
  66. package/dist/local-process.js +7 -2
  67. package/dist/local-process.js.map +1 -1
  68. package/dist/maintenance.d.ts +267 -4
  69. package/dist/maintenance.d.ts.map +1 -1
  70. package/dist/maintenance.js +666 -12
  71. package/dist/maintenance.js.map +1 -1
  72. package/dist/mesh-manifest-schema.d.ts +118 -0
  73. package/dist/mesh-manifest-schema.d.ts.map +1 -0
  74. package/dist/mesh-manifest-schema.js +96 -0
  75. package/dist/mesh-manifest-schema.js.map +1 -0
  76. package/dist/mesh-registry.d.ts +27 -0
  77. package/dist/mesh-registry.d.ts.map +1 -1
  78. package/dist/mesh-registry.js +69 -13
  79. package/dist/mesh-registry.js.map +1 -1
  80. package/dist/mesh-target.d.ts +15 -7
  81. package/dist/mesh-target.d.ts.map +1 -1
  82. package/dist/mesh-target.js +77 -26
  83. package/dist/mesh-target.js.map +1 -1
  84. package/dist/official-connectors.d.ts +13 -0
  85. package/dist/official-connectors.d.ts.map +1 -1
  86. package/dist/official-connectors.js +18 -2
  87. package/dist/official-connectors.js.map +1 -1
  88. package/dist/output.d.ts +147 -0
  89. package/dist/output.d.ts.map +1 -0
  90. package/dist/output.js +186 -0
  91. package/dist/output.js.map +1 -0
  92. package/dist/pid.d.ts +5 -3
  93. package/dist/pid.d.ts.map +1 -1
  94. package/dist/pid.js +25 -13
  95. package/dist/pid.js.map +1 -1
  96. package/dist/preferences.d.ts +93 -0
  97. package/dist/preferences.d.ts.map +1 -0
  98. package/dist/preferences.js +272 -0
  99. package/dist/preferences.js.map +1 -0
  100. package/dist/preflight.d.ts +3 -0
  101. package/dist/preflight.d.ts.map +1 -1
  102. package/dist/preflight.js +6 -3
  103. package/dist/preflight.js.map +1 -1
  104. package/dist/prepared-spaces.d.ts +27 -0
  105. package/dist/prepared-spaces.d.ts.map +1 -0
  106. package/dist/prepared-spaces.js +57 -0
  107. package/dist/prepared-spaces.js.map +1 -0
  108. package/dist/present.d.ts +108 -0
  109. package/dist/present.d.ts.map +1 -0
  110. package/dist/present.js +249 -0
  111. package/dist/present.js.map +1 -0
  112. package/dist/prompt-input.d.ts +12 -0
  113. package/dist/prompt-input.d.ts.map +1 -0
  114. package/dist/prompt-input.js +35 -0
  115. package/dist/prompt-input.js.map +1 -0
  116. package/dist/protected-records.d.ts +102 -0
  117. package/dist/protected-records.d.ts.map +1 -0
  118. package/dist/protected-records.js +465 -0
  119. package/dist/protected-records.js.map +1 -0
  120. package/dist/registration-policy.d.ts +4 -1
  121. package/dist/registration-policy.d.ts.map +1 -1
  122. package/dist/registration-policy.js +4 -3
  123. package/dist/registration-policy.js.map +1 -1
  124. package/dist/render.d.ts +8 -0
  125. package/dist/render.d.ts.map +1 -1
  126. package/dist/render.js +49 -32
  127. package/dist/render.js.map +1 -1
  128. package/dist/service-adapter.d.ts +198 -0
  129. package/dist/service-adapter.d.ts.map +1 -0
  130. package/dist/service-adapter.js +294 -0
  131. package/dist/service-adapter.js.map +1 -0
  132. package/dist/service-custody.d.ts +5 -0
  133. package/dist/service-custody.d.ts.map +1 -0
  134. package/dist/service-custody.js +41 -0
  135. package/dist/service-custody.js.map +1 -0
  136. package/dist/service-definition.d.ts +52 -0
  137. package/dist/service-definition.d.ts.map +1 -0
  138. package/dist/service-definition.js +85 -0
  139. package/dist/service-definition.js.map +1 -0
  140. package/dist/service-definition.schema.json +79 -0
  141. package/dist/service-extension-metadata.d.ts +11 -0
  142. package/dist/service-extension-metadata.d.ts.map +1 -0
  143. package/dist/service-extension-metadata.js +66 -0
  144. package/dist/service-extension-metadata.js.map +1 -0
  145. package/dist/service-identity.d.ts +51 -0
  146. package/dist/service-identity.d.ts.map +1 -0
  147. package/dist/service-identity.js +103 -0
  148. package/dist/service-identity.js.map +1 -0
  149. package/dist/service-observation.d.ts +32 -0
  150. package/dist/service-observation.d.ts.map +1 -0
  151. package/dist/service-observation.js +134 -0
  152. package/dist/service-observation.js.map +1 -0
  153. package/dist/service-preset.d.ts +12 -0
  154. package/dist/service-preset.d.ts.map +1 -0
  155. package/dist/service-preset.js +10 -0
  156. package/dist/service-preset.js.map +1 -0
  157. package/dist/service-startup.d.ts +23 -0
  158. package/dist/service-startup.d.ts.map +1 -0
  159. package/dist/service-startup.js +39 -0
  160. package/dist/service-startup.js.map +1 -0
  161. package/dist/service-stop.d.ts +47 -0
  162. package/dist/service-stop.d.ts.map +1 -0
  163. package/dist/service-stop.js +152 -0
  164. package/dist/service-stop.js.map +1 -0
  165. package/dist/service-target.d.ts +5 -0
  166. package/dist/service-target.d.ts.map +1 -0
  167. package/dist/service-target.js +19 -0
  168. package/dist/service-target.js.map +1 -0
  169. package/dist/signer-export.d.ts +31 -0
  170. package/dist/signer-export.d.ts.map +1 -0
  171. package/dist/signer-export.js +114 -0
  172. package/dist/signer-export.js.map +1 -0
  173. package/dist/space-segmentation.d.ts +13 -2
  174. package/dist/space-segmentation.d.ts.map +1 -1
  175. package/dist/space-segmentation.js +7 -3
  176. package/dist/space-segmentation.js.map +1 -1
  177. package/dist/space.d.ts +5 -5
  178. package/dist/space.d.ts.map +1 -1
  179. package/dist/space.js +8 -6
  180. package/dist/space.js.map +1 -1
  181. package/dist/system-rotation.d.ts +4 -3
  182. package/dist/system-rotation.d.ts.map +1 -1
  183. package/dist/system-rotation.js +16 -6
  184. package/dist/system-rotation.js.map +1 -1
  185. package/dist/web-session.d.ts +7 -0
  186. package/dist/web-session.d.ts.map +1 -1
  187. package/dist/web-session.js +9 -0
  188. package/dist/web-session.js.map +1 -1
  189. package/package.json +6 -2
package/dist/connect.d.ts CHANGED
@@ -1,6 +1,10 @@
1
- import { type EpCaller, type MintOpts, type Profile, type SpaceAuth } from "@cotal-ai/core";
1
+ import { type IssuedCaller, type EpCaller, type MintOpts, type Profile, type SpaceAuth } from "@cotal-ai/core";
2
2
  import { type UserAuthInfo } from "./mesh-registry.js";
3
3
  import { type MeshTarget, type ResolveFlags } from "./mesh-target.js";
4
+ import { type WorkspaceErrorParts } from "./render.js";
5
+ import { CommandFailure, type RefusalCode } from "./output.js";
6
+ import type { MeshTargetErrorCode } from "./mesh-target.js";
7
+ import type { PreflightFailure } from "./preflight.js";
4
8
  /**
5
9
  * The one way every command that touches a running mesh figures out WHICH mesh + with what creds,
6
10
  * and confirms it's actually up — shared by every command surface (@cotal-ai/cli, @cotal-ai/web)
@@ -22,6 +26,8 @@ export interface ConnectFlags extends ResolveFlags {
22
26
  export interface ConnectOpts {
23
27
  instanceId?: string | string[];
24
28
  mint?: Pick<MintOpts, "runDriver" | "runMediator" | "runOperator" | "runAdmitter">;
29
+ /** A read must not sweep or prune the local registry as a hidden prelude. */
30
+ readOnly?: boolean;
25
31
  }
26
32
  /** Raw NATS auth for an off-registry connection — a join link / --token / --user+--pass / --creds.
27
33
  * Structurally matches what `probeConnect` accepts. */
@@ -170,15 +176,59 @@ export declare function refuseStaticCredsForKnownUserAuthOrExit(space: string, s
170
176
  * creds), and a caller that keeps going must stop and say the sentence rather than retry it.
171
177
  */
172
178
  export type ConnectRefusalKind = "transient" | "permanent";
179
+ declare const REFUSAL_BRAND: unique symbol;
173
180
  export declare class ConnectRefusal extends Error {
174
181
  readonly rendered: string;
175
- readonly hint?: string | undefined;
182
+ readonly hint: string | undefined;
183
+ /** A brand that survives two copies of this module, where `instanceof` would not. */
184
+ readonly [REFUSAL_BRAND] = true;
176
185
  readonly kind: ConnectRefusalKind;
177
- constructor(rendered: string, hint?: string | undefined, options?: {
186
+ /** The stable code a structured command reports this refusal under (`AUTH_REQUIRED`,
187
+ * `TARGET_UNAVAILABLE`, ...). Every refusal names one, so none reaches a script unclassified. */
188
+ readonly code: RefusalCode;
189
+ /** The sentence as its message and remedy, when it was written in two parts. */
190
+ readonly parts: WorkspaceErrorParts | undefined;
191
+ constructor(rendered: string, hint: string | undefined, options: {
178
192
  cause?: unknown;
179
193
  kind?: ConnectRefusalKind;
194
+ code: RefusalCode;
195
+ parts?: WorkspaceErrorParts;
180
196
  });
197
+ /** This refusal as a command's classified failure under its code: the message, and the remedy
198
+ * apart from it. */
199
+ failure(): CommandFailure;
181
200
  }
201
+ export declare function isConnectRefusal(e: unknown): e is ConnectRefusal;
202
+ /** The stable code for a mesh target that cannot be resolved. */
203
+ export declare function targetErrorCode(code: MeshTargetErrorCode): RefusalCode;
204
+ /** The stable code for a preflight that did not connect: an outage, a credential the broker needs
205
+ * or a fresh one, or a credential it refused. */
206
+ export declare function preflightCode(failure: PreflightFailure): RefusalCode;
207
+ /** Why a user-auth provider could not issue credentials, when it says: no sign-in session
208
+ * (`signed-out`), its service did not answer (`unavailable`), or it answered and refused this actor
209
+ * (`refused`). A provider sets it as the thrown error's `code`; anything else is unclassified. */
210
+ export type CredentialFailure = "signed-out" | "unavailable" | "refused";
211
+ /** An error a user-auth provider throws, carrying its {@link CredentialFailure}. */
212
+ export declare function credentialFailure(code: CredentialFailure, message: string): Error;
213
+ /**
214
+ * Mint one control-caller instrument for a target the caller already resolved. It is an ISSUANCE
215
+ * (SPEC 13.15): its rails carry a fresh generation, and its ceiling is recorded before the material
216
+ * exists. It depends on no lifecycle gate, so its evidence carries the credential's own five-minute
217
+ * expiry as its liveness. Nothing here reads the registry or the `use` selection, so a caller that
218
+ * pinned its target keeps minting against that target after either one changes.
219
+ *
220
+ * `instanceId` pins THIS one-shot instrument to that manager instance, so it is issued the exact
221
+ * `ep.inst.<endpoint>.<iid>.<command>` rows. Without it the instrument holds only class-rail rows,
222
+ * every instance-addressed request is refused at the broker, and the client renders that refusal
223
+ * as a describe timeout, so `--on` reads as an unresponsive manager rather than an unminted grant.
224
+ * The capability SHAPE is core's to define; this site only decides that a pin was asked for.
225
+ */
226
+ export declare function mintControlInstrument(target: Pick<MeshTarget, "server" | "space" | "tlsRequired"> & {
227
+ readonly auth: SpaceAuth;
228
+ }, tier: "privileged" | "admin", instanceId?: string | string[]): Promise<{
229
+ creds: string;
230
+ epCaller: IssuedCaller;
231
+ }>;
182
232
  /**
183
233
  * Resolve where a mesh-touching command connects + with what creds, THROWING {@link ConnectRefusal}
184
234
  * on every refusal instead of ending the process. {@link connectOrExit} is this plus the printing
@@ -187,9 +237,16 @@ export declare class ConnectRefusal extends Error {
187
237
  * per-user-auth mesh. Those refuse static creds fail-closed because old local creds remain
188
238
  * broker-valid but are the wrong identity plane after the flip.
189
239
  * • Otherwise → resolve the running mesh from the registry (works from any dir), mint `role` creds
190
- * on an auth mesh, and preflight with the registry's stale-prune.
240
+ * on an auth mesh, and preflight with the registry's stale-prune unless readOnly is requested.
191
241
  */
192
242
  export declare function connectOrThrow(flags: ConnectFlags, role: Profile, opts?: ConnectOpts): Promise<Connection>;
243
+ /**
244
+ * Connect to a mesh the caller already resolved, as {@link connectOrThrow} does once it has
245
+ * resolved one: the logged-in user bearer on a user-auth mesh, a minted `role` credential on a
246
+ * static-auth mesh and none on an open one, then a preflight with the registry's stale-prune unless
247
+ * readOnly is requested. It never resolves a target, so a caller that pinned one connects to it.
248
+ */
249
+ export declare function connectTargetOrThrow(target: MeshTarget, role: Profile, opts?: ConnectOpts): Promise<Connection>;
193
250
  /**
194
251
  * Connect as the logged-in user on a user-auth mesh. **No profile/role argument** — there is no
195
252
  * instrument mint on this path; ledger scope is the grant and `epCaller` comes from the bearer
@@ -218,12 +275,12 @@ export declare function reachableOrExit(server: string, auth?: RawAuth): Promise
218
275
  * `--server` override. */
219
276
  export declare function resolveTargetOrThrow(flags: ResolveFlags): Promise<MeshTarget>;
220
277
  /** Confirm the resolved mesh is up and accepts these creds — replaces the raw NATS "Authorization
221
- * Violation" trace with one sentence, and prunes the entry if the broker is gone / mismatched.
278
+ * Violation" trace with one sentence. A readOnly caller never prunes the entry on a mismatch.
222
279
  * The probe + classify + render live beside this file; this wrapper owns the operator I/O — it
223
280
  * acts on the prune decision, colours, and exits. Probes with `probeCreds` when given (the
224
281
  * caller's `--creds`/minted creds); otherwise a throwaway identity is minted from the target's
225
282
  * own trust material. */
226
- export declare function preflightOrThrow(target: MeshTarget, probeCreds?: string): Promise<void>;
283
+ export declare function preflightOrThrow(target: MeshTarget, probeCreds?: string, readOnly?: boolean): Promise<void>;
227
284
  /** {@link preflightOrThrow} with the exiting disposition. */
228
285
  export declare function preflightOrExit(target: MeshTarget, probeCreds?: string): Promise<void>;
229
286
  /**
@@ -233,4 +290,5 @@ export declare function preflightOrExit(target: MeshTarget, probeCreds?: string)
233
290
  export declare function connectOrExit(flags: ConnectFlags, role: Profile, opts?: ConnectOpts): Promise<Connection>;
234
291
  /** {@link resolveTargetOrThrow} with the exiting disposition. */
235
292
  export declare function resolveTargetOrExit(flags: ResolveFlags): Promise<MeshTarget>;
293
+ export {};
236
294
  //# sourceMappingURL=connect.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"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"}
package/dist/connect.js CHANGED
@@ -3,10 +3,11 @@ import { DEFAULT_SERVER, DEFAULT_SPACE, DEV_OWNER, assertLifecycleToken, instanc
3
3
  import { c } from "./colors.js";
4
4
  import { findCotalRoot, hasUserAuthState, userAuthStateDir } from "./auth-paths.js";
5
5
  import { workspaceSecretStore } from "./secret-store-fs.js";
6
- import { findMesh, getCurrent, pruneMesh } from "./mesh-registry.js";
6
+ import { findMesh, pruneMesh } from "./mesh-registry.js";
7
7
  import { isWorkspaceTargetError, resolveMeshTarget } from "./mesh-target.js";
8
8
  import { PREFLIGHT_CONFIRM_TIMEOUT_MS, preflightTarget, pruneStaleMeshes } from "./preflight.js";
9
- import { renderWorkspaceError } from "./render.js";
9
+ import { renderWorkspaceError, workspaceErrorParts } from "./render.js";
10
+ import { CommandFailure } from "./output.js";
10
11
  /** The one way a command turns a {@link Connection} into endpoint auth options — spread this into
11
12
  * `new CotalEndpoint({...})` instead of passing `creds:` directly, so a user-mode connection
12
13
  * (bearer + sentinel) and a static/raw one (creds) ride the same call sites without each command
@@ -132,7 +133,7 @@ export function refuseStaticCredsForKnownUserAuth(space, server, what) {
132
133
  const knownLocalUser = hasUserAuthState(findCotalRoot(), space);
133
134
  if (!knownRecordedUser && !knownLocalUser)
134
135
  return;
135
- throw new ConnectRefusal(`✗ ${what} tried to authenticate with a static creds file, but space "${space}" is a per-user-auth mesh - old --creds files are refused here so they can't bypass user accounts.`, ` Sign in with \`cotal login\` and use the user-mode path instead (for agents: \`cotal spawn\`).`);
136
+ throw new ConnectRefusal(`✗ ${what} tried to authenticate with a static creds file, but space "${space}" is a per-user-auth mesh - old --creds files are refused here so they can't bypass user accounts.`, ` Sign in with \`cotal login\` and use the user-mode path instead (for agents: \`cotal spawn\`).`, { code: "AUTH_REQUIRED" });
136
137
  }
137
138
  /** {@link refuseStaticCredsForKnownUserAuth} with the exiting disposition, for the callers that are
138
139
  * one command deep and want the refusal to end it. */
@@ -144,17 +145,91 @@ export function refuseStaticCredsForKnownUserAuthOrExit(space, server, what) {
144
145
  exitOnRefusal(e);
145
146
  }
146
147
  }
148
+ const REFUSAL_BRAND = Symbol.for("cotal.ConnectRefusal");
147
149
  export class ConnectRefusal extends Error {
148
150
  rendered;
149
151
  hint;
152
+ /** A brand that survives two copies of this module, where `instanceof` would not. */
153
+ [REFUSAL_BRAND] = true;
150
154
  kind;
155
+ /** The stable code a structured command reports this refusal under (`AUTH_REQUIRED`,
156
+ * `TARGET_UNAVAILABLE`, ...). Every refusal names one, so none reaches a script unclassified. */
157
+ code;
158
+ /** The sentence as its message and remedy, when it was written in two parts. */
159
+ parts;
151
160
  constructor(rendered, hint, options) {
152
161
  super(rendered, options);
153
162
  this.rendered = rendered;
154
163
  this.hint = hint;
155
164
  this.name = "ConnectRefusal";
156
- this.kind = options?.kind ?? "permanent";
165
+ this.kind = options.kind ?? "permanent";
166
+ this.code = options.code;
167
+ this.parts = options.parts;
157
168
  }
169
+ /** This refusal as a command's classified failure under its code: the message, and the remedy
170
+ * apart from it. */
171
+ failure() {
172
+ const remedy = this.parts?.remedy ?? this.hint?.trim();
173
+ return new CommandFailure("refused", this.code, this.parts?.message ?? this.rendered.replace(/^✗ /, ""), remedy ? { remedy } : {});
174
+ }
175
+ }
176
+ /** A refusal over a workspace failure: the one-line sentence for a terminal, its parts for a
177
+ * structured command. */
178
+ function workspaceRefusal(e, options) {
179
+ return new ConnectRefusal(renderWorkspaceError(e), undefined, { ...options, parts: workspaceErrorParts(e) });
180
+ }
181
+ export function isConnectRefusal(e) {
182
+ return typeof e === "object" && e !== null && e[REFUSAL_BRAND] === true;
183
+ }
184
+ /** The stable code for a mesh target that cannot be resolved. */
185
+ export function targetErrorCode(code) {
186
+ switch (code) {
187
+ case "no-meshes":
188
+ case "unknown-space":
189
+ case "user-auth-unrecorded":
190
+ return "TARGET_NOT_FOUND";
191
+ case "not-started":
192
+ return "TARGET_UNAVAILABLE";
193
+ case "ambiguous-target":
194
+ return "TARGET_AMBIGUOUS";
195
+ case "default-occupied":
196
+ return "CONFLICT";
197
+ case "stale-auth-root":
198
+ case "unreadable-auth":
199
+ return "DEPENDENCY_UNAVAILABLE";
200
+ }
201
+ }
202
+ /** The stable code for a preflight that did not connect: an outage, a credential the broker needs
203
+ * or a fresh one, or a credential it refused. */
204
+ export function preflightCode(failure) {
205
+ switch (failure) {
206
+ case "unreachable":
207
+ case "slow-link":
208
+ return "TARGET_UNAVAILABLE";
209
+ case "registry-open-now-auth":
210
+ case "open-wants-auth":
211
+ case "stale-auth":
212
+ return "AUTH_REQUIRED";
213
+ case "registry-creds-rejected":
214
+ case "creds-rejected":
215
+ return "PERMISSION_DENIED";
216
+ case "tls-trust":
217
+ return "DEPENDENCY_UNAVAILABLE";
218
+ }
219
+ }
220
+ /** An error a user-auth provider throws, carrying its {@link CredentialFailure}. */
221
+ export function credentialFailure(code, message) {
222
+ return Object.assign(new Error(message), { code });
223
+ }
224
+ function credentialCode(e) {
225
+ const code = e?.code;
226
+ if (code === "signed-out")
227
+ return "AUTH_REQUIRED";
228
+ if (code === "refused")
229
+ return "PERMISSION_DENIED";
230
+ // A provider that cannot issue credentials for a reason it does not name is still a dependency
231
+ // the command could not use; it is not reported as a sign-in the operator could fix.
232
+ return "DEPENDENCY_UNAVAILABLE";
158
233
  }
159
234
  /** The exiting disposition, in ONE place: print what the refusal already decided to say, and end
160
235
  * the command. Anything that is not a {@link ConnectRefusal} is a real fault and rethrows. */
@@ -166,6 +241,32 @@ function exitOnRefusal(e) {
166
241
  console.error(c.dim(e.hint));
167
242
  process.exit(1);
168
243
  }
244
+ /**
245
+ * Mint one control-caller instrument for a target the caller already resolved. It is an ISSUANCE
246
+ * (SPEC 13.15): its rails carry a fresh generation, and its ceiling is recorded before the material
247
+ * exists. It depends on no lifecycle gate, so its evidence carries the credential's own five-minute
248
+ * expiry as its liveness. Nothing here reads the registry or the `use` selection, so a caller that
249
+ * pinned its target keeps minting against that target after either one changes.
250
+ *
251
+ * `instanceId` pins THIS one-shot instrument to that manager instance, so it is issued the exact
252
+ * `ep.inst.<endpoint>.<iid>.<command>` rows. Without it the instrument holds only class-rail rows,
253
+ * every instance-addressed request is refused at the broker, and the client renders that refusal
254
+ * as a describe timeout, so `--on` reads as an unresponsive manager rather than an unminted grant.
255
+ * The capability SHAPE is core's to define; this site only decides that a pin was asked for.
256
+ */
257
+ export async function mintControlInstrument(target, tier, instanceId) {
258
+ const identity = newIdentity();
259
+ const uid = mintLifecycleUid();
260
+ const issued = { generation: mintGeneration(), acceptedToken: mintAcceptedToken() };
261
+ const pinned = instanceId !== undefined ? instancePinnedInstrumentCapabilities(tier, instanceId) : undefined;
262
+ const creds = await withIssuerSession({ servers: target.server, space: target.space, auth: target.auth, tls: target.tlsRequired }, (s) => mintCreds(target.auth, identity, tier === "admin" ? "control-caller-admin" : "control-caller-privileged", {
263
+ lifecycleUid: uid,
264
+ ...(pinned ? { endpointCapabilities: pinned } : {}),
265
+ issued,
266
+ issuance: { mode: "issue", store: s.store, accepted: s.accepted, sources: [] },
267
+ }));
268
+ return { creds, epCaller: { owner: DEV_OWNER, actor: identity.id, uid, generation: issued.generation } };
269
+ }
169
270
  /**
170
271
  * Resolve where a mesh-touching command connects + with what creds, THROWING {@link ConnectRefusal}
171
272
  * on every refusal instead of ending the process. {@link connectOrExit} is this plus the printing
@@ -174,7 +275,7 @@ function exitOnRefusal(e) {
174
275
  * per-user-auth mesh. Those refuse static creds fail-closed because old local creds remain
175
276
  * broker-valid but are the wrong identity plane after the flip.
176
277
  * • Otherwise → resolve the running mesh from the registry (works from any dir), mint `role` creds
177
- * on an auth mesh, and preflight with the registry's stale-prune.
278
+ * on an auth mesh, and preflight with the registry's stale-prune unless readOnly is requested.
178
279
  */
179
280
  export async function connectOrThrow(flags, role, opts = {}) {
180
281
  if (flags.creds) {
@@ -187,7 +288,7 @@ export async function connectOrThrow(flags, role, opts = {}) {
187
288
  refuseStaticCredsForKnownUserAuth(space, flags.server, "--creds");
188
289
  const server = flags.server ?? DEFAULT_SERVER;
189
290
  if (!existsSync(flags.creds))
190
- throw new ConnectRefusal(`✗ creds file not found: ${flags.creds}`);
291
+ throw new ConnectRefusal(`✗ creds file not found: ${flags.creds}`, undefined, { code: "USAGE_INVALID" });
191
292
  const creds = readFileSync(flags.creds, "utf8");
192
293
  // An explicit `--creds` file is an off-registry connect: no mesh record, so no recorded TLS
193
294
  // intent to inherit. It stays non-strict, and that is a real (documented) gap rather than a
@@ -205,13 +306,34 @@ export async function connectOrThrow(flags, role, opts = {}) {
205
306
  // open broker would credless-connect into a callout denial whose copy sends the operator
206
307
  // port-hunting. Name the real state and the recovery instead.
207
308
  if (hasUserAuthState(findCotalRoot(), flags.space))
208
- throw new ConnectRefusal(`✗ space "${flags.space}" has user auth enabled on disk but no usable registry entry - re-record it with \`cotal up\` from its project folder, then sign in (\`cotal login\`)`);
309
+ throw new ConnectRefusal(`✗ space "${flags.space}" has user auth enabled on disk but no usable registry entry - re-record it with \`cotal up\` from its project folder, then sign in (\`cotal login\`)`, undefined, { code: "TARGET_NOT_FOUND" });
209
310
  // A raw OPEN remote broker named entirely on the command line: nothing recorded it, so there
210
311
  // is no intent to honour. Non-strict, same documented gap as `--creds`.
211
312
  await reachableOrThrow(flags.server, {});
212
313
  return { server: flags.server, space: flags.space, tls: false };
213
314
  }
214
- const target = await resolveTargetOrThrow({ server: flags.server, space: flags.space, offline: flags.offline });
315
+ let target;
316
+ if (opts.readOnly) {
317
+ try {
318
+ target = resolveMeshTarget(process.cwd(), { server: flags.server, space: flags.space, offline: flags.offline, readOnly: true });
319
+ }
320
+ catch (e) {
321
+ if (isWorkspaceTargetError(e))
322
+ throw workspaceRefusal({ kind: "target", error: e }, { cause: e, kind: e.code === "no-meshes" || e.code === "unknown-space" || e.code === "not-started" ? "transient" : "permanent", code: targetErrorCode(e.code) });
323
+ throw e;
324
+ }
325
+ }
326
+ else
327
+ target = await resolveTargetOrThrow({ server: flags.server, space: flags.space, offline: flags.offline });
328
+ return connectTargetOrThrow(target, role, opts);
329
+ }
330
+ /**
331
+ * Connect to a mesh the caller already resolved, as {@link connectOrThrow} does once it has
332
+ * resolved one: the logged-in user bearer on a user-auth mesh, a minted `role` credential on a
333
+ * static-auth mesh and none on an open one, then a preflight with the registry's stale-prune unless
334
+ * readOnly is requested. It never resolves a target, so a caller that pinned one connects to it.
335
+ */
336
+ export async function connectTargetOrThrow(target, role, opts = {}) {
215
337
  // USER MODE is a HARD branch: it never mints from on-disk trust material (static creds DO work
216
338
  // on a user-auth broker — minting here would silently connect the operator on the wrong identity
217
339
  // plane) and never connects credlessly. Everything it needs comes from the login cache + the
@@ -229,12 +351,12 @@ export async function connectOrThrow(flags, role, opts = {}) {
229
351
  // subjects can be built. "Never consults role" means never mints by role — not "no triple".
230
352
  if (target.mode === "user") {
231
353
  if (role === "control-caller-privileged" || role === "control-caller-admin")
232
- throw new ConnectRefusal(`✗ cannot mint the "${role}" instrument on a user-mode mesh - the logged-in user bearer is the control surface (ledger scope is the grant). Operator instruments are static-mesh only.`);
354
+ throw new ConnectRefusal(`✗ cannot mint the "${role}" instrument on a user-mode mesh - the logged-in user bearer is the control surface (ledger scope is the grant). Operator instruments are static-mesh only.`, undefined, { code: "UNSUPPORTED" });
233
355
  // A workflow run's own profiles are minted by the space signer, which a client of a user-auth
234
356
  // mesh does not hold; the bearer carries none of their rows. The hosted path refuses too (the
235
357
  // manager names why), so the sentence does not steer at it.
236
358
  if (role === "run-driver" || role === "run-mediator" || role === "run-operator")
237
- throw new ConnectRefusal(`✗ cannot mint the "${role}" credential on a user-mode mesh - a run's driver rides a credential only the space signer mints (SPEC 14.6), and a user-auth mesh hosts no runs yet either. Run programs on a static-auth mesh.`);
359
+ throw new ConnectRefusal(`✗ cannot mint the "${role}" credential on a user-mode mesh - a run's driver rides a credential only the space signer mints (SPEC 14.6), and a user-auth mesh hosts no runs yet either. Run programs on a static-auth mesh.`, undefined, { code: "UNSUPPORTED" });
238
360
  return userConnectOrThrow(target);
239
361
  }
240
362
  // An operator INSTRUMENT mint pins a fresh lifecycle uid: its ep-rail caller rows are
@@ -244,66 +366,44 @@ export async function connectOrThrow(flags, role, opts = {}) {
244
366
  let creds;
245
367
  let epCaller;
246
368
  if (target.auth) {
247
- const identity = newIdentity();
248
- if (instrument) {
369
+ if (role === "deployer") {
370
+ // The deployer is NOT an issuance. It is the one instrument the profile table leaves
371
+ // unbounded (a deploy spans planning, launches and their readiness waits), and an issuance
372
+ // bound to no lifecycle gate must carry an expiry as its liveness (SPEC 13.15), so the mint
373
+ // would refuse it. Nothing it does needs the versioned rail: only `run-start` requires the
374
+ // binding, and a deploy starts no run. It rides the legacy rail under its own uid.
375
+ const identity = newIdentity();
249
376
  const uid = mintLifecycleUid();
250
- // `--on <instanceId>`: pin THIS one-shot instrument to the instance the resolve already
251
- // chose, so it is issued the exact `ep.inst.<endpoint>.<iid>.<command>` rows for this
252
- // invocation. Without it the instrument holds only class-rail rows, every instance-addressed
253
- // request is refused at the broker, and the client renders that refusal as a describe
254
- // timeout — so `--on` reads as an unresponsive manager rather than an unminted grant. The
255
- // capability SHAPE is core's to define; this site only decides that a pin was asked for.
256
- // Only the two control-caller tiers take it: `deployer` mints through a different arm that
257
- // does not consume endpoint capabilities, so pinning it here would silently do nothing.
258
- const tier = role === "control-caller-admin" ? "admin" : "privileged";
259
- const pinned = opts.instanceId !== undefined && role !== "deployer"
260
- ? instancePinnedInstrumentCapabilities(tier, opts.instanceId)
261
- : undefined;
262
- if (role === "deployer") {
263
- // The deployer is NOT an issuance. It is the one instrument the profile table leaves
264
- // unbounded (a deploy spans planning, launches and their readiness waits), and an issuance
265
- // bound to no lifecycle gate must carry an expiry as its liveness (SPEC 13.15), so the mint
266
- // would refuse it. Nothing it does needs the versioned rail: only `run-start` requires the
267
- // binding, and a deploy starts no run. It rides the legacy rail under its own uid.
268
- creds = await mintCreds(target.auth, identity, role, { lifecycleUid: uid });
269
- epCaller = { owner: DEV_OWNER, actor: identity.id, uid };
377
+ creds = await mintCreds(target.auth, identity, role, { lifecycleUid: uid });
378
+ epCaller = { owner: DEV_OWNER, actor: identity.id, uid };
379
+ }
380
+ else if (instrument) {
381
+ // `--on <instanceId>` reaches the mint as `opts.instanceId`. Only the two control-caller
382
+ // tiers take it: `deployer` mints through a different arm that does not consume endpoint
383
+ // capabilities, so pinning it would silently do nothing.
384
+ try {
385
+ ({ creds, epCaller } = await mintControlInstrument({ server: target.server, space: target.space, tlsRequired: target.tlsRequired, auth: target.auth }, role === "control-caller-admin" ? "admin" : "privileged", opts.instanceId));
270
386
  }
271
- else {
272
- // A control-caller instrument is an ISSUANCE (SPEC 13.15): its rails carry a fresh
273
- // generation, and its ceiling is recorded before the material exists. It depends on no
274
- // lifecycle gate, so its evidence carries the credential's own five-minute expiry as its
275
- // liveness.
276
- const issued = { generation: mintGeneration(), acceptedToken: mintAcceptedToken() };
277
- try {
278
- creds = await withIssuerSession({ servers: target.server, space: target.space, auth: target.auth, tls: target.tlsRequired }, (s) => mintCreds(target.auth, identity, role, {
279
- lifecycleUid: uid,
280
- ...(pinned ? { endpointCapabilities: pinned } : {}),
281
- issued,
282
- issuance: { mode: "issue", store: s.store, accepted: s.accepted, sources: [] },
283
- }));
284
- }
285
- catch (e) {
286
- // The issuer dial is now the first thing on this path to touch the broker. A mesh that
287
- // is not there must still be reported in the preflight's classified words (and prune the
288
- // stale entry as before), not as the raw transport error the dial throws. Anything the
289
- // preflight does not explain is the issuer's own fault and surfaces as such.
290
- await preflightOrThrow(target);
291
- throw e;
292
- }
293
- epCaller = { owner: DEV_OWNER, actor: identity.id, uid, generation: issued.generation };
387
+ catch (e) {
388
+ // The issuer dial is now the first thing on this path to touch the broker. A mesh that
389
+ // is not there must still be reported in the preflight's classified words (and prune the
390
+ // stale entry as before), not as the raw transport error the dial throws. Anything the
391
+ // preflight does not explain is the issuer's own fault and surfaces as such.
392
+ await preflightOrThrow(target, undefined, opts.readOnly === true);
393
+ throw e;
294
394
  }
295
395
  }
296
396
  else {
297
- creds = await mintCreds(target.auth, identity, role, opts.mint ?? {});
397
+ creds = await mintCreds(target.auth, newIdentity(), role, opts.mint ?? {});
298
398
  }
299
399
  }
300
400
  // A registered AUTH mesh with no seed is still authenticated. A credless probe would
301
401
  // classify it as "open now wants auth" and prune or attach as open. Refuse here,
302
402
  // naming the recorded mode.
303
403
  if (target.mode === "auth" && !target.auth) {
304
- throw new ConnectRefusal(`✗ mesh "${target.space}" is a static-auth mesh but the seed under ${target.root} is missing. Restore the seed at that checkout. This mesh is not open.`);
404
+ throw new ConnectRefusal(`✗ mesh "${target.space}" is a static-auth mesh but the seed under ${target.root} is missing. Restore the seed at that checkout. This mesh is not open.`, undefined, { code: "DEPENDENCY_UNAVAILABLE" });
305
405
  }
306
- await preflightOrThrow(target, creds);
406
+ await preflightOrThrow(target, creds, opts.readOnly === true);
307
407
  // THE REGISTRY-RESOLVED PATH, and the one that must inherit the recorded decision: if the mesh
308
408
  // record says this broker is TLS-required, the connection REQUIRES it. This is the site whose
309
409
  // omission had no symptom - it connects either way against an honest broker.
@@ -345,7 +445,7 @@ export async function connectUserControlOrExit(flags) {
345
445
  export async function connectUserControlOrThrow(flags) {
346
446
  const target = await resolveTargetOrThrow(flags);
347
447
  if (target.mode !== "user")
348
- throw new ConnectRefusal(`✗ connectUserControlOrThrow requires a user-auth mesh (resolved mode is "${target.mode}")`);
448
+ throw new ConnectRefusal(`✗ connectUserControlOrThrow requires a user-auth mesh (resolved mode is "${target.mode}")`, undefined, { code: "UNSUPPORTED" });
349
449
  return userConnectOrThrow(target);
350
450
  }
351
451
  /** The user-mode connect: resolve the space's auth provider from the registry (composition-root
@@ -363,7 +463,7 @@ async function userConnectOrThrow(target) {
363
463
  return await userConnect(target);
364
464
  }
365
465
  catch (e) {
366
- throw new ConnectRefusal(`✗ ${e instanceof Error ? e.message : String(e)}`, undefined, { cause: e });
466
+ throw new ConnectRefusal(`✗ ${e instanceof Error ? e.message : String(e)}`, undefined, { cause: e, code: credentialCode(e) });
367
467
  }
368
468
  }
369
469
  async function userConnect(target) {
@@ -418,7 +518,8 @@ export async function reachableOrThrow(server, auth = {}) {
418
518
  // of this: it is transport, not identity, and a TLS-only connection presents no credential.
419
519
  const hasAuth = Boolean(auth.creds ?? auth.token ?? (auth.user && auth.pass));
420
520
  const kind = probe.reason === "timeout" || probe.reason === "unreachable" ? "transient" : "permanent";
421
- throw new ConnectRefusal(renderWorkspaceError({ kind: "reachable", reason: probe.reason, server, hasAuth }), undefined, { kind });
521
+ const code = kind === "transient" ? "TARGET_UNAVAILABLE" : probe.reason === "auth-required" && hasAuth ? "PERMISSION_DENIED" : "AUTH_REQUIRED";
522
+ throw workspaceRefusal({ kind: "reachable", reason: probe.reason, server, hasAuth }, { kind, code });
422
523
  }
423
524
  /** {@link reachableOrThrow} with the exiting disposition. */
424
525
  export async function reachableOrExit(server, auth = {}) {
@@ -448,26 +549,20 @@ export async function resolveTargetOrThrow(flags) {
448
549
  // found is transient: the sweep keeps a crashed `up` mesh as offline, so it resolves again once
449
550
  // its broker is back. A record that exists and is broken, or several that match, is not.
450
551
  if (isWorkspaceTargetError(e)) {
451
- const kind = e.code === "no-meshes" || e.code === "unknown-space" ? "transient" : "permanent";
452
- throw new ConnectRefusal(renderWorkspaceError({ kind: "target", error: e }), undefined, { cause: e, kind });
552
+ const kind = e.code === "no-meshes" || e.code === "unknown-space" || e.code === "not-started" ? "transient" : "permanent";
553
+ throw workspaceRefusal({ kind: "target", error: e }, { cause: e, kind, code: targetErrorCode(e.code) });
453
554
  }
454
555
  throw e;
455
556
  }
456
- // If a dangling `current` was silently bypassed — it named a mesh that's since gone (deleted,
457
- // or kept as offline) and we fell back to the only live one — say so. The N>1 case errors
458
- // loudly; this is the one spot that would otherwise quietly redirect a stale default.
459
- const cur = getCurrent();
460
- if (cur && (!findMesh(cur) || offline.includes(cur)) && target.source === "registry")
461
- console.error(c.dim(`note: default mesh "${cur}" is down - using "${target.space}"`));
462
557
  return target;
463
558
  }
464
559
  /** Confirm the resolved mesh is up and accepts these creds — replaces the raw NATS "Authorization
465
- * Violation" trace with one sentence, and prunes the entry if the broker is gone / mismatched.
560
+ * Violation" trace with one sentence. A readOnly caller never prunes the entry on a mismatch.
466
561
  * The probe + classify + render live beside this file; this wrapper owns the operator I/O — it
467
562
  * acts on the prune decision, colours, and exits. Probes with `probeCreds` when given (the
468
563
  * caller's `--creds`/minted creds); otherwise a throwaway identity is minted from the target's
469
564
  * own trust material. */
470
- export async function preflightOrThrow(target, probeCreds) {
565
+ export async function preflightOrThrow(target, probeCreds, readOnly = false) {
471
566
  // USER-mode targets are never credless-probed here: the callout denies a bare connect, the
472
567
  // classifier reads that as a stale-entry mismatch, and a mismatch prune would drop a healthy
473
568
  // `up` record (found live: foreground `spawn` did exactly this and every later command fell
@@ -476,7 +571,8 @@ export async function preflightOrThrow(target, probeCreds) {
476
571
  if (target.mode === "user") {
477
572
  if (await isReachable(target.server))
478
573
  return;
479
- throw new ConnectRefusal(`✗ no mesh running at ${target.server} - mesh "${target.space}" is recorded at ${target.root} but not running; run \`cotal up\` there to restart`, undefined, { kind: "transient" });
574
+ const parts = { message: `no mesh running at ${target.server}; mesh "${target.space}" is recorded at ${target.root} but not running`, remedy: "run `cotal up` there to restart" };
575
+ throw new ConnectRefusal(`✗ ${parts.message} - ${parts.remedy}`, undefined, { kind: "transient", code: "TARGET_UNAVAILABLE", parts });
480
576
  }
481
577
  const r = await preflightTarget(target, probeCreds);
482
578
  if (r.ok)
@@ -485,9 +581,9 @@ export async function preflightOrThrow(target, probeCreds) {
485
581
  // record is one an automatic sweep may delete. Liveness (`unreachable`) keeps an `up` record as
486
582
  // `offline`; mismatch (creds rejected / mode flipped) still drops it. Manual never deletes.
487
583
  // The message reports what ACTUALLY happened, so it never claims a removal that the registry refused.
488
- const pruned = r.prune ? pruneMesh(target.space, r.kind === "unreachable" ? "gone" : "mismatch") : false;
584
+ const pruned = !readOnly && r.prune ? pruneMesh(target.space, r.kind === "unreachable" ? "gone" : "mismatch") : false;
489
585
  const kind = r.kind === "unreachable" || r.kind === "slow-link" ? "transient" : "permanent";
490
- throw new ConnectRefusal(renderWorkspaceError({ kind: "preflight", failure: r.kind, target, pruned }), undefined, { kind });
586
+ throw workspaceRefusal({ kind: "preflight", failure: r.kind, target, pruned }, { kind, code: preflightCode(r.kind) });
491
587
  }
492
588
  /** {@link preflightOrThrow} with the exiting disposition. */
493
589
  export async function preflightOrExit(target, probeCreds) {