@@ -0,0 +1,6 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Migrate Squad 0.9.x casting registries that store agents and assignments as arrays, preserve byte-exact originals, keep the rest of `squad upgrade` running when casting evidence still needs repair, and normalize an absolute self `teamRoot` to `"."`.
@@ -422,9 +422,10 @@ Example: upgrading to v0.2.0 creates `.ai-team/skills/` if it doesn't already ex
 
 ### Legacy casting state (upgrades to 1.x)
 
-`squad upgrade` validates casting state **before** replacing the coordinator,
+`squad upgrade` attempts casting migration **before** replacing the coordinator,
 skills, workflows, or other upgrade-managed files, even when the installed
-coordinator already matches the CLI version.
+coordinator already matches the CLI version. A casting-only failure leaves both
+live casting files unchanged, but no longer blocks unrelated upgrade work.
 
 Supported unversioned registries have an `agents` object with persistent names,
 universes, statuses, and creation dates. Roles default to the agent ID only when
@@ -438,16 +439,19 @@ denote the same instant. The original timestamp string, including its timezone
 offset, is retained; migration never substitutes an agent creation date for an
 assignment date.
 
-The historical `entries[]` / `assignments[]` variant is also supported when
+The historical `entries[]` / `assignments[]` and `agents[]` / `assignments[]`
+variants emitted by 0.9.x coordinators are also supported when
 each registry entry's persistent name matches exactly one canonical folder's
 `charter.md` under the team's `agents/` directory. The charter must contain an
 `## Identity` section with `- **Name:**`; its optional `- **Role:**` supplies the
 role, otherwise the canonical folder ID is used. Missing, duplicated, malformed,
 or conflicting identities stop migration; names are never slugified into IDs.
 Keep the original producer's charters with the state when testing this variant.
-Each assignment's explicit persistent-name list supplies **only that historical
-membership**, not today's roster. Its recorded universe and timestamp supply
-the corresponding usage event. Missing universe or date evidence is never filled
+Each assignment's explicit persistent-name list or `{ name, role }` member list
+supplies **only that historical membership**, not today's roster. Member roles
+must agree with the authoritative charter. Its recorded universe and
+`timestamp`, `created_at`, `used_at`, or `assigned_at` value supplies the
+corresponding usage event. Missing universe or date evidence is never filled
 from the current naming policy or agent creation dates.
 
 Migration preserves agent IDs, names, original dates (including timezone offsets),
@@ -465,8 +469,11 @@ registry/history commit transaction. Repeating migration preserves managed bytes
 `squad upgrade --dry-run` validates and previews migration without creating locks,
 archives, or transaction files. Unknown schemas, damaged files, missing pair
 members, mismatched assignment evidence, or inconsistent managed transactions
-stop the upgrade before managed files change. Back up the state and seek recovery
-help; do not manually add `revision`, delete casting files, or rewrite dates.
+leave the casting pair byte-exact and produce an actionable warning. The rest of
+the upgrade continues, including client templates and the `squad_state` bridge,
+then repeats the casting warning in the completion summary. Back up the state and
+seek recovery help; do not manually add `revision`, delete casting files, or
+rewrite dates.
 
 #### Incomplete legacy provenance
 
@@ -476,12 +483,13 @@ Descriptive names alone do not prove a universe. A current coordinator's naming
 policy does not prove the policy of an older assignment. Migration will not
 invent a universe, usage entry, or historical membership.
 
-The historical `entries[]` / `assignments[]` pair requires recovery when original
-folder/charter identities are missing or ambiguous. Persistent names are not
-canonical folder IDs. Today's team roster is not evidence of which agents
-belonged to an older assignment. Restore the original authoritative `charter.md`
-files alongside the original casting pair; do not create charters from guessed
-name-to-folder mappings.
+The historical `entries[]` / `assignments[]` and `agents[]` / `assignments[]`
+pairs require recovery when original folder/charter identities are missing or
+ambiguous. The diagnostic names the unmapped persistent name and the number of
+matching folders. Persistent names are not canonical folder IDs. Today's team
+roster is not evidence of which agents belonged to an older assignment. Restore
+the original authoritative `charter.md` files alongside the original casting
+pair; do not create charters from guessed name-to-folder mappings.
 
 If either policy stops your upgrade:
 
 
