@aiwg/cli 2026.10.3 → 2026.10.4

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

@@ -5,12 +5,12 @@
  * - **Authority.** The tracker comes from `resolveTrackerAuthority` over the
  *   project config and git remote URLs. A target whose forge is neither the
  *   internal nor the customer tracker, or whose repository differs from that
- *   tracker remote, is `unknown` / `tracker-blocked`. The API base is derived
- *   from the selected remote URL; no host is assumed.
+ *   tracker remote, is `unknown` with a specific precondition reason. The API
+ *   base is derived from the selected remote URL; no host is assumed.
  * - **Access order.** `chooseTrackerAccess` over the probes a CLI process can
  *   offer: the tracker HTTP API (with credentials from the existing tracker
  *   token path, `resolveToken`), then the forge CLI (`gh`, GitHub only). MCP
- *   is never offered. A blocker is `unknown` / `tracker-blocked`.
+ *   is never offered. Blockers include a safe configuration or credential hint.
  * - **Matching.** A comment matches exactly when it carries the
  *   `<!-- aiwg-effect: <id> -->` marker and was written by the pinned tracker
  *   actor; a merged PR matches its merge commit's `Effect-Id:` trailer.
@@ -20,8 +20,8 @@
  *   older than `minAbsentAgeMs`; a younger intent is `unknown` /
  *   `consistency-lag`.
  *
- * Access material stays inside the transport: evidence carries IDs, SHAs and
- * digests only, and errors carry fixed messages.
+ * Access material stays inside the transport: evidence carries IDs, SHAs,
+ * digests and safe repair hints only, and errors carry fixed messages.
  *
  * @see docs/contracts/effect-ledger.v1.md "Tracker verifiers"
  */
@@ -92,7 +92,7 @@ function onPath(binary) {
         }
     }));
 }
