@openchambery/web 2.0.0-beta.3 → 2.0.0-beta.31

package/server/lib/opencode/upgrade-screen.js

@@ -0,0 +1,292 @@
+/**
+ * Startup upgrade screen for OpenCode below the runtime contract minimum.
+ *
+ * This module does not own process lifecycle. It classifies the version the
+ * existing startup path already detected, and installs through the owned-cache
+ * installer (`installPinnedOpenCode2Cli`) plus the caller's restart hook.
+ * Success is a verified running version, never a download that has not started.
+ */
+
+import {
+  PINNED_OPENCODE2_VERSION,
+  MINIMUM_OPENCODE2_VERSION,
+  isAcceptableOpenCode2HealthVersion,
+  isOpenCode1xVersion,
+  isOpenCode2VersionAtLeast,
+  npmPackageForOpenCode2,
+} from './opencode2-pin.js';
+
+/** Oldest OpenCode this OpenChamber build will enter a session against. */
+export const REQUIRED_OPENCODE_VERSION = MINIMUM_OPENCODE2_VERSION;
+
+const normalizeVersion = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim().replace(/^v/i, '');
+  return trimmed || null;
+};
+
+/**
+ * Install target is the pin when the pin already satisfies the screen, otherwise
+ * the screen minimum. A pin still at 2.0.12 must not be what this screen installs.
+ * @param {string} [pin]
+ */
+export function resolveUpgradeScreenTarget(pin = PINNED_OPENCODE2_VERSION) {
+  if (isOpenCode2VersionAtLeast(pin, REQUIRED_OPENCODE_VERSION)) return pin;
+  return REQUIRED_OPENCODE_VERSION;
+}
+
+/** 2.x at or above the screen minimum. A future major is not this contract. */
+function isUpgradeScreenSatisfied(version) {
+  const normalized = normalizeVersion(version);
+  if (!normalized || !isAcceptableOpenCode2HealthVersion(normalized)) return false;
+  return isOpenCode2VersionAtLeast(normalized, REQUIRED_OPENCODE_VERSION);
+}
+
+function isOlderThanUpgradeScreenMinimum(version) {
+  const normalized = normalizeVersion(version);
+  if (!normalized) return false;
+  if (isOpenCode1xVersion(normalized)) return true;
+  if (!isAcceptableOpenCode2HealthVersion(normalized)) return false;
+  return !isOpenCode2VersionAtLeast(normalized, REQUIRED_OPENCODE_VERSION);
+}
+
+/**
+ * @param {string | null | undefined} ownership
+ * @returns {'managed' | 'external' | 'bundled'}
+ */
+function classifyUpgradeScreenInstallation(ownership) {
+  if (ownership === 'external-serve') return 'external';
+  if (ownership === 'bundled') return 'bundled';
+  return 'managed';
+}
+
+export function platformSupportsUpgradeScreenInstall(platform = process.platform, arch = process.arch) {
+  try {
+    npmPackageForOpenCode2(platform, arch);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {{
+ *   version?: string | null,
+ *   installation?: 'managed' | 'external' | 'bundled',
+ *   platformCanInstall?: boolean,
+ *   guidance?: string | null,
+ *   pin?: string,
+ * }} input
+ */
+export function describeUpgradeScreen(input = {}) {
+  const version = normalizeVersion(input.version);
+  const installation = input.installation === 'external' || input.installation === 'bundled'
+    ? input.installation
+    : 'managed';
+  const state = version == null
+    ? 'unavailable'
+    : isUpgradeScreenSatisfied(version)
+      ? 'compatible'
+      : 'incompatible';
+  const older = version != null && isOlderThanUpgradeScreenMinimum(version);
+  // External processes are not replaced. Bundled and managed locals can receive
+  // an owned-cache install; that does not overwrite the user's other binaries.
+  const canInstall = state === 'incompatible'
+    && older
+    && installation !== 'external'
+    && input.platformCanInstall === true;
+  const guidance = canInstall
+    ? null
+    : (typeof input.guidance === 'string' && input.guidance.trim() ? input.guidance.trim() : null);
+  return {
+    state,
+    version,
+    installation,
+    minimumVersion: REQUIRED_OPENCODE_VERSION,
+    targetVersion: resolveUpgradeScreenTarget(input.pin),
+    canInstall,
+    guidance,
+  };
+}
+
+/**
+ * A running serve below the minimum, or a missing version, is not an upgrade.
+ * @param {{ targetVersion?: string | null, serveVersion?: string | null }} input
+ */
+export function evaluateUpgradeScreenInstallResult(input = {}) {
+  const targetVersion = resolveUpgradeScreenTarget(input.targetVersion || REQUIRED_OPENCODE_VERSION);
+  const version = normalizeVersion(input.serveVersion);
+  if (!version || !isUpgradeScreenSatisfied(version) || !isOpenCode2VersionAtLeast(version, targetVersion)) {
+    const found = version || 'unknown';
+    return {
+      ok: false,
+      upgraded: false,
+      version,
+      targetVersion,
+      errorCode: 'UPGRADE_SCREEN_NOT_VERIFIED',
+      error: `OpenCode is still ${found}. OpenChamber requires ${REQUIRED_OPENCODE_VERSION} or newer.`,
+    };
+  }
+  return {
+    ok: true,
+    upgraded: true,
+    version,
+    targetVersion,
+    error: null,
+    errorCode: null,
+  };
+}
+
+async function readUpgradeScreenStatus(deps) {
+  const ownership = typeof deps.resolveOwnership === 'function'
+    ? await deps.resolveOwnership()
+    : { ownership: 'unknown', guidance: null };
+  const installation = classifyUpgradeScreenInstallation(ownership?.ownership);
+  const serveVersion = typeof deps.readServeVersion === 'function'
+    ? await Promise.resolve(deps.readServeVersion()).catch(() => null)
+    : null;
+  const cliVersion = typeof deps.readCliVersion === 'function'
+    ? await Promise.resolve(deps.readCliVersion()).catch(() => null)
+    : null;
+  return describeUpgradeScreen({
+    version: serveVersion || (typeof deps.readServeVersion === 'function' ? null : cliVersion),
+    installation,
+    platformCanInstall: typeof deps.platformCanInstall === 'boolean'
+      ? deps.platformCanInstall
+      : platformSupportsUpgradeScreenInstall(deps.platform, deps.arch),
+    guidance: ownership?.guidance ?? null,
+    pin: deps.pin,
+  });
+}
+
+const failure = (message, code, status = 500) => {
+  const error = new Error(message);
+  error.code = code;
+  error.status = status;
+  return error;
+};
+
+/**
+ * Install the screen target into the owned cache and restart through the
+ * caller's existing lifecycle hooks. Restores the previous binary selection
+ * when verification fails. Never returns upgraded:true for a failed install.
+ * @param {object} deps
+ */
+export async function installRequiredOpenCode(deps) {
+  const status = await readUpgradeScreenStatus(deps);
+  if (status.state !== 'incompatible' || status.canInstall !== true) {
+    throw failure(
+      status.guidance || 'Automatic OpenCode installation is unavailable for this runtime.',
+      'UPGRADE_SCREEN_UNAVAILABLE',
+      409,
+    );
+  }
+  const target = status.targetVersion;
+  const previousBinary = typeof deps.getResolvedBinary === 'function' ? deps.getResolvedBinary() : null;
+  const previousSource = typeof deps.getResolvedBinarySource === 'function' ? deps.getResolvedBinarySource() : null;
+  const previousSetting = typeof deps.readConfiguredBinary === 'function'
+    ? await deps.readConfiguredBinary()
+    : undefined;
+  let persisted = false;
+  try {
+    if (typeof deps.install !== 'function') {
+      throw failure('OpenCode install is not configured.', 'UPGRADE_SCREEN_INSTALL_UNAVAILABLE', 500);
+    }
+    const installedPath = await deps.install({ version: target });
+    const diskVersion = typeof deps.readBinaryVersion === 'function'
+      ? await Promise.resolve(deps.readBinaryVersion(installedPath))
+      : null;
+    if (diskVersion !== target) {
+      throw failure(
+        `Installed OpenCode version mismatch: expected ${target}, got ${diskVersion || 'unknown'}`,
+        'UPGRADE_SCREEN_BINARY_MISMATCH',
+        500,
+      );
+    }
+    if (typeof deps.persistBinary === 'function') {
+      await deps.persistBinary(installedPath);
+      persisted = true;
+    }
+    if (typeof deps.forceBinary === 'function') {
+      deps.forceBinary(installedPath, 'installed');
+    }
+    if (typeof deps.restart === 'function') {
+      const shared = typeof deps.isSharedService === 'function' && deps.isSharedService() === true;
+      await deps.restart(shared ? { binaryPath: installedPath } : undefined);
+    }
+    if (typeof deps.waitReady === 'function') {
+      await deps.waitReady();
+    }
+    const serveVersion = typeof deps.readServeVersion === 'function'
+      ? await deps.readServeVersion()
+      : null;
+    const verification = evaluateUpgradeScreenInstallResult({ targetVersion: target, serveVersion });
+    if (!verification.ok) {
+      throw failure(verification.error, verification.errorCode, 500);
+    }
+    return verification;
+  } catch (error) {
+    if (persisted && typeof deps.persistBinary === 'function') {
+      try {
+        await deps.persistBinary(typeof previousSetting === 'string' ? previousSetting : '');
+      } catch {
+        // Keep the install error. A failed restore must not become success.
+      }
+    }
+    if (previousBinary && typeof deps.forceBinary === 'function') {
+      try {
+        deps.forceBinary(previousBinary, previousSource || 'discovered');
+      } catch {
+        // Same: report the install failure, not a restored-success.
+      }
+    }
+    throw error;
+  }
+}
+
+export function registerUpgradeScreenRoutes(app, deps) {
+  app.get('/api/opencode/compatibility', async (_req, res) => {
+    try {
+      res.json(await readUpgradeScreenStatus(deps));
+    } catch (error) {
+      res.status(503).json({
+        error: error instanceof Error ? error.message : 'Could not check OpenCode compatibility',
+      });
+    }
+  });
+
+  let inFlight = null;
+  app.post('/api/opencode/install-required', async (_req, res) => {
+    try {
+      if (!inFlight) {
+        inFlight = installRequiredOpenCode(deps).finally(() => {
+          inFlight = null;
+        });
+      }
+      const result = await inFlight;
+      if (!result || result.ok !== true || result.upgraded !== true || !result.version) {
+        return res.status(500).json({
+          success: false,
+          upgraded: false,
+          error: result?.error || 'OpenCode installation did not verify a new version',
+          errorCode: result?.errorCode || 'UPGRADE_SCREEN_NOT_VERIFIED',
+          version: result?.version ?? null,
+        });
+      }
+      return res.json({
+        success: true,
+        upgraded: true,
+        version: result.version,
+        targetVersion: result.targetVersion,
+      });
+    } catch (error) {
+      const status = Number.isInteger(error?.status) ? error.status : 500;
+      return res.status(status).json({
+        success: false,
+        upgraded: false,
+        error: error instanceof Error ? error.message : 'OpenCode installation failed',
+        errorCode: error?.code || 'UPGRADE_SCREEN_FAILED',
+      });
+    }
+  });
+}

package/server/lib/opencode/upgrade-screen.test.js

@@ -0,0 +1,196 @@
+import express from 'express';
+import request from 'supertest';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  REQUIRED_OPENCODE_VERSION,
+  describeUpgradeScreen,
+  evaluateUpgradeScreenInstallResult,
+  installRequiredOpenCode,
+  registerUpgradeScreenRoutes,
+  resolveUpgradeScreenTarget,
+} from './upgrade-screen.js';
+
+describe('upgrade screen version gate', () => {
+  it('uses the floor even when the runtime pin is older', () => {
+    expect(REQUIRED_OPENCODE_VERSION).toBe('2.0.20');
+    expect(resolveUpgradeScreenTarget('2.0.12')).toBe('2.0.20');
+    expect(resolveUpgradeScreenTarget('2.0.23')).toBe('2.0.23');
+  });
+
+  it('does not open the gate at or above 2.0.20', () => {
+    expect(describeUpgradeScreen({
+      version: '2.0.20',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'compatible', canInstall: false, minimumVersion: '2.0.20' });
+    expect(describeUpgradeScreen({
+      version: 'v2.0.23',
+      installation: 'managed',
+      platformCanInstall: true,
+    }).state).toBe('compatible');
+  });
+
+  it('opens the gate below 2.0.20 and offers install only when this runtime can switch', () => {
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true, version: '2.0.14' });
+    expect(describeUpgradeScreen({
+      version: '1.18.30',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true });
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'external',
+      platformCanInstall: true,
+    }).canInstall).toBe(false);
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'bundled',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true, installation: 'bundled' });
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'managed',
+      platformCanInstall: false,
+    }).canInstall).toBe(false);
+  });
+
+  it('does not treat a missing version as an old install', () => {
+    expect(describeUpgradeScreen({
+      version: null,
+      installation: 'managed',
+      platformCanInstall: true,
+    }).state).toBe('unavailable');
+  });
+
+  it('does not report an unverified install as upgraded', () => {
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.23',
+      serveVersion: '2.0.14',
+    })).toMatchObject({ ok: false, upgraded: false, version: '2.0.14' });
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.23',
+      serveVersion: null,
+    }).upgraded).toBe(false);
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.23',
+      serveVersion: '2.0.23',
+    })).toMatchObject({ ok: true, upgraded: true, version: '2.0.23' });
+  });
+});
+
+describe('installRequiredOpenCode', () => {
+  const createDeps = (overrides = {}) => {
+    const calls = [];
+    const deps = {
+      resolveOwnership: async () => ({ ownership: 'global-cli', guidance: null }),
+      readServeVersion: async () => '2.0.14',
+      readCliVersion: () => '2.0.14',
+      platformCanInstall: true,
+      install: vi.fn(async () => {
+        calls.push('install');
+        return '/cache/opencode';
+      }),
+      readBinaryVersion: vi.fn(() => '2.0.23'),
+      persistBinary: vi.fn(async () => {
+        calls.push('persist');
+      }),
+      forceBinary: vi.fn(() => {
+        calls.push('force');
+      }),
+      restart: vi.fn(async () => {
+        calls.push('restart');
+      }),
+      waitReady: vi.fn(async () => {
+        calls.push('ready');
+      }),
+      readConfiguredBinary: async () => null,
+      isSharedService: () => false,
+      ...overrides,
+    };
+    return { deps, calls };
+  };
+
+  it('installs 2.0.23 and only succeeds after the running serve is verified', async () => {
+    const { deps, calls } = createDeps({
+      readServeVersion: vi.fn()
+        .mockResolvedValueOnce('2.0.14')
+        .mockResolvedValueOnce('2.0.23'),
+    });
+
+    await expect(installRequiredOpenCode(deps)).resolves.toMatchObject({
+      ok: true,
+      upgraded: true,
+      version: '2.0.23',
+      targetVersion: '2.0.23',
+    });
+    expect(deps.install).toHaveBeenCalledWith({ version: '2.0.23' });
+    expect(calls).toEqual(['install', 'persist', 'force', 'restart', 'ready']);
+  });
+
+  it('returns the failure reason and does not claim an upgrade when verification fails', async () => {
+    const { deps } = createDeps({
+      readServeVersion: vi.fn()
+        .mockResolvedValueOnce('1.18.30')
+        .mockResolvedValueOnce('1.18.30'),
+      readCliVersion: () => '1.18.30',
+      readBinaryVersion: () => '2.0.23',
+    });
+
+    await expect(installRequiredOpenCode(deps)).rejects.toThrow(/still 1\.18\.30/);
+    expect(deps.persistBinary).toHaveBeenCalledWith('');
+  });
+
+  it('does not install when the runtime cannot switch', async () => {
+    const { deps } = createDeps({
+      resolveOwnership: async () => ({
+        ownership: 'external-serve',
+        guidance: 'Restart that server yourself.',
+      }),
+    });
+
+    await expect(installRequiredOpenCode(deps)).rejects.toMatchObject({
+      status: 409,
+      message: 'Restart that server yourself.',
+    });
+    expect(deps.install).not.toHaveBeenCalled();
+  });
+});
+
+describe('upgrade screen routes', () => {
+  it('hides the gate for 2.0.20 and reports install failure without upgraded:true', async () => {
+    const app = express();
+    app.use(express.json());
+    const readServeVersion = vi.fn()
+      .mockResolvedValueOnce('2.0.20')
+      .mockResolvedValueOnce('2.0.12')
+      .mockResolvedValueOnce('2.0.12');
+    registerUpgradeScreenRoutes(app, {
+      resolveOwnership: async () => ({ ownership: 'owned-cache', guidance: null }),
+      readServeVersion,
+      readCliVersion: () => '2.0.12',
+      platformCanInstall: true,
+      install: vi.fn(async () => {
+        throw new Error('registry unreachable');
+      }),
+      readBinaryVersion: () => '2.0.23',
+      persistBinary: vi.fn(),
+      forceBinary: vi.fn(),
+      restart: vi.fn(),
+    });
+
+    const compatible = await request(app).get('/api/opencode/compatibility').expect(200);
+    expect(compatible.body).toMatchObject({ state: 'compatible', version: '2.0.20', minimumVersion: '2.0.20' });
+
+    const failed = await request(app).post('/api/opencode/install-required').expect(500);
+    expect(failed.body).toMatchObject({
+      success: false,
+      upgraded: false,
+      error: 'registry unreachable',
+    });
+    expect(failed.body.upgraded).not.toBe(true);
+  });
+});

