@aiwg/cli 2026.10.4 → 2026.10.6

package/dist/src/sessions/workspace-discovery.js

@@ -5,10 +5,11 @@ import { inspectMuseNativeWorkspace } from './adapters/muse.js';
 import { readOmpSessionHeader } from './adapters/omp.js';
 import { grokbotConversationIdFromLocator } from './adapters/grokbot-locator.js';
 import { resolveOmpPaths } from '../providers/omp-paths.mjs';
-import { SESSION_PROVIDER_IDS, SessionCoveragePreflightSchema, SessionContractError, sha256, } from './contracts.js';
+import { readAiwgConfig } from '../config/aiwg-config.js';
+import { SessionCoveragePreflightSchema, SessionContractError, sha256, } from './contracts.js';
 import { redactSourceLocator } from './discovery.js';
 import { createSessionAdapterRegistry } from './adapter-registry.js';
-import { coveragePreflight, expectedSessionProviders } from './coverage-preflight.js';
+import { coveragePreflight, providerScopeWarnings, resolveSessionProviderScope } from './coverage-preflight.js';
 import { fingerprintSourceFile, streamJsonLines } from './readers.js';
 import { matchSessionWorkspace } from './workspace-matching.js';
 import { matchImportExclusion, nativeSessionIdFromLocator, resolveImportExclusions } from './import-exclusions.js';
