@bradygaster/squad-cli 0.9.6-insider.2 → 0.10.0-insider.1

package/dist/cli/core/upgrade.js

@@ -4,6 +4,7 @@
  * @module cli/core/upgrade
  */
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { FSStorageProvider } from '@bradygaster/squad-sdk';
 import { success, warn, info, dim } from './output.js';
 import { fatal } from './errors.js';
@@ -11,7 +12,105 @@ import { detectSquadDir } from './detect-squad-dir.js';
 import { TEMPLATE_MANIFEST, getTemplatesDir } from './templates.js';
 import { runMigrations } from './migrations.js';
 import { getPackageVersion, stampVersion, readInstalledVersion } from './version.js';
+import { resolveSquadStateMcpSpec } from './mcp-spec.js';
+export { resolveSquadStateMcpSpec } from './mcp-spec.js';
+import { ensureSquadStateMcpInRoot, tombstoneStaleSquadStateInProjectMcp } from './mcp-root.js';
 const storage = new FSStorageProvider();
+/**
+ * Returns true if the version looks like a local dev build or unpublished
+ * pre-release that cannot be resolved from the public npm registry.
+ * Guards against writing unresolvable version strings into MCP config
+ * (see #1204).
+ */
+export function isLocalOrUnpublishedVersion(version) {
+    if (!version || version === '0.0.0')
+        return true;
+    // Local linked builds often have 0.0.0-development or similar sentinel
+    if (/^0\.0\.0/.test(version))
+        return true;
+    // Versions with `+` build metadata (e.g. 0.10.0+local.1234) are not
+    // publishable to npm — they indicate a local build.
+    if (version.includes('+'))
+        return true;
+    return false;
+}
+function buildMcpServerSpecs(isGitHub, cliVersion) {
+    // Pin the squad-cli package to the currently-installed CLI version so that
+    // `npx -y @bradygaster/squad-cli state-mcp` does NOT silently resolve to the
+    // npm `latest` dist-tag (which may predate the `state-mcp` command and thus
+    // expose zero tools to Copilot — see MCP-BRIDGE-BROKEN root cause).
+    //
+    // #1204: When the CLI is a local dev build or unpublished pre-release, fall
+    // back to the @insider dist-tag to avoid writing an unresolvable version
+    // string that breaks npx resolution at session start.
+    let pkgSpec;
+    if (!cliVersion || isLocalOrUnpublishedVersion(cliVersion)) {
+        pkgSpec = '@bradygaster/squad-cli@insider';
+    }
+    else {
+        pkgSpec = `@bradygaster/squad-cli@${cliVersion}`;
+    }
+    const servers = [
+        {
+            name: 'squad_state',
+            command: 'npx',
+            args: ['-y', pkgSpec, 'state-mcp'],
+        },
+    ];
+    servers.push(isGitHub
+        ? {
+            name: 'EXAMPLE-github',
+            command: 'npx',
+            args: ['-y', '@anthropic/github-mcp-server'],
+            env: { GITHUB_TOKEN: '${GITHUB_TOKEN}' },
+        }
+        : {
+            name: 'EXAMPLE-azure-devops',
+            command: 'npx',
+            args: ['-y', '@azure/devops-mcp-server'],
+            env: {
+                AZURE_DEVOPS_ORG: '${AZURE_DEVOPS_ORG}',
+                AZURE_DEVOPS_PAT: '${AZURE_DEVOPS_PAT}',
+            },
+        });
+    return servers;
+}
+function yamlSingleQuoted(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function yamlEnvValue(value) {
+    if (/^\$\{[A-Z0-9_]+\}$/.test(value)) {
+        return value;
+    }
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function buildMcpFrontmatterBlock(isGitHub, cliVersion) {
+    const lines = ['mcp-servers:'];
+    for (const server of buildMcpServerSpecs(isGitHub, cliVersion)) {
+        lines.push(`  ${server.name}:`);
+        lines.push('    type: local');
+        lines.push(`    command: ${server.command}`);
+        lines.push(`    args: [${server.args.map(yamlSingleQuoted).join(', ')}]`);
+        lines.push('    tools: ["*"]');
+        if (server.env && Object.keys(server.env).length > 0) {
+            lines.push('    env:');
+            for (const [key, value] of Object.entries(server.env)) {
+                lines.push(`      ${key}: ${yamlEnvValue(value)}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function injectMcpFrontmatter(content, isGitHub, cliVersion) {
+    const closingStart = content.indexOf('\n---', 4);
+    if (!content.startsWith('---') || closingStart === -1) {
+        return content;
+    }
+    return content.slice(0, closingStart)
+        + '\n'
+        + buildMcpFrontmatterBlock(isGitHub, cliVersion)
+        + content.slice(closingStart);
+}
 function copyDirRecursive(src, dest, force = true) {
     storage.mkdirSync(dest, { recursive: true });
     for (const entry of storage.listSync(src)) {
@@ -49,6 +148,64 @@ function compareSemver(a, b) {
         return a < b ? -1 : a > b ? 1 : 0;
     return 0;
 }
+function readSquadConfig(squadDir) {
+    const configPath = path.join(squadDir, 'config.json');
+    if (!storage.existsSync(configPath))
+        return {};
+    try {
+        const raw = storage.readSync(configPath);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Ignore malformed config for upgrade compatibility.
+    }
+    return {};
+}
+function readMcpConfigMode(config) {
+    return config['mcpConfigMode'] === 'agent-frontmatter' ? 'agent-frontmatter' : 'copilot-file';
+}
+function detectMcpConfigMode(config, agentDest) {
+    const configuredMode = readMcpConfigMode(config);
+    if (configuredMode === 'agent-frontmatter')
+        return configuredMode;
+    if (storage.existsSync(agentDest)) {
+        const existingAgent = storage.readSync(agentDest) ?? '';
+        const frontmatterEnd = existingAgent.indexOf('\n---', 4);
+        const frontmatter = frontmatterEnd === -1 ? '' : existingAgent.slice(0, frontmatterEnd);
+        if (frontmatter.includes('mcp-servers:')) {
+            return 'agent-frontmatter';
+        }
+    }
+    return configuredMode;
+}
+function detectIsGitHubForMcp(dest, config) {
+    if (config['platform'] === 'azure-devops')
+        return false;
+    try {
+        const remoteUrl = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: dest, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const remoteUrlLower = remoteUrl.toLowerCase();
+        if (remoteUrlLower.includes('dev.azure.com') || remoteUrlLower.includes('visualstudio.com') || remoteUrlLower.includes('ssh.dev.azure.com')) {
+            return false;
+        }
+    }
+    catch {
+        // No git remote — assume GitHub, matching init behavior.
+    }
+    return true;
+}
+function writeAgentTemplate(agentSrc, agentDest, cliVersion, mcpConfigMode, isGitHub) {
+    let agentContent = storage.readSync(agentSrc) ?? '';
+    if (mcpConfigMode === 'agent-frontmatter') {
+        agentContent = injectMcpFrontmatter(agentContent, isGitHub, cliVersion);
+    }
+    storage.writeSync(agentDest, agentContent);
+    stampVersion(agentDest, cliVersion);
+}
 /**
  * Detect project type by checking marker files
  */
@@ -252,6 +409,7 @@ const GITIGNORE_ENTRIES = [
     '.squad/log/',
     '.squad/decisions/inbox/',
     '.squad/sessions/',
+    '.squad/.cache/',
     '.squad-workstream',
 ];
 const ENSURE_DIRECTORIES = [
@@ -262,7 +420,7 @@ const ENSURE_DIRECTORIES = [
     '.squad/decisions/inbox',
     '.squad/casting',
     '.squad/agents',
-    '.copilot/skills',
+    '.github/skills',
 ];
 /**
  * Ensure .gitattributes has required merge=union rules (idempotent)
@@ -417,7 +575,74 @@ function warnIfSkillCustomized(srcPath, destPath, sourceName) {
     }
 }
 /**
- * Sync manifest-declared skills to .copilot/skills/, respecting overwriteOnUpgrade.
+ * Migrate skills from the legacy `.copilot/skills/<name>/` location to the
+ * canonical `.github/skills/<name>/`. Only migrates skills that appear in
+ * `TEMPLATE_MANIFEST` (manifest-curated Squad skills) — does NOT touch
+ * user-added skills in `.copilot/skills/`. After successful migration,
+ * removes the now-empty `.copilot/skills/<name>/` directories.
+ *
+ * Idempotent: when a skill already exists at the new location the legacy
+ * copy is tombstoned without comparing content — this protects any
+ * in-place customization the user made at `.github/skills/<name>/` from
+ * being clobbered, and means re-running upgrade is a no-op on the new
+ * location. If only the legacy copy exists, it is moved over.
+ *
+ * See bradygaster/squad#1126 (canonical issue) — this is the migration
+ * piece of that fix; #1304 is the PR that implements it.
+ */
+function migrateLegacyCopilotSkills(dest) {
+    const legacyDir = path.join(dest, '.copilot', 'skills');
+    if (!storage.existsSync(legacyDir))
+        return { migrated: [], tombstoned: [] };
+    const manifestSkills = new Set(TEMPLATE_MANIFEST
+        .filter(f => f.source.startsWith('skills/'))
+        .map(f => f.source.split('/')[1]) // 'skills/foo/SKILL.md' -> 'foo'
+        .filter((s) => Boolean(s)));
+    const newDir = path.join(dest, '.github', 'skills');
+    const migrated = [];
+    const tombstoned = [];
+    for (const entry of storage.listSync(legacyDir)) {
+        if (!manifestSkills.has(entry))
+            continue; // leave user-added skills alone
+        const legacySkillDir = path.join(legacyDir, entry);
+        if (!storage.isDirectorySync(legacySkillDir))
+            continue;
+        const newSkillDir = path.join(newDir, entry);
+        if (storage.existsSync(newSkillDir)) {
+            // New location already has it — drop the legacy copy without overwriting.
+            try {
+                storage.deleteDirSync(legacySkillDir);
+                tombstoned.push(path.posix.join('.copilot/skills', entry));
+            }
+            catch {
+                // best-effort; leave the legacy dir if we can't remove it
+            }
+            continue;
+        }
+        try {
+            storage.mkdirSync(newDir, { recursive: true });
+            copyDirRecursive(legacySkillDir, newSkillDir);
+            storage.deleteDirSync(legacySkillDir);
+            migrated.push(path.posix.join('.github/skills', entry));
+        }
+        catch {
+            // best-effort; leave the legacy dir if anything fails
+        }
+    }
+    // If the legacy `.copilot/skills/` directory is now empty, remove it too.
+    try {
+        if (storage.existsSync(legacyDir) && storage.listSync(legacyDir).length === 0) {
+            storage.deleteDirSync(legacyDir);
+            tombstoned.push('.copilot/skills');
+        }
+    }
+    catch {
+        // best-effort
+    }
+    return { migrated, tombstoned };
+}
+/**
+ * Sync manifest-declared skills to .github/skills/, respecting overwriteOnUpgrade.
  * Only skills listed in TEMPLATE_MANIFEST are installed — not the entire templates/skills/ dir.
  */
 function syncAllSkills(dest, templatesDir) {
@@ -464,7 +689,7 @@ function refreshSquadTemplatesDir(dest, templatesDir) {
 /**
  * Run all ensure* checks and skill/template sync — shared by both code paths
  */
-function runEnsureChecks(dest, templatesDir, filesUpdated) {
+async function runEnsureChecks(dest, templatesDir, filesUpdated) {
     const attrAdded = ensureGitattributes(dest);
     if (attrAdded.length > 0) {
         success(`ensured .gitattributes (${attrAdded.length} rules added)`);
@@ -485,14 +710,170 @@ function runEnsureChecks(dest, templatesDir, filesUpdated) {
         success(`scaffolded ${castingFiles.length} default casting files`);
         filesUpdated.push(...castingFiles);
     }
+    const memoryFiles = ensureMemoryGovernanceUpgradeDefaults(dest);
+    if (memoryFiles.length > 0) {
+        success(`scaffolded memory governance defaults (${memoryFiles.length} files/directories)`);
+        filesUpdated.push(...memoryFiles);
+    }
+    const builtinAgents = ensureBuiltinAgents(dest, templatesDir);
+    if (builtinAgents.length > 0) {
+        const uniqueAgentNames = Array.from(new Set(builtinAgents.map(p => path.basename(path.dirname(p)))));
+        success(`scaffolded ${uniqueAgentNames.length} built-in agent(s): ${uniqueAgentNames.join(', ')}`);
+        filesUpdated.push(...builtinAgents);
+    }
+    const skillMigration = migrateLegacyCopilotSkills(dest);
+    if (skillMigration.migrated.length > 0) {
+        success(`migrated ${skillMigration.migrated.length} skill(s) from .copilot/skills/ → .github/skills/`);
+        filesUpdated.push(...skillMigration.migrated);
+    }
+    if (skillMigration.tombstoned.length > 0) {
+        success(`removed ${skillMigration.tombstoned.length} stale .copilot/skills entries (now live at .github/skills/)`);
+    }
     const skillCount = syncAllSkills(dest, templatesDir);
     if (skillCount > 0) {
-        success(`synced ${skillCount} skills to .copilot/skills/`);
+        success(`synced ${skillCount} skills to .github/skills/`);
         filesUpdated.push(`skills (${skillCount})`);
     }
     refreshSquadTemplatesDir(dest, templatesDir);
     success('refreshed .squad/templates/');
     filesUpdated.push('.squad/templates/');
+    // iter-8: write squad_state MCP entry to repo-root `.mcp.json`
+    // (auto-loaded by Copilot CLI ≥1.0.59, which walks up from cwd to the
+    // git root looking for .mcp.json) and tombstone any stale project-level
+    // entry left by older Squad versions in `.copilot/mcp-config.json`.
+    // No HOME modifications.
+    const pinnedSpec = await resolveSquadStateMcpSpec(getPackageVersion());
+    try {
+        const rootResult = ensureSquadStateMcpInRoot(dest, getPackageVersion(), pinnedSpec);
+        if (rootResult.written) {
+            success(`installed squad_state MCP server to .mcp.json (${describeMcpSpec(pinnedSpec)}) — Copilot CLI will auto-load on next invocation`);
+            filesUpdated.push('.mcp.json');
+        }
+    }
+    catch (err) {
+        warn(`Could not write .mcp.json: ${err instanceof Error ? err.message : err}`);
+    }
+    // iter-8: do NOT write to ~/.copilot/mcp-config.json on upgrade. The
+    // repo-root .mcp.json write above is sufficient for Copilot CLI ≥1.0.59
+    // (walks from cwd up looking for .mcp.json) AND for `copilot -p` from
+    // the project root. Out-of-tree `copilot -p` should use
+    // `--additional-mcp-config @.mcp.json`. See bradygaster/squad#1296.
+    const tomb = tombstoneStaleSquadStateInProjectMcp(dest);
+    if (tomb.removed) {
+        success(`removed stale squad_state from ${tomb.path} (now lives in .mcp.json)`);
+        filesUpdated.push('.copilot/mcp-config.json (tombstoned)');
+    }
+}
+/** Human-readable single-line description of an McpSpec for success() messages. */
+export function describeMcpSpec(spec) {
+    // After iter-7 all specs are `npx -y <pkg@version-or-tag> state-mcp`.
+    const pkg = spec.args[1] ?? '<unknown>';
+    return spec.source === 'insider' ? `${pkg} (@insider fallback)` : pkg;
+}
+export function ensureMemoryGovernanceUpgradeDefaults(dest) {
+    const memoryDir = path.join(dest, '.squad', 'memory');
+    const created = [];
+    for (const dir of ['local', 'policy-inbox', 'semantic-inbox', 'tombstones']) {
+        const fullPath = path.join(memoryDir, dir);
+        if (!storage.existsSync(fullPath)) {
+            storage.mkdirSync(fullPath, { recursive: true });
+            created.push(path.join('.squad', 'memory', dir));
+        }
+    }
+    const defaults = {
+        'config.json': JSON.stringify({
+            version: 1,
+            defaultProvider: 'local',
+            promptOnlyFallback: true,
+            externalProviders: {
+                hostInjectedCopilotAdapter: {
+                    enabled: false,
+                    requireApproval: true,
+                },
+            },
+            policy: {
+                rejectForbidden: true,
+                rejectTransientDurableWrites: true,
+                auditContent: false,
+            },
+        }, null, 2) + '\n',
+        'index.json': '[]\n',
+        'audit.jsonl': '',
+    };
+    for (const [file, content] of Object.entries(defaults)) {
+        const fullPath = path.join(memoryDir, file);
+        if (!storage.existsSync(fullPath)) {
+            storage.writeSync(fullPath, content);
+            created.push(path.join('.squad', 'memory', file));
+        }
+    }
+    return created;
+}
+/**
+ * Scaffold always-on built-in agent charters (Rai, Fact Checker) that ship
+ * as templates but may be missing from older squads. Idempotent — only writes
+ * when the agent directory is absent. Never overwrites existing charters or
+ * history. Sources charter content from the shipped `templates/{name}-charter.md`
+ * files when available, falling back to a minimal placeholder otherwise.
+ *
+ * Scribe and Ralph are intentionally NOT scaffolded here — they should already
+ * exist in any squad that ran a prior init, and their charters are inlined in
+ * cast.ts (no shipped template file). Adding them here would risk overwriting
+ * customized versions on legacy squads.
+ *
+ * @param dest Root directory containing .squad/
+ * @param templatesDir Directory containing shipped charter templates
+ * @returns Paths (relative to dest) of created agent files
+ */
+export function ensureBuiltinAgents(dest, templatesDir) {
+    const agentsDir = path.join(dest, '.squad', 'agents');
+    if (!storage.existsSync(agentsDir)) {
+        storage.mkdirSync(agentsDir, { recursive: true });
+    }
+    // Built-in agents that ship as charter templates. Each entry maps to:
+    //   - dirName: case-preserving directory name under .squad/agents/
+    //   - templateFile: filename under templatesDir (charter template)
+    //   - displayName: shown in history.md header
+    const builtins = [
+        { dirName: 'Rai', templateFile: 'Rai-charter.md', displayName: 'Rai' },
+        { dirName: 'fact-checker', templateFile: 'fact-checker-charter.md', displayName: 'Fact Checker' },
+    ];
+    const created = [];
+    for (const agent of builtins) {
+        const agentDir = path.join(agentsDir, agent.dirName);
+        const charterPath = path.join(agentDir, 'charter.md');
+        const historyPath = path.join(agentDir, 'history.md');
+        // Idempotent: skip if agent directory already exists. Never overwrite
+        // existing charters or history files (preserves user customization).
+        if (storage.existsSync(agentDir))
+            continue;
+        // Source charter content from the shipped template; fall back to a
+        // minimal placeholder if the template file is missing (defensive — should
+        // not happen in a well-formed install, but better than crashing upgrade).
+        const tplPath = path.join(templatesDir, agent.templateFile);
+        let charterContent;
+        if (storage.existsSync(tplPath)) {
+            charterContent = storage.readSync(tplPath) ?? '';
+        }
+        else {
+            charterContent = `# ${agent.displayName}\n\n> Charter template not found in shipped templates. Run \`squad upgrade\` after reinstalling the CLI to repair.\n`;
+        }
+        try {
+            storage.mkdirSync(agentDir, { recursive: true });
+            storage.writeSync(charterPath, charterContent);
+            created.push(path.join('.squad', 'agents', agent.dirName, 'charter.md'));
+            storage.writeSync(historyPath, `# ${agent.displayName} — History\n\n## Learnings\n\nInitial scaffold via \`squad upgrade\`. Ready for work.\n`);
+            created.push(path.join('.squad', 'agents', agent.dirName, 'history.md'));
+        }
+        catch (err) {
+            if (err instanceof Error && 'code' in err && ['EPERM', 'EACCES'].includes(err.code ?? '')) {
+                warn(`Could not scaffold built-in agent ${agent.displayName} (read-only). Create .squad/agents/${agent.dirName}/ manually.`);
+                continue;
+            }
+            throw err;
+        }
+    }
+    return created;
 }
 /**
  * Run the upgrade command
@@ -513,6 +894,9 @@ export async function runUpgrade(dest, options = {}) {
     }
     const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md');
     const oldVersion = readInstalledVersion(agentDest) ?? '0.0.0';
+    const squadConfig = readSquadConfig(squadDirInfo.path);
+    const mcpConfigMode = detectMcpConfigMode(squadConfig, agentDest);
+    const isGitHubForMcp = detectIsGitHubForMcp(dest, squadConfig);
     // Check if already current
     const isAlreadyCurrent = !options.force && oldVersion && oldVersion !== '0.0.0' && compareSemver(oldVersion, cliVersion) === 0;
     const projectType = detectProjectType(dest);
@@ -537,8 +921,7 @@ export async function runUpgrade(dest, options = {}) {
         const agentSrc = path.join(templatesDir, 'squad.agent.md.template');
         if (storage.existsSync(agentSrc)) {
             storage.mkdirSync(path.dirname(agentDest), { recursive: true });
-            storage.copySync(agentSrc, agentDest);
-            stampVersion(agentDest, cliVersion);
+            writeAgentTemplate(agentSrc, agentDest, cliVersion, mcpConfigMode, isGitHubForMcp);
             success('upgraded squad.agent.md');
             filesUpdated.push('squad.agent.md');
         }
@@ -546,7 +929,7 @@ export async function runUpgrade(dest, options = {}) {
             warn('squad.agent.md.template not found — squad.agent.md was not refreshed. Reinstall or repair the CLI to restore the missing template.');
         }
         // Run infrastructure ensure checks even when already current
-        runEnsureChecks(dest, templatesDir, filesUpdated);
+        await runEnsureChecks(dest, templatesDir, filesUpdated);
         return {
             fromVersion: oldVersion,
             toVersion: cliVersion,
@@ -561,8 +944,7 @@ export async function runUpgrade(dest, options = {}) {
         fatal('squad.agent.md.template not found in templates — installation may be corrupted');
     }
     storage.mkdirSync(path.dirname(agentDest), { recursive: true });
-    storage.copySync(agentSrc, agentDest);
-    stampVersion(agentDest, cliVersion);
+    writeAgentTemplate(agentSrc, agentDest, cliVersion, mcpConfigMode, isGitHubForMcp);
     const fromLabel = oldVersion === '0.0.0' || !oldVersion ? 'unknown' : oldVersion;
     success(`upgraded coordinator from ${fromLabel} to ${cliVersion}`);
     filesUpdated.push('squad.agent.md');
@@ -613,7 +995,7 @@ export async function runUpgrade(dest, options = {}) {
         }
     }
     // Run infrastructure ensure checks
-    runEnsureChecks(dest, templatesDir, filesUpdated);
+    await runEnsureChecks(dest, templatesDir, filesUpdated);
     console.log();
     info(`Upgrade complete: v${fromLabel} → v${cliVersion}`);
     if (migrationsApplied.some(m => m.toLowerCase().includes('scrub email'))) {
@@ -677,15 +1059,31 @@ export async function selfUpgradeCli(options = {}) {
         execSync(cmd, { stdio: 'inherit' });
     }
     catch (err) {
-        const isPermission = err instanceof Error &&
-            'code' in err &&
-            err.code === 'EACCES';
+        // UPGRADE-EPERM-FALSE-SUCCESS fix: do NOT swallow self-upgrade failures.
+        // Previously this only printed a warning and returned, causing the caller
+        // (cli-entry.ts) to then unconditionally print "✅ Upgraded" and exit 0.
+        // Now we surface the failure as a thrown error so the caller can exit non-zero
+        // and avoid the contradictory success message.
+        const errMsg = err instanceof Error ? err.message : String(err);
+        const code = err instanceof Error && 'code' in err
+            ? (err.code ?? '')
+            : '';
+        const isPermission = code === 'EACCES' || code === 'EPERM' || /EACCES|EPERM|permission denied/i.test(errMsg);
+        const isBusy = code === 'EBUSY' || /EBUSY|in use|cannot access|being used by another process/i.test(errMsg);
+        let hint;
         if (isPermission) {
-            warn(`Permission denied. Try: sudo ${cmd}`);
+            hint = `Permission denied. Try: sudo ${cmd}`;
+        }
+        else if (isBusy) {
+            hint = `A file is in use (likely another squad shell is running). Close other squad CLI processes and retry: ${cmd}`;
         }
         else {
-            warn(`Upgrade failed. Try running manually: ${cmd}`);
+            hint = `Upgrade failed. Try running manually: ${cmd}`;
         }
+        warn(hint);
+        const failure = new Error(`Self-upgrade failed: ${hint}`);
+        failure.code = code || undefined;
+        throw failure;
     }
 }
 //# sourceMappingURL=upgrade.js.map