package/server/lib/opencode/version-alignment.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from 'vitest';
+import { MINIMUM_OPENCODE2_VERSION, PINNED_OPENCODE2_VERSION } from './opencode2-pin.js';
+import { evaluateRuntimeContract } from './runtime-contract.js';
+import { describeUpgradeScreen, installRequiredOpenCode, resolveUpgradeScreenTarget } from './upgrade-screen.js';
+import { ensurePinnedOpenCode2Cli } from './ensure-cli.js';
+
+describe('v2 version alignment', () => {
+  it.each(['1.18.30', '2.0.19', null, 'unknown'])('blocks execution and startup for %s', (version) => {
+    expect(evaluateRuntimeContract({ serveVersion: version, cliVersion: '2.0.23', reachable: true, authenticated: true }).executionAllowed).toBe(false);
+    expect(describeUpgradeScreen({ version }).state).not.toBe('compatible');
+  });
+  it.each(['2.0.20', '2.0.23', '2.1.0'])('admits running %s independently of CLI pin', (version) => {
+    expect(evaluateRuntimeContract({ serveVersion: version, cliVersion: '2.0.15', reachable: true, authenticated: true })).toMatchObject({ executionAllowed: true, versionMismatch: true, minVerifiedVersion: '2.0.20' });
+    expect(describeUpgradeScreen({ version }).state).toBe('compatible');
+  });
+  it('installs the audited pin on first install and preserves newer discovered CLIs', async () => {
+    expect(MINIMUM_OPENCODE2_VERSION).toBe('2.0.20');
+    expect(PINNED_OPENCODE2_VERSION).toBe('2.0.23');
+    expect(resolveUpgradeScreenTarget()).toBe('2.0.23');
+    const install = vi.fn(async () => '/owned/opencode');
+    await expect(ensurePinnedOpenCode2Cli({ readVersion: (path) => path === '/owned/opencode' ? '2.0.23' : '', install })).resolves.toMatchObject({ version: '2.0.23', installed: true });
+    expect(install).toHaveBeenCalledWith(expect.objectContaining({ version: '2.0.23' }));
+    install.mockClear();
+    await expect(ensurePinnedOpenCode2Cli({ discoveredPath: '/global/opencode', readVersion: () => '2.1.0', install })).resolves.toMatchObject({ version: '2.1.0', installed: false });
+    expect(install).not.toHaveBeenCalled();
+  });
+  it('does not infer a successful installation from an unreadable binary', async () => {
+    await expect(ensurePinnedOpenCode2Cli({ readVersion: () => '', install: async () => '/owned/opencode' })).rejects.toThrow('got unknown');
+  });
+  it('verifies the live service after explicit install, and rolls selection back on failure', async () => {
+    const persistBinary = vi.fn();
+    const restart = vi.fn();
+    const deps = { resolveOwnership: async () => ({ ownership: 'shared-service' }), readServeVersion: vi.fn().mockResolvedValueOnce('2.0.19').mockResolvedValueOnce('2.0.23'), readCliVersion: () => '2.0.23', platformCanInstall: true, install: async () => '/owned/opencode', readBinaryVersion: () => '2.0.23', persistBinary, restart, isSharedService: () => true };
+    await expect(installRequiredOpenCode(deps)).resolves.toMatchObject({ upgraded: true, version: '2.0.23' });
+    expect(restart).toHaveBeenCalledWith({ binaryPath: '/owned/opencode' });
+    deps.readServeVersion.mockResolvedValue('2.0.19');
+    await expect(installRequiredOpenCode(deps)).rejects.toMatchObject({ code: 'UPGRADE_SCREEN_NOT_VERIFIED' });
+    expect(persistBinary).toHaveBeenLastCalledWith('');
+  });
+});

