commandmate 0.32.1 → 0.33.1

package/dist/server/src/lib/cli-tools/base.js

@@ -5,6 +5,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseCLITool = void 0;
+exports.resetHookUrlProbesForTest = resetHookUrlProbesForTest;
+exports.readLaunchLineHookUrl = readLaunchLineHookUrl;
+exports.hookUrlPort = hookUrlPort;
+exports.probeRunningSessionHookUrl = probeRunningSessionHookUrl;
 const child_process_1 = require("child_process");
 const util_1 = require("util");
 const session_name_1 = require("./session-name");
@@ -15,11 +19,121 @@ const graceful_exit_1 = require("./graceful-exit");
 const liveness_spec_1 = require("./liveness-spec");
 const session_liveness_1 = require("./session-liveness");
 const start_availability_1 = require("./start-availability");
+const ansi_1 = require("../detection/ansi");
+const env_1 = require("../env");
+const launch_command_1 = require("../hooks/sources/launch-command");
 const logger_1 = require("../logger");
 const terminal_keys_1 = require("../../types/terminal-keys");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
+const tmux_pane_config_1 = require("../../config/tmux-pane-config");
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 const logger = (0, logger_1.createLogger)('cli-tools/base');
+/**
+ * `CM_HOOK_URL='…'` as a launch line spells it (Issue #2429).
+ *
+ * Built from {@link AGENT_EVENT_URL_ENV_VAR} rather than from a literal, for
+ * the reason `launch-command` gives for owning that constant: a drifted name
+ * here would read a variable CommandMate never wrote and report every session
+ * as fine.
+ *
+ * All three quoting forms, because the reader is a pane and not a parser:
+ * `resolveAgentLaunchEnv` renders single quotes today, and a line typed by hand
+ * or by an older build may carry double quotes or none.
+ */
+const HOOK_URL_ASSIGNMENT_PATTERN = new RegExp(`${launch_command_1.AGENT_EVENT_URL_ENV_VAR}=(?:'([^']*)'|"([^"]*)"|(\\S+))`, 'g');
+/**
+ * Session names whose launch took the REUSE branch (Issue #2429).
+ *
+ * The adopt marker, and the reason it is a set rather than a return value:
+ * {@link BaseCLITool.reconcileExistingSession} is the one line every tool's
+ * reuse branch calls and it is handed only a session name, while the identity
+ * the warning needs — worktree, instance, tool name — is `startSession`'s. A
+ * signature change would have to reach seven `launchSession` implementations to
+ * carry one boolean back up.
+ *
+ * Written by the reconcile, consumed by `startSession` (see
+ * {@link BaseCLITool.takeAdoptionMark}), so a pane this server CREATED never
+ * reaches the probe: its launch line is one this process just typed, and asking
+ * tmux to prove that would cost a full-scrollback `capture-pane` on every
+ * session start for an answer that is known.
+ */
+const adoptedSessions = new Set();
+/**
+ * Session names whose launch line this process has already read (Issue #2433).
+ *
+ * The reason the send path can ask at all. #2429 put the hook-URL probe behind
+ * the adopt marker, and measured on this tree that marker is unreachable for
+ * every tool that writes `CM_HOOK_URL` onto its launch line: antigravity,
+ * command-code and gemini all answer `isRunning()` with `hasSession()`, so the
+ * reuse branch that sets the mark needs a pane to exist while `startSession()`
+ * — the only caller of `launchSession()` — is reached only when one does not.
+ * The situation #2429 actually reported (a pane raised by a server on another
+ * port, still being typed into) is exactly the situation in which the pane is
+ * alive, so the probe never ran.
+ *
+ * Moving the question to "we are about to send into an existing session" makes
+ * it reachable, and this set is what keeps it cheap: reading the launch line
+ * costs a full-scrollback `capture-pane`, and a send happens as often as an
+ * operator presses Enter. A launch line does not change while a pane lives —
+ * {@link BaseCLITool.relaunchIfToolExited} re-types it with THIS server's port,
+ * which is never the mismatch — so one read per session per process answers it
+ * for good.
+ *
+ * Recorded only after a capture that actually returned, so a pane that could not
+ * be read (a session that vanished between `isRunning` and here) is asked again
+ * rather than silently written off.
+ */
+const hookUrlProbedSessions = new Set();
+/**
+ * Forget every hook-URL probe made so far (Issue #2433).
+ *
+ * Test-only, and named so, for the same reason
+ * `resetStaleHookUrlReportsForTest` is: the set above is process-lifetime state
+ * and a suite that asserts "the pane is read once" needs the first read to be
+ * the first one.
+ */
+function resetHookUrlProbesForTest() {
+    hookUrlProbedSessions.clear();
+}
+/**
+ * The last `CM_HOOK_URL` a pane's scrollback names, or null (Issue #2429).
+ *
+ * **Last**, not first. An adopted pane carries only the launch line that
+ * started the agent — the stale one. A pane whose tool exited and was relaunched
+ * by {@link BaseCLITool.relaunchIfToolExited} carries both, oldest first, and
+ * the newest is the one in force. Taking the first match would report a
+ * mismatch this server had already repaired.
+ *
+ * Exported for the unit suite: the whole rule is "what does this text say", and
+ * pinning it against real launch lines needs no tmux.
+ */
+function readLaunchLineHookUrl(pane) {
+    let last = null;
+    for (const match of (0, ansi_1.stripAnsi)(pane).matchAll(HOOK_URL_ASSIGNMENT_PATTERN)) {
+        const value = match[1] ?? match[2] ?? match[3] ?? null;
+        if (value)
+            last = value;
+    }
+    return last;
+}
+/**
+ * The port a hook URL posts to, or null when it is not a URL (Issue #2429).
+ *
+ * The default port is filled in from the scheme rather than left null, so a
+ * `http://127.0.0.1/api/hooks/...` line is compared as 80 instead of being
+ * waved through as unreadable.
+ */
+function hookUrlPort(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.port !== '')
+            return Number(parsed.port);
+        return parsed.protocol === 'https:' ? 443 : 80;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Abstract base class for CLI tools
  * Implements common functionality and defines abstract methods for specific implementations
