@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/gates/providers/loader.js

@@ -1,3 +1,4 @@
+import { signalChild } from '../../process/signal-child.mjs';
 import { createHash, randomBytes } from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { closeSync, lstatSync, openSync, readSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync, } from 'node:fs';
@@ -7,6 +8,7 @@ import { GateProviderEntrySchema } from '../../extensions/manifest.js';
 import { artifactDigest } from '../../decision/validate.js';
 import { providerSourceDigest } from './types.js';
 import { ISOLATED_CHILD_SOURCE } from './isolated-child-source.js';
+import { positiveTimeoutMs } from '../../process/bounded-child-process.mjs';
 /**
  * Addon/extension metric-provider loading, isolated rework (P1-P5).
  *
@@ -52,6 +54,10 @@ export const GATE_PROVIDER_MAX_TIMEOUT_MS = 30000;
 export const GATE_PROVIDER_DEFAULT_MAX_RECORDS = 50000;
 /** Largest accepted isolated-run stdout body (single JSON message). */
 export const GATE_PROVIDER_MAX_OUTPUT_BYTES = 1024 * 1024;
+/** V8 old generation; RLIMIT_DATA also bounds off-heap ArrayBuffer allocations. */
+export const GATE_PROVIDER_MAX_OLD_SPACE_MB = 128;
+// Node reserves ~512 MiB for its code range before any provider runs.
+export const GATE_PROVIDER_MAX_DATA_BYTES = 768 * 1024 * 1024;
 export class GateProviderError extends Error {
     code;
     constructor(message, code) {
@@ -316,11 +322,16 @@ function prepareIsolatedRun(record, args) {
 // OS sandbox (C1c/C1d): bubblewrap is the isolation boundary.
 // ---------------------------------------------------------------------------
 const BWRAP_CANDIDATES = ['/usr/bin/bwrap', '/bin/bwrap', '/usr/local/bin/bwrap'];
+const PRLIMIT_CANDIDATES = ['/usr/bin/prlimit', '/bin/prlimit', '/usr/local/bin/prlimit'];
 const SANDBOX_NODE_PATH = '/aiwg/bin/node';
 const SANDBOX_CWD = '/tmp';
 const SANDBOX_SELF_TEST_TIMEOUT_MS = 15000;
 const SANDBOX_NAMESPACES = ['net', 'pid', 'ipc', 'uts', 'user', 'mnt'];
+const MEMORY_NODE_ARGS = [
+    `--max-old-space-size=${GATE_PROVIDER_MAX_OLD_SPACE_MB}`, '--max-semi-space-size=16',
+];
 const DRIVER_NODE_ARGS = [
+    ...MEMORY_NODE_ARGS,
     '--experimental-vm-modules', '--permission', '--disallow-code-generation-from-strings',
     '--no-warnings', '--input-type=module', '-e', ISOLATED_CHILD_SOURCE,
 ];
@@ -329,8 +340,16 @@ const RESULT_FRAME = 'AIWG-RESULT ';
 const SANDBOX_SELF_TEST_SOURCE = [
     "import fs from 'node:fs';",
     "import net from 'node:net';",
+    "import v8 from 'node:v8';",
     "const input = JSON.parse(fs.readFileSync(0, 'utf8'));",
-    'const out = { env: {}, ns: {}, visible: [], connect: null };',
+    'const out = { env: {}, ns: {}, visible: [], connect: null, memory: null };',
+    // Read the inherited kernel limits AND exercise the allocation path. Do
+    // not touch the allocation if the wrapper is broken: fail without committing it.
+    "const data = /^Max data size\\s+(\\S+)\\s+(\\S+)/m.exec(fs.readFileSync('/proc/self/limits', 'utf8'));",
+    'let allocationBlocked = false;',
+    'try { new Uint8Array(input.maxDataBytes); } catch (error) { allocationBlocked = error instanceof RangeError; }',
+    'out.memory = { dataSoftBytes: Number(data?.[1]) || null, dataHardBytes: Number(data?.[2]) || null,',
+    '  heapLimitBytes: v8.getHeapStatistics().heap_size_limit, allocationBlocked };',
     'for (const key of Object.keys(process.env)) out.env[key] = String(process.env[key]);',
     "for (const name of input.namespaces) { try { out.ns[name] = fs.readlinkSync('/proc/self/ns/' + name); } catch { out.ns[name] = null; } }",
     'for (const path of input.paths) { try { fs.lstatSync(path); out.visible.push(path); } catch { /* absent */ } }',
@@ -348,7 +367,7 @@ let sandboxOverride = null;
 let sandboxVerdict;
 let runtimeBindCache;
 /**
- * Test-only hook: point the runner at another bwrap path (for example a
+ * Test-only hook: point the runner at another bwrap/prlimit path (for example a
  * missing binary, or one that fails the self-test) or reset with `null`.
  * It can only make the runner refuse: whatever path is configured must still
  * pass the capability self-test before any provider runs.
@@ -359,6 +378,13 @@ export function configureIsolationSandboxForTests(options) {
 }
 function resolveBwrapPath() {
     const candidates = sandboxOverride?.bwrapPath !== undefined ? [sandboxOverride.bwrapPath] : BWRAP_CANDIDATES;
+    return resolveExecutable(candidates);
+}
+function resolvePrlimitPath() {
+    const candidates = sandboxOverride?.prlimitPath !== undefined ? [sandboxOverride.prlimitPath] : PRLIMIT_CANDIDATES;
+    return resolveExecutable(candidates);
+}
+function resolveExecutable(candidates) {
     for (const candidate of candidates) {
         try {
             const status = statSync(candidate);
@@ -475,6 +501,10 @@ function sandboxCommand(nodeArgs) {
     if (bwrap === null) {
         throw new GateProviderError('bundle providers require bubblewrap (bwrap) for OS-level isolation and none was found: refusing to run', 'sandbox-unavailable');
     }
+    const prlimit = resolvePrlimitPath();
+    if (prlimit === null) {
+        throw new GateProviderError('bundle providers require prlimit for a kernel memory cap and none was found: refusing to run', 'sandbox-unavailable');
+    }
     const args = [
         '--unshare-all', '--unshare-user', '--disable-userns',
         '--die-with-parent', '--new-session', '--clearenv', '--cap-drop', 'ALL',
@@ -482,7 +512,13 @@ function sandboxCommand(nodeArgs) {
     for (const [source, target] of runtimeBinds())
         args.push('--ro-bind', source, target);
     args.push('--tmpfs', SANDBOX_CWD, '--proc', '/proc', '--dev', '/dev', '--chdir', SANDBOX_CWD, '--', SANDBOX_NODE_PATH, ...nodeArgs);
-    return { command: bwrap, args, env: {} };
+    return {
+        command: prlimit,
+        // Both limits are hard as well as soft, inherited across exec into bwrap
+        // and node. Core dumps are disabled for bounded heap exhaustion failures.
+        args: [`--data=${GATE_PROVIDER_MAX_DATA_BYTES}:${GATE_PROVIDER_MAX_DATA_BYTES}`, '--core=0:0', '--', bwrap, ...args],
+        env: {},
+    };
 }
 /**
  * The exact sandboxed launch used for every provider run: bubblewrap with
@@ -490,7 +526,8 @@ function sandboxCommand(nodeArgs) {
  * cleared environment, new session, die-with-parent, read-only node runtime
  * binds, a private tmpfs, and node with `--permission` (no fs, no child
  * processes, no workers) plus `--disallow-code-generation-from-strings`.
- * The spawn environment itself is empty.
+ * prlimit applies a hard data cap (including off-heap memory); V8 has a
+ * separate heap cap. The spawn environment itself is empty.
  */
 export function isolationLaunchPlan() {
     return sandboxCommand(DRIVER_NODE_ARGS);
@@ -514,11 +551,11 @@ function hostProbePaths() {
 }
 function selfTestInput(port) {
     const paths = hostProbePaths();
-    return { paths, input: JSON.stringify({ namespaces: SANDBOX_NAMESPACES, paths, port }) };
+    return { paths, input: JSON.stringify({ namespaces: SANDBOX_NAMESPACES, paths, port, maxDataBytes: GATE_PROVIDER_MAX_DATA_BYTES }) };
 }
 function judgeSelfTest(stdout, status, paths, port) {
     const report = {
-        ok: false, reason: '', envKeys: [], sharedNamespaces: [], hostPathsVisible: [], connect: null,
+        ok: false, reason: '', envKeys: [], sharedNamespaces: [], hostPathsVisible: [], connect: null, memory: null,
     };
     let observed;
     try {
@@ -549,7 +586,15 @@ function judgeSelfTest(stdout, status, paths, port) {
     }
     report.hostPathsVisible = (observed.visible ?? []).filter(path => paths.includes(path));
     report.connect = observed.connect ?? null;
+    report.memory = observed.memory ?? null;
     const problems = [];
+    const memory = report.memory;
+    if (memory === null
+        || memory.dataSoftBytes !== GATE_PROVIDER_MAX_DATA_BYTES || memory.dataHardBytes !== GATE_PROVIDER_MAX_DATA_BYTES
+        || !(memory.heapLimitBytes > 0 && memory.heapLimitBytes <= (GATE_PROVIDER_MAX_OLD_SPACE_MB + 48) * 1024 * 1024)
+        || memory.allocationBlocked !== true) {
+        problems.push('memory cap not enforced');
+    }
     if (report.envKeys.length)
         problems.push(`environment leaks ${report.envKeys.join(',')}`);
     if (report.sharedNamespaces.length)
@@ -564,7 +609,7 @@ function judgeSelfTest(stdout, status, paths, port) {
 }
 /**
  * Runs the sandbox capability self-test asynchronously and returns the
- * observations (empty env, private namespaces, no host paths, optional
+ * observations (enforced memory caps, empty env, private namespaces, no host paths, optional
  * loopback connect to a parent listener on `connectPort`).
  */
 export function probeIsolationSandbox(options) {
@@ -572,20 +617,20 @@ export function probeIsolationSandbox(options) {
     let plan;
     let probe;
     try {
-        plan = sandboxCommand(['--no-warnings', '--input-type=module', '-e', SANDBOX_SELF_TEST_SOURCE]);
+        plan = sandboxCommand([...MEMORY_NODE_ARGS, '--no-warnings', '--input-type=module', '-e', SANDBOX_SELF_TEST_SOURCE]);
         probe = selfTestInput(port);
     }
     catch (error) {
         return Promise.resolve({
             ok: false, reason: error instanceof Error ? error.message : 'sandbox unavailable',
-            envKeys: [], sharedNamespaces: [], hostPathsVisible: [], connect: null,
+            envKeys: [], sharedNamespaces: [], hostPathsVisible: [], connect: null, memory: null,
         });
     }
     return new Promise((resolvePromise) => {
         const child = spawn(plan.command, plan.args, { env: plan.env, stdio: ['pipe', 'pipe', 'ignore'] });
         const chunks = [];
         const timer = setTimeout(() => { try {
-            child.kill('SIGKILL');
+            signalChild(child, 'SIGKILL');
         }
         catch { /* exited */ } }, SANDBOX_SELF_TEST_TIMEOUT_MS);
         child.stdout?.on('data', (chunk) => { chunks.push(chunk); });
@@ -594,7 +639,7 @@ export function probeIsolationSandbox(options) {
             clearTimeout(timer);
             resolvePromise({
                 ok: false, reason: `sandbox failed to start: ${error.message}`,
-                envKeys: [], sharedNamespaces: [], hostPathsVisible: [], connect: null,
+                envKeys: [], sharedNamespaces: [], hostPathsVisible: [], connect: null, memory: null,
             });
         });
         child.on('close', (code) => {
@@ -606,15 +651,15 @@ export function probeIsolationSandbox(options) {
 }
 /**
  * Fail-closed gate before every provider run: bwrap must exist and pass the
- * capability self-test (cached per bwrap path for the process lifetime).
+ * capability self-test (cached per bwrap/prlimit path for the process lifetime).
  * There is no unsandboxed fallback.
  */
 function ensureIsolationSandbox() {
-    const key = resolveBwrapPath() ?? '<missing>';
+    const key = JSON.stringify([resolveBwrapPath(), resolvePrlimitPath()]);
     if (sandboxVerdict === undefined || sandboxVerdict.key !== key) {
         let verdict;
         try {
-            const plan = sandboxCommand(['--no-warnings', '--input-type=module', '-e', SANDBOX_SELF_TEST_SOURCE]);
+            const plan = sandboxCommand([...MEMORY_NODE_ARGS, '--no-warnings', '--input-type=module', '-e', SANDBOX_SELF_TEST_SOURCE]);
             const probe = selfTestInput(null);
             const completed = spawnSync(plan.command, plan.args, {
                 env: plan.env, input: probe.input, encoding: 'utf8', timeout: SANDBOX_SELF_TEST_TIMEOUT_MS,
@@ -684,7 +729,8 @@ function runIsolatedRecordSync(record, args, limits) {
     const completed = spawnSync(plan.command, plan.args, {
         env: plan.env,
         input,
-        timeout: limits.timeoutMs,
+        // Validated upstream; clamped here so the bound holds at the call site.
+        timeout: positiveTimeoutMs(limits.timeoutMs, GATE_PROVIDER_DEFAULT_TIMEOUT_MS),
         killSignal: 'SIGKILL',
         maxBuffer: limits.maxOutputBytes,
         encoding: 'utf8',
@@ -741,14 +787,14 @@ function runIsolatedRecord(record, args, limits) {
         }
         const timer = setTimeout(() => {
             try {
-                child.kill('SIGKILL');
+                signalChild(child, 'SIGKILL');
             }
             catch { /* already exited */ }
             settle(() => rejectPromise(new GateProviderError(`provider ${record.id} timed out`, 'timeout')));
         }, limits.timeoutMs);
         const onAbort = () => {
             try {
-                child.kill('SIGKILL');
+                signalChild(child, 'SIGKILL');
             }
             catch { /* already exited */ }
             settle(() => rejectPromise(new GateProviderError(`provider ${record.id} was cancelled`, 'cancelled')));
@@ -762,7 +808,7 @@ function runIsolatedRecord(record, args, limits) {
             if (bytes > limits.maxOutputBytes) {
                 capped = true;
                 try {
-                    child.kill('SIGKILL');
+                    signalChild(child, 'SIGKILL');
                 }
                 catch { /* already exited */ }
                 settle(() => rejectPromise(new GateProviderError(`provider ${record.id} exceeds its output cap`, 'rejected')));

package/dist/src/installation/manager-command.d.mts

@@ -0,0 +1,18 @@
+export interface ManagerCommandOptions {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  execute?: (file: string, args: string[], options?: Record<string, unknown>) => unknown;
+  execOptions?: Record<string, unknown>;
+}
+
+export function resolveManagerCommand(
+  file: string,
+  args: string[],
+  options?: ManagerCommandOptions,
+): { file: string; args: string[] };
+
+export function executeManagerCommand(
+  file: string,
+  args: string[],
+  options?: ManagerCommandOptions,
+): unknown;

package/dist/src/installation/manager-command.mjs

@@ -1,7 +1,17 @@
 import { execFileSync } from 'node:child_process';
 
+const cmdMetaChars = /([()\][%!^"`<>&|;, *?])/g;
+
 function quoteCmdArgument(value) {
-  return `"${String(value).replace(/%/g, '%%').replace(/"/g, '""')}"`;
+  // Match cross-spawn's argument transport: first escape quotes and trailing
+  // backslashes for the target's argv parser, then protect cmd metacharacters
+  // outside quotes. Doubling % only works in batch source, not a /c operand.
+  const argument = String(value)
+    .replace(/(?=(\\+?)?)\1"/g, '$1$1\\"')
+    .replace(/(?=(\\+?)?)\1$/, '$1$1');
+  // Batch wrappers forward operands through another cmd parse (typically %*),
+  // so retain one layer of caret escaping for that second parse.
+  return `"${argument}"`.replace(cmdMetaChars, '^$1').replace(cmdMetaChars, '^$1');
 }
 
 /**
@@ -17,10 +27,12 @@ export function resolveManagerCommand(file, args, options = {}) {
 
   const env = options.env ?? process.env;
   const commandInterpreter = env.ComSpec || env.COMSPEC || 'cmd.exe';
-  const command = `"${[file, ...args].map(quoteCmdArgument).join(' ')}"`;
+  // The command itself is consumed by the first parse; only its operands need
+  // the second escape layer. Escape spaces in the path as well as operators.
+  const command = `"${[String(file).replace(cmdMetaChars, '^$1'), ...args.map(quoteCmdArgument)].join(' ')}"`;
   return {
     file: commandInterpreter,
-    args: ['/d', '/s', '/c', command],
+    args: ['/d', '/v:off', '/s', '/c', command],
     // The payload above already contains cmd.exe-native quoting. Instruct
     // Node not to apply MSVCRT escaping to those embedded quotes (#173).
     windowsVerbatimArguments: true,

package/dist/src/installation/manager.d.mts

@@ -0,0 +1,49 @@
+export type InstallationMethod = 'npm' | 'web' | 'source';
+export type InstallationRunMode = 'normal' | 'development';
+export type InstallationChannel = 'stable' | 'next' | 'nightly' | 'edge';
+export interface InstallationIdentity {
+  schemaVersion: 1;
+  runMode: InstallationRunMode;
+  method: InstallationMethod;
+  root: string;
+  updateStrategy: 'npm-global' | 'signed-web' | 'source-git';
+  managerExecutable: string | null;
+  channel: InstallationChannel;
+  edgePath: string | null;
+  checkOnStartup: boolean;
+  lastUpdateCheck: number | string | null;
+  updateCheckInterval: number;
+  recordedAt: string;
+}
+export interface InstallationStatus {
+  state: 'aligned' | 'mismatch' | 'stale' | 'unrecorded';
+  identity: InstallationIdentity | null;
+  canonicalRoot?: string;
+  actualRoot: string;
+  actualMethod: InstallationMethod;
+  /** Root AIWG reads its corpus from. Equals actualRoot unless an edge launcher redirect applies. */
+  frameworkRoot: string;
+  /** Edge/customize mode only: the running executable's own package root (#2505). */
+  launcher: { root: string; method: InstallationMethod } | null;
+  drift: string[];
+  managerProbe: { state: 'usable' | 'failed'; error?: string } | null;
+}
+export const INSTALLATION_IDENTITY_VERSION: 1;
+export const INSTALLATION_FILE: string;
+export function installationFile(options?: Record<string, unknown>): string;
+export function inferInstallationMethod(root: string): InstallationMethod;
+export function createInstallationIdentity(options: Record<string, any>): InstallationIdentity;
+export function saveInstallationIdentity(identity: InstallationIdentity, options?: Record<string, any>): InstallationIdentity;
+export function loadInstallationIdentity(options?: Record<string, any>): InstallationIdentity | null;
+export function inspectInstallation(options: Record<string, any>): InstallationStatus;
+export interface InstallationCopy {
+  root: string;
+  executables: string[];
+  onPath: boolean;
+  registered: boolean;
+}
+export function inspectInstallationCopies(options?: Record<string, any>): InstallationCopy[];
+export function formatInstallationDiagnostic(status: InstallationStatus, options?: { readOnlyCommand?: string }): string;
+export function assertCanonicalInstallation(options: Record<string, any>): InstallationStatus;
+export function adoptInstallation(options: Record<string, any>): InstallationStatus;
+export function switchInstallation(options: Record<string, any>): InstallationStatus;

package/dist/src/installation/manager.mjs

@@ -1,16 +1,18 @@
-import { execFileSync } from 'node:child_process';
+import { boundedExecFileSync } from '../process/bounded-child-process.mjs';
 import {
   accessSync,
   constants,
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   realpathSync,
   renameSync,
   statSync,
   writeFileSync,
 } from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import { resolveUserConfigDir } from '../config/user-config-dir.mjs';
 import { executeManagerCommand } from './manager-command.mjs';
 
@@ -50,7 +52,22 @@ function resolveExecutable(name, options = {}) {
   if (existsSync(besideNode)) return canonicalPath(besideNode);
   try {
     const finder = process.platform === 'win32' ? 'where.exe' : 'which';
-    const found = execFileSync(finder, [name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    // Go/no-go review, blocker 1B: this runs unconditionally on first
+    // launch (creating the installation identity) for *every* command,
+    // including a credential-handling one — before `bin/aiwg.mjs` even
+    // knows which command that is. `which`/`where.exe` only need `PATH`
+    // (and, on Windows, `PATHEXT`/`SystemRoot` for its own resolution), so
+    // this never inherits the whole parent environment the way an absent
+    // `env` option otherwise would.
+    const lookupEnv = {
+      PATH: env.PATH ?? '',
+      ...(process.platform === 'win32' ? { PATHEXT: env.PATHEXT ?? '', SystemRoot: env.SystemRoot ?? '' } : {}),
+    };
+    const found = boundedExecFileSync(finder, [name], 'quick', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: lookupEnv,
+    })
       .split(/\r?\n/, 1)[0]?.trim();
     return found ? canonicalPath(found) : null;
   } catch {
@@ -254,13 +271,86 @@ export function inspectInstallation(options = {}) {
   };
 }
 
-export function formatInstallationDiagnostic(status) {
+/** Inspect executable copies without launching them or changing installation identity. */
+export function inspectInstallationCopies(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.homeDir ?? os.homedir();
+  const identity = options.identity ?? loadInstallationIdentity({ ...options, createIfMissing: false });
+  const copies = new Map();
+  const names = process.platform === 'win32' ? ['aiwg', 'aiwg.cmd', 'aiwg.exe'] : ['aiwg'];
+
+  function addDirectory(directory, onPath) {
+    for (const name of names) {
+      const executable = path.resolve(directory, name);
+      if (!executableIsUsable(executable)) continue;
+      let root = path.dirname(canonicalPath(executable));
+      while (!['aiwg', '@aiwg/cli'].includes(packageName(root))) {
+        const parent = path.dirname(root);
+        if (parent === root) { root = null; break; }
+        root = parent;
+      }
+      // npm's Windows command shims are files rather than symlinks.
+      if (!root && process.platform === 'win32') {
+        const candidate = path.join(directory, 'node_modules', 'aiwg');
+        if (packageName(candidate) === 'aiwg') root = canonicalPath(candidate);
+      }
+      if (!root) continue;
+      let copy = copies.get(root);
+      if (!copy) {
+        const status = identity ? inspectInstallation({ actualRoot: root, identity, createIfMissing: false }) : null;
+        copy = {
+          root,
+          executables: [],
+          onPath: false,
+          registered: Boolean(status && status.frameworkRoot === status.canonicalRoot),
+        };
+        copies.set(root, copy);
+      }
+      if (!copy.executables.includes(executable)) copy.executables.push(executable);
+      copy.onPath ||= onPath;
+    }
+  }
+
+  const pathDirectories = (env.PATH ?? '').split(path.delimiter);
+  for (const directory of new Set(pathDirectories)) addDirectory(directory, true);
+
+  const nvmRoots = new Set([path.join(home, '.nvm'), env.NVM_DIR].filter(Boolean));
+  // A running/registered nvm copy or NVM_BIN also identifies custom nvm homes.
+  for (const location of [options.actualRoot, identity?.root, env.NVM_BIN, ...pathDirectories]) {
+    if (!location) continue;
+    let directory = path.resolve(location);
+    while (path.dirname(directory) !== directory) {
+      if (path.basename(directory) === 'node' && path.basename(path.dirname(directory)) === 'versions') {
+        nvmRoots.add(path.dirname(path.dirname(directory)));
+        break;
+      }
+      directory = path.dirname(directory);
+    }
+  }
+  for (const nvmRoot of nvmRoots) {
+    const versions = path.join(nvmRoot, 'versions', 'node');
+    try {
+      for (const version of readdirSync(versions, { withFileTypes: true })) {
+        if (version.isDirectory()) addDirectory(path.join(versions, version.name, 'bin'), false);
+      }
+    } catch { /* nvm is optional and may no longer be installed. */ }
+  }
+  return [...copies.values()];
+}
+
+export function formatInstallationDiagnostic(status, options = {}) {
   if (status.state === 'aligned') return 'Canonical installation is aligned.';
   return [
-    'AIWG installation identity drift detected; update and refresh are blocked.',
+    options.readOnlyCommand
+      ? `installation identity drift detected; \`${options.readOnlyCommand}\` is read-only and continues, but update, refresh, and deployment stay blocked until the identity is repaired.`
+      : 'AIWG installation identity drift detected; update and refresh are blocked.',
+    `Running installation: ${status.actualMethod} at ${status.actualRoot}`,
+    `Registered installation: ${status.identity?.method ?? 'unrecorded'} at ${status.identity?.root ?? '(none)'}`,
     ...status.drift.map((item) => `- ${item}`),
+    'Diagnose PATH and nvm copies: aiwg doctor',
     'Inspect: aiwg installation show',
-    'Adopt this installation: aiwg installation adopt',
+    `Register this running copy deliberately: aiwg installation adopt --method ${status.actualMethod} --yes`,
+    'To keep the registered install, put its executable first on PATH; remove unwanted npm copies using npm from their Node prefix (npm uninstall -g aiwg).',
     'Switch deliberately: aiwg installation switch --root <path> --method <npm|web|source> [--manager <absolute-path>]',
   ].join('\n');
 }

package/dist/src/issues/cli.js

@@ -310,9 +310,9 @@ async function handleClose(issues, rest, args) {
 }
 async function handleIndex(issues, rest, args) {
     if (rest[0] !== 'rebuild')
-        throw new Error('Usage: aiwg issue index rebuild');
-    const index = await issues.rebuildIssueIndex();
-    printJsonOrText(args, index, `Rebuilt local issue index (${index.issues.length} issues)`);
+        throw new Error('Usage: aiwg issue index rebuild [--force]');
+    const index = await issues.rebuildIssueIndex({ force: args.flags.has('force') });
+    printJsonOrText(args, index, `Local issue index ready (${index.issues.length} issues)`);
 }
 function requiredStringFlag(args, flag) {
     const value = stringFlag(args, flag);
@@ -406,6 +406,6 @@ function printUsage() {
   aiwg issue sync map-comments <KEY> --map-file path [--json]
   aiwg issue comment <KEY> --body "..." [--author name]
   aiwg issue close <KEY> [--reason "..."]
-  aiwg issue index rebuild`);
+  aiwg issue index rebuild [--force]`);
 }
 //# sourceMappingURL=cli.js.map

package/dist/src/issues/local.js

@@ -1,5 +1,6 @@
 import { constants } from 'fs';
-import { mkdir, open, readFile, readdir, rename, unlink, writeFile } from 'fs/promises';
+import { mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from 'fs/promises';
+import { createHash } from 'node:crypto';
 import { basename, dirname, join, relative, resolve, sep } from 'path';
 import { hostname } from 'os';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
@@ -328,15 +329,32 @@ export class LocalIssueProviderCore {
         const idx = events.findIndex((event) => event.event_id === since);
         return idx >= 0 ? events.slice(idx + 1) : events;
     }
-    async rebuildIssueIndex() {
+    async rebuildIssueIndex(options = {}) {
         await this.ensureLayout();
         return this.lockManager.withIndexLock('rebuild issue index', async () => {
             const itemDir = this.path('items');
-            const entries = await readdir(itemDir, { withFileTypes: true }).catch(() => []);
+            const entries = (await readdir(itemDir, { withFileTypes: true }))
+                .filter(entry => entry.isFile() && entry.name.endsWith('.md'))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            const inputs = await Promise.all(entries.map(async (entry) => {
+                const metadata = await stat(join(itemDir, entry.name));
+                return [entry.name, metadata.mtimeMs, metadata.ctimeMs, metadata.size];
+            }));
+            const inputFingerprint = createHash('sha256').update(JSON.stringify([1, inputs])).digest('hex');
+            if (!options.force) {
+                try {
+                    const cached = JSON.parse(await readFile(this.path('index/issues.index.json'), 'utf-8'));
+                    if (cached?.provider === 'local' && Array.isArray(cached.issues) && cached.inputFingerprint === inputFingerprint) {
+                        return cached;
+                    }
+                }
+                catch (error) {
+                    if (!(error instanceof SyntaxError) && !(isNodeError(error) && error.code === 'ENOENT'))
+                        throw error;
+                }
+            }
             const issues = [];
             for (const entry of entries) {
-                if (!entry.isFile() || !entry.name.endsWith('.md'))
-                    continue;
                 const record = parseIssueMarkdown(await readFile(join(itemDir, entry.name), 'utf-8'));
                 issues.push({
                     id: record.fields.id,
@@ -355,6 +373,7 @@ export class LocalIssueProviderCore {
             const index = {
                 provider: 'local',
                 rebuilt_at: new Date().toISOString(),
+                inputFingerprint,
                 issues,
             };
             await atomicWrite(this.path('index/issues.index.json'), `${JSON.stringify(index, null, 2)}\n`);

package/dist/src/jobs/runner.js

@@ -184,7 +184,7 @@ async function acquireLock(stateRoot, flow) {
             const lock = JSON.parse(await fs.readFile(file, 'utf8'));
             const tooOld = !lock.startedAt || Date.now() - Date.parse(lock.startedAt) > (flow.spec.workItem.claimTtlSeconds ?? 900) * 1000;
             let alive = false;
-            if (typeof lock.pid === 'number') {
+            if (Number.isSafeInteger(lock.pid) && (lock.pid ?? 0) > 0) {
                 try {
                     process.kill(lock.pid, 0);
                     alive = true;

package/dist/src/lint/cli.js

@@ -13,6 +13,7 @@
  * @issue #810
  */
 import fs from 'fs';
+import { readAiwgConfigCandidate } from '../config/aiwg-config.js';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { discoverRulesets } from './loader.js';
@@ -71,9 +72,15 @@ function parseArgs(args) {
         else if (arg === '--format' && i + 1 < args.length) {
             options.format = args[++i];
         }
+        else if (arg === '--startup-plan' && i + 1 < args.length) {
+            options.startupPlan = args[++i];
+        }
         else if (arg === '--ci') {
             options.ci = true;
         }
+        else if (arg === '--allow-empty') {
+            options.allowEmpty = true;
+        }
         else if (arg === '--fail-on' && i + 1 < args.length) {
             options.failOn = args[++i];
         }
@@ -102,6 +109,14 @@ function parseArgs(args) {
 export async function main(args) {
     const options = parseArgs(args);
     const cwd = process.cwd();
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log('Usage: aiwg lint <target> [--ruleset <name>] [--format full|summary|json] [--ci] [--allow-empty] [--fail-on error|warn|info] [--no-gitignore]');
+        console.log('  --ci           Fail on lint violations, zero files checked or zero rules applied');
+        console.log('  --allow-empty  Allow zero files or zero applied rules under --ci');
+        console.log('  --startup-plan <json>  Guard a complete projected startup set { provider, files: [{ path, bytes | content }] }');
+        console.log('  --list-rulesets | --list-rules <ruleset>');
+        return;
+    }
     // Discover available rulesets. `cwd` is where the user runs the lint (used
     // to find deployed `.aiwg/frameworks/*/lint/` overlays); `AIWG_ROOT` is the
     // AIWG install (used to find shipped `agentic/code/frameworks/*/lint/`).
@@ -126,7 +141,7 @@ export async function main(args) {
     }
     // Require a target for actual linting
     if (!options.target) {
-        console.error('Usage: aiwg lint <target> [--ruleset <name>] [--format full|summary|json] [--ci] [--fail-on error|warn|info] [--no-gitignore]');
+        console.error('Usage: aiwg lint <target> [--ruleset <name>] [--format full|summary|json] [--ci] [--allow-empty] [--fail-on error|warn|info] [--no-gitignore]');
         console.error('       aiwg lint --list-rulesets');
         console.error('       aiwg lint --list-rules <ruleset>');
         process.exitCode = 1;
@@ -159,9 +174,20 @@ export async function main(args) {
         }
         return;
     }
+    let startupBudget;
+    if (options.startupPlan) {
+        const plan = JSON.parse(fs.readFileSync(path.resolve(cwd, options.startupPlan), 'utf8'));
+        if (!plan || typeof plan.provider !== 'string' || !Array.isArray(plan.files)) {
+            throw new Error('Startup plan must contain provider and files (the complete assembled startup set).');
+        }
+        startupBudget = { provider: plan.provider, files: plan.files, config: await readAiwgConfigCandidate(cwd) ?? {} };
+    }
     // Run lint
     const result = await runLint(targetDir, selectedRulesets, {
+        startupBudget,
         recursive: options.recursive,
+        ci: options.ci,
+        allowEmpty: options.allowEmpty,
         failOn: options.failOn,
         respectGitignore: options.respectGitignore ?? true,
     });

package/dist/src/lint/loader.js

@@ -8,6 +8,7 @@
  * @issue #810
  */
 import fs from 'fs';
+import { ruleActivationRuleset } from './rule-activation.js';
 import fsp from 'fs/promises';
 import path from 'path';
 import { projectAiwgPath } from '../config/project-artifacts.js';
@@ -178,7 +179,7 @@ export async function loadRuleset(lintDir, frameworkId) {
  * 2. Deployed frameworks: .aiwg/frameworks/{id}/lint/
  */
 export async function discoverRulesets(cwd, frameworkRoot) {
-    const rulesets = [];
+    const rulesets = [ruleActivationRuleset];
     // Check framework source directories
     const frameworksDir = path.join(frameworkRoot, 'agentic', 'code', 'frameworks');
     if (fs.existsSync(frameworksDir)) {