package/server/lib/question-auto-delegate/DOCUMENTATION.md

@@ -2,12 +2,15 @@
 
 ## Purpose
 
-Server-owned automatic handling of OpenCode `question.asked` prompts. When
+Server-owned automatic handling of OpenCode 2 question-tool forms (`form.created`,
+`data.form.metadata.kind === "question"`). When
 enabled (default), pending questions are answered after 30 seconds with a fixed
 continuation text so agents (including background/subagent sessions) can proceed
 without a connected UI. Manual reply/reject still use the official OpenCode
-SDK shape; the Host only adds a single-flight claim so timer, manual, and
-delegate paths cannot double-POST upstream.
+form schema. The Host adds a single-flight claim for timer, delegate, and
+compatibility question routes. Native manual form replies settle via
+`form.replied` / `form.cancelled`; upstream form settlement arbitrates any race
+with a native reply already in flight.
 
 Permission auto-accept is intentionally out of scope — this module never
 replies to permission requests.
@@ -42,6 +45,7 @@ Auto-submit requires **settings ready + enabled + authoritative directory**.
 |---|---|
 | `core.js` / `core.d.ts` | Platform-agnostic state machine (IO/timer injected). Shared contract for VS Code. |
 | `runtime.js` | Web adapter: OpenCode upstream fetch, global event hub, settings, SSE tips, project + session-index directories. |