@@ -100,6 +214,10 @@ class BaseCLITool {
             await this.launchSession(worktreeId, worktreePath, instanceId, model);
         }
         catch (error) {
+            // Issue #2429: a launch that threw is reported as a failed start and as
+            // nothing else. The mark is dropped rather than left behind so a later,
+            // successful start of the same session does not inherit it.
+            this.takeAdoptionMark(worktreeId, instanceId);
             (0, start_availability_1.reportSessionStartFailure)({
                 worktreeId,
                 cliToolId: this.id,
@@ -108,11 +226,177 @@ class BaseCLITool {
             }, error);
             throw error;
         }
+        const adopted = this.takeAdoptionMark(worktreeId, instanceId);
+        if (adopted !== null)
+            await this.warnIfHookUrlIsStale(worktreeId, adopted, instanceId);
     }
-    /** Repair geometry when reusing a tmux session that predates the current defaults. */
+    /**
+     * Repair geometry when reusing a tmux session that predates the current
+     * defaults, and record that this launch reused one (Issue #2429).
+     */
     async reconcileExistingSession(sessionName, options) {
+        adoptedSessions.add(sessionName);
         await (0, tmux_1.reconcileSessionGeometry)(sessionName, options);
     }
+    /**
+     * The reused pane's session name, or null when this launch created one
+     * (Issue #2429).
+     *
+     * Consumes the mark, so one launch asks one question. `getSessionName` can
+     * throw on an id that would not validate — the tool's own `launchSession`
+     * would have thrown on it first, so reaching that catch means something more
+     * interesting than a stale hook URL is wrong and this must not be what
+     * reports it.
+     */
+    takeAdoptionMark(worktreeId, instanceId) {
+        try {
+            const sessionName = this.getSessionName(worktreeId, instanceId);
+            return adoptedSessions.delete(sessionName) ? sessionName : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Warn when an adopted pane's hooks are addressed to another server
+     * (Issue #2429).
+     *
+     * ## What goes wrong without it
+     *
+     * `CM_HOOK_URL` is written onto the launch line by the server that starts the
+     * agent, and it is the whole of the correlation channel: it names the port the
+     * relay posts every lifecycle event to. A tmux session outlives the server
+     * that created it, so a pane started by a server on :3010 and later adopted by
+     * one on :3000 — {@link reconcileExistingSession}'s branch, which repairs the
+     * window geometry and nothing else — goes on posting to :3010. Measured
+     * 2026-09-08: every `commandmate wait` on that session held for #1975's full
+     * 60 s and then completed `basis=scraper_ready` with `Its hooks are not
+     * answering`, because from :3000's side the agent had simply gone silent.
+     *
+     * Nothing on any surface said so. The pane looked healthy, the CLI was
+     * reachable, and the only evidence was a port number in a launch line
+     * thousands of scrollback rows up.
+     *
+     * ## Why it warns rather than repairs
+     *
+     * The repair is to restart the agent, and restarting it is exactly what must
+     * not happen automatically: the adopted session may be mid-turn, and killing a
+     * generating agent to fix its telemetry costs the work. So this reports and
+     * stops. `reportStaleHookUrl` is what makes it once — see that function.
+     *
+     * ## Who asks, and why the create path still does not
+     *
+     * Two callers. {@link startSession} asks when the launch REUSED a pane —
+     * {@link reconcileExistingSession}'s mark — and
+     * {@link warnIfRunningSessionHookUrlIsStale} asks when a send is about to type
+     * into a session that is already running. The second was added by Issue #2433
+     * because the first, alone, is unreachable for every tool that puts
+     * `CM_HOOK_URL` on its launch line: see {@link hookUrlProbedSessions}.
+     *
+     * A pane this server CREATED is asked by neither. Its launch line is one this
+     * process typed a moment ago, so the comparison is this server's port against
+     * itself and the answer is known without asking; asking anyway would put a
+     * full-scrollback `capture-pane` in front of every session start, which is a
+     * real cost on the path an operator is waiting on.
+     *
+     * The #2070 relaunch (the tool died, so the pane is reused but the launch
+     * line is re-typed) goes through the adopt mark too, and is why
+     * {@link readLaunchLineHookUrl} takes the NEWEST assignment: such a pane
+     * carries both, and the new one is in force.
+     *
+     * Never throws, never blocks a start and never blocks a send: a tool whose
+     * hook URL cannot be read — claude and opencode keep theirs out of the launch
+     * line entirely — simply yields null and is left alone.
+     */
+    async warnIfHookUrlIsStale(worktreeId, sessionName, instanceId) {
+        // Issue #2433: at most one read per session per process. The send path calls
+        // this on every message to an already-running session, and without this line
+        // that would put a full-scrollback capture in front of every Enter.
+        if (hookUrlProbedSessions.has(sessionName))
+            return;
+        try {
+            // The whole scrollback: the launch line is the OLDEST thing in an adopted
+            // pane, and `TMUX_HISTORY_LIMIT` is the ceiling tmux was told to keep.
+            const pane = await (0, tmux_1.capturePane)(sessionName, { startLine: -tmux_pane_config_1.TMUX_HISTORY_LIMIT });
+            hookUrlProbedSessions.add(sessionName);
+            const sessionHookUrl = readLaunchLineHookUrl(pane);
+            if (sessionHookUrl === null)
+                return;
+            const sessionPort = hookUrlPort(sessionHookUrl);
+            const serverPort = (0, env_1.getServerPort)();
+            if (sessionPort === null || sessionPort === serverPort)
+                return;
+            logger.warn('session:hook-url-stale', {
+                cliToolId: this.id,
+                sessionName,
+                sessionPort,
+                serverPort,
+            });
+            (0, start_availability_1.reportStaleHookUrl)({
+                worktreeId,
+                cliToolId: this.id,
+                instanceId,
+                toolName: this.name,
+                sessionPort,
+                serverPort,
+            });
+        }
+        catch (error) {
+            logger.debug('session:hook-url-probe-failed', {
+                cliToolId: this.id,
+                worktreeId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Ask the same question of a session that is ALREADY running (Issue #2433).
+     *
+     * ## Why the send path is where it has to be asked
+     *
+     * #2429's probe hangs off the adopt marker, and the marker is set inside a
+     * tool's `launchSession()` reuse branch — which `startSession()` reaches only
+     * when the pane already exists, while `POST /api/worktrees/:id/send` calls
+     * `startSession()` only when `isRunning()` said it does not. For antigravity,
+     * command-code and gemini — the three tools that write `CM_HOOK_URL` onto the
+     * launch line at all — `isRunning()` IS `hasSession()`, so those two
+     * conditions cannot both hold and the probe never ran. claude's `isRunning()`
+     * does look at the process, but claude keeps its endpoint out of the launch
+     * line, so {@link readLaunchLineHookUrl} answers null for it.
+     *
+     * The result was that the one situation #2429 was written for — a pane raised
+     * by a server on another port, still being typed into, its hooks posting into
+     * the void — was precisely the situation in which the pane is alive and
+     * therefore never examined. Measured 2026-09-08 against a live
+     * `mcbd-command-code-…` session whose launch line named :3000 while the server
+     * was :3010: zero `session:hook-url-stale` lines from either a capture or a
+     * send.
+     *
+     * ## What it costs
+     *
+     * One `capture-pane` per session per server process, and nothing after that —
+     * {@link hookUrlProbedSessions} is checked before tmux is touched, so the
+     * second and every later send to the same pane reach no further than a `Set`
+     * lookup. The per-send capture count the launch-readiness suites pin is
+     * unchanged.
+     *
+     * Nothing here can fail a send: {@link warnIfHookUrlIsStale} contains its own
+     * faults, and a session id that would not validate is simply not probed (the
+     * send that follows will fail on its own account, with a better message).
+     *
+     * @param worktreeId - Worktree the running session belongs to
+     * @param instanceId - Agent instance ID (defaults to the primary instance)
+     */
+    async warnIfRunningSessionHookUrlIsStale(worktreeId, instanceId) {
+        let sessionName;
+        try {
+            sessionName = this.getSessionName(worktreeId, instanceId);
+        }
+        catch {
+            return;
+        }
+        await this.warnIfHookUrlIsStale(worktreeId, sessionName, instanceId);
+    }
     /**
      * Interrupt processing by sending Escape key
      * Default implementation: send Escape key to tmux session
@@ -314,3 +598,29 @@ class BaseCLITool {
     }
 }
 exports.BaseCLITool = BaseCLITool;
+/**
+ * Probe a running session's hook URL, for a caller holding an `ICLITool`
+ * (Issue #2433).
+ *
+ * `POST /api/worktrees/:id/send` gets its tool from
+ * `CLIToolManager.getTool()`, which is typed as the {@link ICLITool} interface;
+ * the probe is a {@link BaseCLITool} concern and deliberately not part of that
+ * interface, because it is not something a tool has to implement — it is
+ * something every tool inherits. The narrowing lives here, next to the class it
+ * narrows to, rather than as an `instanceof` in the route.
+ *
+ * Fire-and-forget on purpose. The answer changes nothing about the message
+ * being sent — the Issue's decision, inherited from #2429, is to warn and NOT
+ * restart, because the adopted session may be mid-turn — so making the operator
+ * wait on a `capture-pane` for it would be paying latency for a notification.
+ * The returned promise cannot reject; the `.catch` is the belt.
+ *
+ * @param tool - The tool whose session is about to be typed into
+ * @param worktreeId - Worktree the running session belongs to
+ * @param instanceId - Agent instance ID (defaults to the primary instance)
+ */
+function probeRunningSessionHookUrl(tool, worktreeId, instanceId) {
+    if (!(tool instanceof BaseCLITool))
+        return;
+    void tool.warnIfRunningSessionHookUrlIsStale(worktreeId, instanceId).catch(() => { });
+}

package/dist/server/src/lib/cli-tools/start-availability.js

@@ -62,6 +62,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reportSessionStartFailure = reportSessionStartFailure;
+exports.reportStaleHookUrl = reportStaleHookUrl;
+exports.resetStaleHookUrlReportsForTest = resetStaleHookUrlReportsForTest;
 exports.assertToolStartable = assertToolStartable;
 exports.reportToolUnavailable = reportToolUnavailable;
 const install_hints_1 = require("./install-hints");
@@ -87,6 +89,56 @@ function reportSessionStartFailure(report, error) {
     void Promise.resolve().then(() => __importStar(require('../push/failure-push-notifier'))).then(({ notifySessionStartFailurePush }) => notifySessionStartFailurePush({ ...report, error }))
         .catch(() => { });
 }
+/**
+ * Which (instance, port pair) has already been reported (Issue #2429).
+ *
+ * The "once" in the Issue's acceptance, and it is keyed on the *facts* rather
+ * than on the session name so the two ways this can recur read correctly:
+ *
+ *  - the same pane asked about again by the same server — adopted a second
+ *    time, or sent to a hundred times more — is the same sentence, and is
+ *    dropped;
+ *  - a pane that moves to a different mismatch — a third server, or the one it
+ *    was pointing at coming back — is a different sentence and is told.
+ *
+ * Process-lifetime, like every other in-memory notification ledger here: a
+ * server that restarts is a server whose port may have changed, and re-asking
+ * is cheaper than a stale answer.
+ */
+const reportedStaleHookUrls = new Set();
+/**
+ * Report a session whose hook URL names another server, at most once.
+ *
+ * Fire-and-forget through the same one窓口 as {@link reportSessionStartFailure},
+ * and deferred behind `await import()` for the same reason: this file is loaded
+ * by `./base`, which every tool module loads, and `push/failure-push-notifier`
+ * pulls the database and `web-push` behind it.
+ *
+ * @param report - The pane, the port it posts to, and the port that is listening
+ */
+function reportStaleHookUrl(report) {
+    const key = [
+        report.worktreeId,
+        report.instanceId ?? report.cliToolId,
+        report.sessionPort,
+        report.serverPort,
+    ].join(':');
+    if (reportedStaleHookUrls.has(key))
+        return;
+    reportedStaleHookUrls.add(key);
+    void Promise.resolve().then(() => __importStar(require('../push/failure-push-notifier'))).then(({ notifyStaleHookUrlPush }) => notifyStaleHookUrlPush(report))
+        .catch(() => { });
+}
+/**
+ * Forget every stale-hook-URL report made so far (Issue #2429).
+ *
+ * Test-only, and named so: the ledger above is process-lifetime state, and a
+ * suite that asserts "the second call says nothing" needs the first call to be
+ * the first one.
+ */
+function resetStaleHookUrlReportsForTest() {
+    reportedStaleHookUrls.clear();
+}
 /**
  * Refuse a start this tool cannot perform, reporting it exactly as a failed
  * launch does (Issue #2022).

package/dist/server/src/lib/db/agent-instances-db.js

@@ -12,7 +12,7 @@
  * exceed it throw AgentInstanceLimitError.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InvalidAgentInstanceError = exports.AgentInstanceLimitError = void 0;
+exports.SessionNoteTooLongError = exports.MAX_SESSION_NOTE_LENGTH = exports.InvalidAgentInstanceError = exports.AgentInstanceLimitError = void 0;
 exports.getAgentInstances = getAgentInstances;
 exports.getAgentInstance = getAgentInstance;
 exports.resolveInstanceCliTool = resolveInstanceCliTool;
@@ -24,6 +24,13 @@ exports.getOpencodeInstanceSettings = getOpencodeInstanceSettings;
 exports.getOpencodeInstanceSettingsByWorktree = getOpencodeInstanceSettingsByWorktree;
 exports.setOpencodeInstanceSettings = setOpencodeInstanceSettings;
 exports.pruneOpencodeInstanceSettings = pruneOpencodeInstanceSettings;
+exports.normalizeSessionNoteText = normalizeSessionNoteText;
+exports.sessionNoteLength = sessionNoteLength;
+exports.getSessionNote = getSessionNote;
+exports.getSessionNotesByWorktree = getSessionNotesByWorktree;
+exports.getAllSessionNotes = getAllSessionNotes;
+exports.setSessionNote = setSessionNote;
+exports.pruneSessionNotes = pruneSessionNotes;
 const opencode_instance_settings_1 = require("../../types/opencode-instance-settings");
 const types_1 = require("../../lib/cli-tools/types");
 /**
@@ -199,6 +206,13 @@ function setAgentInstances(db, worktreeId, instances) {
         // is a full replace, so an instance dropped from the roster would otherwise
         // leave its opencode settings behind for whoever next claimed that id.
         pruneOpencodeInstanceSettings(db, worktreeId, instances.map((instance) => instance.id));
+        // Issue #2427: the same rule for the session notes, and the same rule read
+        // the other way round — this prunes only the ids that LEFT the roster, so
+        // the note of every surviving instance outlives the delete/re-insert that
+        // renaming an alias or reordering the list performs. That survival is the
+        // Issue's third acceptance condition; a mutation that drops this call makes
+        // the note of a *removed* instance haunt the next instance to claim its id.
+        pruneSessionNotes(db, worktreeId, instances.map((instance) => instance.id));
         const insertStmt = db.prepare(`
       INSERT INTO agent_instances
         (worktree_id, instance_id, cli_tool_id, alias, sort_order, created_at)
@@ -251,6 +265,11 @@ function removeAgentInstance(db, worktreeId, instanceId) {
     // it was configured to launch opencode with is gone with it.
     db.prepare(`
     DELETE FROM opencode_instance_settings WHERE worktree_id = ? AND instance_id = ?
+  `).run(worktreeId, instanceId);
+    // Issue #2427: and the memo written about it. A note names a session; the
+    // session is gone.
+    db.prepare(`
+    DELETE FROM session_notes WHERE worktree_id = ? AND instance_id = ?
   `).run(worktreeId, instanceId);
     return result.changes > 0;
 }
@@ -369,3 +388,196 @@ function pruneOpencodeInstanceSettings(db, worktreeId, keepInstanceIds) {
     WHERE worktree_id = ? AND instance_id NOT IN (${placeholders})
   `).run(worktreeId, ...keepInstanceIds).changes;
 }
+// ============================================================================
+// Session notes (Issue #2427). Appended after the opencode block for the same
+// reason that one was appended after the roster CRUD: everything below is
+// additive and touches no export above it, so `AgentInstance` — which is the
+// roster PATCH's INPUT shape as much as its output — is unchanged, and so is
+// every resolution path that reads it.
+//
+// A note is a memo a human reads. It is NOT an alias: since Issue #2376
+// `--instance レビュー担当` resolves through `agent_instances.alias`, so an alias
+// decides where a `send` lands. Nothing in this section is read by
+// `resolveInstanceCliTool` or by `/resolve-target`, and that is the whole reason
+// the two are stored apart.
+// ============================================================================
+/**
+ * Longest note this server will store, in code points (Issue #2427).
+ *
+ * One line beside a session title, so the bound is about what can be READ in a
+ * split header rather than about storage. Code points rather than UTF-16 units
+ * because the operator counts characters: an emoji is one character to whoever
+ * typed it and two to `String.prototype.length`, and a limit that charges two
+ * for one is a limit that cannot be explained.
+ *
+ * The client mirrors it as the input's `maxLength` (`SESSION_NOTE_MAX_LENGTH` in
+ * `TerminalSplitPane`), which is a convenience; THIS is the enforcement, because
+ * the route is reachable without the UI.
+ */
+exports.MAX_SESSION_NOTE_LENGTH = 100;
+/** Thrown when a note is longer than {@link MAX_SESSION_NOTE_LENGTH}. */
+class SessionNoteTooLongError extends Error {
+    constructor(limit = exports.MAX_SESSION_NOTE_LENGTH) {
+        super(`Session note exceeds ${limit} characters`);
+        this.name = 'SessionNoteTooLongError';
+    }
+}
+exports.SessionNoteTooLongError = SessionNoteTooLongError;
+/** Below this code point (plus DEL) a character cannot be typed into a memo. */
+const FIRST_PRINTABLE_CODE_POINT = 0x20;
+const DELETE_CODE_POINT = 0x7f;
+/**
+ * Fold a submitted note into the one line that is actually stored.
+ *
+ * Control characters — a pasted newline above all, which is how a multi-line
+ * clipboard reaches a one-line input — become spaces rather than being rejected:
+ * the operator pasting two lines of a commit message means the text, not the
+ * line break, and a refusal there would read as a bug. Runs of whitespace
+ * collapse and the ends are trimmed, so the stored value is what the header will
+ * render, and the length limit is measured against that rather than against
+ * padding.
+ *
+ * Iterating code points rather than matching a control-character class keeps the
+ * repository's own `scripts/check-control-chars.mjs` discipline — the escape
+ * sequence for a control character is still a control character to a reviewer
+ * skimming the line — and gets surrogate pairs right for free.
+ *
+ * Returns `''` for anything that folds away to nothing, which is the caller's
+ * signal to DELETE rather than to store.
+ */
+function normalizeSessionNoteText(raw) {
+    if (typeof raw !== 'string')
+        return '';
+    let folded = '';
+    for (const char of raw) {
+        const code = char.codePointAt(0) ?? 0;
+        folded += code < FIRST_PRINTABLE_CODE_POINT || code === DELETE_CODE_POINT ? ' ' : char;
+    }
+    return folded.replace(/\s+/g, ' ').trim();
+}
+/** How long a normalized note is, counted the way the limit is defined. */
+function sessionNoteLength(text) {
+    return Array.from(text).length;
+}
+/**
+ * The note kept beside one session, or null when there is none.
+ *
+ * @param db - Database instance
+ * @param worktreeId - Worktree ID
+ * @param instanceId - Instance ID (the primary instance uses the CLI tool id)
+ */
+function getSessionNote(db, worktreeId, instanceId) {
+    const row = db.prepare(`
+    SELECT instance_id, note, updated_at
+    FROM session_notes
+    WHERE worktree_id = ? AND instance_id = ?
+  `).get(worktreeId, instanceId);
+    return row ? { text: row.note, updatedAt: row.updated_at } : null;
+}
+/**
+ * Every note kept for a worktree, keyed by instance id.
+ *
+ * One statement rather than one per roster entry: the split header asks for the
+ * whole worktree at once, and an instance with no row is simply absent from the
+ * result — which is also how the UI decides to render nothing.
+ */
+function getSessionNotesByWorktree(db, worktreeId) {
+    const rows = db.prepare(`
+    SELECT instance_id, note, updated_at
+    FROM session_notes
+    WHERE worktree_id = ?
+  `).all(worktreeId);
+    const notes = {};
+    for (const row of rows) {
+        notes[row.instance_id] = { text: row.note, updatedAt: row.updated_at };
+    }
+    return notes;
+}
+/**
+ * Every note on the server, grouped by worktree id then instance id.
+ *
+ * `GET /api/worktrees` composes one payload for every worktree at once and is
+ * polled by every open client, so it reads this table ONCE rather than issuing a
+ * point query per row of the list. The whole table is a handful of rows per
+ * worktree by construction (at most `MAX_AGENT_INSTANCES`, and only for the
+ * sessions somebody annotated), so grouping in JS costs less than the round
+ * trips it replaces — and it is immune to SQLite's bound-parameter ceiling,
+ * which an `IN (...)` over every worktree id would not be.
+ */
+function getAllSessionNotes(db) {
+    const rows = db.prepare(`
+    SELECT worktree_id, instance_id, note, updated_at
+    FROM session_notes
+  `).all();
+    const byWorktree = {};
+    for (const row of rows) {
+        const notes = byWorktree[row.worktree_id] ?? (byWorktree[row.worktree_id] = {});
+        notes[row.instance_id] = { text: row.note, updatedAt: row.updated_at };
+    }
+    return byWorktree;
+}
+/**
+ * Write one session's note, or clear it.
+ *
+ * A note that normalizes to nothing DELETES the row instead of storing `''`, for
+ * the reason {@link setOpencodeInstanceSettings} deletes an all-unset write: the
+ * two states are indistinguishable to every reader, and absence is what lets the
+ * split header render nothing at all rather than an empty chip.
+ *
+ * @param at - Epoch ms recorded as the note's time; injectable so a test can
+ *   assert the displayed timestamp without racing the clock
+ * @returns The stored note, or null when the note was cleared
+ * @throws InvalidAgentInstanceError when the instance id is not a valid one
+ * @throws SessionNoteTooLongError when the note is over the limit
+ */
+function setSessionNote(db, worktreeId, instanceId, text, at = Date.now()) {
+    if (!(0, types_1.isValidInstanceId)(instanceId)) {
+        throw new InvalidAgentInstanceError(`Invalid instance id: ${String(instanceId)}`);
+    }
+    const normalized = normalizeSessionNoteText(text);
+    if (sessionNoteLength(normalized) > exports.MAX_SESSION_NOTE_LENGTH) {
+        throw new SessionNoteTooLongError();
+    }
+    if (normalized.length === 0) {
+        db.prepare(`
+      DELETE FROM session_notes WHERE worktree_id = ? AND instance_id = ?
+    `).run(worktreeId, instanceId);
+        return null;
+    }
+    db.prepare(`
+    INSERT INTO session_notes (worktree_id, instance_id, note, updated_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(worktree_id, instance_id) DO UPDATE SET
+      note = excluded.note,
+      updated_at = excluded.updated_at
+  `).run(worktreeId, instanceId, normalized, at);
+    return { text: normalized, updatedAt: at };
+}
+/**
+ * Drop the notes of instances that are no longer in the roster.
+ *
+ * Called by {@link setAgentInstances} and {@link removeAgentInstance} for the
+ * reason {@link pruneOpencodeInstanceSettings} is: `session_notes` is keyed on an
+ * instance id and nothing else would ever remove a row for an instance the
+ * operator deleted, so re-adding an instance under the same id would inherit a
+ * memo written about a session that no longer exists as if it were its own.
+ *
+ * The counterpart matters just as much: this prunes the ids that are GONE and
+ * leaves every surviving id alone, which is what makes a note survive the roster
+ * replace that an alias edit performs.
+ *
+ * @param keepInstanceIds - The ids that survive; every other row is deleted
+ * @returns How many rows were removed
+ */
+function pruneSessionNotes(db, worktreeId, keepInstanceIds) {
+    if (keepInstanceIds.length === 0) {
+        return db.prepare(`
+      DELETE FROM session_notes WHERE worktree_id = ?
+    `).run(worktreeId).changes;
+    }
+    const placeholders = keepInstanceIds.map(() => '?').join(', ');
+    return db.prepare(`
+    DELETE FROM session_notes
+    WHERE worktree_id = ? AND instance_id NOT IN (${placeholders})
+  `).run(worktreeId, ...keepInstanceIds).changes;
+}

package/dist/server/src/lib/db/migrations/index.js

@@ -44,6 +44,7 @@ const v57_push_subscription_defaults_notice_1 = require("./v57-push-subscription
 const v58_agent_session_costs_1 = require("./v58-agent-session-costs");
 const v59_opencode_instance_settings_1 = require("./v59-opencode-instance-settings");
 const v60_session_relays_1 = require("./v60-session-relays");
+const v61_session_notes_1 = require("./v61-session-notes");
 /**
  * Complete ordered list of all migrations.
  * Used internally by the barrel file (db-migrations.ts); NOT exported from the barrel (DR2-004).
@@ -91,4 +92,5 @@ exports.migrations = [
     ...v58_agent_session_costs_1.v58_migrations,
     ...v59_opencode_instance_settings_1.v59_migrations,
     ...v60_session_relays_1.v60_migrations,
+    ...v61_session_notes_1.v61_migrations,
 ];