-/** Resolve the tracker lane for a target: authority, remote, access path and reader. Throws `tracker-blocked`. */
+/** Resolve the tracker lane, or return a classified precondition failure with a safe repair hint. */
 function resolveLane(options, target) {
     const parsed = TARGET.exec(target);
     if (!parsed)
@@ -103,16 +103,16 @@ function resolveLane(options, target) {
     const remotes = options.config?.remotes;
     let lane = null;
     if (authority.provider === provider) {
-        lane = { remote: authority.issueTrackerRemote, url: authority.issueTrackerUrl, actor: remotes?.tracker_actor };
+        lane = { remote: authority.issueTrackerRemote, url: authority.issueTrackerUrl, actor: remotes?.tracker_actor, actorConfigKey: 'remotes.tracker_actor.login' };
     }
     else if (authority.customerIssueTrackerRemote && authority.customerProvider === provider) {
-        lane = { remote: authority.customerIssueTrackerRemote, url: authority.customerIssueTrackerUrl, actor: remotes?.customer_tracker_actor };
+        lane = { remote: authority.customerIssueTrackerRemote, url: authority.customerIssueTrackerUrl, actor: remotes?.customer_tracker_actor, actorConfigKey: 'remotes.customer_tracker_actor.login' };
     }
     if (!lane)
-        throw new EffectVerifierError('tracker-blocked');
+        return unknown('tracker-provider-unresolved', { hint: 'Set remotes.issue_provider (or remotes.customer_issue_provider for the customer tracker) to the target forge.' });
     const endpoint = forgeEndpointFromRemote(provider, lane.url);
     if (!endpoint || endpoint.repository.toLowerCase() !== parsed[2].toLowerCase())
-        throw new EffectVerifierError('tracker-blocked');
+        return unknown('tracker-repository-mismatch', { hint: 'Match the target repository to the remote selected by remotes.issue_tracker (or remotes.customer_issue_tracker).' });
     const laneAuthority = { ...authority, provider, issueTrackerRemote: lane.remote, issueTrackerUrl: lane.url };
     const token = resolveToken(provider, options.env ?? process.env);
     const cli = options.cli === false ? null : options.cli ?? {};
@@ -125,13 +125,16 @@ function resolveLane(options, target) {
     const readerOptions = options.pageSize ? { pageSize: options.pageSize } : {};
     if (decision.kind === 'http-api' && token) {
         const transport = httpForgeTransport({ provider, apiBaseUrl: endpoint.apiBaseUrl, token, fetchImpl: options.fetchImpl, maxResponseBytes: options.maxResponseBytes });
-        return { provider, repository: endpoint.repository, number, access: 'http-api', reader: createForgeReader(provider, transport, readerOptions), actor: lane.actor };
+        return { provider, repository: endpoint.repository, number, access: 'http-api', reader: createForgeReader(provider, transport, readerOptions), actor: lane.actor, actorConfigKey: lane.actorConfigKey };
     }
     if (decision.kind === 'cli' && cli) {
         const transport = cliForgeTransport({ provider, hostname: endpoint.host, runner: cli.runner, binary: cli.binary, maxResponseBytes: options.maxResponseBytes });
-        return { provider, repository: endpoint.repository, number, access: 'cli', reader: createForgeReader(provider, transport, readerOptions), actor: lane.actor };
+        return { provider, repository: endpoint.repository, number, access: 'cli', reader: createForgeReader(provider, transport, readerOptions), actor: lane.actor, actorConfigKey: lane.actorConfigKey };
     }
-    throw new EffectVerifierError('tracker-blocked');
+    // Gitea has no raw-read CLI fallback. GitHub may use gh when no token is set.
+    return provider === 'gitea'
+        ? unknown('tracker-credential-missing', { hint: 'Set AIWG_GITEA_TOKEN or GITEA_TOKEN for the tracker HTTP API.' })
+        : unknown('tracker-no-access-route', { hint: 'Set AIWG_GITHUB_TOKEN or GITHUB_TOKEN, or install and authenticate gh for the tracker host.' });
 }
 const unknown = (reason, evidence) => ({ result: 'unknown', reason, complete: false, ...(evidence ? { evidence } : {}) });
 /** `absent` once the intent is old enough, else `unknown` / `consistency-lag`. */
@@ -160,6 +163,8 @@ export function trackerCommentVerifier(options) {
         canReportAbsent: true,
         async verify(request) {
             const lane = resolveLane(options, request.target);
+            if ('result' in lane)
+                return lane;
             const expectedDigest = expectedString(request, 'digest');
             if (expectedDigest !== undefined && !DIGEST.test(expectedDigest))
                 return unknown('malformed-response');
@@ -220,7 +225,10 @@ export function trackerCommentVerifier(options) {
             const summary = { ...base, pages, scanned };
             // A marker for this effect under another author is never ours; escalate instead of replaying.
             if (foreignMarker)
-                return unknown('evidence-conflict', { ...summary, foreignMarker: true });
+                return unknown('evidence-conflict', {
+                    ...summary, foreignMarker: true,
+                    ...(!pinned ? { actorUnpinned: true, hint: `Set ${lane.actorConfigKey} to the trusted tracker author.` } : {}),
+                });
             if (digestMatch) {
                 return { result: 'present', reason: 'digest-match', complete, evidence: { ...summary, commentId: digestMatch.id, bodyDigest: digestMatch.bodyDigest, confidence: 'exact' } };
             }
@@ -241,6 +249,8 @@ export function trackerIssueClosedVerifier(options) {
         canReportAbsent: true,
         async verify(request) {
             const lane = resolveLane(options, request.target);
+            if ('result' in lane)
+                return lane;
             const issue = await read(() => lane.reader.getIssue(lane.repository, lane.number, request.signal));
             const evidence = { ...laneEvidence(lane), state: issue.state, closedAt: issue.closedAt };
             if (issue.state === 'closed')
@@ -263,6 +273,8 @@ export function trackerPrMergedVerifier(options) {
             if (expectedSha !== undefined && !OBJECT_ID.test(expectedSha))
                 return unknown('malformed-response');
             const lane = resolveLane(options, request.target);
+            if ('result' in lane)
+                return lane;
             const pr = await read(() => lane.reader.getPullState(lane.repository, lane.number, request.signal));
             const evidence = {
                 ...laneEvidence(lane), state: pr.state, merged: pr.merged, mergedAt: pr.mergedAt,

package/dist/src/extensions/commands/definitions.js

@@ -200,6 +200,24 @@ export const decisionCommand = {
         allowedTools: ['Read', 'Write', 'Bash'],
     },
 };
+export const rulesCommand = {
+    id: 'rules',
+    type: 'command',
+    name: 'Rule Pins',
+    description: 'Pin installed rules to every request and manage reusable capability groups',
+    version: '1.0.0',
+    capabilities: ['cli', 'rules', 'configuration', 'activation'],
+    keywords: ['rules', 'pin', 'unpin', 'pinned', 'tier', 'capability', 'group'],
+    category: 'config',
+    platforms: { claude: 'full', generic: 'full' },
+    deployment: { pathTemplate: '.{platform}/commands/{id}.md', core: true },
+    metadata: {
+        type: 'command',
+        template: 'utility',
+        argumentHint: '<pin|unpin|pinned|group> [rules...] [--tier tiers] [--capability ids] [--group name] [--all] [--dry-run] [--json]',
+        allowedTools: ['Read', 'Write', 'Bash'],
+    },
+};
 export const gatesCommand = {
     id: 'gates',
     type: 'command',
@@ -3752,6 +3770,7 @@ export const commandDefinitions = [
     updateCommand,
     installationCommand,
     decisionCommand,
+    rulesCommand,
     gatesCommand,
     refreshCommand,
     regenerateCommand,

package/dist/src/extensions/project-local-remove.js

@@ -12,8 +12,10 @@
  * @design @.aiwg/architecture/design-aiwg-remove-revert.md
  * @implements #1037
  */
-import { lstat, readdir, stat, unlink, rmdir } from 'fs/promises';
+import { lstat, readdir, readFile, stat, unlink, rmdir } from 'fs/promises';
 import { resolve, join, relative, dirname, isAbsolute } from 'path';
+import { deployedSkillRoots } from '../providers/deployed-skill-roots.js';
+import { releaseSkillOwnership } from '../providers/skill-ownership.mjs';
 import { appendProjectLocalActivity } from './project-local-activity.js';
 import { sha256OfFileNormalized } from './managed-marker.js';
 import { getProviderArtifactPathStrings } from '../providers/provider-definitions.js';
@@ -257,7 +259,40 @@ export async function removeProjectLocalBundle(config, projectDir, bundleId, opt
     for (const provider of providers) {
         const artifactHashes = artifactHashesForProvider(installedEntry, provider);
         let providerHadSkip = false;
+        // Receipts cover the complete transformed skill and support tree, including
+        // retired skills no longer present in the source inventory.
+        const receiptSkills = new Set();
+        const sourceRoot = installedEntry.localPath ? resolve(projectDir, installedEntry.localPath) : undefined;
+        for (const root of deployedSkillRoots(projectDir, provider)) {
+            for (const name of await readdir(root).catch(() => [])) {
+                const skillDir = join(root, name);
+                try {
+                    await readFile(join(skillDir, '.aiwg-manifest.json'), 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                receiptSkills.add(name);
+                const removed = releaseSkillOwnership(skillDir, {
+                    frameworkSlug: bundleId,
+                    skillSource: sourceRoot ? join(sourceRoot, 'skills', name) : undefined,
+                    sourceRoot,
+                }, { dryRun });
+                if (removed === null) {
+                    // Unrelated receipts are outside this bundle's removal inventory.
+                    if (!Object.keys(artifactHashes).some(sourceRel => sourceRel.startsWith(`skills/${name}/`)))
+                        continue;
+                    providerHadSkip = true;
+                }
+                outcomes.push({ provider, artifactPath: `skills/${name}/SKILL.md`, deployedAbsPath: skillDir,
+                    case: removed === null ? 'replaced' : 'pristine', reverted: removed !== null && !dryRun,
+                    message: removed === null ? 'owned by another source — preserved' : dryRun
+                        ? '[dry-run] would release skill ownership' : 'released skill ownership; operator files preserved' });
+            }
+        }
         for (const sourceRel of Object.keys(artifactHashes)) {
+            if (sourceRel.startsWith('skills/') && receiptSkills.has(sourceRel.split('/')[1]))
+                continue;
             const owner = resolveOwnership(config, bundleId, provider, sourceRel);
             if (owner) {
                 providerHadSkip = true;

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';
@@ -53,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) {
@@ -317,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,
 ];
@@ -330,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 */ } }',
@@ -349,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.
@@ -360,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);
@@ -476,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',
@@ -483,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
@@ -491,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);
@@ -515,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 {
@@ -550,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)
@@ -565,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) {
@@ -573,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); });
@@ -595,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) => {
@@ -607,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,
@@ -743,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')));
@@ -764,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,7 +27,9 @@ 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', '/v:off', '/s', '/c', command],

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

@@ -5,12 +5,14 @@ import {
   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';
 
@@ -269,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