feat(walkthrough): guided AI walkthrough for diffs, branches, and PRs (#2572)

A diff is ordered by file path, which is almost never the order in which a
change makes sense. This adds a Walkthrough surface that reorders it: the model
groups related hunks into stops, explains what each group changes about
behavior, and orders the stops so each builds on the last. It explains and
orders; judging code stays with the existing Review action.

Reviews uncommitted work (all, staged, unstaged), a branch against its base, or
a pull request. Generation is always user-initiated — nothing runs on a timer,
on a file change, or as a side effect of opening a panel.

Invariants worth preserving:

- Hunk identity is derived on the server and only there. Ids are content
  hashes, so an anchor that no longer resolves is proof the code it described
  changed, and staleness needs no heuristics. The client matches ids to ids and
  never recomputes them; two implementations would have to agree forever.
- The digest is never truncated. A diff that does not fit the model's context
  is refused with an actionable reason, because a walkthrough written against
  half a diff reads as confident and is wrong.
- Nothing disappears. Lockfiles and other generated output are excluded from
  the model's input by name — never by size — and everything no stop covers is
  listed at the end, so "have I seen all of it" stays answerable.
- Cost is explicit. Results are content-addressed, so returning the working
  tree to an earlier state costs nothing; generation outlives its request, so a
  refresh detaches the client rather than discarding paid-for work, and only an
  explicit cancel stops it.

Supporting changes to shared modules:

- git: expose the existing getRangeDiff as GET /api/git
  listUntrackedPaths and getUntrackedDiffs. The latter resolve the repository
  once for a batch instead of per file, taking a panel
  ~340ms on an 80-file working tree.
- small-model: structured output across four wire forma
  and abort signal, and an onOverflow policy so an oversized prompt fails
  loudly instead of being silently clipped. A provider
  remembered so the prompt-side fallback goes first next time.
- models.dev metadata: surface structured_output as tri
  false blocks a model, a missing field does not, because the catalog omits it
  for roughly half of all models.

Desktop and tablet only: VS Code serves Git through its
these routes, and the mobile shell does not consume the surface registry.

Docs: packages/docs walkthrough page in English and all eight locales.

packages/web/server/lib/git/DOCUMENTATION.md

@@ -26,9 +26,11 @@ The following functions are exported and used by the web server:
 ### Status and Diff Operations
 - `getStatus(directory)`: Get comprehensive Git status including current branch, tracking, ahead/behind, file changes, diff stats, merge/rebase state.
 - `getDiff(directory, { path, staged, contextLines })`: Get diff output for files or entire working tree. Untracked symbolic links are represented as link entries without following their targets.
-- `getRangeDiff(directory, { base, head, path, contextLines })`: Get diff between two refs.
+- `getRangeDiff(directory, { base, head, path, contextLines })`: Get diff between two refs. Uses three-dot `base...head` semantics, so work merged into `head` from `base` is excluded and only the branch's own changes are returned. Prefers `origin/<base>` when that remote-tracking ref exists, so a stale local base branch does not resurface already-merged commits. Exposed as `GET /api/git/range-diff` (`path` optional; omit it for the whole range).
 - `getRangeFiles(directory, { base, head })`: Get list of changed files between two refs.
 - `getFileDiff(directory, { path, staged })`: Get original and modified file contents for a single file (handles images as data URLs and symbolic links as their link-target text).
+- `listUntrackedPaths(directory)`: List individual untracked file paths honoring ignore rules. Much cheaper than `getStatus` when that is all a caller needs. Deliberately not `--directory`: collapsed directory entries end in a slash and are rejected by the per-file diff helpers, so a caller would silently lose every file inside a new directory.
+- `getUntrackedDiffs(directory, filePaths, { concurrency, contextLines })`: Diffs for untracked files against an empty tree. Resolves the repository context once instead of per file (`getDiff` re-resolves every call, costing an extra `rev-parse` each time) and bounds how many diff processes run at once. Returns one entry per input path in order; unreadable paths yield `''` rather than failing the batch.
 - `collectDiffs(directory, files)`: Collect diff output for multiple files.
 - `revertFile(directory, filePath, options)`: Revert a file. Default scope `all` discards staged and working-tree changes; scope `working` discards only unstaged/working-tree changes.
 - `stageFile(directory, filePath)`: Add one file path to the index.
@@ -109,6 +111,9 @@ The following functions are internal helpers used by exported functions:
 - `mergeInProgress`: Object with `{ head, message }` if merge in progress.
 - `rebaseInProgress`: Object with `{ headName, onto }` if rebase in progress.
 
+### Runtime availability of range diffs
+- `GET /api/git/range-diff` is served by the OpenChamber web server, so it is available to web, desktop, and mobile clients. The shared `GitAPI.getGitRangeDiff` is therefore optional: web supplies the HTTP implementation, and VS Code does not implement it because the extension host serves Git through its own bridge rather than these routes. Features built on range diffs (currently the AI diff walkthrough) are not offered in VS Code.
+
 ### Staged and unstaged change handling
 - `status.files` exposes both `index` and `working_dir` codes. Shared UI uses these as separate scopes: staged rows are derived from non-empty `index` statuses, while unstaged rows are derived from `working_dir` statuses and untracked files.
 - A file with both staged and unstaged changes can appear in both UI sections. Staged rows request diffs with `staged: true`; unstaged rows request normal working-tree diffs.

packages/web/server/lib/git/routes.js

@@ -397,6 +397,37 @@ export function registerGitRoutes(app) {
     }
   });
 
