commandmate 0.27.1 → 0.28.0

package/dist/server/src/lib/hooks/sources/opencode/launch-settings.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * The opencode settings one instance is launched and prompted with (#2048).
+ *
+ * Issue #2048 adds three per-instance settings — persona, model and variant.
+ * The database holds them (`opencode_instance_settings`, migration v59) because
+ * they belong to a worktree and have to follow its renames and its deletion.
+ * This module is the **launcher's copy** of the same values, and it exists for
+ * the reason `../../../session/opencode-session-store` spells out for the resume
+ * flag, applied to a second value:
+ *
+ *  1. **The reader is the launcher.** `prepareOpencodeLaunch` builds a command
+ *     line synchronously, from an `AgentLaunchContext` that five other tools
+ *     share and that has nowhere to hand settings through; and
+ *     `src/lib/cli-tools/opencode.ts` is deliberately outside `better-sqlite3`'s
+ *     import graph. Reading the row here would either pull that graph into the
+ *     launcher or make the launch path `await` a dynamic import — measured, that
+ *     second option is not free: the three launch tests in
+ *     `tests/unit/cli-tools/opencode.test.ts` drive `startSession` under fake
+ *     timers, and a dynamic import does not resolve on the timer queue, so the
+ *     command line was never composed at all.
+ *  2. **It is read on the send path too**, once per prompt, where an extra
+ *     database round trip would sit in front of the operator's message.
+ *
+ * So: same shape as `./ports`, same `~/.commandmate` directory, same "never
+ * throws, a bad file means none" contract. `GET`/`PUT
+ * /api/worktrees/:id/instances/opencode` writes both — the row and this mirror —
+ * and the `GET` reconciles the mirror from the row, so opening the settings pane
+ * repairs a mirror that a worktree rename or a restored database left stale.
+ * The database is the source of truth; this is a cache with a file behind it.
+ *
+ * ## What the settings may and may not do
+ *
+ * Measured on opencode 1.18.22 (`docs/design/opencode-server-live-verification.md`
+ * §20): the TUI takes `--agent` and `-m provider/model` and has **no
+ * `--variant`** — passing one makes opencode print its usage and exit, so the
+ * pane would come up empty. {@link opencodeLaunchArguments} therefore never
+ * emits a variant, and the variant travels on the prompt instead
+ * ({@link opencodePromptSelection}), which is the one channel measured to apply
+ * it.
+ *
+ * @module lib/hooks/sources/opencode/launch-settings
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOpencodeLaunchSettingsFilePath = getOpencodeLaunchSettingsFilePath;
+exports.readPersistedOpencodeLaunchSettings = readPersistedOpencodeLaunchSettings;
+exports.getOpencodeLaunchSettings = getOpencodeLaunchSettings;
+exports.rememberOpencodeLaunchSettings = rememberOpencodeLaunchSettings;
+exports.forgetOpencodeLaunchSettings = forgetOpencodeLaunchSettings;
+exports.resetOpencodeLaunchSettings = resetOpencodeLaunchSettings;
+exports.opencodeLaunchArguments = opencodeLaunchArguments;
+exports.opencodePromptSelection = opencodePromptSelection;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const safe_directory_1 = require("../../../../config/safe-directory");
+const auto_yes_state_1 = require("../../../../lib/auto-yes-state");
+const logger_1 = require("../../../../lib/logger");
+const hook_settings_generator_1 = require("../../../../lib/hooks/hook-settings-generator");
+const opencode_instance_settings_1 = require("../../../../types/opencode-instance-settings");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/launch-settings');
+const cache = (globalThis.__opencodeLaunchSettings ??= new Map());
+function keyOf(target) {
+    return (0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId);
+}
+/**
+ * Where the mirror lives. `CM_OPENCODE_LAUNCH_SETTINGS_FILE` overrides.
+ *
+ * Guarded exactly as `getOpencodePortFilePath` is (Issue #1774): the write below
+ * creates this file's directory with a recursive mkdir, and for a path inside
+ * `/proc`, `/sys` or `/dev` that call does not throw — it spins the event loop
+ * forever, so the `try/catch` around it never runs. `resolveSafeDirectory`
+ * refuses such an override and hands back the default.
+ */
+function getOpencodeLaunchSettingsFilePath() {
+    const fallback = (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'opencode-launch-settings.json');
+    return (0, safe_directory_1.resolveSafeDirectory)(process.env.CM_OPENCODE_LAUNCH_SETTINGS_FILE, fallback, 'CM_OPENCODE_LAUNCH_SETTINGS_FILE');
+}
+/** Read the mirror. Never throws — a bad file means "nothing is configured". */
+function readPersistedOpencodeLaunchSettings() {
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(getOpencodeLaunchSettingsFilePath(), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        const result = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            // Re-validated on the way out as well as in: this file is writable by
+            // anything running as the user, and `agent` / `model` end up on a shell
+            // command line.
+            const settings = (0, opencode_instance_settings_1.normalizeOpencodeInstanceSettings)(value);
+            if ((0, opencode_instance_settings_1.hasOpencodeInstanceSettings)(settings))
+                result[key] = settings;
+        }
+        return result;
+    }
+    catch {
+        // Absent on a first run, unreadable if somebody edited it. Both mean the
+        // same thing to a caller: nothing is configured.
+        return {};
+    }
+}
+/** Write the mirror back. Never throws — losing it costs one launch's flags. */
+function writePersistedOpencodeLaunchSettings(all) {
+    const path = getOpencodeLaunchSettingsFilePath();
+    try {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true });
+        (0, fs_1.writeFileSync)(path, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch (error) {
+        logger.warn('opencode-launch-settings-write-failed', {
+            path,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * The settings this instance should launch with.
+ *
+ * **Synchronous, and that is the requirement** — {@link prepareOpencodeLaunch}
+ * calls it while composing a command line. Memory first, then the file, then
+ * all-unset, which is the state every instance is in until somebody opens the
+ * settings pane.
+ */
+function getOpencodeLaunchSettings(target) {
+    const key = keyOf(target);
+    const live = cache.get(key);
+    if (live)
+        return live;
+    const persisted = readPersistedOpencodeLaunchSettings()[key];
+    if (!persisted)
+        return { ...opencode_instance_settings_1.EMPTY_OPENCODE_INSTANCE_SETTINGS };
+    cache.set(key, persisted);
+    return persisted;
+}
+/**
+ * Record what this instance should launch with, in memory and on disk.
+ *
+ * An all-unset write **removes** the entry rather than storing four nulls: the
+ * two are indistinguishable to every reader, and the removal keeps the file to
+ * the instances somebody actually configured.
+ *
+ * @returns The normalised settings that were stored
+ */
+function rememberOpencodeLaunchSettings(target, settings) {
+    const key = keyOf(target);
+    const normalized = (0, opencode_instance_settings_1.normalizeOpencodeInstanceSettings)(settings ?? {});
+    const all = readPersistedOpencodeLaunchSettings();
+    if (!(0, opencode_instance_settings_1.hasOpencodeInstanceSettings)(normalized)) {
+        cache.delete(key);
+        if (key in all) {
+            delete all[key];
+            writePersistedOpencodeLaunchSettings(all);
+        }
+        return normalized;
+    }
+    cache.set(key, normalized);
+    all[key] = normalized;
+    writePersistedOpencodeLaunchSettings(all);
+    return normalized;
+}
+/** Drop one instance's settings from memory and disk. */
+function forgetOpencodeLaunchSettings(target) {
+    rememberOpencodeLaunchSettings(target, opencode_instance_settings_1.EMPTY_OPENCODE_INSTANCE_SETTINGS);
+}
+/** Drop every in-memory entry. Test seam; production only ever writes or forgets one. */
+function resetOpencodeLaunchSettings() {
+    cache.clear();
+}
+/**
+ * The flags these settings add to an opencode launch line, or `''`.
+ *
+ * **`--variant` is deliberately absent and must stay absent.** The TUI does not
+ * declare it (`opencode --help`, 1.18.22): yargs answers an unknown option by
+ * printing the usage banner and exiting, so a launch line carrying it starts no
+ * agent at all — measured twice, once inside tmux and once directly (§20.3).
+ * `opencode run --variant` does exist, which is exactly the trap: the flag is
+ * real, on a different subcommand.
+ *
+ * Both values are shell-quoted even though {@link normalizeOpencodeInstanceSettings}
+ * has already refused everything with a metacharacter in it. The quoting is the
+ * second of two independent guards, and it is the cheaper one to keep.
+ *
+ * @param settings - The instance's settings; all-unset yields `''`
+ * @returns A string starting with a space, or `''` when nothing is configured
+ */
+function opencodeLaunchArguments(settings) {
+    const normalized = (0, opencode_instance_settings_1.normalizeOpencodeInstanceSettings)(settings ?? {});
+    const parts = [];
+    if (normalized.agent)
+        parts.push(`--agent ${(0, hook_settings_generator_1.shellQuote)(normalized.agent)}`);
+    const model = (0, opencode_instance_settings_1.opencodeModelReference)(normalized);
+    if (model)
+        parts.push(`--model ${(0, hook_settings_generator_1.shellQuote)(model)}`);
+    return parts.length > 0 ? ` ${parts.join(' ')}` : '';
+}
+/**
+ * The `prompt_async` keys these settings contribute, or null.
+ *
+ * Null — send nothing extra — when nothing is configured, so an unconfigured
+ * instance's request body is byte-identical to the pre-#2048 one. That matters
+ * more than it looks: a body with **no** `agent` runs the turn as `build` even
+ * on a pane launched `--agent plan` (§20.5), so the choice between "omit" and
+ * "send" is a behavioural one and the omission is only correct while the
+ * operator has expressed no preference.
+ *
+ * The model is sent alongside the variant rather than left to the launch flag
+ * because the two have to agree: a variant names an entry in one model's own
+ * `variants` map, and sending `high` against whichever model the pane happens to
+ * be on would be asserting something about a model the operator did not choose.
+ */
+function opencodePromptSelection(settings) {
+    const normalized = (0, opencode_instance_settings_1.normalizeOpencodeInstanceSettings)(settings ?? {});
+    const selection = {};
+    if (normalized.agent)
+        selection.agent = normalized.agent;
+    if (normalized.providerId && normalized.modelId) {
+        selection.model = { providerID: normalized.providerId, modelID: normalized.modelId };
+    }
+    if (normalized.variant)
+        selection.variant = normalized.variant;
+    return Object.keys(selection).length > 0 ? selection : null;
+}

package/dist/server/src/lib/hooks/sources/opencode/mappers.js

@@ -37,6 +37,7 @@ exports.OPENCODE_MAPPERS = exports.OPENCODE_ERROR_DETAIL = exports.OPENCODE_PERM
 exports.frameProperties = frameProperties;
 exports.frameSessionId = frameSessionId;
 exports.frameModel = frameModel;
+exports.frameVariant = frameVariant;
 exports.partToolName = partToolName;
 exports.partCallId = partCallId;
 exports.repliedPermissionId = repliedPermissionId;
@@ -105,6 +106,36 @@ function frameModel(payload) {
         return null;
     return (0, event_mapper_1.readNestedString)(info, ['model', 'modelID']) ?? (0, event_mapper_1.readNestedString)(info, ['model', 'id']);
 }
+/**
+ * The model **variant** this frame reports, or null (Issue #2048).
+ *
+ * Two spellings, for the same reason {@link frameModel} has two: the value sits
+ * in a different place on the two frames that carry it, and both were measured
+ * on 1.18.22 in an isolated `HOME`
+ * (`docs/design/opencode-server-live-verification.md` §20.4).
+ *
+ *  - `session.updated` -> `properties.info.model.variant`, because
+ *    `Session.model` is a `ModelRef` (`{ id, providerID, variant? }`);
+ *  - `message.updated` -> `properties.info.variant`, because `AssistantMessage`
+ *    declares it as a flat field of its own.
+ *
+ * **Absent is the ordinary answer, not an error.** The `variant` key is missing
+ * altogether from both frames when the session is on a model's default, and from
+ * the assistant message a turn opens with. `agent-event-state` latches this
+ * rather than assigning it, which is what makes a frame without one mean
+ * "unchanged" instead of "cleared".
+ *
+ * opencode calls it a variant; CommandMate publishes it as the reasoning
+ * *effort*, which is what it is — the catalogue entry for `high` is literally
+ * `{ effort: "high" }` (§20.1) — and is the field every other tool's level is
+ * already shown in.
+ */
+function frameVariant(payload) {
+    const info = frameProperties(payload).info;
+    if (!(0, event_mapper_1.isPlainObject)(info))
+        return null;
+    return (0, event_mapper_1.readNestedString)(info, ['model', 'variant']) ?? (0, event_mapper_1.readNestedString)(info, ['variant']);
+}
 /** `properties.part.state.status` — `pending` / `running` / `completed` / `error`. */
 function partStatus(payload) {
     return (0, event_mapper_1.readNestedString)(frameProperties(payload), ['part', 'state', 'status']);

package/dist/server/src/lib/hooks/sources/opencode/payloads.js

@@ -37,6 +37,7 @@ exports.resetOpencodeToolCalls = resetOpencodeToolCalls;
 exports.parseOpencodePermissionRequest = parseOpencodePermissionRequest;
 exports.parseOpencodeQuestion = parseOpencodeQuestion;
 exports.toOpencodePendingPermission = toOpencodePendingPermission;
+exports.readOpencodePermissionSubject = readOpencodePermissionSubject;
 exports.toOpencodePendingQuestion = toOpencodePendingQuestion;
 const ask_user_question_payload_1 = require("../../../../lib/hooks/ask-user-question-payload");
 const event_mapper_1 = require("../event-mapper");
@@ -171,6 +172,50 @@ function toOpencodePendingPermission(payload, askedAt) {
         askedAt,
     };
 }
+/**
+ * What an approval is ABOUT, for the surfaces that have to show it
+ * (Issue #2031).
+ *
+ * Read back off {@link toOpencodePendingPermission} rather than re-parsed from
+ * the frame, and that is the point rather than an economy: the pending decision
+ * is what the adjudicator judges and what `Allow always` is delivered against,
+ * so a panel describing a *differently* parsed view of the same frame could
+ * tell the user one thing while the verdict did another. One parse, two
+ * readers.
+ *
+ * The tool name is the `message.part.updated` correlation
+ * ({@link lookupOpencodeToolName}) with the approval kind behind it, because
+ * `permission.asked` carries no tool name of its own (#1758 §5.4).
+ *
+ * `patterns` comes back as `toolInput.patterns`, which is NOT always the
+ * frame's top-level `properties.patterns`: `parseOpencodePermissionRequest`
+ * spreads `metadata` last, so an approval whose metadata carries its own
+ * `patterns` shadows the outer list. That is the behaviour to keep, not a wart
+ * to route around — the shadowed list is what the adjudicator judged and what
+ * `Allow always` is delivered against, and a panel showing the other one would
+ * describe a verdict nobody is about to take. Pinned in
+ * `opencode-permission-subject-2031`.
+ *
+ * `patterns` is left unbounded here on purpose. It is bounded where it is
+ * *retained* — `boundDecisionPatterns` in `lib/session/provisional-turn`,
+ * beside the bounds on `message` and `toolName` — so there is one place the
+ * footprint of a stored decision is decided, and a second bound here would be a
+ * second number to keep in step with it.
+ *
+ * @param payload - A `permission.asked` frame or a `GET /permission` entry
+ * @param askedAt - Epoch ms
+ * @returns The subject, or null when this is not an approval this server reads
+ */
+function readOpencodePermissionSubject(payload, askedAt) {
+    const pending = toOpencodePendingPermission(payload, askedAt);
+    if (!pending || pending.subject.kind !== 'permission')
+        return null;
+    const patterns = pending.subject.toolInput.patterns;
+    return {
+        toolName: pending.subject.toolName,
+        patterns: Array.isArray(patterns) ? patterns : [],
+    };
+}
 /** Turn a question into a {@link PendingDecision}. */
 function toOpencodePendingQuestion(payload, askedAt) {
     const properties = unwrap(payload);

package/dist/server/src/lib/hooks/sources/opencode/ports.js

@@ -47,6 +47,7 @@ exports.OPENCODE_PORT_PROBE_HOSTS = exports.OPENCODE_PORT_RANGE = void 0;
 exports.getOpencodePortFilePath = getOpencodePortFilePath;
 exports.readPersistedOpencodePorts = readPersistedOpencodePorts;
 exports.getAssignedOpencodePort = getAssignedOpencodePort;
+exports.getAssignedOpencodeWorktreePath = getAssignedOpencodeWorktreePath;
 exports.rememberOpencodePort = rememberOpencodePort;
 exports.forgetOpencodePort = forgetOpencodePort;
 exports.isPortFree = isPortFree;
@@ -138,6 +139,21 @@ function writePersistedOpencodePorts(all) {
 function getAssignedOpencodePort(target) {
     return assignments.get(keyOf(target))?.port ?? null;
 }
+/**
+ * The worktree an assignment was made for, in this process. Null when there is
+ * none (Issue #2038).
+ *
+ * Exists because `killSession` is handed `(worktreeId, instanceId)` and no
+ * path, and Issue #2038 has to answer "is the session opencode is about to
+ * forget rooted in THIS worktree?" at exactly that moment. The assignment is
+ * already the record of "this instance is running there" — `recoverOpencodePort`
+ * trusts the same field — so reading it is cheaper and more honest than
+ * re-deriving the path from the database inside a launcher that is deliberately
+ * kept out of the database's import graph.
+ */
+function getAssignedOpencodeWorktreePath(target) {
+    return assignments.get(keyOf(target))?.worktreePath ?? null;
+}
 /** Record an assignment in memory and on disk. */
 function rememberOpencodePort(target, port, worktreePath, at = Date.now()) {
     const key = keyOf(target);

package/dist/server/src/lib/hooks/sources/opencode/push.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * The phone notifications opencode's own stream raises (Issue #2045).
+ *
+ * ## Why opencode gets a producer of its own
+ *
+ * Every other tool's prompt notification is raised from the *waiting edge*
+ * (`push/waiting-push-notifier`), and that edge is only ever observed by a
+ * status probe — `worktree-status-helper` on a list/detail API read, or
+ * `response-checker` while the poller happens to be running. So for the five
+ * scraped tools a wait notifies when somebody is looking, and the phone is the
+ * consolation prize for when nobody is.
+ *
+ * opencode is the one tool where that trade is unaffordable. Measured on
+ * 1.18.22 (`docs/design/opencode-server-live-verification.md` §17): after
+ * `question.asked` the session stays `busy` and **no `session.idle` ever
+ * arrives** — `GET /session/status` still read `{"…":{"type":"busy"}}` twenty
+ * seconds later, with nothing else on the stream. Nothing in this repository
+ * answers an opencode question either (`grep` for a question-reply producer
+ * finds only the manual `respond` path), so Auto-Yes cannot end the wait and
+ * the turn is stopped until a human acts. A notification that waits for a page
+ * view is exactly the wrong shape for that.
+ *
+ * ## Closed to opencode, on purpose
+ *
+ * The Issue's constraint, and it is the reason this is a module in
+ * `sources/opencode/` rather than a hook on `notification` / `error` in the
+ * shared receiver: the other five tools reach `recordAgentEvent` through
+ * `POST /api/hooks/agent-event`, which does not import this file, so their push
+ * counts cannot move. `tests/unit/hooks/sources/opencode-push-2045.test.ts`
+ * pins that as a test rather than as a comment.
+ *
+ * ## One notification per wait, across both producers
+ *
+ * The question push carries `waitingSince: <the frame's receivedAt>`, which
+ * routes it through `shouldSendWaitingPush` — the episode-scoped guard #1790
+ * built — keyed `${worktreeId}::${instanceId}`. That is the *same* key and the
+ * *same* value the waiting edge will later use, because
+ * `worktree-status-helper` opens the episode with
+ * `structuredSince = peekPromptWaiting().structured?.at`, and that `at` is the
+ * `receivedAt` this module is handed. So the status probe's own notification is
+ * suppressed as a repeat of this one, and the reader gets one card per wait
+ * however many producers saw it. Passing no `waitingSince` would have fallen
+ * back to the 30 s content hash, whose key is a different map — two cards.
+ *
+ * ## Nothing here throws
+ *
+ * The same contract `./ingest` declares, for the same reason: a notification is
+ * advisory and must never cost the event that raised it.
+ *
+ * @module lib/hooks/sources/opencode/push
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_INTERRUPT_ERROR_NAME = exports.OPENCODE_PUSH_EXCERPT_LENGTH = void 0;
+exports.notifyOpencodeQuestionPush = notifyOpencodeQuestionPush;
+exports.notifyOpencodeSessionErrorPush = notifyOpencodeSessionErrorPush;
+exports.notifyOpencodeUpdateAvailablePush = notifyOpencodeUpdateAvailablePush;
+const logger_1 = require("../../../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/push');
+/**
+ * How much of the question / error text the notification body carries.
+ *
+ * 80, from the Issue, and narrower than `push-sender`'s own 120 default: this
+ * is applied at the producer so the truncation is the one the Issue specifies
+ * rather than whatever the fan-out happens to default to. The re-truncation
+ * inside `buildPushPayload` is then a no-op.
+ */
+exports.OPENCODE_PUSH_EXCERPT_LENGTH = 80;
+/**
+ * The one `session.error` name that is not a failure (measured, §17).
+ *
+ * `MessageAbortedError` is what a `POST /session/:id/abort` produces — the user
+ * pressed Escape, or CommandMate itself aborted the turn. Pushing "the agent
+ * stopped with an error" for a stop the reader just asked for would report
+ * their own action back to them as a fault. §5.3.2 of the design note already
+ * establishes the same reading for `wait`.
+ *
+ * The other seven names in opencode 1.18.22's `session.error` union
+ * (`APIError`, `ProviderAuthError`, `UnknownError`, `MessageOutputLengthError`,
+ * `StructuredOutputError`, `ContextOverflowError`, `ContentFilterError`) all
+ * describe a turn that ended badly, so the default is to notify: a name nobody
+ * enumerated here fails towards telling the human rather than towards silence.
+ */
+exports.OPENCODE_INTERRUPT_ERROR_NAME = 'MessageAbortedError';
+/**
+ * The worktree's display name, for the notification title.
+ *
+ * Dynamic import for the reason `./ingest` documents at length: `../registry`
+ * statically imports `./source`, so anything this module's graph reaches
+ * eagerly would put `better-sqlite3` (and, through `@/lib/push`, `web-push`)
+ * into every import of `@/lib/hooks/sources`.
+ *
+ * Falls back to the id rather than dropping the notification — the same call
+ * `push/waiting-push-notifier` makes, and for the same reason: a database that
+ * cannot answer is a reason to send a less readable title, not a reason to
+ * leave the human waiting in silence.
+ */
+async function resolveWorktreeName(worktreeId) {
+    try {
+        const [{ getDbInstance }, { getWorktreeById }] = await Promise.all([
+            Promise.resolve().then(() => __importStar(require('../../../../lib/db/db-instance'))),
+            Promise.resolve().then(() => __importStar(require('../../../../lib/db'))),
+        ]);
+        return getWorktreeById(getDbInstance(), worktreeId)?.name ?? worktreeId;
+    }
+    catch {
+        return worktreeId;
+    }
+}
+/**
+ * `@/lib/push/push-sender`, reached by module path rather than through the
+ * `@/lib/push` barrel.
+ *
+ * The barrel's own comments give the reason: a suite that stubs `@/lib/push`
+ * wholesale would leave the very path it is guarding undefined. Both existing
+ * producers (`waiting-push-notifier`, `failure-push-notifier`) import the
+ * concrete module for that reason, and this one follows.
+ */
+async function loadPushSender() {
+    return Promise.resolve().then(() => __importStar(require('../../../../lib/push/push-sender')));
+}
+async function subjectOf(target, instanceId) {
+    return {
+        worktreeId: target.worktreeId,
+        worktreeName: await resolveWorktreeName(target.worktreeId),
+        instanceId,
+    };
+}
+/**
+ * Tell the human's phone that opencode is asking them a question.
+ *
+ * `kind: 'prompt'` — this is the acting bucket, and it is the truthful one: the
+ * turn does not continue until the question is answered.
+ *
+ * `waitingKind: 'prompt'` rather than `'menu'`, deliberately. The kind decides
+ * whether the body says "waiting for your reply" or "needs attention in the
+ * terminal", and an opencode question is answerable *from the app*: it arrives
+ * as structured choices (`recordAskUserQuestion` in `./ingest`), so the picker
+ * and `commandmate respond <n>` can both close it without a terminal.
+ *
+ * @param question - The question text, or null when the frame carried none
+ * @param askedAt - The frame's `receivedAt`; the wait's identity (see module doc)
+ */
+async function notifyOpencodeQuestionPush(target, instanceId, question, askedAt) {
+    try {
+        const { notifyPushSubscribers, buildExcerpt } = await loadPushSender();
+        const subject = await subjectOf(target, instanceId);
+        await notifyPushSubscribers({
+            ...subject,
+            kind: 'prompt',
+            // Both halves of "worktree / instance" the Issue asks for: the title is
+            // `${worktreeName} (${agentName})`, so naming the instance here is what
+            // tells two panes of the same worktree apart.
+            agentName: instanceId,
+            waitingKind: 'prompt',
+            waitingSince: askedAt,
+            excerpt: buildExcerpt(question ?? undefined, exports.OPENCODE_PUSH_EXCERPT_LENGTH),
+        }, 
+        // The frame's clock, not a fresh reading: `askedAt` is when the human
+        // became blocked, and it is what the card's timestamp should say.
+        askedAt);
+        logger.info('opencode-question-push-sent', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            hasQuestion: question !== null,
+        });
+    }
+    catch (error) {
+        logger.warn('opencode-question-push-failed', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Tell the human's phone that a turn ended in an error.
+ *
+ * `kind: 'failure'` (#2000), which shares the "you need to act" toggle with
+ * `prompt` but keeps its own Service Worker `tag`, so a failure never replaces
+ * the card for a question that is still open.
+ *
+ * The dedup content is the {@link FailureContext.signature}, not the excerpt:
+ * `error.data.message` for a retrying provider carries changing detail, while
+ * `(session, error name)` is the incident. Two *different* errors in one
+ * session therefore both notify, and a repeat of one does not.
+ *
+ * @param errorName - `properties.error.name`, or null
+ * @param message - The human-facing line `./ingest` already extracted
+ *   (`error.data.message`, falling back to `error.name`)
+ * @param sessionId - The opencode session the error belongs to, for the signature
+ */
+async function notifyOpencodeSessionErrorPush(target, instanceId, errorName, message, sessionId, at) {
+    if (errorName === exports.OPENCODE_INTERRUPT_ERROR_NAME) {
+        logger.info('opencode-error-push-skipped-interrupt', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            errorName,
+        });
+        return;
+    }
+    try {
+        const { notifyPushSubscribers, buildExcerpt } = await loadPushSender();
+        const subject = await subjectOf(target, instanceId);
+        await notifyPushSubscribers({
+            ...subject,
+            kind: 'failure',
+            agentName: instanceId,
+            excerpt: buildExcerpt(message ?? undefined, exports.OPENCODE_PUSH_EXCERPT_LENGTH),
+            failure: {
+                reason: 'agent-session-error',
+                signature: `opencode:session-error:${sessionId ?? 'unknown'}:${errorName ?? 'unknown'}`,
+            },
+        }, at);
+        logger.info('opencode-error-push-sent', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            errorName,
+            sessionId,
+        });
+    }
+    catch (error) {
+        logger.warn('opencode-error-push-failed', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Tell the human that a newer opencode exists.
+ *
+ * `kind: 'completion'` — the informational bucket. Nothing is blocked and
+ * nobody has to act, so this must not ride the toggle a waiting prompt and a
+ * failed run share; a reader who opted out of "for information" opted out of
+ * this too.
+ *
+ * The excerpt is the version rather than prose. It is never rendered — the body
+ * comes from `updateAvailable` — but `passesDedup` hashes it, so carrying the
+ * version there makes the fan-out's own 30 s guard key off *which* update this
+ * is instead of off an empty string it would share with a bare completion.
+ *
+ * Suppressing repeats is the caller's job (`./subscription` remembers the
+ * versions it has announced), not this module's: the frame carries **no
+ * `sessionID`** — measured against 1.18.22's `GET /doc`, where
+ * `EventInstallationUpdate-available.properties` is `{ version }` and nothing
+ * else — so "once per session" can only be answered by whoever holds the
+ * connection.
+ */
+async function notifyOpencodeUpdateAvailablePush(target, instanceId, version, at) {
+    try {
+        const { notifyPushSubscribers } = await loadPushSender();
+        const subject = await subjectOf(target, instanceId);
+        await notifyPushSubscribers({
+            ...subject,
+            kind: 'completion',
+            agentName: instanceId,
+            excerpt: version,
+            updateAvailable: { agent: instanceId, version },
+        }, at);
+        logger.info('opencode-update-push-sent', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            version,
+        });
+    }
+    catch (error) {
+        logger.warn('opencode-update-push-failed', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}