product-console-companion 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fynch Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# product-console-companion
+
+A local-first BYOS companion for the [Fynch Product Console](../README.md). Reads code from
+your own machine, so:
+
+- code never leaves your machine — only a small structured verdict (matches/differs + a short
+  explanation) is ever sent back;
+- there's no server-side truncation on what gets read (`server/drift.ts`'s
+  `MAX_FILE_CHARS`/`MAX_TREE_PATHS` don't apply here at all);
+- AI spend bills against your own key/subscription, not the workspace's shared/BYOK credential.
+
+Covers every AI call the hosted Console makes that reads your code — six task kinds as of this
+release (`verify_module` — "Check against code" on a module card; `generate_spec_batch` —
+writing full specs during setup; `propose_skeleton` and `propose_new_capabilities` — the two
+shallow whole-repo scans; `design_prompt` — the free-text export; `analyse_shipment` — the
+passive per-commit drift check behind the GitHub webhook and the "Check GitHub" button), two
+backends, chosen per connection at `connect` time:
+
+- **`api-key`** (default) — no CLI dependency. Calls Anthropic directly with your own API key
+  (`api-key-caller.ts`), running its own two-pass file-select-then-judge, mirroring
+  `server/drift.ts`'s `verifyModuleAgainstCode` but reading local files unbounded.
+- **`cli`** — shells out to an already-authenticated `claude` CLI (`claude-cli-caller.ts`) for
+  full agentic Read/Grep/Glob depth in one call — the model does its own exploring instead of a
+  separate file-select pass. Bills against whatever the CLI is authenticated with (a Claude
+  subscription via `claude setup-token`, or `ANTHROPIC_API_KEY` if the CLI has that set). Runs
+  against a disposable, read-only git worktree (`sandbox.ts`) as defense-in-depth on top of
+  `--restricted --tools "Read,Grep,Glob"`, which should already make a write/exec structurally
+  impossible on its own.
+
+## Setup
+
+```bash
+npx product-console-companion connect \
+  --url https://console.fynchconsulting.com \
+  --token <publicId>.<secret> \
+  --connection <connectionId> \
+  --path /path/to/your/local/checkout \
+  --backend api-key   # or: --backend cli
+```
+
+Get `--token`/`--connection` from the Console's **Companion** button (generates a token and a
+ready-to-paste version of this command) — see `src/CompanionModal.tsx` in the parent repo.
+Running `connect` again for a different `--connection`/`--path` (same `--url`/`--token`) adds a
+second connection to the same local config; one companion process can serve several repos, each
+with its own backend choice.
+
+For `--backend api-key`: `export ANTHROPIC_API_KEY=sk-ant-...` (get one at console.anthropic.com).
+For `--backend cli`: install and authenticate the CLI first — `npm install -g
+@anthropic-ai/claude-code`, then `claude` (interactive login) or set `ANTHROPIC_API_KEY` for it.
+`connect` checks `claude --version` up front and fails fast if it's missing.
+
+Then, in the Console's **Manage connected repos**, switch that repo's execution to "On your
+machine, via companion". Finally, to actually serve tasks:
+
+```bash
+npx product-console-companion run
+```
+
+Polls each configured connection every few seconds until Ctrl+C. Nothing runs while this isn't
+running — see the parent plan's Section 7 for why that's deliberate (goal 4: no AI spend while
+you're not around to notice).
+
+## What's NOT yet implemented (be aware before relying on this)
+
+- **Per-task budget is not enforced client-side for the `api-key` backend.** Every dispatched
+  task carries a `maxBudgetUsd` (visible in the `run` log line); `api-key-caller.ts` does not
+  track spend against it or abort a call that exceeds it. The `cli` backend passes it straight
+  through as `claude`'s own `--max-budget-usd`, which the CLI does enforce (confirmed
+  empirically: it stops and reports `terminal_reason: 'budget_exhausted'`).
+- **No wall-clock timeout for the `api-key` backend** — a hung request blocks that connection's
+  polling loop. The `cli` backend has one (10 minutes, independent of the budget cap — a dollar
+  ceiling doesn't stop a network-stall hang).
+- **Git-fetch-if-missing is `analyse_shipment`-only.** Every other task kind reads whatever HEAD
+  currently is in `--path` (or, for `cli`, a worktree pinned to that HEAD) — correct for those,
+  since they check the *current* state of your code, not a specific historical commit.
+  `analyse_shipment` is different: it's about one specific commit a webhook or the hosted poller
+  told the server about, which the server never fetches for you. It verifies that commit is
+  actually present locally first, attempts one `git fetch` (your own git credentials — never
+  anything from the hosted server) if it isn't, and reports back distinctly (`sha_not_local`)
+  rather than silently analysing the wrong tree state if it still can't find it.
+- **`cli` backend's sandbox worktree isolates writes, not reads** — `--add-dir` points at the
+  disposable worktree, so a read sees exactly what's committed at HEAD, including anything
+  `.gitignore`d being invisible (same as `git ls-files`'s own behavior). Uncommitted local
+  changes in your real checkout are never visible to the CLI backend — worth knowing if you're
+  expecting a check to see work-in-progress edits. (`analyse_shipment`'s own diff read is the one
+  exception: it happens against your real checkout, via `git show`, before the sandbox is even
+  created — the model itself still only ever sees the sandboxed copy.)
+
+## Local development (inside the parent repo)
+
+```bash
+cd companion
+npm install
+npm run dev -- connect --url http://localhost:3101 --token <publicId>.<secret> --connection <connectionId> --path <repo path> --backend api-key
+npm run dev -- run
+```

package/dist/api-key-caller.js

@@ -0,0 +1,371 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildLocalDesignContext } from './design-context.js';
+import { buildLocalRepoContext, listRepoFiles } from './local-scan.js';
+import { appendDiffToVolatile, prepareShipmentAnalysis } from './shipment.js';
+const MAX_CANDIDATE_FILES = 8;
+/** A skip threshold, not a truncation — a file over this is left OUT of what's read entirely
+ *  (with a note in the log), rather than read and cut off partway through. The whole point of
+ *  this backend is that what IS read is never truncated; this only guards against an
+ *  accidentally-selected generated/binary/data file blowing up the prompt. */
+const MAX_FILE_BYTES = 512 * 1024;
+const fileSelectSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['paths'],
+    properties: {
+        paths: {
+            type: 'array',
+            items: { type: 'string' },
+            description: `Up to ${MAX_CANDIDATE_FILES} repo file paths (verbatim from the tree) most likely to implement this module. Prefer source over tests/config. Empty if nothing in the tree plausibly implements it.`,
+        },
+    },
+};
+async function readLocalFile(repoPath, relPath) {
+    try {
+        const buf = await readFile(join(repoPath, relPath));
+        if (buf.byteLength > MAX_FILE_BYTES) {
+            console.warn(`  [skip] ${relPath} is ${Math.round(buf.byteLength / 1024)}KB — over the ${MAX_FILE_BYTES / 1024}KB safety threshold, leaving it out rather than truncating it`);
+            return null;
+        }
+        return buf.toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** Runs the whole verify_module task locally and returns exactly what
+ * POST /api/companion/tasks/:id/result expects — `result` validated server-side against the
+ * exact schema the task shipped with (task.payload.spec.schema), `filesRead` for the UI's
+ * provenance note. Throws on anything that should surface as a task error (caller reports it
+ * via POST .../error). */
+export async function runVerifyModuleTask(client, task, repoPath) {
+    const payload = task.payload;
+    const spec = payload.spec;
+    const allFiles = await listRepoFiles(repoPath);
+    console.log(`  scanning ${allFiles.length} files in ${repoPath}…`);
+    // Pass 1: which files implement this module? Reuses the module-spec text the server already
+    // wrote into spec.volatileText (buildVerifyModuleTaskSpec) as context — it already contains
+    // the full spec, so this doesn't need to re-derive it.
+    const selectPrompt = `${spec.volatileText}
+
+# The repository file tree (${allFiles.length} files)
+
+${allFiles.join('\n')}
+
+# Before judging
+
+First, list the file paths (verbatim from the tree above, up to ${MAX_CANDIDATE_FILES}) most
+likely to implement this module's behaviour. Prefer application source over tests, config, and
+generated files. Empty list if nothing plausibly implements it.`;
+    const selectStream = client.messages.stream({
+        model: spec.model,
+        max_tokens: 2000,
+        thinking: { type: 'adaptive' },
+        output_config: { effort: 'low', format: { type: 'json_schema', schema: fileSelectSchema } },
+        system: spec.system,
+        messages: [{ role: 'user', content: selectPrompt }],
+    });
+    const selectMsg = await selectStream.finalMessage();
+    const selectText = selectMsg.content.find((b) => b.type === 'text');
+    if (!selectText || selectText.type !== 'text')
+        throw new Error('Could not pick files to check (no text in the file-select response).');
+    const known = new Set(allFiles);
+    const chosen = JSON.parse(selectText.text).paths.filter((p) => known.has(p)).slice(0, MAX_CANDIDATE_FILES);
+    if (chosen.length === 0) {
+        return {
+            filesRead: [],
+            result: {
+                verdict: 'differs',
+                specSaid: 'See the module spec above.',
+                codeDid: 'No file in the local checkout appears to implement this module.',
+                differences: ['Nothing in the local checkout plausibly implements this spec — it may be unbuilt, or the code lives outside this checkout.'],
+            },
+        };
+    }
+    const files = (await Promise.all(chosen.map(async (p) => {
+        const content = await readLocalFile(repoPath, p);
+        return content !== null ? { path: p, content } : null;
+    }))).filter((f) => f !== null);
+    console.log(`  reading ${files.map((f) => f.path).join(', ') || '(nothing readable)'}`);
+    // Pass 2: does the code satisfy the spec? spec.system/spec.volatileText/spec.schema are sent
+    // by the server unchanged — this is the exact same prompt+schema the server-execution path
+    // would use, just pointed at unbounded local file contents instead of truncated GitHub reads.
+    const content = [];
+    if (spec.stableText)
+        content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
+    content.push({
+        type: 'text',
+        text: `${spec.volatileText}\n\n# The actual code, as it currently stands locally\n\n${files.map((f) => `## ${f.path}\n\n\`\`\`\n${f.content}\n\`\`\``).join('\n\n')}`,
+    });
+    const verdictStream = client.messages.stream({
+        model: spec.model,
+        max_tokens: spec.maxTokens,
+        thinking: { type: 'adaptive' },
+        output_config: spec.schema
+            ? { effort: spec.effort, format: { type: 'json_schema', schema: spec.schema } }
+            : { effort: spec.effort },
+        system: spec.system,
+        messages: [{ role: 'user', content }],
+    });
+    const verdictMsg = await verdictStream.finalMessage();
+    if (verdictMsg.stop_reason === 'refusal')
+        throw new Error('The model declined to check this module.');
+    const verdictText = verdictMsg.content.find((b) => b.type === 'text');
+    if (!verdictText || verdictText.type !== 'text')
+        throw new Error('No verdict returned.');
+    return { result: JSON.parse(verdictText.text), filesRead: files.map((f) => f.path) };
+}
+/* ------------------------------------------------------------------ generate_spec_batch */
+/** Matches verify_module's own MAX_CANDIDATE_FILES — tried lower (4) first on the theory that a
+ *  batch multiplies by however many modules it holds, but a real end-to-end test caught it
+ *  under-reading: a module genuinely spread across companion/, server/, and src/ (this repo's
+ *  own "Local Companion Agent" module, dogfooded during Phase 3 development) got 4 real files
+ *  read and produced an accurate spec for what it saw, but never even considered
+ *  server/companion.ts or src/CompanionModal.tsx — half the actual implementation. Comfortably
+ *  beats the server path's own FILES_PER_MODULE=2 (bootstrap.ts) either way; this raises the
+ *  ceiling for the genuinely multi-file case rather than assuming it wouldn't come up. */
+const MAX_FILES_PER_MODULE_IN_BATCH = 8;
+const batchFileSelectSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['selections'],
+    properties: {
+        selections: {
+            type: 'array',
+            description: 'One entry per module in the batch, in the same order.',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['moduleId', 'paths'],
+                properties: {
+                    moduleId: { type: 'string' },
+                    paths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: `Up to ${MAX_FILES_PER_MODULE_IN_BATCH} repo file paths (verbatim from the tree) most likely to implement this module. Empty if nothing plausibly does.`,
+                    },
+                },
+            },
+        },
+    },
+};
+/** Runs a whole generate_spec_batch task locally — writes full specs for every module in the
+ *  batch (up to server/bootstrap.ts's BATCH_SIZE, currently 5) in one task. Same two-pass shape
+ *  as runVerifyModuleTask (pick files, then use them), just per-module in pass 1 and producing
+ *  the whole specs array in pass 2. `spec.volatileText` already carries the per-module id/lane/
+ *  purpose breakdown and the "find files yourself" instruction (buildSpecBatchVolatile,
+ *  server/bootstrap.ts) — this only adds the file tree and, in pass 2, what was actually read. */
+export async function runGenerateSpecBatchTask(client, task, repoPath) {
+    const payload = task.payload;
+    const spec = payload.spec;
+    const moduleIds = payload.moduleIds;
+    const allFiles = await listRepoFiles(repoPath);
+    console.log(`  scanning ${allFiles.length} files in ${repoPath} for ${moduleIds.length} module(s)…`);
+    // Pass 1: which files relate to each module in this batch?
+    const selectPrompt = `${spec.volatileText}
+
+# The repository file tree (${allFiles.length} files)
+
+${allFiles.join('\n')}
+
+# Before writing specs
+
+For EACH module above (by id: ${moduleIds.join(', ')}), list up to ${MAX_FILES_PER_MODULE_IN_BATCH}
+file paths (verbatim from the tree above) most likely to implement it. One entry per module id,
+in the same order as given.`;
+    const selectStream = client.messages.stream({
+        model: spec.model,
+        max_tokens: 3000,
+        thinking: { type: 'adaptive' },
+        output_config: { effort: 'low', format: { type: 'json_schema', schema: batchFileSelectSchema } },
+        system: spec.system,
+        messages: [{ role: 'user', content: selectPrompt }],
+    });
+    const selectMsg = await selectStream.finalMessage();
+    const selectText = selectMsg.content.find((b) => b.type === 'text');
+    if (!selectText || selectText.type !== 'text')
+        throw new Error('Could not pick files for this batch (no text in the file-select response).');
+    const known = new Set(allFiles);
+    const selections = JSON.parse(selectText.text).selections;
+    const uniquePaths = [...new Set(selections.flatMap((s) => s.paths.filter((p) => known.has(p)).slice(0, MAX_FILES_PER_MODULE_IN_BATCH)))];
+    const fileMap = new Map();
+    await Promise.all(uniquePaths.map(async (p) => {
+        const content = await readLocalFile(repoPath, p);
+        if (content !== null)
+            fileMap.set(p, content);
+    }));
+    console.log(`  reading ${[...fileMap.keys()].join(', ') || '(nothing readable)'}`);
+    // Pass 2: write the actual specs, grounded in what was read.
+    const filesSection = selections
+        .map((s) => {
+        const found = s.paths.filter((p) => fileMap.has(p));
+        return `## Files read for ${s.moduleId}\n\n${found.length ? found.map((p) => `### ${p}\n\`\`\`\n${fileMap.get(p)}\n\`\`\``).join('\n\n') : '(nothing readable found for this module)'}`;
+    })
+        .join('\n\n');
+    const content = [];
+    if (spec.stableText)
+        content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
+    content.push({ type: 'text', text: `${spec.volatileText}\n\n# Related files, as found in the local checkout\n\n${filesSection}` });
+    const writeStream = client.messages.stream({
+        model: spec.model,
+        max_tokens: spec.maxTokens,
+        thinking: { type: 'adaptive' },
+        output_config: spec.schema ? { effort: spec.effort, format: { type: 'json_schema', schema: spec.schema } } : { effort: spec.effort },
+        system: spec.system,
+        messages: [{ role: 'user', content }],
+    });
+    const writeMsg = await writeStream.finalMessage();
+    if (writeMsg.stop_reason === 'refusal')
+        throw new Error('The model declined to write specs for this batch.');
+    const writeText = writeMsg.content.find((b) => b.type === 'text');
+    if (!writeText || writeText.type !== 'text')
+        throw new Error('No specs returned.');
+    return { result: JSON.parse(writeText.text), filesRead: [...fileMap.keys()] };
+}
+/* ---------------------------------------------------- propose_skeleton / propose_new_capabilities */
+/**
+ * Both propose_skeleton and propose_new_capabilities are "shallow whole-repo" tasks — server
+ * sends stableText/volatileText built with NO repo content at all (see bootstrap.ts's
+ * stableTextForLocalDispatch / buildCapabilityScanVolatile's repoCtx-null branch), because
+ * there's nothing GitHub-sourced to send: the whole point of dispatching is that the companion
+ * reads the repo itself. Unlike verify_module/generate_spec_batch, there's no per-module drilling
+ * here — just one shallow local scan (file tree + README/CHANGELOG/package.json, mirroring
+ * server/bootstrap.ts's own RepoContext shape) appended after spec.volatileText, then one model
+ * call. filesRead is always empty for these two: neither result shape uses it (check
+ * server/index.ts's completeAiJob payloads for /api/setup/skeleton and
+ * /api/module-suggestions/scan — neither includes it), so there's nothing meaningful to report.
+ */
+async function runShallowRepoTask(client, spec, repoPath) {
+    const repoCtx = await buildLocalRepoContext(repoPath);
+    console.log(`  scanning ${repoCtx.fileList.length} files, README ${repoCtx.readme ? 'found' : 'not found'}, CHANGELOG ${repoCtx.changelog ? 'found' : 'not found'}, package.json ${repoCtx.packageJson ? 'found' : 'not found'}`);
+    const repoSection = `
+# Repository context (your local checkout)
+
+## File tree (${repoCtx.fileList.length} files)
+${repoCtx.fileList.join('\n')}
+
+## README
+${repoCtx.readme ?? '(none found)'}
+
+## CHANGELOG
+${repoCtx.changelog ?? '(none found)'}
+
+## package.json
+${repoCtx.packageJson ?? '(none found)'}
+`.trim();
+    const content = [];
+    if (spec.stableDocumentBase64) {
+        content.push({ type: 'document', source: { type: 'base64', media_type: 'application/pdf', data: spec.stableDocumentBase64 } });
+    }
+    if (spec.stableText)
+        content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
+    content.push({ type: 'text', text: `${spec.volatileText}\n\n${repoSection}` });
+    const stream = client.messages.stream({
+        model: spec.model,
+        max_tokens: spec.maxTokens,
+        thinking: { type: 'adaptive' },
+        output_config: spec.schema ? { effort: spec.effort, format: { type: 'json_schema', schema: spec.schema } } : { effort: spec.effort },
+        system: spec.system,
+        messages: [{ role: 'user', content }],
+    });
+    const message = await stream.finalMessage();
+    if (message.stop_reason === 'refusal')
+        throw new Error('The model declined this request.');
+    const text = message.content.find((b) => b.type === 'text');
+    if (!text || text.type !== 'text')
+        throw new Error('No result returned.');
+    return { result: JSON.parse(text.text), filesRead: [] };
+}
+export async function runProposeSkeletonTask(client, task, repoPath) {
+    const payload = task.payload;
+    return runShallowRepoTask(client, payload.spec, repoPath);
+}
+export async function runProposeNewCapabilitiesTask(client, task, repoPath) {
+    const payload = task.payload;
+    return runShallowRepoTask(client, payload.spec, repoPath);
+}
+/* --------------------------------------------------------------------- design_prompt */
+/**
+ * The one task kind with no schema — spec.schema is undefined, so the model's raw text answer
+ * IS the result, never JSON.parse'd (unlike every other task kind here). Looks for local design
+ * signal (findDesignFiles, copied verbatim from server/design-context.ts — see design-context.ts's
+ * own comment) and appends it if found; spec.volatileText already carries the right instructions
+ * for both the "honor what you find" and "propose from scratch" cases (see export.ts's
+ * generateDesignPrompt — the local-dispatch branch decides which wording to send based on the
+ * same `direction` the server path already respects, before this ever reaches the companion).
+ */
+export async function runDesignPromptTask(client, task, repoPath) {
+    const payload = task.payload;
+    const spec = payload.spec;
+    const designContext = await buildLocalDesignContext(repoPath);
+    console.log(`  design signal: ${designContext ? 'found' : 'none found'}`);
+    const content = [];
+    if (spec.stableText)
+        content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
+    content.push({
+        type: 'text',
+        text: designContext ? `${spec.volatileText}\n\n# Design signal found in your local checkout\n\n${designContext}` : spec.volatileText,
+    });
+    const stream = client.messages.stream({
+        model: spec.model,
+        max_tokens: spec.maxTokens,
+        thinking: { type: 'adaptive' },
+        output_config: spec.schema ? { effort: spec.effort, format: { type: 'json_schema', schema: spec.schema } } : { effort: spec.effort },
+        system: spec.system,
+        messages: [{ role: 'user', content }],
+    });
+    const message = await stream.finalMessage();
+    if (message.stop_reason === 'refusal')
+        throw new Error('The model declined to write a design prompt.');
+    const text = message.content.find((b) => b.type === 'text');
+    if (!text || text.type !== 'text')
+        throw new Error('No design prompt returned.');
+    return { result: text.text, filesRead: [] }; // filesRead unused for this kind — see propose_skeleton/propose_new_capabilities's own comment
+}
+/* --------------------------------------------------------------------- analyse_shipment */
+/**
+ * Runs a whole analyse_shipment task locally. Unlike every other task kind above, this one's
+ * "find the relevant content" step is git-level, not file-level (prepareShipmentAnalysis, see
+ * shipment.ts), and can conclude the task WITHOUT ever calling the model at all — a commit the
+ * companion's own local looksTrivial filter rejects is reported straight back as an empty
+ * result ({touched: [], possibleNewModules: []}), exactly the shape driftSchema already treats
+ * as a valid "nothing plausible here" answer, so there's no separate result shape to teach the
+ * server about. sha_not_local throws — the caller (cli.ts's runOneTask) reports it as a task
+ * error via POST .../error, which surfaces to checkConnection as one caught, per-commit failure
+ * (see server/poller.ts's own comment), not a crash that would wedge the rest of that check.
+ */
+export async function runAnalyseShipmentTask(client, task, repoPath) {
+    const payload = task.payload;
+    const prep = await prepareShipmentAnalysis(repoPath, payload.sha);
+    if (prep.outcome === 'sha_not_local') {
+        throw new Error(`sha_not_local: commit ${payload.sha} was not found in the local checkout at ${repoPath}, even after a git fetch.`);
+    }
+    if (prep.outcome === 'trivial') {
+        console.log(`  ${payload.sha.slice(0, 7)} looks trivial (lockfile/CI-config/build-output only) — skipping the AI call`);
+        return { result: { touched: [], possibleNewModules: [] }, filesRead: [] };
+    }
+    console.log(`  read ${payload.sha.slice(0, 7)}'s diff locally (${prep.diffText.length} chars, ${prep.changedPaths.length} file(s) changed)`);
+    const spec = appendDiffToVolatile(payload.spec, prep.diffText, prep.changedPaths);
+    const content = [];
+    if (spec.stableText)
+        content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
+    content.push({ type: 'text', text: spec.volatileText });
+    const stream = client.messages.stream({
+        model: spec.model,
+        max_tokens: spec.maxTokens,
+        thinking: { type: 'adaptive' },
+        output_config: spec.schema ? { effort: spec.effort, format: { type: 'json_schema', schema: spec.schema } } : { effort: spec.effort },
+        system: spec.system,
+        messages: [{ role: 'user', content }],
+    });
+    const message = await stream.finalMessage();
+    if (message.stop_reason === 'refusal')
+        throw new Error('The model declined to analyse this shipment.');
+    const text = message.content.find((b) => b.type === 'text');
+    if (!text || text.type !== 'text')
+        throw new Error('No drift analysis returned.');
+    // filesRead unused for this kind, same as propose_skeleton/propose_new_capabilities above —
+    // dispatchAndAwaitLocalTask's caller (poller.ts) only consumes the parsed result, not filesRead.
+    return { result: JSON.parse(text.text), filesRead: [] };
+}