@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/sessions/contracts.js

@@ -1,11 +1,47 @@
 import { createHash } from 'node:crypto';
 import { z } from 'zod';
+import { redactSessionText, redactSessionValue } from './policy.js';
 export const SESSION_CONTRACT_VERSION = '1.0.0';
 export const SESSION_PROVIDER_IDS = [
     'claude', 'codex', 'copilot', 'cursor', 'factory', 'hermes',
     'opencode', 'openclaw', 'openhuman', 'grokbot', 'grok-build', 'pi', 'omp', 'deepseek-harness', 'warp', 'devin-desktop', 'muse', 'generic',
 ];
 export const SessionProviderIdSchema = z.enum(SESSION_PROVIDER_IDS);
+// Expected scope must also represent providers unknown to this runtime.
+export const ExpectedSessionProviderSchema = z.string().regex(/^[a-z][a-z0-9-]*$/);
+export const SessionRuntimeIdentitySchema = z.object({
+    packageName: z.string(),
+    version: z.string(),
+    packageRoot: z.string(),
+    executable: z.string(),
+    nodeVersion: z.string(),
+    installationMethod: z.string(),
+    installationState: z.enum(['aligned', 'mismatch', 'stale', 'unrecorded', 'unknown']),
+    canonicalRoot: z.string().nullable(),
+    diagnostics: z.array(z.string()),
+});
+export const SessionCoveragePreflightSchema = z.object({
+    expectedProviders: z.array(ExpectedSessionProviderSchema).min(1),
+    expectedProviderBasis: z.enum(['explicit', 'declared-default', 'legacy']),
+    supportedProviders: z.array(ExpectedSessionProviderSchema),
+    runtime: SessionRuntimeIdentitySchema,
+    status: z.enum(['partial', 'complete']),
+    unresolvedProviders: z.array(ExpectedSessionProviderSchema),
+    ledger: z.array(z.object({
+        provider: ExpectedSessionProviderSchema,
+        disposition: z.enum([
+            'missing-adapter', 'unsupported', 'authorization-required', 'export-required',
+            'unavailable', 'no-sources', 'not-checked', 'pending-import', 'import-incomplete',
+            'scope-incomplete', 'acquired',
+        ]),
+        adapterVersion: z.string().nullable(),
+        supportedOperations: z.array(z.string()),
+        acquisitionModes: z.array(z.string()),
+        sourceCount: z.number().int().nonnegative(),
+        boundaries: z.array(z.string()),
+        remediation: z.string().nullable(),
+    })),
+});
 export const SESSION_PROVIDER_ALIASES = Object.freeze({
     windsurf: 'devin-desktop',
     dsh: 'deepseek-harness',
@@ -327,11 +363,48 @@ export function sha256(value) {
 function stableId(prefix, ...parts) {
     return `${prefix}_${createHash('sha256').update(parts.join('\0')).digest('hex')}`;
 }
+export const SessionRejectionDetailSchema = z.union([
+    z.object({ limit: z.string(), configured: z.number(), observed: z.number(),
+        setting: z.string().optional(), origin: z.enum(['flag', 'env', 'config', 'default']).optional() }),
+    z.object({ issues: z.array(z.object({ path: z.string(), code: z.string() })) }),
+]);
+export function schemaIssueDetail(path, code = 'custom') {
+    return { issues: [{ path, code }] };
+}
+export function assertSessionResourceLimit(limit, configured, observed) {
+    if (observed > configured) {
+        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'session resource limit exceeded', {
+            limit, configured, observed,
+        });
+    }
+}
+/** Extract schema locations and validator codes without messages or input values. */
+export function schemaRejectionDetail(error) {
+    const issues = [];
+    const visit = (entries) => {
+        for (const issue of entries) {
+            if (issues.length >= 20)
+                return;
+            if (issue.code === 'invalid_union') {
+                for (const branch of issue.unionErrors)
+                    visit(branch.issues);
+            }
+            else {
+                issues.push({ path: issue.path.join('.') || '<root>', code: issue.code });
+            }
+        }
+    };
+    visit(error.issues);
+    return redactSessionValue({ issues }).value;
+}
 export class SessionContractError extends Error {
     code;
-    constructor(code, message) {
-        super(message);
+    detail;
+    constructor(code, message, detail) {
+        super(redactSessionText(message).text);
         this.code = code;
+        this.detail = detail;
+        this.detail = redactSessionValue(detail).value;
         this.name = 'SessionContractError';
     }
 }

package/dist/src/sessions/coverage-preflight.js

@@ -0,0 +1,134 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findPackageRoot } from '../cli/find-package-root.js';
+import { inspectInstallation } from '../installation/manager.mjs';
+import { ExpectedSessionProviderSchema, SESSION_PROVIDER_ALIASES, SESSION_PROVIDER_IDS, SessionContractError, SessionCoveragePreflightSchema, SessionRuntimeIdentitySchema, } from './contracts.js';
+import { createSessionAdapterRegistry } from './adapter-registry.js';
+export function expectedSessionProviders(values) {
+    const providers = values.map((value) => {
+        const canonical = SESSION_PROVIDER_ALIASES[value.trim()]
+            ?? value.trim();
+        if (!ExpectedSessionProviderSchema.safeParse(canonical).success) {
+            throw new SessionContractError('INVALID_ARGUMENT', `invalid expected provider: ${value}`);
+        }
+        return canonical;
+    });
+    if (providers.length === 0) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'expected providers must not be empty');
+    }
+    return [...new Set(providers)].sort();
+}
+/** Resolve the code actually loaded, independently of cwd, AIWG_ROOT and corpus redirects. */
+export function sessionRuntimeIdentity() {
+    const packageRoot = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+    if (!packageRoot)
+        throw new SessionContractError('INVALID_ARGUMENT', 'cannot locate the running AIWG package');
+    const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+    const executable = process.argv[1] ?? process.execPath;
+    const base = {
+        packageName: pkg.name, version: pkg.version, packageRoot: realpathSync(packageRoot),
+        executable, nodeVersion: process.version,
+    };
+    try {
+        const installation = inspectInstallation({ actualRoot: packageRoot, createIfMissing: false });
+        return SessionRuntimeIdentitySchema.parse({
+            ...base,
+            installationMethod: installation.actualMethod,
+            installationState: installation.state,
+            canonicalRoot: installation.identity?.root ?? null,
+            diagnostics: [
+                ...installation.drift,
+                ...(['mismatch', 'stale'].includes(installation.state)
+                    ? ['Deliberately select a compatible runtime, inspect `aiwg installation show`, and rediscover. No automatic upgrade or installation switch is performed.'] : []),
+            ],
+        });
+    }
+    catch (error) {
+        return SessionRuntimeIdentitySchema.parse({
+            ...base, installationMethod: 'unknown', installationState: 'unknown', canonicalRoot: null,
+            diagnostics: [
+                error instanceof Error ? error.message : String(error),
+                'Inspect `aiwg installation show` and deliberately select a compatible runtime before claiming complete coverage.',
+            ],
+        });
+    }
+}
+export function coveragePreflight(options = {}) {
+    const expectedProviders = expectedSessionProviders(options.expectedProviders ?? SESSION_PROVIDER_IDS);
+    const adapters = (options.registry ?? createSessionAdapterRegistry()).list();
+    const runtime = options.runtime ?? sessionRuntimeIdentity();
+    const ledger = expectedProviders.map((provider) => {
+        const adapter = adapters.find((item) => item.provider === provider);
+        const report = options.reports?.find((item) => item.provider === provider);
+        const entry = {
+            provider, disposition: 'not-checked', adapterVersion: adapter?.adapterVersion ?? null,
+            supportedOperations: [...(adapter?.supportedOperations ?? [])],
+            acquisitionModes: [...(adapter?.acquisitionModes ?? [])],
+            sourceCount: report?.sourceCount ?? 0, boundaries: [],
+            remediation: report?.remediation ?? 'Run authorized workspace discovery or select a supported export.',
+        };
+        if (!adapter) {
+            entry.disposition = 'missing-adapter';
+            entry.remediation = `Running ${runtime.packageName} ${runtime.version} at ${runtime.packageRoot} has no ${provider} adapter. Deliberately select a compatible runtime or use an explicitly authorized supported export; no installation is switched automatically.`;
+        }
+        else if (adapter.disposition === 'unsupported' || !adapter.supportedOperations.includes('stream')) {
+            entry.disposition = 'unsupported';
+        }
+        else if (report?.reasonCode === 'SHARED_ROOT_AUTHORIZATION_REQUIRED') {
+            entry.disposition = 'authorization-required';
+        }
+        else if (report?.status === 'export-required' || !adapter.supportedOperations.includes('discover')) {
+            entry.disposition = 'export-required';
+        }
+        else if (report?.status === 'unavailable') {
+            entry.disposition = 'unavailable';
+        }
+        else if (report?.reasonCode === 'MUSE_SOURCE_INSPECTION_INCOMPLETE') {
+            entry.disposition = report.sourceCount > 0 ? 'pending-import' : 'not-checked';
+            entry.boundaries.push('Some Muse sources could not be fully inspected; see museSourceInspections in the discovery manifest.');
+            entry.remediation = report.remediation;
+        }
+        else if (report?.status === 'checked') {
+            entry.disposition = report.sourceCount > 0 ? 'pending-import' : 'no-sources';
+            entry.remediation = report.sourceCount > 0
+                ? 'Import the exact authorized manifest and inspect source dispositions.'
+                : 'Zero matching sources does not establish no activity; verify scope, authorization and export availability.';
+        }
+        if (provider === 'muse') {
+            entry.boundaries.push('Native discovery includes parent session.jsonl logs only; nested subagent logs and approval-review scope are not established.');
+        }
+        return entry;
+    });
+    return SessionCoveragePreflightSchema.parse({
+        expectedProviders,
+        expectedProviderBasis: options.expectedProviderBasis ?? (options.expectedProviders ? 'explicit' : 'declared-default'),
+        supportedProviders: adapters.map((adapter) => adapter.provider), runtime,
+        status: 'partial', unresolvedProviders: expectedProviders, ledger,
+    });
+}
+export function reconcileCoveragePreflight(preflight, sources) {
+    const accepted = new Set(['committed', 'duplicate', 'previously-committed']);
+    const ledger = preflight.ledger.map((entry) => {
+        if (!['pending-import', 'import-incomplete', 'scope-incomplete', 'acquired'].includes(entry.disposition))
+            return entry;
+        const selected = sources.filter((source) => source.provider === entry.provider);
+        const imported = selected.length === entry.sourceCount && selected.length > 0
+            && selected.every((source) => source.status === 'excluded' || (accepted.has(source.status) && source.eventsAccepted > 0));
+        return {
+            ...entry,
+            disposition: !imported ? 'import-incomplete'
+                : entry.boundaries.length > 0 ? 'scope-incomplete' : 'acquired',
+            remediation: !imported ? 'Resolve pending, rejected, skipped or empty imports before claiming acquisition coverage.'
+                : entry.boundaries.length > 0 ? 'Declare the parent-only boundary and separately authorize supported exports for omitted scope.' : null,
+        };
+    });
+    const unresolvedProviders = ledger.filter((entry) => entry.disposition !== 'acquired').map((entry) => entry.provider);
+    const runtimeGap = ['mismatch', 'stale', 'unknown'].includes(preflight.runtime.installationState);
+    return {
+        ...preflight, ledger, unresolvedProviders,
+        status: unresolvedProviders.length > 0 || runtimeGap || preflight.expectedProviderBasis !== 'explicit'
+            ? 'partial' : 'complete',
+    };
+}
+//# sourceMappingURL=coverage-preflight.js.map

