@aiwg/cli 2026.8.16 → 2026.8.18

package/dist/src/cli/handlers/help.js

@@ -91,7 +91,7 @@ function displayHelp() {
     ]);
     helpGroup('FEATURES', [
         ['features', 'Show optional feature install status'],
-        ['cockpit [--status]', 'Launch the opt-in AIWG Cockpit control plane'],
+        ['cockpit [--status|doctor]', 'Launch Cockpit or diagnose its executor topology'],
     ]);
     helpGroup('VALIDATION', [
         ['validate-metadata [path]', 'Validate AIWG component metadata (defaults to agentic/code)'],

package/dist/src/cli/handlers/index.js

@@ -63,12 +63,13 @@ import { costReportHandler } from './cost-report.js';
 import { evidenceHandler } from './evidence.js';
 import { artifactVerifyHandler } from './artifact-verify.js';
 import { outputModeHandler } from './output-mode.js';
+import { installationHandler } from './installation.js';
 // Re-export individual handlers
 export { 
 // Maintenance
 helpHandler, versionHandler, authHandler, doctorHandler, contextFirewallHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
 // Framework management
-useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, 
+useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, installationHandler, 
 // Project
 newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
@@ -125,6 +126,7 @@ export const allHandlers = [
     contextFirewallHandler,
     updateHandler,
     refreshHandler,
+    installationHandler,
     regenerateHandler,
     workspaceContextHandler,
     // Framework management

package/dist/src/cli/handlers/installation.js

@@ -0,0 +1,79 @@
+import { getPackageRoot } from '../../channel/manager.mjs';
+import { adoptInstallation, inspectInstallation, loadInstallationIdentity, switchInstallation, } from '../../installation/manager.mjs';
+function valueAfter(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function display(status, json) {
+    if (json) {
+        console.log(JSON.stringify(status, null, 2));
+        return;
+    }
+    console.log('\nCanonical AIWG Installation');
+    console.log('===========================');
+    console.log(`State:             ${status.state}`);
+    console.log(`Canonical method:  ${status.identity?.method ?? '(unrecorded)'}`);
+    console.log(`Canonical root:    ${status.identity?.root ?? '(unrecorded)'}`);
+    console.log(`Manager:           ${status.identity?.managerExecutable ?? '(internal)'}`);
+    console.log(`Update strategy:   ${status.identity?.updateStrategy ?? '(unrecorded)'}`);
+    console.log(`Run mode:          ${status.identity?.runMode ?? '(unrecorded)'}`);
+    console.log(`Release channel:   ${status.identity?.channel ?? '(unrecorded)'}`);
+    console.log(`Actual method:     ${status.actualMethod}`);
+    console.log(`Actual root:       ${status.actualRoot}`);
+    if (status.drift.length > 0) {
+        console.log('Drift:');
+        for (const item of status.drift)
+            console.log(`  - ${item}`);
+    }
+    console.log('');
+}
+export const installationHandler = {
+    id: 'installation',
+    name: 'Installation',
+    description: 'Inspect, adopt, or deliberately switch the canonical global installation',
+    category: 'maintenance',
+    aliases: [],
+    async execute(ctx) {
+        const [action = 'show'] = ctx.args;
+        const json = ctx.args.includes('--json');
+        const actualRoot = getPackageRoot();
+        const common = {
+            actualRoot,
+            configDir: valueAfter(ctx.args, '--config-dir'),
+            managerExecutable: valueAfter(ctx.args, '--manager'),
+            channel: valueAfter(ctx.args, '--channel'),
+        };
+        if (action === 'show') {
+            const identity = loadInstallationIdentity({ ...common, createIfMissing: true });
+            display(inspectInstallation({ ...common, identity }), json);
+            return { exitCode: 0 };
+        }
+        if (action === 'adopt') {
+            const method = valueAfter(ctx.args, '--method');
+            const status = adoptInstallation({
+                ...common,
+                method,
+                runMode: valueAfter(ctx.args, '--run-mode'),
+            });
+            display(status, json);
+            return { exitCode: 0 };
+        }
+        if (action === 'switch') {
+            const root = valueAfter(ctx.args, '--root');
+            const method = valueAfter(ctx.args, '--method');
+            if (!root || !method) {
+                return { exitCode: 2, message: 'Usage: aiwg installation switch --root <path> --method <npm|web|source> [--manager <absolute-path>]' };
+            }
+            const status = switchInstallation({
+                ...common,
+                root,
+                method,
+                runMode: valueAfter(ctx.args, '--run-mode'),
+            });
+            display(status, json);
+            return { exitCode: 0 };
+        }
+        return { exitCode: 2, message: 'Usage: aiwg installation <show|adopt|switch> [options]' };
+    },
+};
+//# sourceMappingURL=installation.js.map

package/dist/src/cli/handlers/ralph.js

@@ -278,7 +278,8 @@ LFD LOOP CONTROLS (hard cumulative ceilings; loop stops with a best-output repor
                           Spawnable: claude, opencode, codex, hermes
   --dangerous             Enable unrestricted mode for the selected provider.
                           Passes the provider's native flag (e.g. --dangerously-skip-permissions
-                          for claude/opencode, --full-auto for codex). No effect if the
+                          for claude/opencode,
+                          --dangerously-bypass-approvals-and-sandbox for codex). No effect if the
                           provider doesn't have a dangerous mode flag.
   --params "<args>"       Pass arbitrary args verbatim to the agent binary.
                           Appended after all other flags. Quoted segments preserved.

package/dist/src/cli/handlers/refresh.js

@@ -242,8 +242,10 @@ export const refreshHandler = {
                         ui.success('Package up to date');
                 }
                 else {
-                    if (!quiet)
-                        ui.warn('Update check returned non-zero (may already be current)');
+                    return {
+                        exitCode: updateResult.exitCode,
+                        message: 'Installation update failed; refresh stopped before re-deployment. Run `aiwg installation show` for canonical-install diagnostics.',
+                    };
                 }
             }
         }

package/dist/src/cli/handlers/runtime-info.js

@@ -10,6 +10,8 @@
  */
 import path from 'path';
 import { AiwgError, EXIT_CODES, handlerResultFromError } from '../errors.js';
+import { getPackageRoot } from '../../channel/manager.mjs';
+import { inspectInstallation } from '../../installation/manager.mjs';
 function isMissingRuntimeCatalogError(error) {
     return error instanceof Error && error.message.includes('No catalog found');
 }
@@ -237,8 +239,9 @@ async function handleRuntimeInfo(args, cwd = process.cwd()) {
             await discovery.discover();
             summary = await discovery.getSummary();
         }
+        const installation = inspectInstallation({ actualRoot: getPackageRoot() });
         if (hasJson) {
-            console.log(JSON.stringify(summary, null, 2));
+            console.log(JSON.stringify({ ...summary, installation }, null, 2));
         }
         else {
             console.log(`\nRuntime Environment Summary`);
@@ -256,6 +259,11 @@ async function handleRuntimeInfo(args, cwd = process.cwd()) {
             console.log(`\nTotal: ${summary.totalTools} verified tools`);
             console.log(`\nLast Discovery: ${summary.lastDiscovery}`);
             console.log(`Catalog: ${summary.catalogPath}`);
+            console.log(`\nAIWG Installation:`);
+            console.log(`  Canonical: ${installation.identity?.method ?? 'unrecorded'} at ${installation.identity?.root ?? '(unrecorded)'}`);
+            console.log(`  Actual:    ${installation.actualMethod} at ${installation.actualRoot}`);
+            console.log(`  Run mode:  ${installation.identity?.runMode ?? '(unrecorded)'}`);
+            console.log(`  State:     ${installation.state}`);
             // Scheduler backend detection
             const { execSync } = await import('child_process');
             let schedulerBackend = 'external trigger required (system cron/systemd/CI)';

package/dist/src/cli/handlers/sdlc-accelerate.js

@@ -123,7 +123,8 @@ AGENT OPTIONS:
                           IDE-integrated (guidance only): copilot, cursor, factory, warp, windsurf
   --dangerous             Enable unrestricted mode (skips permission prompts).
                           Maps to the provider's native flag — e.g. claude gets
-                          --dangerously-skip-permissions, codex gets --full-auto.
+                          --dangerously-skip-permissions, codex gets
+                          --dangerously-bypass-approvals-and-sandbox.
                           Has no effect on providers that don't support it.
   --params "<args>"       Pass arbitrary args directly to the agent binary.
                           Appended verbatim after all other flags. You are

package/dist/src/cli/handlers/serve.js

@@ -27,8 +27,14 @@ const pushSecretRegistry = new PushSecretRegistry();
 const webhookIdempotency = new IdempotencyCache();
 const DEFAULT_PORT = 7337;
 const DEFAULT_HOST = '127.0.0.1';
+function readA2AProtocolPolicy(value) {
+    const policy = value ?? '0.3';
+    if (policy === '0.3' || policy === '1.0' || policy === 'auto')
+        return policy;
+    throw new Error(`AIWG_A2A_PROTOCOL_POLICY must be 0.3, 1.0, or auto (received '${policy}')`);
+}
 /**
- * Parse --port, --bind, --no-open, --read-only flags from args
+ * Parse dashboard and A2A negotiation flags from args.
  */
 function parseServeArgs(args) {
     let port = DEFAULT_PORT;
@@ -36,6 +42,9 @@ function parseServeArgs(args) {
     let open = true;
     let readOnly = false;
     let sandbox = null;
+    let a2aProtocolPolicy;
+    let allowA2AProtocolFallback;
+    let allowLegacyExecutorFallback;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '--port' && args[i + 1]) {
@@ -58,8 +67,33 @@ function parseServeArgs(args) {
         else if (arg === '--read-only') {
             readOnly = true;
         }
+        else if (arg === '--a2a-protocol' && args[i + 1]) {
+            a2aProtocolPolicy = readA2AProtocolPolicy(args[i + 1]);
+            i++;
+        }
+        else if (arg === '--a2a-protocol-fallback') {
+            allowA2AProtocolFallback = true;
+        }
+        else if (arg === '--no-a2a-protocol-fallback') {
+            allowA2AProtocolFallback = false;
+        }
+        else if (arg === '--a2a-legacy-executor-fallback') {
+            allowLegacyExecutorFallback = true;
+        }
+        else if (arg === '--no-a2a-legacy-executor-fallback') {
+            allowLegacyExecutorFallback = false;
+        }
     }
-    return { port, host, open, readOnly, sandbox };
+    return {
+        port,
+        host,
+        open,
+        readOnly,
+        sandbox,
+        ...(a2aProtocolPolicy ? { a2aProtocolPolicy } : {}),
+        ...(allowA2AProtocolFallback !== undefined ? { allowA2AProtocolFallback } : {}),
+        ...(allowLegacyExecutorFallback !== undefined ? { allowLegacyExecutorFallback } : {}),
+    };
 }
 // ============================================================
 // WebSocket routing (#851)
@@ -499,6 +533,13 @@ async function setupWebSockets(httpServer, readOnly) {
  * @see #1277 — moves the integration suite off spawn-based testing
  */
 export async function startServer(opts) {
+    const configuredA2AProtocolPolicy = opts.a2aProtocolPolicy
+        ?? readA2AProtocolPolicy(process.env['AIWG_A2A_PROTOCOL_POLICY']);
+    const configuredA2AProtocolFallback = opts.allowA2AProtocolFallback
+        ?? process.env['AIWG_A2A_PROTOCOL_FALLBACK'] === 'true';
+    const configuredLegacyExecutorFallback = configuredA2AProtocolPolicy !== '1.0'
+        && (opts.allowLegacyExecutorFallback
+            ?? process.env['AIWG_A2A_LEGACY_EXECUTOR_FALLBACK'] !== 'false');
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let honoMod;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -760,8 +801,32 @@ export async function startServer(opts) {
         let a2aInstanceId;
         let dispatchPath = 'v2';
         let a2aTask = undefined;
+        let a2aProtocolVersion;
+        let a2aInterface;
+        let a2aFallbackReason;
+        const a2aProtocolPolicy = configuredA2AProtocolPolicy;
         try {
             const result = await routeDispatch(executor, payload, {
+                a2aProtocolPolicy,
+                allowA2AProtocolFallback: configuredA2AProtocolFallback,
+                allowLegacyExecutorFallback: configuredLegacyExecutorFallback,
+                onA2AProtocolSelection: (info) => {
+                    telemetryStore.ingest(createEvent('a2a.protocol.selected', sessionId, {
+                        selected_version: info.selected,
+                        policy: info.policy,
+                        ...(info.interface ? {
+                            protocol_binding: info.interface.protocolBinding,
+                            interface_url: info.interface.url,
+                        } : {}),
+                    }, missionId));
+                },
+                onA2AProtocolFallback: (info) => {
+                    telemetryStore.ingest(createEvent('a2a.protocol.fallback', sessionId, {
+                        from_version: info.from,
+                        to_version: info.to,
+                        reason: info.reason,
+                    }, missionId));
+                },
                 onV1Fallback: (info) => {
                     logServeWarn('dispatch', `v1 fallback for executor ${info.executorId}: ${info.reason}`);
                     telemetryStore.ingest(createEvent('v1.dispatch.fallback', sessionId, info, missionId));
@@ -775,6 +840,9 @@ export async function startServer(opts) {
             dispatchPath = result.dispatchPath;
             a2aInstanceId = result.a2aInstanceId;
             a2aTask = result.task;
+            a2aProtocolVersion = result.a2aProtocolVersion;
+            a2aInterface = result.a2aInterface;
+            a2aFallbackReason = result.a2aFallbackReason;
             if (result.estimatedStart)
                 estimatedStart = result.estimatedStart;
         }
@@ -796,12 +864,22 @@ export async function startServer(opts) {
             return c.json({ error: errorTag, detail: msg }, status);
         }
         // 4. Record the mission and emit telemetry
+        if (a2aProtocolVersion && a2aInterface) {
+            executorRegistry.recordA2AProtocolSelection(executor.executorId, {
+                policy: a2aProtocolPolicy,
+                selectedVersion: a2aProtocolVersion,
+                interface: a2aInterface,
+                ...(a2aFallbackReason ? { fallbackReason: a2aFallbackReason } : {}),
+            });
+        }
         executorRegistry.assignMission(missionId, executor.executorId);
         if (dispatchPath === 'v2' && a2aTask && a2aInstanceId) {
             void observeA2ATerminalState(executorRegistry, executor, missionId, a2aInstanceId, a2aTask, {
                 onError: (err) => {
                     logServeWarn('dispatch', `A2A terminal observer failed for mission ${missionId}: ${err.message ?? String(err)}`);
                 },
+                ...(a2aProtocolVersion ? { protocolVersion: a2aProtocolVersion } : {}),
+                ...(a2aInterface ? { selectedInterface: a2aInterface } : {}),
             });
         }
         telemetryStore.ingest(createEvent('mission.dispatch', sessionId, {
@@ -809,6 +887,8 @@ export async function startServer(opts) {
             executorId: executor.executorId,
             objective: payload.objective,
             completion: payload.completion,
+            ...(a2aProtocolVersion ? { a2a_protocol_version: a2aProtocolVersion } : {}),
+            ...(a2aFallbackReason ? { a2a_fallback_reason: a2aFallbackReason } : {}),
         }, missionId));
         // 5. Return 202 Accepted
         const dispatchResp = {
@@ -819,6 +899,14 @@ export async function startServer(opts) {
         };
         if (a2aInstanceId)
             dispatchResp.a2a_instance_id = a2aInstanceId;
+        if (a2aProtocolVersion)
+            dispatchResp.a2a_protocol_version = a2aProtocolVersion;
+        if (a2aInterface) {
+            dispatchResp.a2a_protocol_binding = a2aInterface.protocolBinding;
+            dispatchResp.a2a_interface_url = a2aInterface.url;
+        }
+        if (a2aFallbackReason)
+            dispatchResp.a2a_fallback_reason = a2aFallbackReason;
         if (estimatedStart)
             dispatchResp.estimated_start = estimatedStart;
         return c.json(dispatchResp, 202);
@@ -947,6 +1035,7 @@ export async function startServer(opts) {
         const result = await handleWebhook(configId, bodyBuf, signature, eventId, {
             registry: pushSecretRegistry,
             idempotency: webhookIdempotency,
+            contentType: c.req.header('content-type') ?? undefined,
             route: async (entry, event) => {
                 // Append to mission recentEvents via a synthesized envelope.
                 // The 'mission.webhook' event type falls through the registry's
@@ -990,11 +1079,17 @@ export async function startServer(opts) {
         if (!p.secret || typeof p.secret !== 'string' || p.secret.length < 16) {
             return c.json({ error: 'secret is required and must be ≥16 chars' }, 400);
         }
+        if (p.protocolVersion === '1.0' && !p.taskId) {
+            return c.json({ error: 'taskId is required for A2A 1.0 push ownership scope' }, 400);
+        }
         pushSecretRegistry.register({
             configId: p.configId,
             secret: p.secret,
             ...(p.missionId ? { missionId: p.missionId } : {}),
             ...(p.taskId ? { taskId: p.taskId } : {}),
+            ...(p.contextId ? { contextId: p.contextId } : {}),
+            ...(p.protocolVersion ? { protocolVersion: p.protocolVersion } : {}),
+            ...(p.taskOwner ? { taskOwner: p.taskOwner } : {}),
             ...(p.metadata ? { metadata: p.metadata } : {}),
         });
         return c.json({ ok: true, configId: p.configId }, 201);
@@ -1749,10 +1844,18 @@ export const serveHandler = {
     category: 'project',
     aliases: [],
     async execute(ctx) {
-        const { port, host, open, readOnly } = parseServeArgs(ctx.args);
+        const { port, host, open, readOnly, a2aProtocolPolicy, allowA2AProtocolFallback, allowLegacyExecutorFallback, } = parseServeArgs(ctx.args);
         let server;
         try {
-            server = await startServer({ port, host, readOnly, frameworkRoot: ctx.frameworkRoot });
+            server = await startServer({
+                port,
+                host,
+                readOnly,
+                frameworkRoot: ctx.frameworkRoot,
+                ...(a2aProtocolPolicy ? { a2aProtocolPolicy } : {}),
+                ...(allowA2AProtocolFallback !== undefined ? { allowA2AProtocolFallback } : {}),
+                ...(allowLegacyExecutorFallback !== undefined ? { allowLegacyExecutorFallback } : {}),
+            });
         }
         catch (error) {
             const { handlerResultFromError } = await import('../errors.js');

package/dist/src/cli/handlers/session.js

@@ -21,6 +21,7 @@ import { spawnSync } from 'child_process';
 import { ensureRuntimeHome, writeProfileConfig, launchWithProfile } from '../../mcp/adapters/codex-runtime.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
 import { forceUpdateCheck } from '../../update/checker.mjs';
+import { updateInstallation } from '../../update/service.mjs';
 import { readAiwgConfig, getDeploymentSummary, VALID_PROVIDERS, } from '../../config/aiwg-config.js';
 import { getProviderConfig, isSpawnableProvider, PROVIDER_CONFIGS, } from '../agent-spawn.js';
 import { useHandler as useFrameworkHandler } from './use.js';
@@ -84,8 +85,11 @@ async function checkAndUpdateVersion(noRepair) {
         debug('cli:session:update', 'forceUpdateCheck failed', err);
         if (!noRepair) {
             console.log('  Version check failed — attempting sync...');
-            const r = spawnSync('npm', ['install', '-g', 'aiwg@latest'], { stdio: 'inherit' });
-            if (r.status !== 0) {
+            try {
+                await updateInstallation();
+            }
+            catch (updateError) {
+                debug('cli:session:update', 'canonical installation update failed', updateError);
                 console.warn('  WARN  Could not update aiwg — continuing with current version.');
                 return false;
             }
@@ -103,10 +107,11 @@ function runDoctor(_frameworkRoot, cwd) {
 }
 /**
  * Attempt to repair a failed doctor result.
- * Strategy: `aiwg sync` first; if that fails, offer full reinstall.
+ * Strategy: `aiwg sync`; package repair remains bound to the canonical update
+ * strategy and never falls through to an arbitrary npm on PATH.
  * Returns true if repair succeeded (doctor now passes).
  */
-function repairInstallation(frameworkRoot, cwd, provider, installedFrameworks) {
+function repairInstallation(frameworkRoot, cwd, provider) {
     // Strategy 1: sync (update + redeploy)
     console.log('\n  Attempting auto-repair via `aiwg sync`...');
     const syncResult = spawnSync(process.execPath, [process.argv[1], 'sync'], { stdio: 'inherit', cwd });
@@ -118,29 +123,13 @@ function repairInstallation(frameworkRoot, cwd, provider, installedFrameworks) {
             return true;
         }
     }
-    // Strategy 2: full reinstall
-    console.log('\n  Sync did not fully resolve the issue. Attempting full reinstall...');
-    const reinstallResult = spawnSync('npm', ['install', '-g', 'aiwg@latest'], { stdio: 'inherit' });
-    if (reinstallResult.status === 0 && installedFrameworks.length > 0) {
-        // Redeploy all installed frameworks for this provider
-        console.log(`\n  Redeploying frameworks to ${provider}...`);
-        for (const fw of installedFrameworks) {
-            spawnSync(process.execPath, [process.argv[1], 'use', fw, '--provider', provider], { stdio: 'inherit', cwd });
-        }
-        // Final doctor check
-        const finalOk = runDoctor(frameworkRoot, cwd);
-        if (finalOk) {
-            console.log('  OK  Full reinstall + redeploy succeeded.');
-            return true;
-        }
-    }
     // Could not auto-repair
     console.log(`
   ✗  Auto-repair could not resolve all issues.
 
   Manual options:
-    aiwg sync                       — sync and redeploy
-    npm install -g aiwg@latest      — reinstall package
+    aiwg installation show          — inspect canonical install drift
+    aiwg refresh                    — update and redeploy canonically
     aiwg use all --provider ${provider.padEnd(10)} — redeploy all frameworks
 
   Report this issue:
@@ -291,10 +280,7 @@ export const sessionHandler = {
         console.log('\n  Running health checks...');
         const doctorOk = runDoctor(frameworkRoot, cwd);
         if (!doctorOk && !noRepair) {
-            // Read installed frameworks before attempting repair (needed for redeploy)
-            const config = await readAiwgConfig(cwd);
-            const installedFrameworks = Object.keys(config?.installed ?? {});
-            const repaired = repairInstallation(frameworkRoot, cwd, provider, installedFrameworks);
+            const repaired = repairInstallation(frameworkRoot, cwd, provider);
             if (!repaired) {
                 // Repair failed — still continue (user was already informed)
             }

package/dist/src/cli/handlers/use.js

@@ -52,7 +52,7 @@ import { generate as generateContextFiles, discoverDeployedArtifacts, } from '..
 import { verifyModelWrapperDeployment } from '../../models/wrapper-deployment.js';
 import { loadGraphIndexFile } from '../../artifacts/index-reader.js';
 import { aggregateUseDeploymentResult, buildDryRunUseResult, renderUseDeploymentResult, verifyProviderDeployment, } from '../services/deployment-verification.js';
-import { finalizeProviderTransformationReceipt, sourceVerificationsFromSignedWebRelease, } from '../../providers/transformation-receipt-integration.js';
+import { finalizeProviderTransformationReceipt, providerReceiptHasLocalSources, sourceVerificationsFromSignedWebRelease, } from '../../providers/transformation-receipt-integration.js';
 import { loadResourceTrustRootFile, resolveWebRelease, } from '../../resources/web-release.js';
 import { createResourceCredentialProvider } from '../../auth/resource-credentials.js';
 /**
@@ -75,10 +75,16 @@ function providerReceiptWebReleaseOptions() {
             : {}),
     };
 }
-async function signedProviderSourceVerifications(options) {
+function releaseResourceUnavailable(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /fetch failed|request timed out|no fetch implementation/i.test(message);
+}
+export async function resolveProviderReceiptSource(options) {
+    if (await providerReceiptHasLocalSources(options))
+        return { sourceDisposition: 'local-source' };
     const versionInfo = await getVersionInfo();
     if (versionInfo.devMode)
-        return undefined;
+        return { sourceDisposition: 'local-source' };
     const releaseOptions = providerReceiptWebReleaseOptions();
     let release;
     try {
@@ -90,15 +96,24 @@ async function signedProviderSourceVerifications(options) {
         // Protected production resources require the authenticated release
         // credential. A configured alternate endpoint may intentionally be public.
         if (!token && releaseOptions.baseUrl === undefined)
-            return undefined;
-        release = await resolveWebRelease({
-            ...releaseOptions,
-            selector: versionInfo.version,
-            credentialProvider: async () => token,
-        });
+            return { sourceDisposition: 'source-unavailable' };
+        try {
+            release = await resolveWebRelease({
+                ...releaseOptions,
+                selector: versionInfo.version,
+                credentialProvider: async () => token,
+            });
+        }
+        catch (error) {
+            if (releaseResourceUnavailable(error))
+                return { sourceDisposition: 'source-unavailable' };
+            throw error;
+        }
     }
     const verifications = await sourceVerificationsFromSignedWebRelease(options, release);
-    return Object.keys(verifications).length > 0 ? verifications : undefined;
+    return Object.keys(verifications).length > 0
+        ? { sourceVerifications: verifications }
+        : { sourceDisposition: 'verification-failed' };
 }
 /**
  * Framework name to deploy mode mapping.
@@ -1005,6 +1020,79 @@ async function countBundleDeployedArtifacts(bundlePath, target, provider) {
         rules: await countDeployedBundleFiles(bundlePath, 'rules', target, paths.rules, ['.md', '.mdc']),
     };
 }
+const SKILL_SUPPORT_REFERENCE = /(?:^|[\s`('"\[])((?:templates|references|scripts|assets)\/[A-Za-z0-9._@/+\-]+)(?=$|[\s`)'"\],:;])/gm;
+/**
+ * Project skill-relative support files may live beside the skill or at the
+ * bundle root (plugin payloads commonly share report templates). Materialize
+ * only paths explicitly named by SKILL.md, and fail closed on missing or
+ * unsafe sources so a deployed instruction can never point at absent assets.
+ */
+async function reconcileProjectLocalSkillAssets(bundlePath, target, provider) {
+    const skillsRoot = path.join(bundlePath, 'skills');
+    let skillDirs;
+    try {
+        skillDirs = (await fs.readdir(skillsRoot, { withFileTypes: true }))
+            .filter(entry => entry.isDirectory())
+            .map(entry => entry.name);
+    }
+    catch {
+        return;
+    }
+    const paths = getProviderPaths(provider);
+    const kernelSkillsPath = getProviderKernelSkillsPath(provider);
+    const deployRoots = [...new Set([
+            paths.skills,
+            kernelSkillsPath,
+        ].filter((value) => Boolean(value)).map(value => resolveDeployPath(target, value)))];
+    for (const skillName of skillDirs) {
+        const sourceSkillDir = path.join(skillsRoot, skillName);
+        const sourceSkillMd = path.join(sourceSkillDir, 'SKILL.md');
+        let content;
+        try {
+            content = await fs.readFile(sourceSkillMd, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const references = [...new Set([...content.matchAll(SKILL_SUPPORT_REFERENCE)].map(match => match[1]))];
+        for (const relative of references) {
+            const normalized = path.posix.normalize(relative);
+            if (normalized !== relative || normalized.startsWith('../') || path.isAbsolute(normalized)) {
+                throw new Error(`unsafe skill support reference '${relative}' in ${sourceSkillMd}`);
+            }
+            const candidates = [path.join(sourceSkillDir, normalized), path.join(bundlePath, normalized)];
+            let source;
+            for (const candidate of candidates) {
+                try {
+                    const stat = await fs.lstat(candidate);
+                    if (stat.isFile() && !stat.isSymbolicLink()) {
+                        source = candidate;
+                        break;
+                    }
+                }
+                catch { /* try bundle-root fallback */ }
+            }
+            if (!source)
+                throw new Error(`missing skill support asset '${relative}' referenced by ${sourceSkillMd}`);
+            let deployedSkillRoot;
+            for (const root of deployRoots) {
+                // The deployer may select the bulk or kernel tier; use the tier that
+                // actually contains this skill's transformed SKILL.md.
+                if (await fileExists(path.join(root, skillName, 'SKILL.md'))) {
+                    deployedSkillRoot = root;
+                    break;
+                }
+            }
+            if (!deployedSkillRoot)
+                throw new Error(`deployed skill '${skillName}' not found while reconciling support assets`);
+            const destination = path.join(deployedSkillRoot, skillName, ...normalized.split('/'));
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            await fs.copyFile(source, destination);
+            const mode = (await fs.stat(source)).mode & 0o777;
+            await fs.chmod(destination, mode);
+        }
+    }
+}
 /**
  * Deploy a single project-local bundle to one provider via deploy-agents.mjs.
  * Runs the same script and flags used for upstream addons, with the bundle
@@ -1072,6 +1160,15 @@ async function deployOneProjectLocalBundle(opts) {
             env: { AIWG_ROOT: frameworkRoot },
         });
         exitCode = result.exitCode;
+        if (exitCode === 0 && !dryRun) {
+            try {
+                await reconcileProjectLocalSkillAssets(bundle.artifactPath, target, provider);
+            }
+            catch (error) {
+                ui.warn(`Project-local skill asset deployment failed for '${bundle.id}': ${error.message}`);
+                exitCode = 1;
+            }
+        }
     }
     if (exitCode === 0 && cliCommandCount > 0) {
         try {
@@ -2017,10 +2114,18 @@ export class UseHandler {
                             scope: effectiveScope,
                             requestedBundles: [requestedBundle],
                         };
-                        const sourceVerifications = await signedProviderSourceVerifications(receiptOptions);
-                        await finalizeProviderTransformationReceipt({ ...receiptOptions, sourceVerifications });
+                        const sourceResolution = await resolveProviderReceiptSource(receiptOptions);
+                        await finalizeProviderTransformationReceipt({ ...receiptOptions, ...sourceResolution });
                     }
                     catch (error) {
+                        await finalizeProviderTransformationReceipt({
+                            projectRoot: projectDir,
+                            frameworkRoot,
+                            provider,
+                            scope: effectiveScope,
+                            requestedBundles: [requestedBundle],
+                            sourceDisposition: 'verification-failed',
+                        }).catch(() => undefined);
                         originalConsole.warn(`Provider receipt finalization failed for ${provider}: ${error instanceof Error ? error.message : String(error)}`);
                     }
                 }

package/dist/src/cli/handlers/utilities.js

@@ -777,6 +777,10 @@ export const updateHandler = {
                 console.log(`${update.message}\n`);
             }
             catch (error) {
+                if (error.code === 'AIWG_INSTALLATION_DRIFT'
+                    || error.code === 'AIWG_INSTALLATION_INVALID') {
+                    return { exitCode: 78, message: error instanceof Error ? error.message : String(error) };
+                }
                 console.error(`Warning: Update check failed: ${error instanceof Error ? error.message : String(error)}`);
                 console.log('Continuing with re-deployment...\n');
             }