@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/sessions/policy.js

@@ -27,7 +27,9 @@ export async function authorizeSourceFile(input) {
         throw new SessionContractError('SOURCE_NOT_REGULAR_FILE', 'session source must be a regular file');
     }
     if (input.maxBytes !== undefined && stat.size > input.maxBytes) {
-        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'session source exceeds the authorized byte limit');
+        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'session source exceeds the authorized byte limit', {
+            limit: 'maxBytes', configured: input.maxBytes, observed: stat.size,
+        });
     }
     return {
         canonicalPath,
@@ -54,21 +56,62 @@ async function safeRealpath(path, root = false) {
         throw new SessionContractError('SOURCE_NOT_AUTHORIZED', root ? 'an authorized source root is inaccessible' : 'selected session source is inaccessible');
     }
 }
+// Newline gaps are bounded and each repetition consumes a line break, keeping
+// indentation scans disjoint even on large malformed records (#3273, #3404).
+const VALUE_GAP = /[ \t]*(?:\r?\n[ \t]*){0,2}/.source;
+const NEXT_LINE_GAP = /[ \t]*(?:\r?\n[ \t]*){1,2}/.source;
+const QUOTED_VALUE = /"(?:\\[^\r\n]|[^"\\\r\n])+"|'(?:\\[^\r\n]|[^'\\\r\n])+'|`(?!`)(?:\\[^\r\n]|[^`\\\r\n])+`(?!`)/.source;
+const GENERATED_VALUE = /(?=[A-Za-z0-9._~+/=-]*[0-9])(?=[A-Za-z0-9._~+/=-]*[A-Za-z])[A-Za-z0-9._~+/=-]{20,}/.source;
+function assignmentPattern(key, separator, sameLineValue) {
+    // Only the next-line branch needs stronger evidence: quoted text or a long
+    // generated value. In particular, YAML lists and Markdown fences are prose.
+    return new RegExp(`\\b${key}[ \\t]*${separator}(?:${NEXT_LINE_GAP}(?:${QUOTED_VALUE}|${GENERATED_VALUE})|[ \\t]*(?:${QUOTED_VALUE}|${sameLineValue}))`, 'gi');
+}
+// Ambiguous token components are bounded; whitespace and key blocks use disjoint scans.
 const SECRET_PATTERNS = [
-    ['private-key', /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g],
-    ['bearer-token', /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/gi],
-    ['authorization', /\bAuthorization\s*:\s*[^\r\n]+/gi],
-    ['cookie', /\b(?:Cookie|Set-Cookie)\s*:\s*[^\r\n]+/gi],
-    ['credential', /\b(?:api[_-]?key|token|password|secret)\s*(?:[:=]|\s)\s*["']?[^\s"',;]{6,}/gi],
-    ['provider-token', /\b(?:sk-(?:proj-)?|gh[pousr]_|github_pat_|xox[baprs]-|AKIA)[A-Za-z0-9._~+/=-]{8,}\b/g],
+    ['bearer-token', new RegExp(`\\bBearer(?:[ \\t]+|${NEXT_LINE_GAP})(?:${QUOTED_VALUE}|\\\\"[A-Za-z0-9._~+/=-]{12,}\\\\"|[A-Za-z0-9._~+/=-]{12,})`, 'gi')],
+    ['authorization', new RegExp(`\\bAuthorization[ \\t]*:${VALUE_GAP}[^\\s][^\\r\\n]*`, 'gi')],
+    ['cookie', new RegExp(`\\b(?:Cookie|Set-Cookie)[ \\t]*:${VALUE_GAP}[^\\s][^\\r\\n]*`, 'gi')],
+    ['environment-assignment', assignmentPattern('(?:AWS_SECRET_ACCESS_KEY|[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY))', '=', /[^\s]+/.source)],
+    ['credential', assignmentPattern('(?:api[_-]?key|token|password|secret)', '[:=]', /["'`]?[^\s"'`,;]{6,}/.source)],
+    ['credential', /^[ \t]*password[ \t]+[^\s]+[ \t]*$/gim],
+    // Space-separated values only when they look generated (20+ chars, letters and digits), so prose stays.
+    ['credential', new RegExp(`\\b(?:api[_-]?key|token|secret)[ \\t]+${GENERATED_VALUE}`, 'gi')],
+    ['provider-token', /\b(?:sk-(?:ant-|proj-)?|[sr]k_(?:live|test)_|gh[pousr]_|github_pat_|glpat-|xai-|npm_|hf_|xox[baprs]-|AKIA|AIza)[A-Za-z0-9._~+/=-]{8,}/g],
+    ['provider-token', /https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+/g],
     ['connection-string', /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^\s]+/gi],
-    ['credential-url', /\bhttps?:\/\/[^/\s:@]+:[^/\s@]+@[^\s]+/gi],
-    ['environment-assignment', /\b[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY)\s*=\s*(?:"[^"]+"|'[^']+'|[^\s]+)/g],
+    ['credential-url', new RegExp(`\\bhttps?://${VALUE_GAP}[^/\\s:@]+:${VALUE_GAP}(?:${QUOTED_VALUE}|[^/\\s@]+)@${VALUE_GAP}[^\\s"'\x60<>\\\\]+`, 'gi')],
     ['fixture-credential', /\bredaction-canary-[A-Za-z0-9_-]+\b/gi],
-    ['email', /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi],
+    ['email', /\b[A-Z0-9._%+-]{1,64}@[A-Z0-9.-]{1,253}\.[A-Z]{2,63}\b/gi],
 ];
+function redactJwts(input, mark) {
+    // Consume even incomplete candidates. Retrying at each inner `eyJ` in an
+    // unterminated segment would repeatedly scan the remainder of a large record.
+    return input.replace(/\beyJ[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+){0,2}/g, (candidate) => {
+        const parts = candidate.split('.');
+        return parts.length === 3 && parts[0].length >= 8 && parts[1].length >= 2 && parts[2].length >= 8
+            ? mark('provider-token') : candidate;
+    });
+}
+const PRIVATE_KEY_BEGIN = /-----BEGIN ((?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED) )?PRIVATE KEY|PGP PRIVATE KEY BLOCK)-----/g;
+function redactPrivateKeys(input, mark) {
+    const parts = [];
+    let cursor = 0;
+    PRIVATE_KEY_BEGIN.lastIndex = 0;
+    let match;
+    while ((match = PRIVATE_KEY_BEGIN.exec(input))) {
+        parts.push(input.slice(cursor, match.index), mark('private-key'));
+        const endMarker = `-----END ${match[1]}-----`;
+        const end = input.indexOf(endMarker, PRIVATE_KEY_BEGIN.lastIndex);
+        // An unfinished key block is sensitive through the end of the record.
+        cursor = end < 0 ? input.length : end + endMarker.length;
+        PRIVATE_KEY_BEGIN.lastIndex = cursor;
+    }
+    parts.push(input.slice(cursor));
+    return parts.join('');
+}
 const SENSITIVE_KEY = /(?:authorization|auth[_-]?header|cookie|credential|password|passwd|secret|token|api[_-]?key|private[_-]?key|connection[_-]?string)/i;
-const CONTENT_KEY = /(?:^|[_-])(?:text|content|prompt|command|arguments?|args|result|output|body|request|response|source|code|query)(?:$|[_-])/i;
+const CONTENT_KEY = /(?:^|[_-])(?:data|text|content|prompt|command|arguments?|args|result|output|body|request|response|source|code|query)(?:$|[_-])/i;
 const PATH_KEY = /(?:^|[_-])(?:path|cwd|directory|filename|file)(?:$|[_-])/i;
 const SAFE_STRING_KEY = /(?:^|[_-])(?:id|kind|type|role|status|state|lifecycle|reason|name|product|provider|version|schema|model|format|class|mode|event|operation|tool|method|language|scope|consistency|disposition|phase|visibility|protocol|category|classification|decision|capability|permission|transition|hash|digest)(?:$|[_-])/i;
 const CONTROL_CHARACTERS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
@@ -103,23 +146,28 @@ export function sanitizeNativeExtensions(input, overrides = {}) {
             return marker('depth-limit');
         if (value === null || typeof value === 'boolean' || typeof value === 'number')
             return value;
+        if (typeof value === 'string' && /^\[REDACTED:[a-z-]+\]$/.test(value))
+            return value;
+        if (SENSITIVE_KEY.test(classifiedKey))
+            return marker('sensitive-field');
+        if (CONTENT_KEY.test(classifiedKey))
+            return marker('content');
+        if (PATH_KEY.test(classifiedKey))
+            return marker('path');
         if (typeof value === 'bigint')
             return String(value);
         if (typeof value !== 'string' && typeof value !== 'object') {
             return marker('unsupported-value');
         }
         if (typeof value === 'string') {
-            if (SENSITIVE_KEY.test(classifiedKey))
-                return marker('sensitive-field');
-            if (CONTENT_KEY.test(classifiedKey))
-                return marker('content');
-            if (PATH_KEY.test(classifiedKey))
-                return marker('path');
             if (Buffer.byteLength(value) > limits.maxStringBytes)
                 return marker('string-limit');
             const redacted = redactSessionText(value);
             for (const classification of redacted.classes)
                 classes.add(classification);
+            for (const [classification, count] of Object.entries(redacted.decisions)) {
+                decisions[classification] = (decisions[classification] ?? 0) + count;
+            }
             if (redacted.classes.length) {
                 decisions['classified-value'] = (decisions['classified-value'] ?? 0) + 1;
                 return redacted.text.replace(CONTROL_CHARACTERS, ' ');
@@ -142,8 +190,15 @@ export function sanitizeNativeExtensions(input, overrides = {}) {
             const output = {};
             const entries = Object.entries(value);
             for (const [childKey, childValue] of entries.slice(0, limits.maxObjectKeys)) {
-                output[childKey.replace(/\r?\n/g, ' ').replace(CONTROL_CHARACTERS, '')] =
-                    visit(childValue, childKey, depth + 1);
+                const safeKey = redactSessionText(childKey);
+                for (const classification of safeKey.classes)
+                    classes.add(classification);
+                for (const [classification, count] of Object.entries(safeKey.decisions)) {
+                    decisions[classification] = (decisions[classification] ?? 0) + count;
+                }
+                Object.defineProperty(output, safeKey.text.replace(/\r?\n/g, ' ').replace(CONTROL_CHARACTERS, ''), {
+                    value: visit(childValue, childKey, depth + 1), enumerable: true, configurable: true, writable: true,
+                });
             }
             if (entries.length > limits.maxObjectKeys)
                 output.__truncated__ = marker('object-key-limit');
@@ -165,15 +220,79 @@ export function sanitizeNativeExtensions(input, overrides = {}) {
     };
 }
 export function redactSessionText(input) {
-    const classes = new Set();
-    let text = input;
+    const decisions = {};
+    const mark = (classification) => {
+        decisions[classification] = (decisions[classification] ?? 0) + 1;
+        return `[REDACTED:${classification}]`;
+    };
+    let text = redactJwts(redactPrivateKeys(input, mark), mark);
     for (const [classification, pattern] of SECRET_PATTERNS) {
-        text = text.replace(pattern, () => {
-            classes.add(classification);
-            return `[REDACTED:${classification}]`;
-        });
+        // Every email match requires an at-sign. Avoid costly bounded local-part
+        // backtracking on large records containing only email-shaped near matches.
+        if (classification === 'email' && !text.includes('@'))
+            continue;
+        text = text.replace(pattern, () => mark(classification));
+    }
+    const classes = Object.keys(decisions).sort();
+    return { text, sensitivity: classes.length ? 'sensitive' : 'none', classes, decisions };
+}
+/** Redact every string, including object keys, without changing canonical field shapes. */
+export function redactSessionValue(input) {
+    const decisions = {};
+    const active = new WeakSet();
+    const text = (value) => {
+        const result = redactSessionText(value);
+        for (const [key, count] of Object.entries(result.decisions)) {
+            decisions[key] = (decisions[key] ?? 0) + count;
+        }
+        return result.text;
+    };
+    const visit = (value, depth) => {
+        if (typeof value === 'string')
+            return text(value);
+        if (!value || typeof value !== 'object')
+            return value;
+        if (depth > 64 || active.has(value))
+            return '[REDACTED:structure-limit]';
+        active.add(value);
+        try {
+            return Array.isArray(value)
+                ? value.map((item) => visit(item, depth + 1))
+                : Object.fromEntries(Object.entries(value).map(([key, item]) => [text(key), visit(item, depth + 1)]));
+        }
+        finally {
+            active.delete(value);
+        }
+    };
+    const value = visit(input, 0);
+    return { value, classes: Object.keys(decisions).sort(), decisions };
+}
+/** Shared import boundary for canonical text, metadata and bounded native attributes. */
+export function sanitizeSessionEvent(input) {
+    const native = sanitizeNativeExtensions(input.extensions);
+    const result = redactSessionValue({ ...input, extensions: native.value });
+    const event = result.value;
+    const classes = [...new Set([...event.sensitivity.classes, ...native.classes, ...result.classes])].sort();
+    event.sensitivity = {
+        classification: classes.length ? 'sensitive' : 'none', classes,
+    };
+    // Counts contain classifications only, never matched input or excerpts.
+    const prior = event.extensions['native.redaction'];
+    const counts = {};
+    for (const item of Array.isArray(prior?.decisions) ? prior.decisions : []) {
+        if (item && typeof item.classification === 'string' && Number.isSafeInteger(item.count) && item.count >= 0) {
+            counts[item.classification] = item.count;
+        }
+    }
+    for (const decisions of [native.decisions, result.decisions]) {
+        for (const [key, count] of Object.entries(decisions)) {
+            counts[key] = (counts[key] ?? 0) + count;
+        }
     }
-    return { text, sensitivity: classes.size ? 'sensitive' : 'none', classes: [...classes].sort() };
+    event.extensions['native.redaction'] = {
+        decisions: Object.entries(counts).map(([classification, count]) => ({ classification, count })),
+    };
+    return event;
 }
 export function contentFreeAuditEvent(event) {
     return Object.freeze({ ...event, counts: { ...event.counts } });

package/dist/src/sessions/readers.js

@@ -1,15 +1,82 @@
 import { createHash } from 'node:crypto';
-import { createReadStream } from 'node:fs';
 import { open, readFile } from 'node:fs/promises';
-import { createInterface } from 'node:readline';
-import { SessionContractError } from './contracts.js';
+import { assertSessionResourceLimit, schemaIssueDetail, SessionContractError } from './contracts.js';
+import { assertImportByteLimit, DEFAULT_IMPORT_BYTE_LIMITS } from './import-limits.js';
 import { authorizeSourceFile } from './policy.js';
 export const DEFAULT_READER_LIMITS = Object.freeze({
     maxRecords: 1_000_000,
-    maxRecordBytes: 8 * 1024 * 1024,
-    maxTotalBytes: 1024 * 1024 * 1024,
+    ...DEFAULT_IMPORT_BYTE_LIMITS,
     maxNestingDepth: 64,
 });
+const JSONL_READ_CHUNK_BYTES = 1024 * 1024;
+export async function* streamJsonLines(path, options = {}) {
+    const startOffset = options.start ?? 0;
+    if (!Number.isSafeInteger(startOffset) || startOffset < 0)
+        throw new RangeError('start must be a nonnegative safe integer');
+    if (options.end !== undefined && options.end !== Infinity
+        && (!Number.isSafeInteger(options.end) || options.end < 0))
+        throw new RangeError('end must be a nonnegative safe integer or Infinity');
+    if (options.end !== undefined && options.end < startOffset)
+        throw new RangeError('end must not precede start');
+    // Reuse raw storage across the full source instead of allocating a new MiB
+    // buffer per read. Only incomplete line fragments outlive the current read.
+    const storage = Buffer.allocUnsafe(JSONL_READ_CHUNK_BYTES);
+    const input = await open(path, 'r');
+    let position = startOffset;
+    let parts = [];
+    let length = 0;
+    let total = 0;
+    try {
+        while (options.end === undefined || position <= options.end) {
+            const wanted = options.end === undefined ? storage.length
+                : Math.min(storage.length, options.end - position + 1);
+            const { bytesRead } = await input.read(storage, 0, wanted, position);
+            if (bytesRead === 0)
+                break;
+            position += bytesRead;
+            const buffer = storage.subarray(0, bytesRead);
+            let start = 0;
+            while (start < buffer.length) {
+                const newline = buffer.indexOf(10, start);
+                const end = newline === -1 ? buffer.length : newline + 1;
+                const segment = buffer.subarray(start, end);
+                if (options.limits) {
+                    const recordBytes = length + segment.length;
+                    const totalBytes = (options.start ?? 0) + total + segment.length;
+                    // For an incomplete segment, report the first byte known to exceed
+                    // the limit instead of making diagnostics depend on read-buffer size.
+                    assertImportByteLimit('maxRecordBytes', options.limits, newline === -1 && recordBytes > options.limits.maxRecordBytes
+                        ? options.limits.maxRecordBytes + 1 : recordBytes);
+                    assertImportByteLimit('maxTotalBytes', options.limits, newline === -1 && options.limits.maxTotalBytes !== 0 && totalBytes > options.limits.maxTotalBytes
+                        ? options.limits.maxTotalBytes + 1 : totalBytes);
+                }
+                // Bound the raw bytes before copying or decoding a record. Only LF
+                // separates records; CRLF and Unicode separators remain JSON input.
+                parts.push(segment);
+                length += segment.length;
+                total += segment.length;
+                start = end;
+                if (newline !== -1) {
+                    const line = (parts.length === 1 ? parts[0] : Buffer.concat(parts, length)).toString('utf8');
+                    const byteLength = length;
+                    parts = [];
+                    length = 0;
+                    yield { line, byteLength };
+                }
+            }
+            // Earlier fragments already own their bytes. The last fragment is the
+            // only view into storage, which the next read will overwrite.
+            if (parts.length > 0)
+                parts[parts.length - 1] = Buffer.from(parts[parts.length - 1]);
+        }
+        if (length > 0) {
+            yield { line: (parts.length === 1 ? parts[0] : Buffer.concat(parts, length)).toString('utf8'), byteLength: length };
+        }
+    }
+    finally {
+        await input.close();
+    }
+}
 export async function readBoundedJsonLines(authorization, options) {
     const stream = await streamBoundedJsonLines(authorization, options);
     const records = [];
@@ -28,50 +95,36 @@ export async function streamBoundedJsonLines(authorization, options) {
     const limits = { ...DEFAULT_READER_LIMITS, ...options.limits };
     const start = parseCursor(options.cursor);
     if (start > allowed.size)
-        throw new SessionContractError('SCHEMA_DRIFT', 'reader cursor is beyond source size');
+        throw new SessionContractError('SCHEMA_DRIFT', 'reader cursor is beyond source size', schemaIssueDetail('cursor'));
     let offset = start;
     let total = 0;
     let count = 0;
     let incompleteTail = false;
     const iterate = async function* () {
-        const input = createReadStream(allowed.canonicalPath, { start, encoding: 'utf8' });
-        const lines = createInterface({ input, crlfDelay: Infinity });
-        try {
-            for await (const line of lines) {
-                const bytes = Buffer.byteLength(line) + 1;
-                if (bytes > limits.maxRecordBytes || total + bytes > limits.maxTotalBytes
-                    || count + 1 > limits.maxRecords) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'bounded session reader limit exceeded');
-                }
-                if (line.trim() === '') {
-                    offset += bytes;
-                    total += bytes;
-                    continue;
-                }
-                let value;
-                try {
-                    value = JSON.parse(line);
-                }
-                catch {
-                    if (options.consistency === 'provisional') {
-                        incompleteTail = true;
-                        break;
-                    }
-                    throw new SessionContractError('SCHEMA_DRIFT', 'malformed JSONL record in consistent source');
-                }
-                if (jsonDepth(value) > limits.maxNestingDepth) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'JSON nesting depth exceeds reader limit');
-                }
-                const record = { value, sequence: count, byteOffset: offset, byteLength: bytes };
-                count += 1;
+        for await (const { line, byteLength: bytes } of streamJsonLines(allowed.canonicalPath, { start, limits })) {
+            assertSessionResourceLimit('maxRecords', limits.maxRecords, count + 1);
+            if (line.trim() === '') {
                 offset += bytes;
                 total += bytes;
-                yield record;
+                continue;
             }
-        }
-        finally {
-            lines.close();
-            input.destroy();
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                if (options.consistency === 'provisional') {
+                    incompleteTail = true;
+                    break;
+                }
+                throw new SessionContractError('SCHEMA_DRIFT', 'malformed JSONL record in consistent source', schemaIssueDetail('<root>', 'invalid_json'));
+            }
+            assertSessionResourceLimit('maxNestingDepth', limits.maxNestingDepth, jsonDepth(value));
+            const record = { value, sequence: count, byteOffset: offset, byteLength: bytes };
+            count += 1;
+            offset += bytes;
+            total += bytes;
+            yield record;
         }
     };
     return {
@@ -83,30 +136,30 @@ export async function streamBoundedJsonLines(authorization, options) {
         [Symbol.asyncIterator]: iterate,
     };
 }
+// Single-document JSON and text exports cannot be incrementally normalized.
+export const MAX_BUFFERED_SOURCE_BYTES = 64 * 1024 * 1024;
 export async function readBoundedJson(authorization, limitsInput) {
     const allowed = await authorizeSourceFile(authorization);
     const limits = { ...DEFAULT_READER_LIMITS, ...limitsInput };
-    if (allowed.size > limits.maxTotalBytes || allowed.size > limits.maxRecordBytes) {
-        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'bounded JSON source limit exceeded');
-    }
+    assertImportByteLimit('maxTotalBytes', limits, allowed.size);
+    assertImportByteLimit('maxRecordBytes', limits, allowed.size);
+    assertSessionResourceLimit('maxBufferedSourceBytes', MAX_BUFFERED_SOURCE_BYTES, allowed.size);
     let value;
     try {
         value = JSON.parse(await readFile(allowed.canonicalPath, 'utf8'));
     }
     catch {
-        throw new SessionContractError('SCHEMA_DRIFT', 'malformed JSON source');
-    }
-    if (jsonDepth(value) > limits.maxNestingDepth) {
-        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'JSON nesting depth exceeds reader limit');
+        throw new SessionContractError('SCHEMA_DRIFT', 'malformed JSON source', schemaIssueDetail('<root>', 'invalid_json'));
     }
+    assertSessionResourceLimit('maxNestingDepth', limits.maxNestingDepth, jsonDepth(value));
     return { value, bytesRead: allowed.size };
 }
 export async function readBoundedText(authorization, limitsInput) {
     const allowed = await authorizeSourceFile(authorization);
     const limits = { ...DEFAULT_READER_LIMITS, ...limitsInput };
-    if (allowed.size > limits.maxTotalBytes || allowed.size > limits.maxRecordBytes) {
-        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'bounded text source limit exceeded');
-    }
+    assertImportByteLimit('maxTotalBytes', limits, allowed.size);
+    assertImportByteLimit('maxRecordBytes', limits, allowed.size);
+    assertSessionResourceLimit('maxBufferedSourceBytes', MAX_BUFFERED_SOURCE_BYTES, allowed.size);
     return {
         value: await readFile(allowed.canonicalPath, 'utf8'),
         bytesRead: allowed.size,
@@ -136,7 +189,7 @@ export async function fingerprintSourcePrefix(authorization, length, skipPrefixB
     const allowed = await authorizeSourceFile(authorization);
     if (!Number.isSafeInteger(length) || length < 0 || length > allowed.size
         || !Number.isSafeInteger(skipPrefixBytes) || skipPrefixBytes < 0 || skipPrefixBytes > allowed.size) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'checkpoint source position is beyond the current source size');
+        throw new SessionContractError('SCHEMA_DRIFT', 'checkpoint source position is beyond the current source size', schemaIssueDetail('cursor'));
     }
     const handle = await open(allowed.canonicalPath, 'r');
     const hash = createHash('sha256');
@@ -165,7 +218,7 @@ function parseCursor(cursor) {
     if (cursor === undefined || cursor === '')
         return 0;
     if (!/^\d+$/.test(cursor))
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid reader cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid reader cursor', schemaIssueDetail('cursor'));
     return Number(cursor);
 }
 function jsonDepth(value, depth = 0) {

package/dist/src/sessions/refresh.js

@@ -0,0 +1,105 @@
+import { existsSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { requireFeaturePackage } from '../features/runtime.js';
+import { readAiwgConfig } from '../config/aiwg-config.js';
+import { createSessionAdapterRegistry } from './adapter-registry.js';
+import { resolveImportExclusions } from './import-exclusions.js';
+import { resolveImportLimits } from './import-limits.js';
+import { acquireImportLease } from './import-lease.js';
+import { SessionRepository } from './repository.js';
+import { importDiscoveryManifest } from './batch-import.js';
+import { defaultDiscoveryManifestPath, discoverWorkspaceHistories, readDiscoveryManifest, writeDiscoveryManifest, } from './workspace-discovery.js';
+export function sessionRefreshAvailable() {
+    try {
+        const Database = requireFeaturePackage('better-sqlite3');
+        const probe = new Database(':memory:');
+        probe.close();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Refresh current configured scope within saved provider root grants. */
+export async function refreshSessionCatalog(workspace, full, waitMs, signal, workspaceAliases = [], flags = {}) {
+    const canonicalWorkspace = realpathSync(workspace);
+    const config = await readAiwgConfig(canonicalWorkspace);
+    const limits = resolveImportLimits(config?.sessions?.import, flags);
+    const exclude = resolveImportExclusions(config?.sessions?.import, flags.exclude);
+    const database = path.join(workspace, '.aiwg/sessions/catalog.sqlite');
+    const manifests = [];
+    if (!full) {
+        const paths = new Set([
+            defaultDiscoveryManifestPath(canonicalWorkspace),
+            ...(config?.sessions?.discovery_manifests ?? []).map(file => path.resolve(canonicalWorkspace, file)),
+        ]);
+        let found = false;
+        for (const manifestPath of paths) {
+            if (!existsSync(manifestPath))
+                continue;
+            const previous = await readDiscoveryManifest(manifestPath);
+            if (previous.workspaceId !== canonicalWorkspace)
+                throw new Error('discovery manifest workspace mismatch');
+            found = true;
+            const authorizedRoots = previous.authorizedRoots ?? {};
+            if (!previous.authorizedRoots) {
+                for (const source of previous.sources) {
+                    const roots = authorizedRoots[source.provider] ??= [];
+                    if (!roots.includes(source.authorizedRoot))
+                        roots.push(source.authorizedRoot);
+                }
+            }
+            const providers = Object.keys(authorizedRoots)
+                .filter(provider => authorizedRoots[provider]?.length);
+            if (!providers.length)
+                continue;
+            const manifest = await discoverWorkspaceHistories({
+                workspace: canonicalWorkspace,
+                workspaceAliases: [workspace, ...workspaceAliases],
+                refreshFrom: { ...previous, authorizedRoots },
+                registry: createSessionAdapterRegistry(limits),
+                exclude,
+                knownSources: previous.sources,
+            });
+            manifests.push({ path: manifestPath, manifest });
+        }
+        if (!found)
+            return 'no authorized discovery manifest';
+        if (!manifests.length)
+            return 'no authorized provider roots';
+    }
+    const lease = await acquireImportLease(database, `index-refresh-${process.pid}`, { waitMs });
+    try {
+        const repository = new SessionRepository(database);
+        try {
+            if (full)
+                repository.reindex();
+            else {
+                const receipts = [];
+                for (const entry of manifests) {
+                    const prior = repository.getBatchImportRunForManifest(entry.manifest.manifestId, canonicalWorkspace);
+                    if (prior?.status === 'complete')
+                        continue;
+                    // Persist the exact discovered batch before its confirmed import.
+                    await writeDiscoveryManifest(entry.path, entry.manifest);
+                    const receipt = await importDiscoveryManifest({ manifest: entry.manifest, repository, signal, limits, exclude });
+                    if (receipt.totals.pending) {
+                        throw new Error(`session import incomplete: ${receipt.totals.rejected} rejected, ${receipt.totals.pending} pending`);
+                    }
+                    receipts.push(receipt);
+                }
+                if (!receipts.length)
+                    return 'unchanged';
+                return receipts.length === 1 ? receipts[0] : receipts;
+            }
+        }
+        finally {
+            repository.close();
+        }
+    }
+    finally {
+        await lease.release();
+    }
+    return undefined;
+}
+//# sourceMappingURL=refresh.js.map