@corenel/harness 0.10.0 → 0.12.0

package/dist/sidecar/server.js

@@ -1,9 +1,23 @@
-import { SIDECAR_PROTOCOL, errMessage, isLoopbackHost, parseMcpToolAddress, } from '@corenel/protocol';
+import { DEFAULT_STATE_DIR, RUN_TASK_FEATURE, RUN_PLAN_FEATURE, CREW_DEPLOY_FEATURE, denialNote } from '@corenel/protocol';
+import { SIDECAR_PROTOCOL, errMessage, isLoopbackHost, isLoopbackAddress, parseMcpToolAddress, isWebPushSubscription, MAX_ASSERTION_LEN, } from '@corenel/protocol';
+import { pairingTokenHash } from './identity.js';
+const NO_CHECKS = 'this sidecar does not run checks (start it with --allow-shell)';
+/** Default pre-pairing deadline: a real client sends `hello` immediately. */
+export const HELLO_DEADLINE_MS = 10000;
+/** Denied hellos one connection may send before it is closed: a client with a
+ *  stale token needs one, not an unbounded guessing loop. */
+export const MAX_FAILED_HELLOS = 3;
 /** How long the welcome waits on `clientDirName` before going out without it. A
  * manifest write is a few milliseconds; anything near this is a wedged disk, and
  * a client left with no handshake at all is worse than one that has to fall back
  * to deducing its own directory. */
 const DIR_NAME_TIMEOUT_MS = 3000;
+/** How long pairing waits on the identity verifier before going out
+ * UNVERIFIED. The same bound as `DIR_NAME_TIMEOUT_MS`, and run concurrently
+ * with it, so a verifier that hangs never makes the handshake slower than a
+ * wedged dirName lookup already could. A timeout never refuses the connection:
+ * it only withholds the widened trust a verified id would earn. */
+export const IDENTITY_TIMEOUT_MS = 3000;
 /** True for anything with a callable `.then` -- covers native Promises and any
  * other thenable a caller's `onClient` might return, without assuming it's a
  * real Promise instance (the declared type is `() => void`; an async function
@@ -24,6 +38,19 @@ const MAX_IDENTITY_FIELD_LEN = 200;
  * daemon produces -- it only stops an unbounded list from becoming unbounded
  * work at a point where the connection has just authenticated. */
 const MAX_CLAIMED_ACCOUNTS = 8;
