@aiwg/cli 2026.10.3 → 2026.10.4

package/dist/src/decision/offload.js

@@ -0,0 +1,550 @@
+/**
+ * Decision-offload checkpoint execution and offline adoption reporting.
+ *
+ * Opportunity records describe only checkpoints that called this contract.
+ * Generic activity-log prose is deliberately not interpreted as a precise
+ * opportunity denominator. Completed-call records remain in ledger.ts; the
+ * shared correlation id joins the two append-only journals.
+ */
+import { randomUUID } from 'node:crypto';
+import { constants as fsConstants, createReadStream } from 'node:fs';
+import { lstat, mkdir, open } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import path from 'node:path';
+import { projectAiwgPath, projectAiwgWritePath } from '../config/project-artifacts.js';
+import { resolveDecisionEnablement } from '../config/decision-config.js';
+import { readAiwgConfig } from '../config/aiwg-config.js';
+import { resolveActiveProvider } from '../cli/provider-resolution.js';
+import { askDecision, DecisionAskUsageError } from './ask.js';
+import { inspectJevCredential } from './jev-credentials.js';
+import { inspectDecisionOffloadActivation } from './offload-activation.js';
+import { ATTRIBUTION_FIELD_PATTERN, decisionLedgerHistory, DECISION_LEDGER_RECORD_TIMEOUT_MS, recordDecisionAsk, resolveDecisionSession, } from './ledger.js';
+export const DECISION_OPPORTUNITY_SCHEMA = 'aiwg-decision-opportunity/v1';
+export const DECISION_OFFLOAD_SNAPSHOT_SCHEMA = 'aiwg-decision-offload-snapshot/v1';
+const OPPORTUNITY_FILE = 'opportunities.jsonl';
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+const MAX_OPPORTUNITY_RECORD_BYTES = 4000;
+export const DECISION_OPPORTUNITY_RECORD_TIMEOUT_MS = DECISION_LEDGER_RECORD_TIMEOUT_MS;
+const TIMED_OUT = Symbol('decision-offload-timeout');
+export const DECISION_OFFLOAD_CHECKPOINT_COVERAGE = [
+    'address-issues:worker-pick', 'address-issues:failure-triage', 'address-issues:review-verdict',
+    'address-issues:minor-triage', 'aiwg-mission:worker-pick', 'aiwg-mission:failure-triage',
+    'subagent-scoping:worker-pick', 'subagent-scoping:failure-triage',
+].map(caller => ({ caller, coverage: 'instruction-only' }));
+export const DECISION_OFFLOAD_EXECUTABLE_COVERAGE = [
+    { entrypoint: 'aiwg decision ask', transport: 'cli', coverage: 'shared-contract-generic' },
+    { entrypoint: 'decision-ask', transport: 'mcp', coverage: 'shared-contract-generic' },
+];
+function safeCaller(caller) {
+    if (!ATTRIBUTION_FIELD_PATTERN.test(caller))
+        throw new DecisionAskUsageError('invalid-caller', 'checkpoint caller must be a valid attribution tag');
+    return caller;
+}
+export function decisionOffloadCategory(caller) {
+    if (!caller)
+        return 'unattributed';
+    const prefix = caller.split(':', 1)[0].toLowerCase();
+    if (['diagnosis', 'diagnostic', 'control'].includes(prefix))
+        return 'diagnostic';
+    if (['setup', 'verify'].includes(prefix))
+        return 'setup';
+    if (['benchmark', 'bench', 'qualification', 'eval'].includes(prefix))
+        return 'benchmark';
+    return 'organic';
+}
+async function providerFor(options) {
+    const work = (async () => {
+        const resolve = options.resolveProvider ?? resolveActiveProvider;
+        const resolution = await resolve({ cwd: options.projectRoot, explicitProvider: options.explicitProvider, env: options.env ?? process.env });
+        return resolution.provider ?? 'unknown';
+    })().catch(() => 'unknown');
+    const outcome = await bounded(work, options.providerTimeoutMs ?? DECISION_OPPORTUNITY_RECORD_TIMEOUT_MS);
+    return outcome === TIMED_OUT ? 'unknown' : outcome;
+}
+async function bounded(work, timeoutMs) {
+    let timer;
+    const timeout = new Promise(resolve => {
+        timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+        // Keep this timer referenced: it is the only liveness guarantee when an
+        // injected resolver or filesystem promise never settles in a standalone
+        // CLI process. Unref would let Node exit before the ask can run.
+    });
+    try {
+        const outcome = await Promise.race([work, timeout]);
+        if (outcome === TIMED_OUT)
+            work.catch(() => undefined);
+        return outcome;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function boundedAppend(append, record, projectRoot, timeoutMs, warn) {
+    let work;
+    try {
+        work = Promise.resolve(append(record, projectRoot, warn));
+    }
+    catch (error) {
+        warn(`warning: failed to record decision opportunity: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+    const outcome = await bounded(work.catch(error => {
+        warn(`warning: failed to record decision opportunity: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }), timeoutMs);
+    if (outcome === TIMED_OUT) {
+        warn(`warning: decision opportunity recording exceeded ${timeoutMs}ms; completion unknown`);
+        return null;
+    }
+    return outcome;
+}
+function recordFor(options, fields, correlationId, provider) {
+    const session = resolveDecisionSession(options.explicitSessionId, options.env ?? process.env);
+    const caller = safeCaller(options.caller);
+    return {
+        schema: DECISION_OPPORTUNITY_SCHEMA,
+        correlationId,
+        timestamp: new Date(options.now?.() ?? Date.now()).toISOString(),
+        provider,
+        ...session,
+        transport: options.transport,
+        caller,
+        category: options.category ?? decisionOffloadCategory(caller),
+        ...fields,
+    };
+}
+const RECORD_TIMESTAMP_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})\.\d{3}Z$/;
+function isStrictTimestamp(value) {
+    if (typeof value !== 'string' || !RECORD_TIMESTAMP_PATTERN.test(value))
+        return false;
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) && parsed.toISOString() === value;
+}
+function validOpportunity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const v = value;
+    return v.schema === DECISION_OPPORTUNITY_SCHEMA
+        && typeof v.correlationId === 'string' && v.correlationId.length > 0
+        && isStrictTimestamp(v.timestamp)
+        && ['started', 'completed', 'skipped'].includes(String(v.phase))
+        && typeof v.provider === 'string'
+        && typeof v.sessionId === 'string' && typeof v.sessionSource === 'string'
+        && ['cli', 'mcp', 'internal'].includes(String(v.transport))
+        && typeof v.caller === 'string' && ATTRIBUTION_FIELD_PATTERN.test(v.caller)
+        && ['organic', 'diagnostic', 'setup', 'benchmark', 'unattributed'].includes(String(v.category))
+        && typeof v.eligible === 'boolean' && typeof v.attempted === 'boolean'
+        && ['answered', 'fallback', 'skipped', 'unknown'].includes(String(v.outcome))
+        && typeof v.reason === 'string'
+        && (typeof v.ledgerRecorded === 'boolean' || v.ledgerRecorded === null);
+}
+async function writeFully(handle, buffer) {
+    let offset = 0;
+    while (offset < buffer.length) {
+        const { bytesWritten } = await handle.write(buffer.subarray(offset));
+        if (!Number.isFinite(bytesWritten) || bytesWritten <= 0)
+            throw new Error('decision opportunity: write made no progress');
+        offset += bytesWritten;
+    }
+}
+export async function appendDecisionOpportunity(record, projectRoot, warn = message => process.stderr.write(`${message}\n`)) {
+    if (!validOpportunity(record))
+        return false;
+    const line = `${JSON.stringify(record)}\n`;
+    if (Buffer.byteLength(line, 'utf8') > MAX_OPPORTUNITY_RECORD_BYTES) {
+        warn(`warning: decision opportunity exceeds the ${MAX_OPPORTUNITY_RECORD_BYTES}-byte size cap and was not written`);
+        return false;
+    }
+    let handle;
+    try {
+        const directory = projectAiwgWritePath(projectRoot, 'decision');
+        const file = path.join(directory, OPPORTUNITY_FILE);
+        await mkdir(directory, { recursive: true, mode: DIR_MODE });
+        const dirStat = await lstat(directory);
+        if (!dirStat.isDirectory() || dirStat.isSymbolicLink() || (dirStat.mode & 0o077) !== 0)
+            throw new Error('unsafe opportunity directory');
+        try {
+            const fileStat = await lstat(file);
+            if (!fileStat.isFile() || fileStat.isSymbolicLink() || fileStat.nlink !== 1 || (fileStat.mode & 0o077) !== 0)
+                throw new Error('unsafe opportunity file');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        handle = await open(file, fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_WRONLY | (fsConstants.O_NOFOLLOW ?? 0), FILE_MODE);
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.nlink !== 1 || (opened.mode & 0o077) !== 0)
+            throw new Error('unsafe opened opportunity file');
+        await writeFully(handle, Buffer.from(line, 'utf8'));
+        return true;
+    }
+    catch (error) {
+        warn(`warning: failed to record decision opportunity: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+export async function runDecisionOffloadCheckpoint(input, options) {
+    const correlationId = (options.id ?? randomUUID)();
+    const provider = await providerFor(options);
+    const append = options.appendOpportunity ?? appendDecisionOpportunity;
+    let warned = false;
+    let pendingOpportunityWarning;
+    const warn = (message) => {
+        if (warned)
+            return;
+        warned = true;
+        (options.warn ?? (value => process.stderr.write(`${value}\n`)))(message);
+    };
+    const queueOpportunityWarning = (message) => { pendingOpportunityWarning ??= message; };
+    const flushOpportunityWarning = () => {
+        if (pendingOpportunityWarning)
+            warn(pendingOpportunityWarning);
+    };
+    const eligibility = options.eligibility ?? { eligible: true };
+    const appendBounded = (record, appendWarn) => boundedAppend(append, record, options.projectRoot, options.opportunityTimeoutMs ?? DECISION_OPPORTUNITY_RECORD_TIMEOUT_MS, appendWarn);
+    if (!eligibility.eligible) {
+        const opportunity = recordFor(options, { phase: 'skipped', eligible: false, attempted: false, outcome: 'skipped', reason: eligibility.reason ?? 'other-exclusion', ledgerRecorded: null }, correlationId, provider);
+        return { outcome: 'skipped', result: null, opportunity, opportunityRecorded: await appendBounded(opportunity, warn) };
+    }
+    // Persist the eligible, attempted checkpoint before invoking the backend.
+    // If the process dies in the call, the offline snapshot retains an unknown
+    // attempt rather than incorrectly reporting that no opportunity existed.
+    const started = recordFor(options, {
+        phase: 'started', eligible: true, attempted: true, outcome: 'unknown',
+        reason: 'attempt-started', ledgerRecorded: null,
+    }, correlationId, provider);
+    const attemptRecorded = await appendBounded(started, queueOpportunityWarning);
+    let result;
+    try {
+        const ask = options.ask ?? askDecision;
+        result = await ask(input, options.askRuntime ?? { cwd: options.projectRoot, env: options.env ?? process.env });
+    }
+    catch (error) {
+        const usage = error instanceof DecisionAskUsageError;
+        const opportunity = recordFor(options, {
+            phase: 'completed',
+            eligible: true, attempted: !usage, outcome: usage ? 'skipped' : 'unknown',
+            reason: usage ? 'usage-rejected' : 'execution-unknown', ledgerRecorded: false,
+        }, correlationId, provider);
+        const opportunityRecorded = await appendBounded(opportunity, queueOpportunityWarning);
+        flushOpportunityWarning();
+        if (usage)
+            throw error;
+        return { outcome: 'unknown', result: null, opportunity, attemptRecorded, opportunityRecorded, error };
+    }
+    let ledger = null;
+    try {
+        ledger = await (options.recordAsk ?? recordDecisionAsk)(input, result, {
+            ...options,
+            warn,
+            caller: options.ledgerCaller === undefined ? safeCaller(options.caller) : options.ledgerCaller,
+            id: () => correlationId,
+        });
+    }
+    catch (error) {
+        warn(`warning: failed to record decision ledger: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const opportunity = recordFor(options, {
+        phase: 'completed',
+        eligible: true, attempted: result.reason !== 'not-configured', outcome: result.status,
+        reason: result.reason, ledgerRecorded: ledger ? true : null,
+    }, correlationId, provider);
+    const opportunityRecorded = await appendBounded(opportunity, queueOpportunityWarning);
+    flushOpportunityWarning();
+    return { outcome: result.status, result, opportunity, attemptRecorded, opportunityRecorded };
+}
+/** Collapse append-only started/completed events to one current state per checkpoint. */
+function collapseOpportunities(records) {
+    const byId = new Map();
+    for (const record of records)
+        byId.set(record.correlationId, record);
+    return [...byId.values()];
+}
+async function readOpportunities(projectRoot) {
+    const file = projectAiwgPath(projectRoot, 'decision', OPPORTUNITY_FILE);
+    const records = [];
+    let invalid = 0;
+    try {
+        const input = createReadStream(file, { encoding: 'utf8' });
+        for await (const line of createInterface({ input, crlfDelay: Infinity })) {
+            if (!line.trim())
+                continue;
+            try {
+                const value = JSON.parse(line);
+                if (validOpportunity(value))
+                    records.push(value);
+                else
+                    invalid += 1;
+            }
+            catch {
+                invalid += 1;
+            }
+        }
+        return { records, invalid, status: 'available' };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { records, invalid, status: 'absent' };
+        return { records, invalid: invalid + 1, status: 'unreadable' };
+    }
+}
+const ACTIVITY_LINE_PATTERN = /^##\s+\[(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\]\s+[a-z]+\s+\|\s+(.+?)\s*$/;
+const ORCHESTRATION_ACTIVITY_PATTERN = /\b(?:worker[- ]dispatch|dispatch(?:ed|ing)?\s+(?:a\s+)?worker|address-issues(?:\s+cycle)?|orchestration\s+worker)\b/i;
+async function readOrchestrationActivity(projectRoot, since) {
+    const root = projectAiwgPath(projectRoot);
+    const candidates = [path.join(root, 'activity.log'), path.join(root, 'activity-log', 'activity.log')];
+    for (const candidate of candidates) {
+        try {
+            let recognizable = 0;
+            let valid = 0;
+            const input = createReadStream(candidate, { encoding: 'utf8' });
+            for await (const line of createInterface({ input, crlfDelay: Infinity })) {
+                const match = ACTIVITY_LINE_PATTERN.exec(line);
+                if (!match)
+                    continue;
+                const timestamp = Date.parse(`${match[1]}T${match[2]}:00.000Z`);
+                if (!Number.isFinite(timestamp) || timestamp < since.getTime())
+                    continue;
+                valid += 1;
+                if (ORCHESTRATION_ACTIVITY_PATTERN.test(match[3]))
+                    recognizable += 1;
+            }
+            return { status: 'available', source: path.relative(projectRoot, candidate), valid, recognizable };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            return { status: 'unreadable', source: path.relative(projectRoot, candidate), valid: 0, recognizable: 0 };
+        }
+    }
+    return { status: 'absent', source: null, valid: 0, recognizable: 0 };
+}
+function filterScope(records, sessionId, since) {
+    return records.filter(record => sessionId ? record.sessionId === sessionId : Date.parse(record.timestamp) >= since.getTime());
+}
+function completedCalls(records) {
+    const fallbackReasons = {};
+    let answered = 0;
+    let fallback = 0;
+    let llmTokensAvoided = 0;
+    let jevTokens = 0;
+    for (const record of records) {
+        if (record.status === 'answered')
+            answered += 1;
+        else {
+            fallback += 1;
+            const reason = record.fallbackReason ?? 'unknown';
+            fallbackReasons[reason] = (fallbackReasons[reason] ?? 0) + 1;
+        }
+        llmTokensAvoided += record.llm_tokens_avoided ?? record.estimatedLlmTokensAvoided;
+        jevTokens += record.jev_tokens ?? (record.usage?.inputTokens ?? 0) + (record.usage?.outputTokens ?? 0);
+    }
+    return { completed: records.length, answered, fallback, fallbackReasons, llmTokensAvoided, jevTokens };
+}
+function opportunityCounts(records) {
+    const reasons = {};
+    for (const record of records)
+        reasons[record.reason] = (reasons[record.reason] ?? 0) + 1;
+    return {
+        observed: records.length,
+        eligible: records.filter(record => record.eligible).length,
+        attempted: records.filter(record => record.attempted).length,
+        answered: records.filter(record => record.outcome === 'answered').length,
+        fallback: records.filter(record => record.outcome === 'fallback').length,
+        skipped: records.filter(record => record.outcome === 'skipped').length,
+        unknown: records.filter(record => record.outcome === 'unknown').length,
+        usageRejected: records.filter(record => record.reason === 'usage-rejected').length,
+        ledgerRecordingUnknown: records.filter(record => record.ledgerRecorded === null && record.outcome !== 'skipped').length,
+        reasons,
+    };
+}
+function activationEvidence(input) {
+    return { ...(input?.ruleSourceAvailable !== undefined ? { ruleSourceAvailable: input.ruleSourceAvailable } : {}), addon: input?.addon ?? 'unknown', ruleDelivery: input?.ruleDelivery ?? 'unknown',
+        startupAnchor: input?.startupAnchor ?? 'unknown', nativeActivation: input?.nativeActivation ?? 'not-claimed',
+        ...(input?.source ? { source: input.source } : {}) };
+}
+function askReadinessState(configured, latest) {
+    if (configured === null)
+        return 'unknown';
+    if (!configured)
+        return 'disabled';
+    if (latest?.outcome === 'answered')
+        return 'reachable';
+    if (latest?.outcome === 'fallback' && latest.attempted)
+        return 'fallback';
+    if (latest?.outcome === 'unknown')
+        return 'unknown';
+    return 'configured-unprobed';
+}
+export async function buildDecisionOffloadSnapshot(options) {
+    const projectRoot = path.resolve(options.projectRoot);
+    const env = options.env ?? process.env;
+    const now = options.now ?? new Date();
+    let projectConfig = null;
+    let configReadable = true;
+    try {
+        projectConfig = await readAiwgConfig(projectRoot);
+    }
+    catch {
+        configReadable = false;
+    }
+    const configuredThresholds = projectConfig?.decision?.offload_report;
+    const windowHours = options.windowHours ?? configuredThresholds?.window_hours ?? 24;
+    const since = new Date(now.getTime() - windowHours * 60 * 60 * 1000);
+    const detectedSession = resolveDecisionSession(options.sessionId, env);
+    const sessionId = options.sessionId ?? (detectedSession.sessionId === 'unknown' ? undefined : detectedSession.sessionId);
+    const thresholds = {
+        minimumEligible: configuredThresholds?.minimum_eligible ?? 1,
+        minimumAttemptRate: configuredThresholds?.minimum_attempt_rate ?? 0.5,
+        repeatedFallbacks: configuredThresholds?.repeated_fallbacks ?? 3,
+        ...options.thresholds,
+    };
+    let enablement = null;
+    try {
+        enablement = resolveDecisionEnablement({ cwd: projectRoot, env });
+    }
+    catch {
+        configReadable = false;
+    }
+    let credential;
+    try {
+        credential = await inspectJevCredential({ cwd: projectRoot, env });
+    }
+    catch {
+        credential = { configured: null, enabled: null, source: 'unknown' };
+    }
+    const [opportunitiesRead, ledger, activity] = await Promise.all([
+        readOpportunities(projectRoot),
+        decisionLedgerHistory(projectRoot),
+        readOrchestrationActivity(projectRoot, since),
+    ]);
+    const opportunityEvents = filterScope(opportunitiesRead.records, sessionId, since);
+    const opportunities = collapseOpportunities(opportunityEvents);
+    const calls = filterScope(ledger.records, sessionId, since);
+    const organicOpportunities = opportunities.filter(record => record.category === 'organic');
+    const diagnosticOpportunities = opportunities.filter(record => record.category !== 'organic');
+    const organic = opportunityCounts(organicOpportunities);
+    const diagnostics = opportunityCounts(diagnosticOpportunities);
+    const opportunityIds = new Set(opportunities.filter(record => record.attempted).map(record => record.correlationId));
+    const callIds = new Set(calls.map(record => record.id));
+    const organicOpportunityIds = new Set(organicOpportunities.filter(record => record.attempted).map(record => record.correlationId));
+    const organicCallIds = new Set(calls.filter(record => decisionOffloadCategory(record.caller) === 'organic').map(record => record.id));
+    const latestObserved = [...opportunities].sort((a, b) => a.timestamp.localeCompare(b.timestamp)).at(-1);
+    const latestTransportEvidence = [...opportunities].filter(record => record.attempted)
+        .sort((a, b) => a.timestamp.localeCompare(b.timestamp)).at(-1);
+    const askConfigured = credential.configured === null || credential.enabled === null
+        ? null : credential.configured && credential.enabled;
+    const evaluateState = configReadable && enablement
+        ? (enablement.enabled ? 'configured-unprobed' : 'disabled') : 'unknown';
+    let inspectedActivation;
+    if (!options.activationEvidence) {
+        try {
+            const inspected = await inspectDecisionOffloadActivation({ cwd: projectRoot, frameworkRoot: options.frameworkRoot, env });
+            inspectedActivation = {
+                addon: inspected.installed === true ? 'installed' : inspected.installed === false ? 'missing' : 'unknown',
+                ruleSourceAvailable: inspected.ruleSourcePresent,
+                ruleDelivery: inspected.ruleDelivery,
+                startupAnchor: inspected.startupAnchorPresent === true ? 'present'
+                    : inspected.startupAnchorPresent === false ? 'missing' : 'unknown',
+                nativeActivation: inspected.nativeActivation,
+                source: 'local-configuration-and-startup-pointer; source availability is not delivery',
+            };
+        }
+        catch { /* unavailable inspection remains unknown, never a loading claim */ }
+    }
+    const activation = activationEvidence(options.activationEvidence ?? inspectedActivation);
+    const organicCalls = calls.filter(record => decisionOffloadCategory(record.caller) === 'organic');
+    const activityCandidate = activity.recognizable > 0 && organicCalls.length === 0;
+    const activitySuppressionReason = !activityCandidate ? null
+        : activation.addon === 'unknown' ? 'activation-unknown'
+            : activation.addon === 'missing' ? 'addon-missing'
+                : askConfigured === null ? 'ask-readiness-unknown'
+                    : askConfigured === false ? 'ask-disabled-or-unconfigured'
+                        : null;
+    const activityGap = activityCandidate && activitySuppressionReason === null;
+    const driftReasons = [];
+    const attemptedWithoutLedger = [...opportunityIds].filter(id => !callIds.has(id)).length;
+    const organicAttemptedWithoutLedger = [...organicOpportunityIds].filter(id => !organicCallIds.has(id)).length;
+    if (!configReadable || opportunitiesRead.status === 'unreadable' || opportunitiesRead.invalid > 0 || organic.unknown > 0)
+        driftReasons.push('observation-unknown');
+    if (organic.ledgerRecordingUnknown > 0 || ledger.skipped > 0)
+        driftReasons.push('recording-failure-or-unknown');
+    if (organicAttemptedWithoutLedger > 0)
+        driftReasons.push('attempted-without-completed-ledger');
+    if (organic.usageRejected > 0)
+        driftReasons.push('usage-rejection');
+    if (activation.addon === 'missing')
+        driftReasons.push('missing-addon');
+    else if (activation.addon === 'unknown')
+        driftReasons.push('activation-evidence-unknown');
+    if (activation.ruleDelivery === 'missing')
+        driftReasons.push('missing-rule-delivery');
+    if (activation.startupAnchor === 'missing')
+        driftReasons.push('missing-activation-anchor');
+    if (askConfigured === false)
+        driftReasons.push('disabled-or-unconfigured');
+    else if (askConfigured === null)
+        driftReasons.push('ask-readiness-unknown');
+    if (organic.eligible > 0 && organic.eligible >= thresholds.minimumEligible) {
+        const rate = organic.eligible ? organic.attempted / organic.eligible : 0;
+        if (organic.attempted === 0)
+            driftReasons.push('observed-eligible-zero-attempts');
+        else if (rate < thresholds.minimumAttemptRate)
+            driftReasons.push('observed-eligible-low-attempt-rate');
+    }
+    if (organic.fallback >= thresholds.repeatedFallbacks)
+        driftReasons.push('repeated-fallback');
+    const unknown = !configReadable || askConfigured === null || activation.addon === 'unknown' || activation.startupAnchor === 'unknown'
+        || opportunitiesRead.status === 'unreadable' || opportunitiesRead.invalid > 0
+        || organic.unknown > 0 || organic.ledgerRecordingUnknown > 0 || ledger.skipped > 0 || organicAttemptedWithoutLedger > 0;
+    const driftStatus = unknown ? 'unknown' : organic.eligible === 0 ? 'not-applicable' : driftReasons.length ? 'advisory' : 'ok';
+    return {
+        schema: DECISION_OFFLOAD_SNAPSHOT_SCHEMA,
+        scope: { projectRoot, mode: sessionId ? 'session' : 'window', sessionId: sessionId ?? null,
+            since: sessionId ? null : since.toISOString(), windowHours: sessionId ? null : windowHours, generatedAt: now.toISOString() },
+        readiness: {
+            ask: { state: askReadinessState(askConfigured, latestTransportEvidence), configured: credential.configured,
+                enabled: credential.enabled, source: credential.source, probed: false },
+            evaluate: { state: evaluateState, enabled: enablement?.enabled ?? null,
+                source: configReadable && enablement ? enablement.source : 'unknown', probed: false },
+            observed: latestObserved ? {
+                timestamp: latestObserved.timestamp, transport: latestObserved.transport,
+                category: latestObserved.category, outcome: latestObserved.outcome,
+                reason: latestObserved.reason,
+            } : null,
+        },
+        activation,
+        coverage: { executable: DECISION_OFFLOAD_EXECUTABLE_COVERAGE,
+            instructionOnly: DECISION_OFFLOAD_CHECKPOINT_COVERAGE, unsupportedObservation: 'unknown' },
+        opportunities: { organic, excluded: diagnostics, journalEvents: opportunityEvents.length, invalidRecords: opportunitiesRead.invalid,
+            journal: opportunitiesRead.status },
+        calls: { organic: completedCalls(organicCalls),
+            excluded: completedCalls(calls.filter(record => decisionOffloadCategory(record.caller) !== 'organic')), invalidRecords: ledger.skipped },
+        activityHint: {
+            status: activityGap ? 'advisory' : 'none',
+            reason: activityGap ? 'orchestration-without-organic-completed-calls' : null,
+            suppressionReason: activitySuppressionReason,
+            recognizableOrchestrationEvents: activity.recognizable,
+            eligibleCount: 'unknown',
+            confidence: 'low',
+            scope: 'recent-window',
+            source: activity.source,
+            journal: activity.status,
+            note: 'Generic activity is a low-confidence signal only; it is not a measured eligible-opportunity denominator.',
+        },
+        correlation: { matched: [...opportunityIds].filter(id => callIds.has(id)).length,
+            attemptedWithoutLedger,
+            organicAttemptedWithoutLedger,
+            ledgerWithoutOpportunity: [...callIds].filter(id => !opportunityIds.has(id)).length },
+        drift: { status: driftStatus, advisory: driftStatus === 'advisory', reasons: [...new Set(driftReasons)], thresholds,
+            thresholdSource: options.thresholds ? 'options' : configuredThresholds ? 'project' : 'default',
+            note: organic.eligible === 0 ? 'No observed eligible checkpoints; this is not evidence of healthy adoption.' : null },
+    };
+}
+//# sourceMappingURL=offload.js.map

package/dist/src/decision/qualification/load.js

@@ -110,9 +110,7 @@ export async function runDecisionLoadHarness(options) {
     const { manifest, clock, driver, sample } = options;
     const arrivals = decisionLoadArrivals(manifest, options.windowSeconds);
     const start = clock.now();
-    const threadCpu = process.threadCpuUsage?.bind(process);
-    const cpuStart = threadCpu?.();
-    const wallStart = process.hrtime.bigint();
+    const cpuStart = process.threadCpuUsage();
     let rss = process.memoryUsage().rss;
     let heap = process.memoryUsage().heapUsed;
     const sampleMemory = () => {
@@ -170,8 +168,8 @@ export async function runDecisionLoadHarness(options) {
         await clock.advance(drainStep);
     const results = await all;
     sampleMemory();
-    const threadUsage = cpuStart && threadCpu ? threadCpu(cpuStart) : undefined;
-    const cpuMicros = threadUsage ? threadUsage.user + threadUsage.system : Number(process.hrtime.bigint() - wallStart) / 1000;
+    const threadUsage = process.threadCpuUsage(cpuStart);
+    const cpuMicros = threadUsage.user + threadUsage.system;
     const virtualDurationMs = Math.max(1, clock.now() - start);
     const shedReasons = {};
     let attempts = 0;
@@ -219,7 +217,7 @@ export async function runDecisionLoadHarness(options) {
             heapUsedMiB: Number((heap / 1_048_576).toFixed(1)),
             residentMemoryMiB: Number((rss / 1_048_576).toFixed(1)),
             cpuPercentOneCore: Number(((cpuMicros / 1000) / virtualDurationMs * 100).toFixed(3)),
-            cpuSource: threadUsage ? 'thread' : 'wall-clock-upper-bound',
+            cpuSource: 'thread',
         },
     };
 }

package/dist/src/decision/savings.js

@@ -0,0 +1,28 @@
+/** Planning assumptions, not a vendor price quote or measured caller usage. */
+export const DEFAULT_DECISION_SAVINGS_WEIGHTS = {
+    caller_model_class: 'reasoning',
+    reasoning_tokens: 1024,
+    output_tokens: 128,
+    llm_per_mtok: 15,
+    jev_per_mtok: 0.2,
+};
+export function decisionSavingsWeights(ask) {
+    const modelClass = ask?.savings?.caller_model_class ?? 'reasoning';
+    return {
+        ...DEFAULT_DECISION_SAVINGS_WEIGHTS,
+        ...ask?.cost,
+        caller_model_class: modelClass,
+        reasoning_tokens: ask?.savings?.reasoning_tokens ?? (modelClass === 'reasoning' ? 1024 : 256),
+        output_tokens: ask?.savings?.output_tokens ?? 128,
+    };
+}
+export function estimateDecisionSavings(inputTokens, answered, jevTokens, weights) {
+    const llmTokens = answered ? inputTokens + weights.reasoning_tokens + weights.output_tokens : 0;
+    return {
+        llm_tokens_avoided: llmTokens,
+        jev_tokens: jevTokens,
+        cost_weighted_net_usd: (llmTokens * weights.llm_per_mtok - jevTokens * weights.jev_per_mtok) / 1_000_000,
+        estimationMethod: { version: 'aiwg-decision-savings/v2', input_tokens: inputTokens, ...weights },
+    };
+}
+//# sourceMappingURL=savings.js.map

package/dist/src/effects/types.js

@@ -41,7 +41,11 @@ export const UNKNOWN_REASONS = [
     'container-unreadable',
     'paging-incomplete',
     'consistency-lag',
-    'tracker-blocked',
+    'tracker-blocked', // Retained for existing ledger records.
+    'tracker-provider-unresolved',
+    'tracker-repository-mismatch',
+    'tracker-credential-missing',
+    'tracker-no-access-route',
     'malformed-response',
     'evidence-conflict',
 ];

package/dist/src/effects/verifiers/git.js

@@ -13,6 +13,7 @@
  *
  * @see docs/contracts/effect-ledger.v1.md "Built-in verifiers"
  */
+import { signalChild } from '../../process/signal-child.mjs';
 import { spawn } from 'node:child_process';
 import { EffectVerifierError } from './types.js';
 export const GIT_VERIFIER_VERSION = '1.0.0';
@@ -31,7 +32,7 @@ function spawnRunner(repoDir, binary) {
         const collect = (sink) => (chunk) => {
             size += chunk.length;
             if (size > MAX_OUTPUT)
-                child.kill();
+                signalChild(child);
             else
                 sink.push(chunk);
         };