+  app.get('/api/git/range-diff', async (req, res) => {
+    const { getRangeDiff } = await getGitLibraries();
+    try {
+      const directory = req.query.directory;
+      if (!directory || typeof directory !== 'string') {
+        return res.status(400).json({ error: 'directory parameter is required' });
+      }
+
+      const base = req.query.base;
+      const head = req.query.head;
+      if (!base || typeof base !== 'string' || !head || typeof head !== 'string') {
+        return res.status(400).json({ error: 'base and head parameters are required' });
+      }
+
+      const pathParam = typeof req.query.path === 'string' && req.query.path ? req.query.path : undefined;
+      const context = req.query.context ? parseInt(String(req.query.context), 10) : undefined;
+
+      const diff = await getRangeDiff(directory, {
+        base,
+        head,
+        path: pathParam,
+        contextLines: Number.isFinite(context) ? context : 3,
+      });
+
+      res.json({ diff });
+    } catch (error) {
+      console.error('Failed to get git range diff:', error);
+      res.status(500).json({ error: error.message || 'Failed to get git range diff' });
+    }
+  });
+
   app.post('/api/git/revert', async (req, res) => {
     const { revertFile } = await getGitLibraries();
     try {

packages/web/server/lib/git/service.js

@@ -488,6 +488,16 @@ const createRepositoryGitContext = async (directory) => {
   return { directoryPath, directoryGit, repoRoot, git };
 };
 
+/**
+ * Absolute repository root for a directory anywhere inside it. Callers that key
+ * persisted data by repository need this so two directories in the same
+ * repository do not address different records.
+ */
+export async function getRepositoryRoot(directory) {
+  const { repoRoot } = await createRepositoryGitContext(directory);
+  return repoRoot;
+}
+
 const resolveGitInternalPath = async (repoRoot, git, gitPath) => {
   const resolved = await git.raw(['rev-parse', '--git-path', gitPath]);
   return path.resolve(repoRoot, resolved.trim());
@@ -2427,6 +2437,78 @@ export async function getDiff(directory, { path: filePath, staged = false, conte
   }
 }
 
+/**
+ * Individual untracked file paths, honoring ignore rules.
+ *
+ * Deliberately not `--directory`: collapsed directory entries end in a slash
+ * and are not valid inputs to the per-file diff helpers, so a caller would
+ * silently lose every file inside a new directory. Listing files costs more
+ * entries but each one is usable.
+ *
+ * Callers that only need this list should not pay for `getStatus`, which also
+ * computes ahead/behind, diff stats, and merge state — an order of magnitude
+ * more work for an answer they throw away.
+ */
+export async function listUntrackedPaths(directory) {
+  const { repoRoot } = await createRepositoryGitContext(directory);
+  const result = await runGitCommand(repoRoot, [
+    'ls-files',
+    '--others',
+    '--exclude-standard',
+  ]);
+  if (!result.success) return [];
+  return String(result.stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Diffs for untracked files, produced against an empty tree.
+ *
+ * `getDiff` re-resolves the repository context on every call, which costs an
+ * extra `rev-parse` per file; a walkthrough of a branch with thirty new files
+ * pays that thirty times. This resolves once and reuses it, with a bounded pool
+ * so a repository full of new files cannot flood the process table.
+ *
+ * Returns one entry per input path, in order; unreadable paths yield `''`
+ * rather than failing the batch.
+ */
+export async function getUntrackedDiffs(directory, filePaths = [], { concurrency = 8, contextLines = 3 } = {}) {
+  const paths = (Array.isArray(filePaths) ? filePaths : []).filter((value) => typeof value === 'string' && value);
+  if (paths.length === 0) return [];
+
+  const { directoryPath, directoryGit, repoRoot, git } = await createRepositoryGitContext(directory);
+  const results = new Array(paths.length).fill('');
+  let cursor = 0;
+
+  const worker = async () => {
+    while (cursor < paths.length) {
+      const index = cursor++;
+      try {
+        const fileContext = await resolveGitFileContext(directoryPath, directoryGit, paths[index], repoRoot);
+        const args = ['diff', '--no-color'];
+        if (typeof contextLines === 'number' && !Number.isNaN(contextLines)) {
+          args.push(`-U${Math.max(0, contextLines)}`);
+        }
+        args.push('--no-index', '--', '/dev/null', fileContext.repoPath);
+        try {
+          results[index] = await git.raw(args);
+        } catch (error) {
+          // `git diff --no-index` exits 1 whenever there are differences, which
+          // for a new file is always.
+          results[index] = error?.exitCode === 1 && error?.message ? error.message : '';
+        }
+      } catch {
+        results[index] = '';
+      }
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.min(concurrency, paths.length) }, worker));
+  return results;
+}
+
 export async function getRangeDiff(directory, { base, head, path: filePath, contextLines = 3 } = {}) {
   const { directoryPath, directoryGit, repoRoot, git } = await createRepositoryGitContext(directory);
   const baseRef = typeof base === 'string' ? base.trim() : '';

packages/web/server/lib/opencode/core-routes.js

@@ -1072,6 +1072,7 @@ export const registerCommonRequestMiddleware = (app, dependencies) => {
       req.path.startsWith('/api/permission-auto-accept') ||
       req.path.startsWith('/api/session-folders') ||
       req.path.startsWith('/api/small-model') ||
+      req.path.startsWith('/api/walkthrough') ||
       req.path.startsWith('/api/goals') ||
       req.path.startsWith('/api/text') ||
       req.path.startsWith('/api/voice') ||

packages/web/server/lib/opencode/feature-routes-runtime.js

@@ -1,6 +1,7 @@
 import { registerFsRoutes } from '../fs/routes.js';
 import { registerQuotaRoutes } from '../quota/routes.js';
 import { registerSmallModelRoutes } from '../small-model/routes.js';
+import { registerWalkthroughRoutes } from '../walkthrough/routes.js';
 import { registerSessionGoalRoutes } from '../session-goal/routes.js';
 import { registerGitHubRoutes } from '../github/routes.js';
 import { registerGitRoutes } from '../git/routes.js';
@@ -67,6 +68,18 @@ export const createFeatureRoutesRuntime = (dependencies) => {
     return smallModelService;
   };
 
+  let walkthroughService = null;
+  const getWalkthroughService = async () => {
+    if (!walkthroughService) {
+      const [service, pullRequest] = await Promise.all([
+        import('../walkthrough/index.js'),
+        import('../walkthrough/pull-request.js'),
+      ]);
+      walkthroughService = { ...service, getPullRequestDiff: pullRequest.getPullRequestDiff };
+    }
+    return walkthroughService;
+  };
+
   const registerRoutes = async (app, routeDependencies) => {
     const {
       crypto,
@@ -264,6 +277,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
 
     registerQuotaRoutes(app, { getQuotaProviders });
     registerSmallModelRoutes(app, { getSmallModelService });
+    registerWalkthroughRoutes(app, { getWalkthroughService });
     registerSessionGoalRoutes(app);
     registerGitHubRoutes(app);
     registerGitRoutes(app);

packages/web/server/lib/opencode/settings-helpers.js

@@ -443,6 +443,10 @@ export const createSettingsHelpers = (dependencies) => {
       const trimmed = candidate.smallModelOverride.trim();
       result.smallModelOverride = trimmed.length > 0 ? trimmed : undefined;
     }
+    if (typeof candidate.walkthroughModelOverride === 'string') {
+      const trimmed = candidate.walkthroughModelOverride.trim();
+      result.walkthroughModelOverride = trimmed.length > 0 ? trimmed : undefined;
+    }
     if (typeof candidate.defaultGitIdentityId === 'string') {
       const trimmed = candidate.defaultGitIdentityId.trim();
       result.defaultGitIdentityId = trimmed.length > 0 ? trimmed : undefined;

packages/web/server/lib/small-model/DOCUMENTATION.md

@@ -31,10 +31,43 @@ other runtime API.
      and as a final utility fallback.
   4. Last resort: the session's own model (`preferredModelID`) when no small
      model resolves anywhere — costlier, but always valid.
-- Input clamp: the prompt is truncated to the resolved model's catalog
+- Input clamp: the prompt is measured against the resolved model's catalog
   `limit.context` (minus an output reserve, ~4 chars/token estimate;
-  conservative default when the model is not in the catalog). Truncation is
-  reported as `inputTruncated: true` in the response.
+  conservative default when the model is not in the catalog). `onOverflow`
+  decides what an oversized prompt means:
+  - `truncate` (default) clips the tail and reports `inputTruncated: true`.
+    Correct for callers that degrade gracefully (summaries, commit messages).
+  - `error` throws a `413` with `code: 'context-too-small'` plus
+    `requiredChars`/`availableChars`. Correct for callers whose output would be
+    quietly wrong on a clipped input, so they can ask the user for a roomier
+    model instead of returning confident nonsense.
+- Structured output: pass `responseSchema` (a JSON Schema) to get
+  schema-shaped JSON back as `text`. Wire support differs per format —
+  `response_format: {type: 'json_schema'}` for OpenAI-compatible chat,
+  `text.format` for the Responses API, a forced single tool call for the
+  Anthropic messages API, and `generationConfig.responseSchema` for Google
+  (whose OpenAPI-flavored dialect drops unknown JSON Schema keywords). The
+  ChatGPT-plan codex backend has no equivalent and rejects a schema request
+  with `code: 'structured-output-unsupported'` rather than silently returning
+  prose.
+- Output budget: `maxOutputTokens` is capped at the catalog's `limit.output` for
+  the model, and the **same number** is reserved from the input allowance. The
+  two must not drift — a caller that asks for a large answer while the reserve
+  stays at the default overruns the context, and the failure looks like a
+  truncation bug rather than a budgeting one. `describeSmallModel` takes
+  `outputReserveTokens` so readiness checks agree with what generation will do.
+- Reasoning models can spend the entire output budget thinking and return
+  nothing. That case (empty content with `finish_reason: 'length'`, or content
+  empty while `reasoning_content` is populated) throws with
+  `code: 'output-exhausted'` so callers can offer a different model instead of
+  showing a transport error.
+- `timeoutMs` overrides the 60s default per call; `signal` lets a caller abort
+  a request that is no longer wanted. Both apply to every wire format.
+- `describeSmallModel()` additionally reports `inputCharBudget`,
+  `contextTokens`, `contextKnown`, and `structuredOutput`. The last is
+  tri-state: `true`/`false` from the catalog, `null` when the catalog omits the
+  field — which it does for roughly half of all models, aggregators and proxies
+  especially. Callers must treat `null` as "try it", not "unsupported".
 - `call.js` — wire formats and per-provider auth, replicating OpenCode's
   plugin auth loaders:
   - **GitHub Copilot**: fetches the requested model's authenticated `/models`

packages/web/server/lib/small-model/call.js

@@ -25,7 +25,44 @@ const CODEX_RESPONSES_URL = 'https://chatgpt.com/backend-api/codex/responses';
 const httpError = async (response, provider) => {
   const body = await response.text().catch(() => '');
   const snippet = body ? `: ${body.slice(0, 300)}` : '';
-  return new Error(`${provider} request failed with ${response.status}${snippet}`);
+  // Callers need the status to tell "this provider rejected the request shape"
+  // (retryable with a different shape) from "this provider is down".
+  return Object.assign(new Error(`${provider} request failed with ${response.status}${snippet}`), {
+    status: response.status,
+    provider,
+  });
+};
+
+// Callers own two independent reasons to stop: their own abort signal (user
+// navigated away, request cancelled) and a per-call deadline. Long-running
+// callers such as the diff walkthrough need a deadline well past the default.
+const requestSignal = (timeoutMs, signal) => {
+  const deadline = AbortSignal.timeout(Number(timeoutMs) > 0 ? Number(timeoutMs) : REQUEST_TIMEOUT_MS);
+  return signal ? AbortSignal.any([deadline, signal]) : deadline;
+};
+
+const STRUCTURED_OUTPUT_NAME = 'response';
+
+// Google's schema dialect is OpenAPI-flavored and rejects JSON Schema keywords
+// it does not know, so unsupported keys are dropped rather than passed through.
+const GOOGLE_UNSUPPORTED_SCHEMA_KEYS = new Set([
+  '$schema',
+  'additionalProperties',
+  'definitions',
+  '$defs',
+  '$ref',
+  'strict',
+]);
+
+const toGoogleSchema = (schema) => {
+  if (Array.isArray(schema)) return schema.map(toGoogleSchema);
+  if (!schema || typeof schema !== 'object') return schema;
+  const result = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (GOOGLE_UNSUPPORTED_SCHEMA_KEYS.has(key)) continue;
+    result[key] = toGoogleSchema(value);
+  }
+  return result;
 };
 
 // ---------------------------------------------------------------------------
@@ -106,7 +143,7 @@ const ensureFreshOpenaiOauth = async (entry) => {
 // Wire formats
 // ---------------------------------------------------------------------------
 
-const callOpenaiCompatible = async ({ baseURL, headers, modelID, prompt, system, maxOutputTokens, providerLabel, extraBody }) => {
+const callOpenaiCompatible = async ({ baseURL, headers, modelID, prompt, system, maxOutputTokens, providerLabel, extraBody, responseSchema, timeoutMs, signal }) => {
   const trimmedBase = baseURL.replace(/\/+$/, '');
   console.log('[small-model:diagnostic] request', {
     provider: providerLabel,
@@ -132,9 +169,17 @@ const callOpenaiCompatible = async ({ baseURL, headers, modelID, prompt, system,
       ],
       max_tokens: maxOutputTokens,
       stream: false,
+      ...(responseSchema
+        ? {
+          response_format: {
+            type: 'json_schema',
+            json_schema: { name: STRUCTURED_OUTPUT_NAME, strict: true, schema: responseSchema },
+          },
+        }
+        : {}),
       ...(extraBody || {}),
     }),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    signal: requestSignal(timeoutMs, signal),
   });
   console.log('[small-model:diagnostic] response', {
     provider: providerLabel,
@@ -171,11 +216,16 @@ const callOpenaiCompatible = async ({ baseURL, headers, modelID, prompt, system,
       .map((part) => (typeof part?.text === 'string' ? part.text : ''))
       .join('');
   }
-  if (!text.trim() && typeof message?.reasoning_content === 'string' && message.reasoning_content.trim()) {
-    const finishReason = payload?.choices?.[0]?.finish_reason;
-    throw new Error(
-      `${providerLabel} spent the output budget on reasoning and returned no answer`
-      + (finishReason ? ` (finish_reason: ${finishReason})` : ''),
+  const finishReason = payload?.choices?.[0]?.finish_reason;
+  if (!text.trim() && (finishReason === 'length' || (typeof message?.reasoning_content === 'string' && message.reasoning_content.trim()))) {
+    // The model produced only reasoning, or was cut off before answering. This
+    // is a budget problem, not a transport problem, and callers can act on it.
+    throw Object.assign(
+      new Error(
+        `${providerLabel} spent the output budget on reasoning and returned no answer`
+        + (finishReason ? ` (finish_reason: ${finishReason})` : ''),
+      ),
+      { code: 'output-exhausted', provider: providerLabel },
     );
   }
   if (!text.trim()) {
@@ -184,7 +234,7 @@ const callOpenaiCompatible = async ({ baseURL, headers, modelID, prompt, system,
   return text;
 };
 
-const callOpenaiResponses = async ({ baseURL, headers, modelID, prompt, system, maxOutputTokens, providerLabel }) => {
+const callOpenaiResponses = async ({ baseURL, headers, modelID, prompt, system, maxOutputTokens, providerLabel, responseSchema, timeoutMs, signal }) => {
   const trimmedBase = baseURL.replace(/\/+$/, '');
   const response = await fetch(`${trimmedBase}/responses`, {
     method: 'POST',
@@ -201,10 +251,22 @@ const callOpenaiResponses = async ({ baseURL, headers, modelID, prompt, system,
         content: [{ type: 'input_text', text: prompt }],
       }],
       max_output_tokens: maxOutputTokens,
+      ...(responseSchema
+        ? {
+          text: {
+            format: {
+              type: 'json_schema',
+              name: STRUCTURED_OUTPUT_NAME,
+              strict: true,
+              schema: responseSchema,
+            },
+          },
+        }
+        : {}),
       stream: false,
       store: false,
     }),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    signal: requestSignal(timeoutMs, signal),
   });
   if (!response.ok) {
     throw await httpError(response, providerLabel);
@@ -224,7 +286,7 @@ const callOpenaiResponses = async ({ baseURL, headers, modelID, prompt, system,
   return text;
 };
 
-const callMessages = async ({ url, headers, modelID, prompt, system, maxOutputTokens, providerLabel }) => {
+const callMessages = async ({ url, headers, modelID, prompt, system, maxOutputTokens, providerLabel, responseSchema, timeoutMs, signal }) => {
   const response = await fetch(url, {
     method: 'POST',
     headers: {
@@ -237,13 +299,36 @@ const callMessages = async ({ url, headers, modelID, prompt, system, maxOutputTo
       max_tokens: maxOutputTokens,
       ...(system ? { system } : {}),
       messages: [{ role: 'user', content: prompt }],
+      // The messages API has no response_format; a forced single-tool call is
+      // the supported way to get schema-shaped output.
+      ...(responseSchema
+        ? {
+          tools: [{
+            name: STRUCTURED_OUTPUT_NAME,
+            description: 'Return the answer in the required structure.',
+            input_schema: responseSchema,
+          }],
+          tool_choice: { type: 'tool', name: STRUCTURED_OUTPUT_NAME },
+        }
+        : {}),
     }),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    signal: requestSignal(timeoutMs, signal),
   });
   if (!response.ok) {
     throw await httpError(response, providerLabel);
   }
   const payload = await response.json();
+
+  if (responseSchema) {
+    const toolUse = (payload?.content || []).find(
+      (part) => part?.type === 'tool_use' && part.name === STRUCTURED_OUTPUT_NAME,
+    );
+    if (!toolUse || typeof toolUse.input !== 'object' || toolUse.input === null) {
+      throw new Error(`${providerLabel} returned no structured output`);
+    }
+    return JSON.stringify(toolUse.input);
+  }
+
   const text = (payload?.content || [])
     .filter((part) => part?.type === 'text' && typeof part.text === 'string')
     .map((part) => part.text)
@@ -254,7 +339,7 @@ const callMessages = async ({ url, headers, modelID, prompt, system, maxOutputTo
   return text;
 };
 
-const callAnthropic = async ({ apiKey, modelID, prompt, system, maxOutputTokens }) => callMessages({
+const callAnthropic = async ({ apiKey, modelID, prompt, system, maxOutputTokens, responseSchema, timeoutMs, signal }) => callMessages({
   url: 'https://api.anthropic.com/v1/messages',
   headers: {
     'x-api-key': apiKey,
@@ -265,6 +350,9 @@ const callAnthropic = async ({ apiKey, modelID, prompt, system, maxOutputTokens
   system,
   maxOutputTokens,
   providerLabel: 'Anthropic',
+  responseSchema,
+  timeoutMs,
+  signal,
 });
 
 const getCopilotEndpoint = async ({ baseURL, headers, modelID }) => {
@@ -312,7 +400,7 @@ const getCopilotEndpoint = async ({ baseURL, headers, modelID }) => {
   throw new Error(`GitHub Copilot model "${modelID}" has no supported text endpoint`);
 };
 
-const callGoogle = async ({ apiKey, modelID, prompt, system, maxOutputTokens }) => {
+const callGoogle = async ({ apiKey, modelID, prompt, system, maxOutputTokens, responseSchema, timeoutMs, signal }) => {
   const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(modelID)}:generateContent`;
   const thinkingConfig = modelID.toLowerCase().startsWith('gemini-3')
     ? { thinkingLevel: modelID.toLowerCase().includes('flash') ? 'minimal' : 'low' }
@@ -327,9 +415,15 @@ const callGoogle = async ({ apiKey, modelID, prompt, system, maxOutputTokens })
     body: JSON.stringify({
       contents: [{ role: 'user', parts: [{ text: prompt }] }],
       ...(system ? { systemInstruction: { parts: [{ text: system }] } } : {}),
-      generationConfig: { maxOutputTokens, thinkingConfig },
+      generationConfig: {
+        maxOutputTokens,
+        thinkingConfig,
+        ...(responseSchema
+          ? { responseMimeType: 'application/json', responseSchema: toGoogleSchema(responseSchema) }
+          : {}),
+      },
     }),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    signal: requestSignal(timeoutMs, signal),
   });
   if (!response.ok) {
     throw await httpError(response, 'Google');
@@ -346,7 +440,7 @@ const callGoogle = async ({ apiKey, modelID, prompt, system, maxOutputTokens })
 
 // ChatGPT-plan traffic goes to the codex backend, which only speaks the
 // streaming Responses API — collect the output_text deltas from the SSE body.
-const callCodexResponses = async ({ accessToken, accountId, modelID, prompt, system }) => {
+const callCodexResponses = async ({ accessToken, accountId, modelID, prompt, system, timeoutMs, signal }) => {
   const response = await fetch(CODEX_RESPONSES_URL, {
     method: 'POST',
     headers: {
@@ -372,7 +466,7 @@ const callCodexResponses = async ({ accessToken, accountId, modelID, prompt, sys
       stream: true,
       store: false,
     }),
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    signal: requestSignal(timeoutMs, signal),
   });
   if (!response.ok) {
     throw await httpError(response, 'OpenAI (ChatGPT plan)');
@@ -472,7 +566,7 @@ const readProviderConfig = (workingDirectory, providerID) => {
 // Dispatch
 // ---------------------------------------------------------------------------
 
-export async function callSmallModel({ auth, catalog, workingDirectory, providerID, modelID, prompt, system, maxOutputTokens }) {
+export async function callSmallModel({ auth, catalog, workingDirectory, providerID, modelID, prompt, system, maxOutputTokens, responseSchema, timeoutMs, signal }) {
   const tokens = Number(maxOutputTokens) > 0 ? Number(maxOutputTokens) : DEFAULT_MAX_OUTPUT_TOKENS;
   const providerConfig = readProviderConfig(workingDirectory, providerID);
   // Match OpenCode's resolveSDK precedence:
@@ -516,6 +610,9 @@ export async function callSmallModel({ auth, catalog, workingDirectory, provider
       system,
       maxOutputTokens: tokens,
       providerLabel: 'GitHub Copilot',
+      responseSchema,
+      timeoutMs,
+      signal,
     };
     if (endpoint === 'messages') {
       return callMessages({
@@ -534,6 +631,15 @@ export async function callSmallModel({ auth, catalog, workingDirectory, provider
   }
 
   if (providerID === 'openai' && entry.type === 'oauth') {
+    // The codex backend speaks only the streaming Responses API and rejects
+    // the structured-output fields, so a schema request fails loudly here
+    // instead of silently returning free-form prose.
+    if (responseSchema) {
+      throw Object.assign(
+        new Error('The ChatGPT-plan OpenAI login does not support structured output — choose another small model'),
+        { code: 'structured-output-unsupported' },
+      );
+    }
     const fresh = await ensureFreshOpenaiOauth(entry);
     return callCodexResponses({
       accessToken: fresh.access,
@@ -541,6 +647,8 @@ export async function callSmallModel({ auth, catalog, workingDirectory, provider
       modelID,
       prompt,
       system,
+      timeoutMs,
+      signal,
     });
   }
 
@@ -552,10 +660,10 @@ export async function callSmallModel({ auth, catalog, workingDirectory, provider
   }
 
   if (providerID === 'anthropic') {
-    return callAnthropic({ apiKey, modelID, prompt, system, maxOutputTokens: tokens });
+    return callAnthropic({ apiKey, modelID, prompt, system, maxOutputTokens: tokens, responseSchema, timeoutMs, signal });
   }
   if (providerID === 'google') {
-    return callGoogle({ apiKey, modelID, prompt, system, maxOutputTokens: tokens });
+    return callGoogle({ apiKey, modelID, prompt, system, maxOutputTokens: tokens, responseSchema, timeoutMs, signal });
   }
 
   // Everything else: OpenAI-compatible chat completions against the catalog's
@@ -600,5 +708,8 @@ export async function callSmallModel({ auth, catalog, workingDirectory, provider
     maxOutputTokens: tokens,
     providerLabel: provider?.name || providerID,
     extraBody,
+    responseSchema,
+    timeoutMs,
+    signal,
   });
 }

packages/web/server/lib/small-model/call.test.js

@@ -635,3 +635,156 @@ describe('callSmallModel — GitHub Copilot endpoint routing', () => {
     expect(fetchMock).toHaveBeenCalledTimes(1);
   });
 });
+
+// Structured output has no single wire format: each provider family needs its
+// own request shape and its own extraction, and one family cannot do it at all.
+// These lock the per-format translation so a provider is never silently sent a
+// schema it will ignore.
+describe('callSmallModel — structured output', () => {
+  let fetchMock;
+  let originalFetch;
+
+  const SCHEMA = {
+    type: 'object',
+    properties: { title: { type: 'string' } },
+    required: ['title'],
+    additionalProperties: false,
+  };
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = fetchMock;
+    readConfig.mockReset();
+    readConfig.mockReturnValue({});
+    readConfigLayers.mockReset();
+    readConfigLayers.mockReturnValue({ mergedConfig: {} });
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('sends a json_schema response_format on OpenAI-compatible chat', async () => {
+    fetchMock.mockResolvedValue(ok('{"title":"ok"}'));
+
+    const text = await callSmallModel({
+      auth: { openai: { type: 'api', key: 'sk-test' } },
+      catalog: {},
+      workingDirectory: '/proj',
+      providerID: 'openai',
+      modelID: 'gpt-5.4-mini',
+      prompt: 'summarize',
+      responseSchema: SCHEMA,
+    });
+
+    expect(text).toBe('{"title":"ok"}');
+    const body = JSON.parse(lastCall(fetchMock).init.body);
+    expect(body.response_format).toEqual({
+      type: 'json_schema',
+      json_schema: { name: 'response', strict: true, schema: SCHEMA },
+    });
+  });
+
+  it('omits response_format entirely when no schema is requested', async () => {
+    fetchMock.mockResolvedValue(ok('plain text'));
+
+    await callSmallModel({
+      auth: { openai: { type: 'api', key: 'sk-test' } },
+      catalog: {},
+      workingDirectory: '/proj',
+      providerID: 'openai',
+      modelID: 'gpt-5.4-mini',
+      prompt: 'summarize',
+    });
+
+    const body = JSON.parse(lastCall(fetchMock).init.body);
+    expect(body.response_format).toBeUndefined();
+  });
+
+  it('forces a single tool call on the Anthropic messages API and returns its input', async () => {
+    fetchMock.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        content: [
+          { type: 'text', text: 'thinking out loud' },
+          { type: 'tool_use', name: 'response', input: { title: 'ok' } },
+        ],
+      }),
+    });
+
+    const text = await callSmallModel({
+      auth: { anthropic: { type: 'api', key: 'sk-ant' } },
+      catalog: {},
+      workingDirectory: '/proj',
+      providerID: 'anthropic',
+      modelID: 'claude-haiku-4-5',
+      prompt: 'summarize',
+      responseSchema: SCHEMA,
+    });
+
+    expect(JSON.parse(text)).toEqual({ title: 'ok' });
+    const body = JSON.parse(lastCall(fetchMock).init.body);
+    expect(body.tool_choice).toEqual({ type: 'tool', name: 'response' });
+    expect(body.tools[0].input_schema).toEqual(SCHEMA);
+  });
+
+  it('fails loudly when Anthropic answers with prose instead of the tool call', async () => {
+    fetchMock.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ content: [{ type: 'text', text: 'here you go' }] }),
+    });
+
+    await expect(callSmallModel({
+      auth: { anthropic: { type: 'api', key: 'sk-ant' } },
+      catalog: {},
+      workingDirectory: '/proj',
+      providerID: 'anthropic',
+      modelID: 'claude-haiku-4-5',
+      prompt: 'summarize',
+      responseSchema: SCHEMA,
+    })).rejects.toThrow('returned no structured output');
+  });
+
+  it('strips JSON Schema keywords Google rejects', async () => {
+    fetchMock.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ candidates: [{ content: { parts: [{ text: '{"title":"ok"}' }] } }] }),
+    });
+
+    await callSmallModel({
+      auth: { google: { type: 'api', key: 'google-key' } },
+      catalog: {},
+      workingDirectory: '/proj',
+      providerID: 'google',
+      modelID: 'gemini-2.5-flash',
+      prompt: 'summarize',
+      responseSchema: { ...SCHEMA, $schema: 'https://json-schema.org/draft/2020-12/schema' },
+    });
+
+    const body = JSON.parse(lastCall(fetchMock).init.body);
+    expect(body.generationConfig.responseMimeType).toBe('application/json');
+    expect(body.generationConfig.responseSchema).toEqual({
+      type: 'object',
+      properties: { title: { type: 'string' } },
+      required: ['title'],
+    });
+  });
+
+  it('refuses a schema on the ChatGPT-plan backend instead of returning prose', async () => {
+    await expect(callSmallModel({
+      auth: { openai: { type: 'oauth', access: 'token', refresh: 'refresh' } },
+      catalog: {},
+      workingDirectory: '/proj',
+      providerID: 'openai',
+      modelID: 'gpt-5.4-mini',
+      prompt: 'summarize',
+      responseSchema: SCHEMA,
+    })).rejects.toThrow('does not support structured output');
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

packages/web/server/lib/small-model/index.js

@@ -36,14 +36,46 @@ const readSmallModelSettingsOverride = () => {
 const DEFAULT_CONTEXT_TOKENS = 64_000;
 const OUTPUT_RESERVE_TOKENS = 4_000;
 
-const clampPromptToModelLimit = ({ prompt, catalog, providerID, modelID }) => {
+/**
+ * Input budget in characters, given how much of the context the caller intends
+ * to leave for the answer. The reserve must match the output budget the caller
+ * will actually request, or the two disagree and the model overruns its context.
+ */
+export const getModelInputCharBudget = ({ catalog, providerID, modelID, outputReserveTokens }) => {
   const limit = catalog?.[providerID]?.models?.[modelID]?.limit;
-  const contextTokens = Number(limit?.context) > 0 ? Number(limit.context) : DEFAULT_CONTEXT_TOKENS;
-  const inputBudgetTokens = Math.max(1_000, contextTokens - OUTPUT_RESERVE_TOKENS);
-  const maxChars = inputBudgetTokens * 4;
+  const known = Number(limit?.context) > 0;
+  const contextTokens = known ? Number(limit.context) : DEFAULT_CONTEXT_TOKENS;
+  const reserve = Number(outputReserveTokens) > 0 ? Number(outputReserveTokens) : OUTPUT_RESERVE_TOKENS;
+  const inputBudgetTokens = Math.max(1_000, contextTokens - reserve);
+  return { maxChars: inputBudgetTokens * 4, contextTokens, contextKnown: known };
+};
+
+/**
+ * The output budget to actually request: what the caller asked for, capped by
+ * what the model admits it can emit. Asking for more than `limit.output` is
+ * rejected outright by some providers and silently ignored by others.
+ */
+const resolveOutputTokens = ({ catalog, providerID, modelID, maxOutputTokens }) => {
+  const requested = Number(maxOutputTokens) > 0 ? Number(maxOutputTokens) : 0;
+  if (!requested) return undefined;
+  const limit = Number(catalog?.[providerID]?.models?.[modelID]?.limit?.output);
+  return limit > 0 ? Math.min(requested, limit) : requested;
+};
+
+// `truncate` keeps the historical behavior for callers whose prompt losing its
+// tail is survivable (summaries, commit messages). `error` is for callers whose
+// output would be quietly wrong on a clipped input — they need the failure.
+const clampPromptToModelLimit = ({ prompt, catalog, providerID, modelID, onOverflow, outputReserveTokens }) => {
+  const { maxChars } = getModelInputCharBudget({ catalog, providerID, modelID, outputReserveTokens });
   if (prompt.length <= maxChars) {
     return { prompt, truncated: false };
   }
+  if (onOverflow === 'error') {
+    throw Object.assign(
+      new Error(`Input is too large for ${providerID}/${modelID}: ${prompt.length} characters exceeds the ${maxChars} the model's context allows`),
+      { statusCode: 413, code: 'context-too-small', providerID, modelID, requiredChars: prompt.length, availableChars: maxChars },
+    );
+  }
   return { prompt: `${prompt.slice(0, maxChars)}…`, truncated: true };
 };
 
@@ -61,7 +93,7 @@ const readConfiguredSmallModel = (workingDirectory) => {
  * Generates text with the user's small model, resolved and authenticated
  * entirely server-side from the OpenCode config and auth store.
  */
-export async function generateSmallModelText({ prompt, system, maxOutputTokens, model, directory, preferredProviderID, preferredModelID, restrictToPreferredProvider = false }) {
+export async function generateSmallModelText({ prompt, system, maxOutputTokens, model, directory, preferredProviderID, preferredModelID, restrictToPreferredProvider = false, responseSchema, timeoutMs, signal, onOverflow = 'truncate' }) {
   if (typeof prompt !== 'string' || !prompt.trim()) {
     throw Object.assign(new Error('prompt is required'), { statusCode: 400 });
   }
@@ -101,11 +133,20 @@ export async function generateSmallModelText({ prompt, system, maxOutputTokens,
     );
   }
 
+  const outputTokens = resolveOutputTokens({
+    catalog,
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    maxOutputTokens,
+  });
+
   const clamped = clampPromptToModelLimit({
     prompt: prompt.trim(),
     catalog,
     providerID: resolved.providerID,
     modelID: resolved.modelID,
+    onOverflow,
+    outputReserveTokens: outputTokens,
   });
 
   const text = await callSmallModel({
@@ -116,7 +157,10 @@ export async function generateSmallModelText({ prompt, system, maxOutputTokens,
     modelID: resolved.modelID,
     prompt: clamped.prompt,
     system: typeof system === 'string' && system.trim() ? system.trim() : undefined,
-    maxOutputTokens,
+    maxOutputTokens: outputTokens,
+    responseSchema,
+    timeoutMs,
+    signal,
   });
 
   return {
@@ -152,17 +196,47 @@ export function listAuthenticatedProviders() {
 
 /**
  * Reports which model would be used, without calling it.
+ *
+ * `inputCharBudget` and `structuredOutput` let callers refuse work before
+ * spending a request: the walkthrough needs both a big enough context and
+ * schema-shaped output, and would rather tell the user to pick another model
+ * than send a doomed prompt. `structuredOutput` is deliberately tri-state —
+ * the catalog omits the field for roughly half of all models (aggregators and
+ * proxies especially), and treating "unknown" as "unsupported" would hide
+ * models that work fine.
  */
-export async function describeSmallModel({ directory, preferredProviderID, preferredModelID } = {}) {
+export async function describeSmallModel({ directory, preferredProviderID, preferredModelID, outputReserveTokens, overrideModel } = {}) {
   const auth = readAuthFile();
   const catalog = await getModelCatalog().catch(() => ({}));
-  const resolved = resolveSmallModel({
-    auth,
+  // A caller with its own model setting (the diff walkthrough) outranks the
+  // small-model chain entirely — it asked for this model on purpose.
+  const explicit = parseModelRef(overrideModel);
+  const resolved = explicit
+    ? { ...explicit, source: 'request' }
+    : resolveSmallModel({
+      auth,
+      catalog,
+      settingsSmallModel: readSmallModelSettingsOverride(),
+      configSmallModel: readConfiguredSmallModel(directory),
+      preferredProviderID,
+      preferredModelID,
+    });
+  if (!resolved) return resolved;
+
+  const entry = catalog?.[resolved.providerID]?.models?.[resolved.modelID];
+  const { maxChars, contextTokens, contextKnown } = getModelInputCharBudget({
     catalog,
-    settingsSmallModel: readSmallModelSettingsOverride(),
-    configSmallModel: readConfiguredSmallModel(directory),
-    preferredProviderID,
-    preferredModelID,
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    outputReserveTokens,
   });
-  return resolved;
+
+  return {
+    ...resolved,
+    inputCharBudget: maxChars,
+    contextTokens,
+    contextKnown,
+    structuredOutput: typeof entry?.structured_output === 'boolean' ? entry.structured_output : null,
+    outputTokenLimit: Number(entry?.limit?.output) > 0 ? Number(entry.limit.output) : null,
+  };
 }

packages/web/server/lib/small-model/index.test.js

@@ -0,0 +1,221 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// The settings override is read straight from disk at module load, so without
+// this the suite would resolve whatever small model the developer running it
+// happens to have configured.
+const TEMP_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'small-model-settings-'));
+process.env.OPENCHAMBER_DATA_DIR = TEMP_DATA_DIR;
+
+vi.mock('../opencode/auth.js', () => ({ readAuthFile: vi.fn() }));
+vi.mock('../opencode/shared.js', () => ({
+  readConfig: vi.fn(),
+  readConfigLayers: vi.fn(),
+}));
+vi.mock('./catalog.js', () => ({
+  getModelCatalog: vi.fn(),
+  getCatalogProvider: vi.fn(),
+}));
+vi.mock('./call.js', () => ({ callSmallModel: vi.fn() }));
+
+const { generateSmallModelText, describeSmallModel } = await import('./index.js');
+const { readAuthFile } = await import('../opencode/auth.js');
+const { readConfigLayers } = await import('../opencode/shared.js');
+const { getModelCatalog } = await import('./catalog.js');
+const { callSmallModel } = await import('./call.js');
+
+// 8k context leaves 4k input tokens after the output reserve → 16k chars.
+const CATALOG = {
+  anthropic: {
+    id: 'anthropic',
+    models: {
+      'claude-haiku-4-5': { id: 'claude-haiku-4-5', limit: { context: 8_000 }, structured_output: true },
+      'legacy-tiny': { id: 'legacy-tiny', limit: { context: 8_000 }, structured_output: false },
+      'unlisted-capability': { id: 'unlisted-capability', limit: { context: 8_000 } },
+    },
+  },
+};
+
+const request = (overrides = {}) => ({
+  prompt: 'x'.repeat(20_000),
+  model: 'anthropic/claude-haiku-4-5',
+  directory: '/proj',
+  ...overrides,
+});
+
+describe('generateSmallModelText — oversized input', () => {
+  beforeEach(() => {
+    readAuthFile.mockReturnValue({ anthropic: { type: 'api', key: 'sk-ant' } });
+    readConfigLayers.mockReturnValue({ mergedConfig: {} });
+    getModelCatalog.mockResolvedValue(CATALOG);
+    callSmallModel.mockReset();
+    callSmallModel.mockResolvedValue('generated');
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('truncates and flags the response by default', async () => {
+    const result = await generateSmallModelText(request());
+
+    expect(result.inputTruncated).toBe(true);
+    const sent = callSmallModel.mock.calls.at(-1)[0].prompt;
+    expect(sent.length).toBeLessThan(20_000);
+    expect(sent.endsWith('…')).toBe(true);
+  });
+
+  it('refuses without calling the provider when the caller cannot survive truncation', async () => {
+    await expect(generateSmallModelText(request({ onOverflow: 'error' })))
+      .rejects.toMatchObject({
+        statusCode: 413,
+        code: 'context-too-small',
+        requiredChars: 20_000,
+        availableChars: 16_000,
+      });
+
+    expect(callSmallModel).not.toHaveBeenCalled();
+  });
+
+  it('leaves an input that fits untouched under either policy', async () => {
+    const result = await generateSmallModelText(request({ prompt: 'short prompt', onOverflow: 'error' }));
+
+    expect(result.inputTruncated).toBeUndefined();
+    expect(callSmallModel.mock.calls.at(-1)[0].prompt).toBe('short prompt');
+  });
+
+  it('forwards schema, timeout, and abort signal to the transport', async () => {
+    const controller = new AbortController();
+    const schema = { type: 'object' };
+
+    await generateSmallModelText(request({
+      prompt: 'short',
+      responseSchema: schema,
+      timeoutMs: 240_000,
+      signal: controller.signal,
+    }));
+
+    expect(callSmallModel.mock.calls.at(-1)[0]).toMatchObject({
+      responseSchema: schema,
+      timeoutMs: 240_000,
+      signal: controller.signal,
+    });
+  });
+});
+
+describe('describeSmallModel — capability reporting', () => {
+  beforeEach(() => {
+    readAuthFile.mockReturnValue({ anthropic: { type: 'api', key: 'sk-ant' } });
+    readConfigLayers.mockReturnValue({ mergedConfig: { small_model: 'anthropic/claude-haiku-4-5' } });
+    getModelCatalog.mockResolvedValue(CATALOG);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('reports the input budget and a known structured-output capability', async () => {
+    const described = await describeSmallModel({ directory: '/proj' });
+
+    expect(described).toMatchObject({
+      providerID: 'anthropic',
+      modelID: 'claude-haiku-4-5',
+      inputCharBudget: 16_000,
+      contextTokens: 8_000,
+      contextKnown: true,
+      structuredOutput: true,
+    });
+  });
+
+  it('reports an explicit false so callers can block the model', async () => {
+    readConfigLayers.mockReturnValue({ mergedConfig: { small_model: 'anthropic/legacy-tiny' } });
+
+    const described = await describeSmallModel({ directory: '/proj' });
+
+    expect(described.structuredOutput).toBe(false);
+  });
+
+  it('reports null — not false — when the catalog omits the capability', async () => {
+    readConfigLayers.mockReturnValue({ mergedConfig: { small_model: 'anthropic/unlisted-capability' } });
+
+    const described = await describeSmallModel({ directory: '/proj' });
+
+    expect(described.structuredOutput).toBeNull();
+  });
+});
+
+// The input reserve and the requested output budget are the same number seen
+// from two sides; if they drift, a caller that asks for a large answer overruns
+// the model's context and the failure looks like a truncation bug.
+describe('output budget and input reserve', () => {
+  beforeEach(() => {
+    readAuthFile.mockReturnValue({ anthropic: { type: 'api', key: 'sk-ant' } });
+    readConfigLayers.mockReturnValue({ mergedConfig: {} });
+    getModelCatalog.mockResolvedValue({
+      anthropic: {
+        id: 'anthropic',
+        models: {
+          roomy: { id: 'roomy', limit: { context: 100_000, output: 8_000 } },
+          unlisted: { id: 'unlisted', limit: { context: 100_000 } },
+        },
+      },
+    });
+    callSmallModel.mockReset();
+    callSmallModel.mockResolvedValue('generated');
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('caps the request at the model\'s advertised output limit', async () => {
+    await generateSmallModelText({
+      prompt: 'short',
+      model: 'anthropic/roomy',
+      maxOutputTokens: 24_000,
+    });
+
+    expect(callSmallModel.mock.calls.at(-1)[0].maxOutputTokens).toBe(8_000);
+  });
+
+  it('honours the requested budget when the catalog states no output limit', async () => {
+    await generateSmallModelText({
+      prompt: 'short',
+      model: 'anthropic/unlisted',
+      maxOutputTokens: 24_000,
+    });
+
+    expect(callSmallModel.mock.calls.at(-1)[0].maxOutputTokens).toBe(24_000);
+  });
+
+  it('reserves exactly the requested output budget from the input allowance', async () => {
+    // 100k context − 24k reserved for the answer = 76k tokens ≈ 304k chars.
+    await expect(generateSmallModelText({
+      prompt: 'x'.repeat(304_001),
+      model: 'anthropic/unlisted',
+      maxOutputTokens: 24_000,
+      onOverflow: 'error',
+    })).rejects.toMatchObject({ code: 'context-too-small', availableChars: 304_000 });
+
+    await expect(generateSmallModelText({
+      prompt: 'x'.repeat(303_999),
+      model: 'anthropic/unlisted',
+      maxOutputTokens: 24_000,
+      onOverflow: 'error',
+    })).resolves.toBeTruthy();
+  });
+
+  it('reports the same budget through describeSmallModel', async () => {
+    readConfigLayers.mockReturnValue({ mergedConfig: { small_model: 'anthropic/unlisted' } });
+
+    const described = await describeSmallModel({ directory: '/proj', outputReserveTokens: 24_000 });
+
+    expect(described.inputCharBudget).toBe(304_000);
+  });
+});
+
+afterAll(() => {
+  fs.rmSync(TEMP_DATA_DIR, { recursive: true, force: true });
+});

packages/web/server/lib/small-model/routes.js

@@ -38,7 +38,10 @@ export function registerSmallModelRoutes(app, { getSmallModelService }) {
       if (statusCode >= 500) {
         console.error('Small model generation failed:', error);
       }
-      res.status(statusCode).json({ error: error.message || 'Small model generation failed' });
+      res.status(statusCode).json({
+        error: error.message || 'Small model generation failed',
+        ...(error?.code ? { code: error.code } : {}),
+      });
     }
   });
 }

packages/web/server/lib/walkthrough/DOCUMENTATION.md

@@ -0,0 +1,298 @@
+# Walkthrough
+
+Generates a guided, ordered reading path through a diff: the small model groups
+related hunks into stops and chapters and explains each group, and the UI
+renders those stops interleaved with the code they describe.
+
+Generation is **always user-initiated**. Nothing here runs on a timer, on a file
+change, or as a side effect of opening a panel — it spends tokens, so a person
+has to ask for it.
+
+## Files
+
+- `hunks.js` — parses a unified diff into files and hunks and assigns each hunk
+  a stable id.
+- `generated.js` — recognises tool-produced files that are kept out of the
+  model's input.
+- `sources.js` — turns a source descriptor into diff *sections*.
+- `digest.js` — builds the model-facing digest and the alias↔id mapping.
+- `prompt.js` — system prompt, size guidance, previous-walkthrough section, and
+  `PROMPT_VERSION`.
+- `schema.js` — response schema, response normalization, tolerant JSON parsing.
+- `store.js` — content-addressed cache entries plus mutable pointers.
+- `pull-request.js` — PR diffs via the shared GitHub octokit helper.
+- `model-settings.js` — the feature's own model override.
+- `index.js` — orchestration.
+- `routes.js` — `/api/walkthrough*`.
+
+## Hunk identity
+
+`hunks.js` is the only place that decides what a hunk is or what its id is. The
+client never recomputes ids; it receives the current hunk index (id → patch)
+alongside the walkthrough and matches ids to ids. Two implementations of the
+same hash would have to agree byte-for-byte forever, and the first one to drift
+would silently mis-anchor every stop.
+
+An id is `<scope>:<path>:<sha1(header + body)[:8]>`, with a `-2`, `-3`, … suffix
+for byte-identical hunks repeated inside one file.
+
+Two consequences fall out of hashing the content:
+
+- Editing a hunk changes its id, so an anchor that no longer resolves is
+  **proof** the code it described changed. Staleness needs no heuristics.
+- Editing one hunk does not disturb its neighbours, so a small edit invalidates
+  only the stops that actually covered it.
+
+`scope` keeps staged and unstaged versions of the same lines apart, so a stop
+written against staged code never silently re-anchors onto an unstaged edit.
+
+## Sources
+
+| Kind | Sections | Notes |
+|---|---|---|
+| `working-tree` (`all` \| `staged` \| `working`) | `staged`, `working` | Untracked files are fetched individually because `git diff` omits them |
+| `branch` | `branch` | `getRangeDiff` uses three-dot `base...head`, so work merged in from the base branch is excluded |
+| `pr` | `pr:<number>` | GitHub returns the merge-base diff, matching the branch semantics |
+
+The panel offers the current branch's pull request on its own: it registers with
+the shared GitHub PR status store (`useGitHubPrStatusStore`) rather than waiting
+for the pull request panel to have been visited. That store already dedupes
+concurrent requests by signature and throttles by TTL, so several panels asking
+the same question produce one call to GitHub.
+
+## No truncation
+
+Within what it covers, the digest is complete. When it does not fit the resolved
+model's context, generation is **refused** (`409`, `code: 'context-too-small'`)
+so the user can pick a roomier model. A walkthrough written against a silently
+clipped diff is confidently wrong in a way no reader can detect, which is worse
+than no walkthrough.
+
+## Generated files
+
+`generated.js` excludes tool-produced files — lockfiles, minified bundles,
+codegen, snapshots — from the digest by **name, never by size**. A lockfile can
+be larger than the entire change around it and carries no intent, so sending it
+wastes context that real code needs.
+
+They are excluded, not hidden: they carry no hunk aliases (so nothing can anchor
+to them), but they are still parsed, still returned to the client, and still
+appear in the uncovered tail. The matcher is deliberately conservative —
+`src/lock.ts` and `src/generator.ts` are authored code — because a false
+positive silently drops real code from a review, which is the exact failure this
+feature exists to prevent.
+
+When a change consists only of generated files, generation is refused with
+`code: 'only-generated'` rather than the misleading "nothing changed".
+
+## Model selection
+
+The walkthrough has its own model setting (Settings → Sessions → Changes
+Walkthrough Model), read by `model-settings.js`:
+
+`walkthroughModelOverride` (`provider/model`) is the whole contract: set, that
+model is used for this feature and nothing else; unset or empty, generation
+falls back to whatever the small-model chain resolves to. Choosing a model *is*
+the opt-out, so there is no separate toggle to disagree with the picker — the
+settings picker simply shows "Small model will be used" until a choice is made,
+and clearing it restores the fallback.
+
+The separation exists because the two roles pull in opposite directions: the
+small model is chosen to be cheap and fast for recaps and commit messages, while
+this one needs schema-shaped output and enough context for a whole diff. Forcing
+one setting to serve both means degrading one feature to fix the other.
+
+A review can also override the model for itself: `GET`/`POST` accept a `model`
+(`provider/model`) that outranks both the setting and the small-model chain.
+That choice is panel state, not a settings edit — picking a roomier model for
+one risky change should not silently redefine the default for every future one.
+It needs no storage: the model that produced a walkthrough is already recorded
+in its cache entry, so reopening a panel resolves the picker as *explicit choice
+→ model that generated what is on screen → settings*. Because the model is part
+of the cache key, switching models and back returns the earlier review for free.
+
+The picker hides models the catalog reports as `structured_output: false` —
+offering them would move the same refusal one click later — and, like the small
+model picker, only shows providers with a usable login. The in-panel picker on a
+blocked walkthrough writes this setting too, so recovering from a refusal never
+silently changes the model behind commit messages.
+
+## Structured output, and what happens when it is refused
+
+`structured_output: false` in the catalog blocks generation up front. A
+**missing** capability field does not block — the catalog omits it for roughly
+half of all models, and treating unknown as unsupported would hide models that
+work.
+
+Providers that do not declare the capability sometimes reject the schema at
+request time (a plain `400`, or Alibaba/Qwen's "'messages' must contain the word
+'json'"). A rejected request shape is not a dead end, so a `4xx` on a schema
+request triggers exactly one retry with the schema moved into the prompt and the
+tolerant parser handling the result. Only if *that* fails to yield usable JSON is
+`structured-output-unsupported` reported — at which point it is a real capability
+problem the user can fix by switching model.
+
+The refusal is then remembered per `provider/model` and the fallback goes first
+from then on. Without that, every generation on such a provider pays for a call
+whose failure is already known. The memory is process-lifetime only on purpose:
+a provider that gains structured-output support should not need a settings
+change to be tried again, and one wasted first attempt after a restart is cheap.
+
+The system prompt states "respond with a single JSON object" explicitly, which
+also satisfies the providers that scan the request for the word `json` before
+honouring `response_format`. That keeps them on the fast path instead of paying
+for a wasted first call.
+
+## Output budget
+
+Generation asks for 24k output tokens (capped per model by the catalog), and the
+input budget reserves exactly that much. A walkthrough itself is only a few
+thousand tokens of JSON — the headroom exists because reasoning models spend the
+same budget thinking first and return nothing when it runs out. When that still
+happens, `code: 'output-exhausted'` reports it as what it is: this model cannot
+finish this job, so pick another or review a narrower scope.
+
+## Caching and staleness
+
+**Cache entries** (`entries/<sha256>.json`) are immutable and content-addressed.
+The key covers walkthrough version, prompt version, repo root, source, provider,
+model, and every file's path/status/hunk-ids. The key is computed from the
+*current* diff, so a hit means the walkthrough was written about exactly this
+code; there is no freshness question to ask of an entry, because staleness is a
+miss. Returning the working tree to an earlier state therefore costs nothing.
+
+**Pointers** (`pointers/<sha256(repoRoot + source)>.json`) are mutable and hold
+`{ cacheKey, generatedAt, repoRoot, sourceKey }`. They answer what the cache
+cannot: which walkthrough was last shown here, and has the code moved since. A
+pointer whose entry has been evicted reads as "no walkthrough" — truthful, and
+the next generation overwrites it.
+
+Regeneration is manual and re-authors rather than merges: the previous
+walkthrough goes into the prompt as prose so the model can keep what is still
+true, with its anchors deliberately stripped so everything is re-anchored
+against the current digest. Splicing partially-regenerated chapters into an old
+narrative was considered and rejected — the seams produce stops that contradict
+each other, and the failure is invisible.
+
+## Hygiene
+
+- Entries are bounded by count and total size (200 / 50 MB) and evicted
+  least-recently-used after a write that crosses a limit. Nothing is dropped for
+  being merely old: an entry costs kilobytes and stays reachable if the working
+  tree ever returns to that state.
+- Writes are tmp+rename; reads enforce a size limit and validate the version, so
+  a corrupt file is a miss rather than a crash.
+- Pointers are never evicted by size. They are pruned only when their repository
+  is **provably gone**, deferred off the request path, fully asynchronous, and
+  capped.
+
+That last point is deliberate rather than incidental. The desktop app hosts this
+server inside the Electron main process, so a synchronous loop here would stall
+IPC and the window rather than a single request — and the paths being checked
+are user repositories, where a worktree on an unplugged drive or an unreachable
+share can make one existence check hang for seconds. Only `ENOENT` deletes a
+pointer: unreachable is not the same as gone, and a dead share must not cost the
+user their walkthroughs.
+
+## Coverage
+
+The model is told it may leave mechanical changes out. Whatever it does not
+anchor is computed as `uncoveredHunkIds` and rendered as a collapsed tail, so
+the reader can always answer "have I seen everything that changed". No hunk
+disappears from the view.
+
+## Cost of reading
+
+Opening the panel is a `GET` that runs the whole git pipeline, so it is kept as
+cheap as the data allows:
+
+- Untracked files come from `listUntrackedPaths` (a plain `ls-files`) rather
+  than `getStatus`, which also computes ahead/behind, diff stats, and merge
+  state — roughly 180ms of work for an answer this module discards.
+- Their diffs go through `getUntrackedDiffs`, which resolves the repository once
+  for the whole batch and bounds concurrency, instead of one `getDiff` per file
+  each re-resolving the repository.
+- Readiness is computed from the same diff as the walkthrough itself. It used to
+  be its own endpoint that the client called in parallel, which meant every
+  panel open ran the entire pipeline twice.
+
+On a working tree of 80 files and 138 hunks this took a panel open from ~800ms
+to ~340ms. Parsing and digest building are ~3ms of that; everything else is git.
+
+## Generation outlives its request
+
+A dropped connection and a deliberate cancel are indistinguishable at the
+socket, so tying generation to the request lifetime meant an accidental refresh
+threw away a minute of paid-for work. Instead:
+
+- Jobs live in a module-level map keyed by repository + source. A second
+  `generate` for the same source **attaches to the running job** rather than
+  starting a rival one — pressing the button again after a refresh costs
+  nothing extra.
+- Leaving the page detaches the client; the job finishes and writes its cache
+  entry, so coming back finds the result waiting.
+- `GET /api/walkthrough` reports `generating`, letting a returning client show
+  progress instead of an empty panel, and the client re-attaches so the result
+  lands somewhere.
+- Stopping is an explicit `POST /api/walkthrough/cancel`. That is the only thing
+  that aborts the model call.
+
+The cost of this is that a job everyone abandoned keeps spending until it
+finishes; the generation timeout bounds it.
+
+That timeout is a hang guard, not a pace-setter, and it scales with the diff:
+120s plus 1s per hunk, capped at 15 minutes. A fixed number made a three-hunk
+edit and a 500-hunk pull request wait the same, which guarded nothing in the
+small case and risked killing the big one just short of the finish line. It errs
+long on purpose — losing a nearly-complete generation costs real money, while an
+over-long deadline only holds a job slot. Note that the schema fallback can use
+the deadline twice, once per attempt.
+
+## Progress
+
+A running job records a coarse stage: `collecting` (reading the diff, which for
+a pull request is seconds of network), `asking`, `retrying` when a provider
+rejects the schema and the prompt-side fallback runs, and `assembling`.
+
+Only phases a person can wait on are named. Building the digest and reading the
+cache take single-digit milliseconds; giving them rows would imply progress that
+is not happening.
+
+`retrying` exists for diagnostics but is **not shown**: from outside it is the
+same wait on the same model, and naming our fallback only raises the question of
+what it is. The client folds it into `asking`.
+
+The client also paces the display, holding each step for a floor before
+revealing the next and keeping the list on screen briefly after the work ends.
+Assembling takes milliseconds, so without that the result replaces the list
+before the final step is ever seen finishing — naming a step the user never
+observes is worse than not naming it. The cost is well under a second at the end
+of a wait measured in minutes.
+
+`GET /api/walkthrough/progress` reads the job registry and nothing else — no git,
+no network — so the client can poll it once a second. The full read must never
+be used for this: it re-runs the whole git pipeline.
+
+## Routes
+
+- `GET /api/walkthrough?directory&source` — last walkthrough, the current hunk
+  index, staleness, and `readiness`. Never generates.
+- `POST /api/walkthrough/generate` — `{ directory, source, force }`. Survives
+  client disconnects; a concurrent call for the same source joins the running
+  job.
+- `GET /api/walkthrough/progress?directory&source` — the current stage, or
+  `null`. Memory-only and safe to poll.
+- `POST /api/walkthrough/cancel` — `{ directory, source }`; aborts a running
+  generation.
+
+There is deliberately no delete route: regeneration covers the need, and an
+endpoint nothing calls is a maintenance surface that rots untested.
+
+Registered lazily from `feature-routes-runtime.js`. `/api/walkthrough` is in the
+JSON body-parser allowlist in `core-routes.js`.
+
+## Runtime availability
+
+Web, desktop, and hosted mobile reach these routes normally. VS Code serves Git
+through its own bridge rather than the OpenChamber Git routes, so the feature is
+not offered there; the surface is also gated to tablet width and above.

packages/web/server/lib/walkthrough/digest.js

@@ -0,0 +1,73 @@
+import { isGeneratedArtifact } from './generated.js';
+import { parseDiffFiles } from './hunks.js';
+
+// The digest is what the model actually reads. Within what it covers there is
+// no truncation: a diff that does not fit the model's context is refused
+// upstream so the user can pick a roomier model, because a walkthrough written
+// against a silently clipped diff is confidently wrong in a way nobody can see.
+//
+// The one thing it does not cover is tool-produced files (lockfiles, minified
+// bundles, codegen). Those are excluded by name, not by size, and they are not
+// hidden — they carry no hunk aliases, so nothing can anchor to them, and they
+// surface in the uncovered tail like any other unreviewed change.
+
+/**
+ * Parse sections into files and build the model-facing digest.
+ *
+ * Hunks are exposed to the model as request-local aliases (`h1`, `h2`, …)
+ * rather than their real ids: the aliases are far cheaper in tokens, and a
+ * model cannot invent a plausible-looking id for a hunk that does not exist.
+ */
+export function buildDigest(sections) {
+  const files = [];
+  for (const section of sections) {
+    const parsed = parseDiffFiles(section.patch, section.scope);
+    for (const file of parsed.files) {
+      files.push({ ...file, scope: section.scope, generated: isGeneratedArtifact(file.path) });
+    }
+  }
+
+  const idByAlias = new Map();
+  const aliasById = new Map();
+  let counter = 0;
+
+  const digestFiles = files
+    .filter((file) => !file.generated)
+    .map((file) => ({
+      path: file.path,
+      ...(file.oldPath ? { oldPath: file.oldPath } : {}),
+      status: file.status,
+      ...(file.scope !== 'branch' && !file.scope.startsWith('pr:') ? { scope: file.scope } : {}),
+      ...(file.binary ? { binary: true } : {}),
+      hunks: file.hunks.map((hunk) => {
+        counter += 1;
+        const alias = `h${counter}`;
+        idByAlias.set(alias, hunk.id);
+        aliasById.set(hunk.id, alias);
+        return {
+          alias,
+          header: hunk.header,
+          oldLines: `${hunk.oldStart}-${hunk.oldStart + Math.max(0, hunk.oldLines - 1)}`,
+          newLines: `${hunk.newStart}-${hunk.newStart + Math.max(0, hunk.newLines - 1)}`,
+          added: hunk.added,
+          deleted: hunk.deleted,
+          patch: hunk.body,
+        };
+      }),
+    }));
+
+  const generatedFiles = files.filter((file) => file.generated);
+
+  return {
+    digest: { files: digestFiles },
+    files,
+    idByAlias,
+    aliasById,
+    // Reviewable counts: what the model is actually asked about. The excluded
+    // files still reach the client through `files`.
+    hunkCount: counter,
+    fileCount: digestFiles.length,
+    generatedFileCount: generatedFiles.length,
+    generatedPaths: generatedFiles.map((file) => file.path),
+  };
+}

packages/web/server/lib/walkthrough/digest.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { buildDigest } from './digest.js';
+import { isGeneratedArtifact } from './generated.js';
+
+const fileDiff = (path, body = '+const a = 1;') => `diff --git a/${path} b/${path}
+--- a/${path}
++++ b/${path}
+@@ -1,1 +1,2 @@
+${body}
+`;
+
+describe('isGeneratedArtifact', () => {
+  it('matches lockfiles by exact name anywhere in the tree', () => {
+    expect(isGeneratedArtifact('bun.lock')).toBe(true);
+    expect(isGeneratedArtifact('packages/web/package-lock.json')).toBe(true);
+    expect(isGeneratedArtifact('Cargo.lock')).toBe(true);
+    expect(isGeneratedArtifact('go.sum')).toBe(true);
+  });
+
+  it('matches conventional generated output', () => {
+    expect(isGeneratedArtifact('dist/app.min.js')).toBe(true);
+    expect(isGeneratedArtifact('src/api.generated.ts')).toBe(true);
+    expect(isGeneratedArtifact('proto/user.pb.go')).toBe(true);
+    expect(isGeneratedArtifact('src/__snapshots__/App.test.tsx.snap')).toBe(true);
+    expect(isGeneratedArtifact('src/generated/client.ts')).toBe(true);
+  });
+
+  it('does not match authored source that merely looks similar', () => {
+    // A false positive silently removes real code from the review, so these
+    // near-misses matter more than the hits.
+    expect(isGeneratedArtifact('src/lock.ts')).toBe(false);
+    expect(isGeneratedArtifact('src/useLockfile.ts')).toBe(false);
+    expect(isGeneratedArtifact('src/generator.ts')).toBe(false);
+    expect(isGeneratedArtifact('src/minifier.ts')).toBe(false);
+    expect(isGeneratedArtifact('packages/ui/src/lib/i18n/messages/en.ts')).toBe(false);
+  });
+});
+
+describe('buildDigest', () => {
+  const sections = [{
+    scope: 'working',
+    patch: [fileDiff('src/a.ts'), fileDiff('bun.lock', '+  "version": "2",'), fileDiff('src/b.ts')].join(''),
+  }];
+
+  it('keeps generated files out of what the model sees', () => {
+    const built = buildDigest(sections);
+
+    expect(built.digest.files.map((file) => file.path)).toEqual(['src/a.ts', 'src/b.ts']);
+    expect(JSON.stringify(built.digest)).not.toContain('bun.lock');
+    expect(built.fileCount).toBe(2);
+    expect(built.hunkCount).toBe(2);
+    expect(built.generatedFileCount).toBe(1);
+    expect(built.generatedPaths).toEqual(['bun.lock']);
+  });
+
+  it('still returns generated files to the client so nothing disappears', () => {
+    const built = buildDigest(sections);
+
+    expect(built.files.map((file) => file.path)).toEqual(['src/a.ts', 'bun.lock', 'src/b.ts']);
+    expect(built.files.find((file) => file.path === 'bun.lock')?.generated).toBe(true);
+  });
+
+  it('gives aliases only to reviewable hunks', () => {
+    const built = buildDigest(sections);
+    const aliased = [...built.idByAlias.values()];
+
+    expect([...built.idByAlias.keys()]).toEqual(['h1', 'h2']);
+    expect(aliased.some((id) => id.includes('bun.lock'))).toBe(false);
+  });
+
+  it('reports zero reviewable hunks when only generated files changed', () => {
+    const built = buildDigest([{ scope: 'working', patch: fileDiff('bun.lock', '+  "version": "2",') }]);
+
+    expect(built.hunkCount).toBe(0);
+    expect(built.files).toHaveLength(1);
+    expect(built.generatedFileCount).toBe(1);
+  });
+});

packages/web/server/lib/walkthrough/generated.js

@@ -0,0 +1,58 @@
+// Files that are produced by a tool rather than written by a person. Their
+// diffs are enormous, carry no intent, and are exactly the kind of content a
+// reviewer scrolls past — but they are still part of the change, so they are
+// never hidden: they are kept out of the model's input and shown in the
+// uncovered tail instead.
+
+const LOCKFILES = new Set([
+  'bun.lock',
+  'bun.lockb',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'composer.lock',
+  'Gemfile.lock',
+  'Pipfile.lock',
+  'poetry.lock',
+  'uv.lock',
+  'Cargo.lock',
+  'go.sum',
+  'mix.lock',
+  'pubspec.lock',
+  'flake.lock',
+  'gradle.lockfile',
+  'packages.lock.json',
+  'deno.lock',
+]);
+
+const GENERATED_PATTERNS = [
+  // Minified or bundled output committed to the repository.
+  /\.min\.(js|css)$/i,
+  /\.(js|css)\.map$/i,
+  // Conventional "this file is generated" naming.
+  /\.generated\.[^/]+$/i,
+  /\.gen\.[^/]+$/i,
+  /(^|\/)generated\//i,
+  // Protocol buffers and similar codegen.
+  /\.pb\.(go|ts|js)$/i,
+  /_pb2(_grpc)?\.py$/i,
+  /\.pb\.cc$|\.pb\.h$/i,
+  // Test snapshots.
+  /(^|\/)__snapshots__\//,
+  /\.snap$/,
+];
+
+/**
+ * Whether a path is a tool-produced artifact rather than authored source.
+ *
+ * Deliberately conservative: a false positive silently removes real code from
+ * the review, which is the failure this whole feature exists to prevent. Only
+ * unambiguous, conventional names qualify.
+ */
+export function isGeneratedArtifact(filePath) {
+  if (typeof filePath !== 'string' || !filePath) return false;
+  const name = filePath.split('/').pop() || '';
+  if (LOCKFILES.has(name)) return true;
+  return GENERATED_PATTERNS.some((pattern) => pattern.test(filePath));
+}

packages/web/server/lib/walkthrough/hunks.js

@@ -0,0 +1,166 @@
+import crypto from 'crypto';
+
+// Parsing a unified diff into addressable hunks lives here and only here. The
+// model anchors its narrative to hunk ids, the client resolves those ids back
+// to rendered code, and staleness is "an id the current diff no longer has" —
+// all three break the moment two implementations disagree about what an id is,
+// so the client is never given the algorithm, only the results.
+
+const FILE_HEADER = /^diff --git /;
+const HUNK_HEADER = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@(.*)$/;
+
+const shortHash = (value) => crypto.createHash('sha1').update(value).digest('hex').slice(0, 8);
+
+const parsePathsFromFileHeader = (line) => {
+  // `diff --git a/old b/new`, with either side quoted when it contains spaces.
+  const match = /^diff --git (?:"?a\/(.+?)"?) (?:"?b\/(.+?)"?)$/.exec(line);
+  if (!match) return null;
+  return { oldPath: match[1], newPath: match[2] };
+};
+
+const statusFromHeaderLines = (lines) => {
+  if (lines.some((line) => line.startsWith('new file mode'))) return 'added';
+  if (lines.some((line) => line.startsWith('deleted file mode'))) return 'deleted';
+  if (lines.some((line) => line.startsWith('rename from'))) return 'renamed';
+  return 'modified';
+};
+
+const isBinaryHeader = (lines) => lines.some((line) => line.startsWith('Binary files ') || line.startsWith('GIT binary patch'));
+
+/**
+ * Split a unified diff covering any number of files into files and hunks.
+ *
+ * @param {string} patch raw `git diff` output
+ * @param {string} scope opaque namespace for the ids (e.g. 'staged', 'branch').
+ *   Two scopes of the same repository can contain byte-identical hunks; the
+ *   scope keeps their ids distinct so a walkthrough written against staged
+ *   changes never silently resolves against unstaged ones.
+ * @returns {{files: Array<{path: string, oldPath: string|null, status: string, binary: boolean, hunks: Array<object>}>}}
+ */
+export function parseDiffFiles(patch, scope = 'diff') {
+  const text = typeof patch === 'string' ? patch : '';
+  if (!text.trim()) return { files: [] };
+
+  const lines = text.split(/\r?\n/);
+  const files = [];
+  let current = null;
+  let headerLines = [];
+  let hunk = null;
+
+  const closeHunk = () => {
+    if (!current || !hunk) return;
+    const body = hunk.lines.join('\n');
+    // The id covers the header and the body, so any edit to the hunk — even one
+    // that keeps its line numbers — produces a different id. That is what makes
+    // "this stop is stale" detectable without diffing narratives.
+    const digest = shortHash(`${hunk.header}\n${body}`);
+    const seen = current.hunkDigests.get(digest) ?? 0;
+    current.hunkDigests.set(digest, seen + 1);
+    // A file can legitimately contain byte-identical hunks (repeated boilerplate
+    // edits). Disambiguate by occurrence so ids stay unique without becoming
+    // positional for the common case.
+    const suffix = seen === 0 ? '' : `-${seen + 1}`;
+
+    current.hunks.push({
+      id: `${scope}:${current.path}:${digest}${suffix}`,
+      header: hunk.header,
+      oldStart: hunk.oldStart,
+      oldLines: hunk.oldLines,
+      newStart: hunk.newStart,
+      newLines: hunk.newLines,
+      added: hunk.added,
+      deleted: hunk.deleted,
+      patch: `${current.headerText}\n${hunk.header}\n${body}\n`,
+      body,
+    });
+    hunk = null;
+  };
+
+  const closeFile = () => {
+    closeHunk();
+    if (!current) return;
+    current.binary = current.binary || isBinaryHeader(headerLines);
+    delete current.hunkDigests;
+    files.push(current);
+    current = null;
+  };
+
+  for (const line of lines) {
+    if (FILE_HEADER.test(line)) {
+      closeFile();
+      headerLines = [line];
+      const paths = parsePathsFromFileHeader(line);
+      current = {
+        path: paths?.newPath || paths?.oldPath || '',
+        oldPath: paths && paths.oldPath !== paths.newPath ? paths.oldPath : null,
+        status: 'modified',
+        binary: false,
+        headerText: line,
+        hunks: [],
+        hunkDigests: new Map(),
+      };
+      continue;
+    }
+
+    if (!current) continue;
+
+    const hunkMatch = HUNK_HEADER.exec(line);
+    if (hunkMatch) {
+      closeHunk();
+      current.status = statusFromHeaderLines(headerLines);
+      current.headerText = headerLines.join('\n');
+      hunk = {
+        header: line,
+        oldStart: Number.parseInt(hunkMatch[1], 10),
+        oldLines: hunkMatch[2] === undefined ? 1 : Number.parseInt(hunkMatch[2], 10),
+        newStart: Number.parseInt(hunkMatch[3], 10),
+        newLines: hunkMatch[4] === undefined ? 1 : Number.parseInt(hunkMatch[4], 10),
+        added: 0,
+        deleted: 0,
+        lines: [],
+      };
+      continue;
+    }
+
+    if (!hunk) {
+      headerLines.push(line);
+      continue;
+    }
+
+    hunk.lines.push(line);
+    if (line.startsWith('+')) hunk.added += 1;
+    else if (line.startsWith('-')) hunk.deleted += 1;
+  }
+
+  closeFile();
+
+  return {
+    files: files.filter((file) => file.path),
+  };
+}
+
+/**
+ * Flatten parsed files into an id-keyed index for resolution and staleness
+ * checks.
+ */
+export function indexHunks(files) {
+  const index = new Map();
+  for (const file of files) {
+    for (const hunk of file.hunks) {
+      index.set(hunk.id, { ...hunk, path: file.path, status: file.status });
+    }
+  }
+  return index;
+}
+
+/**
+ * Every hunk id in the diff, in file-then-position order. Used to compute the
+ * "not covered by any stop" tail.
+ */
+export function listHunkIds(files) {
+  const ids = [];
+  for (const file of files) {
+    for (const hunk of file.hunks) ids.push(hunk.id);
+  }
+  return ids;
+}

packages/web/server/lib/walkthrough/hunks.test.js

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import { parseDiffFiles, indexHunks, listHunkIds } from './hunks.js';
+
+const TWO_FILE_DIFF = `diff --git a/src/a.ts b/src/a.ts
+index 1111111..2222222 100644
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,3 +1,4 @@
+ const a = 1;
++const b = 2;
+ const c = 3;
+ const d = 4;
+@@ -20,2 +21,2 @@
+-const old = true;
++const next = true;
+diff --git a/src/b.ts b/src/b.ts
+new file mode 100644
+index 0000000..3333333
+--- /dev/null
++++ b/src/b.ts
+@@ -0,0 +1,2 @@
++export const x = 1;
++export const y = 2;
+`;
+
+describe('parseDiffFiles', () => {
+  it('splits files and hunks with line ranges and counts', () => {
+    const { files } = parseDiffFiles(TWO_FILE_DIFF, 'working');
+
+    expect(files.map((file) => file.path)).toEqual(['src/a.ts', 'src/b.ts']);
+    expect(files[0].hunks).toHaveLength(2);
+    expect(files[0].hunks[0]).toMatchObject({
+      oldStart: 1,
+      oldLines: 3,
+      newStart: 1,
+      newLines: 4,
+      added: 1,
+      deleted: 0,
+    });
+    expect(files[0].hunks[1]).toMatchObject({ added: 1, deleted: 1 });
+    expect(files[1].status).toBe('added');
+    expect(files[1].hunks[0]).toMatchObject({ added: 2, deleted: 0 });
+  });
+
+  it('produces a standalone applicable patch per hunk', () => {
+    const { files } = parseDiffFiles(TWO_FILE_DIFF, 'working');
+    const patch = files[0].hunks[1].patch;
+
+    expect(patch.startsWith('diff --git a/src/a.ts b/src/a.ts')).toBe(true);
+    expect(patch).toContain('--- a/src/a.ts');
+    expect(patch).toContain('+++ b/src/a.ts');
+    expect((patch.match(/^@@/gm) || [])).toHaveLength(1);
+    expect(patch).toContain('+const next = true;');
+    expect(patch).not.toContain('const b = 2;');
+  });
+
+  it('keeps ids stable across reparses of identical input', () => {
+    const first = listHunkIds(parseDiffFiles(TWO_FILE_DIFF, 'working').files);
+    const second = listHunkIds(parseDiffFiles(TWO_FILE_DIFF, 'working').files);
+
+    expect(first).toEqual(second);
+    expect(new Set(first).size).toBe(first.length);
+  });
+
+  it('keeps an untouched hunk addressable when a neighbour changes', () => {
+    const before = parseDiffFiles(TWO_FILE_DIFF, 'working').files[0].hunks;
+    const edited = TWO_FILE_DIFF.replace('+const next = true;', '+const next = false;');
+    const after = parseDiffFiles(edited, 'working').files[0].hunks;
+
+    // The unrelated first hunk survives; only the edited one loses its id.
+    expect(after[0].id).toBe(before[0].id);
+    expect(after[1].id).not.toBe(before[1].id);
+  });
+
+  it('separates identical hunks in different scopes', () => {
+    const staged = parseDiffFiles(TWO_FILE_DIFF, 'staged').files[0].hunks[0].id;
+    const working = parseDiffFiles(TWO_FILE_DIFF, 'working').files[0].hunks[0].id;
+
+    expect(staged).not.toBe(working);
+  });
+
+  it('disambiguates byte-identical hunks inside one file', () => {
+    const repeated = `diff --git a/src/dup.ts b/src/dup.ts
+--- a/src/dup.ts
++++ b/src/dup.ts
+@@ -1,1 +1,2 @@
++import { thing } from './thing';
+@@ -1,1 +1,2 @@
++import { thing } from './thing';
+`;
+
+    const ids = listHunkIds(parseDiffFiles(repeated, 'working').files);
+
+    expect(ids).toHaveLength(2);
+    expect(new Set(ids).size).toBe(2);
+  });
+
+  it('records renames and deletions', () => {
+    const renamed = `diff --git a/src/old.ts b/src/new.ts
+similarity index 90%
+rename from src/old.ts
+rename to src/new.ts
+--- a/src/old.ts
++++ b/src/new.ts
+@@ -1,1 +1,1 @@
+-const a = 1;
++const a = 2;
+diff --git a/src/gone.ts b/src/gone.ts
+deleted file mode 100644
+--- a/src/gone.ts
++++ /dev/null
+@@ -1,1 +0,0 @@
+-const gone = true;
+`;
+
+    const { files } = parseDiffFiles(renamed, 'working');
+
+    expect(files[0]).toMatchObject({ path: 'src/new.ts', oldPath: 'src/old.ts', status: 'renamed' });
+    expect(files[1]).toMatchObject({ path: 'src/gone.ts', status: 'deleted' });
+  });
+
+  it('marks binary files and gives them no hunks', () => {
+    const binary = `diff --git a/logo.png b/logo.png
+index 1111111..2222222 100644
+Binary files a/logo.png and b/logo.png differ
+`;
+
+    const { files } = parseDiffFiles(binary, 'working');
+
+    expect(files[0]).toMatchObject({ path: 'logo.png', binary: true });
+    expect(files[0].hunks).toHaveLength(0);
+  });
+
+  it('returns nothing for empty or whitespace input', () => {
+    expect(parseDiffFiles('', 'working').files).toEqual([]);
+    expect(parseDiffFiles('   \n', 'working').files).toEqual([]);
+    expect(parseDiffFiles(undefined, 'working').files).toEqual([]);
+  });
+});
+
+describe('indexHunks', () => {
+  it('maps every id to its hunk with the owning file path', () => {
+    const { files } = parseDiffFiles(TWO_FILE_DIFF, 'working');
+    const index = indexHunks(files);
+
+    expect(index.size).toBe(3);
+    for (const [id, hunk] of index) {
+      expect(hunk.id).toBe(id);
+      expect(hunk.path).toBeTruthy();
+    }
+  });
+});

packages/web/server/lib/walkthrough/index.js

@@ -0,0 +1,509 @@
+import { getRepositoryRoot } from '../git/service.js';
+import { describeSmallModel, generateSmallModelText } from '../small-model/index.js';
+import { buildDigest } from './digest.js';
+import { indexHunks } from './hunks.js';
+import { buildPrompt, JSON_SHAPE_INSTRUCTION } from './prompt.js';
+import { normalizeWalkthrough, parseModelJson, responseSchema } from './schema.js';
+import {
+  buildCacheKey,
+  pruneMissingRepositories,
+  readCachedWalkthrough,
+  readPointer,
+  writeCachedWalkthrough,
+  writePointer,
+} from './store.js';
+import { readWalkthroughModelOverride } from './model-settings.js';
+import { loadSourceSections, parseSource, sourceKey, WalkthroughSourceError } from './sources.js';
+
+// Walkthrough generation is always user-initiated and never automatic: it costs
+// tokens, and a background regeneration on every keystroke would be a way to
+// spend a budget without anyone deciding to.
+
+// This module is imported lazily, which means module-level work lands on the
+// first walkthrough request. Housekeeping has no business being there, so it is
+// deferred and never awaited: the request proceeds immediately and the prune
+// interleaves behind it.
+setTimeout(() => {
+  void pruneMissingRepositories().catch(() => {
+    // Housekeeping failing is not worth surfacing or retrying.
+  });
+}, 0).unref?.();
+
+// A hang guard, not a pace-setter. Losing a nearly-finished generation wastes
+// real money and minutes, while an over-long deadline only holds a job slot, so
+// this errs long. It scales because a three-hunk edit and a 500-hunk pull
+// request have no business sharing a deadline.
+const GENERATION_TIMEOUT_BASE_MS = 120_000;
+const GENERATION_TIMEOUT_PER_HUNK_MS = 1_000;
+const GENERATION_TIMEOUT_MAX_MS = 900_000;
+
+const generationTimeoutMs = (hunkCount) => Math.min(
+  GENERATION_TIMEOUT_MAX_MS,
+  GENERATION_TIMEOUT_BASE_MS + Math.max(0, hunkCount) * GENERATION_TIMEOUT_PER_HUNK_MS,
+);
+// A full walkthrough is a few thousand tokens of JSON, but reasoning models
+// spend the same budget thinking first and return nothing if it runs out. The
+// reserve subtracted from the input budget matches this exactly, so a bigger
+// answer allowance costs input room rather than overrunning the context.
+const MAX_OUTPUT_TOKENS = 24_000;
+
+const fail = (message, statusCode, extra = {}) =>
+  Object.assign(new Error(message), { statusCode, ...extra });
+
+// Generation outlives the request that started it.
+//
+// A dropped connection and a deliberate cancel look identical at the socket, so
+// tying the work to the request lifetime meant an accidental refresh threw away
+// a minute of paid-for work. Jobs are keyed by repository + source, so a client
+// that comes back attaches to the running job instead of starting a second one,
+// and cancelling is an explicit request rather than a side effect of leaving.
+const jobs = new Map();
+
+// Providers that answered a schema request with a 4xx. Retrying the schema on
+// every generation means paying for a call we already know will fail, so the
+// refusal is remembered and the fallback goes first next time.
+//
+// Process-lifetime only, on purpose: a provider that gains structured-output
+// support should not need a settings change to be tried again — a restart is
+// enough, and the cost of one wasted first attempt after that is small.
+const schemaRefusedBy = new Set();
+
+const modelKey = (model) => `${model.providerID}/${model.modelID}`;
+
+const jobKey = (repoRoot, sourceKeyValue) => `${repoRoot}\0${sourceKeyValue}`;
+
+/**
+ * Coarse stages, reported so a long wait is legible.
+ *
+ * Only phases a person can actually wait on are named. Building the digest and
+ * reading the cache take single-digit milliseconds; giving them their own rows
+ * would imply progress where there is none. `retrying` appears only when a
+ * provider rejects the schema and the prompt-side fallback runs.
+ */
+export const GENERATION_STAGES = ['collecting', 'asking', 'retrying', 'assembling'];
+
+const setStage = (repoRoot, sourceKeyValue, stage) => {
+  const job = jobs.get(jobKey(repoRoot, sourceKeyValue));
+  if (job) job.stage = stage;
+};
+
+/**
+ * Current stage of a running generation, or `null` when nothing is running.
+ * Reads memory only — no git, no network — so it is cheap to poll.
+ */
+export function getGenerationStage(repoRoot, sourceKeyValue) {
+  return jobs.get(jobKey(repoRoot, sourceKeyValue))?.stage ?? null;
+}
+
+/**
+ * Whether a generation is currently running for a source. Lets a reconnecting
+ * client show progress instead of an empty panel.
+ */
+export function isGenerating(repoRoot, sourceKeyValue) {
+  return jobs.has(jobKey(repoRoot, sourceKeyValue));
+}
+
+/**
+ * Resolve the pair the job registry is keyed by, for callers that need to look
+ * a job up without doing any diff work.
+ */
+export async function getRepositoryRootFor(directory, rawSource) {
+  const source = parseSource(rawSource);
+  return { repoRoot: await getRepositoryRoot(directory), sourceKey: sourceKey(source) };
+}
+
+/**
+ * Stop a running generation. Only an explicit request does this — leaving the
+ * page does not.
+ */
+export async function cancelWalkthroughGeneration({ directory, source: rawSource }) {
+  const source = parseSource(rawSource);
+  const repoRoot = await getRepositoryRoot(directory);
+  const job = jobs.get(jobKey(repoRoot, sourceKey(source)));
+  if (!job) return { cancelled: false };
+  job.controller.abort();
+  return { cancelled: true };
+}
+
+const modelLabel = (model) => `${model.providerID}/${model.modelID}`;
+
+/**
+ * Resolve the model for this feature: the walkthrough override when set,
+ * otherwise whatever the small-model chain resolves to.
+ */
+/**
+ * Resolve the model for this feature. An explicit per-review choice outranks the
+ * saved setting, which in turn outranks the small-model chain — the user picking
+ * a roomier model for a risky change is the most specific intent there is.
+ */
+const resolveModel = (directory, explicitModel) => describeSmallModel({
+  directory,
+  outputReserveTokens: MAX_OUTPUT_TOKENS,
+  overrideModel: explicitModel || readWalkthroughModelOverride(),
+});
+
+export const __testing = { generationTimeoutMs };
+
+/**
+ * Current diff for a source, parsed into files and hunks.
+ */
+async function loadCurrentDiff(directory, source, deps) {
+  const { sections } = await loadSourceSections(directory, source, deps);
+  const built = buildDigest(sections);
+  return built;
+}
+
+const stopHunkIds = (walkthrough) =>
+  walkthrough.chapters.flatMap((chapter) => chapter.stops.flatMap((stop) => stop.hunkIds));
+
+/**
+ * Compare a stored walkthrough against the diff as it is right now.
+ *
+ * Staleness is not a heuristic here: a hunk id is a hash of the hunk's content,
+ * so an anchor that no longer resolves is proof that the code it described has
+ * changed or gone. Anchors that still resolve are still accurate.
+ */
+function resolveAgainstCurrent(walkthrough, hunkIndex) {
+  const missingHunkIds = [];
+  const staleStopIds = [];
+
+  for (const chapter of walkthrough.chapters) {
+    for (const stop of chapter.stops) {
+      const missing = stop.hunkIds.filter((id) => !hunkIndex.has(id));
+      if (missing.length === 0) continue;
+      missingHunkIds.push(...missing);
+      staleStopIds.push(stop.id);
+    }
+  }
+
+  const covered = new Set(stopHunkIds(walkthrough));
+  const uncoveredHunkIds = [...hunkIndex.keys()].filter((id) => !covered.has(id));
+
+  return {
+    isStale: missingHunkIds.length > 0,
+    missingHunkIds,
+    staleStopIds,
+    uncoveredHunkIds,
+  };
+}
+
+const serializeHunks = (files) => files.flatMap((file) => file.hunks.map((hunk) => ({
+  id: hunk.id,
+  path: file.path,
+  oldPath: file.oldPath || null,
+  status: file.status,
+  scope: file.scope,
+  header: hunk.header,
+  newStart: hunk.newStart,
+  added: hunk.added,
+  deleted: hunk.deleted,
+  patch: hunk.patch,
+})));
+
+/**
+ * Read the last walkthrough for a source, resolved against the current diff.
+ * Never generates and never spends tokens.
+ */
+export async function getWalkthrough({ directory, source: rawSource, model: explicitModel }, deps = {}) {
+  const source = parseSource(rawSource);
+  const repoRoot = await getRepositoryRoot(directory);
+  const key = sourceKey(source);
+
+  const pointer = readPointer(repoRoot, key);
+  // One diff, one model lookup, both answers. These used to be separate
+  // endpoints the client called in parallel, which meant every panel open ran
+  // the whole git pipeline twice.
+  const [built, model] = await Promise.all([
+    loadCurrentDiff(directory, source, deps),
+    resolveModel(directory, explicitModel).catch(() => null),
+  ]);
+  const { files } = built;
+  const hunkIndex = indexHunks(files);
+  const readiness = computeReadiness({ ...built, model, source });
+
+  const base = {
+    source,
+    hunks: serializeHunks(files),
+    hunkCount: hunkIndex.size,
+    readiness,
+    generating: isGenerating(repoRoot, key),
+  };
+
+  const entry = pointer ? readCachedWalkthrough(pointer.cacheKey) : null;
+  if (!entry) {
+    // No pointer, or the pointer outlived its entry (eviction, manual cleanup).
+    // "No walkthrough" is the truthful answer either way; the pointer is left
+    // for the next generation to overwrite.
+    return { ...base, walkthrough: null };
+  }
+
+  return {
+    ...base,
+    walkthrough: entry.walkthrough,
+    model: entry.model,
+    generatedAt: entry.generatedAt,
+    ...resolveAgainstCurrent(entry.walkthrough, hunkIndex),
+  };
+}
+
+/**
+ * Whether the resolved model can do this job, computed from a digest the caller
+ * already built.
+ *
+ * Folded into the walkthrough read rather than living on its own endpoint: both
+ * answers need the same diff, and computing it twice doubled the git work on
+ * every panel open.
+ */
+function computeReadiness({ model, digest, files, fileCount, hunkCount, generatedFileCount, source }) {
+  if (!model) return { ready: false, reason: 'no-model' };
+
+  if (hunkCount === 0) {
+    // "Only a lockfile changed" is a different answer from "nothing changed",
+    // and the user can act on it (commit and move on) rather than wonder why
+    // the review refuses.
+    const reason = files.length > 0 && generatedFileCount === files.length ? 'only-generated' : 'empty-diff';
+    return { ready: false, reason, model, generatedFileCount };
+  }
+
+  const { prompt, system } = buildPrompt({ digest, fileCount, hunkCount, source });
+  const requiredChars = prompt.length + system.length;
+
+  if (model.structuredOutput === false) {
+    return { ready: false, reason: 'structured-output-unsupported', model, requiredChars };
+  }
+
+  if (requiredChars > model.inputCharBudget) {
+    return {
+      ready: false,
+      reason: 'context-too-small',
+      model,
+      requiredChars,
+      availableChars: model.inputCharBudget,
+    };
+  }
+
+  return { ready: true, model, requiredChars, availableChars: model.inputCharBudget, hunkCount, fileCount };
+}
+
+/**
+ * Generate a walkthrough for a source.
+ *
+ * Returns the cached entry when the diff, model, and prompt are all unchanged —
+ * which also means returning to a previous state of the working tree costs
+ * nothing.
+ */
+export async function generateWalkthrough({ directory, source: rawSource, force = false, model: explicitModel }, deps = {}) {
+  const source = parseSource(rawSource);
+  const repoRoot = await getRepositoryRoot(directory);
+  const key = sourceKey(source);
+
+  // Attach to a running job rather than starting a second one. A user who
+  // refreshed and pressed the button again wants the answer, not two bills.
+  const existing = jobs.get(jobKey(repoRoot, key));
+  if (existing) return existing.promise;
+
+  const controller = new AbortController();
+  const promise = runGeneration({ directory, source, repoRoot, key, force, explicitModel, signal: controller.signal }, deps)
+    .finally(() => {
+      if (jobs.get(jobKey(repoRoot, key))?.controller === controller) {
+        jobs.delete(jobKey(repoRoot, key));
+      }
+    });
+
+  jobs.set(jobKey(repoRoot, key), { controller, promise, stage: 'collecting' });
+  return promise;
+}
+
+async function runGeneration({ directory, source, repoRoot, key, force, explicitModel, signal }, deps) {
+
+  const model = await resolveModel(directory, explicitModel);
+  if (!model) {
+    throw fail('No model is available — sign in to a provider first', 404, { code: 'no-model' });
+  }
+
+  const { digest, files, idByAlias, fileCount, hunkCount, generatedFileCount } = await loadCurrentDiff(directory, source, deps);
+  setStage(repoRoot, key, 'asking');
+  if (hunkCount === 0) {
+    if (files.length > 0 && generatedFileCount === files.length) {
+      throw fail('Only generated files changed — there is nothing to review', 400, { code: 'only-generated' });
+    }
+    throw fail('There are no changes to review', 400, { code: 'empty-diff' });
+  }
+
+  const cacheKey = buildCacheKey({
+    repoRoot,
+    sourceKey: key,
+    providerID: model.providerID,
+    modelID: model.modelID,
+    files,
+  });
+
+  const hunkIndex = indexHunks(files);
+
+  if (!force) {
+    const cached = readCachedWalkthrough(cacheKey);
+    if (cached) {
+      writePointer(repoRoot, key, {
+        repoRoot,
+        sourceKey: key,
+        cacheKey,
+        generatedAt: cached.generatedAt,
+      });
+      return {
+        source,
+        walkthrough: cached.walkthrough,
+        model: cached.model,
+        generatedAt: cached.generatedAt,
+        fromCache: true,
+        hunks: serializeHunks(files),
+        hunkCount,
+        ...resolveAgainstCurrent(cached.walkthrough, hunkIndex),
+      };
+    }
+  }
+
+  // A forced regeneration hands the model its own previous narrative so it can
+  // keep what is still true instead of starting from a blank page. The old
+  // anchors are deliberately not included — they belong to code that has moved.
+  let previousWalkthrough = null;
+  const pointer = readPointer(repoRoot, key);
+  if (pointer) {
+    const previousEntry = readCachedWalkthrough(pointer.cacheKey);
+    if (previousEntry && previousEntry.cacheKey !== cacheKey) {
+      previousWalkthrough = previousEntry.walkthrough;
+    }
+  }
+
+  const { prompt, system } = buildPrompt({ digest, fileCount, hunkCount, source, previousWalkthrough });
+
+  if (model.structuredOutput === false) {
+    throw fail(
+      `${modelLabel(model)} cannot produce structured output — choose a different small model`,
+      409,
+      { code: 'structured-output-unsupported', model },
+    );
+  }
+
+  const run = (options) => generateSmallModelText({
+    prompt: options.prompt,
+    system: options.system,
+    directory,
+    model: `${model.providerID}/${model.modelID}`,
+    responseSchema: options.responseSchema,
+    onOverflow: 'error',
+    timeoutMs: generationTimeoutMs(hunkCount),
+    maxOutputTokens: MAX_OUTPUT_TOKENS,
+    signal,
+  });
+
+  // Roughly half the catalog does not declare `structured_output`, and some of
+  // those providers reject the schema outright. A rejected request shape is not
+  // a dead end: the shape can travel in the prompt instead, and the response
+  // parser is already tolerant of imperfect JSON.
+  const withSchema = () => run({ prompt, system, responseSchema });
+  const withoutSchema = () => run({
+    prompt,
+    system: `${system}\n${JSON_SHAPE_INSTRUCTION}`,
+    responseSchema: undefined,
+  });
+
+  const asRequestFailure = (error) => {
+    if (error?.code === 'context-too-small') {
+      return fail(error.message, 409, {
+        code: 'context-too-small',
+        model,
+        requiredChars: error.requiredChars,
+        availableChars: error.availableChars,
+      });
+    }
+    if (error?.code === 'output-exhausted') {
+      return fail(error.message, 409, { code: 'output-exhausted', model });
+    }
+    return null;
+  };
+
+  const refusesSchema = (error) => error?.code === 'structured-output-unsupported'
+    || (Number(error?.status) >= 400 && Number(error?.status) < 500);
+
+  let raw;
+  let usedSchema = false;
+
+  if (schemaRefusedBy.has(modelKey(model))) {
+    // Already known to refuse: skip straight to the fallback rather than pay
+    // for a call whose failure is a foregone conclusion.
+    setStage(repoRoot, key, 'retrying');
+    try {
+      raw = await withoutSchema();
+    } catch (error) {
+      throw asRequestFailure(error) ?? error;
+    }
+  } else {
+    try {
+      raw = await withSchema();
+      usedSchema = true;
+    } catch (error) {
+      const failure = asRequestFailure(error);
+      if (failure) throw failure;
+      if (!refusesSchema(error)) throw error;
+
+      schemaRefusedBy.add(modelKey(model));
+      setStage(repoRoot, key, 'retrying');
+      try {
+        raw = await withoutSchema();
+      } catch (fallbackError) {
+        throw asRequestFailure(fallbackError) ?? fallbackError;
+      }
+    }
+  }
+
+  setStage(repoRoot, key, 'assembling');
+
+  let walkthrough;
+  try {
+    walkthrough = normalizeWalkthrough(parseModelJson(raw.text), idByAlias);
+  } catch (error) {
+    // Without schema support the model was asked for JSON in prose and did not
+    // deliver: that is a capability problem the user can fix by switching model,
+    // so it gets the picker rather than a parser error.
+    if (!usedSchema) {
+      throw fail(
+        `${modelLabel(model)} could not return the structured response a walkthrough needs`,
+        409,
+        { code: 'structured-output-unsupported', model },
+      );
+    }
+    throw fail(
+      `${modelLabel(model)} did not return a usable walkthrough — try a different small model`,
+      502,
+      { code: 'invalid-walkthrough', model, cause: error?.message },
+    );
+  }
+
+  const generatedAt = new Date().toISOString();
+  const entry = {
+    cacheKey,
+    generatedAt,
+    repoRoot,
+    sourceKey: key,
+    model: { providerID: model.providerID, modelID: model.modelID, source: model.source },
+    walkthrough,
+  };
+
+  // A failed write costs a regeneration next time; it must never fail the
+  // request that already produced a good walkthrough.
+  writeCachedWalkthrough(cacheKey, entry);
+  writePointer(repoRoot, key, { repoRoot, sourceKey: key, cacheKey, generatedAt });
+
+  return {
+    source,
+    walkthrough,
+    model: entry.model,
+    generatedAt,
+    fromCache: false,
+    hunks: serializeHunks(files),
+    hunkCount,
+    ...resolveAgainstCurrent(walkthrough, hunkIndex),
+  };
+}
+
+export { WalkthroughSourceError };

packages/web/server/lib/walkthrough/jobs.test.js

@@ -0,0 +1,256 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const TEMP_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'walkthrough-jobs-'));
+process.env.OPENCHAMBER_DATA_DIR = TEMP_DATA_DIR;
+
+// Mocking git rather than this module's own source loading: fewer of our own
+// seams faked means the test exercises the real digest and prompt path.
+vi.mock('../git/service.js', () => ({
+  getRepositoryRoot: vi.fn(async () => '/repo'),
+  getDiff: vi.fn(),
+  getRangeDiff: vi.fn(),
+  getUntrackedDiffs: vi.fn(async () => []),
+  listUntrackedPaths: vi.fn(async () => []),
+}));
+vi.mock('../small-model/index.js', () => ({
+  describeSmallModel: vi.fn(),
+  generateSmallModelText: vi.fn(),
+}));
+const {
+  generateWalkthrough,
+  cancelWalkthroughGeneration,
+  isGenerating,
+  getGenerationStage,
+  __testing: walkthroughTesting,
+} = await import('./index.js');
+const { describeSmallModel, generateSmallModelText } = await import('../small-model/index.js');
+const { getDiff } = await import('../git/service.js');
+
+// bun's vitest shim has no `vi.waitFor`.
+const waitFor = async (predicate, { timeout = 2_000, interval = 5 } = {}) => {
+  const deadline = Date.now() + timeout;
+  for (;;) {
+    if (predicate()) return;
+    if (Date.now() > deadline) throw new Error('waitFor timed out');
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+};
+
+const SOURCE = { kind: 'working-tree', scope: 'all' };
+
+const PATCH = `diff --git a/src/a.ts b/src/a.ts
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,1 +1,2 @@
++const added = true;
+`;
+
+const RESPONSE = JSON.stringify({
+  title: 'Change',
+  focus: 'why',
+  chapters: [{
+    title: 'Data',
+    icon: 'doc',
+    blurb: '',
+    stops: [{ title: 'Adds a flag', hunks: ['h1'], importance: 'normal', prose: 'It adds a flag.' }],
+  }],
+});
+
+describe('generation jobs', () => {
+  beforeEach(() => {
+    fs.rmSync(path.join(TEMP_DATA_DIR, 'walkthroughs'), { recursive: true, force: true });
+    describeSmallModel.mockResolvedValue({
+      providerID: 'anthropic',
+      modelID: 'claude-haiku-4-5',
+      source: 'config',
+      inputCharBudget: 1_000_000,
+      structuredOutput: true,
+    });
+    getDiff.mockImplementation(async (_dir, options) => (options?.staged ? '' : PATCH));
+    generateSmallModelText.mockReset();
+  });
+
+  afterEach(async () => {
+    if (isGenerating('/repo', 'working-tree:all')) {
+      await cancelWalkthroughGeneration({ directory: '/repo', source: SOURCE }).catch(() => {});
+    }
+  });
+
+  afterAll(() => {
+    fs.rmSync(TEMP_DATA_DIR, { recursive: true, force: true });
+  });
+
+  it('runs a second request against the same job instead of paying twice', async () => {
+    let release;
+    generateSmallModelText.mockImplementation(() => new Promise((resolve) => {
+      release = () => resolve({ text: RESPONSE });
+    }));
+
+    const first = generateWalkthrough({ directory: '/repo', source: SOURCE });
+    // Let the first call reach the model before the second arrives, which is
+    // what a refresh-then-press-again actually looks like.
+    await waitFor(() => generateSmallModelText.mock.calls.length === 1);
+    const second = generateWalkthrough({ directory: '/repo', source: SOURCE });
+
+    release();
+    const [a, b] = await Promise.all([first, second]);
+
+    expect(generateSmallModelText).toHaveBeenCalledTimes(1);
+    expect(a.walkthrough.title).toBe('Change');
+    expect(b).toBe(a);
+  });
+
+  it('reports a running job so a returning client can show progress', async () => {
+    let release;
+    generateSmallModelText.mockImplementation(() => new Promise((resolve) => {
+      release = () => resolve({ text: RESPONSE });
+    }));
+
+    const running = generateWalkthrough({ directory: '/repo', source: SOURCE });
+    await waitFor(() => isGenerating('/repo', 'working-tree:all'));
+
+    release();
+    await running;
+
+    expect(isGenerating('/repo', 'working-tree:all')).toBe(false);
+  });
+
+  it('stops only on an explicit cancel', async () => {
+    generateSmallModelText.mockImplementation(({ signal }) => new Promise((_resolve, reject) => {
+      signal?.addEventListener('abort', () => reject(Object.assign(new Error('aborted'), { name: 'AbortError' })));
+    }));
+
+    const running = generateWalkthrough({ directory: '/repo', source: SOURCE });
+    await waitFor(() => isGenerating('/repo', 'working-tree:all'));
+
+    expect(await cancelWalkthroughGeneration({ directory: '/repo', source: SOURCE }))
+      .toEqual({ cancelled: true });
+    await expect(running).rejects.toThrow();
+    expect(isGenerating('/repo', 'working-tree:all')).toBe(false);
+  });
+
+  it('reports nothing to cancel when no job is running', async () => {
+    expect(await cancelWalkthroughGeneration({ directory: '/repo', source: SOURCE }))
+      .toEqual({ cancelled: false });
+  });
+
+  it('serves the cache once the job has finished, without calling the model again', async () => {
+    generateSmallModelText.mockResolvedValue({ text: RESPONSE });
+
+    await generateWalkthrough({ directory: '/repo', source: SOURCE });
+    generateSmallModelText.mockClear();
+
+    const second = await generateWalkthrough({ directory: '/repo', source: SOURCE });
+
+    expect(second.fromCache).toBe(true);
+    expect(generateSmallModelText).not.toHaveBeenCalled();
+  });
+});
+
+// A fixed deadline made a three-hunk edit and a 500-hunk pull request wait the
+// same, so the small case guarded nothing and the big case died just short of
+// the finish line.
+describe('generation timeout', () => {
+  const { generationTimeoutMs } = walkthroughTesting;
+
+  it('gives a small diff a floor rather than a proportional sliver', () => {
+    expect(generationTimeoutMs(0)).toBe(120_000);
+    expect(generationTimeoutMs(3)).toBe(123_000);
+  });
+
+  it('grows with the work', () => {
+    expect(generationTimeoutMs(515)).toBeGreaterThan(generationTimeoutMs(138));
+    expect(generationTimeoutMs(515)).toBe(635_000);
+  });
+
+  it('stays bounded so a hung connection cannot hold a job forever', () => {
+    expect(generationTimeoutMs(100_000)).toBe(900_000);
+  });
+});
+
+describe('generation stages', () => {
+  beforeEach(() => {
+    // Without this the previous suite's cache entry is a hit for the same
+    // content and the model is never called.
+    fs.rmSync(path.join(TEMP_DATA_DIR, 'walkthroughs'), { recursive: true, force: true });
+    describeSmallModel.mockResolvedValue({
+      providerID: 'anthropic',
+      modelID: 'claude-haiku-4-5',
+      source: 'config',
+      inputCharBudget: 1_000_000,
+      structuredOutput: true,
+    });
+    getDiff.mockImplementation(async (_dir, options) => (options?.staged ? '' : PATCH));
+    generateSmallModelText.mockReset();
+  });
+
+  it('reports asking while the model runs and clears when the job ends', async () => {
+    let release;
+    generateSmallModelText.mockImplementation(() => new Promise((resolve) => {
+      release = () => resolve({ text: RESPONSE });
+    }));
+
+    const running = generateWalkthrough({ directory: '/repo', source: SOURCE });
+    await waitFor(() => getGenerationStage('/repo', 'working-tree:all') === 'asking');
+
+    release();
+    await running;
+
+    expect(getGenerationStage('/repo', 'working-tree:all')).toBeNull();
+  });
+
+  it('reports retrying only when a provider rejects the schema', async () => {
+    let seen = [];
+    let attempt = 0;
+    generateSmallModelText.mockImplementation(async () => {
+      attempt += 1;
+      seen.push(getGenerationStage('/repo', 'working-tree:all'));
+      if (attempt === 1) throw Object.assign(new Error('bad request'), { status: 400 });
+      return { text: RESPONSE };
+    });
+
+    await generateWalkthrough({ directory: '/repo', source: SOURCE });
+
+    expect(seen).toEqual(['asking', 'retrying']);
+  });
+});
+
+// Retrying the schema on every generation means paying for a call already known
+// to fail; the refusal has to be remembered.
+describe('schema refusal memory', () => {
+  beforeEach(() => {
+    fs.rmSync(path.join(TEMP_DATA_DIR, 'walkthroughs'), { recursive: true, force: true });
+    describeSmallModel.mockResolvedValue({
+      providerID: 'opencode-go',
+      modelID: 'deepseek-v4-flash',
+      source: 'config',
+      inputCharBudget: 1_000_000,
+      structuredOutput: null,
+    });
+    getDiff.mockImplementation(async (_dir, options) => (options?.staged ? '' : PATCH));
+    generateSmallModelText.mockReset();
+  });
+
+  it('stops sending a schema to a model that already rejected one', async () => {
+    const sentSchema = [];
+    generateSmallModelText.mockImplementation(async ({ responseSchema }) => {
+      sentSchema.push(Boolean(responseSchema));
+      if (responseSchema) throw Object.assign(new Error('bad request'), { status: 400 });
+      return { text: RESPONSE };
+    });
+
+    await generateWalkthrough({ directory: '/repo', source: SOURCE });
+    expect(sentSchema).toEqual([true, false]);
+
+    // A different diff, so the cache cannot answer instead.
+    getDiff.mockImplementation(async (_dir, options) => (
+      options?.staged ? '' : PATCH.replace('const added = true;', 'const added = false;')
+    ));
+    await generateWalkthrough({ directory: '/repo', source: SOURCE });
+
+    expect(sentSchema).toEqual([true, false, false]);
+  });
+});

packages/web/server/lib/walkthrough/model-settings.js

@@ -0,0 +1,38 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// The walkthrough may run on a different model than the rest of the small-model
+// callers. Those callers want cheap and fast; this one needs structured output
+// and enough context for a whole diff, and forcing one setting to serve both
+// means the user has to degrade one feature to fix the other.
+
+const SETTINGS_FILE = path.join(
+  process.env.OPENCHAMBER_DATA_DIR
+    ? path.resolve(process.env.OPENCHAMBER_DATA_DIR)
+    : path.join(os.homedir(), '.config', 'openchamber'),
+  'settings.json',
+);
+
+/**
+ * The explicit walkthrough model, or `null` to fall back to normal small-model
+ * resolution.
+ *
+ * Having chosen a model *is* the opt-out; a separate toggle would let the two
+ * disagree, and then clearing the picker would leave a setting that says "do
+ * not use the small model" with nothing to use instead.
+ */
+export function readWalkthroughModelOverride() {
+  try {
+    const settings = JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'));
+    if (!settings || typeof settings !== 'object') return null;
+    const override = typeof settings.walkthroughModelOverride === 'string'
+      ? settings.walkthroughModelOverride.trim()
+      : '';
+    return override || null;
+  } catch {
+    // No settings file, unreadable, or malformed all mean the same thing: no
+    // override, use the small model.
+    return null;
+  }
+}

packages/web/server/lib/walkthrough/model-settings.test.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterAll, beforeEach, describe, expect, it } from 'vitest';
+
+const TEMP_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'walkthrough-model-settings-'));
+process.env.OPENCHAMBER_DATA_DIR = TEMP_DATA_DIR;
+
+const { readWalkthroughModelOverride } = await import('./model-settings.js');
+
+const SETTINGS_FILE = path.join(TEMP_DATA_DIR, 'settings.json');
+
+const write = (value) => fs.writeFileSync(SETTINGS_FILE, JSON.stringify(value), 'utf8');
+
+describe('readWalkthroughModelOverride', () => {
+  beforeEach(() => {
+    fs.rmSync(SETTINGS_FILE, { force: true });
+  });
+
+  it('returns the chosen model', () => {
+    write({ walkthroughModelOverride: 'anthropic/claude-haiku-4-5' });
+    expect(readWalkthroughModelOverride()).toBe('anthropic/claude-haiku-4-5');
+  });
+
+  it('defers to the small model when nothing is chosen', () => {
+    write({});
+    expect(readWalkthroughModelOverride()).toBeNull();
+
+    // Clearing the picker writes an empty string; that must read as "use the
+    // small model", not as an override of ''.
+    write({ walkthroughModelOverride: '' });
+    expect(readWalkthroughModelOverride()).toBeNull();
+
+    write({ walkthroughModelOverride: '   ' });
+    expect(readWalkthroughModelOverride()).toBeNull();
+  });
+
+  it('never throws on a missing or corrupt settings file', () => {
+    expect(readWalkthroughModelOverride()).toBeNull();
+
+    fs.writeFileSync(SETTINGS_FILE, '{ not json', 'utf8');
+    expect(readWalkthroughModelOverride()).toBeNull();
+  });
+
+  it('is independent of the small model override', () => {
+    write({
+      smallModelUseDefault: false,
+      smallModelOverride: 'google/gemini-2.5-flash',
+      walkthroughModelOverride: 'anthropic/claude-haiku-4-5',
+    });
+
+    expect(readWalkthroughModelOverride()).toBe('anthropic/claude-haiku-4-5');
+  });
+});
+
+afterAll(() => {
+  fs.rmSync(TEMP_DATA_DIR, { recursive: true, force: true });
+});

packages/web/server/lib/walkthrough/prompt.js

@@ -0,0 +1,83 @@
+import { MAX_CHAPTERS, MAX_CHAPTER_TITLE_CHARS, MAX_HUNKS_PER_STOP, MAX_STOPS } from './schema.js';
+
+const SYSTEM = `You are writing a guided review of a code change for the engineer who is about to read it.
+
+Your job is to impose a reading order the diff itself does not have. A diff is ordered by file path, which is almost never the order in which the change makes sense. Group related hunks — across files — into stops, and order the stops so that each one is understandable given the ones before it.
+
+What a good stop says:
+- what this code now does differently, in terms of behavior, not syntax
+- why the surrounding hunks belong together
+- what a reviewer should check or be suspicious about, when there is something
+
+What a bad stop says:
+- "Renamed X to Y", "Added a parameter", "Updated the imports" — restating the diff in prose is worthless; the reader can already see it
+- speculation about intent you cannot support from the code
+
+Rules:
+- Anchor every stop to hunk aliases from the digest, exactly as given (h1, h2, …). Never invent an alias.
+- Anchor each hunk at most once, in the stop where it matters most.
+- You do not have to cover every hunk. Mechanical changes are better left out than padded into a stop; whatever you omit is still shown to the reader separately.
+- Order stops so the reader builds understanding: entry points and data shape before the code that consumes them.
+- importance: "critical" for changes that carry real risk or drive the rest, "context" for supporting changes, "normal" otherwise.
+- Stop titles name the thing the stop is about, not the act of reviewing it. "Hardware keyboard bridge" and "Overflow menu removed" tell a reader scanning the contents what they will find; "Exercise the boundaries" and "Describe the contract" do not.
+- Write prose as plain sentences. No markdown, no bullet lists, no code fences.
+
+Respond with a single JSON object and nothing else. (Some providers refuse a structured-output request unless the word "json" appears in the request, which is why this is stated explicitly.)`;
+
+const sizing = ({ fileCount, hunkCount }) => {
+  const targetStops = Math.max(1, Math.min(MAX_STOPS, Math.round(hunkCount / 2.5) || 1));
+  const targetChapters = hunkCount <= 4
+    ? 1
+    : Math.max(1, Math.min(MAX_CHAPTERS, Math.ceil(targetStops / 3)));
+
+  return `This change has ${fileCount} file(s) and ${hunkCount} reviewable hunk(s).
+
+Aim for about ${targetStops} stop(s) across about ${targetChapters} chapter(s); never exceed ${MAX_STOPS} stops, ${MAX_CHAPTERS} chapters, or ${MAX_HUNKS_PER_STOP} hunks in one stop. Fewer, denser stops beat many thin ones.
+
+Chapter titles render in a narrow column: at most ${MAX_CHAPTER_TITLE_CHARS} characters, one or two words.`;
+};
+
+const previousWalkthroughSection = (previous) => {
+  if (!previous || !Array.isArray(previous.chapters) || previous.chapters.length === 0) return '';
+
+  const outline = previous.chapters
+    .map((chapter) => {
+      const stops = (chapter.stops || [])
+        .map((stop) => `  - ${stop.title}: ${stop.prose}`)
+        .join('\n');
+      return `- ${chapter.title}${chapter.blurb ? ` — ${chapter.blurb}` : ''}\n${stops}`;
+    })
+    .join('\n');
+
+  return `
+A previous walkthrough of an earlier state of this change is below. The code has moved on since it was written, so its anchors are gone — deliberately, so you re-anchor everything against the current digest.
+
+Keep the stops that are still accurate and phrased well, revise the ones whose code changed, drop the ones whose code no longer exists, and add stops for work that is new. Do not preserve its structure out of loyalty; preserve it only where it still fits.
+
+Previous walkthrough — "${previous.title}":
+${outline}
+`;
+};
+
+// Used only when a provider rejects a schema request: the shape has to travel
+// in the prompt instead of the request body.
+export const JSON_SHAPE_INSTRUCTION = `
+Return ONLY a JSON object, with no prose around it and no markdown fences, in exactly this shape:
+{"title": string, "focus": string, "chapters": [{"title": string, "icon": "bug"|"wrench"|"path"|"flask"|"doc"|"gear", "blurb": string, "stops": [{"title": string, "hunks": [string], "importance": "critical"|"normal"|"context", "prose": string}]}]}`;
+
+export function buildPrompt({ digest, fileCount, hunkCount, source, previousWalkthrough }) {
+  const sourceLine = source.kind === 'working-tree'
+    ? `Uncommitted local changes (${source.scope === 'all' ? 'staged and unstaged' : source.scope}).`
+    : source.kind === 'branch'
+      ? `All work on branch "${source.headRef}" that is not in "${source.baseRef}". Changes merged in from ${source.baseRef} are already excluded.`
+      : `Pull request #${source.number}.`;
+
+  const prompt = `Reviewing: ${sourceLine}
+
+${sizing({ fileCount, hunkCount })}
+${previousWalkthroughSection(previousWalkthrough)}
+Change digest:
+${JSON.stringify(digest)}`;
+
+  return { system: SYSTEM, prompt };
+}

packages/web/server/lib/walkthrough/pull-request.js

@@ -0,0 +1,46 @@
+import { getOctokitOrNull } from '../github/octokit.js';
+import { resolveGitHubRepoFromDirectory } from '../github/repo/index.js';
+
+/**
+ * Raw unified diff for a pull request.
+ *
+ * GitHub already returns the merge-base diff for a PR, so this matches the
+ * three-dot semantics used for local branch reviews: work merged in from the
+ * base branch is not part of it.
+ */
+export async function getPullRequestDiff(directory, number) {
+  const octokit = getOctokitOrNull();
+  if (!octokit) {
+    throw Object.assign(new Error('Connect a GitHub account to review pull requests'), {
+      statusCode: 401,
+      code: 'github-not-connected',
+    });
+  }
+
+  // The resolver returns `{ repo, remoteUrl }`, not the repo itself. Reading
+  // `.owner` off the wrapper made this check fail for every repository.
+  const { repo } = await resolveGitHubRepoFromDirectory(directory);
+  if (!repo?.owner || !repo?.repo) {
+    throw Object.assign(new Error('This directory has no GitHub remote'), {
+      statusCode: 400,
+      code: 'no-github-remote',
+    });
+  }
+
+  const response = await octokit.request('GET /repos/{owner}/{repo}/pulls/{pull_number}', {
+    owner: repo.owner,
+    repo: repo.repo,
+    pull_number: number,
+    headers: { accept: 'application/vnd.github.v3.diff' },
+  });
+
+  const patch = typeof response?.data === 'string' ? response.data : '';
+  if (!patch.trim()) {
+    throw Object.assign(new Error(`Pull request #${number} has no diff`), {
+      statusCode: 404,
+      code: 'empty-diff',
+    });
+  }
+
+  return { patch, meta: { owner: repo.owner, repo: repo.repo, number } };
+}

packages/web/server/lib/walkthrough/pull-request.test.js

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../github/octokit.js', () => ({ getOctokitOrNull: vi.fn() }));
+vi.mock('../github/repo/index.js', () => ({ resolveGitHubRepoFromDirectory: vi.fn() }));
+
+const { getPullRequestDiff } = await import('./pull-request.js');
+const { getOctokitOrNull } = await import('../github/octokit.js');
+const { resolveGitHubRepoFromDirectory } = await import('../github/repo/index.js');
+
+const PATCH = `diff --git a/src/a.ts b/src/a.ts
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,1 +1,2 @@
++const added = true;
+`;
+
+describe('getPullRequestDiff', () => {
+  let request;
+
+  beforeEach(() => {
+    request = vi.fn().mockResolvedValue({ data: PATCH });
+    getOctokitOrNull.mockReturnValue({ request });
+    // The resolver hands back a wrapper, not the repo. Reading `.owner` off the
+    // wrapper made every repository look remote-less, which is what this suite
+    // exists to prevent.
+    resolveGitHubRepoFromDirectory.mockResolvedValue({
+      repo: { owner: 'openchamber', repo: 'openchamber' },
+      remoteUrl: 'git@github.com:openchamber/openchamber.git',
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('requests the diff for the resolved repository', async () => {
+    const result = await getPullRequestDiff('/repo', 2122);
+
+    expect(result.patch).toBe(PATCH);
+    expect(result.meta).toEqual({ owner: 'openchamber', repo: 'openchamber', number: 2122 });
+    expect(request).toHaveBeenCalledWith('GET /repos/{owner}/{repo}/pulls/{pull_number}', {
+      owner: 'openchamber',
+      repo: 'openchamber',
+      pull_number: 2122,
+      headers: { accept: 'application/vnd.github.v3.diff' },
+    });
+  });
+
+  it('reports a missing GitHub remote only when there really is none', async () => {
+    resolveGitHubRepoFromDirectory.mockResolvedValue({ repo: null, remoteUrl: null });
+
+    await expect(getPullRequestDiff('/repo', 2122)).rejects.toMatchObject({
+      code: 'no-github-remote',
+      statusCode: 400,
+    });
+    expect(request).not.toHaveBeenCalled();
+  });
+
+  it('asks the user to connect GitHub before anything else', async () => {
+    getOctokitOrNull.mockReturnValue(null);
+
+    await expect(getPullRequestDiff('/repo', 2122)).rejects.toMatchObject({
+      code: 'github-not-connected',
+      statusCode: 401,
+    });
+    expect(resolveGitHubRepoFromDirectory).not.toHaveBeenCalled();
+  });
+
+  it('treats an empty diff as a missing pull request rather than an empty review', async () => {
+    request.mockResolvedValue({ data: '   ' });
+
+    await expect(getPullRequestDiff('/repo', 2122)).rejects.toMatchObject({
+      code: 'empty-diff',
+      statusCode: 404,
+    });
+  });
+});

packages/web/server/lib/walkthrough/routes.js

@@ -0,0 +1,107 @@
+// `req.destroyed` is true for every healthy request once the body parser has
+// consumed the stream, so using it as a disconnect check silently swallows every
+// response. The response socket is the one that actually reflects whether the
+// client is still there.
+const clientIsGone = (res) => res.writableEnded || res.destroyed;
+
+export function registerWalkthroughRoutes(app, { getWalkthroughService }) {
+  const respondWithError = (res, error, fallback) => {
+    const statusCode = Number(error?.statusCode) || 500;
+    if (statusCode >= 500) {
+      console.error(`${fallback}:`, error);
+    }
+    res.status(statusCode).json({
+      error: error?.message || fallback,
+      ...(error?.code ? { code: error.code } : {}),
+      ...(error?.model ? { model: error.model } : {}),
+      ...(Number.isFinite(error?.requiredChars) ? { requiredChars: error.requiredChars } : {}),
+      ...(Number.isFinite(error?.availableChars) ? { availableChars: error.availableChars } : {}),
+    });
+  };
+
+  const readSource = (value) => {
+    if (typeof value !== 'string' || !value) return null;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  };
+
+  app.get('/api/walkthrough', async (req, res) => {
+    try {
+      const { getWalkthrough, getPullRequestDiff } = await getWalkthroughService();
+      const directory = typeof req.query.directory === 'string' ? req.query.directory : '';
+      if (!directory) {
+        return res.status(400).json({ error: 'directory parameter is required' });
+      }
+
+      const result = await getWalkthrough(
+        {
+          directory,
+          source: readSource(req.query.source),
+          model: typeof req.query.model === 'string' ? req.query.model : undefined,
+        },
+        { getPullRequestDiff },
+      );
+      res.json(result);
+    } catch (error) {
+      respondWithError(res, error, 'Failed to load walkthrough');
+    }
+  });
+
+  // Deliberately not aborted when the client disconnects: generation runs for
+  // minutes and a refresh must not throw the work away. Leaving detaches the
+  // client; the job finishes and caches its result. Stopping is an explicit
+  // request below.
+  app.post('/api/walkthrough/generate', async (req, res) => {
+    try {
+      const { generateWalkthrough, getPullRequestDiff } = await getWalkthroughService();
+      const { directory, source, force, model } = req.body || {};
+      if (!directory || typeof directory !== 'string') {
+        return res.status(400).json({ error: 'directory is required' });
+      }
+
+      const result = await generateWalkthrough(
+        { directory, source, force: force === true, model: typeof model === 'string' ? model : undefined },
+        { getPullRequestDiff },
+      );
+      if (clientIsGone(res)) return;
+      res.json(result);
+    } catch (error) {
+      if (clientIsGone(res)) return;
+      respondWithError(res, error, 'Failed to generate walkthrough');
+    }
+  });
+
+  // Memory-only, so it is safe to poll while a generation runs. The full read
+  // re-runs the whole git pipeline and must not be used for this.
+  app.get('/api/walkthrough/progress', async (req, res) => {
+    try {
+      const { getGenerationStage, getRepositoryRootFor } = await getWalkthroughService();
+      const directory = typeof req.query.directory === 'string' ? req.query.directory : '';
+      if (!directory) {
+        return res.status(400).json({ error: 'directory parameter is required' });
+      }
+
+      const { repoRoot, sourceKey } = await getRepositoryRootFor(directory, readSource(req.query.source));
+      res.json({ stage: getGenerationStage(repoRoot, sourceKey) });
+    } catch (error) {
+      respondWithError(res, error, 'Failed to read walkthrough progress');
+    }
+  });
+
+  app.post('/api/walkthrough/cancel', async (req, res) => {
+    try {
+      const { cancelWalkthroughGeneration } = await getWalkthroughService();
+      const { directory, source } = req.body || {};
+      if (!directory || typeof directory !== 'string') {
+        return res.status(400).json({ error: 'directory is required' });
+      }
+
+      res.json(await cancelWalkthroughGeneration({ directory, source }));
+    } catch (error) {
+      respondWithError(res, error, 'Failed to cancel walkthrough generation');
+    }
+  });
+}

packages/web/server/lib/walkthrough/routes.test.js

@@ -0,0 +1,110 @@
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { registerWalkthroughRoutes } from './routes.js';
+
+// These run over real HTTP on purpose. The bug this file exists for was
+// invisible to unit tests: the service and the store were both correct, and the
+// response was dropped by a disconnect check that misread a healthy request.
+
+const SOURCE = { kind: 'working-tree', scope: 'all' };
+
+describe('walkthrough routes', () => {
+  let server;
+  let base;
+  let releaseJob;
+  let job;
+
+  const service = {
+    async getWalkthrough() {
+      return { walkthrough: null, hunks: [], hunkCount: 0, generating: Boolean(job) };
+    },
+    async generateWalkthrough() {
+      if (job) return job;
+      job = new Promise((resolve) => {
+        releaseJob = () => resolve({ walkthrough: { title: 'DONE' }, hunks: [], hunkCount: 1 });
+      }).finally(() => { job = null; });
+      return job;
+    },
+    async cancelWalkthroughGeneration() {
+      return { cancelled: Boolean(job) };
+    },
+  };
+
+  const generate = (signal) => fetch(`${base}/api/walkthrough/generate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ directory: '/repo', source: SOURCE }),
+    signal,
+  });
+
+  beforeEach(async () => {
+    job = null;
+    releaseJob = undefined;
+    const app = express();
+    app.use(express.json());
+    registerWalkthroughRoutes(app, { getWalkthroughService: async () => service });
+    server = app.listen(0);
+    await new Promise((resolve) => server.once('listening', resolve));
+    base = `http://127.0.0.1:${server.address().port}`;
+  });
+
+  afterEach(async () => {
+    await new Promise((resolve) => server.close(resolve));
+  });
+
+  it('answers a generation request that nobody interrupted', async () => {
+    const pending = generate();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    releaseJob();
+
+    const body = await (await pending).json();
+
+    expect(body.walkthrough).toEqual({ title: 'DONE' });
+  });
+
+  it('delivers the result to a client that reconnected after a refresh', async () => {
+    const controller = new AbortController();
+    generate(controller.signal).catch(() => {});
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    controller.abort();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    // The reloaded page sees work in progress and re-attaches to it.
+    const read = await (await fetch(
+      `${base}/api/walkthrough?directory=/repo&source=${encodeURIComponent(JSON.stringify(SOURCE))}`,
+    )).json();
+    expect(read.generating).toBe(true);
+
+    const reattached = generate();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    releaseJob();
+
+    const body = await (await reattached).json();
+    expect(body.walkthrough).toEqual({ title: 'DONE' });
+  });
+
+  it('rejects a request without a directory before touching the service', async () => {
+    const response = await fetch(`${base}/api/walkthrough/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ source: SOURCE }),
+    });
+
+    expect(response.status).toBe(400);
+    expect(job).toBeNull();
+  });
+
+  it('cancels through its own endpoint rather than a dropped connection', async () => {
+    generate().catch(() => {});
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    const response = await fetch(`${base}/api/walkthrough/cancel`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ directory: '/repo', source: SOURCE }),
+    });
+
+    expect(await response.json()).toEqual({ cancelled: true });
+    releaseJob();
+  });
+});

packages/web/server/lib/walkthrough/schema.js

@@ -0,0 +1,175 @@
+// Shape of the walkthrough the model must produce, plus normalization of what
+// it actually produced. The model is only ever trusted for prose and grouping —
+// every anchor it returns is re-resolved against the digest here, and anything
+// that does not resolve is dropped rather than rendered as a broken stop.
+
+export const WALKTHROUGH_VERSION = 1;
+
+// Bumping this invalidates every cached walkthrough, which is the point: a
+// changed prompt produces different output and old entries would misrepresent
+// what the current code would say.
+export const PROMPT_VERSION = 2;
+
+export const MAX_CHAPTERS = 6;
+export const MAX_STOPS = 16;
+export const MAX_HUNKS_PER_STOP = 14;
+export const MAX_CHAPTER_TITLE_CHARS = 24;
+
+const CHAPTER_ICONS = ['bug', 'wrench', 'path', 'flask', 'doc', 'gear'];
+const STOP_IMPORTANCE = ['critical', 'normal', 'context'];
+
+export const responseSchema = {
+  type: 'object',
+  properties: {
+    title: { type: 'string' },
+    focus: { type: 'string' },
+    chapters: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          icon: { type: 'string', enum: CHAPTER_ICONS },
+          blurb: { type: 'string' },
+          stops: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                title: { type: 'string' },
+                hunks: { type: 'array', items: { type: 'string' } },
+                importance: { type: 'string', enum: STOP_IMPORTANCE },
+                prose: { type: 'string' },
+              },
+              required: ['title', 'hunks', 'importance', 'prose'],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ['title', 'icon', 'blurb', 'stops'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['title', 'focus', 'chapters'],
+  additionalProperties: false,
+};
+
+const asString = (value, max) => {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  return max && trimmed.length > max ? trimmed.slice(0, max) : trimmed;
+};
+
+/**
+ * Turn a raw model response into a walkthrough anchored to real hunk ids.
+ *
+ * @param {object} raw parsed model JSON
+ * @param {Map<string,string>} idByAlias alias → real hunk id, from the digest
+ * @returns {{title: string, focus: string, chapters: Array<object>, droppedAnchors: number}}
+ */
+export function normalizeWalkthrough(raw, idByAlias) {
+  if (!raw || typeof raw !== 'object') {
+    throw Object.assign(new Error('Model returned no walkthrough object'), { code: 'invalid-walkthrough' });
+  }
+
+  const usedIds = new Set();
+  let droppedAnchors = 0;
+  let stopCount = 0;
+
+  const chapters = [];
+  for (const [chapterIndex, rawChapter] of (Array.isArray(raw.chapters) ? raw.chapters : []).entries()) {
+    if (chapters.length >= MAX_CHAPTERS) break;
+    if (!rawChapter || typeof rawChapter !== 'object') continue;
+
+    const stops = [];
+    for (const rawStop of Array.isArray(rawChapter.stops) ? rawChapter.stops : []) {
+      if (stopCount >= MAX_STOPS) break;
+      if (!rawStop || typeof rawStop !== 'object') continue;
+
+      const hunkIds = [];
+      for (const alias of Array.isArray(rawStop.hunks) ? rawStop.hunks : []) {
+        const id = idByAlias.get(typeof alias === 'string' ? alias.trim() : '');
+        if (!id) {
+          droppedAnchors += 1;
+          continue;
+        }
+        // One hunk belongs to exactly one stop; a model that anchors the same
+        // code twice would otherwise render it twice in the stream.
+        if (usedIds.has(id)) continue;
+        if (hunkIds.length >= MAX_HUNKS_PER_STOP) break;
+        usedIds.add(id);
+        hunkIds.push(id);
+      }
+
+      const prose = asString(rawStop.prose);
+      if (hunkIds.length === 0 || !prose) continue;
+
+      stopCount += 1;
+      stops.push({
+        id: `stop-${chapterIndex + 1}-${stops.length + 1}`,
+        title: asString(rawStop.title) || `Step ${stopCount}`,
+        hunkIds,
+        importance: STOP_IMPORTANCE.includes(rawStop.importance) ? rawStop.importance : 'normal',
+        prose,
+      });
+    }
+
+    if (stops.length === 0) continue;
+
+    chapters.push({
+      id: `chapter-${chapters.length + 1}`,
+      title: asString(rawChapter.title, MAX_CHAPTER_TITLE_CHARS) || `Part ${chapters.length + 1}`,
+      icon: CHAPTER_ICONS.includes(rawChapter.icon) ? rawChapter.icon : 'doc',
+      blurb: asString(rawChapter.blurb),
+      stops,
+    });
+  }
+
+  if (chapters.length === 0) {
+    throw Object.assign(
+      new Error('Model returned no usable stops for this diff'),
+      { code: 'invalid-walkthrough' },
+    );
+  }
+
+  return {
+    title: asString(raw.title) || 'Change walkthrough',
+    focus: asString(raw.focus),
+    chapters,
+    droppedAnchors,
+  };
+}
+
+/**
+ * Extract a JSON object from a model response that may or may not honour the
+ * schema — some providers wrap it in prose or a fenced block.
+ */
+export function parseModelJson(text) {
+  if (typeof text !== 'string' || !text.trim()) {
+    throw Object.assign(new Error('Model returned an empty response'), { code: 'invalid-walkthrough' });
+  }
+
+  const withoutFence = text.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
+
+  try {
+    return JSON.parse(withoutFence);
+  } catch {
+    // Fall through to a bounded scan for the outermost object.
+  }
+
+  const start = withoutFence.indexOf('{');
+  if (start === -1) {
+    throw Object.assign(new Error('Model response contained no JSON object'), { code: 'invalid-walkthrough' });
+  }
+
+  for (let end = withoutFence.lastIndexOf('}'); end > start; end = withoutFence.lastIndexOf('}', end - 1)) {
+    try {
+      return JSON.parse(withoutFence.slice(start, end + 1));
+    } catch {
+      // Keep shrinking from the right.
+    }
+  }
+
+  throw Object.assign(new Error('Model response was not valid JSON'), { code: 'invalid-walkthrough' });
+}

packages/web/server/lib/walkthrough/schema.test.js

@@ -0,0 +1,143 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeWalkthrough, parseModelJson, MAX_STOPS } from './schema.js';
+
+const ALIASES = new Map([
+  ['h1', 'working:src/a.ts:aaaa1111'],
+  ['h2', 'working:src/a.ts:bbbb2222'],
+  ['h3', 'working:src/b.ts:cccc3333'],
+]);
+
+const walkthrough = (chapters) => ({ title: 'Change', focus: 'why', chapters });
+
+describe('normalizeWalkthrough', () => {
+  it('maps aliases to real hunk ids and assigns stable local ids', () => {
+    const result = normalizeWalkthrough(walkthrough([
+      {
+        title: 'Data',
+        icon: 'doc',
+        blurb: 'shape first',
+        stops: [
+          { title: 'New field', hunks: ['h1', 'h2'], importance: 'critical', prose: 'Adds a field.' },
+        ],
+      },
+    ]), ALIASES);
+
+    expect(result.chapters[0].id).toBe('chapter-1');
+    expect(result.chapters[0].stops[0]).toMatchObject({
+      id: 'stop-1-1',
+      hunkIds: ['working:src/a.ts:aaaa1111', 'working:src/a.ts:bbbb2222'],
+      importance: 'critical',
+    });
+  });
+
+  it('drops invented aliases instead of rendering a broken anchor', () => {
+    const result = normalizeWalkthrough(walkthrough([
+      {
+        title: 'Data',
+        icon: 'doc',
+        blurb: '',
+        stops: [
+          { title: 'Mixed', hunks: ['h1', 'h99', 'nonsense'], importance: 'normal', prose: 'Something.' },
+        ],
+      },
+    ]), ALIASES);
+
+    expect(result.chapters[0].stops[0].hunkIds).toEqual(['working:src/a.ts:aaaa1111']);
+    expect(result.droppedAnchors).toBe(2);
+  });
+
+  it('anchors each hunk to a single stop', () => {
+    const result = normalizeWalkthrough(walkthrough([
+      {
+        title: 'Data',
+        icon: 'doc',
+        blurb: '',
+        stops: [
+          { title: 'First', hunks: ['h1'], importance: 'normal', prose: 'One.' },
+          { title: 'Second', hunks: ['h1', 'h2'], importance: 'normal', prose: 'Two.' },
+        ],
+      },
+    ]), ALIASES);
+
+    expect(result.chapters[0].stops[0].hunkIds).toEqual(['working:src/a.ts:aaaa1111']);
+    expect(result.chapters[0].stops[1].hunkIds).toEqual(['working:src/a.ts:bbbb2222']);
+  });
+
+  it('discards stops left with no anchor or no prose', () => {
+    const result = normalizeWalkthrough(walkthrough([
+      {
+        title: 'Data',
+        icon: 'doc',
+        blurb: '',
+        stops: [
+          { title: 'Ghost', hunks: ['h99'], importance: 'normal', prose: 'About nothing.' },
+          { title: 'Silent', hunks: ['h1'], importance: 'normal', prose: '   ' },
+          { title: 'Real', hunks: ['h2'], importance: 'normal', prose: 'Actual explanation.' },
+        ],
+      },
+    ]), ALIASES);
+
+    expect(result.chapters[0].stops.map((stop) => stop.title)).toEqual(['Real']);
+  });
+
+  it('rejects a response whose stops all fall away', () => {
+    expect(() => normalizeWalkthrough(walkthrough([
+      { title: 'Empty', icon: 'doc', blurb: '', stops: [{ title: 'Ghost', hunks: ['h99'], importance: 'normal', prose: 'x' }] },
+    ]), ALIASES)).toThrow('no usable stops');
+  });
+
+  it('clamps chapter titles and falls back on unknown enums', () => {
+    const result = normalizeWalkthrough(walkthrough([
+      {
+        title: 'An extremely long chapter title that will not fit the column',
+        icon: 'rocket',
+        blurb: '',
+        stops: [{ title: 'A', hunks: ['h1'], importance: 'urgent', prose: 'Text.' }],
+      },
+    ]), ALIASES);
+
+    expect(result.chapters[0].title.length).toBeLessThanOrEqual(24);
+    expect(result.chapters[0].icon).toBe('doc');
+    expect(result.chapters[0].stops[0].importance).toBe('normal');
+  });
+
+  it('caps the total number of stops', () => {
+    const many = Array.from({ length: 30 }, (_, index) => ({
+      title: `Stop ${index}`,
+      hunks: [['h1', 'h2', 'h3'][index % 3]],
+      importance: 'normal',
+      prose: 'Text.',
+    }));
+
+    const result = normalizeWalkthrough(
+      walkthrough([{ title: 'All', icon: 'doc', blurb: '', stops: many }]),
+      ALIASES,
+    );
+
+    const total = result.chapters.reduce((sum, chapter) => sum + chapter.stops.length, 0);
+    expect(total).toBeLessThanOrEqual(MAX_STOPS);
+    // Only three aliases exist and each is used once, so the real cap here is
+    // the alias pool, not the stop limit.
+    expect(total).toBe(3);
+  });
+});
+
+describe('parseModelJson', () => {
+  it('parses a clean object', () => {
+    expect(parseModelJson('{"title":"x"}')).toEqual({ title: 'x' });
+  });
+
+  it('unwraps a fenced block', () => {
+    expect(parseModelJson('```json\n{"title":"x"}\n```')).toEqual({ title: 'x' });
+  });
+
+  it('recovers an object followed by stray prose', () => {
+    expect(parseModelJson('{"title":"x"}\n\nHope that helps!')).toEqual({ title: 'x' });
+  });
+
+  it('fails loudly on unusable output', () => {
+    expect(() => parseModelJson('')).toThrow('empty response');
+    expect(() => parseModelJson('no json at all')).toThrow('no JSON object');
+    expect(() => parseModelJson('{"broken":')).toThrow('not valid JSON');
+  });
+});

packages/web/server/lib/walkthrough/sources.js

@@ -0,0 +1,116 @@
+import { getDiff, getRangeDiff, getUntrackedDiffs, listUntrackedPaths } from '../git/service.js';
+
+// A walkthrough source resolves to one or more diff *sections*. A section is a
+// patch plus the scope its hunk ids live in; keeping staged and working-tree
+// changes in separate scopes means a stop written against staged code never
+// silently re-anchors onto an unstaged edit of the same lines.
+
+const WORKING_TREE_SCOPES = new Set(['all', 'staged', 'working']);
+
+export class WalkthroughSourceError extends Error {
+  constructor(message, statusCode = 400, code = undefined) {
+    super(message);
+    this.statusCode = statusCode;
+    if (code) this.code = code;
+  }
+}
+
+/**
+ * Normalize and validate an untrusted source descriptor from the client.
+ */
+export function parseSource(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new WalkthroughSourceError('source is required');
+  }
+
+  if (raw.kind === 'working-tree') {
+    const scope = typeof raw.scope === 'string' ? raw.scope : 'all';
+    if (!WORKING_TREE_SCOPES.has(scope)) {
+      throw new WalkthroughSourceError(`Unknown working-tree scope "${scope}"`);
+    }
+    return { kind: 'working-tree', scope };
+  }
+
+  if (raw.kind === 'branch') {
+    const baseRef = typeof raw.baseRef === 'string' ? raw.baseRef.trim() : '';
+    const headRef = typeof raw.headRef === 'string' ? raw.headRef.trim() : '';
+    if (!baseRef || !headRef) {
+      throw new WalkthroughSourceError('branch sources require baseRef and headRef');
+    }
+    return { kind: 'branch', baseRef, headRef };
+  }
+
+  if (raw.kind === 'pr') {
+    const number = Number(raw.number);
+    if (!Number.isInteger(number) || number <= 0) {
+      throw new WalkthroughSourceError('pr sources require a positive number');
+    }
+    return { kind: 'pr', number };
+  }
+
+  throw new WalkthroughSourceError(`Unknown source kind "${String(raw.kind)}"`);
+}
+
+/**
+ * Stable string form of a source, used as the pointer key and as part of the
+ * cache key. Must not change shape casually — it addresses persisted files.
+ */
+export function sourceKey(source) {
+  if (source.kind === 'working-tree') return `working-tree:${source.scope}`;
+  if (source.kind === 'branch') return `branch:${source.baseRef}...${source.headRef}`;
+  return `pr:${source.number}`;
+}
+
+// `git diff` never reports untracked files, so a brand-new file would be
+// invisible in a walkthrough of local work. The batch helper resolves the
+// repository once and bounds how many diff processes run at a time.
+const untrackedSections = async (directory) => {
+  const untracked = await listUntrackedPaths(directory);
+  if (untracked.length === 0) return [];
+
+  const patches = await getUntrackedDiffs(directory, untracked);
+  return patches.filter((patch) => typeof patch === 'string' && patch.trim());
+};
+
+/**
+ * Resolve a source into diff sections.
+ *
+ * @returns {Promise<{sections: Array<{scope: string, patch: string}>, meta: object}>}
+ */
+export async function loadSourceSections(directory, source, { getPullRequestDiff } = {}) {
+  if (source.kind === 'working-tree') {
+    const sections = [];
+
+    if (source.scope === 'all' || source.scope === 'staged') {
+      const patch = await getDiff(directory, { staged: true });
+      if (patch && patch.trim()) sections.push({ scope: 'staged', patch });
+    }
+
+    if (source.scope === 'all' || source.scope === 'working') {
+      const patch = await getDiff(directory, { staged: false });
+      const untracked = await untrackedSections(directory);
+      const combined = [patch, ...untracked].filter((value) => value && value.trim()).join('\n');
+      if (combined.trim()) sections.push({ scope: 'working', patch: combined });
+    }
+
+    return { sections, meta: {} };
+  }
+
+  if (source.kind === 'branch') {
+    const patch = await getRangeDiff(directory, { base: source.baseRef, head: source.headRef });
+    return {
+      sections: patch && patch.trim() ? [{ scope: 'branch', patch }] : [],
+      meta: { baseRef: source.baseRef, headRef: source.headRef },
+    };
+  }
+
+  if (typeof getPullRequestDiff !== 'function') {
+    throw new WalkthroughSourceError('Pull request diffs are unavailable', 500);
+  }
+
+  const { patch, meta } = await getPullRequestDiff(directory, source.number);
+  return {
+    sections: patch && patch.trim() ? [{ scope: `pr:${source.number}`, patch }] : [],
+    meta: meta || {},
+  };
+}

packages/web/server/lib/walkthrough/store.js

@@ -0,0 +1,226 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import fsp from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { PROMPT_VERSION, WALKTHROUGH_VERSION } from './schema.js';
+
+// Two artifacts with two different jobs.
+//
+// Cache entries are content-addressed and immutable: the key is derived from
+// the *current* diff, so a hit means "this walkthrough was written about
+// exactly this code". There is no freshness question to ask of an entry —
+// staleness is a miss.
+//
+// The pointer is mutable and keyed by repository + source only. It answers the
+// questions the cache cannot: which walkthrough was the last one here, what was
+// it written about, and has the code moved since. It is also what feeds the
+// previous walkthrough into a regeneration.
+
+const DATA_DIR = process.env.OPENCHAMBER_DATA_DIR
+  ? path.resolve(process.env.OPENCHAMBER_DATA_DIR)
+  : path.join(os.homedir(), '.config', 'openchamber');
+
+const WALKTHROUGH_DIR = path.join(DATA_DIR, 'walkthroughs');
+const ENTRIES_DIR = path.join(WALKTHROUGH_DIR, 'entries');
+const POINTERS_DIR = path.join(WALKTHROUGH_DIR, 'pointers');
+
+const MAX_ENTRIES = 200;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+
+const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+
+const ensureDir = (dir) => {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    return true;
+  } catch (error) {
+    console.error('[walkthrough] failed to create store directory:', error?.message || error);
+    return false;
+  }
+};
+
+// Atomic so a crash mid-write leaves the previous entry intact rather than a
+// half-written file that later fails to parse.
+const writeJsonAtomic = (filePath, value) => {
+  if (!ensureDir(path.dirname(filePath))) return false;
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(value), 'utf8');
+    fs.renameSync(tmp, filePath);
+    return true;
+  } catch (error) {
+    console.error('[walkthrough] failed to write store file:', error?.message || error);
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      // Nothing else to do; the temp file is already orphaned.
+    }
+    return false;
+  }
+};
+
+const readJson = (filePath) => {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    // Missing, unreadable, or corrupt all mean the same thing to callers: no
+    // usable cached walkthrough. Never throw — a bad cache file must not break
+    // the feature.
+    return null;
+  }
+};
+
+/**
+ * Content-addressed key. Every input that can change the output is in here:
+ * change any of them and you get a miss rather than a stale hit.
+ */
+export function buildCacheKey({ repoRoot, sourceKey, providerID, modelID, files }) {
+  const canonical = JSON.stringify({
+    walkthroughVersion: WALKTHROUGH_VERSION,
+    promptVersion: PROMPT_VERSION,
+    repoRoot,
+    sourceKey,
+    providerID,
+    modelID,
+    files: [...files]
+      .map((file) => ({ path: file.path, status: file.status, hunkIds: file.hunks.map((hunk) => hunk.id) }))
+      .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+  });
+  return sha256(canonical);
+}
+
+const entryPath = (cacheKey) => path.join(ENTRIES_DIR, `${cacheKey}.json`);
+const pointerPath = (repoRoot, sourceKey) => path.join(POINTERS_DIR, `${sha256(`${repoRoot}\0${sourceKey}`)}.json`);
+
+const isWalkthroughEntry = (value) => Boolean(
+  value
+  && typeof value === 'object'
+  && value.walkthroughVersion === WALKTHROUGH_VERSION
+  && value.walkthrough
+  && Array.isArray(value.walkthrough.chapters),
+);
+
+export function readCachedWalkthrough(cacheKey) {
+  const value = readJson(entryPath(cacheKey));
+  return isWalkthroughEntry(value) ? value : null;
+}
+
+export function writeCachedWalkthrough(cacheKey, entry) {
+  const written = writeJsonAtomic(entryPath(cacheKey), {
+    walkthroughVersion: WALKTHROUGH_VERSION,
+    ...entry,
+  });
+  if (written) evictEntries();
+  return written;
+}
+
+export function readPointer(repoRoot, sourceKey) {
+  const value = readJson(pointerPath(repoRoot, sourceKey));
+  if (!value || typeof value !== 'object' || typeof value.cacheKey !== 'string') return null;
+  return value;
+}
+
+export function writePointer(repoRoot, sourceKey, pointer) {
+  return writeJsonAtomic(pointerPath(repoRoot, sourceKey), pointer);
+}
+
+/**
+ * Bound the cache by count and total size, dropping least-recently-used
+ * entries. Pointers are tiny and are left alone; a pointer to an evicted entry
+ * simply reads as "no walkthrough", which is the truthful answer.
+ */
+function evictEntries() {
+  let files;
+  try {
+    files = fs.readdirSync(ENTRIES_DIR)
+      .filter((name) => name.endsWith('.json'))
+      .map((name) => {
+        const full = path.join(ENTRIES_DIR, name);
+        try {
+          const stat = fs.statSync(full);
+          return { full, size: stat.size, atime: stat.atimeMs };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return;
+  }
+
+  let totalBytes = files.reduce((sum, file) => sum + file.size, 0);
+  if (files.length <= MAX_ENTRIES && totalBytes <= MAX_TOTAL_BYTES) return;
+
+  files.sort((a, b) => a.atime - b.atime);
+  let count = files.length;
+  for (const file of files) {
+    if (count <= MAX_ENTRIES && totalBytes <= MAX_TOTAL_BYTES) break;
+    try {
+      fs.unlinkSync(file.full);
+      count -= 1;
+      totalBytes -= file.size;
+    } catch {
+      // Skip files we cannot remove; the next write retries.
+    }
+  }
+}
+
+// Housekeeping runs off the request path and never synchronously.
+//
+// The Electron desktop app hosts this server inside the main process, so a
+// blocking loop here stalls IPC and the window, not just one request. Worse,
+// the paths being checked are user repositories: a worktree on an unplugged
+// drive or an unreachable network share can make a single existence check hang
+// for seconds. Async calls wait without holding the loop, and the cap keeps a
+// pathological directory from turning into a long tail of work.
+const PRUNE_LIMIT = 500;
+
+/**
+ * Drop pointers for repositories that no longer exist. Only ever removes
+ * entries whose subject is provably gone.
+ */
+export async function pruneMissingRepositories() {
+  let names;
+  try {
+    names = (await fsp.readdir(POINTERS_DIR)).filter((name) => name.endsWith('.json'));
+  } catch {
+    return 0;
+  }
+
+  let removed = 0;
+  for (const name of names.slice(0, PRUNE_LIMIT)) {
+    const full = path.join(POINTERS_DIR, name);
+    let repoRoot = null;
+    try {
+      const value = JSON.parse(await fsp.readFile(full, 'utf8'));
+      repoRoot = value && typeof value.repoRoot === 'string' ? value.repoRoot : null;
+    } catch {
+      continue;
+    }
+    if (!repoRoot) continue;
+
+    try {
+      await fsp.stat(repoRoot);
+      continue;
+    } catch (error) {
+      // Unreachable is not the same as gone. Only a definite "no such file"
+      // justifies deleting: a disconnected share or a permissions error must
+      // not cost the user their walkthroughs.
+      if (error?.code !== 'ENOENT') continue;
+    }
+
+    try {
+      await fsp.unlink(full);
+      removed += 1;
+    } catch {
+      // Leave it; the next prune retries.
+    }
+  }
+  return removed;
+}
+
+export const __testing = { WALKTHROUGH_DIR, ENTRIES_DIR, POINTERS_DIR, MAX_ENTRIES, MAX_TOTAL_BYTES };

packages/web/server/lib/walkthrough/store.test.js

@@ -0,0 +1,206 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterAll, beforeEach, describe, expect, it } from 'vitest';
+
+// The store resolves its directory at import time from the environment, so the
+// temp dir has to be in place before the module is loaded.
+const TEMP_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'walkthrough-store-'));
+process.env.OPENCHAMBER_DATA_DIR = TEMP_ROOT;
+
+const store = await import('./store.js');
+const {
+  buildCacheKey,
+  readCachedWalkthrough,
+  writeCachedWalkthrough,
+  readPointer,
+  writePointer,
+  pruneMissingRepositories,
+  __testing,
+} = store;
+
+const files = (overrides = []) => ([
+  {
+    path: 'src/a.ts',
+    status: 'modified',
+    hunks: [{ id: 'working:src/a.ts:aaaa1111' }, { id: 'working:src/a.ts:bbbb2222' }],
+  },
+  {
+    path: 'src/b.ts',
+    status: 'added',
+    hunks: [{ id: 'working:src/b.ts:cccc3333' }],
+  },
+  ...overrides,
+]);
+
+const baseKeyInput = {
+  repoRoot: '/repo',
+  sourceKey: 'working-tree:all',
+  providerID: 'anthropic',
+  modelID: 'claude-haiku-4-5',
+  files: files(),
+};
+
+const entry = (cacheKey) => ({
+  cacheKey,
+  generatedAt: '2026-08-02T00:00:00.000Z',
+  repoRoot: '/repo',
+  sourceKey: 'working-tree:all',
+  model: { providerID: 'anthropic', modelID: 'claude-haiku-4-5' },
+  walkthrough: { title: 'x', focus: '', chapters: [{ id: 'chapter-1', stops: [] }] },
+});
+
+describe('buildCacheKey', () => {
+  it('is stable for identical input', () => {
+    expect(buildCacheKey(baseKeyInput)).toBe(buildCacheKey(baseKeyInput));
+  });
+
+  it('ignores file ordering', () => {
+    const reordered = { ...baseKeyInput, files: [...baseKeyInput.files].reverse() };
+    expect(buildCacheKey(reordered)).toBe(buildCacheKey(baseKeyInput));
+  });
+
+  it('changes when any hunk changes', () => {
+    const edited = {
+      ...baseKeyInput,
+      files: [
+        { ...baseKeyInput.files[0], hunks: [{ id: 'working:src/a.ts:aaaa1111' }, { id: 'working:src/a.ts:dddd4444' }] },
+        baseKeyInput.files[1],
+      ],
+    };
+    expect(buildCacheKey(edited)).not.toBe(buildCacheKey(baseKeyInput));
+  });
+
+  it('separates repositories, sources, and models', () => {
+    const original = buildCacheKey(baseKeyInput);
+    expect(buildCacheKey({ ...baseKeyInput, repoRoot: '/other' })).not.toBe(original);
+    expect(buildCacheKey({ ...baseKeyInput, sourceKey: 'working-tree:staged' })).not.toBe(original);
+    expect(buildCacheKey({ ...baseKeyInput, modelID: 'other-model' })).not.toBe(original);
+    expect(buildCacheKey({ ...baseKeyInput, providerID: 'google' })).not.toBe(original);
+  });
+});
+
+describe('cache entries', () => {
+  beforeEach(() => {
+    fs.rmSync(__testing.ENTRIES_DIR, { recursive: true, force: true });
+    fs.rmSync(__testing.POINTERS_DIR, { recursive: true, force: true });
+  });
+
+  it('round-trips a walkthrough', () => {
+    const key = buildCacheKey(baseKeyInput);
+    expect(writeCachedWalkthrough(key, entry(key))).toBe(true);
+
+    const read = readCachedWalkthrough(key);
+    expect(read.walkthrough.title).toBe('x');
+    expect(read.cacheKey).toBe(key);
+  });
+
+  it('reports a miss for an unknown key', () => {
+    expect(readCachedWalkthrough('0'.repeat(64))).toBeNull();
+  });
+
+  it('treats a corrupt entry as a miss rather than throwing', () => {
+    const key = buildCacheKey(baseKeyInput);
+    writeCachedWalkthrough(key, entry(key));
+    fs.writeFileSync(path.join(__testing.ENTRIES_DIR, `${key}.json`), '{ not json', 'utf8');
+
+    expect(readCachedWalkthrough(key)).toBeNull();
+  });
+
+  it('rejects an entry written by an incompatible version', () => {
+    const key = buildCacheKey(baseKeyInput);
+    writeCachedWalkthrough(key, entry(key));
+    const file = path.join(__testing.ENTRIES_DIR, `${key}.json`);
+    const stored = JSON.parse(fs.readFileSync(file, 'utf8'));
+    fs.writeFileSync(file, JSON.stringify({ ...stored, walkthroughVersion: 999 }), 'utf8');
+
+    expect(readCachedWalkthrough(key)).toBeNull();
+  });
+
+  it('leaves no temp files behind', () => {
+    const key = buildCacheKey(baseKeyInput);
+    writeCachedWalkthrough(key, entry(key));
+
+    const leftovers = fs.readdirSync(__testing.ENTRIES_DIR).filter((name) => name.includes('.tmp'));
+    expect(leftovers).toEqual([]);
+  });
+
+  it('evicts least-recently-used entries past the count limit', () => {
+    for (let index = 0; index < __testing.MAX_ENTRIES + 10; index += 1) {
+      const key = buildCacheKey({ ...baseKeyInput, sourceKey: `source-${index}` });
+      writeCachedWalkthrough(key, entry(key));
+    }
+
+    const remaining = fs.readdirSync(__testing.ENTRIES_DIR).filter((name) => name.endsWith('.json'));
+    expect(remaining.length).toBeLessThanOrEqual(__testing.MAX_ENTRIES);
+  });
+});
+
+describe('pointers', () => {
+  beforeEach(() => {
+    fs.rmSync(__testing.POINTERS_DIR, { recursive: true, force: true });
+  });
+
+  it('round-trips and stays scoped to its source', () => {
+    writePointer('/repo', 'working-tree:all', {
+      repoRoot: '/repo',
+      sourceKey: 'working-tree:all',
+      cacheKey: 'abc',
+      generatedAt: 'now',
+    });
+
+    expect(readPointer('/repo', 'working-tree:all')).toMatchObject({ cacheKey: 'abc' });
+    expect(readPointer('/repo', 'working-tree:staged')).toBeNull();
+  });
+
+  it('keeps different repositories apart', () => {
+    writePointer('/repo-a', 'working-tree:all', { repoRoot: '/repo-a', cacheKey: 'a' });
+    writePointer('/repo-b', 'working-tree:all', { repoRoot: '/repo-b', cacheKey: 'b' });
+
+    expect(readPointer('/repo-a', 'working-tree:all').cacheKey).toBe('a');
+    expect(readPointer('/repo-b', 'working-tree:all').cacheKey).toBe('b');
+  });
+
+  it('prunes only pointers whose repository is gone', async () => {
+    const liveRepo = fs.mkdtempSync(path.join(TEMP_ROOT, 'live-repo-'));
+    writePointer(liveRepo, 'working-tree:all', { repoRoot: liveRepo, cacheKey: 'live' });
+    writePointer('/definitely/not/here', 'working-tree:all', {
+      repoRoot: '/definitely/not/here',
+      cacheKey: 'dead',
+    });
+
+    expect(await pruneMissingRepositories()).toBe(1);
+    expect(readPointer(liveRepo, 'working-tree:all')).toMatchObject({ cacheKey: 'live' });
+    expect(readPointer('/definitely/not/here', 'working-tree:all')).toBeNull();
+  });
+
+  it('keeps a pointer whose repository is merely unreachable', async () => {
+    // A path we cannot stat for a reason other than absence — an unplugged
+    // drive or a dead share behaves this way. Deleting then would cost the user
+    // walkthroughs for a repository that still exists.
+    const blocked = fs.mkdtempSync(path.join(TEMP_ROOT, 'blocked-'));
+    const inaccessible = path.join(blocked, 'inner', 'repo');
+    fs.mkdirSync(path.join(blocked, 'inner'), { recursive: true });
+    fs.mkdirSync(inaccessible);
+    writePointer(inaccessible, 'working-tree:all', { repoRoot: inaccessible, cacheKey: 'blocked' });
+    fs.chmodSync(path.join(blocked, 'inner'), 0o000);
+
+    try {
+      expect(await pruneMissingRepositories()).toBe(0);
+      expect(readPointer(inaccessible, 'working-tree:all')).toMatchObject({ cacheKey: 'blocked' });
+    } finally {
+      fs.chmodSync(path.join(blocked, 'inner'), 0o755);
+    }
+  });
+
+  it('survives a pointer file it cannot parse', async () => {
+    fs.mkdirSync(__testing.POINTERS_DIR, { recursive: true });
+    fs.writeFileSync(path.join(__testing.POINTERS_DIR, 'broken.json'), '{ not json', 'utf8');
+
+    await expect(pruneMissingRepositories()).resolves.toBeGreaterThanOrEqual(0);
+  });
+});
+
+afterAll(() => {
+  fs.rmSync(TEMP_ROOT, { recursive: true, force: true });
+});