@stravica-ai/digital-operator-pa 0.1.8 → 0.1.11

package/dist/engineering-pa-cli/src/knowledge/cli.mjs

@@ -63,6 +63,10 @@ Graph location: <repo-root>/operator/knowledge/.graph.json.
 Repo-root resolution: \$DAVE_REPO_ROOT / \$PA_REPO_ROOT, else walk upward
 from cwd looking for a .git entry.
 
+The graph is a per-device artefact: untracked, and rebuilt locally by
+library-sync-cycle's graph-rebuild leg. If it is absent, the first query
+rebuilds it on demand (one stderr line, then the answer) rather than failing.
+
 JSON output shape (stable-by-convention — consumed by dispatch-briefer):
   { "verb": "<name>", ...verb-specific fields }
 

package/dist/engineering-pa-cli/src/knowledge/graph.mjs

@@ -31,12 +31,65 @@ const GRAPH_RELATIVE_PATH = 'operator/knowledge/.graph.json';
 
 // --- loader ---------------------------------------------------------------
 
-export async function loadGraph({ repoRoot, graphPath } = {}) {
+// SELF-HEAL ON A MISSING GRAPH (w-2026-07-29-007)
+//
+// Since the estate moved to per-device retrieval artefacts (w-2026-07-29-002),
+// `.graph.json` is untracked and rebuilt locally by `library-sync-cycle`'s
+// graph-rebuild leg. Any host that pulls the untracking commit before it runs a
+// sync cycle -- an unmigrated laptop, a host that has been off during a move --
+// therefore has a knowledge tree on disk and no graph over it, and every
+// `pa knowledge` verb used to exit 3. Refusing to answer when the source data
+// is right there is the wrong default for a retrieval tool.
+//
+// So a missing artefact triggers an on-demand build (same two builders, same
+// order, same root as the scheduled leg) and the query is served. The artefact
+// is a pure function of the tree, so this cannot produce a graph the scheduled
+// leg would not have produced -- only a less well-stamped one, which the
+// `coverage.builtBy` marker makes visible.
+//
+// GATE. Self-heal fires only when the caller passed a `repoRoot` and did NOT
+// pass an explicit `graphPath`. An explicit `graphPath` means the caller is
+// pointing at a specific artefact (a fixture, a snapshot, an inspection copy);
+// the builders write to `<root>/operator/knowledge/.graph.json` and nowhere
+// else, so building would silently answer a different question than the one
+// asked. Those callers keep the exit-3 refusal.
+//
+// Set `autoBuild: false` to opt out entirely.
+export async function loadGraph({ repoRoot, graphPath, autoBuild = true, stderr = process.stderr } = {}) {
   const path = graphPath ?? join(repoRoot, GRAPH_RELATIVE_PATH);
   if (!existsSync(path)) {
-    const err = new Error(`knowledge graph not found at ${path}`);
-    err.exitCode = 3;
-    throw err;
+    const canBuild = autoBuild && Boolean(repoRoot) && graphPath == null;
+    if (!canBuild) {
+      const err = new Error(`knowledge graph not found at ${path}`);
+      err.exitCode = 3;
+      throw err;
+    }
+    try {
+      const { rebuildRetrievalArtefacts } = await import('./rebuild.mjs');
+      const built = await rebuildRetrievalArtefacts({ root: repoRoot });
+      stderr.write(
+        `[pa knowledge] no graph at ${path} -- built on demand ` +
+        `(${built.nodeCount} nodes, ${built.edgeCount} edges, ${built.durationMs}ms); ` +
+        'retrieval artefacts are per-device and normally rebuilt by library-sync-cycle\n',
+      );
+    } catch (e) {
+      // Both errors, in one message: "graph missing" alone sends the reader
+      // looking for the artefact, when what they need to fix is why it could
+      // not be built.
+      const err = new Error(
+        `knowledge graph not found at ${path}, and the on-demand rebuild failed: ${e.message}`,
+      );
+      err.exitCode = 3;
+      err.cause = e;
+      throw err;
+    }
+    if (!existsSync(path)) {
+      const err = new Error(
+        `knowledge graph not found at ${path}, and the on-demand rebuild did not produce it`,
+      );
+      err.exitCode = 3;
+      throw err;
+    }
   }
   let raw;
   try {

package/dist/engineering-pa-cli/src/knowledge/rebuild.mjs

@@ -0,0 +1,118 @@
+// rebuild.mjs — in-process rebuild of the retrieval artefacts.
+//
+// WHY THIS EXISTS
+// ---------------
+// As of 2026-07-29 (estate ruling w-2026-07-29-002) `operator/knowledge/.graph.json`
+// and `.backlinks.json` are PER-DEVICE artefacts: untracked by the library
+// repos, and rebuilt locally by `library-sync-cycle`'s `graph-rebuild` leg
+// immediately after the down-path materialises the tree they describe. Each
+// device's graph then describes exactly the tree that device can see, instead
+// of one build host's partial view being shipped to everyone.
+//
+// The migration has a gap. A host that pulls the untracking commit but has not
+// yet run a sync cycle -- or whose cycle is not installed at all -- ends up with
+// no artefact on disk, and every `pa knowledge` verb hard-failed with exit 3
+// ("knowledge graph not found"). The retrieval tool going dark is a bad failure
+// for a host whose whole job is to answer questions from the library, and the
+// data needed to fix it is sitting right there on disk.
+//
+// So `loadGraph` self-heals: on a missing artefact it calls this module, which
+// runs the same two builders the graph-rebuild leg runs, in the same order,
+// against the same workspace root -- then serves the query. The artefact is a
+// pure function of the tree, so building it on demand cannot produce anything
+// the scheduled leg would not have produced.
+//
+// IN-PROCESS, NOT SPAWNED
+// -----------------------
+// The builders ship in the same package as this module, so we import and call
+// them rather than spawning `node <script> --root <root>`. That removes a
+// process launch (~50 ms of the total) and, more importantly, removes the
+// `--root`-resolution hazard entirely: a spawned builder without `--root`
+// resolves its default four levels up from its own script path, which for a
+// package install lands inside the versioned `dist/` tree rather than the
+// workspace (the "versioned-dist-path trap"). An imported function takes the
+// root as an argument and cannot get this wrong.
+//
+// PROVENANCE
+// ----------
+// Both artefacts carry a `coverage` stamp naming which path built them. The
+// scheduled leg writes `builtBy: 'library-sync-cycle:graph-rebuild'` plus the
+// device's entitlement picture; this path writes `builtBy: 'loadGraph:on-demand'`
+// and honestly reports `complete: null`, because a CLI invocation has no
+// registry context and therefore cannot know which knowledge mounts this device
+// is not entitled to. An on-demand graph is a fallback, not a substitute for
+// the stamped one -- and it says so in its own output.
+
+import { buildBacklinkIndex } from '../../../engineering-pa-core/src/knowledge/retrieval/backlink-indexer.mjs';
+import { buildKnowledgeGraph } from '../../../engineering-pa-core/src/knowledge/retrieval/graph-builder.mjs';
+
+/** Marks artefacts produced by the self-heal path rather than the scheduled leg. */
+export const ON_DEMAND_BUILT_BY = 'loadGraph:on-demand';
+
+/**
+ * The coverage stamp this path writes.
+ *
+ * Shape-compatible with the one `library-sync-cycle:graph-rebuild` writes so a
+ * reader can branch on the same fields, but honest about what it does not know:
+ * `complete: null` means "this build could not determine its own coverage",
+ * which is different from `false` ("it has a named hole"). `registryError`
+ * carries the reason in the same slot the scheduled leg uses, so the estate's
+ * `formatCoverageSummary` renders a truthful "coverage UNKNOWN (...)" line
+ * without special-casing.
+ *
+ * `rebuildDurationMs` stays null on this path: the stamp has to exist before the
+ * artefacts are serialised, so the elapsed time is not known yet. The caller
+ * gets it as a return value for its stderr line instead of the artefact
+ * carrying a number it would have to be rewritten to hold.
+ *
+ * @param {{workspace:string, builtOn?:string}} args
+ * @returns {object}
+ */
+export function buildOnDemandCoverage({
+  workspace,
+  builtOn = new Date().toISOString(),
+}) {
+  return {
+    builtOn,
+    deviceId: null,
+    builtBy: ON_DEMAND_BUILT_BY,
+    workspace,
+    sourceMarkdownCount: null,
+    rebuildDurationMs: null,
+    registryDir: null,
+    entitledRepos: [],
+    unentitledRepos: [],
+    unentitledKnowledgeMountTargets: [],
+    complete: null,
+    registryError: 'built on demand by pa knowledge -- no registry context, coverage not determined',
+  };
+}
+
+/**
+ * Rebuild `.backlinks.json` then `.graph.json` over `root`.
+ *
+ * Order is a correctness property, not a preference: `graph-builder` reads the
+ * file `backlink-indexer` writes, so running them the other way round builds a
+ * graph from the previous run's backlinks.
+ *
+ * Throws whatever the builders throw (a missing `operator/knowledge/` yields
+ * ENOENT on the first write) -- the caller decides how loud to be.
+ *
+ * @param {{root:string, coverage?:object|null}} args
+ * @returns {Promise<{nodeCount:number, edgeCount:number, targetCount:number, durationMs:number, graphPath:string, backlinksPath:string}>}
+ */
+export async function rebuildRetrievalArtefacts({ root, coverage }) {
+  const started = Date.now();
+  const stamp = coverage ?? buildOnDemandCoverage({ workspace: root });
+  const backlinks = await buildBacklinkIndex({ root, coverage: stamp });
+  const graph = await buildKnowledgeGraph({ root, coverage: stamp });
+  const durationMs = Date.now() - started;
+  return {
+    nodeCount: graph.nodeCount,
+    edgeCount: graph.edgeCount,
+    targetCount: backlinks.targetCount,
+    durationMs,
+    graphPath: graph.outPath,
+    backlinksPath: backlinks.outPath,
+  };
+}

package/dist/engineering-pa-cli/src/launch/identity.mjs

@@ -1,32 +1,98 @@
 // identity.mjs — pure: load + validate an agent identity from the operator roster.
-// Roster path: <repoRoot>/operator/knowledge/hr/roster/<name>.json
+//
+// Roster resolution is mount-aware (w-2026-07-29-007). Rosters live at two
+// levels of the operator knowledge tree:
+//   1. Flat (HQ) path:      <repoRoot>/operator/knowledge/hr/roster/<name>.json
+//   2. Team-mount subtrees: <repoRoot>/operator/knowledge/<team>/hr/roster/<name>.json
+//      (e.g. WSD's dex at operator/knowledge/wsd/hr/roster/dex.json)
+//
+// The flat path is checked first, then every team mount. A single hit --
+// wherever it lives -- resolves. The SAME agent name present in more than one
+// roster (flat + team, or two teams) is an ambiguity the operator must fix:
+// the loader errors listing every matching path rather than silently picking
+// one. Silent precedence is exactly the failure mode this guards against -- a
+// stale flat copy shadowing a team roster (or vice versa) would launch an
+// agent under the wrong identity with no signal.
+//
 // Required fields: id, name, roleId, runFolder, status
-import { readFile } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 const REQUIRED_FIELDS = ['id', 'name', 'roleId', 'runFolder', 'status'];
 
-export async function loadIdentity(repoRoot, agentName) {
-  const path = join(repoRoot, 'operator', 'knowledge', 'hr', 'roster', `${agentName}.json`);
-  let raw;
+const ROSTER_SEGMENTS = ['hr', 'roster'];
+
+function flatRosterPath(repoRoot, agentName) {
+  return join(repoRoot, 'operator', 'knowledge', ...ROSTER_SEGMENTS, `${agentName}.json`);
+}
+
+// Enumerate team-mount roster candidates: operator/knowledge/<team>/hr/roster/<name>.json.
+// Directory listing is sorted so error output is deterministic across
+// filesystems. The flat tree's own `hr/` directory is skipped --
+// `operator/knowledge/hr` is the flat roster's parent, not a team mount, and
+// matching it would double-count the flat path.
+async function teamRosterPaths(repoRoot, agentName) {
+  const knowledgeRoot = join(repoRoot, 'operator', 'knowledge');
+  let entries;
+  try {
+    entries = await readdir(knowledgeRoot, { withFileTypes: true });
+  } catch {
+    return []; // no knowledge tree at all -- nothing to scan
+  }
+  return entries
+    .filter((e) => e.isDirectory() && e.name !== 'hr')
+    .map((e) => e.name)
+    .sort()
+    .map((team) => join(knowledgeRoot, team, ...ROSTER_SEGMENTS, `${agentName}.json`));
+}
+
+// Read a roster file's raw content, distinguishing "not there" (null) from
+// real read failures (thrown, exitCode 3).
+async function readRosterFile(path, agentName) {
   try {
-    raw = await readFile(path, 'utf8');
+    return await readFile(path, 'utf8');
   } catch (err) {
-    if (err.code === 'ENOENT') {
-      const e = new Error(`agent "${agentName}" not found in roster (${path})`);
-      e.exitCode = 2;
-      throw e;
-    }
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return null;
     const e = new Error(`could not read roster file for "${agentName}": ${err.message}`);
     e.exitCode = 3;
     throw e;
   }
+}
+
+export async function loadIdentity(repoRoot, agentName) {
+  const flatPath = flatRosterPath(repoRoot, agentName);
+  const candidates = [flatPath, ...(await teamRosterPaths(repoRoot, agentName))];
+
+  const hits = [];
+  for (const candidate of candidates) {
+    const content = await readRosterFile(candidate, agentName);
+    if (content !== null) hits.push({ path: candidate, content });
+  }
+
+  if (hits.length === 0) {
+    const e = new Error(
+      `agent "${agentName}" not found in roster (searched ${flatPath} and team mounts operator/knowledge/*/hr/roster/)`,
+    );
+    e.exitCode = 2;
+    throw e;
+  }
+  if (hits.length > 1) {
+    const e = new Error(
+      `agent "${agentName}" is ambiguous -- found in ${hits.length} rosters: ${hits
+        .map((h) => h.path)
+        .join(', ')}. Remove the duplicate roster entry (or rename one agent) before launching.`,
+    );
+    e.exitCode = 2;
+    throw e;
+  }
+
+  const { path: resolvedPath, content: raw } = hits[0];
 
   let data;
   try {
     data = JSON.parse(raw);
   } catch (err) {
-    const e = new Error(`roster file for "${agentName}" is not valid JSON: ${err.message}`);
+    const e = new Error(`roster file for "${agentName}" is not valid JSON (${resolvedPath}): ${err.message}`);
     e.exitCode = 2;
     throw e;
   }

package/dist/engineering-pa-core/docs/knowledge-scaffold.md

@@ -56,7 +56,13 @@ Use double-bracket syntax to link to other documents:
 See [[fermentation]] for details on lacto-fermentation.
 ```
 
-Wiki-links are resolved by searching for a file matching the target name (case-insensitive) across all knowledge domains. If multiple matches exist, the link resolves to the most recently updated one.
+Wiki-links are resolved against the real file set, in this order:
+
+1. A target containing a `/` (`[[../wespa/spi-no-staging]]`, `[[engineering/standards/secrets]]`) is tried relative to the linking document first, then repo-root-relative, then relative to each knowledge root. An over-deep `../` chain is salvaged when exactly one file can be meant.
+2. A bare target (`[[fermentation]]`) matches on filename across all knowledge domains -- exact case first, case-insensitive second.
+3. If several files share the name, the one in the linking document's own directory wins, then the one in its own domain. If neither disambiguates, the link is reported as ambiguous and produces no edge -- the builder does not guess, because a guess silently changes what `related`, `path` and `orphans` answer.
+
+A wiki-link that resolves to nothing is reported as dangling and produces no edge. It is never turned into a node: a graph that invents a document for every broken reference inflates itself and corrupts its own orphan statistics.
 
 ### Standard markdown links
 
@@ -66,6 +72,26 @@ Use standard markdown links for explicit paths:
 See [fermentation](techniques/fermentation.md) for details.
 ```
 
+Markdown links resolve relative to the linking document. Unlike wiki-links, a markdown link to a file that is not present still produces a node -- that is deliberate, and is how a document the build host is not entitled to stays visible in the graph.
+
+### Machine-readable hubs (`index.json`)
+
+A directory can carry an `index.json` listing its documents with curated descriptions:
+
+```json
+{
+  "version": "1.0",
+  "patterns": [
+    { "id": "some-pattern", "path": "knowledge/engineering/patterns/some-pattern.md",
+      "description": "What it is and when it bites" }
+  ]
+}
+```
+
+Every `.md` path in such a file becomes an edge from the hub to the document, so a document listed in its domain's index is indexed for retrieval without also needing a prose link. Entry paths may be canonical-repo-relative (`knowledge/...`), repo-root-relative, or relative to the index file. A `path` naming a directory resolves to that directory's `README.md`. Hubs nest: each `index.json` is linked from the nearest `index.json` above it.
+
+`index.json` files are hand-maintained source, not build output -- no builder writes them.
+
 
 ## Backlink indexing
 
@@ -89,7 +115,8 @@ The retrieval system builds a graph of document relationships based on links. Th
 
 The retrieval tools at `core/knowledge/retrieval/` provide:
 
-- **index-builder.mjs** -- Rebuilds all indexes (domain registry, backlinks, adjacency graph)
+- **index-builder.mjs** -- Rebuilds the domain registry (`operator/knowledge/domains.json`)
+- **backlink-indexer.mjs** / **graph-builder.mjs** -- Rebuild the per-device retrieval artefacts (`.backlinks.json`, `.graph.json`). These two are untracked and device-local: each host builds its own over the tree it can actually see, and `pa knowledge` rebuilds them on demand if they are missing. Do not commit them.
 - **search.mjs** -- Full-text search across all knowledge
 - **graph.mjs** -- Graph queries (neighbours, paths, clusters)
 

package/dist/engineering-pa-core/docs/tools/distill.md

@@ -46,13 +46,36 @@ any file changes distill produced.
 2. Count markdown observations under `agents/*/staging/` (depth ≤ 2,
    excluding `_archived/`). If zero, append a `noop-empty-staging`
    audit record and exit 0.
-3. Invoke `claude` with the librarian definition as an appended system
-   prompt and the distillation instructions as the positional prompt.
+3. Invoke `claude` with an explicit `--model` (see Model selection below),
+   the librarian definition as an appended system prompt, and the
+   distillation instructions as the positional prompt.
    Output is written to `<repoRoot>/.cache/distill/logs/<ts>.log`.
 4. Append a one-line JSON audit record to
    `<repoRoot>/.cache/distill/logs/runs.jsonl` (schema below).
 5. Exit 0 (ok) or 3 (claude transport failure).
 
+### Model selection
+
+The sweep passes `--model claude-opus-4-7` explicitly (operator ruling
+2026-07-29). Before the pin, no `--model` was passed and the Librarian
+inherited whatever the host CLI defaulted to -- so the model running the
+sweep was an accident of host configuration, and a host-side default bump
+silently changed sweep behaviour across the estate. The pin makes the
+choice deliberate. The reasoning behind 4.7 specifically: it follows
+briefs better than 4.8/5 in estate experience, and brief-following
+matters more for a scripted sweep than raw capability.
+
+Override per host or per run with the `DISTILL_MODEL` environment
+variable:
+
+```
+DISTILL_MODEL=claude-opus-4-8 pnpm exec distill run
+```
+
+An empty or whitespace-only `DISTILL_MODEL` is treated as unset. The
+dry-run plan reports the effective model and whether it came from the
+pinned default or the override.
+
 ### Librarian definition resolution
 
 The system prompt appended to the sweep session is resolved in this

package/dist/engineering-pa-core/src/distill/prompt.mjs

@@ -14,6 +14,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Absolute paths to the bundled retrieval tools. From this module
 // (`packages/core/src/distill/prompt.mjs`) the retrieval tools live at
 // `../knowledge/retrieval/`.
+//
+// Only the index builder is named in the prompt. The backlink indexer and the
+// graph builder are still exported here -- they are part of this module's
+// public surface and callers outside the sweep use them -- but a distillation
+// sweep must NOT run them; see step 4 for why.
 export const RETRIEVAL_INDEX_BUILDER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'index-builder.mjs');
 export const RETRIEVAL_BACKLINK_INDEXER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'backlink-indexer.mjs');
 export const RETRIEVAL_GRAPH_BUILDER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'graph-builder.mjs');
@@ -22,11 +27,19 @@ export const RETRIEVAL_GRAPH_BUILDER = resolve(__dirname, '..', 'knowledge', 're
  * Build the distillation prompt text. Absolute paths are interpolated for the
  * retrieval-tool invocations so Claude doesn't have to guess at install
  * locations.
+ *
+ * `workspaceRoot` is interpolated as the builder's `--root`, and it is
+ * load-bearing. Without `--root` the builder falls back to `$DAVE_ROOT`, then to
+ * a path resolved four levels up from its own script -- which for a
+ * package-installed platform lands inside the versioned `dist/` tree, so the
+ * sweep writes its index INTO THE PACKAGE instead of the workspace (the
+ * "versioned-dist-path trap"). `runDistill` passes the repo root it has already
+ * resolved from prereqs; the default is this process's cwd, which is correct for
+ * the cron/bin invocations that construct the prompt with no arguments.
  */
 export function buildDistillPrompt({
   indexBuilder = RETRIEVAL_INDEX_BUILDER,
-  backlinkIndexer = RETRIEVAL_BACKLINK_INDEXER,
-  graphBuilder = RETRIEVAL_GRAPH_BUILDER,
+  workspaceRoot = process.cwd(),
 } = {}) {
   return `You are operating as the Librarian. Run a full distillation sweep now.
 
@@ -41,10 +54,12 @@ export function buildDistillPrompt({
 
 3. **Synthesise the operator profile narrative.** After updating operator/profile/operator.json, regenerate operator/profile/profile.md as a human-readable markdown narrative derived from the JSON plus the body of accumulated observations. This is the file the workspace and PA read first; it must always exist and reflect current state. Replace it in full each run — it is a derived artefact, not an append log.
 
-4. **Rebuild indexes.** After all content changes, run these in order:
-   - node ${indexBuilder}
-   - node ${backlinkIndexer}
-   - node ${graphBuilder}
+4. **Rebuild the domain index.** After all content changes, run exactly this one command:
+   - node ${indexBuilder} --root ${workspaceRoot}
+
+   The \`--root\` argument is required: without it the builder resolves a default root inside the installed package and writes the index there instead of into the workspace.
+
+   Do NOT rebuild, and do NOT commit, \`operator/knowledge/.backlinks.json\` or \`operator/knowledge/.graph.json\`. Since w-2026-07-29-002 those two artefacts are per-device and untracked -- every host rebuilds its own from the tree it can actually see, via library-sync-cycle's graph-rebuild leg -- so a sweep that rebuilds them commits one host's partial view of the library over everybody else's.
 
 5. **Library hygiene check.** Per your role definition — verify JSON camelCase, cross-reference integrity, index completeness, and lastUpdated freshness. Fix violations in place.
 
@@ -54,17 +69,38 @@ export function buildDistillPrompt({
 }
 
 /**
- * Back-compat constant: the prompt assembled with default (bundled) paths.
- * Existing consumers that import DISTILL_PROMPT keep working; new callers
- * should use buildDistillPrompt() with explicit overrides where needed.
+ * Back-compat constant: the prompt assembled with default (bundled) paths and
+ * this process's cwd as the workspace root. Existing consumers that import
+ * DISTILL_PROMPT keep working; new callers should use buildDistillPrompt() with
+ * an explicit `workspaceRoot`, as `runDistill` does -- the resolved repo root is
+ * more trustworthy than cwd at module-load time.
  */
 export const DISTILL_PROMPT = buildDistillPrompt();
 
-export function claudeArgs({ sessionName, librarianDef, prompt = DISTILL_PROMPT }) {
+// The model the distillation sweep runs on, pinned explicitly (Baz ruling
+// 2026-07-29). Before this pin, claudeArgs passed no `--model`, so the
+// Librarian inherited whatever the host CLI happened to default to -- the
+// model choice was an accident of host config, and a host-side default bump
+// silently changed sweep behaviour. The pin makes the choice deliberate:
+// claude-opus-4-7 follows briefs better than 4.8/5 in estate experience,
+// which matters more for a scripted sweep than raw capability.
+//
+// Override per host or per run via the DISTILL_MODEL environment variable
+// (documented in docs/tools/distill.md).
+export const DEFAULT_DISTILL_MODEL = 'claude-opus-4-7';
+
+export function resolveDistillModel(env = process.env) {
+  const override = env.DISTILL_MODEL;
+  if (typeof override === 'string' && override.trim() !== '') return override.trim();
+  return DEFAULT_DISTILL_MODEL;
+}
+
+export function claudeArgs({ sessionName, librarianDef, prompt = DISTILL_PROMPT, model = resolveDistillModel() }) {
   // Positional prompt last. No shell interpolation — this array is
   // handed directly to child_process.spawn.
   return [
     '--print',
+    '--model', model,
     '--permission-mode', 'bypassPermissions',
     '--no-session-persistence',
     '--name', sessionName,

package/dist/engineering-pa-core/src/distill/run.mjs

@@ -37,7 +37,7 @@ import { basename, join } from 'node:path';
 
 import { resolvePrereqs } from './prereqs.mjs';
 import { countStagedObservations } from './staging.mjs';
-import { DISTILL_PROMPT, claudeArgs } from './prompt.mjs';
+import { buildDistillPrompt, claudeArgs, resolveDistillModel } from './prompt.mjs';
 
 function log(line, { stderr = process.stderr } = {}) {
   stderr.write(`[distill] ${line}\n`);
@@ -116,6 +116,12 @@ export async function runDistill({
   }
   log(`found ${stagingCount} staged observation(s)`, { stderr });
 
+  // Assemble the sweep prompt against THIS host's resolved repo root. The
+  // index-builder invocation in step 4 carries it as `--root`; the module-level
+  // DISTILL_PROMPT default (cwd) is a fallback for callers that have not
+  // resolved a root, and a cron sweep always has.
+  const prompt = buildDistillPrompt({ workspaceRoot: repoRoot });
+
   // Step 3 — assemble & invoke.
   //
   // Two timestamp shapes for two jobs:
@@ -165,8 +171,9 @@ export async function runDistill({
     log(`  appended system:      ${librarianDef} (${librarianBase.length} bytes)`, { stderr });
     log(`  operator supplement:  ${supplementPlanLine}`, { stderr });
     log(`  composed total:       ${librarianIdentity.length} bytes`, { stderr });
-    log(`  prompt:               <inline> (${DISTILL_PROMPT.length} bytes)`, { stderr });
-    log('  command:              claude --print --permission-mode bypassPermissions \\', { stderr });
+    log(`  prompt:               <inline> (${prompt.length} bytes, --root ${repoRoot})`, { stderr });
+    log(`  model:                ${resolveDistillModel()}${process.env.DISTILL_MODEL ? ' (DISTILL_MODEL override)' : ' (pinned default)'}`, { stderr });
+    log(`  command:              claude --print --model ${resolveDistillModel()} --permission-mode bypassPermissions \\`, { stderr });
     log(`                          --no-session-persistence --name ${sessionName} \\`, { stderr });
     log('                          --append-system-prompt <librarian definition> \\', { stderr });
     log('                          <distill prompt as positional arg>', { stderr });
@@ -177,7 +184,7 @@ export async function runDistill({
   log(`starting distillation sweep — log: ${runLogPath}`, { stderr });
   const start = Date.now();
 
-  const claudeArgv = claudeArgs({ sessionName, librarianDef: librarianIdentity });
+  const claudeArgv = claudeArgs({ sessionName, librarianDef: librarianIdentity, prompt });
   const claudeResult = await runner.spawn('claude', claudeArgv, { cwd: repoRoot });
 
   // Persist claude stdout/stderr to the per-run log file.