bug: upgrade pipeline gaps — postinstall misses repo-local node_modules, two-layer hooks not installed, teamRoot not portable #1190

Summary

After upgrading to 0.9.6-insider.3 with stateBackend=two-layer, three related gaps in the upgrade pipeline leave a repo in a subtly broken state that squad doctor only partially catches.

Environment

• squad-cli: 0.9.6-insider.3 (global), 0.9.1 (repo-local)
• Windows 11, PowerShell, Node v23.5.0
• stateBackend: "two-layer" in .squad/config.json

Finding 1 — postinstall ESM patch misses repo-local node_modules (references #449)

squad doctor reports two failures after a global install of 0.9.6-insider.3:

❌  vscode-jsonrpc exports field — missing exports field — run postinstall or reinstall (see #449)
❌  copilot-sdk session.js ESM patch — session.js has extensionless vscode-jsonrpc/node import

Running npm run postinstall from the global squad-cli package dir reports "already patched — skipping" yet doctor still fails. Root cause: patch-esm-imports.mjs uses hardcoded SEARCH_ROOTS relative to __dirname of the global install:

const SEARCH_ROOTS = [
  join(__dirname, '..', 'node_modules'),              // squad-cli local
  join(__dirname, '..', '..', '..', 'node_modules'),  // workspace root
  join(__dirname, '..', '..'),                         // global install (sibling)
];

None of these resolve to <repo>/node_modules. The repo-local node_modules (where doctor actually checks) is never patched.

Fix: Add join(process.cwd(), 'node_modules') to SEARCH_ROOTS. Additionally, squad upgrade should invoke the patch script from the repo root (not the global package dir) after install completes.

Finding 2 — pre-commit / post-commit hooks missing after two-layer upgrade (references #1185)

Because --state-backend migration was ignored during upgrade (#1185), the pre-commit and post-commit hooks required by two-layer were never installed. The squad-state orphan branch exists but has only its init commit — nothing has ever written to it.

Installed hooks after upgrade:

squad doctor does not flag this even though stateBackend=two-layer is configured. The state branch is silently dormant.

Fix: squad doctor should cross-check: if stateBackend=two-layer, verify pre-commit and post-commit hooks are present and warn/error if not.

Finding 3 — teamRoot absolute path not portable; squad upgrade / squad init should default to "." (references #1163)

squad upgrade writes teamRoot as an absolute path (e.g. C:\Users\...\tamresearch1). When the same repo is cloned to a different path or machine, squad doctor fails:

❌  team root resolves — directory not found

teamRoot: "." is a portable relative default. Machine-specific absolute paths should live in peers.<machineId>.teamRoot, not the top-level field.

Additionally, config.json had a duplicate stateBackend key — written once at the top and appended again at the end by the upgrade path. Non-breaking (JSON last-value wins) but indicates the upgrade config-write path appends rather than merges.

Fix:

• squad init / squad upgrade should write teamRoot: "." by default.
• Config write should merge/replace keys, not append.

Workaround (applied on our end)

1. Manually patched node_modules/vscode-jsonrpc/package.json with exports field and @github/copilot-sdk/dist/session.js to use .js extension.
2. Changed teamRoot to ".", updated peers.<machineId>.teamRoot to the correct absolute path.
3. Removed duplicate stateBackend key.

After these manual fixes: squad doctor → 13 passed, 0 failed, 0 warnings ✅

Related

• squad-cli fails with ERR_MODULE_NOT_FOUND on Node 22 (vscode-jsonrpc ESM import) #449 — original ESM/vscode-jsonrpc report
• squad upgrade --self --insider: misplaced templates, Rai not installed, --state-backend ignored #1185 — --state-backend ignored during upgrade (root cause of finding 2)
• Coordinator TEAM_ROOT has inconsistent semantics between State & Team Root Resolution and Worktree Awareness #1163 — teamRoot inconsistency and relative path support