@@ -14,7 +14,7 @@ import path from 'node:path';
 import { lstatSync, readFileSync, readdirSync, type Dirent } from 'node:fs';
 import { exec, execFileSync } from 'node:child_process';
 import { FSStorageProvider, resolveStateBackend, type StateBackendType } from '@bradygaster/squad-sdk';
-import { readCastingRegistryPair } from '@bradygaster/squad-sdk/casting';
+import { detectHistoricalCastingSchema, readCastingRegistryPair } from '@bradygaster/squad-sdk/casting';
 import { resolveSquad, resolveSquadPaths, clearResolveSquadCache } from '@bradygaster/squad-sdk/resolution';
 import { fatalNoSquad } from '../core/errors.js';
 import { isMutableStateKey, MUTABLE_STATE_PATHS } from '@bradygaster/squad-sdk/tools';
@@ -292,12 +292,30 @@ function checkAgentsDir(squadDir: string): DoctorCheck {
 }
 
 function checkCastingRegistry(squadDir: string): DoctorCheck {
-  const registryPath = path.join(squadDir, 'casting', 'registry.json');
+  const castingDir = path.join(squadDir, 'casting');
+  const registryPath = path.join(castingDir, 'registry.json');
   if (!fileExists(registryPath)) {
     return { name: 'casting/registry.json exists', status: 'fail', message: 'file not found' };
   }
   try {
-    readCastingRegistryPair(path.join(squadDir, 'casting'));
+    const registry = JSON.parse(storage.readSync(registryPath) ?? '{}') as unknown;
+    const history = JSON.parse(storage.readSync(path.join(castingDir, 'history.json')) ?? '{}') as unknown;
+    const legacySchema = detectHistoricalCastingSchema(registry, history);
+    if (legacySchema) {
+      return {
+        name: 'casting/registry.json exists',
+        status: 'fail',
+        message:
+          `detected legacy casting schema ${legacySchema} from a Squad 0.9.x coordinator. `
+          + 'Run `squad upgrade --force` to map persistent names through the existing agent folders, '
+          + 'preserve byte-exact originals, and create the managed durable pair.',
+      };
+    }
+  } catch {
+    // The strict pair reader below reports malformed JSON and missing history precisely.
+  }
+  try {
+    readCastingRegistryPair(castingDir);
   } catch (error) {
     return {
       name: 'casting/registry.json exists',
 
@@ -11,6 +11,7 @@ import { FSStorageProvider, stripTeamCapabilitiesBlock, syncTeamCapabilities } f
 import { clearResolveSquadCache, isRetiredProfileTeamRoot } from '@bradygaster/squad-sdk/resolution';
 import {
   backfillCastingRegistryFromTeam,
+  detectHistoricalCastingSchema,
   ensureCastingRegistryPair,
   normalizeCastingJsonLineEndings as normalizeCastingJsonFiles,
   preflightCastingRegistryPair,
@@ -298,6 +299,18 @@ function stripRetiredProfileTeamRoot(squadDir: string, dest: string, dryRun: boo
   const teamRoot = record['teamRoot'];
   if (typeof teamRoot !== 'string' || teamRoot.length === 0 || teamRoot === '.') return;
   const target = path.resolve(dest, teamRoot);
+  const comparable = (value: string) => process.platform === 'win32' ? value.toLowerCase() : value;
+  if (comparable(target) === comparable(path.resolve(dest))) {
+    if (dryRun) {
+      info('Would normalize the absolute "teamRoot" setting to "." in .squad/config.json.');
+      return;
+    }
+    record['teamRoot'] = '.';
+    storage.writeSync(configPath, JSON.stringify(record, null, 2) + '\n');
+    clearResolveSquadCache();
+    info('Normalized the absolute "teamRoot" setting to "." in .squad/config.json.');
+    return;
+  }
   if (!isRetiredProfileTeamRoot(target)) return;
   if (dryRun) {
     info('Would remove obsolete "teamRoot" setting from .squad/config.json.');
@@ -1157,7 +1170,12 @@ function runLegacySkillMigration(dest: string, filesUpdated: string[]): void {
   }
 }
 
-async function runEnsureChecks(dest: string, templatesDir: string, filesUpdated: string[]): Promise<void> {
+async function runEnsureChecks(
+  dest: string,
+  templatesDir: string,
+  filesUpdated: string[],
+  options: { skipCasting?: boolean } = {},
+): Promise<void> {
   const attrAdded = ensureGitattributes(dest);
   if (attrAdded.length > 0) {
     success(`ensured .gitattributes (${attrAdded.length} rules added)`);
@@ -1176,15 +1194,17 @@ async function runEnsureChecks(dest: string, templatesDir: string, filesUpdated:
     filesUpdated.push(...dirsCreated);
   }
 
-  const castingFiles = ensureCastingDefaults(dest, templatesDir);
-  if (castingFiles.length > 0) {
-    success(`scaffolded ${castingFiles.length} default casting files`);
-    filesUpdated.push(...castingFiles);
-  }
-  const normalizedCasting = normalizeCastingJsonLineEndings(dest);
-  if (normalizedCasting.length > 0) {
-    success(`normalized ${normalizedCasting.length} casting JSON file(s) to LF`);
-    filesUpdated.push(...normalizedCasting);
+  if (!options.skipCasting) {
+    const castingFiles = ensureCastingDefaults(dest, templatesDir);
+    if (castingFiles.length > 0) {
+      success(`scaffolded ${castingFiles.length} default casting files`);
+      filesUpdated.push(...castingFiles);
+    }
+    const normalizedCasting = normalizeCastingJsonLineEndings(dest);
+    if (normalizedCasting.length > 0) {
+      success(`normalized ${normalizedCasting.length} casting JSON file(s) to LF`);
+      filesUpdated.push(...normalizedCasting);
+    }
   }
 
   const memoryFiles = ensureMemoryGovernanceUpgradeDefaults(dest);
@@ -1535,6 +1555,22 @@ function warnCastingRepairSkipped(headline: string, result: RepairResult): void
   }
 }
 
+function detectLegacyCastingFiles(castingDir: string): ReturnType<typeof detectHistoricalCastingSchema> {
+  try {
+    const registry = JSON.parse(storage.readSync(path.join(castingDir, 'registry.json')) ?? '{}') as unknown;
+    const history = JSON.parse(storage.readSync(path.join(castingDir, 'history.json')) ?? '{}') as unknown;
+    return detectHistoricalCastingSchema(registry, history);
+  } catch {
+    return undefined;
+  }
+}
+
+function reportCastingMigrationFailure(message: string | undefined): void {
+  if (!message) return;
+  warn(`Upgrade completed, but legacy casting still needs repair: ${message}`);
+  info('  The original registry.json and history.json were left unchanged. See "Incomplete legacy provenance" in the upgrading guide, then run `squad upgrade --force` again.');
+}
+
 /**
  * Run the upgrade command
  */
@@ -1573,7 +1609,10 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
   // The repair reconciles a single Init Mode history snapshot; registries with real history keep failing closed.
   const castingDir = path.join(squadDirInfo.path, 'casting');
   const dryRun = options.dryRun ?? false;
-  const repair = repairHandwrittenCastingRegistry(castingDir, { dryRun });
+  const historicalSchema = detectLegacyCastingFiles(castingDir);
+  const repair: RepairResult = historicalSchema
+    ? { repaired: false, files: [] }
+    : repairHandwrittenCastingRegistry(castingDir, { dryRun });
   const handwrittenRepaired = repair.repaired;
   if (handwrittenRepaired) {
     if (dryRun) {
@@ -1586,13 +1625,22 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
   }
   // Legacy registries still go through the strict preflight (and its specific errors); only the
   // preflight's generic failure is enriched with the handwritten-repair reason and fix.
-  const castingMigrated = handwrittenRepaired && dryRun
-    ? false
-    : withCastingRepairContext(repair, () => preflightCastingRegistryPair(castingDir, dryRun));
+  let castingMigrationFailure: string | undefined;
+  let castingMigrated = false;
+  try {
+    castingMigrated = handwrittenRepaired && dryRun
+      ? false
+      : withCastingRepairContext(repair, () => preflightCastingRegistryPair(castingDir, dryRun));
+  } catch (error) {
+    castingMigrationFailure = error instanceof Error ? error.message : String(error);
+    warn(`Could not migrate legacy casting; continuing with the rest of the upgrade: ${castingMigrationFailure}`);
+  }
   if (castingMigrated) {
-    info(dryRun
-      ? 'Would migrate legacy casting state to a managed registry/history pair.'
-      : 'Migrated legacy casting state to a managed registry/history pair.');
+    if (dryRun) {
+      info('Would migrate legacy casting state to a managed registry/history pair.');
+    } else {
+      warn('Migrated legacy casting state to a managed registry/history pair; byte-exact originals were preserved in its legacy archive.');
+    }
   }
 
   // --dry-run: preview what upgrade would do without writing (#1052, #2297)
@@ -1639,6 +1687,7 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
       warn(`Could not plan client files: ${err instanceof Error ? err.message : String(err)}`);
     }
     console.log(`\nRun without --dry-run to apply.\n`);
+    reportCastingMigrationFailure(castingMigrationFailure);
     return { fromVersion: oldVersion, toVersion: cliVersion, filesUpdated: [], migrationsRun: [] };
   }
 
@@ -1661,7 +1710,7 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
     // to render the <!-- squad:capabilities --> block, so a 0.9.x project (empty casting/) would
     // otherwise get the block only on the SECOND upgrade (F4, upgrade matrix).
     prepareBuiltinAgents(dest, templatesDir, filesUpdated);
-    preflightCastingPair(dest, templatesDir, filesUpdated);
+    if (!castingMigrationFailure) preflightCastingPair(dest, templatesDir, filesUpdated);
 
     // Refresh squad.agent.md
     const agentSrc = path.join(templatesDir, 'squad.agent.md.template');
@@ -1675,8 +1724,9 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
     }
 
     // Run infrastructure ensure checks even when already current
-    await runEnsureChecks(dest, templatesDir, filesUpdated);
+    await runEnsureChecks(dest, templatesDir, filesUpdated, { skipCasting: !!castingMigrationFailure });
     await refreshClients(dest, squadDirInfo.path, options, filesUpdated);
+    reportCastingMigrationFailure(castingMigrationFailure);
 
     return {
       fromVersion: oldVersion,
@@ -1696,7 +1746,7 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
 
   // See preflightCastingPair: the capabilities block needs the casting pair first (F4).
   prepareBuiltinAgents(dest, templatesDir, filesUpdated);
-  preflightCastingPair(dest, templatesDir, filesUpdated);
+  if (!castingMigrationFailure) preflightCastingPair(dest, templatesDir, filesUpdated);
 
   storage.mkdirSync(path.dirname(agentDest), { recursive: true });
   writeAgentTemplate(agentSrc, agentDest, cliVersion, mcpConfigMode, isGitHubForMcp, { squadDir: squadDirInfo.path });
@@ -1734,7 +1784,7 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
   }
 
   // Run infrastructure ensure checks
-  await runEnsureChecks(dest, templatesDir, filesUpdated);
+  await runEnsureChecks(dest, templatesDir, filesUpdated, { skipCasting: !!castingMigrationFailure });
   await refreshClients(dest, squadDirInfo.path, options, filesUpdated);
 
   console.log();
@@ -1745,6 +1795,7 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
     dim('Preserves user state: team.md, decisions/, agents/*/history.md');
   }
   console.log();
+  reportCastingMigrationFailure(castingMigrationFailure);
 
   return {
     fromVersion: fromLabel,