commandmate 0.42.1 → 0.43.0

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

@@ -0,0 +1,351 @@
+"use strict";
+/**
+ * Reading OpenCode V2's approvals and questions (Issue #2945, Epic #2370
+ * Phase 2).
+ *
+ * The v2 counterpart of `../opencode/payloads`: both shapes are parsed into
+ * the vocabulary the tool-independent layers already speak
+ * ({@link PermissionRequestPayload}, {@link AskUserQuestionSpec},
+ * {@link PendingDecision}), so the adjudicator, `agent-event-state`, the
+ * `/respond` route and `commandmate respond` need no v2 branch.
+ *
+ * ## Approvals (`permission.asked`, `Permission.Request`)
+ *
+ * Measured on 2.0.18 (#2370 Phase 0): `{id: "per_…", sessionID, action,
+ * resources, save, metadata: {files: [{file, patch, status, additions,
+ * deletions}]}, source}`. Unlike v1 the approval names what it is for — the
+ * `action` (`edit`, `shell`, …) — so there is no tool-call correlation table
+ * here. And it carries the diff, which is what the approval card shows
+ * ({@link describeOpencodeV2Permission}).
+ *
+ * ## Questions (`form.created`, `Form.Info`)
+ *
+ * `form.created` carries the form under `data.form` (measured on 2.0.18); the
+ * list endpoints answer it bare. Either way it is
+ * `{id: "frm_…", sessionID, title, metadata: {kind: "question"}, fields:
+ * [{key, title, description, type, options: [{value, label, description}],
+ * custom}]}`. One field is one question. A field is representable as a
+ * question with choices when it offers options (`string` with `options`,
+ * `multiselect`) or is a `boolean` (two synthesised choices); a form with any
+ * other visible field (a bare number, a free-text string, an external link) is
+ * not parsed, and the human answers it in the TUI. A form with several fields
+ * is parsed field by field, but `resolveStructuredQuestionAnswer` refuses a
+ * multi-question answer, so only a one-field form is answerable from a surface
+ * — the same bound v1's multi-question calls have.
+ *
+ * The answer goes back as `{answer: {<key>: <value>}}`, and the value is the
+ * option's `value`, not its label: {@link buildOpencodeV2FormAnswer} maps the
+ * labels a verdict carries back through the same form the question was read
+ * from.
+ *
+ * @module lib/hooks/sources/opencode-v2/payloads
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapOpencodeV2Payload = unwrapOpencodeV2Payload;
+exports.parseOpencodeV2PermissionRequest = parseOpencodeV2PermissionRequest;
+exports.toOpencodeV2PendingPermission = toOpencodeV2PendingPermission;
+exports.readOpencodeV2PermissionSubject = readOpencodeV2PermissionSubject;
+exports.stripOpencodeV2PatchHeaders = stripOpencodeV2PatchHeaders;
+exports.describeOpencodeV2Permission = describeOpencodeV2Permission;
+exports.parseOpencodeV2Form = parseOpencodeV2Form;
+exports.toOpencodeV2PendingQuestion = toOpencodeV2PendingQuestion;
+exports.buildOpencodeV2FormAnswer = buildOpencodeV2FormAnswer;
+const ask_user_question_payload_1 = require("../../../../lib/hooks/ask-user-question-payload");
+const event_mapper_1 = require("../event-mapper");
+/**
+ * The object an approval or a question lives in.
+ *
+ * Two callers hand this module two shapes: the SSE frame `{id, type, data}`,
+ * and the bare object the list endpoints return. Unwrapping here lets the
+ * list path reuse the live path's parsing.
+ */
+function unwrapOpencodeV2Payload(payload) {
+    if (typeof payload.type === 'string' && (0, event_mapper_1.isPlainObject)(payload.data)) {
+        // `form.created` nests the form one level further — `data.form` (measured
+        // on 2.0.18); `permission.asked` does not.
+        return (0, event_mapper_1.isPlainObject)(payload.data.form) ? payload.data.form : payload.data;
+    }
+    return payload;
+}
+function readStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+// =============================================================================
+// Approvals
+// =============================================================================
+/**
+ * Read a `permission.asked` frame, or an entry of `GET /api/permission/request`.
+ *
+ * @returns What the adjudicator judges, or null when this is not an approval
+ *   the server can address (no `per_…` id or no session) — which every caller
+ *   treats as "leave it for the human"
+ */
+function parseOpencodeV2PermissionRequest(payload) {
+    const data = unwrapOpencodeV2Payload(payload);
+    const permissionId = (0, event_mapper_1.readStringField)(data, 'id');
+    const sessionId = (0, event_mapper_1.readStringField)(data, 'sessionID');
+    // Both are in the reply URL: `/api/session/{sessionID}/permission/{id}/reply`.
+    if (!permissionId || !sessionId)
+        return null;
+    // A form shares nothing with an approval but the envelope; never judge one.
+    if (Array.isArray(data.fields))
+        return null;
+    const action = (0, event_mapper_1.readStringField)(data, 'action');
+    const metadata = (0, event_mapper_1.isPlainObject)(data.metadata) ? data.metadata : {};
+    return {
+        // The approval names its own kind (`edit`, `shell`, …); v1 had to borrow
+        // the tool name from a separate frame.
+        toolName: action ?? 'permission',
+        // `metadata` verbatim — a `shell` approval's command, an `edit`'s files and
+        // patches — plus what is being asked for. What the deny patterns see.
+        toolInput: {
+            action,
+            resources: readStringArray(data.resources),
+            ...metadata,
+        },
+        promptId: permissionId,
+        sessionId,
+        permissionMode: null,
+        // `save` is the rule `Always allow` would store. Recorded, never judged.
+        permissionSuggestions: Array.isArray(data.save) ? data.save : null,
+    };
+}
+/** Turn an approval into a {@link PendingDecision}. */
+function toOpencodeV2PendingPermission(payload, askedAt) {
+    const parsed = parseOpencodeV2PermissionRequest(payload);
+    if (!parsed || !parsed.promptId)
+        return null;
+    return {
+        kind: 'permission',
+        id: parsed.promptId,
+        conversationId: parsed.sessionId,
+        subject: { kind: 'permission', toolName: parsed.toolName, toolInput: parsed.toolInput },
+        raw: payload,
+        askedAt,
+    };
+}
+/**
+ * What an approval is about, for the approval card (Issue #2945 D1).
+ *
+ * `toolName` is the action and `patterns` is `save` — the rule `Always allow`
+ * would store, which is what the card shows beside that button (the same slot
+ * v1 fills from `patterns`, #2031). Null when the payload is not an approval.
+ */
+function readOpencodeV2PermissionSubject(payload) {
+    const parsed = parseOpencodeV2PermissionRequest(payload);
+    if (!parsed)
+        return null;
+    return {
+        toolName: parsed.toolName,
+        patterns: readStringArray(parsed.permissionSuggestions),
+    };
+}
+/**
+ * Lines of a unified diff that carry no change: the `Index:` / `====` banner
+ * and the `---` / `+++` file headers the card already names.
+ */
+const PATCH_HEADER_LINE = /^(Index: |={3,}$|--- |\+\+\+ )/;
+/** A patch with its file headers removed, trailing newline trimmed. */
+function stripOpencodeV2PatchHeaders(patch) {
+    return patch
+        .split('\n')
+        .filter((line) => !PATCH_HEADER_LINE.test(line))
+        .join('\n')
+        .replace(/\n+$/, '');
+}
+/**
+ * The approval card's text: what is asked for, then the diff (Issue #2945 D1).
+ *
+ * ```
+ * edit hello.txt
+ * @@ -0,0 +1,1 @@
+ * +hi
+ * ```
+ *
+ * The first line is the action and its resources; then, per file in
+ * `metadata.files`, the file name (when there is more than one) and its patch
+ * without the header lines. A `shell` approval, which carries a command rather
+ * than files, reads `shell <command>`. Unbounded here — the caller cuts it to
+ * the record's message bound, and a cut diff is still the head of the diff.
+ *
+ * @returns The text, or null when the payload is not an approval
+ */
+function describeOpencodeV2Permission(payload) {
+    const parsed = parseOpencodeV2PermissionRequest(payload);
+    if (!parsed)
+        return null;
+    const input = parsed.toolInput;
+    const subject = typeof input.command === 'string' && input.command !== ''
+        ? input.command
+        : readStringArray(input.resources).join(', ');
+    const lines = [subject === '' ? parsed.toolName : `${parsed.toolName} ${subject}`];
+    const files = Array.isArray(input.files) ? input.files.filter(event_mapper_1.isPlainObject) : [];
+    for (const file of files) {
+        const patch = typeof file.patch === 'string' ? stripOpencodeV2PatchHeaders(file.patch) : '';
+        if (patch === '')
+            continue;
+        if (files.length > 1 && typeof file.file === 'string')
+            lines.push(file.file);
+        lines.push(patch);
+    }
+    return lines.join('\n');
+}
+/**
+ * The two choices a `boolean` field is offered as. Untranslated for the reason
+ * the approval verdicts are: the label is also what `commandmate respond`
+ * accepts, and a locale-dependent word would make the same command work on one
+ * machine and not another.
+ */
+const BOOLEAN_FIELD_CHOICES = [
+    // eslint-disable-next-line no-restricted-syntax -- CLI answer vocabulary, not display text
+    { label: 'Yes', description: null, value: true },
+    // eslint-disable-next-line no-restricted-syntax -- CLI answer vocabulary, not display text
+    { label: 'No', description: null, value: false },
+];
+/** The label as `parseAskUserQuestionToolInput` keeps it, for matching back. */
+function normalizeLabel(label) {
+    return label.trim().slice(0, ask_user_question_payload_1.MAX_ASK_USER_QUESTION_LABEL_LENGTH);
+}
+function readFieldChoices(options) {
+    if (!Array.isArray(options) || options.length === 0)
+        return null;
+    const choices = [];
+    for (const option of options) {
+        if (!(0, event_mapper_1.isPlainObject)(option))
+            return null;
+        const value = (0, event_mapper_1.readStringField)(option, 'value');
+        const label = (0, event_mapper_1.readStringField)(option, 'label') ?? value;
+        if (value === null || label === null)
+            return null;
+        choices.push({ label, description: (0, event_mapper_1.readStringField)(option, 'description'), value });
+    }
+    return choices;
+}
+/**
+ * The form's visible fields as questions, or null when one of them cannot be
+ * offered as a choice (see the module comment).
+ */
+function readFormQuestionFields(form) {
+    if (!Array.isArray(form.fields))
+        return null;
+    const formTitle = (0, event_mapper_1.readStringField)(form, 'title');
+    const fields = [];
+    for (const raw of form.fields) {
+        if (!(0, event_mapper_1.isPlainObject)(raw))
+            return null;
+        if (raw.hidden === true)
+            continue;
+        const key = (0, event_mapper_1.readStringField)(raw, 'key');
+        if (key === null)
+            return null;
+        const type = (0, event_mapper_1.readStringField)(raw, 'type');
+        const choices = type === 'boolean' ? [...BOOLEAN_FIELD_CHOICES] : type === 'string' || type === 'multiselect'
+            ? readFieldChoices(raw.options)
+            : null;
+        if (choices === null)
+            return null;
+        // Measured on 2.0.18: the question tool puts the question in `description`
+        // (`Which colour do you like?`) and a heading in `title` (`Favourite colour`).
+        const question = (0, event_mapper_1.readStringField)(raw, 'description') ?? (0, event_mapper_1.readStringField)(raw, 'title') ?? formTitle;
+        if (question === null)
+            return null;
+        fields.push({
+            key,
+            question,
+            header: (0, event_mapper_1.readStringField)(raw, 'title') ?? formTitle,
+            multiSelect: type === 'multiselect',
+            custom: raw.custom === true && type !== 'boolean',
+            choices,
+        });
+    }
+    return fields.length > 0 ? fields : null;
+}
+/**
+ * Read a form (`form.created` data, or an entry of `GET …/form`) as a question.
+ *
+ * @returns The spec — `promptId` is the `frm_…` id — or null when the form is
+ *   not one a surface can offer choices for
+ */
+function parseOpencodeV2Form(payload) {
+    const form = unwrapOpencodeV2Payload(payload);
+    const formId = (0, event_mapper_1.readStringField)(form, 'id');
+    if (!formId)
+        return null;
+    const fields = readFormQuestionFields(form);
+    if (fields === null)
+        return null;
+    const questions = (0, ask_user_question_payload_1.parseAskUserQuestionToolInput)({
+        questions: fields.map((field) => ({
+            question: field.question,
+            header: field.header,
+            multiSelect: field.multiSelect,
+            options: field.choices.map((choice) => ({
+                label: choice.label,
+                ...(choice.description ? { description: choice.description } : {}),
+            })),
+        })),
+    });
+    if (questions === null)
+        return null;
+    // Issue #2951: a field that takes a typed answer says so, so the surfaces
+    // can offer an input for it. `questions` is `fields` one-to-one.
+    const withCustom = questions.map((entry, index) => fields[index]?.custom ? { ...entry, custom: true } : entry);
+    return { questions: withCustom, promptId: formId };
+}
+/** Turn a form into a {@link PendingDecision}; `raw` keeps the form for the reply. */
+function toOpencodeV2PendingQuestion(payload, askedAt) {
+    const form = unwrapOpencodeV2Payload(payload);
+    const spec = parseOpencodeV2Form(form);
+    if (!spec || !spec.promptId)
+        return null;
+    return {
+        kind: 'question',
+        id: spec.promptId,
+        conversationId: (0, event_mapper_1.readStringField)(form, 'sessionID'),
+        subject: { kind: 'question', spec },
+        raw: form,
+        askedAt,
+    };
+}
+/**
+ * The `answer` object a form reply carries, built from a verdict's `answers`
+ * (one array per question, in field order).
+ *
+ * Each entry is matched to the field's choices by label (then by value), and
+ * the choice's `value` is sent — `true` / `false` for a boolean. An entry that
+ * matches no choice is sent as typed only where the field accepts free text
+ * (`custom: true`); anywhere else the whole answer is refused, because the
+ * server would refuse it (`FormInvalidAnswerError`) and a partial answer is not
+ * the operator's.
+ *
+ * @returns The object, or null when the answer does not fit the form
+ */
+function buildOpencodeV2FormAnswer(form, answers) {
+    const fields = readFormQuestionFields(unwrapOpencodeV2Payload(form));
+    if (fields === null || answers.length !== fields.length)
+        return null;
+    const answer = {};
+    for (const [index, field] of fields.entries()) {
+        const values = [];
+        for (const given of answers[index]) {
+            const wanted = normalizeLabel(given);
+            const choice = field.choices.find((candidate) => normalizeLabel(candidate.label) === wanted) ??
+                field.choices.find((candidate) => candidate.value === given);
+            if (choice)
+                values.push(choice.value);
+            else if (field.custom && given.trim() !== '')
+                values.push(given.trim());
+            else
+                return null;
+        }
+        if (field.multiSelect) {
+            answer[field.key] = values.map(String);
+        }
+        else {
+            if (values.length !== 1)
+                return null;
+            answer[field.key] = values[0];
+        }
+    }
+    return answer;
+}

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

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * Per-instance port assignment for OpenCode V2 servers (Issue #2934, D4).
+ *
+ * The same idea as v1's `../opencode/ports` — a deterministic starting point per
+ * instance, the first free port from there, an in-memory map for the running
+ * process and a file so a restarted CommandMate can find a server that outlived
+ * it — but its own range and its own file, so v1 is not touched:
+ *
+ *  - range {@link OPENCODE_V2_PORT_RANGE} (4300–4399) does not overlap v1's
+ *    `OPENCODE_PORT_RANGE` (4200–4299). A v1 and a v2 instance of the same
+ *    worktree therefore can never be handed the same port, whatever their
+ *    hashes say;
+ *  - the file is `ports.json` inside the OpenCode V2 state directory
+ *    (`~/.commandmate/opencode-v2/`), next to the password files.
+ *
+ * The bind probe is v1's {@link isPortFree}, imported rather than copied: it is
+ * a pure question about the machine ("can something bind here on every
+ * address?") and has nothing v1-specific in it.
+ *
+ * @module lib/hooks/sources/opencode-v2/ports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_V2_PORT_FILE_NAME = exports.OPENCODE_V2_PORT_RANGE = void 0;
+exports.getOpencodeV2PortFilePath = getOpencodeV2PortFilePath;
+exports.readPersistedOpencodeV2Ports = readPersistedOpencodeV2Ports;
+exports.getAssignedOpencodeV2Port = getAssignedOpencodeV2Port;
+exports.rememberOpencodeV2Port = rememberOpencodeV2Port;
+exports.forgetOpencodeV2Port = forgetOpencodeV2Port;
+exports.forgetOpencodeV2PortByKey = forgetOpencodeV2PortByKey;
+exports.deriveOpencodeV2PortStart = deriveOpencodeV2PortStart;
+exports.opencodeV2PortCandidates = opencodeV2PortCandidates;
+exports.allocateOpencodeV2Port = allocateOpencodeV2Port;
+exports.recoverOpencodeV2Port = recoverOpencodeV2Port;
+exports.resetOpencodeV2PortAssignments = resetOpencodeV2PortAssignments;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const logger_1 = require("../../../../lib/logger");
+const ports_1 = require("../opencode/ports");
+const secrets_1 = require("./secrets");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode-v2/ports');
+/** Ports OpenCode V2 servers are started on. Disjoint from v1's 4200–4299. */
+exports.OPENCODE_V2_PORT_RANGE = { min: 4300, max: 4399 };
+const PORT_SPAN = exports.OPENCODE_V2_PORT_RANGE.max - exports.OPENCODE_V2_PORT_RANGE.min + 1;
+/** File name of the persisted assignments inside the state directory. */
+exports.OPENCODE_V2_PORT_FILE_NAME = 'ports.json';
+const assignments = (globalThis.__opencodeV2PortAssignments ??= new Map());
+/** Absolute path of the persisted assignments. */
+function getOpencodeV2PortFilePath() {
+    return (0, path_1.join)((0, secrets_1.getOpencodeV2StateDir)(), exports.OPENCODE_V2_PORT_FILE_NAME);
+}
+function isAssignment(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return (typeof record.port === 'number' &&
+        Number.isInteger(record.port) &&
+        record.port >= exports.OPENCODE_V2_PORT_RANGE.min &&
+        record.port <= exports.OPENCODE_V2_PORT_RANGE.max &&
+        typeof record.worktreePath === 'string');
+}
+/** Every persisted assignment, keyed by composite key. Unreadable → empty. */
+function readPersistedOpencodeV2Ports() {
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(getOpencodeV2PortFilePath(), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        const result = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (isAssignment(value)) {
+                result[key] = {
+                    port: value.port,
+                    worktreePath: value.worktreePath,
+                    updatedAt: typeof value.updatedAt === 'number' ? value.updatedAt : 0,
+                };
+            }
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+function writePersistedOpencodeV2Ports(all) {
+    const path = getOpencodeV2PortFilePath();
+    try {
+        if (Object.keys(all).length === 0) {
+            (0, fs_1.rmSync)(path, { force: true });
+            return;
+        }
+        (0, secrets_1.ensureOpencodeV2StateDir)();
+        (0, fs_1.writeFileSync)(path, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch (error) {
+        logger.warn('opencode-v2-port-file-write-failed', {
+            path,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/** The port this process assigned to the instance, or null. */
+function getAssignedOpencodeV2Port(target) {
+    return assignments.get((0, secrets_1.opencodeV2KeyOf)(target))?.port ?? null;
+}
+/** Record an assignment in memory and on disk. */
+function rememberOpencodeV2Port(target, port, worktreePath, at = Date.now()) {
+    const key = (0, secrets_1.opencodeV2KeyOf)(target);
+    const assignment = { port, worktreePath, updatedAt: at };
+    assignments.set(key, assignment);
+    const all = readPersistedOpencodeV2Ports();
+    all[key] = assignment;
+    writePersistedOpencodeV2Ports(all);
+}
+/** Drop an assignment from memory and from disk. */
+function forgetOpencodeV2Port(target) {
+    forgetOpencodeV2PortByKey((0, secrets_1.opencodeV2KeyOf)(target));
+}
+/** {@link forgetOpencodeV2Port} by composite key (the startup sweep's form). */
+function forgetOpencodeV2PortByKey(key) {
+    assignments.delete(key);
+    const all = readPersistedOpencodeV2Ports();
+    if (key in all) {
+        delete all[key];
+        writePersistedOpencodeV2Ports(all);
+    }
+}
+/**
+ * First port tried for a key: FNV-1a of the key, folded into the range.
+ *
+ * The same hash v1 uses, over a different range, so instances spread out
+ * instead of all contending for the range's first port.
+ */
+function deriveOpencodeV2PortStart(key) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < key.length; index += 1) {
+        hash ^= key.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return exports.OPENCODE_V2_PORT_RANGE.min + (hash % PORT_SPAN);
+}
+/** Every port in the range, starting at the instance's own start and wrapping. */
+function opencodeV2PortCandidates(target) {
+    const start = deriveOpencodeV2PortStart((0, secrets_1.opencodeV2KeyOf)(target));
+    const candidates = [];
+    for (let offset = 0; offset < PORT_SPAN; offset += 1) {
+        candidates.push(exports.OPENCODE_V2_PORT_RANGE.min + ((start - exports.OPENCODE_V2_PORT_RANGE.min + offset) % PORT_SPAN));
+    }
+    return candidates;
+}
+/**
+ * Assign a free port to the instance.
+ *
+ * Unlike v1 this is not optional: an OpenCode V2 pane without its own server
+ * would fall back to the user's shared background service, which CommandMate
+ * must not drive. So hook injection being off does not skip the allocation.
+ * An already-held assignment is reused; a persisted one is preferred when its
+ * port is free again.
+ *
+ * @returns The port, or null when the whole range is taken
+ */
+async function allocateOpencodeV2Port(target, worktreePath, probe = ports_1.isPortFree) {
+    const existing = getAssignedOpencodeV2Port(target);
+    if (existing !== null && (await probe(existing)))
+        return existing;
+    const key = (0, secrets_1.opencodeV2KeyOf)(target);
+    const preferred = readPersistedOpencodeV2Ports()[key]?.port;
+    const candidates = opencodeV2PortCandidates(target);
+    const ordered = preferred !== undefined ? [preferred, ...candidates.filter((p) => p !== preferred)] : candidates;
+    for (const port of ordered) {
+        if (await probe(port)) {
+            rememberOpencodeV2Port(target, port, worktreePath);
+            logger.info('opencode-v2-port-allocated', {
+                worktreeId: target.worktreeId,
+                instanceId: target.instanceId ?? target.cliToolId,
+                port,
+            });
+            return port;
+        }
+    }
+    logger.warn('opencode-v2-port-exhausted', {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        range: `${exports.OPENCODE_V2_PORT_RANGE.min}-${exports.OPENCODE_V2_PORT_RANGE.max}`,
+    });
+    return null;
+}
+/**
+ * Re-adopt a persisted assignment after a CommandMate restart.
+ *
+ * Adopted only when it was recorded for the same worktree path and `verify`
+ * says the server on it is this instance's (it accepts the instance's
+ * password). A port someone else took since is not re-adopted.
+ *
+ * @returns The recovered port, or null
+ */
+async function recoverOpencodeV2Port(target, worktreePath, verify) {
+    const existing = getAssignedOpencodeV2Port(target);
+    if (existing !== null)
+        return existing;
+    const key = (0, secrets_1.opencodeV2KeyOf)(target);
+    const persisted = readPersistedOpencodeV2Ports()[key];
+    if (!persisted)
+        return null;
+    if (persisted.worktreePath !== worktreePath) {
+        logger.info('opencode-v2-port-recovery-path-mismatch', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+        });
+        return null;
+    }
+    if (!(await verify(persisted.port))) {
+        logger.info('opencode-v2-port-recovery-unverified', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            port: persisted.port,
+        });
+        return null;
+    }
+    assignments.set(key, persisted);
+    logger.info('opencode-v2-port-recovered', {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        port: persisted.port,
+    });
+    return persisted.port;
+}
+/** Forget every in-memory assignment. For tests. */
+function resetOpencodeV2PortAssignments() {
+    assignments.clear();
+}