package/dist/src/sessions/discovery.js

@@ -1,6 +1,9 @@
 import { SessionContractError, assertSessionProviderId, } from './contracts.js';
 export class SessionSourceAdapterRegistry {
     adapters = new Map();
+    list() {
+        return [...this.adapters.values()].sort((a, b) => a.provider.localeCompare(b.provider));
+    }
     register(adapter) {
         const provider = assertSessionProviderId(adapter.provider);
         if (this.adapters.has(provider))

package/dist/src/sessions/export-plan.js

@@ -13,6 +13,7 @@ import { SessionContractError } from './contracts.js';
 import { buildSessionAiwgFortemiIndexExport, SESSION_EXPORT_INDEX_SCHEMA_VERSION, } from './fortemi-export-mapping.js';
 import { discoverSessionOutputCandidates } from './output-lineage.js';
 import { FilesystemDerivedOutputIndex } from './output-registration.js';
+import { redactSessionValue } from './policy.js';
 export const SESSION_EXPORT_PLAN_SCHEMA_VERSION = '1.1.0';
 function eventDigestSummary(events) {
     const hash = createHash('sha256');
@@ -43,7 +44,7 @@ function localEventAttachment(event, projectRoot) {
         && value.dataBytes.every((item) => Number.isInteger(item) && Number(item) >= 0 && Number(item) <= 255)) {
         return { filename, mediaType, bytes: Uint8Array.from(value.dataBytes) };
     }
-    if (typeof value.dataUrl === 'string') {
+    if (typeof value.dataUrl === 'string' && !value.dataUrl.startsWith('[REDACTED:')) {
         const match = /^data:([^;,]*)(;base64)?,(.*)$/s.exec(value.dataUrl);
         if (!match)
             throw new SessionContractError('MALFORMED_SOURCE', `invalid data URL attachment: ${event.eventId}`);
@@ -52,7 +53,7 @@ function localEventAttachment(event, projectRoot) {
             : Buffer.from(decodeURIComponent(match[3]), 'utf8');
         return { filename, mediaType: match[1] || mediaType, bytes };
     }
-    if (typeof value.fileUrl === 'string') {
+    if (typeof value.fileUrl === 'string' && !value.fileUrl.startsWith('[REDACTED:')) {
         if (!projectRoot)
             throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'project root is required for file attachments');
         const root = realpathSync(projectRoot);
@@ -157,7 +158,7 @@ export function buildSessionExportPlan(repository, options) {
             sampleRecordIds: index.items.slice(0, sampleSize).map((item) => item.id),
         },
     };
-    return { plan, sessions, eventsBySessionId };
+    return { plan: redactSessionValue(plan).value, sessions, eventsBySessionId };
 }
 /**
  * Re-selects the plan's sessions from the repository and compares digests

package/dist/src/sessions/grok-build-cli.js

@@ -1,7 +1,7 @@
 import { execFile as execFileCallback } from 'node:child_process';
 import { constants as fsConstants } from 'node:fs';
-import { lstat, open, realpath, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, parse, resolve } from 'node:path';
+import { access, lstat, open, realpath, stat, writeFile } from 'node:fs/promises';
+import { delimiter, dirname, isAbsolute, join, parse, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { resolveGrokHomeResult } from '../providers/grok-build-paths.js';
 import { SessionContractError } from './contracts.js';
@@ -115,10 +115,10 @@ async function runGrok(options, args) {
     if (!home.ok)
         throw new SessionContractError('SOURCE_NOT_AUTHORIZED', home.message);
     await rejectSymlinkComponents(home.path);
-    const binary = options.binary ?? 'grok';
-    if (binary !== 'grok' && !isAbsolute(binary)) {
+    if (options.binary !== undefined && !isAbsolute(options.binary)) {
         throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build binary override must be absolute');
     }
+    const binary = options.binary ?? await defaultGrokBinary(env, home.path);
     const runner = options.runner ?? execFile;
     try {
         const result = await runner(binary, ['--no-auto-update', ...args], {
@@ -136,7 +136,69 @@ async function runGrok(options, args) {
         if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
             throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Build CLI output exceeds 2 MB');
         }
-        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build CLI failed or timed out; check the local `grok` installation, authentication, and selected workspace.');
+        throw grokFailure(error, binary);
+    }
+}
+/**
+ * Map a failed `grok` launch to an actionable error (#2968). stderr is never
+ * echoed: Grok Build diagnostics can carry session content.
+ */
+function grokFailure(error, binary) {
+    const name = binary === 'grok' ? '`grok`' : `\`${binary}\``;
+    if (error.code === 'ENOENT') {
+        return new SessionContractError('UNSUPPORTED_OPERATION', `Grok Build CLI not found: ${name} is not on PATH and no $GROK_HOME/bin/grok was found; `
+            + 'pass --grok-bin <absolute path> or add the Grok Build bin directory to PATH.');
+    }
+    if (error.code === 'EACCES') {
+        return new SessionContractError('UNSUPPORTED_OPERATION', `Grok Build CLI ${name} is not executable; check its permissions or pass --grok-bin <absolute path>.`);
+    }
+    if (error.killed || error.signal) {
+        return new SessionContractError('UNSUPPORTED_OPERATION', `Grok Build CLI ${name} timed out after ${TIMEOUT_MS / 1000}s; check that it is authenticated `
+            + 'and does not prompt for input.');
+    }
+    if (typeof error.code === 'number') {
+        return new SessionContractError('UNSUPPORTED_OPERATION', `Grok Build CLI ${name} exited with code ${error.code}; run \`grok sessions list\` in the selected `
+            + 'workspace to check authentication and installation.');
+    }
+    return new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build CLI failed; check the local `grok` installation, authentication, and selected workspace.');
+}
+/**
+ * Resolve `grok` from PATH, else the installer's `$GROK_HOME/bin/grok` (#2968).
+ * The installer links `bin/grok` to a versioned binary beside it, so that one
+ * link is followed only when it resolves to a regular file inside `bin`.
+ */
+async function defaultGrokBinary(env, grokHome) {
+    for (const directory of (env.PATH ?? '').split(delimiter)) {
+        if (!directory || !isAbsolute(directory))
+            continue;
+        if (await isExecutableFile(join(directory, 'grok')))
+            return 'grok';
+    }
+    const binDirectory = join(grokHome, 'bin');
+    try {
+        await rejectSymlinkComponents(binDirectory);
+        const canonicalBin = await realpath(binDirectory);
+        const target = await realpath(join(binDirectory, 'grok'));
+        if (dirname(target) !== canonicalBin || !(await isExecutableFile(target)))
+            return 'grok';
+        return target;
+    }
+    catch (error) {
+        if (error instanceof SessionContractError)
+            throw error;
+        return 'grok';
+    }
+}
+async function isExecutableFile(path) {
+    try {
+        const item = await stat(path);
+        if (!item.isFile())
+            return false;
+        await access(path, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
     }
 }
 function parseSessionIds(stdout, mode) {

package/dist/src/sessions/import-exclusions.js

@@ -0,0 +1,72 @@
+import { homedir } from 'node:os';
+import { basename, dirname, extname, isAbsolute } from 'node:path';
+import { SessionContractError } from './contracts.js';
+import { grokbotConversationIdFromLocator } from './adapters/grokbot-locator.js';
+export function validateImportExclusions(value) {
+    if (!Array.isArray(value) || !value.every(entry => typeof entry === 'string' && entry.trim().length > 0)) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'sessions.import.exclude must be an array of non-empty strings');
+    }
+    for (const entry of value) {
+        if (!isAbsolute(entry) && entry !== '~' && !entry.startsWith('~/') && /[/*?\\~]/.test(entry)) {
+            throw new SessionContractError('INVALID_ARGUMENT', 'sessions.import.exclude path globs must be absolute or ~/ prefixed');
+        }
+    }
+}
+export function resolveImportExclusions(config, flags = [], env = process.env) {
+    const configured = config?.exclude === undefined ? [] : config.exclude;
+    validateImportExclusions(configured);
+    const entries = [...configured, ...(env.AIWG_SESSIONS_IMPORT_EXCLUDE === undefined
+            ? [] : env.AIWG_SESSIONS_IMPORT_EXCLUDE.split(',').map(entry => entry.trim())), ...flags];
+    validateImportExclusions(entries);
+    return [...new Set(entries)];
+}
+/** Use only discovery metadata and locator names; never inspect source content. */
+export function matchImportExclusion(source, entries) {
+    const ids = [source.nativeSessionId, nativeSessionIdFromLocator(source)];
+    for (const entry of entries) {
+        if (isAbsolute(entry) || entry === '~' || entry.startsWith('~/')) {
+            const pattern = entry.startsWith('~') ? homedir() + entry.slice(1) : entry;
+            if (globExpression(pattern).test(source.locator))
+                return { entry, kind: 'path-glob' };
+        }
+        else if (ids.includes(entry))
+            return { entry, kind: 'session-id' };
+    }
+    return undefined;
+}
+export function nativeSessionIdFromLocator(source) {
+    if (source.provider === 'grokbot')
+        return grokbotConversationIdFromLocator(source.locator) ?? undefined;
+    if (source.provider === 'muse')
+        return basename(dirname(source.locator));
+    const name = basename(source.locator, extname(source.locator));
+    if (source.provider === 'codex' || source.provider === 'pi') {
+        return /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i.exec(name)?.[1] ?? name;
+    }
+    return name;
+}
+function globExpression(pattern) {
+    let expression = '^';
+    for (let index = 0; index < pattern.length; index++) {
+        const character = pattern[index];
+        if (character === '*') {
+            if (pattern[index + 1] === '*') {
+                index++;
+                if (pattern[index + 1] === '/') {
+                    expression += '(?:.*/)?';
+                    index++;
+                }
+                else
+                    expression += '.*';
+            }
+            else
+                expression += '[^/]*';
+        }
+        else if (character === '?')
+            expression += '[^/]';
+        else
+            expression += character.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(expression + '$');
+}
+//# sourceMappingURL=import-exclusions.js.map

package/dist/src/sessions/import-lease.js

@@ -1,11 +1,10 @@
-import { mkdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { mkdir, readFile, rename, rm, writeFile, } from 'node:fs/promises';
 import { hostname } from 'node:os';
 import { dirname } from 'node:path';
 const DEFAULTS = {
     waitMs: 5_000,
     pollMs: 50,
     heartbeatMs: 1_000,
-    staleMs: 30_000,
 };
 export class ImportLeaseContentionError extends Error {
     owner;
@@ -29,12 +28,13 @@ export async function acquireImportLease(databasePath, runId, options = {}) {
     const waitMs = options.waitMs ?? DEFAULTS.waitMs;
     const pollMs = options.pollMs ?? DEFAULTS.pollMs;
     const heartbeatMs = options.heartbeatMs ?? DEFAULTS.heartbeatMs;
-    const staleMs = options.staleMs ?? DEFAULTS.staleMs;
     const now = options.now ?? (() => new Date());
     const processAlive = options.processAlive ?? defaultProcessAlive;
+    const processStartId = options.processStartId ?? defaultProcessStartId;
     const lockPath = importLeasePath(databasePath);
     const ownerPath = `${lockPath}/owner.json`;
     const deadline = Date.now() + waitMs;
+    const startId = await processStartId(process.pid);
     await mkdir(dirname(databasePath), { recursive: true, mode: 0o700 });
     while (true) {
         try {
@@ -47,6 +47,7 @@ export async function acquireImportLease(databasePath, runId, options = {}) {
                 host: hostname(),
                 startedAt: observed,
                 heartbeatAt: observed,
+                ...(startId === null ? {} : { processStartId: startId }),
             };
             await writeOwner(ownerPath, owner);
             let heartbeatWrite = Promise.resolve();
@@ -78,10 +79,10 @@ export async function acquireImportLease(databasePath, runId, options = {}) {
             if (!isNodeError(error) || error.code !== 'EEXIST')
                 throw error;
             const existing = await readOwner(ownerPath);
-            if (await staleLease(lockPath, existing, staleMs, processAlive)) {
+            if (await staleLease(existing, processAlive, processStartId)) {
                 const confirmed = await readOwner(ownerPath);
                 if (sameLease(existing, confirmed)
-                    && await staleLease(lockPath, confirmed, staleMs, processAlive)) {
+                    && await staleLease(confirmed, processAlive, processStartId)) {
                     await rm(lockPath, { recursive: true, force: true });
                     continue;
                 }
@@ -103,8 +104,9 @@ async function readOwner(path) {
         const value = JSON.parse(await readFile(path, 'utf8'));
         if (value.contractVersion !== '1.0.0'
             || typeof value.runId !== 'string'
-            || typeof value.pid !== 'number'
+            || !Number.isSafeInteger(value.pid) || (value.pid ?? 0) <= 0
             || typeof value.host !== 'string'
+            || (value.processStartId !== undefined && typeof value.processStartId !== 'string')
             || typeof value.startedAt !== 'string'
             || typeof value.heartbeatAt !== 'string')
             return null;
@@ -114,20 +116,15 @@ async function readOwner(path) {
         return null;
     }
 }
-async function staleLease(lockPath, owner, staleMs, processAlive) {
+async function staleLease(owner, processAlive, processStartId) {
     if (!owner || owner.host !== hostname())
         return false;
-    if (processAlive(owner.pid))
-        return false;
-    const heartbeat = owner ? Date.parse(owner.heartbeatAt) : Number.NaN;
-    if (Number.isFinite(heartbeat))
-        return Date.now() - heartbeat > staleMs;
-    try {
-        return Date.now() - (await stat(lockPath)).mtimeMs > staleMs;
-    }
-    catch {
+    if (!processAlive(owner.pid))
+        return true;
+    if (!owner.processStartId)
         return false;
-    }
+    const current = await processStartId(owner.pid);
+    return current !== null && current !== owner.processStartId;
 }
 function sameLease(first, second) {
     if (!first || !second)
@@ -136,6 +133,7 @@ function sameLease(first, second) {
         && first.pid === second.pid
         && first.host === second.host
         && first.startedAt === second.startedAt
+        && first.processStartId === second.processStartId
         && first.heartbeatAt === second.heartbeatAt;
 }
 function defaultProcessAlive(pid) {
@@ -144,7 +142,25 @@ function defaultProcessAlive(pid) {
         return true;
     }
     catch (error) {
-        return isNodeError(error) && error.code === 'EPERM';
+        return !isNodeError(error) || error.code !== 'ESRCH';
+    }
+}
+async function defaultProcessStartId(pid) {
+    if (process.platform !== 'linux')
+        return null;
+    try {
+        const [details, bootId] = await Promise.all([
+            readFile(`/proc/${pid}/stat`, 'utf8'),
+            readFile('/proc/sys/kernel/random/boot_id', 'utf8'),
+        ]);
+        // The command name may contain spaces and parentheses; field 22 is starttime.
+        const startTicks = details.slice(details.lastIndexOf(')') + 2).split(/\s+/)[19];
+        return startTicks && /^\d+$/.test(startTicks) && bootId.trim()
+            ? `${bootId.trim()}:${startTicks}`
+            : null;
+    }
+    catch {
+        return null;
     }
 }
 function isNodeError(error) {

package/dist/src/sessions/import-limits.js

@@ -0,0 +1,37 @@
+import { SessionContractError } from './contracts.js';
+export const DEFAULT_IMPORT_BYTE_LIMITS = Object.freeze({
+    maxRecordBytes: 64 * 1024 * 1024,
+    maxTotalBytes: 1024 * 1024 * 1024,
+});
+export function resolveImportLimits(config, flags, env = process.env) {
+    const resolve = (setting, flag, fallback) => {
+        const environmentValue = env[`AIWG_SESSIONS_IMPORT_${setting.toUpperCase()}`];
+        const origin = flag !== undefined ? 'flag' : environmentValue !== undefined ? 'env'
+            : config?.[setting] !== undefined ? 'config' : 'default';
+        const input = flag ?? environmentValue ?? config?.[setting] ?? fallback;
+        const value = typeof input === 'string' && /^\d+$/.test(input) ? Number(input) : input;
+        if (typeof value !== 'number' || !Number.isSafeInteger(value)
+            || value < (setting === 'max_source_bytes' ? 0 : 1)) {
+            throw new SessionContractError('INVALID_ARGUMENT', `sessions.import.${setting} (${origin}) must be ${setting === 'max_source_bytes' ? 'a non-negative' : 'a positive'} safe integer in bytes`);
+        }
+        return { value, origin };
+    };
+    const record = resolve('max_record_bytes', flags?.maxRecordBytes, DEFAULT_IMPORT_BYTE_LIMITS.maxRecordBytes);
+    const source = resolve('max_source_bytes', flags?.maxSourceBytes, DEFAULT_IMPORT_BYTE_LIMITS.maxTotalBytes);
+    return {
+        maxRecordBytes: record.value,
+        maxTotalBytes: source.value,
+        limitOrigins: { maxRecordBytes: record.origin, maxTotalBytes: source.origin },
+    };
+}
+export function assertImportByteLimit(limit, limits, observed) {
+    const configured = limits[limit];
+    if (limit === 'maxTotalBytes' && configured === 0)
+        return;
+    if (observed > configured) {
+        const setting = limit === 'maxRecordBytes' ? 'sessions.import.max_record_bytes' : 'sessions.import.max_source_bytes';
+        const origin = limits.limitOrigins?.[limit] ?? 'default';
+        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', `${setting} exceeded (configured=${configured}, observed=${observed}, origin=${origin})`, { limit, setting, configured, observed, origin });
+    }
+}
+//# sourceMappingURL=import-limits.js.map