+/** Bounds on a hello's client `capabilities`. A list outside them is carried
+ * as NOTHING (not truncated): it is informational only, so the fail-safe
+ * reading of a malformed list is "an older app". */
+const MAX_CAPABILITIES = 16;
+const MAX_CAPABILITY_LEN = 64;
+/** The client capabilities a hello announced, or [] when absent or malformed
+ * (not an array, too long, or holding anything but short strings). */
+function announcedCapabilities(v) {
+    if (!Array.isArray(v) || v.length > MAX_CAPABILITIES)
+        return [];
+    const list = v;
+    return list.every((c) => typeof c === 'string' && c.length <= MAX_CAPABILITY_LEN) ? list : [];
+}
 /** Base64-encode bytes without a Node Buffer (btoa is in the browser + Node 18+),
  * so this module stays free of node:* types for the shared harness build. */
 function bytesToB64(bytes) {
@@ -32,6 +59,16 @@ function bytesToB64(bytes) {
         bin += String.fromCharCode(bytes[i]);
     return btoa(bin);
 }
+/** A fresh, single-use identity-challenge nonce: 32 random bytes, base64url
+ * (43 characters, no padding). `crypto.getRandomValues` — not node:crypto's
+ * `randomBytes` — for the same host-agnostic reason as `bytesToB64` above:
+ * it is a Web Crypto global in both the browser and Node 18+, so this module
+ * stays free of node:* imports. */
+function makeNonce() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return bytesToB64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
 /** Constant-time string compare for the pairing token — avoids leaking it via the
  * early-exit timing of `!==`. Pure JS so this stays host-agnostic (no node:crypto in
  * a possibly-bundled module). The token is a fixed-length hex string, so comparing
@@ -44,6 +81,39 @@ function safeEqual(a, b) {
         diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
     return diff === 0;
 }
+/** Longest verdict reason the harness will put on a welcome or in a log. */
+const MAX_REASON_LEN = 80;
+/** A verifier-supplied reason (or error message), made safe to echo on the
+ * welcome and write to the log WHATEVER the verifier put in it: only
+ * `[A-Za-z0-9 .,:_()-]` survives (no newlines, quotes, braces or log-forging
+ * control text), whitespace runs collapse, and the result is capped at
+ * MAX_REASON_LEN. Nothing left means 'rejected'. The harness does this itself
+ * rather than trusting every verifier to keep its reasons short and clean. */
+function sanitizeReason(raw) {
+    const kept = raw.replace(/[^A-Za-z0-9 .,:_()-]/g, '').replace(/ {2,}/g, ' ').trim().slice(0, MAX_REASON_LEN).trim();
+    return kept || 'rejected';
+}
+/** A verifier's answer, re-checked before it can bind anything. The port is
+ * daemon code, but a verdict that claims success without a usable user id must
+ * fail CLOSED (unverified), never bind an empty, oversized or non-string id. A
+ * failure with no usable reason still reads as a failure. */
+function normalizeVerdict(got) {
+    if (typeof got === 'object' && got !== null) {
+        const r = got;
+        if (r.ok === true) {
+            const userId = r.identity?.userId;
+            const issuer = r.identity?.issuer;
+            if (typeof userId === 'string' && userId && userId.length <= MAX_IDENTITY_FIELD_LEN) {
+                return { ok: true, identity: { userId, issuer: typeof issuer === 'string' ? issuer : '' } };
+            }
+            return { ok: false, reason: 'malformed verdict' };
+        }
+        if (r.ok === false) {
+            return { ok: false, reason: typeof r.reason === 'string' ? sanitizeReason(r.reason) : 'rejected' };
+        }
+    }
+    return { ok: false, reason: 'malformed verdict' };
+}
 export class SidecarServer {
     constructor(opts) {
         Object.defineProperty(this, "ch", {
@@ -70,6 +140,19 @@ export class SidecarServer {
             writable: true,
             value: false
         });
+        /** Denied hellos on this connection (see MAX_FAILED_HELLOS). */
+        Object.defineProperty(this, "failedHellos", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "clearHelloDeadline", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => { }
+        });
         Object.defineProperty(this, "hostSeq", {
             enumerable: true,
             configurable: true,
@@ -89,7 +172,7 @@ export class SidecarServer {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: '.corenel'
+            value: DEFAULT_STATE_DIR
         });
         /** The authenticated connection's `clientId`, retained here (from `hello`) so
          * later `host-sync-*` messages can be attributed to their owner without
@@ -112,6 +195,63 @@ export class SidecarServer {
             writable: true,
             value: void 0
         });
+        /** The connection's claimed accounts from the same `hello`, kept beside
+         * `clientId` so web push can be filed under both. Bounded/typeof-filtered
+         * the same way `clientId` is -- see the `accounts` local in `onHello`. */
+        Object.defineProperty(this, "accounts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        /** The VERIFIED user id (the identity token's `sub`), set at most once, in
+         * `onHello`, after the pairing token passed and the verifier answered. It is
+         * never re-assigned: no message re-authenticates, so a hijacked socket cannot
+         * swap whose connection this is. Undefined = unverified, which is every
+         * connection on a daemon with no `identity` verifier. The token itself is
+         * never kept. */
+        Object.defineProperty(this, "verifiedUserId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: undefined
+        });
+        /** The verdict echoed on the welcome, when a verifier is wired. Dead by the
+         * time a welcome is ever sent -- `onHello`'s identity block always
+         * overwrites it with a real reason ('not requested', 'no daemon id', or the
+         * challenge/assert outcome) before `sendWelcome` reads it -- but given a
+         * value anyway rather than left to a type assertion, matching every other
+         * field on this class. */
+        Object.defineProperty(this, "identityResult", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: { verified: false, reason: 'not requested' }
+        });
+        /** Resolves the promise `onHello` is awaiting on `identity-assert`. Cleared
+         * (set to `undefined`) the moment it is used, which is what makes a SECOND
+         * `identity-assert` on the same connection a no-op: with no resolver left,
+         * the handler in `onMessage` has nothing to call and the message is simply
+         * ignored. Also resolved (to a timeout-shaped answer) from the close
+         * handler, so a connection that drops while a verdict is pending does not
+         * leave `onHello` waiting on a promise nothing will ever settle until the
+         * unrelated 3s timer fires. */
+        Object.defineProperty(this, "identityAssertResolve", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Set when the channel closes. `onHello` awaits (identity, dirName) before
+         * attaching to attendance and sending the welcome; a connection that dropped
+         * during that wait must not be attached afterwards, or the registry would
+         * hold a dead client that nothing ever detaches. */
+        Object.defineProperty(this, "closed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         /** This connection's attended-client object, retained so an answer it sends
          * can be attributed to it. Typed `unknown` because its only consumer is the
          * registry's own identity lookup, which takes `unknown` for the
@@ -269,6 +409,15 @@ export class SidecarServer {
         for (const t of opts.tools)
             this.tools.set(t.name, t);
         this.ch.onMessage((m) => this.onMessage(m));
+        const deadline = setTimeout(() => {
+            if (this.authed || this.closed)
+                return;
+            this.opts.log?.('closing a connection that did not pair in time');
+            this.ch.close();
+        }, opts.helloDeadlineMs ?? HELLO_DEADLINE_MS);
+        // Never keep a node process alive for this timer alone.
+        deadline.unref?.();
+        this.clearHelloDeadline = () => clearTimeout(deadline);
         // Every connected server subscribes, which is what makes a root added by one
         // paired client reach ALL of them: two browsers on one daemon must never
         // disagree about what is reachable. The payload is the COMPLETE set.
@@ -295,6 +444,14 @@ export class SidecarServer {
             this.ch.send({ t: 'room-progress', room });
         });
         this.ch.onClose?.(() => {
+            this.closed = true;
+            this.clearHelloDeadline();
+            // A connection that drops while `onHello` is awaiting `identity-assert`
+            // must not leave that promise pending until the unrelated 3s timer
+            // fires -- settle it now, exactly like a timeout, so onHello observes
+            // `this.closed` on its very next line and attaches/sends nothing.
+            this.identityAssertResolve?.({ kind: 'timeout' });
+            this.identityAssertResolve = undefined;
             this.attendedDetach?.();
             this.attendedDetach = undefined;
             // Leave the live set, or this directory reads as connected for ever and
@@ -324,10 +481,33 @@ export class SidecarServer {
     onMessage(m) {
         switch (m.t) {
             case 'hello':
+                /* Identity is fixed at first hello; a second must not re-own the
+                 * connection. `authed` is set SYNCHRONOUSLY inside onHello, before its
+                 * first await, so this also refuses a second hello that arrives while
+                 * the first is still waiting on the identity verifier. */
                 if (this.authed)
-                    return; // identity is fixed at first hello; a second must not re-own the connection
-                this.onHello(m);
+                    return;
+                /* onHello is async now, so a throw after its awaits (attendance.attach,
+                 * sendWelcome, hosts.attach) would be an UNHANDLED rejection -- which
+                 * takes the whole daemon down, not just this connection. Log it. */
+                void this.onHello(m).catch((err) => this.opts.log?.(`hello failed: ${errMessage(err)}`));
                 return;
+            case 'identity-assert': {
+                // Only the FIRST identity-assert on a connection counts -- the
+                // resolver is cleared the instant it is used (right here), so a
+                // second (or unsolicited, or late-after-timeout) one finds nothing to
+                // call and is silently ignored, which is also what consumes the
+                // single-use nonce: nothing after this point can still redeem it.
+                const resolve = this.identityAssertResolve;
+                this.identityAssertResolve = undefined;
+                if (!resolve)
+                    return;
+                if (typeof m.assertion === 'string' && m.assertion)
+                    resolve({ kind: 'assertion', value: m.assertion });
+                else
+                    resolve({ kind: 'none' });
+                return;
+            }
             case 'invoke':
                 if (!this.authed) {
                     this.ch.send({ t: 'invoke-result', id: m.id, ok: false, error: 'not authenticated' });
@@ -368,6 +548,13 @@ export class SidecarServer {
                     return;
                 this.onSubscribe(m);
                 return;
+            case 'cancel-run':
+                if (!this.authed) {
+                    this.ch.send({ t: 'cancel-run-result', id: m.id, runId: m.runId, ok: false, reason: 'unsupported' });
+                    return;
+                }
+                this.onCancelRun(m);
+                return;
             case 'acp-start':
                 if (!this.authed) {
                     this.ch.send({ t: 'acp-error', id: m.id, error: 'not authenticated' });
@@ -397,7 +584,9 @@ export class SidecarServer {
                 // answer is dropped silently rather than forwarded into the registry.
                 if (!this.authed)
                     return;
-                this.opts.attendance?.answer(m.id, m.decision, this.attended);
+                // The note is the client's text: cleaned HERE, at the daemon's edge,
+                // and only a deny carries one.
+                this.opts.attendance?.answer(m.id, m.decision, this.attended, m.decision === 'deny' ? denialNote(m.note) : undefined);
                 return;
             case 'roots-browse':
                 // Auth-gated like every other request: directory enumeration must never
@@ -542,6 +731,76 @@ export class SidecarServer {
                 }
                 void this.onAgentPauseSet(m);
                 return;
+            case 'crew-deployments':
+            case 'crew-deploy':
+            case 'crew-undeploy':
+            case 'crew-pause':
+            case 'crew-resume':
+            case 'crew-stop':
+                if (!this.authed) {
+                    this.ch.send({ t: 'crew-deploy-result', id: m.id, reply: { ok: false, error: 'not authenticated' } });
+                    return;
+                }
+                void this.onCrewDeploy(m);
+                return;
+            case 'approvals-accept':
+                if (!this.authed) {
+                    this.ch.send({ t: 'approvals-accept-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onApprovalsAccept(m);
+                return;
+            case 'approvals-list':
+                if (!this.authed) {
+                    this.ch.send({ t: 'approvals-list-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onApprovalsList(m);
+                return;
+            case 'approvals-revoke':
+                if (!this.authed) {
+                    this.ch.send({ t: 'approvals-revoke-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onApprovalsRevoke(m);
+                return;
+            case 'checks-get':
+                if (!this.authed) {
+                    this.ch.send({ t: 'checks-get-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onChecksGet(m);
+                return;
+            case 'checks-pin':
+                if (!this.authed) {
+                    this.ch.send({ t: 'checks-pin-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onChecksPin(m);
+                return;
+            case 'workspace-release':
+                if (!this.authed) {
+                    this.ch.send({ t: 'workspace-release-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onWorkspaceRelease(m);
+                return;
+            case 'run-plan-get':
+                // Authorized exactly like `subscribe` (watching a run): authenticated,
+                // any run id. The answer is narrower than the event stream a watcher
+                // already receives.
+                if (!this.authed) {
+                    this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onRunPlanGet(m);
+                return;
+            case 'push-subscribe':
+                void this.onPushSubscribe(m);
+                return;
+            case 'push-unsubscribe':
+                void this.onPushUnsubscribe(m);
+                return;
             case 'hosts-list':
                 // `ok: false`, not an empty estate: telling an unauthenticated caller
                 // "this daemon holds no synced hosts" is a claim it has not earned --
@@ -667,19 +926,30 @@ export class SidecarServer {
                 return;
         }
     }
-    onHello(m) {
+    /** Close a connection that keeps failing to pair. */
+    countFailedHello() {
+        this.failedHellos++;
+        if (this.failedHellos >= MAX_FAILED_HELLOS) {
+            this.opts.log?.(`closing a connection after ${this.failedHellos} denied hellos`);
+            this.ch.close();
+        }
+    }
+    async onHello(m) {
         if (m.protocol !== SIDECAR_PROTOCOL) {
             this.opts.log?.(`denied: unsupported protocol ${m.protocol}`);
             this.ch.send({ t: 'denied', reason: `protocol ${m.protocol} unsupported` });
+            this.countFailedHello();
             return;
         }
         if (!safeEqual(m.token ?? '', this.opts.token)) {
             this.opts.log?.('denied: invalid token');
             this.ch.send({ t: 'denied', reason: 'invalid token' });
+            this.countFailedHello();
             return;
         }
         this.authed = true;
-        this.hostStateDir = m.stateDir ?? '.corenel';
+        this.clearHelloDeadline();
+        this.hostStateDir = m.stateDir ?? DEFAULT_STATE_DIR;
         // Runtime-validate identity, even though the declared type is `string` --
         // the message crossed the wire via `JSON.parse(...) as SidecarMsg`, so
         // nothing actually guaranteed that. A non-string `clientId` (e.g. a number
@@ -745,6 +1015,7 @@ export class SidecarServer {
                 }
             }
             this.clientId = clientId;
+            this.accounts = accounts;
             // The FRIENDLY label, which falls back to the WIRE id and never to the
             // mapped key: the name is what seeds a directory name and what an
             // operator reads in `hosts list`, and an `acct:<digest>` there would name
@@ -773,12 +1044,91 @@ export class SidecarServer {
                 this.opts.log?.(`onClient hook threw: ${errMessage(err)}`);
             }
         }
+        /* THE WAITS, started together. The welcome carries the synced directory
+         * name this daemon resolved for this connection, and the client has no
+         * other way to learn it -- it could previously only deduce it, and got null
+         * whenever no workspace was open or two hosts held the same workspace id,
+         * leaving a management surface unable to say which registrations were its
+         * own.
+         *
+         * The dirName lookup is STARTED here, before the identity verdict is
+         * awaited, so the two bounded waits (DIR_NAME_TIMEOUT_MS,
+         * IDENTITY_TIMEOUT_MS) overlap: the worst case stays one bound, not two.
+         * Both only ever resolve (every failure is null / unverified), so starting
+         * one and then awaiting the other cannot leave a rejection unhandled.
+         *
+         * Bounded, and every dirName failure ends the same way as an older daemon:
+         * no `dirName` on the welcome. A handshake that never arrives would be a
+         * far worse trade than a client that falls back to deducing. With neither
+         * a resolver nor a verifier nothing is awaited at all, and the welcome
+         * goes out in the same tick as today. */
+        const dirIdentity = this.clientId === undefined
+            ? undefined
+            : { clientId: this.clientId, name: this.clientName ?? this.clientId };
+        const dirNamePending = this.opts.clientDirName && dirIdentity
+            ? this.resolveDirName(this.opts.clientDirName, dirIdentity)
+            : undefined;
+        /* IDENTITY, decided BEFORE attendance or push can see this connection.
+         * Reached only past the pairing-token check above -- the challenge is
+         * never sent for a bad pairing token. Whatever the verdict, the
+         * connection pairs: unverified only withholds the widened trust a verified
+         * id earns. `verifiedUserId` is assigned here and nowhere else, once. The
+         * assertion is never logged; only the reason is. The Clerk token itself
+         * never reaches this class -- this exchange only ever sees a corenel-api
+         * pairing assertion (spec amendment 2026-09-25b). */
+        if (this.opts.identity) {
+            if (!m.wantsIdentity) {
+                this.identityResult = { verified: false, reason: 'not requested' };
+            }
+            else if (!this.opts.info?.id) {
+                this.identityResult = { verified: false, reason: 'no daemon id' };
+            }
+            else {
+                const sidecarId = this.opts.info.id;
+                /* The hash of the pairing token THIS connection presented (it passed
+                 * the check above). The assertion's `cnf.tkh` must equal it: that
+                 * binds the assertion to the pairing the browser actually made, so a
+                 * daemon that holds our token cannot relay our challenge through a
+                 * browser paired with IT (that browser hashed its own, different,
+                 * token). STARTED here but not awaited: the digest is async, and the
+                 * challenge, the resolver and the bound timer must all be in place
+                 * synchronously -- it is awaited only once an assertion is in hand
+                 * (see verdictFromAssertion), inside the same bound. A digest that
+                 * rejects pairs unverified ('error'), never refused. */
+                const tokenHash = pairingTokenHash(m.token ?? '').catch(() => null);
+                const nonce = makeNonce();
+                this.ch.send({ t: 'identity-challenge', nonce, sidecarId });
+                const verdict = await this.awaitAndVerifyIdentity(sidecarId, nonce, tokenHash);
+                if (verdict.ok)
+                    this.verifiedUserId = verdict.identity.userId;
+                this.identityResult = verdict.ok ? { verified: true } : { verified: false, reason: verdict.reason };
+            }
+            this.opts.log?.(`identity: ${this.identityResult.verified ? 'verified' : `unverified (${this.identityResult.reason})`}`);
+        }
+        /* OLDER APPS (crew deploy). A client that does not announce it can deploy
+         * has agents that sync here but never fire until deployed, and nothing on
+         * its screen can say so -- the daemon says it, once per client (the port
+         * de-duplicates). The list is only ever informational: it grants nothing.
+         * A malformed one counts as absent. Best-effort: never breaks a handshake. */
+        if (this.opts.crewDeploy && !announcedCapabilities(m.capabilities).includes(CREW_DEPLOY_FEATURE)) {
+            try {
+                this.opts.crewDeploy.noteOlderClient(this.clientId ?? '', this.clientName ?? 'unknown app');
+            }
+            catch (err) {
+                this.opts.log?.(`noteOlderClient threw: ${errMessage(err)}`);
+            }
+        }
+        // Dropped while verifying: attaching now would leave a dead client in the
+        // registry that the (already-run) close handler can never detach.
+        if (this.closed)
+            return;
         if (this.opts.attendance) {
             const attended = {
                 send: (ask) => this.ch.send({ t: 'permission-ask', ...ask }),
                 resolved: (id, decision, by, byClientId) => this.ch.send({ t: 'permission-resolved', id, decision, by, ...(byClientId ? { byClientId } : {}) }),
                 runActivity: (activity) => this.ch.send({ t: 'run-activity', activity }),
                 registrations: (registrations) => this.ch.send({ t: 'registrations', registrations }),
+                approvalSuggestion: (s) => this.ch.send({ t: 'approvals-suggest', ...s }),
             };
             // Retained so `permission-answer` can name THIS connection as the
             // answerer -- the registry identifies an answerer by the object it
@@ -788,39 +1138,125 @@ export class SidecarServer {
              * the key this connection was FILED under (mapped through `clientKey`
              * where the daemon supplies one), i.e. the same value its RunIdentity
              * carries -- which is what makes a run's owner and its ask's recipient
-             * the same connection. `accounts` are CLAIMED and only ever widen a
-             * delivery; see the registry's `recipients`. */
+             * the same connection. `accounts` are CLAIMED, carried for display, and
+             * widen nothing; only `verifiedUserId` (proven at pairing) widens a
+             * delivery to the same user's other devices. See the registry's
+             * `recipients`. */
             this.attendedDetach = this.opts.attendance.attach(attended, {
                 clientId: this.clientId ?? '',
                 accounts,
+                ...(this.verifiedUserId ? { verifiedUserId: this.verifiedUserId } : {}),
             });
         }
         this.opts.log?.(`paired — ${this.tools.size} ${this.tools.size === 1 ? 'tool' : 'tools'} advertised (host dir: ${this.hostStateDir})`);
-        /* THE ONE THING THAT WAITS. The welcome carries the synced directory name
-         * this daemon resolved for this connection, and the client has no other way
-         * to learn it -- it could previously only deduce it, and got null whenever
-         * no workspace was open or two hosts held the same workspace id, leaving a
-         * management surface unable to say which registrations were its own.
-         *
-         * Bounded, and every failure ends the same way as an older daemon: no
-         * `dirName` on the welcome. A handshake that never arrives would be a far
-         * worse trade than a client that falls back to deducing. */
-        const identity = this.clientId === undefined
-            ? undefined
-            : { clientId: this.clientId, name: this.clientName ?? this.clientId };
-        if (this.opts.clientDirName && identity) {
-            void this.resolveDirName(this.opts.clientDirName, identity).then((dirName) => {
-                this.sendWelcome(dirName);
-            });
+        if (!dirNamePending) {
+            this.sendWelcome(null);
+            return;
+        }
+        const dirName = await dirNamePending;
+        // Same reasoning as above: a dropped connection must not attach to the
+        // hosts live set, which only a close handler that already ran would undo.
+        if (this.closed)
             return;
+        /* CREW DEPLOY OWNERSHIP: a verified connection filed as a synced folder
+         * binds that folder to its user (first one wins; the daemon never
+         * rebinds). Before the welcome, so nothing this client sends can race it.
+         * Best-effort: never breaks a handshake. */
+        if (dirName && this.verifiedUserId && this.opts.crewDeploy?.noteVerifiedDir) {
+            try {
+                this.opts.crewDeploy.noteVerifiedDir(dirName, this.verifiedUserId);
+            }
+            catch (err) {
+                this.opts.log?.(`noteVerifiedDir threw: ${errMessage(err)}`);
+            }
+        }
+        this.sendWelcome(dirName);
+    }
+    /** Waits for this connection's `identity-assert`, with NO timeout of its
+     * own -- the overall bound is `awaitAndVerifyIdentity`'s, covering this wait
+     * AND the verify call together, so the whole leg is bounded at
+     * IDENTITY_TIMEOUT_MS from the challenge, not up to double that. Also
+     * settled (to a timeout-shaped answer) from the close handler, so a
+     * dropped connection cannot leave this pending forever. */
+    awaitIdentityAssertion() {
+        return new Promise((resolve) => {
+            this.identityAssertResolve = resolve;
+        });
+    }
+    /** Turns an `identity-assert` answer into a verdict: 'no assertion' or
+     * 'timed out' unverified for the non-assertion answers, 'assertion too
+     * long' WITHOUT calling the verifier for an oversized one, and otherwise
+     * the verifier's own verdict (never thrown -- a throw or rejection becomes
+     * an unverified 'error'). The expectation is built here, once the
+     * pairing-token hash has settled; a hash that could not be computed is an
+     * unverified 'error' without calling the verifier. */
+    async verdictFromAssertion(answer, audience, nonce, tokenHashPending) {
+        if (answer.kind === 'none')
+            return { ok: false, reason: 'no assertion' };
+        if (answer.kind === 'timeout')
+            return { ok: false, reason: 'timed out' };
+        const assertion = answer.value;
+        if (assertion.length > MAX_ASSERTION_LEN)
+            return { ok: false, reason: 'assertion too long' };
+        const v = this.opts.identity;
+        if (!v)
+            return { ok: false, reason: 'no verifier' };
+        const tokenHash = await tokenHashPending;
+        if (tokenHash === null)
+            return { ok: false, reason: 'error' };
+        const expect = { audience, nonce, tokenHash };
+        try {
+            const verdict = v.explain
+                ? await v.explain(assertion, expect)
+                : await v.verify(assertion, expect).then((id) => (id ? { ok: true, identity: id } : { ok: false, reason: 'rejected' }));
+            return normalizeVerdict(verdict);
+        }
+        catch (err) {
+            this.opts.log?.(`identity verification failed: error (${sanitizeReason(errMessage(err))})`);
+            return { ok: false, reason: 'error' };
+        }
+    }
+    /** The identity verdict for this connection's challenge/assert exchange,
+     * bounded by IDENTITY_TIMEOUT_MS FROM THE CHALLENGE -- covering both the
+     * wait for `identity-assert` and the verify call, in one race, so a slow
+     * verifier cannot add a second timeout's worth of wait on top of a slow
+     * browser. Every failure mode (no assertion, an oversized one, a throw, a
+     * rejection, a malformed answer, a timeout) is an UNVERIFIED verdict with a
+     * reason -- never a refusal. The assertion is passed to the verifier and
+     * nowhere else. */
+    async awaitAndVerifyIdentity(audience, nonce, tokenHash) {
+        let timer;
+        try {
+            const timed = new Promise((res) => {
+                timer = setTimeout(() => res({ ok: false, reason: 'timed out' }), IDENTITY_TIMEOUT_MS);
+            });
+            const answered = this.awaitIdentityAssertion().then((answer) => this.verdictFromAssertion(answer, audience, nonce, tokenHash));
+            const got = await Promise.race([answered, timed]);
+            return normalizeVerdict(got);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            /* Whichever side of the race won, nothing may still be waiting on
+             * `identity-assert` once this settles. If `answered` won, the message
+             * handler already cleared this itself. If `timed` won (the timeout),
+             * NOTHING has cleared it yet -- `awaitIdentityAssertion`'s promise is
+             * still pending, just no longer awaited by anyone. Leaving the
+             * resolver live would let a LATE `identity-assert` (arriving after the
+             * bound this method already returned past) still call it, running
+             * `verdictFromAssertion` -- and therefore the verifier, and possibly a
+             * JWKS fetch -- for a result nothing reads, while the message handler's
+             * own comment claims a late message is ignored. Clearing here is what
+             * makes that claim true. */
+            this.identityAssertResolve = undefined;
         }
-        this.sendWelcome(null);
     }
     /** Resolve the connection's synced directory name, or null for every failure
      * mode there is (throw, rejection, non-string, timeout). */
     async resolveDirName(resolve, identity) {
+        let timer;
         try {
-            const timed = new Promise((res) => setTimeout(() => res(null), DIR_NAME_TIMEOUT_MS));
+            const timed = new Promise((res) => { timer = setTimeout(() => res(null), DIR_NAME_TIMEOUT_MS); });
             const got = await Promise.race([Promise.resolve(resolve(identity)), timed]);
             return typeof got === 'string' && got ? got : null;
         }
@@ -828,6 +1264,10 @@ export class SidecarServer {
             this.opts.log?.(`clientDirName failed: ${errMessage(err)}`);
             return null;
         }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
     }
     /** Whether the identity rule can produce an account key right now. A
      * predicate that throws answers NO: an advertisement is a promise to the
@@ -874,6 +1314,13 @@ export class SidecarServer {
             // default, whose scheduled runs would otherwise fail one by one with
             // nothing on screen to say why.
             ...(this.opts.runner?.hasDefaultModel ? ['default-model'] : []),
+            // A client offers Stop on a watched daemon run only where it would work.
+            ...(this.opts.runner?.cancel ? ['run-cancel'] : []),
+            // A client starts a task only where the daemon will honour it: an older
+            // runner ignores `task`, and a dropped task must never look like a start.
+            ...(this.opts.runner?.supportsTasks ? [RUN_TASK_FEATURE] : []),
+            // Whether this daemon answers run-plan-get (a runner that reads run records).
+            ...(this.opts.runner?.runPlan ? [RUN_PLAN_FEATURE] : []),
             ...(this.opts.acp ? ['acp'] : []),
             ...(this.opts.roots?.areas.length ? ['add-roots'] : []),
             ...(this.opts.roots?.areas.length && this.opts.roots.create ? ['create-roots'] : []),
@@ -894,7 +1341,22 @@ export class SidecarServer {
             // behind it, so a client offers "Pause" only where pausing would actually
             // stop the agent -- the alternative is a button that reports success on a
             // daemon that keeps firing.
-            ...(this.opts.pauses ? ['agent-pause'] : []),
+            // A deploy list holds pauses too (it answers the agent-pause-* messages
+            // through the deploy core), so it earns the flag on its own.
+            ...(this.opts.pauses || this.opts.crewDeploy ? ['agent-pause'] : []),
+            // Whether this daemon keeps a deploy list (crew deploy per machine).
+            // Only with a real port behind it, so a client offers Deploy and
+            // Undeploy only where the daemon would record them -- anywhere else a
+            // client shows the old read-only view.
+            ...(this.opts.crewDeploy ? [CREW_DEPLOY_FEATURE] : []),
+            // Whether this daemon keeps standing approvals (plan 3). Only with a real
+            // service behind it, so a client shows the "This machine" group only
+            // where there is something to list and revoke.
+            ...(this.opts.approvals ? ['approvals'] : []),
+            // Whether this daemon runs confirmed checks and holds the orchestrator's
+            // workspace lock. Only with a real service behind it (--allow-shell) that
+            // is not switched off right now (see SidecarChecks.unavailable).
+            ...(this.checksRefusal() === null ? ['checks'] : []),
             // Whether this daemon can report and reclaim its synced host directories.
             // Advertised only with a real manifest behind it, so a client never
             // offers a destructive control to a daemon that would refuse it.
@@ -917,11 +1379,20 @@ export class SidecarServer {
             // why it must be true at the moment it is said, not merely true of how
             // the daemon was built. See `clientKeyActive`.
             ...(this.opts.clientKey && this.clientKeyIsActive() ? ['account-identity'] : []),
+            // Whether this daemon can send web push. Advertised only with a real
+            // notifier behind it, so a client offers "notify me" only where a
+            // subscription would actually be reached.
+            ...(this.opts.push ? ['web-push'] : []),
+            // Whether this daemon verifies the browser's identity token. Advertised
+            // only with a real verifier behind it; the verdict itself is `identity`.
+            ...(this.opts.identity ? ['verified-identity'] : []),
         ];
         this.ch.send({
             t: 'welcome', tools, features,
             ...(this.opts.info ? { info: this.opts.info } : {}),
             ...(dirName ? { dirName } : {}),
+            ...(this.opts.push ? { vapidPublicKey: this.opts.push.publicKey } : {}),
+            ...(this.opts.identity ? { identity: this.identityResult } : {}),
         });
     }
     /** Proxy a host HTTP request server-side. Restricted to LOOPBACK targets — the
@@ -940,7 +1411,20 @@ export class SidecarServer {
                 throw new Error('http(s) URLs only');
             if (!isLoopbackHost(u.hostname))
                 throw new Error(`the sidecar proxy only reaches loopback hosts, not "${u.hostname}"`);
-            const res = await fetch(m.url, { method: m.method, headers: m.headers, body: m.body });
+            // A NAME (only `localhost` passes the check above) is resolved and every
+            // address re-checked, so a hosts-file or resolver entry cannot point it
+            // off the machine. IP literals need no lookup.
+            const bare = u.hostname.replace(/^\[/, '').replace(/\]$/, '');
+            if (!isLoopbackAddress(bare) && this.opts.resolveHost) {
+                const addrs = await this.opts.resolveHost(bare);
+                if (addrs.length === 0 || addrs.some((a) => !isLoopbackAddress(a))) {
+                    throw new Error(`"${u.hostname}" resolves to a non-loopback address; the sidecar proxy only reaches loopback hosts`);
+                }
+            }
+            // redirect:'manual' -- a loopback service with an open redirect must not
+            // bounce this request to a metadata or LAN host. The 3xx (with its
+            // Location) goes back to the caller, which can decide what to do.
+            const res = await fetch(m.url, { method: m.method, headers: m.headers, body: m.body, redirect: 'manual' });
             const headers = {};
             res.headers.forEach((v, k) => { headers[k] = v; });
             this.ch.send({ t: 'http-res', id: m.id, status: res.status, statusText: res.statusText, headers });
@@ -983,7 +1467,11 @@ export class SidecarServer {
                              * which URLs are refused all live on the daemon side, where the
                              * operator's declarations are. */
                             ...(m.repo ? { repo: m.repo } : {}),
-                            ...(m.owner ? { owner: m.owner } : {}),
+                            // From the AUTHENTICATED connection, never from this message: a
+                            // client naming an owner could label a session as someone
+                            // else's. `m.owner` is ignored; a connection that sent no
+                            // clientId files the session under nobody.
+                            ...(this.clientId ? { owner: this.clientId } : {}),
                             ...(m.fromSnapshot ? { fromSnapshot: m.fromSnapshot } : {}),
                             // From the HANDSHAKE, never from this message: the dot-dir is a
                             // property of the client's workspace, and taking it from the
@@ -1212,7 +1700,12 @@ export class SidecarServer {
             this.ch.send({ t: 'invoke-result', id: m.id, ok: true, result });
         }
         catch (e) {
-            this.opts.log?.(`invoke ${m.name} failed: ${errMessage(e)}`);
+            // A read that finds nothing there (ENOENT) answered the question -- the
+            // crew page probes every project for a crew folder most do not have.
+            // Every other failure, and any from a tool that changes things, is logged.
+            const notThere = tool.mutates !== true && e?.code === 'ENOENT';
+            if (!notThere)
+                this.opts.log?.(`invoke ${m.name} failed: ${errMessage(e)}`);
             this.ch.send({ t: 'invoke-result', id: m.id, ok: false, error: errMessage(e) });
         }
     }
@@ -1243,6 +1736,10 @@ export class SidecarServer {
                  * user has -- the client does -- and the ACP client drops them if the
                  * agent never advertised mcpCapabilities.http. */
                 ...(m.mcpServers?.length ? { mcpServers: m.mcpServers } : {}),
+                /* The connection's own filed key -- the same value it attached to the
+                 * registry under -- so the proxied agent's asks reach whoever started
+                 * it under `--mode team`, and not their teammates. Never from `m`. */
+                ...(this.clientId ? { owner: this.clientId } : {}),
             });
             this.ch.send({ t: 'acp-started', id: m.id, ...started });
         }
@@ -1333,6 +1830,19 @@ export class SidecarServer {
             detachOnce();
         }
     }
+    /** Stop a run, whoever started it. Same trust as `run`: a connection that may
+     * start runs on this daemon may stop them. */
+    onCancelRun(m) {
+        const cancel = this.opts.runner?.cancel;
+        if (!cancel) {
+            this.ch.send({ t: 'cancel-run-result', id: m.id, runId: m.runId, ok: false, reason: 'unsupported' });
+            return;
+        }
+        const out = cancel.call(this.opts.runner, m.runId);
+        this.ch.send(out === 'cancelled'
+            ? { t: 'cancel-run-result', id: m.id, runId: m.runId, ok: true }
+            : { t: 'cancel-run-result', id: m.id, runId: m.runId, ok: false, reason: 'no-such-run' });
+    }
     /**
      * What this caller's agent has actually done.
      *
@@ -1395,6 +1905,14 @@ export class SidecarServer {
          * says so rather than running the work in its own process anyway — silently
          * downgrading is the failure IsolationLevel exists to prevent, and it would
          * be invisible to the client that asked. */
+        // A task is its own run with its own record and autonomy ceiling; the
+        // session layer knows neither, so it is refused rather than dropped. So is
+        // an autonomy on its own: the session path would ignore it, and a ceiling
+        // the client asked for must never be silently dropped.
+        if ((m.task || m.autonomy) && m.sessionId !== undefined) {
+            this.ch.send({ t: 'run-error', id: m.id, error: 'A task starts its own run; it cannot run inside an existing session.' });
+            return;
+        }
         if (m.sessionId !== undefined) {
             const sessions = this.opts.sessions;
             if (!sessions?.run) {
@@ -1417,7 +1935,10 @@ export class SidecarServer {
             // would grant itself mutating tools inside a sandbox. Deliberately
             // absent -- see session/guestRunner.ts.
             this.opts.sessions.run(m.sessionId, agent, input, onEvent, identity, { keepTranscript: m.keepTranscript === true })
-            : (agent, input, onEvent, identity) => this.opts.runner.run(agent, input, onEvent, identity);
+            : (agent, input, onEvent, identity) => 
+            // Task and autonomy are forwarded as asked; the runner, not this
+            // class, decides whether the agent may run that way.
+            this.opts.runner.run(agent, input, onEvent, identity, undefined, undefined, { task: m.task, autonomy: m.autonomy });
         let runId;
         const pending = [];
         const onEvent = (event) => {
@@ -1573,6 +2094,17 @@ export class SidecarServer {
         }
     }
     onAgentPauseList(m) {
+        const deploy = this.opts.crewDeploy;
+        if (deploy) {
+            // A pause is a deploy entry now: the list comes from the deploy list.
+            try {
+                this.ch.send({ t: 'agent-pause-list-result', id: m.id, ok: true, pauses: deploy.legacyPauses() });
+            }
+            catch (err) {
+                this.ch.send({ t: 'agent-pause-list-result', id: m.id, ok: false, error: errMessage(err) });
+            }
+            return;
+        }
         if (!this.opts.pauses) {
             // An honest empty answer for a daemon without the capability: it is
             // holding no pauses, which is true. The feature gate is what tells a
@@ -1588,7 +2120,7 @@ export class SidecarServer {
         }
     }
     async onAgentPauseSet(m) {
-        if (!this.opts.pauses) {
+        if (!this.opts.pauses && !this.opts.crewDeploy) {
             // NOT an empty success. Accepting a pause this daemon cannot hold would
             // leave the operator believing an agent had been stopped while it kept
             // firing on the hour -- the exact failure the feature exists to end.
@@ -1602,6 +2134,23 @@ export class SidecarServer {
             this.ch.send({ t: 'agent-pause-set-result', id: m.id, ok: false, error: 'owner must be a string and agent a non-empty string' });
             return;
         }
+        const deploy = this.opts.crewDeploy;
+        if (deploy) {
+            // An older app's pause goes through the deploy core, recorded as THIS
+            // connection (the core adds who and why; an older app gives no reason).
+            try {
+                const out = await deploy.pauseByOwnerKey(this.deployCaller(), m.owner, m.agent, m.paused === true);
+                this.ch.send(out.ok
+                    ? { t: 'agent-pause-set-result', id: m.id, ok: true, pauses: out.pauses }
+                    : { t: 'agent-pause-set-result', id: m.id, ok: false, error: out.error });
+            }
+            catch (err) {
+                this.ch.send({ t: 'agent-pause-set-result', id: m.id, ok: false, error: errMessage(err) });
+            }
+            return;
+        }
+        if (!this.opts.pauses)
+            return;
         try {
             const pauses = await this.opts.pauses.set(m.owner, m.agent, m.paused === true);
             // Republish before replying: the caller's own row and every other
@@ -1614,6 +2163,259 @@ export class SidecarServer {
             this.ch.send({ t: 'agent-pause-set-result', id: m.id, ok: false, error: errMessage(err) });
         }
     }
+    /** The caller for a deploy action: THIS connection, never a message field.
+     * `dirName` is the directory the daemon resolved for this connection and
+     * `verifiedUserId` the id it proved at pairing; both are absent until (and
+     * unless) the daemon established them, which only ever narrows what the
+     * core permits. */
+    deployCaller() {
+        return {
+            kind: 'client',
+            name: this.clientName ?? this.clientId ?? 'unknown app',
+            ...(this.dirName !== undefined ? { dirName: this.dirName } : {}),
+            ...(this.verifiedUserId !== undefined ? { verifiedUserId: this.verifiedUserId } : {}),
+        };
+    }
+    async onCrewDeploy(m) {
+        const port = this.opts.crewDeploy;
+        const answer = (reply) => this.ch.send({ t: 'crew-deploy-result', id: m.id, reply });
+        if (!port) {
+            answer({ ok: false, error: 'this daemon does not keep a deploy list' });
+            return;
+        }
+        // Runtime-typed: the message arrived via JSON.parse(...) as SidecarMsg.
+        // The ref goes on as `unknown` (the core validates it); a reason or run id
+        // that is not a string is dropped, never coerced.
+        const str = (v) => (typeof v === 'string' ? v : undefined);
+        try {
+            switch (m.t) {
+                case 'crew-deployments':
+                    answer(await port.deployments());
+                    return;
+                case 'crew-deploy':
+                    answer(await port.deploy(this.deployCaller(), m.ref, str(m.reason)));
+                    return;
+                case 'crew-undeploy':
+                    answer(await port.undeploy(this.deployCaller(), m.ref, str(m.reason)));
+                    return;
+                case 'crew-pause':
+                    answer(await port.pause(this.deployCaller(), m.ref, str(m.reason) ?? ''));
+                    return;
+                case 'crew-resume':
+                    answer(await port.resume(this.deployCaller(), m.ref, str(m.reason)));
+                    return;
+                case 'crew-stop':
+                    answer(await port.stop(this.deployCaller(), m.ref, str(m.runId) ?? '', str(m.reason) ?? ''));
+                    return;
+            }
+        }
+        catch (err) {
+            answer({ ok: false, error: errMessage(err) });
+        }
+    }
+    async onApprovalsAccept(m) {
+        const port = this.opts.approvals;
+        if (!port) {
+            this.ch.send({ t: 'approvals-accept-result', id: m.id, ok: false, error: 'this daemon does not keep standing approvals' });
+            return;
+        }
+        // Runtime-validated: the message arrived via JSON.parse(...) as SidecarMsg.
+        if (typeof m.suggestionId !== 'string' || !m.suggestionId || (m.choice !== 'global' && m.choice !== 'not-now' && m.choice !== 'never')) {
+            this.ch.send({ t: 'approvals-accept-result', id: m.id, ok: false, error: 'suggestionId must be a non-empty string and choice one of global, not-now, never' });
+            return;
+        }
+        // A connection that never attached to attendance was never offered
+        // anything, and has no identity to accept with.
+        if (this.attended === undefined) {
+            this.ch.send({ t: 'approvals-accept-result', id: m.id, ok: false, error: 'this connection was not offered that suggestion' });
+            return;
+        }
+        try {
+            // `this.attended` -- the object THIS connection attached -- is the only
+            // accepter identity; the daemon compares it with the client it offered
+            // to. Nothing in the message can name another connection.
+            await port.accept(this.attended, m.suggestionId, m.choice);
+            this.ch.send({ t: 'approvals-accept-result', id: m.id, ok: true });
+        }
+        catch (err) {
+            this.ch.send({ t: 'approvals-accept-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    async onApprovalsList(m) {
+        const port = this.opts.approvals;
+        if (!port) {
+            this.ch.send({ t: 'approvals-list-result', id: m.id, ok: false, error: 'this daemon does not keep standing approvals' });
+            return;
+        }
+        try {
+            this.ch.send({ t: 'approvals-list-result', id: m.id, ok: true, state: await port.state() });
+        }
+        catch (err) {
+            this.ch.send({ t: 'approvals-list-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    async onApprovalsRevoke(m) {
+        const port = this.opts.approvals;
+        if (!port) {
+            this.ch.send({ t: 'approvals-revoke-result', id: m.id, ok: false, error: 'this daemon does not keep standing approvals' });
+            return;
+        }
+        if (typeof m.tool !== 'string' || !m.tool) {
+            this.ch.send({ t: 'approvals-revoke-result', id: m.id, ok: false, error: 'tool must be a non-empty string' });
+            return;
+        }
+        try {
+            this.ch.send({ t: 'approvals-revoke-result', id: m.id, ok: true, state: await port.revoke(m.tool) });
+        }
+        catch (err) {
+            this.ch.send({ t: 'approvals-revoke-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    /** Why the checks port cannot answer right now, or null when it can. */
+    checksRefusal() {
+        if (!this.opts.checks)
+            return NO_CHECKS;
+        try {
+            return this.opts.checks.unavailable?.() ?? null;
+        }
+        catch (err) {
+            // A guard that cannot answer is a guard that says no.
+            return errMessage(err);
+        }
+    }
+    async onChecksGet(m) {
+        const refusal = this.checksRefusal();
+        if (refusal !== null || !this.opts.checks) {
+            this.ch.send({ t: 'checks-get-result', id: m.id, ok: false, error: refusal ?? NO_CHECKS });
+            return;
+        }
+        // Runtime-validate: the message arrived via `JSON.parse(...) as SidecarMsg`.
+        if (typeof m.root !== 'string' || typeof m.stateDir !== 'string') {
+            this.ch.send({ t: 'checks-get-result', id: m.id, ok: false, error: 'root and stateDir must be strings' });
+            return;
+        }
+        try {
+            this.ch.send({ t: 'checks-get-result', id: m.id, ok: true, state: await this.opts.checks.get(m.root, m.stateDir) });
+        }
+        catch (err) {
+            this.ch.send({ t: 'checks-get-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    async onChecksPin(m) {
+        const refusal = this.checksRefusal();
+        if (refusal !== null || !this.opts.checks) {
+            this.ch.send({ t: 'checks-pin-result', id: m.id, ok: false, error: refusal ?? NO_CHECKS });
+            return;
+        }
+        if (typeof m.root !== 'string' || typeof m.stateDir !== 'string' || typeof m.content !== 'string') {
+            this.ch.send({ t: 'checks-pin-result', id: m.id, ok: false, error: 'root, stateDir and content must be strings' });
+            return;
+        }
+        try {
+            this.ch.send({ t: 'checks-pin-result', id: m.id, ok: true, state: await this.opts.checks.pin(m.root, m.stateDir, m.content) });
+        }
+        catch (err) {
+            this.ch.send({ t: 'checks-pin-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    async onWorkspaceRelease(m) {
+        // Deliberately NOT gated on checksRefusal(): releasing only removes a run's
+        // own lock, and a run that started before the port switched off must still
+        // hand its lock back.
+        if (!this.opts.checks) {
+            this.ch.send({ t: 'workspace-release-result', id: m.id, ok: false, error: NO_CHECKS });
+            return;
+        }
+        if (typeof m.root !== 'string' || typeof m.stateDir !== 'string' || typeof m.runId !== 'string') {
+            this.ch.send({ t: 'workspace-release-result', id: m.id, ok: false, error: 'root, stateDir and runId must be strings' });
+            return;
+        }
+        try {
+            const released = await this.opts.checks.release({ root: m.root, stateDir: m.stateDir, runId: m.runId });
+            this.ch.send({ t: 'workspace-release-result', id: m.id, ok: true, released });
+        }
+        catch (err) {
+            this.ch.send({ t: 'workspace-release-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    async onRunPlanGet(m) {
+        const runner = this.opts.runner;
+        if (!runner?.runPlan) {
+            this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: false, error: 'this daemon does not report run plans' });
+            return;
+        }
+        // Runtime-validate: the message arrived via `JSON.parse(...) as SidecarMsg`.
+        if (typeof m.runId !== 'string' || !m.runId) {
+            this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: false, error: 'runId must be a non-empty string' });
+            return;
+        }
+        try {
+            this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: true, plan: await runner.runPlan(m.runId) });
+        }
+        catch (err) {
+            this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    /** The identity a push subscription/unsubscription is filed under -- ALWAYS
+     * this connection's own authenticated `clientId`/`accounts`, never anything
+     * the message itself carries. Auth-gated first, same as every other
+     * handler; a connection with no `clientId` (an older client, or one that
+     * never claimed an identity) is refused rather than filed under nothing. */
+    pushIdentity() {
+        if (!this.authed)
+            return { error: 'not authenticated' };
+        if (!this.clientId)
+            return { error: 'this connection carries no client identity, so there is nobody to notify' };
+        return {
+            clientId: this.clientId,
+            accounts: this.accounts,
+            ...(this.verifiedUserId ? { verifiedUserId: this.verifiedUserId } : {}),
+        };
+    }
+    async onPushSubscribe(m) {
+        const who = this.pushIdentity();
+        if ('error' in who) {
+            this.ch.send({ t: 'push-result', id: m.id, ok: false, error: who.error });
+            return;
+        }
+        if (!this.opts.push) {
+            this.ch.send({ t: 'push-result', id: m.id, ok: false, error: 'this daemon does not send web push' });
+            return;
+        }
+        if (!isWebPushSubscription(m.subscription)) {
+            this.ch.send({ t: 'push-result', id: m.id, ok: false, error: 'malformed push subscription' });
+            return;
+        }
+        try {
+            await this.opts.push.subscribe(who, m.subscription);
+            this.ch.send({ t: 'push-result', id: m.id, ok: true });
+        }
+        catch (err) {
+            this.ch.send({ t: 'push-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    async onPushUnsubscribe(m) {
+        const who = this.pushIdentity();
+        if ('error' in who) {
+            this.ch.send({ t: 'push-result', id: m.id, ok: false, error: who.error });
+            return;
+        }
+        if (!this.opts.push) {
+            this.ch.send({ t: 'push-result', id: m.id, ok: false, error: 'this daemon does not send web push' });
+            return;
+        }
+        if (typeof m.endpoint !== 'string') {
+            this.ch.send({ t: 'push-result', id: m.id, ok: false, error: 'malformed endpoint' });
+            return;
+        }
+        try {
+            await this.opts.push.unsubscribe(who, m.endpoint);
+            this.ch.send({ t: 'push-result', id: m.id, ok: true });
+        }
+        catch (err) {
+            this.ch.send({ t: 'push-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
     async onRoomOpen(m) {
         if (!this.opts.rooms) {
             this.ch.send({ t: 'room-open-result', id: m.id, ok: false, problems: ['this sidecar does not host rooms'] });
@@ -1659,7 +2461,7 @@ export class SidecarServer {
          * unconditionally would make the opt-in flag not an opt-in -- see the
          * team-mode-off test in host.rooms.test.ts, which is the merge-safety
          * claim for this whole branch. */
-        if (this.opts.teamMode && this.clientId === undefined) {
+        if (this.opts.teamMode && this.roomIdentity() === undefined) {
             this.ch.send({
                 t: 'room-open-result',
                 id: m.id,
@@ -1668,7 +2470,7 @@ export class SidecarServer {
             });
             return;
         }
-        const clientId = this.clientId;
+        const clientId = this.roomIdentity();
         const owner = clientId === undefined
             ? undefined
             : m.req.participants.find((p) => p.kind === 'human' && p.role === 'owner');
@@ -1702,8 +2504,8 @@ export class SidecarServer {
              * returned, unnarrowed, for every existing room test and every daemon
              * nobody has reconfigured.
              *
-             * Team mode on: membership is judged against `this.clientId`, the
-             * connection's OWN proven identity, never a participant id read out of
+             * Team mode on: membership is judged against `roomIdentity()`, the
+             * connection's OWN proven identity (its verified user, else its clientId), never a participant id read out of
              * the request -- that is what `onRoomOpen` just finished making
              * trustworthy. A caller with NO clientId is not "an older client that
              * predates identity" here the way it is at `hello` -- membership
@@ -1713,9 +2515,9 @@ export class SidecarServer {
              * opt-out: connect without a clientId and see it all anyway. */
             const mine = !this.opts.teamMode
                 ? rooms
-                : this.clientId === undefined
+                : this.roomIdentity() === undefined
                     ? []
-                    : rooms.filter((r) => r.participants.some((p) => p.id === this.clientId));
+                    : rooms.filter((r) => r.participants.some((p) => p.id === this.roomIdentity()));
             this.ch.send({ t: 'room-list-result', id: m.id, ok: true, rooms: mine });
         }
         catch (err) {
@@ -1743,17 +2545,18 @@ export class SidecarServer {
              * `room: null`, which is the honest "no such room" answer and would be
              * a lie about a room that does in fact exist. */
             if (found && this.opts.teamMode) {
-                if (this.clientId === undefined) {
+                const me = this.roomIdentity();
+                if (me === undefined) {
                     this.ch.send({
                         t: 'room-read-result', id: m.id, ok: false,
                         error: 'This connection has no verified identity, so membership in this room cannot be proven.',
                     });
                     return;
                 }
-                if (!found.room.participants.some((p) => p.id === this.clientId)) {
+                if (!found.room.participants.some((p) => p.id === me)) {
                     this.ch.send({
                         t: 'room-read-result', id: m.id, ok: false,
-                        error: `"${this.clientId}" is not a member of room "${m.roomId}".`,
+                        error: `"${me}" is not a member of room "${m.roomId}".`,
                     });
                     return;
                 }
@@ -1787,10 +2590,26 @@ export class SidecarServer {
             this.ch.send({ t: 'room-resume-result', id: m.id, ok: false, error: errMessage(err) });
         }
     }
+    /** WHO THIS CONNECTION IS, INSIDE A ROOM.
+     *
+     * The user its pairing JWT proved (`verifiedUserId`: API-signed, aud = this
+     * daemon, single-use nonce, allowlisted azp) whenever there is one -- the
+     * same user id the browser seats a person under, sanitized by the same rule
+     * (an OpenAI `name` field accepts only [A-Za-z0-9_-]; src/rooms/participantId.ts).
+     * Keying on `clientId` instead -- the browser's random wire id -- refused
+     * people their own rooms: the room seated `user_...`, the check compared
+     * `1463897a-...`.
+     *
+     * No verified user (no verifier configured, an older client, a JWT that did
+     * not verify): `clientId`, exactly as before. Never a claimed id. */
+    roomIdentity() {
+        const verified = this.verifiedUserId?.replace(/[^A-Za-z0-9_-]/g, '');
+        return verified || this.clientId;
+    }
     /* ONE identity rule for every room verb.
      *
-     * `room-read` judges membership on `this.clientId` -- the identity this
-     * connection PROVED at `hello`. The mutating verbs used to hand
+     * `room-read` judges membership on `roomIdentity()` -- the user this
+     * connection's pairing JWT proved, else the clientId it PROVED at `hello`. The mutating verbs used to hand
      * `m.participantId` straight off the wire to `requireRole`/`mayAct`, so one
      * branch enforced while another trusted the caller: a viewer could send the
      * owner's participantId and close the room. Under team mode every verb now
@@ -1810,10 +2629,11 @@ export class SidecarServer {
     actingId(claimed) {
         if (!this.opts.teamMode)
             return { ok: true, id: claimed };
-        if (this.clientId === undefined) {
+        const me = this.roomIdentity();
+        if (me === undefined) {
             return { ok: false, error: 'This connection has no verified identity (no clientId from hello), so it cannot act on a room.' };
         }
-        return { ok: true, id: this.clientId };
+        return { ok: true, id: me };
     }
     async onRoomAnswer(m) {
         if (!this.opts.rooms) {