feat(sdk): StorageProvider — complete migration + example providers (#481)

[diberry]

StorageProvider Abstraction — Complete Migration

PRD bradygaster#481 — ~95% complete

115 files changed (+12457, -964) — single squashed commit.

---

StorageProvider API

The StorageProvider interface defines 24 methods — 12 async + 12 sync (deprecated):

Surface	Methods	Status
Async (12)	read, write, append, exists, list, delete, deleteDir, isDirectory, mkdir, rename, copy, stat	✅ Primary API
Sync (12)	readSync, writeSync, appendSync, existsSync, listSync, deleteSync, deleteDirSync, isDirectorySync, mkdirSync, statSync, renameSync, copySync	⚠️ Deprecated — removed in Wave 2

Built-in providers (FS, InMemory, SQLite) implement all 24 methods. The Azure Blob sample implements async only — sync methods throw with a clear deprecation message since cloud I/O cannot be synchronous.

All Waves Complete

Wave	Scope	Files	Status
Phase 0-2	Interface + 3 providers + SquadState facade	19	✅ Approved
3b (Shell)	Shell subsystem	5	✅ Approved
3a (Core Infra)	6 sync methods + 12 core files	16	✅ Approved
3c (CLI Commands)	deleteDirSync + 19 commands	20	✅ Approved
4 (SDK)	26 SDK module files	26	✅ Approved
Samples	SQLite + Azure Blob	9	✅ Approved

Intentional fs Retentions (6 total)

• CLI: createReadStream in rc.ts + start.ts (HTTP streaming)
• SDK: createWriteStream (bridge.ts), realpathSync (skill-script-loader.ts), cpSync (consult.ts), watch/FSWatcher (squad-observer.ts)

All outside StorageProvider scope — streaming, symlinks, dir copy, file watching.

Test Results

• 389 storage/contract tests pass
• 24/24 interface methods covered across 3 providers
• Pre-existing failures unchanged (see CI comment for details)

Example Providers

SQLite:

cd samples/storage-provider-sqlite && npm install && npm run demo

Azure Blob Storage:

# With Azurite (local emulator)
cd samples/storage-provider-azure && npm install
npm run azurite    # Terminal 1 — stores data in ./azurite/
npm run demo:emulator  # Terminal 2

# With real Azure
npm run azure:create   # Creates RG + storage account
export AZURE_STORAGE_CONNECTION_STRING="..."
npm run demo
npm run azure:delete   # Tear down when done

Both samples support --keep flag to preserve data for inspection, and npm run clean for cleanup.

CI Failures

• Fixed: ENOTDIR in agent listing (isDirectory guard), EACCES/EPERM cross-platform (accept both)
• Pre-existing on dev: ~20 async/await cascade failures from Wave 3b (see CI comment)

Remaining (separate PR)

• Wave 2: Remove deprecated sync methods (breaking change — async cascade across 50+ call sites)

[diberry]

CI Failure Analysis (commit b918ac7)

✅ Fixed in this push (PR-caused)

1. ENOTDIR in �gent-source.ts and personal.ts — When listing agents, files (not directories) in the agents/ folder caused FSStorageProvider.read to throw ENOTDIR when trying to read README.md/charter.md. Fixed by adding isDirectory() check before reading charter.

2. EACCES vs EPERM in storage-provider.test.ts:465 — Linux returns EACCES for readonly file writes, Windows returns EPERM. Test now accepts both: expect(['EPERM', 'EACCES']).toContain(code).

⚠️ Pre-existing on dev (NOT caused by this PR)

The remaining ~20 test failures are all the async/await cascade from Wave 3b (sync→async migration). Pattern: expected [] to include 'X' — a Promise object is treated as an empty iterable because test call sites were not updated with await.

Affected files (all pre-existing on dev):

• cli-shell-comprehensive.test.ts — 10 failures
• shell.test.ts — 7 failures
• repl-ux-fixes.test.ts — 5 failures

These tests fail identically on dev without this PR's changes. They will be fixed in a separate PR addressing the Wave 3b async test migration.

[diberry]

Rebased onto upstream/dev (328e1df) and retargeted to bradygaster/squad — see upstream PR bradygaster#640 (bradygaster#640)

[diberry]

Retargeted to bradygaster/squad — upstream PR open.