+| `form-io.js` / `form-io.d.ts` | Shared Web/VS Code native form list, schema lookup, answer mapping and cancellation. |
 | `routes.js` | OpenChamber routes + precise `/api/question/:id/reply\|reject` intercepts. |
 
 ## Snapshot
@@ -62,21 +66,31 @@ Tip event (not a data payload):
 | `POST` | `.../requests/:id/pause` | `{ sessionID, directory, reason: 'interaction'\|'user' }` — bound identity conflicts → 409. Directory may be empty; pause still cancels the auto timer. |
 | `POST` | `.../requests/:id/delegate` | recovers identity via scoped list; allowed when toggle off |
 | `POST` | `/api/question/:id/reply` | manual: `answers` must be an array (incl. `[]`); never auto text |
-| `POST` | `/api/question/:id/reject` | SDK body preserved |
+| `POST` | `/api/question/:id/reject` | Compatibility route mapped to native form cancellation |
 
 Concurrent claim losers: HTTP **409** + `code: "question_submission_claimed"`.
 
 ## Claim / upstream rules
 
+OpenCode 2.0.15 upstream uses `GET /api/form?location[directory]=...` for
+pending forms and `GET /api/session/:sessionID/form/:formID` before submitting
+`POST .../reply` with `{ answer }`. Only question-tool forms are eligible.
+The fresh schema owns field keys, option values and string/multiselect shape.
+Failed schema reads are `notSent` and pause for retry. Cancellation uses
+`POST .../cancel`. Session directory recovery reads `info.location.directory`;
+live events read `payload.location.directory` and `payload.data`.
+Web, Electron and mobile hosts use the Web adapter; VS Code imports the same
+form IO and core, restoring `/api` for origin-only upstream URLs.
+
 1. One authority owns at most one upstream POST per `requestID` (sync claim).
 2. **Definitive reject** (400/409/422) or pre-send throw → **release claim**, pause for human retry. **No immediate auto retry.**
 3. **Unclear post-dispatch result** (timeout/5xx/`uncertain`) → `uncertain` tombstone; no retry; still **blocks** goal.
 4. **Settled** must not be downgraded by a late POST failure.
 5. Successful **scoped** empty list may converge `uncertain`/pending → `external` settled **only for that directory**.