@@ -20,9 +21,26 @@ const MANUAL_EXPORT_PROVIDERS = new Set([
 export async function discoverWorkspaceHistories(options) {
     const registry = options.registry ?? createSessionAdapterRegistry();
     const exclusions = resolveImportExclusions(undefined, options.exclude);
-    const expectedProviders = expectedSessionProviders(options.expectedProviders ?? SESSION_PROVIDER_IDS);
     const supportedProviders = new Set(registry.list().map((adapter) => adapter.provider));
     const workspacePath = await canonicalPath(options.workspace);
+    const config = await readAiwgConfig(workspacePath);
+    const configuredProviders = config?.providers ?? [];
+    const explicitlyRootedProviders = [
+        ...(options.codexRoot || options.codexRoots?.length || config?.sessions?.codex_roots?.length ? ['codex'] : []),
+        ...(options.ompRoot ? ['omp'] : []),
+        ...(options.museRoot ? ['muse'] : []),
+        ...(options.dshRoot ? ['deepseek-harness'] : []),
+        ...(options.grokbotRoot ? ['grokbot'] : []),
+    ];
+    const savedRoots = options.authorizedRoots ?? options.refreshFrom?.authorizedRoots;
+    const authorizedProviders = options.refreshFrom
+        ? Object.keys(savedRoots ?? {}).filter(provider => savedRoots?.[provider]?.length)
+        : configuredProviders.length ? explicitlyRootedProviders : undefined;
+    const providerScope = resolveSessionProviderScope(configuredProviders, options.expectedProviders, authorizedProviders);
+    if (options.refreshFrom) {
+        providerScope.scopeWarnings = providerScopeWarnings(configuredProviders, options.refreshFrom.preflight?.expectedProviders ?? []);
+    }
+    const { expectedProviders } = providerScope;
     const workspaceId = workspacePath;
     const workspacePaths = [...new Set([workspacePath, resolve(options.workspace),
             ...(options.workspaceAliases ?? []).map((alias) => resolve(alias))])];
@@ -52,12 +70,19 @@ export async function discoverWorkspaceHistories(options) {
                 ? [resolve(options.grokbotRoot)] : [] },
         {
             provider: 'claude',
-            roots: providerHomes.flatMap((providerHome) => workspacePaths.map((workspace) => join(providerHome, '.claude', 'projects', claudeProjectKey(workspace)))),
+            // Same scope rule as codex: configured providers keep their root grant
+            // even when a narrow discovery does not scan them (#3402).
+            roots: savedRoots || (!expectedProviders.includes('claude') && !providerScope.configuredProviders?.includes('claude'))
+                ? [] : await claudeDiscoveryRoots(providerHomes, workspacePaths, workspacePath, registry, exclusions),
         },
         {
             provider: 'codex',
-            roots: options.authorizedRoots || !expectedProviders.includes('codex')
-                ? [] : await codexDiscoveryRoots(options),
+            roots: savedRoots || (!expectedProviders.includes('codex') && !providerScope.configuredProviders?.includes('codex')
+                && !explicitlyRootedProviders.includes('codex'))
+                ? [] : await codexDiscoveryRoots({ ...options, codexRoots: [
+                    ...(config?.sessions?.codex_roots ?? []).map(root => resolve(workspacePath, root)),
+                    ...(options.codexRoots ?? []),
+                ] }),
         },
         {
             provider: 'cursor',
@@ -85,11 +110,22 @@ export async function discoverWorkspaceHistories(options) {
                 : providerHomes.map((providerHome) => join(providerHome, '.pi', 'agent', 'sessions'))).flatMap((sessionsRoot) => workspacePaths.map((workspace) => join(sessionsRoot, `--${workspaceKey(workspace, false)}--`))),
         },
     ];
-    const authorizedRoots = { ...options.authorizedRoots };
+    const authorizedRoots = { ...savedRoots };
     const reports = new Map();
     const candidates = [];
     const seen = new Set();
     for (const entry of discoverable) {
+        // A hand-run narrow scope must not discard explicit root grants, including
+        // configured providers under an authorized home. Do not scan their histories.
+        if (!savedRoots && !expectedProviders.includes(entry.provider)
+            && (explicitlyRootedProviders.includes(entry.provider)
+                || (providerScope.configuredProviders?.includes(entry.provider) && options.providerHome))) {
+            const roots = [];
+            for (const root of entry.roots)
+                if (await pathExists(root))
+                    roots.push(await canonicalPath(root));
+            authorizedRoots[entry.provider] = [...new Set(roots)];
+        }
         if (!expectedProviders.includes(entry.provider) || !supportedProviders.has(entry.provider))
             continue;
         const adapter = registry.get(entry.provider);
@@ -97,10 +133,10 @@ export async function discoverWorkspaceHistories(options) {
             continue;
         const availableRoots = [];
         const rootCounts = new Map();
-        for (const root of options.authorizedRoots ? options.authorizedRoots[entry.provider] ?? [] : entry.roots) {
+        for (const root of savedRoots ? savedRoots[entry.provider] ?? [] : entry.roots) {
             if (await pathExists(root)) {
                 const canonical = await canonicalPath(root);
-                if (options.authorizedRoots && canonical !== root) {
+                if (savedRoots && canonical !== root) {
                     throw new SessionContractError('INVALID_ARGUMENT', 'previously authorized provider root changed; rediscover with explicit authorization');
                 }
                 if (!availableRoots.includes(canonical)) {
@@ -198,9 +234,12 @@ export async function discoverWorkspaceHistories(options) {
             const authorizedRoot = scope.allowedRoots.find((root) => locator === root || locator.startsWith(`${root}/`));
             if (!authorizedRoot)
                 continue;
-            if (entry.provider === 'claude'
-                && !await claudeSourceMatchesWorkspace(locator, workspacePath))
-                continue;
+            if (entry.provider === 'claude') {
+                const exactProject = workspacePaths.some(path => basename(authorizedRoot) === claudeProjectKey(path));
+                workspaceMatch = await claudeSourceWorkspaceMatch(locator, workspacePath, exactProject);
+                if (!workspaceMatch)
+                    continue;
+            }
             const fingerprint = await fingerprintSourceFile({
                 selectedPath: locator,
                 allowedRoots: [authorizedRoot],
@@ -274,7 +313,7 @@ export async function discoverWorkspaceHistories(options) {
     const sources = candidates.sort(compareSources);
     const providers = [...reports.values()].sort((a, b) => a.provider.localeCompare(b.provider));
     const preflight = coveragePreflight({
-        expectedProviders, expectedProviderBasis: options.expectedProviders ? 'explicit' : 'declared-default',
+        ...providerScope,
         registry, runtime: options.runtime, reports: providers,
     });
     const identity = {
@@ -427,13 +466,12 @@ async function rediscoverManifestIdentity(manifest) {
 }
 async function codexDiscoveryRoots(options) {
     const explicit = [...(options.codexRoots ?? []), ...(options.codexRoot ? [options.codexRoot] : [])];
-    if (explicit.length > 0)
-        return [...new Set(explicit.map((root) => resolve(root)))];
+    const roots = [...new Set(explicit.map((root) => resolve(root)))];
     // Shared stores require the same explicit provider-home authorization as the default root.
     if (!options.providerHome)
-        return [];
+        return roots;
     const codexHome = join(resolve(options.providerHome), '.codex');
-    const roots = [join(codexHome, 'sessions')];
+    roots.push(join(codexHome, 'sessions'));
     if (process.env.CODEX_HOME)
         roots.push(resolve(process.env.CODEX_HOME, 'sessions'));
     try {
@@ -512,7 +550,40 @@ function asObject(value) {
 async function canonicalPath(path) {
     return realpath(resolve(path));
 }
-async function claudeSourceMatchesWorkspace(locator, workspacePath) {
+/** Claude keys are lossy: use transcript cwd, never decode hyphens into paths. */
+async function claudeDiscoveryRoots(homes, paths, workspace, registry, exclusions) {
+    const roots = homes.flatMap(home => paths.map(path => join(home, '.claude', 'projects', claudeProjectKey(path))));
+    const adapter = registry.get('claude');
+    for (const home of homes) {
+        const projects = join(home, '.claude', 'projects');
+        let entries;
+        try {
+            entries = await readdir(projects, { withFileTypes: true });
+        }
+        catch (error) {
+            if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+                continue;
+            throw error;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            const root = join(projects, entry.name);
+            if (roots.includes(root))
+                continue;
+            for await (const descriptor of adapter.discover({ workspaceId: workspace, allowedRoots: [root] })) {
+                if (matchImportExclusion(descriptor, exclusions))
+                    continue;
+                if (await claudeSourceWorkspaceMatch(descriptor.locator, workspace, false)) {
+                    roots.push(root);
+                    break;
+                }
+            }
+        }
+    }
+    return [...new Set(roots)];
+}
+async function claudeSourceWorkspaceMatch(locator, workspacePath, exactProject) {
     let count = 0;
     for await (const { line } of streamJsonLines(locator, { end: 1024 * 1024 - 1 })) {
         if (++count > 50)
@@ -527,15 +598,10 @@ async function claudeSourceMatchesWorkspace(locator, workspacePath) {
         const cwd = asObject(value).cwd;
         if (typeof cwd !== 'string' || cwd.length === 0)
             continue;
-        try {
-            return await canonicalPath(cwd) === workspacePath;
-        }
-        catch {
-            return resolve(cwd) === workspacePath;
-        }
+        return matchSessionWorkspace(cwd, workspacePath);
     }
-    // Older transcripts without cwd still use the selected project folder.
-    return true;
+    // Only exact project keys can establish ownership without cwd.
+    return exactProject ? 'exact' : null;
 }
 export function claudeProjectKey(path) {
     // Claude Code 2.1.302 replaces each character, then caps keys at 200

package/dist/src/smiths/context-pipeline/aiwg-md.js

@@ -18,6 +18,7 @@ import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { projectControlPath } from '../../config/project-artifacts.js';
 import { buildClaudeHookBlock, CLAUDE_HOOK_START, CLAUDE_HOOK_END } from './claude-hook.js';
+import { dedupeProviderBootstrap } from './workspace-context.js';
 import { dominantLineEnding, withLineEnding } from './line-endings.js';
 import { buildParallelismSection, replaceOrAppendParallelismBlock } from './parallelism-section.js';
 import { buildContextFinalizationBlock, replaceOrAppendFinalizationBlock } from './finalization.js';
@@ -60,6 +61,7 @@ export async function buildAiwgMdContent(projectPath, stagedClaudeMdContent) {
         // Regenerate may mirror CLAUDE.md before its hook updater runs. Normalize
         // that managed block here too so legacy duplicate policy never reaches
         // AIWG.md, even on the first refresh. Operator content stays untouched.
+        claudeMdContent = dedupeProviderBootstrap(claudeMdContent);
         const start = claudeMdContent.indexOf(CLAUDE_HOOK_START);
         const end = claudeMdContent.indexOf(CLAUDE_HOOK_END, start);
         if (start >= 0 && end >= start) {
@@ -72,7 +74,22 @@ export async function buildAiwgMdContent(projectPath, stagedClaudeMdContent) {
         // context, so the directive becomes a self-reference when copied through.
         // Match the directive when it appears on its own line (possibly indented).
         const SELF_INCLUDE_PATTERN = /^\s*@AIWG\.md\s*$/;
-        const filtered = lines.filter((line) => !SELF_INCLUDE_PATTERN.test(line));
+        // #3451: CLAUDE.md already `@`-imports WORKSPACE.md; a second `@` path to
+        // the same file would load it twice, so AIWG.md refers to it in plain text.
+        const CONFIG_IMPORT_PATTERN = /^\s*@\S*aiwg\.config\s*$/;
+        const WORKSPACE_IMPORT_PATTERN = /^\s*@(?:\.\.\/)?WORKSPACE\.md\s*$/;
+        const filtered = lines
+            .filter((line) => !SELF_INCLUDE_PATTERN.test(line))
+            .map((line) => {
+            if (WORKSPACE_IMPORT_PATTERN.test(line)) {
+                return 'WORKSPACE.md is the canonical project context (loaded by CLAUDE.md; read it first if your harness did not).';
+            }
+            // Legacy CLAUDE.md files may still `@`-import the raw JSON config.
+            if (CONFIG_IMPORT_PATTERN.test(line)) {
+                return 'Project configuration: `.aiwg/aiwg.config` (not auto-loaded; run `aiwg config show --project` to view it).';
+            }
+            return line;
+        });
         const firstLine = filtered[0] ?? '';
         const rest = filtered.slice(1);
         // If the file already carries the signature elsewhere, don't double-insert.

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -21,7 +21,7 @@
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, } from './workspace-context.js';
+import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, dedupeProviderBootstrap, } from './workspace-context.js';
 import { dominantLineEnding, withLineEnding } from './line-endings.js';
 import { assertSafeContextFile } from './context-file-safety.js';
 export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
@@ -31,7 +31,9 @@ export function buildClaudeHookBlock(_policy = {}) {
         CLAUDE_HOOK_START,
         '',
         buildProviderBootstrapBlock('claude'),
-        '@.aiwg/aiwg.config',
+        // Plain-text pointer, deliberately not an `@` import: the raw JSON config
+        // is several KB and would be pulled into every system prompt (#3451).
+        'Project configuration: `.aiwg/aiwg.config` (not auto-loaded; run `aiwg config show --project` to view it).',
         '',
         'Artifact destination authority: `aiwg show rule artifact-output-policy` (kernel).',
         '',
@@ -45,6 +47,30 @@ export function buildClaudeHookBlock(_policy = {}) {
         CLAUDE_HOOK_END,
     ].join('\n');
 }
+/** Keep the first managed hook block and drop any later complete copies. */
+function collapseExtraHookBlocks(content) {
+    const first = content.indexOf(CLAUDE_HOOK_START);
+    if (first === -1)
+        return content;
+    const firstEnd = content.indexOf(CLAUDE_HOOK_END, first);
+    if (firstEnd === -1)
+        return content;
+    const blockEnd = firstEnd + CLAUDE_HOOK_END.length;
+    let tail = content.slice(blockEnd);
+    const before = tail;
+    for (;;) {
+        const s = tail.indexOf(CLAUDE_HOOK_START);
+        if (s === -1)
+            break;
+        const e = tail.indexOf(CLAUDE_HOOK_END, s);
+        if (e === -1)
+            break;
+        tail = tail.slice(0, s) + tail.slice(e + CLAUDE_HOOK_END.length);
+    }
+    if (tail === before)
+        return content;
+    return content.slice(0, blockEnd) + tail.replace(/(?:\r?\n){3,}/g, '\n\n');
+}
 /**
  * Ensure CLAUDE.md at projectPath contains the AIWG-managed marker block
  * pointing at AIWG.md. Returns a result describing what was done.
@@ -72,6 +98,11 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         }
         throw err;
     }
+    // Repair duplicates left by earlier generations before locating markers, so
+    // regeneration converges on exactly one bootstrap (#3451).
+    const original = existing;
+    existing = collapseExtraHookBlocks(dedupeProviderBootstrap(existing));
+    const repaired = existing !== original;
     const lineEnding = dominantLineEnding(existing);
     block = withLineEnding(block, lineEnding);
     const startIdx = existing.indexOf(CLAUDE_HOOK_START);
@@ -90,7 +121,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
             const updated = existing.substring(0, bootstrapStartIdx)
                 + block
                 + existing.substring(bootstrapEndIdx);
-            await fs.writeFile(claudeMdPath, updated, 'utf8');
+            await fs.writeFile(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
             result.action = 'updated';
             return result;
         }
@@ -101,7 +132,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         // Ensure the file ends with a single newline before appending.
         const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
         const updated = `${trimmed}${lineEnding}${block}${lineEnding}`;
-        await fs.writeFile(claudeMdPath, updated, 'utf8');
+        await fs.writeFile(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
         result.action = 'inserted';
         return result;
     }
@@ -119,7 +150,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         }
         const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
         const updated = `${trimmed}${lineEnding}${block}${lineEnding}`;
-        await fs.writeFile(claudeMdPath, updated, 'utf8');
+        await fs.writeFile(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
         result.action = 'inserted';
         return result;
     }
@@ -127,6 +158,11 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     const blockEndOffset = endIdx + CLAUDE_HOOK_END.length;
     const currentBlock = existing.substring(startIdx, blockEndOffset);
     if (currentBlock === block) {
+        if (repaired) {
+            await fs.writeFile(claudeMdPath, existing, 'utf8');
+            result.action = 'updated';
+            return result;
+        }
         result.action = 'unchanged';
         return result;
     }
@@ -142,7 +178,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         result.warnings.push(`CLAUDE.md AIWG hook block has been modified inside the markers; updating to canonical content. Operator content outside the block is preserved.`);
     }
     const updated = existing.substring(0, startIdx) + block + existing.substring(blockEndOffset);
-    await fs.writeFile(claudeMdPath, updated, 'utf8');
+    await fs.writeFile(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
     result.action = 'updated';
     return result;
 }

package/dist/src/smiths/context-pipeline/parallelism-section.js

@@ -13,12 +13,18 @@
  *
  * @implements #1362
  */
-import { dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findPackageRoot } from '../../cli/find-package-root.js';
 import { readAiwgConfigCandidate, validateWorkerConfigCandidate, resolveParallelism, PROVIDER_PARALLELISM_DEFAULTS } from '../../config/aiwg-config.js';
+import { ConfigLoader } from '../../models/config-loader.js';
+import { validateWorkerCatalogDiscovery } from '../../models/provider-policy.js';
 export const PARALLELISM_BLOCK_START = '<!-- AIWG-PARALLELISM-CAP:START -->';
 export const PARALLELISM_BLOCK_END = '<!-- AIWG-PARALLELISM-CAP:END -->';
+/** Plain-path pointer (not an `@` import) to the long health/supervision explanation. */
+export const WORKER_HEALTH_DOC_POINTER = '`docs/getting-started/worker-dispatch.md` ("Worker health windows and supervision")';
 /**
  * One-line note rendered when the bundled model defaults cannot be loaded.
  * The orchestration health block is omitted; the rest of the section renders
@@ -109,6 +115,58 @@ function groupSummaries(entries, parallelism) {
         return parts.join('; ') + ')';
     });
 }
+/** Same cache used by model discovery; absence/corruption cannot invent evidence. */
+async function readCachedCatalog() {
+    try {
+        return JSON.parse(await readFile(join(homedir(), '.cache/aiwg/model-catalog.v1.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function observationSummaries(entries, deps) {
+    const candidate = await (deps.readCatalog ?? readCachedCatalog)();
+    const catalog = candidate?.version && candidate.providers && !validateWorkerCatalogDiscovery(candidate.discovery).length
+        ? candidate : null;
+    const readAt = (deps.now ?? (() => new Date()))();
+    const stamp = (value) => {
+        const time = value === undefined ? NaN : Date.parse(value);
+        if (!Number.isFinite(time))
+            return 'unknown';
+        const age = readAt.getTime() - time;
+        return `${new Date(time).toISOString()} (${age < 0 ? 'future timestamp; age unavailable' : `${Math.floor(age / 1000)}s old`})`;
+    };
+    const range = (values) => {
+        if (!values.length)
+            return 'unknown';
+        values.sort((a, b) => Date.parse(a) - Date.parse(b));
+        const oldest = stamp(values[0]);
+        return Date.parse(values[0]) === Date.parse(values[values.length - 1]) ? oldest : `${oldest} to ${stamp(values[values.length - 1])}`;
+    };
+    return [
+        `Cached model observations read at ${readAt.toISOString()}; catalog fetchedAt: ${stamp(catalog?.discovery?.fetchedAt)}. Ages are measured at this read and grow afterward. This cache may differ from the resolver's current installation observations; no eligibility read is performed by context generation. Missing or ambiguous observations have unknown age.`,
+        '',
+        ...entries.map(([id, group]) => {
+            const observations = group.members.flatMap(member => {
+                // Mirror the resolver's exact, unambiguous id/API-id lookup per installation.
+                const rows = catalog?.discovery?.instances?.[member.cli]?.models
+                    .filter(row => row.id === member.model || row.apiModelId === member.model) ?? [];
+                return rows.length === 1 && rows[0].worker ? [rows[0].worker] : [];
+            });
+            return `- ${oneLine(id, 64)} cached observations: ${observations.length}/${group.members.length} members; observedAt: ${range(observations.map(row => row.observedAt))}; verifiedAt: ${range(observations.map(row => row.verifiedAt))}.`;
+        }),
+        '',
+    ];
+}
+function capacitySummary(parallelism) {
+    const caps = parallelism.admission;
+    const summaries = ['groupCaps', 'memberCaps', 'cliCaps', 'modelCaps', 'quotaCaps'].map(field => {
+        const entries = Object.entries(caps?.[field] ?? {});
+        const shown = entries.slice(0, MAX_SHOWN_GROUPS).map(([key, value]) => `${oneLine(key, 96)}=${value}`).join(', ');
+        return `${field}: ${shown || 'none configured'}${entries.length > MAX_SHOWN_GROUPS ? ` (+${entries.length - MAX_SHOWN_GROUPS} more)` : ''}`;
+    });
+    return `Configured concurrency ceilings (\`parallelism.admission\`): ${summaries.join('; ')}. Local/self-hosted models obey these same ceilings: CLI caps use installation IDs, model caps use canonical inference-provider/API-model keys, and quota caps use the installation's quotaScope. Unset caps add no extra ceiling; a current/request capacity ceiling of zero blocks selection. The resolver returns the minimum applicable ceiling as \`effectiveMaxParallel\`; Tier 0 conductors must self-count active workers, including workers sharing a local server.`;
+}
 /**
  * One configured health window with its origin. The origin mirrors
  * `resolveWorkerEffectiveHealth()` (`src/serve/worker-invocation.ts`): a
@@ -268,15 +326,24 @@ export async function buildParallelismSection(projectPath, deps = {}) {
         lines.push('');
         lines.push('A group above shown as configured, with excluded members or an uncovered required role listed, is a static config read — not a live eligibility verdict. Eligibility is resolved per (group, member, effort) tuple against the current catalog and request; see `aiwg models resolve` below to check a specific role/task/group.');
         lines.push('');
-        lines.push('Tier 0 direct handoff is the default: use your own shell or a qualified MCP worker tool. No Mission/MC session, scheduler, daemon, or activation marker is needed. Self-count active native + CLI + MCP workers, take the minimum of the project, group, CLI, model, and context caps, and launch each writing task once.');
+        lines.push(...await observationSummaries(entries.slice(0, MAX_SHOWN_GROUPS), deps));
+        const models = await new ConfigLoader(projectPath, { aiwgHome: resolveAiwgHome() }).load(cfg.parallelism);
+        const freshness = models.defaults.workerSelection.freshness;
+        lines.push(`Resolver freshness limits from merged model policy: observation warning after ${freshness.warnHours} hours; observation blocked after ${freshness.blockHours} hours; verification blocked after ${freshness.policyDays} days. Future-dated evidence is blocked. Re-resolve before launch; cached ages do not establish eligibility.`);
+        lines.push('');
+        lines.push('Cross-family review: when required, the reviewer must use a different observed model family from the writer. Different CLI names do not prove different families. The resolver requires unambiguous writer lineage in `reviewOf` with `requireDifferentFamily`; missing, conflicting, unknown, or same-family lineage blocks required review. The direct CLI does not accept review-lineage flags. Family diversity does not establish independent errors; same-vendor or cross-vendor agreement is not proof. Consequential claims require an executable check or human acceptance. Record observed evaluator model/vendor/family, criteria, disagreements and re-review links. Calibration guide: `$AIWG_ROOT/docs/decision/evaluator-calibration.md`.');
+        lines.push('');
+        lines.push(capacitySummary(cfg.parallelism));
+        lines.push('');
+        lines.push('Tier 0 direct handoff is the default: use your own shell or a qualified MCP worker tool. Run the rendered command from your own shell outside your own harness sandbox (Claude Code `sandbox.excludedCommands` or an unsandboxed Bash call). The worker CLI native sandbox, per-task worktree and resource scope provide isolation; never nest sandboxes: a CLI sandbox inside a conductor sandbox fails; do not route Tier 0 workers through `aiwg ralph-external --launch-worker`, whose systemd-unit isolation and namespace probe apply only to that launcher and managed launches. No Mission/MC session, scheduler, daemon, or activation marker is needed. Self-count active native + CLI + MCP workers, take the minimum of the project, group, CLI, model, and context caps, and launch each writing task once.');
         lines.push('');
         lines.push('Before resolving, qualify the installed CLIs and configured model roles with `aiwg doctor --probe-workers --qualify` (`--yes` for headless confirmation).');
         lines.push('Agents pass `--authorize-premium` to `aiwg models resolve` only after the human explicitly confirmed the premium escalation (escalation-discipline rule); authorization applies to that resolution only.');
         lines.push('Resolve each bounded brief with `aiwg models resolve --role <role> --task <class> --group <group> --brief <file> --workdir <tree> --final-output <file> --transport shell --format shell`. Copy the exact rendered command or the MCP server/tool/arguments byte-for-byte; never assemble vendor flags from memory. Re-resolve after any brief, profile, model, or workspace change. `--format shell` prints only the launch command: to see the resolved health windows for an attempt, use `--format json` (the default) and read `invocation.health` with its per-field `origins`.');
         lines.push('');
-        lines.push(`Configured health windows (each followed by its origin — \`default\` or \`project config\`): check every ${check.value}s (${check.origin}); confirm startup within ${startup.value}s (${startup.origin}); quiet limit ${quiet.value}s (${quiet.origin}); stall limit ${stall.value}s (${stall.origin}); hard stop ${hard.value}s (${hard.origin}). Per-attempt windows scale quiet and stall by the single largest applicable role/effort/model factor, never their product (for example, reasoning at \`xhigh\` effort resolves 180s/600s from the 90s/300s defaults; an effective 1.25 scale gives 112.5s/375s). Only the hard deadline and its diagnostic/termination grace periods are capped by the remaining wall-clock and transport ceilings; startup, quiet, and stall keep their configured or scaled values, and \`truncatedWindows\` instead records when one of them would exceed that capped deadline (\`resolveWorkerEffectiveHealth()\` in \`src/serve/worker-invocation.ts\`). Resolved values win over these configured values.`);
-        lines.push('');
-        lines.push('Supervise by observer state, never by suspicion. `quiet` (no observed activity for the quiet window, reported with confidence `suspected`) is not a stop: read the status (`aiwg ralph-external --status --workers --runs-root <dir> --json` is read-only and never kills or retries), check owned-worktree progress, and keep waiting — the observer’s `shouldStop()` stays false. `stalled` (no progress for the stall window) opens diagnosis through the diagnostic grace period; only `hung` (still no progress after grace, with the process live and connected) authorizes a no-progress stop — and only a worker this conductor owns. The launcher also stops independently of progress state on `failed-to-start`, the hard wall-clock deadline (`HARD_DEADLINE`), the step-count limit (`STEP_LIMIT`), and a fatal observer-record failure (`tools/ralph-external/session-launcher.mjs`). Confirm the stop (a sent signal, lease expiry, or final-file presence is not proof — only a confirmed exit is), preserve partial work for independent verification, then re-resolve within remaining attempts and budgets. Observer loss (`OBSERVER_GAP`, `DISCONNECTED`, degraded or unobserved coverage, opaque MCP output) is unknown, never worker failure: keep polling owned run files and processes from the shell at the same cadence. Heartbeats and log bytes are not progress. On correlated failure across workers sharing one account, quota, or host, pause further launches there and report cause and scope.');
+        // #3451: the long window-scaling and supervision explanation lives in the
+        // worker-dispatch doc (and the subagent-scoping rule); keep a summary here.
+        lines.push(`Worker health windows (origin in parentheses): check every ${check.value}s (${check.origin}); startup ${startup.value}s (${startup.origin}); quiet ${quiet.value}s (${quiet.origin}); stall ${stall.value}s (${stall.origin}); hard stop ${hard.value}s (${hard.origin}). Resolved values win. Supervise by observer state: only \`hung\` authorizes a no-progress stop, and only of a worker you own; read status with \`aiwg ralph-external --status --workers --runs-root <dir> --json\` (read-only). Details: ${WORKER_HEALTH_DOC_POINTER} and \`aiwg show rule subagent-scoping\`.`);
         lines.push('');
     }
     lines.push(PARALLELISM_BLOCK_END);