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

package/dist/cli/core/npm-registry.js

@@ -0,0 +1,65 @@
+/**
+ * Lightweight helper to check whether a specific package version exists in the
+ * public npm registry. Used by `ensureSquadStateMcpPinned` to avoid pinning a
+ * `squad_state` MCP launch spec to a version that `npx` cannot resolve
+ * (which would cause an ETARGET at session start and leave the bridge unwired).
+ *
+ * The result is cached per-process to avoid repeated lookups across the
+ * multi-pass upgrade flow. Network failures and non-200 responses are
+ * conservatively treated as "version not published" so that we fall back to
+ * the locally-installed binary rather than pinning a bad spec.
+ *
+ * See `.squad/files/validation/MCP-LOADER-ROOT-CAUSE.md` (data-15 Option A).
+ */
+const cache = new Map();
+/** Reset the cache (test-only helper). */
+export function _resetNpmRegistryCache() {
+    cache.clear();
+}
+/**
+ * Returns true if `@bradygaster/squad-cli@<version>` is reachable on the npm
+ * registry, false on any network failure / 404 / non-publishable response.
+ *
+ * Uses Node's built-in `https` so we don't pull in extra deps. Total budget
+ * is bounded by `timeoutMs` (default 2s) so a slow / offline registry can
+ * never block CLI startup.
+ */
+export async function isSquadCliVersionPublished(version, timeoutMs = 2000) {
+    if (!version || version === '0.0.0')
+        return false;
+    const cacheKey = version;
+    const cached = cache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const url = `https://registry.npmjs.org/@bradygaster%2Fsquad-cli/${encodeURIComponent(version)}`;
+    const ok = await new Promise((resolve) => {
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        void import('node:https')
+            .then(({ request }) => {
+            const req = request(url, { method: 'GET' }, (res) => {
+                // Drain to free the socket.
+                res.resume();
+                finish(res.statusCode === 200);
+            });
+            req.on('error', () => finish(false));
+            req.on('timeout', () => {
+                req.destroy();
+                finish(false);
+            });
+            req.setTimeout(timeoutMs);
+            req.end();
+        })
+            .catch(() => finish(false))
+            .finally(() => clearTimeout(timer));
+    });
+    cache.set(cacheKey, ok);
+    return ok;
+}
+//# sourceMappingURL=npm-registry.js.map

package/dist/cli/core/npm-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm-registry.js","sourceRoot":"","sources":["../../../src/cli/core/npm-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;AAEzC,0CAA0C;AAC1C,MAAM,UAAU,sBAAsB;IACpC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,OAAe,EACf,SAAS,GAAG,IAAI;IAEhB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,QAAQ,GAAG,OAAO,CAAC;IACzB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IAExC,MAAM,GAAG,GAAG,uDAAuD,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;IACjG,MAAM,EAAE,GAAG,MAAM,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;QAChD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,CAAC,CAAU,EAAE,EAAE;YAC5B,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,CAAC,CAAC,CAAC,CAAC;QACb,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;QAEzD,KAAK,MAAM,CAAC,YAAY,CAAC;aACtB,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;YACpB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,EAAE,EAAE;gBAClD,4BAA4B;gBAC5B,GAAG,CAAC,MAAM,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC;YACjC,CAAC,CAAC,CAAC;YACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACrC,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;gBACrB,GAAG,CAAC,OAAO,EAAE,CAAC;gBACd,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;YACH,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YAC1B,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aAC1B,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACxB,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/cli/core/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/cli/core/templates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,kBAAkB,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAAY,EA4Q3C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAWxC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/cli/core/templates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,kBAAkB,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAAY,EAiT3C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAWxC"}

package/dist/cli/core/templates.js

@@ -22,6 +22,9 @@ export const TEMPLATE_MANIFEST = [
         description: 'Squad coordinator agent prompt',
     },
     // Casting system (squad-owned, overwrite on upgrade)