-6. Manual reply forwards `answers` as-is (including `[]`). Fixed text is auto/delegate only.
+6. Compatibility manual reply passes `answers` (including `[]`) to the form adapter, which maps them by authoritative fields. Fixed text is auto/delegate only.
 7. Client `sessionID`/`directory` hints never override a bound identity (conflict → 409).
 8. Auto-submit requires an authoritative directory binding (from event, session cache, or `getSession` write-back). Missing directory → no timer.
-9. Unknown pause/delegate recovers via scoped `question.list` — never invents `questionCount=1`.
+9. Unknown pause/delegate recovers via scoped `form.list`, filtered to question-tool forms — never invents `questionCount=1`.
 
 ## Reconcile
 
@@ -119,6 +133,7 @@ Concurrent claim losers: HTTP **409** + `code: "question_submission_claimed"`.
 ```sh
 bunx vitest run --project @openchamber/web \
   packages/web/server/lib/question-auto-delegate/core.test.js \
+  packages/web/server/lib/question-auto-delegate/runtime.test.js \
   packages/web/server/lib/question-auto-delegate/routes.test.js \
   packages/web/server/lib/session-goal/runtime.test.js
 ```

package/server/lib/question-auto-delegate/core.d.ts

@@ -114,6 +114,8 @@ export interface QuestionAutoDelegatePendingQuestion {
   sessionID: string;
   directory?: string | null;
   questions?: unknown[] | null;
+  fields?: unknown[];
+  metadata?: { kind?: unknown };
 }
 
 export interface QuestionAutoDelegateSessionInfo {
@@ -167,11 +169,13 @@ export interface QuestionAutoDelegateIO {
     requestID: string,
     directory: string | undefined,
     answers: string[][],
+    sessionID: string,
   ): Promise<QuestionAutoDelegateUpstreamResult>;
   postReject(
     requestID: string,
     directory: string | undefined,
-    body?: unknown,
+    body: unknown,
+    sessionID: string,
   ): Promise<QuestionAutoDelegateUpstreamResult>;
   /** Project directories used for reconnect/start reconcile. */
   listDirectories(): Promise<string[]>;