@aiwg/cli 2026.10.7 → 2026.10.9

package/dist/src/cost/fleet-report.js

@@ -1,7 +1,7 @@
 /**
  * OpenRouter fleet spend observation and local activity correlation.
  *
- * Secrets are resolved only from the process environment or the user's
+ * Secrets are resolved from named sources or the user's
  * ~/.config/aiwg/keys directory. Fleet configuration contains references,
  * never credential values.
  *
@@ -11,6 +11,7 @@ import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { load as loadYaml } from 'js-yaml';
+import { resolveSensitiveInput } from '../auth/sensitive-input.js';
 const OPENROUTER_API = 'https://openrouter.ai/api/v1';
 const KEY_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const SECRET_FIELD_PATTERN = /(?:api[_-]?key|token|secret|credential|authorization)/i;
@@ -60,6 +61,9 @@ function validateFleetConfig(value) {
         if (!KEY_REF_PATTERN.test(entry.key_ref)) {
             throw new Error(`fleet[${index}].key_ref contains unsupported characters.`);
         }
+        if (entry.key_store !== undefined && (typeof entry.key_store !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(entry.key_store))) {
+            throw new Error(`fleet[${index}].key_store must name a native-store entry (1–128 letters, digits, dots, underscores or hyphens).`);
+        }
         if (typeof entry.monthly_cap !== 'number' || !Number.isFinite(entry.monthly_cap) || entry.monthly_cap < 0) {
             throw new Error(`fleet[${index}].monthly_cap must be a non-negative number.`);
         }
@@ -73,6 +77,7 @@ function validateFleetConfig(value) {
             bot: entry.bot.trim(),
             machine: entry.machine.trim(),
             key_ref: entry.key_ref,
+            ...(entry.key_store !== undefined ? { key_store: entry.key_store } : {}),
             monthly_cap: entry.monthly_cap,
         };
     });
@@ -101,10 +106,16 @@ export async function loadFleetKey(keyRef, options = {}) {
     if (!KEY_REF_PATTERN.test(keyRef))
         throw new Error('Invalid key_ref.');
     const env = options.env ?? process.env;
+    const dependencies = { environment: env, readStore: options.readStore, isTTY: false };
+    // An explicit reference is scoped to this entry. Never probe a global key or
+    // another bot's store when the selected source is unavailable.
+    if (options.store !== undefined) {
+        return resolveSensitiveInput({ prefix: 'key', store: options.store }, dependencies);
+    }
     const environmentName = keyEnvironmentName(keyRef);
     const environmentValue = env[environmentName]?.trim();
     if (environmentValue)
-        return environmentValue;
+        return resolveSensitiveInput({ prefix: 'key', env: environmentName }, dependencies);
     const homeDir = options.homeDir ?? os.homedir();
     const keyDirectory = path.resolve(homeDir, '.config', 'aiwg', 'keys');
     const keyPath = path.resolve(keyDirectory, keyRef);
@@ -116,7 +127,7 @@ export async function loadFleetKey(keyRef, options = {}) {
     }
     catch (error) {
         if (error.code === 'ENOENT') {
-            throw new Error(`No secure credential directory exists for key_ref '${keyRef}'; use ${environmentName} or create ~/.config/aiwg/keys with mode 0700.`);
+            throw new Error(`No secure credential directory exists for key_ref '${keyRef}'; use ${environmentName}, --key-store <name> (fleet: key_store), or create ~/.config/aiwg/keys with mode 0700.`);
         }
         throw error;
     }
@@ -129,27 +140,12 @@ export async function loadFleetKey(keyRef, options = {}) {
     if (typeof process.getuid === 'function' && directoryStat.uid !== process.getuid()) {
         throw new Error('The AIWG credential directory must be owned by the current user.');
     }
-    let stat;
     try {
-        stat = await fs.lstat(keyPath);
+        return await resolveSensitiveInput({ prefix: 'key', file: keyPath }, dependencies);
     }
     catch (error) {
-        if (error.code === 'ENOENT') {
-            throw new Error(`No credential found for key_ref '${keyRef}' in the secure key directory or ${environmentName}.`);
-        }
-        throw error;
-    }
-    if (stat.isSymbolicLink() || !stat.isFile())
-        throw new Error(`Credential for key_ref '${keyRef}' must be a regular file, not a symlink.`);
-    if ((stat.mode & 0o077) !== 0)
-        throw new Error(`Credential file for key_ref '${keyRef}' must not be accessible by group or other users.`);
-    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
-        throw new Error(`Credential file for key_ref '${keyRef}' must be owned by the current user.`);
+        throw new Error(`Credential for key_ref '${keyRef}': ${error.message} Use ${environmentName}, --key-store <name> (fleet: key_store), or a private ~/.config/aiwg/keys/<key_ref> file.`);
     }
-    const value = (await fs.readFile(keyPath, 'utf8')).trim();
-    if (!value)
-        throw new Error(`Credential file for key_ref '${keyRef}' is empty.`);
-    return value;
 }
 function parseActivityLog(raw) {
     const entries = [];
@@ -202,7 +198,9 @@ async function openRouterGet(endpoint, key, options) {
     }
     if (!payload || typeof payload !== 'object' || !payload.data)
         throw new Error('OpenRouter returned an invalid response.');
-    return payload.data;
+    // Generation metadata can reflect a request header in free-text fields. Keep
+    // such content out of both structured and human-readable reports.
+    return JSON.parse(JSON.stringify(payload.data, (_name, value) => (typeof value === 'string' ? value.split(key).join('[REDACTED]') : value)));
 }
 function correlateGenerations(records) {
     const sessions = new Map();
@@ -223,7 +221,7 @@ function correlateGenerations(records) {
 }
 async function reportBot(entry, activity, options) {
     try {
-        const key = await loadFleetKey(entry.key_ref, options);
+        const key = await loadFleetKey(entry.key_ref, { ...options, store: entry.key_store });
         const keyData = await openRouterGet('/key', key, options);
         const spend = Number(keyData.usage_monthly ?? keyData.usage ?? 0);
         if (!Number.isFinite(spend) || spend < 0)

package/dist/src/decision/driver.js

@@ -4,12 +4,12 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { askDecision, setupJev, DecisionAskUsageError, readDecisionContextFile, validateDecisionAskInput, } from './ask.js';
-import { recordDecisionAsk, decisionLedgerHistory, decisionLedgerStats, resolveDecisionSessionId, resolveDecisionSession, DECISION_SESSION_ENV_VARS, parseDecisionLedgerSince, DecisionLedgerSinceError, DECISION_LEDGER_SCHEMA, DECISION_LEDGER_SCHEMA_V1, ATTRIBUTION_FIELD_PATTERN, MAX_ATTRIBUTION_FIELD_LENGTH, MAX_RECORDED_CHOICE_IDS, MAX_RECORD_TEXT_BYTES, MAX_LEDGER_RECORD_BYTES, DECISION_LEDGER_RECORD_TIMEOUT_MS, DECISION_SAVINGS_REASONING_ALLOWANCE_TOKENS, DECISION_SAVINGS_ESTIMATION_METHOD, buildDecisionLedgerRecord, appendDecisionLedgerRecord, filterDecisionLedgerRecords, } from './ledger.js';
+import { recordDecisionAsk, decisionLedgerHistory, decisionLedgerStats, rotateDecisionLedger, parseDecisionLedgerRetention, resolveDecisionSessionId, resolveDecisionSession, DECISION_SESSION_ENV_VARS, parseDecisionLedgerSince, DecisionLedgerSinceError, DECISION_LEDGER_SCHEMA, DECISION_LEDGER_SCHEMA_V1, ATTRIBUTION_FIELD_PATTERN, MAX_ATTRIBUTION_FIELD_LENGTH, MAX_RECORDED_CHOICE_IDS, MAX_RECORD_TEXT_BYTES, MAX_LEDGER_RECORD_BYTES, DECISION_LEDGER_RECORD_TIMEOUT_MS, DECISION_SAVINGS_REASONING_ALLOWANCE_TOKENS, DECISION_SAVINGS_ESTIMATION_METHOD, buildDecisionLedgerRecord, appendDecisionLedgerRecord, filterDecisionLedgerRecords, } from './ledger.js';
 export { DEFAULT_DECISION_SAVINGS_WEIGHTS, decisionSavingsWeights } from './savings.js';
 import { resolveActiveProvider } from '../cli/provider-resolution.js';
 export { appendDecisionOpportunity, buildDecisionOffloadSnapshot, decisionOffloadCategory, DECISION_OFFLOAD_CHECKPOINT_COVERAGE, DECISION_OFFLOAD_EXECUTABLE_COVERAGE, DECISION_OFFLOAD_SNAPSHOT_SCHEMA, DECISION_OPPORTUNITY_SCHEMA, runDecisionOffloadCheckpoint, } from './offload.js';
 import { assertDecisionEvaluateDispatcherConfig, decisionPatternPacks, getDecisionPatternPack, governedPatternArtifacts, listDecisionPatterns, patternInputSchema, patternOutputSchema, planLiveDecisionPattern, runOfflineDecisionPattern, validateAgainstSchema, validateDecisionDocument, validateDefinition, validateRuleset, } from './index.js';
-export { askDecision, setupJev, readDecisionContextFile, validateDecisionAskInput, DecisionAskUsageError, recordDecisionAsk, decisionLedgerHistory, decisionLedgerStats, resolveDecisionSessionId, resolveDecisionSession, DECISION_SESSION_ENV_VARS, parseDecisionLedgerSince, DecisionLedgerSinceError, DECISION_LEDGER_SCHEMA, DECISION_LEDGER_SCHEMA_V1, ATTRIBUTION_FIELD_PATTERN, MAX_ATTRIBUTION_FIELD_LENGTH, MAX_RECORDED_CHOICE_IDS, MAX_RECORD_TEXT_BYTES, MAX_LEDGER_RECORD_BYTES, DECISION_LEDGER_RECORD_TIMEOUT_MS, DECISION_SAVINGS_REASONING_ALLOWANCE_TOKENS, DECISION_SAVINGS_ESTIMATION_METHOD, buildDecisionLedgerRecord, appendDecisionLedgerRecord, filterDecisionLedgerRecords, resolveActiveProvider, };
+export { askDecision, setupJev, readDecisionContextFile, validateDecisionAskInput, DecisionAskUsageError, recordDecisionAsk, decisionLedgerHistory, decisionLedgerStats, rotateDecisionLedger, parseDecisionLedgerRetention, resolveDecisionSessionId, resolveDecisionSession, DECISION_SESSION_ENV_VARS, parseDecisionLedgerSince, DecisionLedgerSinceError, DECISION_LEDGER_SCHEMA, DECISION_LEDGER_SCHEMA_V1, ATTRIBUTION_FIELD_PATTERN, MAX_ATTRIBUTION_FIELD_LENGTH, MAX_RECORDED_CHOICE_IDS, MAX_RECORD_TEXT_BYTES, MAX_LEDGER_RECORD_BYTES, DECISION_LEDGER_RECORD_TIMEOUT_MS, DECISION_SAVINGS_REASONING_ALLOWANCE_TOKENS, DECISION_SAVINGS_ESTIMATION_METHOD, buildDecisionLedgerRecord, appendDecisionLedgerRecord, filterDecisionLedgerRecords, resolveActiveProvider, };
 const DECISION_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const VALIDATION_TARGETS = ['request', 'definition', 'ruleset', 'binding'];
 const OFFLINE_ADAPTER = 'agentic/code/addons/decision-engine/examples/fixture-jev-adapter.mjs';

package/dist/src/decision/jev-credentials.js

@@ -1,10 +1,11 @@
 import { resolveDecisionEnablement } from '../config/decision-config.js';
 import { constants } from 'node:fs';
-import { access, chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { access, chmod, lstat, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { JevCredentialError } from './adapters/jev.js';
+import { readPrivateValueFile } from '../auth/sensitive-input.js';
 export const JEV_CREDENTIAL_REF = 'typesafe-api';
 export const JEV_DEFAULT_REGION = 'us';
 function env(options) {
@@ -45,10 +46,22 @@ function parseRecord(raw) {
 async function readCredentialFile(options = {}) {
     const credentialPath = jevCredentialPath(options);
     try {
-        const [fileStat, parentStat] = await Promise.all([stat(credentialPath), stat(path.dirname(credentialPath))]);
-        if (isInsecureMode(fileStat.mode) || isInsecureMode(parentStat.mode))
-            throw new JevCredentialError('denied');
-        return parseRecord(await readFile(credentialPath, 'utf8'));
+        // Preserve the missing-file result and the existing directory requirement.
+        // The shared reader validates the opened descriptor, including ownership
+        // and link checks, before any credential record is parsed.
+        const [, parentStat] = await Promise.all([lstat(credentialPath), stat(path.dirname(credentialPath))]);
+        if (isInsecureMode(parentStat.mode)) {
+            throw Object.assign(new JevCredentialError('denied'), { message: 'Jev credential directory must not allow group or other access (chmod 700).' });
+        }
+        let raw;
+        try {
+            raw = await readPrivateValueFile(credentialPath, 'Jev credential file');
+        }
+        catch (error) {
+            // Shared private-file diagnostics contain no path or credential bytes.
+            throw Object.assign(new JevCredentialError('denied'), { message: error.message });
+        }
+        return parseRecord(raw);
     }
     catch (error) {
         if (error.code === 'ENOENT')

package/dist/src/decision/ledger.js

@@ -21,9 +21,9 @@
  * assumption that the artifact root is owned and written by the SAME local
  * user running `aiwg`. It does not and cannot defend against a HOSTILE
  * process running as that same user: such a process already has read/write
- * access to everything the ledger could protect. There is no cross-process
- * lock and no privilege boundary here, by design — adding one would be the
- * "second subsystem" this feature deliberately avoids. Every filesystem
+ * access to everything the ledger could protect. Appenders, rotation and
+ * readers share the existing cross-process directory-lock helper. There is
+ * no privilege boundary here. Every filesystem
  * check below uses only portable Node primitives (no `/proc`, no handle
  * anchoring): `mkdir`/`lstat` for the directory, `open`+`fstat` for the
  * file, with `O_NOFOLLOW` applied when the platform defines it (POSIX; not
@@ -39,25 +39,26 @@
  * single-write atomicity boundary most platforms also honor for `PIPE_BUF`
  * (4096 bytes on Linux): this makes a single, non-interleaved write the
  * overwhelmingly likely outcome for one record, but it is not a guarantee.
- * There is no cross-process append lock, so two concurrent writers can in
- * rare cases interleave and produce one malformed line; `history`/`stats`
- * detect and skip a malformed line (counted, never silently merged into a
- * neighboring record) rather than assuming it is impossible.
+ * The lock covers opening, checking the trailing newline, writing every
+ * byte and closing. Rotation holds that same lock through live-file
+ * replacement. `history`/`stats` count malformed lines as skipped; retention
+ * preserves their original bytes.
  *
  * Recording — attribution resolution and the write — is bounded by a short
  * deadline (`DECISION_LEDGER_RECORD_TIMEOUT_MS`). On timeout, the in-flight
  * attempt is not cancelled (Node has no way to abort an in-flight `open`),
  * so its outcome is genuinely unknown: the record may or may not eventually
  * land. The warning says exactly that ("completion unknown"), and no
- * further stage of that same attempt starts once the deadline has fired
- * (checked before each later `await`), so a slow attribution lookup cannot
- * itself delay the subsequent write past the deadline.
+ * attribution-to-append stage starts once the deadline has fired. An append
+ * already waiting for the ledger lock can still complete after that deadline.
  */
 import { randomUUID, createHash } from 'node:crypto';
 import { constants as fsConstants, createReadStream, existsSync } from 'node:fs';
