@aiwg/cli 2026.9.7 → 2026.9.9

package/dist/src/cli/handlers/repo-access.js

@@ -1,13 +1,16 @@
 import { checkRepoAccess, findRepoEntry, formatRepoAccessEntry, loadRepoAccessManifest, } from '../../policy/repo-access.js';
 import { resolveWorkspace } from '../../config/workspace.js';
+import { getProjectDir, readAiwgConfig, writeAiwgConfig, WORKSPACE_REPO_ACTIONS, } from '../../config/aiwg-config.js';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
 function valueAfter(args, flag) {
     const index = args.indexOf(flag);
     if (index < 0)
         return null;
     return args[index + 1] ?? null;
 }
-function printHelp() {
-    console.log(`
+function usage() {
+    return `
   aiwg repo-access — repo authorization manifest preflight
 
   Usage:
@@ -15,12 +18,149 @@ function printHelp() {
     aiwg repo-access status
     aiwg repo-access explain --path <repo-or-file>
     aiwg repo-access check --path <repo-or-file> --action <read|write|commit|push|issue-comment|service-action|destructive>
+    aiwg repo-access add --path <p> --name <n> --allow <a,b,c> [--provider <gitea|github|gitlab>] [--notes "..."]
+    aiwg repo-access remove --name <n>
+    aiwg repo-access audit
 
   Manifest:
     .aiwg/aiwg.config workspace + repos blocks (preferred)
     .aiwg/ops/security/repo-access.manifest.yaml
     .aiwg/security/repo-access.manifest.yaml (fallback)
-`);
+`;
+}
+function printHelp() {
+    console.log(usage());
+}
+/**
+ * The manifest is mandatory and default-deny, but until now it had no write path:
+ * registering a repo meant hand-editing JSON, and the rule's own recovery text
+ * ("ask for a manifest update") had no supported way to be carried out (#2531).
+ */
+async function addRepo(ctx, args) {
+    const repoPath = valueAfter(args, '--path');
+    const name = valueAfter(args, '--name');
+    const allowRaw = valueAfter(args, '--allow');
+    if (!repoPath)
+        return { exitCode: 2, message: 'repo-access add requires --path <repo-or-file>' };
+    if (!name)
+        return { exitCode: 2, message: 'repo-access add requires --name <name>' };
+    if (!allowRaw) {
+        return { exitCode: 2, message: `repo-access add requires --allow <${WORKSPACE_REPO_ACTIONS.join('|')}>` };
+    }
+    const allowed = allowRaw.split(',').map((item) => item.trim()).filter(Boolean);
+    const invalid = allowed.filter((item) => !WORKSPACE_REPO_ACTIONS.includes(item));
+    if (invalid.length > 0) {
+        return {
+            exitCode: 2,
+            message: `Unknown action(s): ${invalid.join(', ')}. Valid: ${WORKSPACE_REPO_ACTIONS.join(', ')}`,
+        };
+    }
+    const provider = valueAfter(args, '--provider') ?? undefined;
+    if (provider && !['gitea', 'github', 'gitlab'].includes(provider)) {
+        return { exitCode: 2, message: `Unknown provider: ${provider}. Valid: gitea, github, gitlab` };
+    }
+    const projectDir = getProjectDir(ctx, args);
+    const config = await readAiwgConfig(projectDir);
+    if (!config)
+        return { exitCode: 2, message: `No .aiwg/aiwg.config found in ${projectDir}` };
+    const repos = config.repos ? [...config.repos] : [];
+    const entry = {
+        name,
+        path: repoPath,
+        allowed: allowed,
+        ...(provider ? { provider: provider } : {}),
+        ...(valueAfter(args, '--notes') ? { notes: valueAfter(args, '--notes') } : {}),
+    };
+    const existingIndex = repos.findIndex((repo) => repo.name === name);
+    if (existingIndex >= 0) {
+        repos[existingIndex] = { ...repos[existingIndex], ...entry };
+    }
+    else {
+        repos.push(entry);
+    }
+    await writeAiwgConfig(projectDir, { ...config, repos });
+    console.log(`${existingIndex >= 0 ? 'Updated' : 'Registered'} ${name}: ${repoPath} [${allowed.join(', ')}]`);
+    return { exitCode: 0 };
+}
+async function removeRepo(ctx, args) {
+    const name = valueAfter(args, '--name');
+    if (!name)
+        return { exitCode: 2, message: 'repo-access remove requires --name <name>' };
+    const projectDir = getProjectDir(ctx, args);
+    const config = await readAiwgConfig(projectDir);
+    if (!config)
+        return { exitCode: 2, message: `No .aiwg/aiwg.config found in ${projectDir}` };
+    const repos = config.repos ?? [];
+    const remaining = repos.filter((repo) => repo.name !== name);
+    if (remaining.length === repos.length) {
+        return { exitCode: 1, message: `No repo named '${name}' in the manifest.` };
+    }
+    // An empty `repos` array fails config validation, so drop the key entirely
+    // when the last entry goes rather than writing a config that cannot be read back.
+    const next = { ...config };
+    if (remaining.length > 0)
+        next.repos = remaining;
+    else
+        delete next.repos;
+    await writeAiwgConfig(projectDir, next);
+    console.log(`Removed ${name}. It now falls under the default-deny policy.`);
+    return { exitCode: 0 };
+}
+/**
+ * Report workspace subdirectories that are git repos but carry no manifest entry.
+ * Manifests drift out of sync with reality; on the reporting workspace two
+ * actively-used repos were both unlisted and therefore formally denied (#2531).
+ */
+async function auditRepos(ctx, args) {
+    // A missing manifest is the most important case to audit, not a reason to fail:
+    // every repo is then unlisted and formally denied.
+    let manifest = null;
+    try {
+        manifest = loadRepoAccessManifest(ctx.cwd);
+    }
+    catch {
+        manifest = null;
+    }
+    const root = manifest?.workspaceProjectRoot ?? getProjectDir(ctx, args);
+    let children = [];
+    try {
+        children = readdirSync(root);
+    }
+    catch {
+        return { exitCode: 2, message: `Cannot read workspace root: ${root}` };
+    }
+    const unlisted = [];
+    for (const child of children.sort()) {
+        if (child.startsWith('.'))
+            continue;
+        const full = nodePath.join(root, child);
+        try {
+            if (!statSync(full).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (!existsSync(nodePath.join(full, '.git')))
+            continue;
+        if (manifest && findRepoEntry(manifest, full, ctx.cwd))
+            continue;
+        unlisted.push(child);
+    }
+    console.log(`Repo access manifest: ${manifest?.path ?? '(none — every repo is denied)'}`);
+    console.log(`Workspace root: ${root}`);
+    console.log(`Default policy: ${manifest?.defaultPolicy ?? 'deny'}`);
+    if (unlisted.length === 0) {
+        console.log('All git repositories under the workspace root are registered.');
+        return { exitCode: 0 };
+    }
+    console.log('');
+    console.log(`Unlisted git repositories (${unlisted.length}) — denied by default:`);
+    for (const name of unlisted) {
+        console.log(`  - ${name}`);
+        console.log(`      aiwg repo-access add --path ./${name} --name ${name} --allow read`);
+    }
+    return { exitCode: 1 };
 }
 async function handleRepoAccess(ctx) {
     const [subcommand = 'help', ...args] = ctx.args;
@@ -28,6 +168,14 @@ async function handleRepoAccess(ctx) {
         printHelp();
         return { exitCode: 0 };
     }
+    // add/remove write .aiwg/aiwg.config directly and must work before any manifest
+    // exists — registering the first repo is exactly the bootstrap case (#2531).
+    if (subcommand === 'add')
+        return await addRepo(ctx, args);
+    if (subcommand === 'remove')
+        return await removeRepo(ctx, args);
+    if (subcommand === 'audit')
+        return await auditRepos(ctx, args);
     try {
         const manifest = loadRepoAccessManifest(ctx.cwd);
         if (subcommand === 'list' || subcommand === 'status') {
@@ -87,7 +235,7 @@ async function handleRepoAccess(ctx) {
             }
             return { exitCode: decision.allowed ? 0 : 1 };
         }
-        return { exitCode: 2, message: `Unknown repo-access subcommand: ${subcommand}` };
+        return { exitCode: 2, message: `Unknown repo-access subcommand: ${subcommand}\n${usage()}` };
     }
     catch (error) {
         return {
@@ -103,6 +251,9 @@ export const repoAccessHandler = {
     description: 'Validate and query repo access manifest permissions',
     category: 'utility',
     aliases: [],
+    async help() {
+        return { exitCode: 0, message: usage(), rawOutput: true };
+    },
     execute: handleRepoAccess,
 };
 export const repoAccessHandlers = [repoAccessHandler];

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

@@ -1,6 +1,6 @@
 import { spawnSync } from 'child_process';
 import { existsSync } from 'fs';
-import { emptyConfig, getConfigPath, getProjectDir, readAiwgConfig, resolveRemoteProvider, VALID_PROVIDERS, writeAiwgConfig, } from '../../config/aiwg-config.js';
+import { emptyConfig, FORCE_PUSH_POLICY_ALIAS_NOTE, normalizeForcePushPolicy as normalizeForcePushPolicyShared, getConfigPath, getProjectDir, readAiwgConfig, resolveRemoteProvider, VALID_PROVIDERS, writeAiwgConfig, } from '../../config/aiwg-config.js';
 import { AiwgError, EXIT_CODES } from '../errors.js';
 import { askChoice, askString, askYesNo, createPromptInterface } from '../prompt-utils.js';
 import * as ui from '../ui.js';
@@ -165,11 +165,11 @@ function secondaryRemotes(remotes, primary, issueTracker, ci) {
     }));
 }
 function normalizeForcePushPolicy(value, warnings) {
-    if (value === 'main-only-blocked') {
-        warnings.push('delivery.force_push_policy=main-only-blocked is a legacy alias; setup normalized it to own-branch-only.');
-        return 'own-branch-only';
+    const { policy, deprecatedFrom } = normalizeForcePushPolicyShared(value);
+    if (deprecatedFrom) {
+        warnings.push(`delivery.force_push_policy=${deprecatedFrom} is a legacy alias; setup normalized it to ${policy}. ${FORCE_PUSH_POLICY_ALIAS_NOTE}`);
     }
-    return value;
+    return policy;
 }
 function cloneConfig(config) {
     return JSON.parse(JSON.stringify(config));

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

@@ -185,6 +185,18 @@ function printFullMatrix(matrix) {
     }
 }
 // ── Main execution ─────────────────────────────────────────────────────────────
+function permissionsUsage() {
+    return `
+  aiwg steward permissions — authorization model audit and normalization
+
+  Usage:
+    aiwg steward permissions audit                 Find normalized-model errors and legacy grants
+    aiwg steward permissions migrate --dry-run     Preview legacy permission normalization
+    aiwg steward permissions migrate --apply       Back up and atomically normalize config
+
+  Reads .aiwg/aiwg.config authorization block. Migration backs up before writing.
+`;
+}
 async function handleSteward(args, ctx) {
     const subcommand = args[0];
     if (!subcommand || subcommand === '--help' || subcommand === 'help') {
@@ -221,6 +233,11 @@ async function handleSteward(args, ctx) {
     }
     if (subcommand === 'permissions') {
         const operation = args[1];
+        // `<namespace> --help` must reach the same usage block bare invocation prints (#2533).
+        if (!operation || operation === 'help' || operation === '--help' || operation === '-h') {
+            console.log(permissionsUsage());
+            return;
+        }
         const projectDir = ctx ? getProjectDir(ctx, args) : process.cwd();
         const config = await readAiwgConfig(projectDir);
         if (!config)
@@ -273,7 +290,7 @@ async function handleSteward(args, ctx) {
         }
         throw new AiwgError({
             code: 'ERR_USAGE_UNKNOWN_PERMISSION_OPERATION',
-            message: `Unknown permissions operation: ${operation ?? '(missing)'}`,
+            message: `Unknown permissions operation: ${operation}`,
             hint: 'Use audit or migrate --dry-run|--apply.',
             exitCode: EXIT_CODES.USAGE,
         });
@@ -598,6 +615,18 @@ export const stewardHandler = {
     description: 'Provider capability routing and permission normalization',
     category: 'maintenance',
     aliases: [],
+    // The router intercepts --help before execute(), so a handler without this
+    // property gets the generic "no detailed help" stub even when its own usage
+    // text exists. Route to the same block bare invocation prints, and keep
+    // sub-namespace help reachable, without executing anything (#2533).
+    async help(ctx) {
+        const positional = ctx.args.filter((arg) => !arg.startsWith('-'));
+        if (positional[0] === 'permissions') {
+            return { exitCode: 0, message: permissionsUsage(), rawOutput: true };
+        }
+        await handleSteward([], ctx);
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         try {
             await handleSteward(ctx.args, ctx);

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

@@ -694,8 +694,10 @@ const SESSION_RELOAD_NOTICE = {
         rationale: 'Claude Code reads .claude/agents/ at session start. A running session retains its old registry until reloaded.',
     },
     codex: {
-        action: 'Restart/open Codex in this target workspace so it picks up newly deployed agents and .agents/skills entries.',
-        rationale: 'Codex caches its agent and skill registry per session. Project .agents/skills/ and .codex/agents/ are scanned from the Codex working directory up to the repo root on startup.',
+        required: false,
+        action: 'No restart needed for deployed skills — Codex exposes them on the next turn. Reopen Codex in this workspace only if a deployed skill or agent is still missing after that.',
+        rationale: 'A running Codex desktop session listed the newly deployed project skills on the very next user turn without any restart (#2309). Custom agent registry and MCP server changes were not observed to refresh live, so reopening remains the fallback for those.',
+        symptom: 'If a deployed skill or agent stays absent after the next turn, the registry did not rescan — reopen Codex in this workspace.',
     },
     copilot: {
         action: 'Reload the VS Code window (`Developer: Reload Window`) so Copilot picks up the new .github/agents/ entries.',
@@ -736,7 +738,8 @@ function printSessionReloadNotice(provider) {
     if (!notice)
         return;
     const defaultSymptom = 'Until reloaded, the Agent/Task tool will report "Agent type not found" for the newly deployed agents.';
-    ui.section('Session reload required:', [
+    const required = notice.required !== false;
+    ui.section(required ? 'Session reload required:' : 'Session reload (only if something is missing):', [
         notice.action,
         `Why: ${notice.rationale}`,
         notice.symptom ?? defaultSymptom,
@@ -1269,7 +1272,9 @@ async function deployOneProjectLocalBundle(opts) {
             args.push('--quiet');
         // Project-local bundles are addon-shaped — never trigger the legacy commands
         // migration prompt (which is only relevant for full-framework deploys).
-        args.push('--skip-commands-migration');
+        // This is a structural opt-out, not the operator declining, so suppress the
+        // duplicate-commands warning too: it fired once per bundle (#2541).
+        args.push('--skip-commands-migration', '--no-commands-warning');
         const captureOpts = quiet && !verbose ? { capture: true } : {};
         // Inject AIWG_ROOT so the deploy subprocess can resolve the upstream AIWG
         // install root. The bundle's `--source` is its project-local path, so

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

@@ -12,7 +12,7 @@ import { getVersionInfo } from '../../channel/manager.mjs';
 import { getLoggerInfo } from '../log.js';
 import * as ui from '../ui.js';
 import { maybePrintCommunityFooter } from '../../community/footer.js';
-import { existsSync, statSync, readdirSync } from 'fs';
+import { existsSync, statSync, readdirSync, readFileSync } from 'fs';
 import path from 'path';
 /**
  * Version command handler
@@ -30,6 +30,18 @@ export const versionHandler = {
         return { exitCode: 0 };
     },
 };
+/**
+ * Print the installation-drift notice when the canonical declaration and the
+ * running binary disagree. Keeps `aiwg version` honest about which one it is
+ * describing, and names the command that explains the rest (#2529).
+ */
+function printDrift(fp) {
+    if (!fp.drift)
+        return;
+    const method = fp.installation?.identity?.method ?? 'unrecorded';
+    const declared = fp.drift.canonicalVersion ? ` (${fp.drift.canonicalVersion})` : '';
+    ui.dim(`    ! canonical install declares ${method} at ${fp.drift.canonicalRoot}${declared} — run \`aiwg installation show\``);
+}
 function collectFingerprint(versionInfo) {
     const loggerInfo = getLoggerInfo();
     const fp = {
@@ -62,6 +74,22 @@ function collectFingerprint(versionInfo) {
             path: versionInfo.edgePath ?? versionInfo.packageRoot,
         };
     }
+    // `version` is the first thing anyone runs to answer "what am I on". If the
+    // canonical install declares a different root than the one executing, say so
+    // here rather than letting drift persist while every check looks correct.
+    const canonicalRoot = fp.installation?.identity?.root;
+    const actualRoot = fp.installation?.actualRoot;
+    if (canonicalRoot && actualRoot && path.resolve(canonicalRoot) !== path.resolve(actualRoot)) {
+        let canonicalVersion = null;
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(canonicalRoot, 'package.json'), 'utf8'));
+            canonicalVersion = pkg.version ?? null;
+        }
+        catch {
+            // Canonical root may not exist or be readable; report the drift regardless.
+        }
+        fp.drift = { canonicalRoot, canonicalVersion, actualRoot };
+    }
     // Locale / timezone are useful for timezone-dependent bug reports.
     try {
         fp.locale = Intl.DateTimeFormat().resolvedOptions().locale;
@@ -96,13 +124,12 @@ async function displayVersion(opts) {
     ui.blank();
     console.log(`  ${ui.brandMark()} ${ui.bold('aiwg')}  ${ui.bold(fp.version)}  ${ui.channelLabel(fp.channel)}`);
     if (!opts.verbose) {
-        if (fp.git) {
+        if (fp.git)
             ui.dim(`    git: ${fp.git.sha} (${fp.git.branch})`);
-            ui.dim(`    path: ${fp.git.path}`);
-        }
-        else {
-            ui.dim(`    path: ${fp.packageRoot}`);
-        }
+        // Always the root that actually executed — not the declared edge checkout,
+        // which is what made drift invisible here (#2529).
+        ui.dim(`    path: ${fp.packageRoot}`);
+        printDrift(fp);
         maybePrintCommunityFooter();
         ui.blank();
         return;
@@ -110,15 +137,14 @@ async function displayVersion(opts) {
     // --verbose: the full environment fingerprint.
     if (fp.git) {
         ui.dim(`    git:       ${fp.git.sha} (${fp.git.branch})`);
-        ui.dim(`    path:      ${fp.git.path}`);
-    }
-    else {
-        ui.dim(`    path:      ${fp.packageRoot}`);
+        if (fp.git.path !== fp.packageRoot)
+            ui.dim(`    edge:      ${fp.git.path}`);
     }
+    ui.dim(`    path:      ${fp.packageRoot}`);
     ui.dim(`    channel:   ${fp.channel}`);
-    ui.dim(`    install:   ${fp.installation.identity?.method ?? 'unrecorded'} (${fp.installation.state})`);
-    ui.dim(`    canonical: ${fp.installation.identity?.root ?? '(unrecorded)'}`);
-    ui.dim(`    actual:    ${fp.installation.actualRoot}`);
+    ui.dim(`    install:   ${fp.installation?.identity?.method ?? 'unrecorded'} (${fp.installation?.state ?? 'unknown'})`);
+    ui.dim(`    canonical: ${fp.installation?.identity?.root ?? '(unrecorded)'}`);
+    ui.dim(`    actual:    ${fp.installation?.actualRoot ?? fp.packageRoot}`);
     ui.dim(`    node:      ${fp.node}`);
     ui.dim(`    platform:  ${fp.platform.os} ${fp.platform.arch} (${fp.platform.release})`);
     ui.dim(`    tty:       stdin=${fp.tty.stdin} stdout=${fp.tty.stdout} stderr=${fp.tty.stderr}`);

package/dist/src/cli/handlers/workspace-context.js

@@ -55,6 +55,14 @@ export const workspaceContextHandler = {
                     console.log(JSON.stringify(result, null, 2));
                 else {
                     console.log(`${result.dryRun ? 'Migration dry run' : 'Migration applied'}: ${result.changed ? 'changes found' : 'already canonical'}`);
+                    for (const entry of result.audit.plan.routing) {
+                        console.log(`  ${entry.source}: ${entry.operatorBytes.toLocaleString()} chars -> ${entry.destination} (${entry.scope})`);
+                    }
+                    for (const entry of result.audit.plan.scopeReview) {
+                        console.log(`  REVIEW ${entry.source} carries ${entry.operatorBytes.toLocaleString()} chars of operator content and is scoped to ${entry.scope} by filename.`);
+                        console.log('         Content in .aiwg/context/providers/ is read by that provider only.');
+                        console.log("         If this is project-neutral methodology, move it into WORKSPACE.md's Project Context section first.");
+                    }
                     for (const file of result.written)
                         console.log(`  ${result.dryRun ? 'would write' : 'wrote'} ${file}`);
                     if (result.transactionId)

package/dist/src/cli/services/deployment-verification.js

@@ -9,38 +9,48 @@ import { diagnoseWorkspaceContext, providerContextContract, } from '../../smiths
 import { USER_SCOPE_PATHS } from '../scope-resolver.js';
 const RESTART_NOTICES = {
     claude: {
+        policy: 'restart-required',
         action: 'Restart Claude Code so the running session reloads deployed agents and skills.',
         reason: 'Claude Code reads its agent and skill registries when a session starts.',
     },
     codex: {
-        action: 'Restart or reopen Codex in this workspace so it reloads deployed agents and skills.',
-        reason: 'Codex scans project agent and skill registries when a session starts.',
+        policy: 'live-refresh',
+        action: 'Reopen Codex in this workspace if a deployed skill or agent does not appear.',
+        reason: 'Codex refreshes project skills between turns — a running session exposed newly deployed skills on the next turn without a restart (#2309).',
+        fallback: 'Codex picks up newly deployed skills on the next turn. Reopen Codex in this workspace only if a deployed skill or agent is still missing after that.',
     },
     copilot: {
+        policy: 'restart-required',
         action: 'Reload the VS Code window so Copilot reloads workspace agents and instructions.',
         reason: 'Copilot caches workspace agent definitions until the VS Code window reloads.',
     },
     cursor: {
+        policy: 'restart-required',
         action: 'Reload the Cursor workspace so it reloads agents and rules.',
         reason: 'Cursor reads workspace agents and rules when the workspace opens.',
     },
     factory: {
+        policy: 'restart-required',
         action: 'Restart the Factory droid runtime so it reloads deployed droids.',
         reason: 'Factory loads its droid registry when the runtime starts.',
     },
     opencode: {
+        policy: 'restart-required',
         action: 'Restart the OpenCode session so it reloads deployed agents.',
         reason: 'OpenCode scans its agent directory when the session starts.',
     },
     openclaw: {
+        policy: 'restart-required',
         action: 'Restart OpenClaw so it reloads its home-directory registry.',
         reason: 'OpenClaw loads its home-directory registry when the process starts.',
     },
     warp: {
+        policy: 'restart-required',
         action: 'Open a fresh Warp tab so it reloads project context.',
         reason: 'Warp reads project context when a tab starts.',
     },
     windsurf: {
+        policy: 'restart-required',
         action: 'Reload Devin Desktop so it reparses project context.',
         reason: 'Devin Desktop reads the Windsurf-compatible project context when the workspace opens.',
     },
@@ -327,9 +337,16 @@ export async function verifyProviderDeployment(options) {
     const findings = [];
     const counts = emptyCounts();
     const restartNotice = RESTART_NOTICES[normalized] ?? null;
-    const restartAction = restartNotice?.action ?? null;
+    // A provider with no notice gets no restart claim, which is what it got
+    // before this field existed. The label is the absence of a known restart
+    // requirement, not a positive claim that the client refreshes live.
+    const reloadPolicy = restartNotice?.policy ?? 'live-refresh';
+    const restartRequired = reloadPolicy === 'restart-required';
+    // Only a `restart-required` provider gets an imperative restart step. A
+    // `live-refresh` provider keeps its rationale and a conditional fallback (#2309).
+    const restartAction = restartRequired ? (restartNotice?.action ?? null) : null;
     const restartReason = restartNotice?.reason ?? null;
-    const restartRequired = restartAction !== null;
+    const reloadFallback = restartRequired ? null : (restartNotice?.fallback ?? null);
     if (!definition) {
         findings.push(finding(normalized, 'provider-unknown', 'blocking', `No provider definition is available for '${options.provider}'.`, 'Choose a supported provider or repair the project-local provider adapter.'));
     }
@@ -492,6 +509,8 @@ export async function verifyProviderDeployment(options) {
         restartRequired,
         restartAction,
         restartReason,
+        reloadPolicy,
+        reloadFallback,
         counts,
         phases,
         findings,
@@ -501,7 +520,9 @@ export function buildDryRunUseResult(options) {
     const providers = options.providers.map((provider) => {
         const normalized = normalizeProviderDefinitionId(provider) ?? provider;
         const restartNotice = RESTART_NOTICES[normalized] ?? null;
-        const restartAction = restartNotice?.action ?? null;
+        const reloadPolicy = restartNotice?.policy ?? 'live-refresh';
+        const restartRequired = reloadPolicy === 'restart-required';
+        const restartAction = restartRequired ? (restartNotice?.action ?? null) : null;
         const phases = [
             phase('resolve', 'planned', true, `Would resolve ${options.projectRoot}, ${normalized}, ${options.scope} scope.`),
             phase('deploy', 'planned', true, 'Would deploy the requested managed artifact surface.'),
@@ -514,9 +535,11 @@ export function buildDryRunUseResult(options) {
             provider: normalized,
             scope: options.scope,
             outcome: 'planned',
-            restartRequired: restartAction !== null,
+            restartRequired,
             restartAction,
             restartReason: restartNotice?.reason ?? null,
+            reloadPolicy,
+            reloadFallback: restartRequired ? null : (restartNotice?.fallback ?? null),
             counts: emptyCounts(),
             phases,
             findings: [],
@@ -613,6 +636,8 @@ export async function verifyConfiguredDeployments(projectRoot, filters = {}, fra
             restartRequired: false,
             restartAction: null,
             restartReason: null,
+            reloadPolicy: 'live-refresh',
+            reloadFallback: null,
             counts: emptyCounts(),
             phases: [phase('verify', 'failed', true, 'No installed provider deployment could be resolved.')],
             findings: [finding(fallback, 'deployment-not-configured', 'blocking', 'No installed provider deployment could be resolved.', 'Run aiwg use all --provider <provider>.')],
@@ -756,6 +781,14 @@ export function renderUseDeploymentResult(result, options = {}) {
             lines.push(...wrapParagraph(`Framework index built: ${result.discovery.builtAt}`, width));
         }
     }
+    const reloadFallbacks = result.providers
+        .filter((provider) => !provider.restartRequired && provider.reloadFallback)
+        .map((provider) => provider.reloadFallback);
+    if (reloadFallbacks.length > 0) {
+        lines.push('', 'If something is missing');
+        for (const note of reloadFallbacks)
+            lines.push(...wrapParagraph(note, width));
+    }
     const restartActions = result.providers
         .filter((provider) => provider.restartRequired && provider.restartAction)
         .map((provider) => provider.restartAction);