@sema-agent/sdk 0.0.75 → 0.0.77

package/dist/resources/control/secrets.d.ts

@@ -1,25 +1,53 @@
+/** control.secrets — worker app-secret write-through + inventory + batch-rotate + reclaim. Backend: sema-registry
+ *  GET/POST /api/config/secrets, DELETE /api/config/secrets/<name>, POST /api/config/secrets/<name>/rotate,
+ *  GET /api/config/secrets/refs.
+ *
+ *  🔴 INVARIANT I1 (registry-enforced AND mirrored here): a secret VALUE is never persisted, returned, logged, or
+ *     audited — only the NAME. There is NO value-read endpoint by design. The SDK upholds it structurally:
+ *       - set() sends the value ONCE (in the request body) and the result type carries NO value field.
+ *       - The value is NEVER placed in a URL/query/log; the result echoes only the name + advisory next-steps.
+ *       - inventory()/rotate()/delete()/refs() touch NAMES only.
+ *
+ *  inventory/set/rotate/delete are publisher+ (injecting/recreating credentials). refs() is admin. A name a
+ *  worker references → 409 on delete unless force (ControlConflictError); a write colliding with a DIFFERENT
+ *  existing value → 409 unless overwrite. */
 import type { Transport } from "../../transport.js";
 import type { SecretInventory, SecretWriteResult, SecretRotateResult, SecretDeleteResult, SecretRefsResult } from "../../control-types.js";
 export declare class ControlSecretsResource {
     private readonly t;
     constructor(t: Transport);
+    /** GET /api/config/secrets[?orphans=true] → the env-NAMEs in the secret source (NEVER values), each tagged
+     *  referenced/orphan. `orphans` returns only the unreferenced (reclaimable) ones. publisher+. */
     inventory(opts?: {
         orphans?: boolean;
         signal?: AbortSignal;
     }): Promise<SecretInventory>;
+    /** POST /api/config/secrets {name, value} → write-through ONE secret value to the orchestrator secret source.
+     *  🔴 The `value` goes up in the body ONCE and is NEVER returned/logged (I1) — the result carries only `name`
+     *  + advisory next-steps. A collision with a DIFFERENT existing value → 409 ControlConflictError unless
+     *  `overwrite`. publisher+. NOT submit-class (no idempotency key — a re-PUT of the same name/value is a
+     *  server-side no-op; a key would not change the value-overwrite semantics). */
     set(body: {
         name: string;
         value: string;
         overwrite?: boolean;
         signal?: AbortSignal;
     }): Promise<SecretWriteResult>;
+    /** POST /api/config/secrets/<name>/rotate → draft a recreate of EVERY worker referencing this env-NAME (one
+     *  atomic draft; publish to apply). `workers:[]` (200) when nothing references it — not an error. A name
+     *  referenced by nobody → 404 ControlNotFoundError (likely a typo). publisher+. */
     rotate(name: string, opts?: {
         signal?: AbortSignal;
     }): Promise<SecretRotateResult>;
+    /** DELETE /api/config/secrets/<name>[?force=true] → reclaim an orphan name from the secret source.
+     *  `removed:false` is an idempotent no-op (the name wasn't present). A name a worker references → 409
+     *  ControlConflictError unless `force`. publisher+. */
     delete(name: string, opts?: {
         force?: boolean;
         signal?: AbortSignal;
     }): Promise<SecretDeleteResult>;
+    /** GET /api/config/secrets/refs → every env-NAME the effective config references, grouped by name with where
+     *  it's used (audit which env vars each host/service must provide). NAMES only, never values. admin. */
     refs(opts?: {
         signal?: AbortSignal;
     }): Promise<SecretRefsResult>;

package/dist/resources/control/secrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../src/resources/control/secrets.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EACV,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAC7F,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAInC,SAAS,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAUvF,GAAG,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAUjH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOlF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOnG,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAGvE"}
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../src/resources/control/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;6CAY6C;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EACV,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAC7F,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;qGACiG;IAC3F,SAAS,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAK7F;;;;oFAIgF;IAC1E,GAAG,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAOvH;;uFAEmF;IAC7E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIxF;;2DAEuD;IACjD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKzG;4GACwG;IAClG,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAGvE"}

package/dist/resources/control/secrets.js

@@ -3,22 +3,38 @@ export class ControlSecretsResource {
     constructor(t) {
         this.t = t;
     }
+    /** GET /api/config/secrets[?orphans=true] → the env-NAMEs in the secret source (NEVER values), each tagged
+     *  referenced/orphan. `orphans` returns only the unreferenced (reclaimable) ones. publisher+. */
     async inventory(opts) {
         const qs = opts?.orphans ? "?orphans=true" : "";
         return this.t.request({ method: "GET", path: `/api/config/secrets${qs}`, signal: opts?.signal });
     }
+    /** POST /api/config/secrets {name, value} → write-through ONE secret value to the orchestrator secret source.
+     *  🔴 The `value` goes up in the body ONCE and is NEVER returned/logged (I1) — the result carries only `name`
+     *  + advisory next-steps. A collision with a DIFFERENT existing value → 409 ControlConflictError unless
+     *  `overwrite`. publisher+. NOT submit-class (no idempotency key — a re-PUT of the same name/value is a
+     *  server-side no-op; a key would not change the value-overwrite semantics). */
     async set(body) {
         const { signal, overwrite, name, value } = body;
         const qs = overwrite ? "?overwrite=true" : "";
+        // value lives ONLY in the request body — never the path/query/log.
         return this.t.request({ method: "POST", path: `/api/config/secrets${qs}`, body: { name, value }, signal });
     }
+    /** POST /api/config/secrets/<name>/rotate → draft a recreate of EVERY worker referencing this env-NAME (one
+     *  atomic draft; publish to apply). `workers:[]` (200) when nothing references it — not an error. A name
+     *  referenced by nobody → 404 ControlNotFoundError (likely a typo). publisher+. */
     async rotate(name, opts) {
         return this.t.request({ method: "POST", path: `/api/config/secrets/${encodeURIComponent(name)}/rotate`, body: {}, signal: opts?.signal });
     }
+    /** DELETE /api/config/secrets/<name>[?force=true] → reclaim an orphan name from the secret source.
+     *  `removed:false` is an idempotent no-op (the name wasn't present). A name a worker references → 409
+     *  ControlConflictError unless `force`. publisher+. */
     async delete(name, opts) {
         const qs = opts?.force ? "?force=true" : "";
         return this.t.request({ method: "DELETE", path: `/api/config/secrets/${encodeURIComponent(name)}${qs}`, signal: opts?.signal });
     }
+    /** GET /api/config/secrets/refs → every env-NAME the effective config references, grouped by name with where
+     *  it's used (audit which env vars each host/service must provide). NAMES only, never values. admin. */
     async refs(opts) {
         return this.t.request({ method: "GET", path: "/api/config/secrets/refs", signal: opts?.signal });
     }

package/dist/resources/control/secrets.js.map

@@ -1 +1 @@
-{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../../src/resources/control/secrets.ts"],"names":[],"mappings":"AAkBA,MAAM,OAAO,sBAAsB;IACJ;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAI7C,KAAK,CAAC,SAAS,CAAC,IAAkD;QAChE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnG,CAAC;IAOD,KAAK,CAAC,GAAG,CAAC,IAAgF;QACxF,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QAChD,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;QAE9C,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7G,CAAC;IAKD,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAA+B;QACxD,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5I,CAAC;IAKD,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAAgD;QACzE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAClI,CAAC;IAID,KAAK,CAAC,IAAI,CAAC,IAA+B;QACxC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,0BAA0B,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnG,CAAC;CACF"}
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../../src/resources/control/secrets.ts"],"names":[],"mappings":"AAkBA,MAAM,OAAO,sBAAsB;IACJ;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAE7C;qGACiG;IACjG,KAAK,CAAC,SAAS,CAAC,IAAkD;QAChE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnG,CAAC;IAED;;;;oFAIgF;IAChF,KAAK,CAAC,GAAG,CAAC,IAAgF;QACxF,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QAChD,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,mEAAmE;QACnE,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7G,CAAC;IAED;;uFAEmF;IACnF,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAA+B;QACxD,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5I,CAAC;IAED;;2DAEuD;IACvD,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAAgD;QACzE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAClI,CAAC;IAED;4GACwG;IACxG,KAAK,CAAC,IAAI,CAAC,IAA+B;QACxC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,0BAA0B,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnG,CAAC;CACF"}

package/dist/resources/control/users.d.ts

@@ -1,25 +1,47 @@
+/** control.users — console user (RBAC) management + per-user scoped API tokens. Backend: sema-registry
+ *  GET/PUT/DELETE /api/config/users, POST/DELETE /api/config/users/<name>/token. admin-only.
+ *
+ *  These are least-privilege credentials so an external AI/system gets a scoped token instead of the god
+ *  registry admin token. The env bootstrap admin is NOT here (a recovery cred). Self-demotion / self-delete are
+ *  refused server-side (400 ControlValidationError) so the last admin can't lock itself out.
+ *
+ *  🔴 SECRET DISCIPLINE: passwords are write-only (a NEW user needs one; omit on a role-only update — never read
+ *     back; GET never returns hashes). mintToken() returns a PLAINTEXT token ONCE (the registry stores only its
+ *     hash, response is no-store) — treat it like any secret: surface it to the operator once, never log/persist. */
 import type { Transport } from "../../transport.js";
 import type { UsersResult, UserUpsertResult, ControlRole, UserTokenMintResult, UserTokenRevokeResult } from "../../control-types.js";
 export declare class ControlUsersResource {
     private readonly t;
     constructor(t: Transport);
+    /** GET /api/config/users → console users (NO password hashes). admin. */
     list(opts?: {
         signal?: AbortSignal;
     }): Promise<UsersResult>;
+    /** PUT /api/config/users {username, role, password?} → upsert. `password` is REQUIRED for a NEW user (≥8
+     *  chars), OMIT on a role-only update (keeps the existing hash) — it is write-only, never read back. Demoting
+     *  your own account → 400 ControlValidationError. admin. NOT submit-class (idempotent on username). */
     upsert(body: {
         username: string;
         role: ControlRole;
         password?: string;
         signal?: AbortSignal;
     }): Promise<UserUpsertResult>;
+    /** DELETE /api/config/users?username=<u> → delete a user. Deleting your own logged-in account → 400
+     *  ControlValidationError. admin. */
     delete(username: string, opts?: {
         signal?: AbortSignal;
     }): Promise<{
         ok: true;
     }>;
+    /** POST /api/config/users/<name>/token → mint/rotate (replaces any existing) a user's scoped API token.
+     *  🔴 The returned `token` is PLAINTEXT, shown ONCE — the registry stores only its hash and never returns it
+     *  again. Treat it like a secret: surface once, never log/persist. Unknown user → 404 ControlNotFoundError.
+     *  admin. NOT submit-class (a retry would mint a DIFFERENT token — never auto-retried). */
     mintToken(name: string, opts?: {
         signal?: AbortSignal;
     }): Promise<UserTokenMintResult>;
+    /** DELETE /api/config/users/<name>/token → revoke a user's scoped token. Unknown user → 404
+     *  ControlNotFoundError (distinct from already-revoked). admin. */
     revokeToken(name: string, opts?: {
         signal?: AbortSignal;
     }): Promise<UserTokenRevokeResult>;

package/dist/resources/control/users.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../../src/resources/control/users.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EACV,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EACvF,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAGnC,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAO3D,MAAM,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAOzH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC;IAQhF,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAMtF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAGjG"}
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../../src/resources/control/users.ts"],"names":[],"mappings":"AAAA;;;;;;;;;qHASqH;AACrH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EACV,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EACvF,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC,yEAAyE;IACnE,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAIjE;;2GAEuG;IACjG,MAAM,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAK/H;yCACqC;IAC/B,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC;IAItF;;;+FAG2F;IACrF,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI5F;uEACmE;IAC7D,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAGjG"}

package/dist/resources/control/users.js

@@ -3,19 +3,31 @@ export class ControlUsersResource {
     constructor(t) {
         this.t = t;
     }
+    /** GET /api/config/users → console users (NO password hashes). admin. */
     async list(opts) {
         return this.t.request({ method: "GET", path: "/api/config/users", signal: opts?.signal });
     }
+    /** PUT /api/config/users {username, role, password?} → upsert. `password` is REQUIRED for a NEW user (≥8
+     *  chars), OMIT on a role-only update (keeps the existing hash) — it is write-only, never read back. Demoting
+     *  your own account → 400 ControlValidationError. admin. NOT submit-class (idempotent on username). */
     async upsert(body) {
         const { signal, ...rest } = body;
         return this.t.request({ method: "PUT", path: "/api/config/users", body: rest, signal });
     }
+    /** DELETE /api/config/users?username=<u> → delete a user. Deleting your own logged-in account → 400
+     *  ControlValidationError. admin. */
     async delete(username, opts) {
         return this.t.request({ method: "DELETE", path: `/api/config/users?username=${encodeURIComponent(username)}`, signal: opts?.signal });
     }
+    /** POST /api/config/users/<name>/token → mint/rotate (replaces any existing) a user's scoped API token.
+     *  🔴 The returned `token` is PLAINTEXT, shown ONCE — the registry stores only its hash and never returns it
+     *  again. Treat it like a secret: surface once, never log/persist. Unknown user → 404 ControlNotFoundError.
+     *  admin. NOT submit-class (a retry would mint a DIFFERENT token — never auto-retried). */
     async mintToken(name, opts) {
         return this.t.request({ method: "POST", path: `/api/config/users/${encodeURIComponent(name)}/token`, body: {}, signal: opts?.signal });
     }
+    /** DELETE /api/config/users/<name>/token → revoke a user's scoped token. Unknown user → 404
+     *  ControlNotFoundError (distinct from already-revoked). admin. */
     async revokeToken(name, opts) {
         return this.t.request({ method: "DELETE", path: `/api/config/users/${encodeURIComponent(name)}/token`, signal: opts?.signal });
     }

package/dist/resources/control/users.js.map

@@ -1 +1 @@
-{"version":3,"file":"users.js","sourceRoot":"","sources":["../../../src/resources/control/users.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAG7C,KAAK,CAAC,IAAI,CAAC,IAA+B;QACxC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5F,CAAC;IAKD,KAAK,CAAC,MAAM,CAAC,IAAsF;QACjG,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QACjC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1F,CAAC;IAID,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,IAA+B;QAC5D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,8BAA8B,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACxI,CAAC;IAMD,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,IAA+B;QAC3D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACzI,CAAC;IAID,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,IAA+B;QAC7D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,qBAAqB,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACjI,CAAC;CACF"}
+{"version":3,"file":"users.js","sourceRoot":"","sources":["../../../src/resources/control/users.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAE7C,yEAAyE;IACzE,KAAK,CAAC,IAAI,CAAC,IAA+B;QACxC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED;;2GAEuG;IACvG,KAAK,CAAC,MAAM,CAAC,IAAsF;QACjG,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QACjC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1F,CAAC;IAED;yCACqC;IACrC,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,IAA+B;QAC5D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,8BAA8B,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACxI,CAAC;IAED;;;+FAG2F;IAC3F,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,IAA+B;QAC3D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACzI,CAAC;IAED;uEACmE;IACnE,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,IAA+B;QAC7D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,qBAAqB,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACjI,CAAC;CACF"}

package/dist/resources/control/versioning.d.ts

@@ -1,8 +1,16 @@
+/** control.versioning — config audit trail: list changes, diff one change, rollback to a past snapshot.
+ *  Backend: sema-registry GET /api/config/changes, GET /api/config/changes/<id>/diff, POST /api/config/rollback.
+ *
+ *  list/diff are viewer+ (read-only, no version bump). rollback is publisher+ and is itself a validated write
+ *  (re-checks the historical snapshot against the CURRENT schema + cross-domain integrity + quota), appended as
+ *  a NEW change (forward-only history). A stale base / concurrent edit → 409 ControlConflictError. */
 import type { Transport } from "../../transport.js";
 import type { ConfigDomain, ConfigChange, ChangeDiff, RollbackResult } from "../../control-types.js";
 export declare class ControlVersioningResource {
     private readonly t;
     constructor(t: Transport);
+    /** GET /api/config/changes[?domain=&limit=] → recent ConfigChange metadata (newest-first). `limit` is capped
+     *  server-side (≤500). viewer+. */
     changes(opts?: {
         domain?: ConfigDomain;
         limit?: number;
@@ -10,9 +18,13 @@ export declare class ControlVersioningResource {
     }): Promise<{
         changes: ConfigChange[];
     }>;
+    /** GET /api/config/changes/<id>/diff → the domain payload before/after a change (404 → ControlNotFoundError). */
     diff(changeId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<ChangeDiff>;
+    /** POST /api/config/rollback {changeId} → re-apply that change's snapshot as a new change. publisher+. NOT
+     *  submit-class (no idempotency key — a rollback is a CAS write, surfaced 409 on a concurrent edit). A snapshot
+     *  that no longer validates / would break references → 409 ControlConflictError. */
     rollback(body: {
         changeId: string;
         signal?: AbortSignal;

package/dist/resources/control/versioning.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../../../src/resources/control/versioning.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAErG,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAInC,OAAO,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IASrH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAO5E,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;CAI1F"}
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../../../src/resources/control/versioning.ts"],"names":[],"mappings":"AAAA;;;;;sGAKsG;AACtG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAErG,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;uCACmC;IAC7B,OAAO,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IAQ3H,iHAAiH;IAC3G,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAIlF;;wFAEoF;IAC9E,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;CAI1F"}

package/dist/resources/control/versioning.js

@@ -3,6 +3,8 @@ export class ControlVersioningResource {
     constructor(t) {
         this.t = t;
     }
+    /** GET /api/config/changes[?domain=&limit=] → recent ConfigChange metadata (newest-first). `limit` is capped
+     *  server-side (≤500). viewer+. */
     async changes(opts) {
         const q = new URLSearchParams();
         if (opts?.domain)
@@ -12,9 +14,13 @@ export class ControlVersioningResource {
         const qs = q.toString();
         return this.t.request({ method: "GET", path: `/api/config/changes${qs ? `?${qs}` : ""}`, signal: opts?.signal });
     }
+    /** GET /api/config/changes/<id>/diff → the domain payload before/after a change (404 → ControlNotFoundError). */
     async diff(changeId, opts) {
         return this.t.request({ method: "GET", path: `/api/config/changes/${encodeURIComponent(changeId)}/diff`, signal: opts?.signal });
     }
+    /** POST /api/config/rollback {changeId} → re-apply that change's snapshot as a new change. publisher+. NOT
+     *  submit-class (no idempotency key — a rollback is a CAS write, surfaced 409 on a concurrent edit). A snapshot
+     *  that no longer validates / would break references → 409 ControlConflictError. */
     async rollback(body) {
         const { signal, ...rest } = body;
         return this.t.request({ method: "POST", path: "/api/config/rollback", body: rest, signal });

package/dist/resources/control/versioning.js.map

@@ -1 +1 @@
-{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../../../src/resources/control/versioning.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,yBAAyB;IACP;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAI7C,KAAK,CAAC,OAAO,CAAC,IAAsE;QAClF,MAAM,CAAC,GAAG,IAAI,eAAe,EAAE,CAAC;QAChC,IAAI,IAAI,EAAE,MAAM;YAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,IAAI,EAAE,KAAK,KAAK,SAAS;YAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAClE,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnH,CAAC;IAGD,KAAK,CAAC,IAAI,CAAC,QAAgB,EAAE,IAA+B;QAC1D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnI,CAAC;IAKD,KAAK,CAAC,QAAQ,CAAC,IAAgD;QAC7D,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QACjC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9F,CAAC;CACF"}
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../../../src/resources/control/versioning.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,yBAAyB;IACP;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAE7C;uCACmC;IACnC,KAAK,CAAC,OAAO,CAAC,IAAsE;QAClF,MAAM,CAAC,GAAG,IAAI,eAAe,EAAE,CAAC;QAChC,IAAI,IAAI,EAAE,MAAM;YAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,IAAI,EAAE,KAAK,KAAK,SAAS;YAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAClE,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnH,CAAC;IAED,iHAAiH;IACjH,KAAK,CAAC,IAAI,CAAC,QAAgB,EAAE,IAA+B;QAC1D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnI,CAAC;IAED;;wFAEoF;IACpF,KAAK,CAAC,QAAQ,CAAC,IAAgD;QAC7D,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QACjC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9F,CAAC;CACF"}

package/dist/resources/control/workers.d.ts

@@ -1,16 +1,30 @@
+/** control.workers — per-worker operations: read reconciler-reported health, roll the image (full-auto CD),
+ *  rotate (force recreate). Backend: sema-registry GET /api/config/workers/status, POST
+ *  /api/config/workers/roll, POST /api/config/workers/<name>/rotate.
+ *
+ *  status() is admin-readable (viewer+ via the admin path). roll()/rotate() are publisher+ (publishing /
+ *  recreating production). The reconciler-only POST/DELETE on workers/status (SERVICE_PULL_TOKEN, NOT the
+ *  editor Bearer) is DELIBERATELY out of scope — it's a service-token write, a different auth plane. */
 import type { Transport } from "../../transport.js";
 import type { WorkerStatuses, RollResult, RotateResult } from "../../control-types.js";
 export declare class ControlWorkersResource {
     private readonly t;
     constructor(t: Transport);
+    /** GET /api/config/workers/status → reconciler-reported worker health rows. Admin-readable (viewer+). */
     status(opts?: {
         signal?: AbortSignal;
     }): Promise<WorkerStatuses>;
+    /** POST /api/config/workers/roll {sha, repo?} → re-tag matching workers to <base>:<sha> and PUBLISH (full-auto
+     *  CD; bypasses the human approval gate by design). publisher+. No matching worker → clean 200 no-op
+     *  `{rolled:[], published:false}`. NOT submit-class (re-rolling the same sha is an idempotent no-op-publish
+     *  server-side; no client idempotency key needed). */
     roll(body: {
         sha: string;
         repo?: string;
         signal?: AbortSignal;
     }): Promise<RollResult>;
+    /** POST /api/config/workers/<name>/rotate → bump the worker's recreateNonce so the reconciler recreates it +
+     *  re-projects its secrets (drafted; publish to apply). publisher+. Unknown worker → 404 ControlNotFoundError. */
     rotate(name: string, opts?: {
         signal?: AbortSignal;
     }): Promise<RotateResult>;

package/dist/resources/control/workers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workers.d.ts","sourceRoot":"","sources":["../../../src/resources/control/workers.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEvF,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAGnC,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAQhE,IAAI,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAOrF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;CAGnF"}
+{"version":3,"file":"workers.d.ts","sourceRoot":"","sources":["../../../src/resources/control/workers.ts"],"names":[],"mappings":"AAAA;;;;;;wGAMwG;AACxG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEvF,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC,yGAAyG;IACnG,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAItE;;;0DAGsD;IAChD,IAAI,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAK3F;sHACkH;IAC5G,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;CAGnF"}

package/dist/resources/control/workers.js

@@ -3,13 +3,20 @@ export class ControlWorkersResource {
     constructor(t) {
         this.t = t;
     }
+    /** GET /api/config/workers/status → reconciler-reported worker health rows. Admin-readable (viewer+). */
     async status(opts) {
         return this.t.request({ method: "GET", path: "/api/config/workers/status", signal: opts?.signal });
     }
+    /** POST /api/config/workers/roll {sha, repo?} → re-tag matching workers to <base>:<sha> and PUBLISH (full-auto
+     *  CD; bypasses the human approval gate by design). publisher+. No matching worker → clean 200 no-op
+     *  `{rolled:[], published:false}`. NOT submit-class (re-rolling the same sha is an idempotent no-op-publish
+     *  server-side; no client idempotency key needed). */
     async roll(body) {
         const { signal, ...rest } = body;
         return this.t.request({ method: "POST", path: "/api/config/workers/roll", body: rest, signal });
     }
+    /** POST /api/config/workers/<name>/rotate → bump the worker's recreateNonce so the reconciler recreates it +
+     *  re-projects its secrets (drafted; publish to apply). publisher+. Unknown worker → 404 ControlNotFoundError. */
     async rotate(name, opts) {
         return this.t.request({ method: "POST", path: `/api/config/workers/${encodeURIComponent(name)}/rotate`, body: {}, signal: opts?.signal });
     }

package/dist/resources/control/workers.js.map

@@ -1 +1 @@
-{"version":3,"file":"workers.js","sourceRoot":"","sources":["../../../src/resources/control/workers.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,sBAAsB;IACJ;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAG7C,KAAK,CAAC,MAAM,CAAC,IAA+B;QAC1C,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,4BAA4B,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACrG,CAAC;IAMD,KAAK,CAAC,IAAI,CAAC,IAA0D;QACnE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QACjC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAClG,CAAC;IAID,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAA+B;QACxD,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5I,CAAC;CACF"}
+{"version":3,"file":"workers.js","sourceRoot":"","sources":["../../../src/resources/control/workers.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,sBAAsB;IACJ;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAE7C,yGAAyG;IACzG,KAAK,CAAC,MAAM,CAAC,IAA+B;QAC1C,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,4BAA4B,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACrG,CAAC;IAED;;;0DAGsD;IACtD,KAAK,CAAC,IAAI,CAAC,IAA0D;QACnE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QACjC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAClG,CAAC;IAED;sHACkH;IAClH,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAA+B;QACxD,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5I,CAAC;CACF"}

package/dist/resources/elicitations.d.ts

@@ -1,18 +1,53 @@
+/** elicitations — design/99 §E23 (core 1.124.0 `onElicit` seam; service `elicitation.ts`, SHIPPED behind
+ *  `MCP_ELICITATION_ENABLED`). The INBOUND-MCP-elicitation HITL flow: an opted-in MCP server may, MID-tool-call,
+ *  ask the END USER for input. The request rides the SAME open live stream (`POST /v1/tasks/stream`) as a NAMED
+ *  SSE frame (`event: elicitation` / `event: elicitation_complete`), and the shell answers it out-of-band via
+ *  `POST /v1/elicitations/:id/respond`.
+ *
+ *  🔴 LIVE-ONLY + SAME-REPLICA (the `steer()`-class of HITL, NOT the durable approval/checkpoint class): the
+ *  parked promise is in-memory, so a respond that lands on another replica / after answer / after the TTL finds
+ *  nothing → 404. There is NO durable suspend — a crash loses an in-flight elicitation (acceptable for an
+ *  interactive shell; the durable variant waits on the deferred E22 seam).
+ *
+ *  🔴 The `elicitation`/`elicitation_complete` FRAMES are NOT delivered as `AgentEvent` arms — they are a DISTINCT
+ *  vocabulary that interleaves on the live token stream. Tail them off `tasks.streamRaw` and dispatch on the SSE
+ *  `event:` name (the payload also carries `type`, so a name-stripping proxy still works); parse the `data:` with
+ *  this resource's {@link ElicitationFrame} type. Then resolve via {@link ElicitationsResource.respond}.
+ *
+ *  🔴 UNTRUSTED: `message` is service-FENCED (`delimitUntrusted`) + secret-redacted; `requestedSchema` is an
+ *  OPAQUE passthrough (redacted+size-bounded, never interpreted) — the shell MUST still fence it on display.
+ *  v1 is FORM-MODE only (url-mode is rejected upstream as a phishing surface). */
 import type { Transport } from "../transport.js";
+/** A live elicitation frame interleaved on the run's `tasks.streamRaw` connection (service `ElicitationFrame`
+ *  elicitation.ts:41-54). `type` IS the SSE `event:` name AND is echoed in the payload. The shell renders the
+ *  `elicitation` frame as a form dialog and dismisses it on `elicitation_complete`. */
 export interface ElicitationFrame {
     type: "elicitation" | "elicitation_complete";
+    /** The id to echo back to {@link ElicitationsResource.respond}. */
     elicitationId: string;
+    /** Which opted-in MCP server asked (also the trust label core fences `message` against). */
     mcpServerName: string;
+    /** "elicitation" only: the FENCED + secret-redacted human-facing prompt. UNTRUSTED — never re-feed to a model. */
     message?: string;
+    /** "elicitation" only: the server's requested input schema. OPAQUE passthrough — never interpreted/validated;
+     *  still server-controlled UNTRUSTED, so the shell MUST fence it on display. */
     requestedSchema?: unknown;
+    /** "elicitation" only: always "form" in v1 (url-mode is rejected upstream). */
     mode?: "form";
+    /** "elicitation_complete" only: how it resolved (the dialog dismiss reason). */
     action?: "accept" | "decline" | "cancel";
     [k: string]: unknown;
 }
+/** The shell's answer to an {@link ElicitationFrame} (= core's `McpElicitResponse`, types.ts:314-318). On
+ *  `accept`, `content` is a flat record of scalars / string[] — an OPAQUE passthrough core NEVER validates
+ *  against `requestedSchema`. A non-accept (`decline`/`cancel`) carries no content. */
 export interface ElicitResponse {
     action: "accept" | "decline" | "cancel";
+    /** accept only — the submitted form values (flat scalars). The service validates only this OUTER shape, never
+     *  the schema; values must be `string | number | boolean | string[]` (service `parseElicitResponse`). */
     content?: Record<string, string | number | boolean | string[]>;
 }
+/** The 200 ack from a successful respond (service `respond` elicitation.ts:267). */
 export interface ElicitRespondAck {
     elicitationId: string;
     delivery: "applied";
@@ -21,6 +56,14 @@ export interface ElicitRespondAck {
 export declare class ElicitationsResource {
     private readonly t;
     constructor(t: Transport);
+    /** POST /v1/elicitations/:id/respond — resolve a parked inbound-MCP elicitation with the user's form answer.
+     *  The resolved value flows back to the MCP server on the still-open task connection.
+     *
+     *  🔴 OWNER-GATED with a 404 (NO existence oracle): a non-owner AND an unknown/answered/expired/wrong-replica id
+     *  both get 404 — never branch a "does this id exist" decision off the status. A malformed body is a 400
+     *  (existence-independent, like steer). A worker without `MCP_ELICITATION_ENABLED` → 501.
+     *
+     *  Not a submit / not idempotent (it resolves an in-flight promise exactly once) → NO SDK retry. */
     respond(id: string, response: ElicitResponse, opts?: {
         signal?: AbortSignal;
     }): Promise<ElicitRespondAck>;

package/dist/resources/elicitations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"elicitations.d.ts","sourceRoot":"","sources":["../../src/resources/elicitations.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,GAAG,sBAAsB,CAAC;IAE7C,aAAa,EAAE,MAAM,CAAC;IAEtB,aAAa,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAKD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAGxC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC;CAChE;AAGD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;CACzC;AAED,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAUnC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAQhH"}
+{"version":3,"file":"elicitations.d.ts","sourceRoot":"","sources":["../../src/resources/elicitations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;kFAkBkF;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;uFAEuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,GAAG,sBAAsB,CAAC;IAC7C,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,aAAa,EAAE,MAAM,CAAC;IACtB,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;oFACgF;IAChF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;uFAEuF;AACvF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC;6GACyG;IACzG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC;CAChE;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;CACzC;AAED,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;;;;;;wGAOoG;IAC9F,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAQhH"}

package/dist/resources/elicitations.js

@@ -3,6 +3,14 @@ export class ElicitationsResource {
     constructor(t) {
         this.t = t;
     }
+    /** POST /v1/elicitations/:id/respond — resolve a parked inbound-MCP elicitation with the user's form answer.
+     *  The resolved value flows back to the MCP server on the still-open task connection.
+     *
+     *  🔴 OWNER-GATED with a 404 (NO existence oracle): a non-owner AND an unknown/answered/expired/wrong-replica id
+     *  both get 404 — never branch a "does this id exist" decision off the status. A malformed body is a 400
+     *  (existence-independent, like steer). A worker without `MCP_ELICITATION_ENABLED` → 501.
+     *
+     *  Not a submit / not idempotent (it resolves an in-flight promise exactly once) → NO SDK retry. */
     async respond(id, response, opts) {
         return this.t.request({
             method: "POST",

package/dist/resources/elicitations.js.map

@@ -1 +1 @@
-{"version":3,"file":"elicitations.js","sourceRoot":"","sources":["../../src/resources/elicitations.ts"],"names":[],"mappings":"AA2DA,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAU7C,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,QAAwB,EAAE,IAA+B;QACjF,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAmB;YACtC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,oBAAoB,kBAAkB,CAAC,EAAE,CAAC,UAAU;YAC1D,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI,EAAE,MAAM;SACrB,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"elicitations.js","sourceRoot":"","sources":["../../src/resources/elicitations.ts"],"names":[],"mappings":"AA2DA,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAE7C;;;;;;;wGAOoG;IACpG,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,QAAwB,EAAE,IAA+B;QACjF,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAmB;YACtC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,oBAAoB,kBAAkB,CAAC,EAAE,CAAC,UAAU;YAC1D,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI,EAAE,MAAM;SACrB,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/resources/fleet.d.ts

@@ -1,20 +1,67 @@
+/**
+ * MF-Fleet (shell-host data contract) — `GET /v1/fleet/stream` LIVE multi-row fleet view as an SSE PUSH stream.
+ *
+ * The fleet view animates a MULTI-ROW tree: every active task's `status/elapsedMs/tokens/queuedCount` and every
+ * workflow's `doneCount N/M · failedCount` TRANSITION over time. This is a *push* stream, not a one-shot read —
+ * the service sends a SNAPSHOT on connect, then a per-row delta for every transition, with STABLE per-row
+ * identity (`row.id`) so the consumer updates the right row in place.
+ *
+ * 🔴 THE SDK PRODUCES FRAMES, IT DOES NOT MAINTAIN STATE. `stream()` yields each decoded {@link FleetFrame}; the
+ *    consumer (the shell renderer) owns the active-set Map and does the update-in-place / remove. The shell-local
+ *    render state (`main`/tree-`selection`/`timeline`/`depth`/`viewed`/`bulletColor`, MF-Fleet.md) is NOT on the
+ *    wire and the SDK does NOT synthesize it — only the data that transitions rides the frames.
+ *
+ * 🔒 owner-scoped: the route filters to the caller's own active runs (by the credential-derived principal — NOT a
+ *    spoofable header) UNLESS the caller is fleet-wide (an operator / deployment trace token sees every tenant's
+ *    rows, like the trace API). The `scope` field is wire-STRIPPED by the service after the owner-gate — it never
+ *    reaches this SDK, so {@link FleetTaskRow}/{@link FleetWorkflowRow} carry NO `scope`. The connect-time `meta`
+ *    frame's `scoped` flag tells the consumer whether this view is owner-scoped (true) or fleet-wide (false).
+ *
+ * 🔴 NOT RESUMABLE / replica-local + in-process: a drop ends the iterator (re-`stream()` for a fresh snapshot).
+ *    Mirrors `workflows.stream`/`trace.stream` framing but with the fleet vocabulary
+ *    (`meta`/`snapshot`/`task`/`task_remove`/`workflow`/`workflow_remove`). Deliberately uses the vocabulary-
+ *    agnostic `readSseFrames` (NOT `parseSse`, which is hardcoded to the AgentEvent union + auto-reconnect).
+ *    Gated off (no `fleetBus` wired) → 501 (typed error) before any frame.
+ *
+ * Verified against service `1bf7a5c`: handler `streamFleet` (http/server.ts:4874) + `fleet/fleet-bus.ts` types.
+ */
 import type { Transport } from "../transport.js";
+/** The fleet vocabulary the shell renders (MF-Fleet `FleetTask.status`, byte-aligned to service `FleetTaskStatus`
+ *  fleet-bus.ts:27-36). The service maps its run/workflow status onto this NEUTRAL set:
+ *  `awaiting approval` = a needs-review / plan-approval park, `waiting` = a durable suspend. CLOSED on the wire,
+ *  but render open (branch known, fall back to a generic row for any future value). */
 export type FleetTaskStatus = "queued" | "running" | "waiting" | "stopping" | "awaiting approval" | "idle" | "completed" | "failed" | "killed";
+/** One active task row (service `FleetTaskRow` fleet-bus.ts:40-54, MINUS the wire-stripped `scope`). Each frame
+ *  carries the POST-MERGE FULL row (the service merges deltas onto the existing row before emitting), so the
+ *  consumer replaces its row by `id` — NEVER a sparse patch to apply field-by-field. */
 export interface FleetTaskRow {
+    /** Stable identity — the durable runId/taskId (subagent child rows are `"<runId> <taskId>"`). Update/remove by this. */
     id: string;
     name: string;
     description?: string;
+    /** 🔴 §K-7 agent IDENTITY(shell ASK 2026-06-28)—— 短类型 label,让 picker 像 187 显示,而非整段 objective-preview。
+     *  `agentType` = subagent_type/teammate 类型名(如 "Explore"/"general-purpose");`agentName` = in-process
+     *  teammate 的实例名。**值由 core/service 在 fleet 行发**(今天可能缺,缺则 consumer fallback 到 `name`)。additive/tolerate-absent。 */
     agentType?: string;
     agentName?: string;
+    /** Subagent nesting (E2 `parentToolCallId`) — top-level when absent; a child row hangs under its parent's row. */
     parentId?: string;
+    /** design/149(server 1.240):wa\* 行的 workflow 归属附注位(w\* runId)——面板按此分组;footer 树按
+     *  taskId 前缀过滤 wa\*(CC 锚 [1433]),不按此嵌套。ADDITIVE / tolerate-absent。 */
     workflowRunId?: string;
     status: FleetTaskStatus;
+    /** server 1.250(core 1.367 δ):launch 时刻 epoch ms(revive 行=本 revive 周期 wake 时刻)——elapsed
+     *  锚直出,消费方自算不漂(elapsedMs 是服务端快照,保留兼容)。ADDITIVE / tolerate-absent。 */
     startedAt?: number;
     elapsedMs?: number;
     tokens?: number;
+    /** 🔴 `tokenDir` REMOVED(core 裁定,2026-06-28)—— 死字段(0 producer/0 consumer)+ 错 shape
+     *  (`"down"` 因 token 单调递增永不可达)。日后若要 token **速率**指示器 = 全新正确 shape(一个 rate 数),非复活此枚举。 */
     queuedCount?: number;
     awaitingPlanApproval?: boolean;
 }
+/** One workflow row (service `FleetWorkflowRow` fleet-bus.ts:57-69, MINUS the wire-stripped `scope`). `status` is
+ *  the NEUTRAL workflow run status (`running`|`completed`|`failed`), open on read. */
 export interface FleetWorkflowRow {
     id: string;
     name: string;
@@ -26,6 +73,18 @@ export interface FleetWorkflowRow {
     elapsedMs?: number;
     tokens?: number;
 }
+/**
+ * One decoded frame off the fleet stream (service `streamFleet` emit set, http/server.ts:4877-4908). The SDK
+ * yields these in arrival order; the consumer applies them to its own active-set Map:
+ *  - `meta`            — FIRST frame: `{ version, scoped }`. `scoped:true` ⇒ owner-scoped view; `false` ⇒ fleet-wide.
+ *  - `snapshot`        — connect-time FULL state (the visible, scope-stripped rows). Seed the Map from this.
+ *  - `task`            — a single task-row UPSERT (POST-MERGE FULL row) → replace the Map entry by `row.id`.
+ *  - `task_remove`     — the task row left the active set (terminal + swept) → delete `id` from the Map.
+ *  - `workflow`        — a single workflow-row UPSERT (FULL row) → replace by `row.id`.
+ *  - `workflow_remove` — the workflow row left the active set → delete `id`.
+ * OPEN set — branch on `type`, ignore an unknown future frame (heartbeat `: hb` comment frames are swallowed by
+ * the reader and never yielded).
+ */
 export type FleetFrame = {
     type: "meta";
     version: number;
@@ -61,12 +120,23 @@ export type FleetFrame = {
     event: string;
     data: Record<string, unknown>;
 };
+/** design/129-B 缺口②(帧契约,[446]/[1338]⑥)— a background child's COMPLETION notification pushed on the
+ *  ALWAYS-OPEN fleet stream (the only server-push lane an idle shell keeps subscribed): a session-scoped bg
+ *  child finishing while the host sits idle notifies IMMEDIATELY. EVENT semantics, not state — never in the
+ *  snapshot; the consumer's own task_notification queue dedups by (taskId,status). The service filters by
+ *  tenant/`?session=` before send and strips the owner keys — this is the post-strip wire shape
+ *  (fleet-bus.ts `BgNotification` minus `ownerScope`/`ownerSessionId`). */
 export interface FleetBgNotification {
+    /** Registry handle (`a*` domain — the TaskOutput/TaskStop key). */
     taskId: string;
+    /** The child RUN's session id (uuid domain — the a*↔uuid dual anchor), when known. */
     sessionId?: string;
+    /** Stop-cycle counter(server 1.239 起透传 core terminal 帧的 seq;revive 第二周期=更高 seq)——
+     *  consumers fold it into the dedup key ((taskId,status,seq));absent on older engines = 旧键形。 */
     seq?: number;
     status: "completed" | "failed" | "killed";
     summary?: string;
+    /** Background lifetime scope (design/129), NOT the tenant scope. */
     scope: "task" | "session";
     parentTaskId?: string;
     stoppedBy?: string;
@@ -80,17 +150,48 @@ export interface FleetBgNotification {
         path: string;
         edits: number;
     }>;
+    /** server 1.250(core 1.367 δ):委托树 root 宿主会话(固定点语义,嵌套孙代恒锚 root shell)——跨壳
+     *  重启按宿主会话归组的键。ADDITIVE / tolerate-absent。 */
     rootSessionId?: string;
+    /** server 1.258:完成通知的花费汇总(数值 verbatim,fields picked)——完成卡的花费显示。ADDITIVE。 */
+    usage?: {
+        totalTokens?: number;
+        toolUses?: number;
+        durationMs?: number;
+        tokens?: number;
+        turns?: number;
+        costMicroUsd?: number;
+    };
+    /** server 1.258:子代转录锚(引擎铸的 transcript id)——转录跳转键。ADDITIVE / tolerate-absent。 */
+    transcriptId?: string;
 }
+/** The connect-time `meta` frame payload (service http/server.ts:4877). */
 export interface FleetMeta {
     version: number;
+    /** `true` ⇒ this connection is OWNER-SCOPED (the caller's own rows); `false` ⇒ FLEET-WIDE (operator/trace token). */
     scoped: boolean;
+    /** server 1.247+:`true` ⇒ 本连接带 `?session=`(行/通知都按宿主会话过滤)。ADDITIVE / tolerate-absent。 */
     sessionScoped?: boolean;
+    /** server 1.247+ 代际标([1508]):`true` ⇒ 本 server 的 bg_notification 注入路对 scoped 订阅者
+     *  fail-CLOSED——新代际壳可撤帧级 own/foreign 判别(🔴 仅 session-bound 连接;unscoped 连接按设计
+     *  收到同 principal 全部完成帧)。缺键=老 server,保留判别。 */
     bgNotifyFailClosed?: boolean;
 }
 export declare class FleetResource {
     private readonly t;
     constructor(t: Transport);
+    /**
+     * GET /v1/fleet/stream — the LIVE fleet (active task + workflow rows). SSE; the SDK PRODUCES frames, the
+     * consumer maintains the active-set state (update-in-place / remove by `id`).
+     *
+     * Emit order: `meta` (`{version, scoped}`) → `snapshot` (full visible set) → then a `task`/`workflow` upsert
+     * per transition + `task_remove`/`workflow_remove` per departure. Each `task`/`workflow` frame is the POST-MERGE
+     * FULL row (NOT a sparse patch) → replace by `row.id`. Heartbeat comment frames are swallowed.
+     *
+     * 🔴 NOT RESUMABLE: a drop just ends the generator (re-call for a fresh snapshot). Owner-scoped by the
+     * credential principal unless fleet-wide; `scope` is wire-stripped (never appears on a row). 501 (typed) before
+     * any frame when fleet wiring is absent.
+     */
     stream(opts?: {
         signal?: AbortSignal;
     }): AsyncGenerator<FleetFrame>;