+    // NOTE: These JSON files are read at runtime by the SDK and many agent
+    // skills via their flat `.squad/casting-*.json` paths — do NOT route into
+    // a subdirectory without coordinated updates across the SDK + skill docs.
     {
         source: 'casting-history.json',
         destination: 'casting-history.json',
@@ -40,88 +43,102 @@ export const TEMPLATE_MANIFEST = [
         overwriteOnUpgrade: true,
         description: 'Universe-based character registry',
     },
-    // Template files (squad-owned, overwrite on upgrade)
+    // Template files (squad-owned, overwrite on upgrade) — routed to
+    // .squad/templates/ so upgrade doesn't dump ~20 generic *.md docs
+    // into the .squad/ root.
     {
         source: 'charter.md',
-        destination: 'charter.md',
+        destination: 'templates/charter.md',
         overwriteOnUpgrade: true,
         description: 'Agent charter template',
     },
     {
         source: 'constraint-tracking.md',
-        destination: 'constraint-tracking.md',
+        destination: 'templates/constraint-tracking.md',
         overwriteOnUpgrade: true,
         description: 'Constraint tracking template',
     },
     {
         source: 'copilot-instructions.md',
-        destination: 'copilot-instructions.md',
+        destination: 'templates/copilot-instructions.md',
         overwriteOnUpgrade: true,
         description: 'Copilot instructions template',
     },
     {
         source: 'history.md',
-        destination: 'history.md',
+        destination: 'templates/history.md',
         overwriteOnUpgrade: true,
         description: 'Agent history template',
     },
     {
         source: 'mcp-config.md',
-        destination: 'mcp-config.md',
+        destination: 'templates/mcp-config.md',
         overwriteOnUpgrade: true,
         description: 'MCP configuration template',
     },
     {
         source: 'multi-agent-format.md',
-        destination: 'multi-agent-format.md',
+        destination: 'templates/multi-agent-format.md',
         overwriteOnUpgrade: true,
         description: 'Multi-agent format specification',
     },
     {
         source: 'orchestration-log.md',
-        destination: 'orchestration-log.md',
+        destination: 'templates/orchestration-log.md',
         overwriteOnUpgrade: true,
         description: 'Orchestration log template',
     },
     {
         source: 'plugin-marketplace.md',
-        destination: 'plugin-marketplace.md',
+        destination: 'templates/plugin-marketplace.md',
         overwriteOnUpgrade: true,
         description: 'Plugin marketplace template',
     },
     {
         source: 'raw-agent-output.md',
-        destination: 'raw-agent-output.md',
+        destination: 'templates/raw-agent-output.md',
         overwriteOnUpgrade: true,
         description: 'Raw agent output template',
     },
     {
         source: 'roster.md',
-        destination: 'roster.md',
+        destination: 'templates/roster.md',
         overwriteOnUpgrade: true,
         description: 'Team roster template',
     },
     {
         source: 'run-output.md',
-        destination: 'run-output.md',
+        destination: 'templates/run-output.md',
         overwriteOnUpgrade: true,
         description: 'Run output template',
     },
     {
         source: 'scribe-charter.md',
-        destination: 'scribe-charter.md',
+        destination: 'templates/scribe-charter.md',
         overwriteOnUpgrade: true,
         description: 'Scribe charter template',
     },
+    {
+        source: 'Rai-charter.md',
+        destination: 'templates/Rai-charter.md',
+        overwriteOnUpgrade: true,
+        description: 'Rai RAI reviewer charter template',
+    },
+    {
+        source: 'rai-policy.md',
+        destination: 'templates/rai-policy.md',
+        overwriteOnUpgrade: true,
+        description: 'Default RAI policy template',
+    },
     {
         source: 'fact-checker-charter.md',
-        destination: 'fact-checker-charter.md',
+        destination: 'templates/fact-checker-charter.md',
         overwriteOnUpgrade: true,
         description: 'Fact checker charter template',
     },
     {
         source: 'skill.md',
-        destination: 'skill.md',
+        destination: 'templates/skill.md',
         overwriteOnUpgrade: true,
         description: 'Skill definition template',
     },
@@ -154,7 +171,7 @@ export const TEMPLATE_MANIFEST = [
     // Issue lifecycle (squad-owned)
     {
         source: 'issue-lifecycle.md',
-        destination: 'issue-lifecycle.md',
+        destination: 'templates/issue-lifecycle.md',
         overwriteOnUpgrade: true,
         description: 'Issue lifecycle process template',
     },
@@ -207,6 +224,25 @@ export const TEMPLATE_MANIFEST = [
         overwriteOnUpgrade: true,
         description: 'Multi-agent collaboration and handoff patterns',
     },
+    {
+        source: 'skills/squad-commands/SKILL.md',
+        destination: '../.copilot/skills/squad-commands/SKILL.md',
+        overwriteOnUpgrade: true,
+        description: 'In-chat command discovery — categorized menu of Squad operations',
+    },
+    {
+        source: 'skills/squad-version-check/SKILL.md',
+        destination: '../.copilot/skills/squad-version-check/SKILL.md',
+        overwriteOnUpgrade: true,
+        description: 'Squad CLI internals — version stamping & upgrade mechanics',
+    },
+    // Session init reference (squad-owned, coordinator reads at session start)
+    {
+        source: 'session-init-reference.md',
+        destination: 'templates/session-init-reference.md',
+        overwriteOnUpgrade: true,
+        description: 'Session init reference — coordinator procedures run at session start',
+    },
     // Workflows (squad-owned, overwrite on upgrade)
     {
         source: 'workflows/squad-ci.yml',

package/dist/cli/core/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/cli/core/templates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/cli/core/templates.ts"],"names":[],"mappings":"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"}

package/dist/cli/core/upgrade.d.ts

@@ -3,6 +3,8 @@
  * Zero-dep implementation using Node.js stdlib only
  * @module cli/core/upgrade
  */
+import { type SquadStateMcpSpec } from './mcp-spec.js';
+export { resolveSquadStateMcpSpec } from './mcp-spec.js';
 export interface UpgradeOptions {
     migrateDirectory?: boolean;
     self?: boolean;
@@ -35,6 +37,9 @@ export declare function ensureDirectories(dest: string): string[];
  * available, falling back to inline JSON defaults.
  */
 export declare function ensureCastingDefaults(dest: string, templatesDir?: string): string[];
+/** Human-readable single-line description of an McpSpec for success() messages. */
+export declare function describeMcpSpec(spec: SquadStateMcpSpec): string;
+export declare function ensureMemoryGovernanceUpgradeDefaults(dest: string): string[];
 /**
  * Run the upgrade command
  */

package/dist/cli/core/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../../src/cli/core/upgrade.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4BH,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAyPD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB1D;AAkBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAUxD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CA+CnF;AAoGD;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAoKhG;AAMD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAiBD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCpF"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../../src/cli/core/upgrade.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AA0GzD,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAyTD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB1D;AAkBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAUxD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CA+CnF;AA8HD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAI/D;AAED,wBAAgB,qCAAqC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAsC5E;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAqKhG;AAMD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAiBD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDpF"}

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,79 @@ 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();
+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).
+    const pkgSpec = cliVersion && cliVersion !== '0.0.0'
+        ? `@bradygaster/squad-cli@${cliVersion}`
+        : '@bradygaster/squad-cli';
+    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 +122,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 +383,7 @@ const GITIGNORE_ENTRIES = [
     '.squad/log/',
     '.squad/decisions/inbox/',
     '.squad/sessions/',
+    '.squad/.cache/',
     '.squad-workstream',
 ];
 const ENSURE_DIRECTORIES = [
@@ -464,7 +596,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,6 +617,11 @@ 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 skillCount = syncAllSkills(dest, templatesDir);
     if (skillCount > 0) {
         success(`synced ${skillCount} skills to .copilot/skills/`);
@@ -493,6 +630,71 @@ function runEnsureChecks(dest, templatesDir, filesUpdated) {
     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 5.3+ walking up from cwd to git root)
+    // 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}`);
+    }
+    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;
 }
 /**
  * Run the upgrade command
@@ -513,6 +715,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 +742,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 +750,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 +765,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 +816,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 +880,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