@corenel/harness 0.1.0 → 0.3.2

package/dist/sidecar/server.js

@@ -1,4 +1,16 @@
 import { SIDECAR_PROTOCOL, errMessage, isLoopbackHost, } from '@corenel/protocol';
+/** 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
+ * is assignable to that per TS, so the actual runtime return must be checked). */
+function isThenable(v) {
+    return typeof v === 'object' && v !== null && typeof v.then === 'function';
+}
+/** Cap on `clientId`/`clientName` before they are forwarded to `onClient` (and,
+ * downstream, used as a manifest key / dirName seed) — the wire message is
+ * declared `string` but arrives via `JSON.parse(...) as SidecarMsg` with no
+ * runtime check, so an oversized field must never reach persistence unbounded. */
+const MAX_IDENTITY_FIELD_LEN = 200;
 /** 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) {
@@ -57,6 +69,74 @@ export class SidecarServer {
             writable: true,
             value: new Map()
         });
+        /** The connected host's dot-dir name, from `hello.stateDir` (informational —
+         * doesn't change any sidecar behavior yet; reserved for future workspace-state
+         * features that need to know the host's dir name). */
+        Object.defineProperty(this, "hostStateDir", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: '.corenel'
+        });
+        /** The authenticated connection's `clientId`, retained here (from `hello`) so
+         * later `host-sync-*` messages can be attributed to their owner without
+         * trusting anything the client sends per-call. Set only when the `hello`
+         * passed BOTH the token check AND the identity `typeof` gate below --
+         * `undefined` means either "not authenticated yet" or "authenticated, but this
+         * connection carries no identity to attribute files to" (an older client).
+         * Either way, host-sync must be rejected; see `requireHostSyncIdentity`. */
+        Object.defineProperty(this, "clientId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Detach function for this connection's attendance attachment, set on a
+         * successful `hello` when `opts.attendance` is wired. Called once, on channel
+         * close, so a dead connection stops receiving/counting toward asks. */
+        Object.defineProperty(this, "attendedDetach", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Detach callbacks for runs this connection is watching, so a dropped socket
+         * stops the hub fanning out into a dead channel. */
+        Object.defineProperty(this, "runDetachers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        /** Processes THIS connection is watching. A shared process table means two
+         * browsers can be paired to one daemon, and a client that never asked about a
+         * process should not be streamed its output - so output is fanned out per
+         * attachment, not to everyone. Spawning attaches you; `proc-attach` is how a
+         * second client (or the same one after a reload) opts in. */
+        Object.defineProperty(this, "attachedProcs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "procUnsub", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /* ---- sessions ---- */
+        /** Per-session stream stoppers for THIS connection.
+         *
+         * Per connection, not global: two browsers may watch one session, and a
+         * dropped socket must stop only its own follows. Keyed by session because a
+         * session outlives the request that started watching it. */
+        Object.defineProperty(this, "sessionWatch", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "memory", {
             enumerable: true,
             configurable: true,
@@ -139,10 +219,37 @@ export class SidecarServer {
         for (const t of opts.tools)
             this.tools.set(t.name, t);
         this.ch.onMessage((m) => this.onMessage(m));
+        // 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.
+        const offRoots = opts.roots?.subscribe((s) => this.ch.send({ t: 'roots', root: s.root, roots: s.roots }));
+        this.ch.onClose?.(() => {
+            this.attendedDetach?.();
+            this.attendedDetach = undefined;
+            // A dropped connection must stop receiving run events, or the hub keeps
+            // fanning out into a dead channel for the rest of the run.
+            for (const detach of this.runDetachers)
+                detach();
+            this.runDetachers.clear();
+            offRoots?.();
+            // Stop streaming process output into a dead socket. The PROCESSES keep
+            // running - that is the point of the table living on the daemon - but this
+            // connection stops hearing about them until something re-attaches.
+            this.procUnsub?.();
+            this.procUnsub = undefined;
+            this.attachedProcs.clear();
+            // Same reasoning for sessions: the SESSIONS keep running — that is what
+            // makes resume cheap — but this connection stops being sent their
+            // metrics and logs.
+            for (const sid of [...this.sessionWatch.keys()])
+                this.stopWatching(sid);
+        });
     }
     onMessage(m) {
         switch (m.t) {
             case 'hello':
+                if (this.authed)
+                    return; // identity is fixed at first hello; a second must not re-own the connection
                 this.onHello(m);
                 return;
             case 'invoke':
@@ -170,24 +277,238 @@ export class SidecarServer {
                 }
                 void this.onHttpReq(m);
                 return;
+            case 'run':
+                if (!this.authed) {
+                    this.ch.send({ t: 'run-error', id: m.id, error: 'not authenticated' });
+                    return;
+                }
+                void this.onRun(m);
+                return;
+            case 'subscribe':
+                // Guarded by auth like `run` (auth boundary). Pre-auth: drop silently —
+                // subscribe has no response channel, so no message is the correct
+                // pre-auth behavior (do not invent an ack variant).
+                if (!this.authed)
+                    return;
+                this.onSubscribe(m);
+                return;
+            case 'acp-start':
+                if (!this.authed) {
+                    this.ch.send({ t: 'acp-error', id: m.id, error: 'not authenticated' });
+                    return;
+                }
+                void this.onAcpStart(m);
+                return;
+            case 'acp-set-mode':
+                void this.onAcpSetMode(m);
+                return;
+            case 'acp-prompt':
+                if (!this.authed) {
+                    this.ch.send({ t: 'acp-error', id: m.id, error: 'not authenticated' });
+                    return;
+                }
+                void this.onAcpPrompt(m);
+                return;
+            case 'acp-cancel':
+                // A notification-shaped message like `subscribe`: no response channel,
+                // so a pre-auth cancel is dropped silently rather than answered.
+                if (!this.authed)
+                    return;
+                this.opts.acp?.cancel();
+                return;
+            case 'permission-answer':
+                // Guarded by auth like `run`/`subscribe` (auth boundary): a pre-auth
+                // answer is dropped silently rather than forwarded into the registry.
+                if (!this.authed)
+                    return;
+                this.opts.attendance?.answer(m.id, m.decision);
+                return;
+            case 'roots-browse':
+                // Auth-gated like every other request: directory enumeration must never
+                // precede the pairing token. Failures answer ok:false rather than throwing
+                // across the channel.
+                if (!this.authed) {
+                    this.ch.send({ t: 'roots-browse-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onRootsBrowse(m);
+                return;
+            case 'roots-add':
+                if (!this.authed) {
+                    this.ch.send({ t: 'roots-add-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onRootsAdd(m);
+                return;
+            case 'proc-spawn':
+                if (!this.authed) {
+                    this.ch.send({ t: 'proc-error', id: m.id, error: 'not authenticated' });
+                    return;
+                }
+                void this.onProcSpawn(m);
+                return;
+            case 'proc-attach':
+                if (!this.authed) {
+                    this.ch.send({ t: 'proc-attach-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                this.onProcAttach(m);
+                return;
+            case 'proc-input':
+                if (!this.authed) {
+                    this.ch.send({ t: 'proc-input-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                this.onProcSimple(m.id, 'proc-input-result', () => this.requireProcs().write(m.procId, m.text));
+                return;
+            case 'proc-kill':
+                if (!this.authed) {
+                    this.ch.send({ t: 'proc-kill-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                this.onProcSimple(m.id, 'proc-kill-result', () => this.requireProcs().kill(m.procId));
+                return;
+            case 'proc-list':
+                // An empty list is the honest answer for a daemon without the capability:
+                // it is running nothing, and an error here would make the common "what is
+                // running?" probe noisy on every sidecar that never allowed shell.
+                if (!this.authed) {
+                    this.ch.send({ t: 'proc-list-result', id: m.id, procs: [] });
+                    return;
+                }
+                this.ch.send({ t: 'proc-list-result', id: m.id, procs: this.opts.procs?.list() ?? [] });
+                return;
+            case 'session-list':
+                // An empty list is the honest answer from a daemon with no session
+                // layer: it is running none. An error would make the common "what is
+                // there?" probe noisy on every daemon that never enabled sessions.
+                if (!this.authed) {
+                    this.ch.send({ t: 'session-list-result', id: m.id, sessions: [] });
+                    return;
+                }
+                this.ch.send({ t: 'session-list-result', id: m.id, sessions: this.opts.sessions?.list() ?? [] });
+                return;
+            case 'session-create':
+            case 'session-pause':
+            case 'session-resume':
+            case 'session-destroy':
+            case 'session-commit':
+            case 'session-snapshots':
+            case 'session-watch':
+            case 'session-unwatch':
+                if (!this.authed) {
+                    this.ch.send({ t: 'session-error', id: m.id, error: 'not authenticated' });
+                    return;
+                }
+                void this.onSession(m);
+                return;
+            case 'run-history':
+                if (!this.authed) {
+                    this.ch.send({ t: 'run-history-result', id: m.id, runs: [] });
+                    return;
+                }
+                void this.onRunHistory(m);
+                return;
+            case 'run-transcript':
+                if (!this.authed) {
+                    this.ch.send({ t: 'run-transcript-result', id: m.id, lines: [] });
+                    return;
+                }
+                void this.onRunTranscript(m);
+                return;
+            case 'host-sync-put':
+                void this.onHostSyncPut(m);
+                return;
+            case 'host-sync-delete':
+                void this.onHostSyncDelete(m);
+                return;
             default:
-                return; // welcome / denied / invoke-result / host-call are host-side
+                // welcome / denied / invoke-result / host-call / event / run-accepted /
+                // run-done / permission-ask / permission-resolved are host-side.
+                return;
         }
     }
     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` });
             return;
         }
         if (!safeEqual(m.token ?? '', this.opts.token)) {
+            this.opts.log?.('denied: invalid token');
             this.ch.send({ t: 'denied', reason: 'invalid token' });
             return;
         }
         this.authed = true;
+        this.hostStateDir = m.stateDir ?? '.corenel';
+        // 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
+        // or object) must never reach `onClient`: downstream consumers use it as an
+        // object key (a daemon's hosts manifest) or feed it to a directory-name
+        // sanitizer that assumes a string.
+        if (typeof m.clientId === 'string' && m.clientId) {
+            const clientId = m.clientId.slice(0, MAX_IDENTITY_FIELD_LEN);
+            this.clientId = clientId;
+            const name = typeof m.clientName === 'string' && m.clientName
+                ? m.clientName.slice(0, MAX_IDENTITY_FIELD_LEN)
+                : clientId;
+            // Best-effort, fire-and-forget: a throwing/rejecting `onClient` must never
+            // deny/break an otherwise valid, authenticated handshake -- identity
+            // recording is informational, not part of the auth decision. Covers BOTH
+            // failure modes: a synchronous throw (try/catch) and a rejected promise
+            // from an async callback (the `.then(undefined, ...)` below), since the
+            // latter would otherwise surface as an unhandled rejection in the host
+            // process -- not caught by try/catch, which only sees the (resolved)
+            // Promise object the call returns, not its eventual rejection.
+            try {
+                const result = this.opts.onClient?.({ clientId, name });
+                if (isThenable(result)) {
+                    result.then(undefined, (err) => {
+                        this.opts.log?.(`onClient hook rejected: ${errMessage(err)}`);
+                    });
+                }
+            }
+            catch (err) {
+                this.opts.log?.(`onClient hook threw: ${errMessage(err)}`);
+            }
+        }
+        if (this.opts.attendance) {
+            this.attendedDetach = this.opts.attendance.attach({
+                send: (ask) => this.ch.send({ t: 'permission-ask', ...ask }),
+                resolved: (id, decision, by) => this.ch.send({ t: 'permission-resolved', id, decision, by }),
+                runActivity: (activity) => this.ch.send({ t: 'run-activity', activity }),
+                registrations: (registrations) => this.ch.send({ t: 'registrations', registrations }),
+            });
+        }
+        this.opts.log?.(`paired — ${this.tools.size} ${this.tools.size === 1 ? 'tool' : 'tools'} advertised (host dir: ${this.hostStateDir})`);
         const tools = [...this.tools.values()].map(({ run: _run, ...decl }) => decl);
         // Advertise the loopback HTTP proxy so the host can route local-LLM calls
-        // through us (server-side fetch, no browser CORS) instead of failing.
-        this.ch.send({ t: 'welcome', tools, features: ['http-proxy'] });
+        // through us (server-side fetch, no browser CORS) instead of failing, and
+        // 'runner' only when a crew runner is actually wired — that's what lets the
+        // host safely enable daemon-tier triggers (schedule/continuous/self-directed)
+        // instead of adding one that would silently never fire. `info` (the confined
+        // root + platform) lets the host show the working directory when browsing
+        // this sidecar as a file source; omitted cleanly when not provided.
+        const features = [
+            'http-proxy',
+            ...(this.opts.runner ? ['runner'] : []),
+            ...(this.opts.acp ? ['acp'] : []),
+            ...(this.opts.roots?.areas.length ? ['add-roots'] : []),
+            ...(this.opts.procs ? ['procs'] : []),
+            ...(this.opts.sessions ? ['sessions'] : []),
+            // The operator's transcript CEILING, advertised so a client offers the
+            // per-run choice only where it could be honoured. Withheld means every
+            // `run` here keeps nothing however it asks — a client showing a "keep
+            // this" control against such a daemon would be promising storage that
+            // never happens.
+            ...(this.opts.sessions?.canKeepTranscripts ? ['keep-transcripts'] : []),
+            // Whether a session can be created FROM a repository. Off unless the
+            // operator declared somewhere a checkout may be written, so a client only
+            // offers "start from a repository" where it would actually work.
+            ...(this.opts.sessions?.canClone ? ['session-clone'] : []),
+        ];
+        this.ch.send({ t: 'welcome', tools, features, ...(this.opts.info ? { info: this.opts.info } : {}) });
     }
     /** Proxy a host HTTP request server-side. Restricted to LOOPBACK targets — the
      * sidecar must never be usable as an SSRF pivot to internal/metadata hosts. The
@@ -225,20 +546,524 @@ export class SidecarServer {
             this.ch.send({ t: 'http-err', id: m.id, error: errMessage(e) });
         }
     }
+    requireSessions() {
+        const s = this.opts.sessions;
+        if (!s)
+            throw new Error('this sidecar runs no sessions (start the daemon with --daemon)');
+        return s;
+    }
+    async onSession(m) {
+        const id = m.id;
+        try {
+            const sessions = this.requireSessions();
+            switch (m.t) {
+                case 'session-create':
+                    this.ch.send({
+                        t: 'session-created',
+                        id,
+                        session: await sessions.create({
+                            ...(m.workdir ? { workdir: m.workdir } : {}),
+                            /* `repo` asks the daemon to CLONE the source rather than mount a
+                             * directory the client named. Forwarded, not judged: whether
+                             * cloning is permitted at all, where a checkout may land, and
+                             * 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 } : {}),
+                            ...(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
+                            // request would let a caller point a session's state anywhere.
+                            stateDir: this.hostStateDir,
+                        }),
+                    });
+                    return;
+                case 'session-pause': {
+                    // The drain result is carried through rather than reduced to ok/not:
+                    // a caller about to capture has to know whether work was still
+                    // running, because that is what makes a snapshot torn.
+                    const r = await sessions.pause(m.sessionId, m.drainMs);
+                    this.ch.send({ t: 'session-paused', id, drained: r.drained, remaining: r.remaining });
+                    return;
+                }
+                case 'session-resume':
+                    await sessions.resume(m.sessionId);
+                    this.ch.send({ t: 'session-ok', id });
+                    return;
+                case 'session-destroy':
+                    this.stopWatching(m.sessionId);
+                    await sessions.destroy(m.sessionId);
+                    this.ch.send({ t: 'session-ok', id });
+                    return;
+                case 'session-commit': {
+                    if (!sessions.commit)
+                        throw new Error('this session backend cannot capture snapshots');
+                    const snapshot = await sessions.commit(m.sessionId, m.name);
+                    this.ch.send({ t: 'session-committed', id, snapshot });
+                    return;
+                }
+                case 'session-snapshots': {
+                    // An empty list, not an error, when the backend cannot capture: the
+                    // question "what could I restore from?" has an answer there, and it
+                    // is "nothing". The client uses it to decide whether to offer the
+                    // choice at all, and an error would make it look broken instead.
+                    const snapshots = sessions.snapshots ? await sessions.snapshots() : [];
+                    this.ch.send({ t: 'session-snapshots-result', id, snapshots });
+                    return;
+                }
+                case 'session-watch': {
+                    // Idempotent: watching twice from one connection would double every
+                    // sample rather than doing nothing, which is the kind of bug a
+                    // reconnecting UI creates by accident.
+                    if (this.sessionWatch.has(m.sessionId)) {
+                        this.ch.send({ t: 'session-ok', id });
+                        return;
+                    }
+                    const stops = [];
+                    const sid = m.sessionId;
+                    if (sessions.watchMetrics) {
+                        stops.push(sessions.watchMetrics(sid, (sample) => this.ch.send({ t: 'session-metrics', sessionId: sid, sample })));
+                    }
+                    if (sessions.watchLogs) {
+                        stops.push(sessions.watchLogs(sid, (line) => this.ch.send({ t: 'session-log', sessionId: sid, line })));
+                    }
+                    this.sessionWatch.set(sid, stops);
+                    this.ch.send({ t: 'session-ok', id });
+                    return;
+                }
+                case 'session-unwatch':
+                    this.stopWatching(m.sessionId);
+                    this.ch.send({ t: 'session-ok', id });
+                    return;
+                default:
+                    this.ch.send({ t: 'session-error', id, error: `unhandled session message: ${m.t}` });
+            }
+        }
+        catch (e) {
+            this.ch.send({ t: 'session-error', id, error: errMessage(e) });
+        }
+    }
+    stopWatching(sessionId) {
+        for (const stop of this.sessionWatch.get(sessionId) ?? []) {
+            try {
+                stop();
+            }
+            catch { /* already stopped */ }
+        }
+        this.sessionWatch.delete(sessionId);
+    }
+    /* ---- long-running processes ---- */
+    /** The table, or a refusal that names WHY. "unknown message" would send an
+     * operator hunting for a bug when the real answer is that they did not pass
+     * --allow-shell. */
+    requireProcs() {
+        const procs = this.opts.procs;
+        if (!procs)
+            throw new Error('this sidecar was not started with --allow-shell, so it cannot run processes');
+        return procs;
+    }
+    /** Begin fanning this connection's attached processes back over the wire.
+     * Subscribed lazily: a client that never touches a process should not pay to
+     * be woken for someone else's build output. */
+    ensureProcStream() {
+        if (this.procUnsub)
+            return;
+        this.procUnsub = this.requireProcs().subscribe((ev) => {
+            if (!this.attachedProcs.has(ev.procId))
+                return;
+            if (ev.kind === 'out') {
+                this.ch.send({ t: 'proc-out', procId: ev.procId, seq: ev.chunk.seq, stream: ev.chunk.stream, text: ev.chunk.text });
+                return;
+            }
+            this.ch.send({
+                t: 'proc-exit',
+                procId: ev.procId,
+                code: ev.info.exitCode ?? null,
+                ...(ev.info.signal ? { signal: ev.info.signal } : {}),
+            });
+            // Attachment ends with the process. Keeping it would leak an entry per run
+            // on a connection that stays open for hours.
+            this.attachedProcs.delete(ev.procId);
+        });
+    }
+    async onProcSpawn(m) {
+        try {
+            const procs = this.requireProcs();
+            // Attach BEFORE spawning: a command that prints immediately would otherwise
+            // race the subscription and lose its first lines.
+            this.ensureProcStream();
+            const info = await procs.spawn({
+                command: m.command,
+                ...(m.cwd ? { cwd: m.cwd } : {}),
+                ...(m.root ? { root: m.root } : {}),
+                ...(m.label ? { label: m.label } : {}),
+            });
+            this.attachedProcs.add(info.procId);
+            this.ch.send({ t: 'proc-started', id: m.id, proc: info });
+            // A process can finish before the caller ever sees `proc-started` (`echo
+            // hi`). Replay whatever the table already holds so no output is lost to
+            // that race, and report the exit it already had.
+            const { chunks } = procs.backlog(info.procId);
+            for (const c of chunks)
+                this.ch.send({ t: 'proc-out', procId: info.procId, seq: c.seq, stream: c.stream, text: c.text });
+            const now = procs.get(info.procId);
+            if (now && !now.running) {
+                this.attachedProcs.delete(info.procId);
+                this.ch.send({ t: 'proc-exit', procId: info.procId, code: now.exitCode ?? null, ...(now.signal ? { signal: now.signal } : {}) });
+            }
+        }
+        catch (e) {
+            this.ch.send({ t: 'proc-error', id: m.id, error: errMessage(e) });
+        }
+    }
+    /** Re-attach to a process after a reload or from a second client. `sinceSeq`
+     * is what the client already has, so the replay is exactly the rest. */
+    onProcAttach(m) {
+        try {
+            const procs = this.requireProcs();
+            const info = procs.get(m.procId);
+            if (!info) {
+                this.ch.send({ t: 'proc-attach-result', id: m.id, ok: false, error: `no such process: ${m.procId}` });
+                return;
+            }
+            this.ensureProcStream();
+            if (info.running)
+                this.attachedProcs.add(m.procId);
+            const { chunks, truncated } = procs.backlog(m.procId, m.sinceSeq);
+            this.ch.send({ t: 'proc-attach-result', id: m.id, ok: true, proc: info, ...(truncated ? { truncated: true } : {}) });
+            for (const c of chunks)
+                this.ch.send({ t: 'proc-out', procId: m.procId, seq: c.seq, stream: c.stream, text: c.text });
+            // An already-exited process still owes the client its ending, or a
+            // reattaching UI shows a spinner for something finished an hour ago.
+            if (!info.running) {
+                this.ch.send({ t: 'proc-exit', procId: m.procId, code: info.exitCode ?? null, ...(info.signal ? { signal: info.signal } : {}) });
+            }
+        }
+        catch (e) {
+            this.ch.send({ t: 'proc-attach-result', id: m.id, ok: false, error: errMessage(e) });
+        }
+    }
+    /** The kill/input pair: act, then answer with ok or the reason. */
+    onProcSimple(id, reply, act) {
+        try {
+            act();
+            this.ch.send({ t: reply, id, ok: true });
+        }
+        catch (e) {
+            this.ch.send({ t: reply, id, ok: false, error: errMessage(e) });
+        }
+    }
     async onInvoke(m) {
         const tool = this.tools.get(m.name);
         if (!tool) {
+            this.opts.log?.(`invoke ${m.name}: unknown tool`);
             this.ch.send({ t: 'invoke-result', id: m.id, ok: false, error: `unknown tool ${m.name}` });
             return;
         }
+        this.opts.log?.(`invoke ${m.name}`);
         try {
             const result = await tool.run(m.args, this.makeContext());
             this.ch.send({ t: 'invoke-result', id: m.id, ok: true, result });
         }
         catch (e) {
+            this.opts.log?.(`invoke ${m.name} failed: ${errMessage(e)}`);
             this.ch.send({ t: 'invoke-result', id: m.id, ok: false, error: errMessage(e) });
         }
     }
+    /** Runs a crew agent via the configured `runner` and streams its lifecycle back
+     * to the host: `run-accepted` (with the daemon-assigned runId) once the runner
+     * has started, one `event` per `onEvent` callback, then exactly one of
+     * `run-done` (final text + stop reason) or `run-error`.
+     *
+     * `runner.run` returns the runId asynchronously, but a runner is free to call
+     * `onEvent` synchronously before that promise settles (e.g. an immediate first
+     * turn). Events that arrive before we know the runId are buffered and flushed
+     * right after `run-accepted`, so they still carry the correct runId and never
+     * race ahead of it on the wire. */
+    async onAcpStart(m) {
+        const acp = this.opts.acp;
+        if (!acp) {
+            this.ch.send({ t: 'acp-error', id: m.id, error: 'this sidecar was not started with --acp' });
+            return;
+        }
+        try {
+            const started = await acp.start(m.target, (update) => {
+                this.ch.send({ t: 'acp-update', id: m.id, update });
+            }, {
+                ...(m.root ? { root: m.root } : {}),
+                ...(m.modeId ? { modeId: m.modeId } : {}),
+                ...(m.resume ? { resume: m.resume } : {}),
+            });
+            this.ch.send({ t: 'acp-started', id: m.id, ...started });
+        }
+        catch (err) {
+            this.ch.send({ t: 'acp-error', id: m.id, error: errMessage(err) });
+        }
+    }
+    async onAcpSetMode(m) {
+        const acp = this.opts.acp;
+        if (!acp) {
+            this.ch.send({ t: 'acp-error', id: m.id, error: 'this sidecar was not started with --acp' });
+            return;
+        }
+        try {
+            await acp.setMode(m.modeId);
+            this.ch.send({ t: 'acp-mode-set', id: m.id, modeId: m.modeId });
+        }
+        catch (err) {
+            this.ch.send({ t: 'acp-error', id: m.id, error: errMessage(err) });
+        }
+    }
+    async onAcpPrompt(m) {
+        const acp = this.opts.acp;
+        if (!acp) {
+            this.ch.send({ t: 'acp-error', id: m.id, error: 'this sidecar was not started with --acp' });
+            return;
+        }
+        try {
+            const { stopReason } = await acp.prompt(m.text, m.content);
+            this.ch.send({ t: 'acp-done', id: m.id, stopReason });
+        }
+        catch (err) {
+            this.ch.send({ t: 'acp-error', id: m.id, error: errMessage(err) });
+        }
+    }
+    /**
+     * Attach this connection as a VIEWER of a run it did not start.
+     *
+     * The replay comes first, so a client joining mid-run sees the whole run
+     * rather than the tail — a viewer that only sees what happens next cannot tell
+     * a stalled run from a quiet one. Events are tagged with the SUBSCRIBER's own
+     * message id, so a client correlating by id sees its own stream.
+     */
+    onSubscribe(m) {
+        const hub = this.opts.runs;
+        if (!hub) {
+            this.ch.send({ t: 'run-error', id: m.id, error: 'this sidecar does not support watching runs' });
+            return;
+        }
+        const attached = hub.subscribe(m.runId, {
+            event: (event) => this.ch.send({ t: 'event', id: m.id, runId: m.runId, event }),
+            done: (r) => {
+                this.ch.send({ t: 'run-done', id: m.id, runId: m.runId, text: r.text, stopReason: r.stopReason });
+                detachOnce();
+            },
+            error: (message) => {
+                this.ch.send({ t: 'run-error', id: m.id, error: message });
+                detachOnce();
+            },
+        });
+        if (!attached) {
+            this.ch.send({ t: 'run-error', id: m.id, error: `no such run: ${m.runId}` });
+            return;
+        }
+        // Held so a dropped connection detaches; also removed on done/error below.
+        const detachOnce = () => {
+            if (!this.runDetachers.has(attached.detach))
+                return;
+            this.runDetachers.delete(attached.detach);
+            attached.detach();
+        };
+        this.runDetachers.add(attached.detach);
+        this.ch.send({ t: 'run-accepted', id: m.id, runId: m.runId });
+        if (attached.replay.dropped > 0) {
+            // Say so rather than handing over a tail that looks complete.
+            this.opts.log?.(`subscribe ${m.runId}: replaying with ${attached.replay.dropped} earlier event(s) dropped`);
+        }
+        for (const event of attached.replay.events) {
+            this.ch.send({ t: 'event', id: m.id, runId: m.runId, event });
+        }
+        // A run that already finished still replays, then closes immediately.
+        if (attached.replay.done) {
+            this.ch.send({ t: 'run-done', id: m.id, runId: m.runId, ...attached.replay.done });
+            detachOnce();
+        }
+        else if (attached.replay.error) {
+            this.ch.send({ t: 'run-error', id: m.id, error: attached.replay.error });
+            detachOnce();
+        }
+    }
+    /**
+     * What this caller's agent has actually done.
+     *
+     * AN EMPTY LIST IS AN ANSWER, not a failure: a daemon that keeps no record
+     * has no history, and a client uses the rows to render rather than to detect
+     * a broken daemon. The identity handed down is the untrusted `{ clientId }`
+     * this connection authenticated with — the runner resolves it through the
+     * hosts manifest, which is what makes the result owner-scoped by
+     * construction rather than by a filter written here.
+     */
+    async onRunHistory(m) {
+        try {
+            const runs = this.opts.runner?.history
+                ? await this.opts.runner.history({ clientId: this.clientId }, m.agent, m.limit)
+                : [];
+            this.ch.send({ t: 'run-history-result', id: m.id, runs });
+        }
+        catch {
+            // A history that cannot be read is not a reason to break the caller's
+            // page; the rows it already has stay, and it sees none added.
+            this.ch.send({ t: 'run-history-result', id: m.id, runs: [] });
+        }
+    }
+    /** One run's kept events. Empty when they were never kept — the ordinary
+     * case, and a state the caller renders rather than treats as a failure. */
+    async onRunTranscript(m) {
+        try {
+            const lines = this.opts.runner?.transcript
+                ? await this.opts.runner.transcript({ clientId: this.clientId }, m.agent, m.runId)
+                : [];
+            this.ch.send({ t: 'run-transcript-result', id: m.id, lines });
+        }
+        catch {
+            this.ch.send({ t: 'run-transcript-result', id: m.id, lines: [] });
+        }
+    }
+    async onRun(m) {
+        /* WHERE the run happens, decided once, up front.
+         *
+         * A `sessionId` is a confinement request. A daemon that cannot honour it
+         * 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. */
+        if (m.sessionId !== undefined) {
+            const sessions = this.opts.sessions;
+            if (!sessions?.run) {
+                this.ch.send({ t: 'run-error', id: m.id, error: 'this sidecar cannot run agents inside a session' });
+                return;
+            }
+        }
+        else if (!this.opts.runner) {
+            this.ch.send({ t: 'run-error', id: m.id, error: 'this sidecar cannot run agents' });
+            return;
+        }
+        const start = m.sessionId !== undefined
+            ? (agent, input, onEvent, identity) => 
+            /* The request is forwarded, never resolved here. Whether it is honoured
+             * is the session layer's call, because the operator's permission lives
+             * there; this class would have to duplicate that rule to decide, and a
+             * duplicated permission rule is one that eventually disagrees. */
+            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);
+        let runId;
+        const pending = [];
+        const onEvent = (event) => {
+            // Publish to the hub as well as this connection, so another device can
+            // watch. Buffered until the runner reports its id, since the hub is keyed
+            // by it — the same reason `pending` exists for the commanding client.
+            if (runId !== undefined)
+                this.opts.runs?.publish(runId, event);
+            if (runId === undefined) {
+                pending.push(event);
+                return;
+            }
+            this.ch.send({ t: 'event', id: m.id, runId, event });
+        };
+        try {
+            // Task 12 fix-wave: forward this connection's authenticated `clientId`
+            // (or `undefined` for an unidentified/older peer) as an UNTRUSTED
+            // `{ clientId }` identity -- this class must never resolve it itself
+            // (no manifest access here, by design; see the module doc), it just
+            // hands the identity it already holds to the runner, exactly like
+            // `onHostSyncPut`/`onHostSyncDelete` do for `hostSync.put`/`remove`.
+            const started = await start(m.agent, m.input, onEvent, { clientId: this.clientId });
+            runId = started.runId;
+            this.opts.runs?.open(runId);
+            this.ch.send({ t: 'run-accepted', id: m.id, runId });
+            for (const event of pending) {
+                this.opts.runs?.publish(runId, event);
+                this.ch.send({ t: 'event', id: m.id, runId, event });
+            }
+            const fin = await started.done;
+            this.opts.runs?.finish(runId, { text: fin.text, stopReason: fin.stopReason });
+            this.ch.send({ t: 'run-done', id: m.id, runId, text: fin.text, stopReason: fin.stopReason });
+        }
+        catch (e) {
+            const message = errMessage(e);
+            // Tell watchers too: a run that failed must not look merely silent to a
+            // second viewer.
+            if (runId !== undefined)
+                this.opts.runs?.fail(runId, message);
+            this.ch.send({ t: 'run-error', id: m.id, error: message });
+        }
+    }
+    /** The identity to attribute a host-sync write to. Returns either the
+     * authenticated `clientId`, or an error string explaining why there is none --
+     * either this connection is not authenticated yet, or it authenticated with no
+     * `clientId` (an older client). The latter is NOT an auth failure (the pairing
+     * token already authenticated the connection); it is a "no owner to attribute
+     * files to" rule -- a write with no owner must never reach the port. */
+    requireHostSyncIdentity() {
+        if (!this.authed)
+            return { error: 'not authenticated' };
+        if (this.clientId === undefined) {
+            return { error: 'this connection carries no client identity to attribute host-sync writes to' };
+        }
+        return { clientId: this.clientId };
+    }
+    async onRootsBrowse(m) {
+        if (!this.opts.roots) {
+            this.ch.send({ t: 'roots-browse-result', id: m.id, ok: false, error: 'this sidecar cannot add working directories' });
+            return;
+        }
+        try {
+            this.ch.send({ t: 'roots-browse-result', id: m.id, ok: true, dirs: await this.opts.roots.browse(m.path) });
+        }
+        catch (e) {
+            this.ch.send({ t: 'roots-browse-result', id: m.id, ok: false, error: errMessage(e) });
+        }
+    }
+    async onRootsAdd(m) {
+        if (!this.opts.roots) {
+            this.ch.send({ t: 'roots-add-result', id: m.id, ok: false, error: 'this sidecar cannot add working directories' });
+            return;
+        }
+        try {
+            // The broadcast to every client is the controller's subscription, not this
+            // reply -- so a refusal (below) reaches only the asker and changes nothing.
+            await this.opts.roots.add(m.path);
+            this.ch.send({ t: 'roots-add-result', id: m.id, ok: true });
+        }
+        catch (e) {
+            this.ch.send({ t: 'roots-add-result', id: m.id, ok: false, error: errMessage(e) });
+        }
+    }
+    async onHostSyncPut(m) {
+        const identity = this.requireHostSyncIdentity();
+        if ('error' in identity) {
+            this.ch.send({ t: 'host-sync-result', id: m.id, ok: false, error: identity.error });
+            return;
+        }
+        if (!this.opts.hostSync) {
+            this.ch.send({ t: 'host-sync-result', id: m.id, ok: false, error: 'this sidecar cannot sync host config' });
+            return;
+        }
+        try {
+            await this.opts.hostSync.put(identity.clientId, m.path, m.content);
+            this.ch.send({ t: 'host-sync-result', id: m.id, ok: true });
+        }
+        catch (e) {
+            this.ch.send({ t: 'host-sync-result', id: m.id, ok: false, error: errMessage(e) });
+        }
+    }
+    async onHostSyncDelete(m) {
+        const identity = this.requireHostSyncIdentity();
+        if ('error' in identity) {
+            this.ch.send({ t: 'host-sync-result', id: m.id, ok: false, error: identity.error });
+            return;
+        }
+        if (!this.opts.hostSync) {
+            this.ch.send({ t: 'host-sync-result', id: m.id, ok: false, error: 'this sidecar cannot sync host config' });
+            return;
+        }
+        try {
+            await this.opts.hostSync.remove(identity.clientId, m.path);
+            this.ch.send({ t: 'host-sync-result', id: m.id, ok: true });
+        }
+        catch (e) {
+            this.ch.send({ t: 'host-sync-result', id: m.id, ok: false, error: errMessage(e) });
+        }
+    }
     /** A ToolContext whose capabilities proxy back to the host (persist-nothing).
      * The stores, the host's file workspace, and the user prompts (confirm/ask) all
      * round-trip over the channel. confirm/ask default to allow/dismiss when the