@corenel/harness 0.2.0 → 0.4.0

package/dist/sidecar/server.js

@@ -100,6 +100,43 @@ export class SidecarServer {
             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,
@@ -182,9 +219,30 @@ 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) {
@@ -232,10 +290,31 @@ export class SidecarServer {
                 // pre-auth behavior (do not invent an ack variant).
                 if (!this.authed)
                     return;
-                // P1 authed path: acknowledge-and-noop. The single commanding client
-                // already gets events via its `run` id; multi-subscriber replay is P3.
-                // Defined here so the message is forward-compatible and never mistaken
-                // for unknown.
+                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
@@ -244,6 +323,100 @@ export class SidecarServer {
                     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-snapshot-usage':
+            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;
@@ -305,6 +478,8 @@ export class SidecarServer {
             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})`);
@@ -316,7 +491,24 @@ export class SidecarServer {
         // 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'] : [])];
+        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
@@ -355,6 +547,224 @@ 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-snapshot-usage': {
+                    // Same shape as the empty-list answer above: a backend with no
+                    // budget to report has zero usage against zero budget, not an
+                    // error — a status surface should render that as "not applicable"
+                    // rather than treat it as broken.
+                    const usage = sessions.snapshotUsage
+                        ? await sessions.snapshotUsage()
+                        : { usedBytes: 0, budgetBytes: 0, count: 0 };
+                    this.ch.send({ t: 'session-snapshot-usage-result', id, usage });
+                    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) {
@@ -382,14 +792,179 @@ export class SidecarServer {
      * 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) {
-        if (!this.opts.runner) {
+        /* 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;
@@ -403,16 +978,25 @@ export class SidecarServer {
             // (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 this.opts.runner.run(m.agent, m.input, onEvent, { clientId: this.clientId });
+            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)
+            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) {
-            this.ch.send({ t: 'run-error', id: m.id, error: errMessage(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
@@ -429,6 +1013,33 @@ export class SidecarServer {
         }
         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) {