@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/effects/dispatch-verifier.js

@@ -0,0 +1,252 @@
+/**
+ * Worker-dispatch effect verification (#2891, S1 direct/shared checkpoint).
+ *
+ * Modelled on the ledger lock recovery (`src/effects/lock-recovery.ts`): an
+ * extension kind whose verifier is registered only when the evidence it
+ * checks actually exists. Here the evidence is Tier 0 supervisor evidence
+ * held by the conductor — the dispatch record digest for one invocation,
+ * plus optional `file.digest` artifacts. Without supervisor evidence the
+ * factory returns null and the kind stays unregistered, so reconciliation
+ * through the existing ledger answers `unknown` / `verifier-missing` instead
+ * of manufacturing proof.
+ *
+ * Artifact checks reuse the built-in `file.digest` verifier by delegation;
+ * this module owns no second ledger and no file hashing of its own.
+ *
+ * Managed (S2+) durable dispatch proof and Tier 1 registration are out of
+ * scope; this verifier covers direct/shared supervisor evidence only.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Verifier interface"
+ */
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { EffectLedgerError } from './errors.js';
+import { fileDigestVerifier } from './verifiers/file.js';
+import { EffectVerifierError } from './verifiers/types.js';
+export const DISPATCH_KIND = 'x.aiwg.worker-dispatch';
+export const DISPATCH_VERIFIER_VERSION = '1.0.0';
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+/**
+ * Canonical invocation-ID shape for dispatch evidence (#2891). This is the
+ * SINGLE definition: `tools/ralph-external/lib/dispatch-evidence.mjs`
+ * imports this exact binding (through `tools/_resolve-impl.mjs`'s
+ * `importImpl`, since `tools/` cannot import `src/*.js` directly) rather
+ * than duplicating the literal, so the two can never drift.
+ */
+export const INVOCATION_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+/** Conductor-owned evidence directories and files are owner-only. */
+export const DISPATCH_EVIDENCE_DIR_MODE = 0o700;
+export const DISPATCH_EVIDENCE_FILE_MODE = 0o600;
+export function dispatchEffectTarget(invocationId) {
+    return `x-aiwg:dispatch/${invocationId}`;
+}
+/**
+ * Test-only race-injection seam (#2891 R1/R7), mirroring the equivalent hook
+ * in `tools/ralph-external/lib/dispatch-evidence.mjs`. No-op in production
+ * (`afterOpen` defaults to `null`); this package's own conformance suite
+ * sets it to a one-shot callback that performs a deterministic TOCTOU swap
+ * between `loadSupervisorEvidence`'s two `open()` calls, then clears
+ * itself. Never read outside `openTraced` below.
+ */
+export const __raceTestHooks = { afterOpen: null };
+async function openTraced(path, flags) {
+    const handle = await open(path, flags);
+    if (__raceTestHooks.afterOpen)
+        await __raceTestHooks.afterOpen(path);
+    return handle;
+}
+/**
+ * Read supervisor evidence from the conductor-owned evidence location. The
+ * evidence directory is opened `O_NOFOLLOW` ONCE and kept open for the
+ * whole read: the file `<invocationId>.json` is then opened through that
+ * SAME still-open directory descriptor, via `/proc/self/fd/<dirfd>/<name>`,
+ * never by re-resolving `<evidenceDir>/<invocationId>.json` as a fresh path
+ * string. This means a swap of `evidenceDir`'s path between validating the
+ * directory and reading the file cannot redirect the read onto an attacker-
+ * controlled location — the descriptor still refers to the original,
+ * validated directory regardless of what the path now names.
+ *
+ * Every check runs against an open fd: the evidence directory must be a
+ * real directory owned by us with mode exactly 0700, and the evidence file
+ * must be a regular file owned by us with mode exactly 0600 and exactly one
+ * link (no surprise hardlink). Supervisor evidence is never read from a
+ * worker-writable path: any symlink, wrong mode, wrong owner, extra link or
+ * unbound invocationId throws instead of verifying.
+ *
+ * When `expectedRecordDigest` is supplied (the sha256 of the evidence
+ * file's raw bytes, recorded by the conductor at capture time — for
+ * example from the effect ledger intent this evidence backs), the freshly
+ * read bytes must hash to it or the load throws. Shape and permission
+ * checks alone cannot detect in-place mutation of an already-captured
+ * evidence file; this closes that gap for any caller that has an earlier
+ * recorded digest to check against.
+ */
+export async function loadSupervisorEvidence(options) {
+    const invocationId = options?.invocationId;
+    if (typeof invocationId !== 'string' || !INVOCATION_PATTERN.test(invocationId)) {
+        throw new EffectVerifierError('malformed-response', 'Supervisor evidence needs a valid invocation ID');
+    }
+    if (!options || typeof options.evidenceDir !== 'string' || !options.evidenceDir) {
+        throw new EffectVerifierError('container-unreadable', 'Supervisor evidence needs a conductor-owned evidence directory');
+    }
+    const dirResolved = resolve(options.evidenceDir);
+    let dirHandle;
+    try {
+        dirHandle = await openTraced(dirResolved, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | constants.O_NOFOLLOW);
+    }
+    catch {
+        throw new EffectVerifierError('container-unreadable', `Supervisor evidence directory is not a real directory: ${dirResolved}`);
+    }
+    try {
+        const dirStat = await dirHandle.stat();
+        const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+        if (!dirStat.isDirectory() || (dirStat.mode & 0o777) !== DISPATCH_EVIDENCE_DIR_MODE
+            || (uid !== null && dirStat.uid !== uid)) {
+            throw new EffectVerifierError('container-unreadable', `Supervisor evidence directory is not owner-only 0700: ${dirResolved}`);
+        }
+        const name = `${invocationId}.json`;
+        const ref = `/proc/self/fd/${dirHandle.fd}/${name}`;
+        let handle;
+        try {
+            handle = await openTraced(ref, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch {
+            throw new EffectVerifierError('container-unreadable', `Supervisor evidence is unreadable: ${dirResolved}/${name}`);
+        }
+        try {
+            const stat = await handle.stat();
+            const fileUid = typeof process.getuid === 'function' ? process.getuid() : null;
+            if (!stat.isFile() || (stat.mode & 0o777) !== DISPATCH_EVIDENCE_FILE_MODE
+                || (fileUid !== null && stat.uid !== fileUid) || stat.nlink !== 1) {
+                throw new EffectVerifierError('container-unreadable', `Supervisor evidence is not an owner-only 0600 regular file with a single link: ${dirResolved}/${name}`);
+            }
+            const raw = await handle.readFile('utf8');
+            if (typeof options.expectedRecordDigest === 'string' && options.expectedRecordDigest) {
+                const actual = `sha256:${createHash('sha256').update(raw, 'utf8').digest('hex')}`;
+                if (actual !== options.expectedRecordDigest) {
+                    throw new EffectVerifierError('malformed-response', 'Supervisor evidence does not match its recorded digest; mutation after capture is not trusted');
+                }
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw new EffectVerifierError('malformed-response', 'Supervisor evidence is not valid JSON');
+            }
+            if (!hasSupervisorEvidence(parsed) || parsed.invocationId !== invocationId) {
+                throw new EffectVerifierError('malformed-response', 'Supervisor evidence is not bound to this invocation');
+            }
+            return parsed;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    finally {
+        await dirHandle.close();
+    }
+}
+/** True only when actual supervisor evidence exists: a bound invocation and digest. */
+export function hasSupervisorEvidence(evidence) {
+    if (!evidence || typeof evidence !== 'object')
+        return false;
+    const record = evidence;
+    if (typeof record.invocationId !== 'string' || !INVOCATION_PATTERN.test(record.invocationId))
+        return false;
+    if (typeof record.evidenceDigest !== 'string' || !DIGEST_PATTERN.test(record.evidenceDigest))
+        return false;
+    if (record.artifactPath !== undefined || record.artifactDigest !== undefined) {
+        if (typeof record.artifactPath !== 'string' || !record.artifactPath)
+            return false;
+        if (typeof record.artifactDigest !== 'string' || !DIGEST_PATTERN.test(record.artifactDigest))
+            return false;
+    }
+    return true;
+}
+function assertContextShape(context, target) {
+    const invocationId = context.invocationId;
+    const evidenceDigest = context.evidenceDigest;
+    if (typeof invocationId !== 'string' || !INVOCATION_PATTERN.test(invocationId)
+        || target !== dispatchEffectTarget(invocationId)) {
+        throw new EffectVerifierError('malformed-response', 'Dispatch effect has an unexpected target or invocation');
+    }
+    if (typeof evidenceDigest !== 'string' || !DIGEST_PATTERN.test(evidenceDigest)) {
+        throw new EffectVerifierError('malformed-response', 'Dispatch effect has no evidence digest');
+    }
+    return {
+        invocationId,
+        evidenceDigest,
+        ...(typeof context.artifactPath === 'string' ? { artifactPath: context.artifactPath } : {}),
+        ...(typeof context.artifactDigest === 'string' ? { artifactDigest: context.artifactDigest } : {}),
+    };
+}
+/**
+ * Build the dispatch verifier bound to one project's supervisor evidence, or
+ * null when no actual supervisor evidence exists. Callers register the
+ * returned verifier (for example through the `extensions` of
+ * `buildCliVerifierRegistry`) only when it is non-null; a null result means
+ * the kind stays unregistered and reconciliation reports unknown.
+ */
+export function createDispatchVerifierIfSupervised(options) {
+    if (!options || typeof options.projectDir !== 'string' || !options.projectDir) {
+        throw new EffectLedgerError('usage', 'Dispatch verification needs a project directory', 'invalid-project');
+    }
+    if (!hasSupervisorEvidence(options.evidence))
+        return null;
+    const supervised = options.evidence;
+    // The record never picks its own strictness: artifacts root ONLY at the
+    // conductor-owned evidence directory, and the branch below is driven by
+    // what the SUPERVISOR evidence names, not by what the ledger context
+    // offers. No evidenceDir means no delegation target: `verify()` below
+    // reports `evidence-conflict` for an artifact check rather than silently
+    // widening the trusted root to `projectDir`.
+    const files = options.evidenceDir ? fileDigestVerifier({ root: options.evidenceDir }) : null;
+    return {
+        kind: DISPATCH_KIND,
+        version: DISPATCH_VERIFIER_VERSION,
+        canReportAbsent: true,
+        async verify(request) {
+            const context = assertContextShape((request.context ?? {}), request.target);
+            if (context.invocationId !== supervised.invocationId) {
+                throw new EffectVerifierError('malformed-response', 'Dispatch evidence is bound to a different invocation');
+            }
+            const expected = request.expected.digest ?? request.payloadDigest;
+            if (expected !== supervised.evidenceDigest || context.evidenceDigest !== supervised.evidenceDigest) {
+                return { result: 'unknown', reason: 'evidence-conflict', complete: false };
+            }
+            // Supervisor-driven: when supervised evidence names an artifact the
+            // verifier ALWAYS delegates to file.digest. A context that omits the
+            // artifact (or mismatches it), or a missing evidenceDir to delegate
+            // into, is evidence-conflict, never a present/complete downgrade and
+            // never a projectDir fallback.
+            if (supervised.artifactPath !== undefined) {
+                if (!files) {
+                    return { result: 'unknown', reason: 'evidence-conflict', complete: false };
+                }
+                if (context.artifactPath !== supervised.artifactPath || context.artifactDigest !== supervised.artifactDigest) {
+                    return { result: 'unknown', reason: 'evidence-conflict', complete: false };
+                }
+                const observation = await files.verify({
+                    ...request,
+                    kind: 'file.digest',
+                    target: `file:${supervised.artifactPath}@${supervised.artifactDigest}`,
+                    expected: { digest: supervised.artifactDigest },
+                });
+                if (observation.result !== 'present')
+                    return observation;
+                return {
+                    result: 'present', reason: 'state-match', complete: true,
+                    evidence: { invocationId: context.invocationId, evidenceDigest: supervised.evidenceDigest, artifact: supervised.artifactPath },
+                };
+            }
+            return {
+                result: 'present', reason: 'state-match', complete: true,
+                evidence: { invocationId: context.invocationId, evidenceDigest: supervised.evidenceDigest },
+            };
+        },
+    };
+}
+//# sourceMappingURL=dispatch-verifier.js.map

package/dist/src/effects/index.js

@@ -19,6 +19,7 @@ export { writeCheckpoint } from './checkpoint.js';
 export { checkpointDigest, verifyLedger, } from './verify.js';
 export { EFFECT_RETENTION_POLICY, purgeEffect } from './lifecycle.js';
 export { LEDGER_LOCK_NAME_PATTERN, LOCK_RECOVERY_KIND, LOCK_RECOVERY_VERIFIER_VERSION, inspectLedgerLock, inspectLedgerLocks, ledgerLockRecoveryVerifier, lockRecoveryTarget, recoverStaleLedgerLock, } from './lock-recovery.js';
+export { DISPATCH_KIND, DISPATCH_VERIFIER_VERSION, INVOCATION_PATTERN, createDispatchVerifierIfSupervised, dispatchEffectTarget, hasSupervisorEvidence, loadSupervisorEvidence, } from './dispatch-verifier.js';
 export { assertDigestOnly, containsRestrictedMaterial } from './redaction.js';
 export { EFFECT_SCHEMA_IDS, effectSchemaErrors, isEffectSchemaValid } from './schema.js';
 export { decisionLinkOf, verifyDecisionLinks, } from './decision-links.js';

package/dist/src/effects/types.js

@@ -41,7 +41,11 @@ export const UNKNOWN_REASONS = [
     'container-unreadable',
     'paging-incomplete',
     'consistency-lag',
-    'tracker-blocked',
+    'tracker-blocked', // Retained for existing ledger records.
+    'tracker-provider-unresolved',
+    'tracker-repository-mismatch',
+    'tracker-credential-missing',
+    'tracker-no-access-route',
     'malformed-response',
     'evidence-conflict',
 ];

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

@@ -13,6 +13,7 @@
  *
  * @see docs/contracts/effect-ledger.v1.md "Built-in verifiers"
  */
+import { signalChild } from '../../process/signal-child.mjs';
 import { spawn } from 'node:child_process';
 import { EffectVerifierError } from './types.js';
 export const GIT_VERIFIER_VERSION = '1.0.0';
@@ -31,7 +32,7 @@ function spawnRunner(repoDir, binary) {
         const collect = (sink) => (chunk) => {
             size += chunk.length;
             if (size > MAX_OUTPUT)
-                child.kill();
+                signalChild(child);
             else
                 sink.push(chunk);
         };

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/features/installer.js

@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process';
+import { boundedSpawnSync } from '../process/bounded-child-process.mjs';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { FEATURE_CATALOG, getFeature } from './catalog.js';
@@ -46,7 +46,7 @@ export async function installFeature(name, options = {}) {
     const root = options.root ?? getFeaturesRoot();
     await prepareFeatureManifest(feature, root);
     const npmCommand = options.npmCommand ?? (process.platform === 'win32' ? 'npm.cmd' : 'npm');
-    const result = spawnSync(npmCommand, ['install', '--prefix', root, '--no-audit', '--no-fund'], { stdio: 'inherit', env: process.env });
+    const result = boundedSpawnSync(npmCommand, ['install', '--prefix', root, '--no-audit', '--no-fund'], 'long', { stdio: 'inherit', env: process.env });
     if (result.error)
         throw result.error;
     if (result.status !== 0) {

package/dist/src/flow/graph-metadata.js

@@ -1,3 +1,4 @@
+import { assertMissionWorkerHandoff } from '../mission-protocol/codecs.js';
 /** A2A/telemetry metadata key reserved for the optional Flow graph profile. */
 export const AIWG_GRAPH_METADATA_KEY = 'aiwg.flow.graph';
 function nonEmpty(value) {
@@ -15,9 +16,12 @@ export function isGraphExecutionMetadata(value) {
         && nonEmpty(item.nodeRunId);
 }
 export function graphMetadataRecord(value) {
+    assertMissionWorkerHandoff(value, 'graph');
     return { [AIWG_GRAPH_METADATA_KEY]: value };
 }
 export function extractGraphMetadata(metadata) {
+    if (metadata)
+        assertMissionWorkerHandoff({ metadata }, 'graph');
     const value = metadata?.[AIWG_GRAPH_METADATA_KEY];
     return isGraphExecutionMetadata(value) ? value : undefined;
 }
@@ -28,6 +32,7 @@ export function extractGraphMetadata(metadata) {
  * member of this contract and is therefore dropped by construction.
  */
 export function projectGraphMetadata(value, audience) {
+    assertMissionWorkerHandoff(value, 'graph');
     if (!isGraphExecutionMetadata(value))
         throw new Error('Invalid graph execution metadata.');
     if (audience === 'internal')