-import { lstat, mkdir, open } from 'node:fs/promises';
+import { lstat, mkdir, open, readdir, rename, rm } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
-import { join } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { acquireDirectoryLock } from '../artifacts/prebuilt-build-lock.js';
+import { syncDirectory } from '../storage/protected-files.js';
 import { projectAiwgPath, projectAiwgWritePath } from '../config/project-artifacts.js';
 import { redactText } from '../governance/redaction.js';
 import { CanonicalJsonByteEstimator } from './context-plan.js';
@@ -121,6 +122,7 @@ export const MAX_LEDGER_RECORD_BYTES = 4000;
 export const DECISION_LEDGER_RECORD_TIMEOUT_MS = 250;
 const LEDGER_DIR_MODE = 0o700;
 const LEDGER_FILE_MODE = 0o600;
+const LEDGER_LOCK_TIMEOUT_MS = 30_000;
 const IS_WINDOWS = process.platform === 'win32';
 const HAS_O_NOFOLLOW = typeof fsConstants.O_NOFOLLOW === 'number';
 function errorMessage(error) {
@@ -349,8 +351,8 @@ async function ensurePrivateDecisionDir(projectRoot, warn) {
     return decisionDir;
 }
 /**
- * Open (creating if needed) `ledger.jsonl` for append and verify it is safe
- * to write: a regular file with exactly one hard link (rejects a
+ * Open a private ledger/archive file (append by default, read-only for
+ * retention) and verify it is a regular file with exactly one hard link (rejects a
  * pre-planted hard link to an unrelated file, which `O_NOFOLLOW` alone does
  * not catch), and on POSIX owned by the current user with no group/other
  * permission bits. `O_NOFOLLOW` is applied when the platform defines it
@@ -360,7 +362,7 @@ async function ensurePrivateDecisionDir(projectRoot, warn) {
  * check is closed untouched (no chmod, no write) and recording is skipped
  * with exactly one warning naming the reason.
  */
-async function openLedgerFileForAppend(ledgerPath, warn) {
+async function openPrivateLedgerFile(ledgerPath, warn, flags = fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_WRONLY) {
     try {
         const pre = await lstat(ledgerPath);
         if (pre.isSymbolicLink()) {
@@ -374,10 +376,9 @@ async function openLedgerFileForAppend(ledgerPath, warn) {
             return null;
         }
     }
-    const flags = fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_WRONLY | (HAS_O_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
     let handle;
     try {
-        handle = await open(ledgerPath, flags, LEDGER_FILE_MODE);
+        handle = await open(ledgerPath, flags | (HAS_O_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0), LEDGER_FILE_MODE);
     }
     catch (error) {
         warn(`warning: cannot open decision ledger file: ${errorMessage(error)}`);
@@ -466,10 +467,13 @@ export async function appendDecisionLedgerRecord(record, options) {
     if (!decisionDir)
         return false;
     const ledgerPath = join(decisionDir, DECISION_LEDGER_FILE_NAME);
-    const handle = await openLedgerFileForAppend(ledgerPath, warn);
-    if (!handle)
-        return false;
+    let release;
+    let handle = null;
     try {
+        release = await lockDecisionLedger(decisionDir);
+        handle = await openPrivateLedgerFile(ledgerPath, warn);
+        if (!handle)
+            return false;
         const prefix = (await needsLeadingNewline(ledgerPath)) ? '\n' : '';
         await writeFully(handle, Buffer.from(prefix + line, 'utf8'), options.writeChunk);
         return true;
@@ -479,7 +483,162 @@ export async function appendDecisionLedgerRecord(record, options) {
         return false;
     }
     finally {
-        await handle.close().catch(() => { });
+        await handle?.close().catch(() => { });
+        await release?.().catch(error => warn(`warning: cannot release decision ledger lock: ${errorMessage(error)}`));
+    }
+}
+function lockDecisionLedger(decisionDir) {
+    return acquireDirectoryLock(join(decisionDir, 'ledger.lock'), {
+        timeoutMs: LEDGER_LOCK_TIMEOUT_MS, pollMs: 10, reclaimDeadOwner: true,
+    });
+}
+export function parseDecisionLedgerRetention(keepLast, all = false) {
+    if (all) {
+        if (keepLast !== undefined)
+            throw new Error('--all cannot be combined with --keep-last');
+        return {};
+    }
+    const match = /^(\d+)(d?)$/.exec(keepLast ?? '90d');
+    const n = match ? Number(match[1]) : NaN;
+    if (!Number.isSafeInteger(n) || n <= 0 || !Number.isSafeInteger(n * (match?.[2] ? 86_400_000 : 1))) {
+        throw new Error('--keep-last must be a positive count or <N>d; rotating everything requires --all');
+    }
+    return match?.[2] ? { ms: n * 86_400_000 } : { count: n };
+}
+function isBeneath(root, target) {
+    const rel = relative(root, target);
+    return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/** Walk before mkdir: recursive mkdir alone could write through a symlinked ancestor. */
+async function privateArchiveDirectory(root, target, create) {
+    let current = root;
+    for (const part of relative(root, target).split(sep)) {
+        current = join(current, part);
+        if (create) {
+            try {
+                await mkdir(current, { mode: LEDGER_DIR_MODE });
+                if (!IS_WINDOWS)
+                    await syncDirectory(dirname(current));
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch (error) {
+            if (!create && error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+        // archive/ is shared with the activity log and may already be readable.
+        // Its decision/ subtree (and any nested directories) must be private.
+        const modeMask = current === join(root, 'archive') ? 0o022 : 0o077;
+        if (!info.isDirectory() || (!IS_WINDOWS && (info.uid !== currentUid() || (info.mode & modeMask) !== 0))) {
+            throw new Error(`Unsafe decision archive directory (requires a private, owned real directory): ${current}`);
+        }
+    }
+    return true;
+}
+/** Retention preserves each raw line, including invalid UTF-8, CRLF and an unterminated final line. */
+export async function rotateDecisionLedger(options) {
+    const retention = parseDecisionLedgerRetention(options.keepLast, options.all);
+    const now = (options.now ?? Date.now)();
+    const artifactRoot = projectAiwgWritePath(options.projectRoot);
+    const archiveRoot = join(artifactRoot, 'archive', 'decision');
+    const archivePath = resolve(artifactRoot, options.to ?? join('archive', 'decision', `${new Date(now).toISOString().replace(/[-:]/g, '').replace('T', '-').replace(/\.\d{3}Z$/, '')}-${randomUUID()}.jsonl`));
+    if (!isBeneath(artifactRoot, archivePath))
+        throw new Error('Archive path must stay inside the resolved artifact root');
+    if (!isBeneath(archiveRoot, archivePath) || !archivePath.endsWith('.jsonl')) {
+        throw new Error('Archive path must be a .jsonl file beneath archive/decision/ in the resolved artifact root');
+    }
+    const fail = (message) => { throw new Error(message); };
+    const decisionDir = await ensurePrivateDecisionDir(options.projectRoot, fail);
+    if (!decisionDir)
+        throw new Error('Cannot access decision ledger directory');
+    const release = await lockDecisionLedger(decisionDir);
+    const ledgerPath = join(decisionDir, DECISION_LEDGER_FILE_NAME);
+    const tempPath = join(decisionDir, `.ledger-${randomUUID()}.tmp`);
+    let archiveCreated = false;
+    try {
+        const live = await openPrivateLedgerFile(ledgerPath, fail, fsConstants.O_RDONLY | fsConstants.O_CREAT);
+        if (!live)
+            throw new Error('Cannot read decision ledger');
+        let content;
+        try {
+            content = await live.readFile();
+        }
+        finally {
+            await live.close();
+        }
+        const lines = [];
+        for (let start = 0; start < content.length;) {
+            const newline = content.indexOf(0x0a, start);
+            const end = newline < 0 ? content.length : newline + 1;
+            const bytes = content.subarray(start, end);
+            let timestamp = null;
+            try {
+                const record = JSON.parse(bytes.toString('utf8'));
+                if (isDecisionLedgerRecord(record))
+                    timestamp = Date.parse(record.timestamp);
+            }
+            catch { /* preserve malformed bytes */ }
+            lines.push({ bytes, timestamp });
+            start = end;
+        }
+        const valid = lines.filter(line => line.timestamp !== null).sort((a, b) => a.timestamp - b.timestamp);
+        const recent = new Set(retention.count === undefined ? [] : valid.slice(-retention.count));
+        const kept = [], archived = [];
+        for (const line of lines) {
+            const keep = !options.all && (line.timestamp === null || (retention.count !== undefined
+                ? recent.has(line) : line.timestamp >= now - retention.ms));
+            (keep ? kept : archived).push(line.bytes);
+        }
+        const result = { archived: archived.length, retained: kept.length,
+            malformed: lines.length - valid.length, archivePath: archived.length ? archivePath : null };
+        if (!archived.length)
+            return result;
+        await privateArchiveDirectory(artifactRoot, dirname(archivePath), true);
+        const archive = await open(archivePath, 'wx', LEDGER_FILE_MODE);
+        archiveCreated = true;
+        try {
+            await writeFully(archive, Buffer.concat(archived));
+            await archive.sync();
+        }
+        finally {
+            await archive.close();
+        }
+        if (!IS_WINDOWS)
+            await syncDirectory(dirname(archivePath));
+        const replacement = await open(tempPath, 'wx', LEDGER_FILE_MODE);
+        try {
+            await writeFully(replacement, Buffer.concat(kept));
+            await replacement.sync();
+        }
+        finally {
+            await replacement.close();
+        }
+        await rename(tempPath, ledgerPath);
+        archiveCreated = false; // Both files now own their respective records.
+        if (!IS_WINDOWS)
+            await syncDirectory(decisionDir);
+        return result;
+    }
+    catch (error) {
+        if (archiveCreated)
+            await rm(archivePath, { force: true }); // Live file is still intact.
+        throw error;
+    }
+    finally {
+        try {
+            await rm(tempPath, { force: true });
+        }
+        finally {
+            await release();
+        }
     }
 }
 /** Never throws: a provider-detection failure (missing config, unreadable capability matrix, …) degrades to "unknown". */
@@ -723,20 +882,57 @@ async function* streamDecisionLedgerLines(path) {
         rl.close();
     }
 }
-/** Streams parsed-and-validated records one at a time; invalid lines yield `null` so callers can count them as skipped. */
-async function* streamDecisionLedgerRecords(projectRoot) {
-    for await (const line of streamDecisionLedgerLines(ledgerReadPath(projectRoot))) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        try {
-            const parsed = JSON.parse(trimmed);
-            yield isDecisionLedgerRecord(parsed) ? parsed : null;
+async function archiveLedgerPaths(artifactRoot, directory = join(artifactRoot, 'archive', 'decision')) {
+    if (!await privateArchiveDirectory(artifactRoot, directory, false))
+        return [];
+    const paths = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const target = join(directory, entry.name);
+        if (entry.isSymbolicLink())
+            throw new Error(`Unsafe decision archive symlink: ${target}`);
+        if (entry.isDirectory())
+            paths.push(...await archiveLedgerPaths(artifactRoot, target));
+        else if (entry.name.endsWith('.jsonl')) {
+            const handle = await openPrivateLedgerFile(target, message => { throw new Error(message); }, fsConstants.O_RDONLY);
+            if (!handle)
+                throw new Error(`Unsafe decision archive: ${target}`);
+            await handle.close();
+            paths.push(target);
         }
-        catch {
-            yield null;
+    }
+    return paths.sort();
+}
+/** Streams validated records under the rotation lock; invalid lines yield null. */
+async function* streamDecisionLedgerRecords(projectRoot, includeArchives = false) {
+    const livePath = ledgerReadPath(projectRoot);
+    const decisionDir = dirname(livePath);
+    if (!existsSync(decisionDir))
+        return;
+    if (!(await lstat(decisionDir)).isDirectory())
+        throw new Error('Decision ledger directory must be a real directory');
+    // A single lock also prevents readers from observing the archive and live
+    // replacement at different points in a rotation (duplicates or omissions).
+    const release = await lockDecisionLedger(decisionDir);
+    try {
+        const paths = includeArchives ? [...await archiveLedgerPaths(projectAiwgPath(projectRoot)), livePath] : [livePath];
+        for (const path of paths) {
+            for await (const line of streamDecisionLedgerLines(path)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    yield isDecisionLedgerRecord(parsed) ? parsed : null;
+                }
+                catch {
+                    yield null;
+                }
+            }
         }
     }
+    finally {
+        await release();
+    }
 }
 function matchesFilters(record, filters) {
     if (filters.since && new Date(record.timestamp).getTime() < filters.since.getTime())
@@ -765,7 +961,7 @@ export function filterDecisionLedgerRecords(records, filters) {
 export async function decisionLedgerHistory(projectRoot, filters = {}) {
     const records = [];
     let skipped = 0;
-    for await (const record of streamDecisionLedgerRecords(projectRoot)) {
+    for await (const record of streamDecisionLedgerRecords(projectRoot, filters.includeArchives)) {
         if (!record) {
             skipped += 1;
             continue;
@@ -897,7 +1093,7 @@ export async function decisionLedgerStats(projectRoot, filters = {}) {
     const weights = decisionSavingsWeights(config?.decision?.ask);
     const groups = new Map();
     let skipped = 0;
-    for await (const record of streamDecisionLedgerRecords(projectRoot)) {
+    for await (const record of streamDecisionLedgerRecords(projectRoot, filters.includeArchives)) {
         if (!record) {
             skipped += 1;
             continue;