Make AO storage match how AO actually works.

This is not a cosmetic refactor. It removes a foundational inconsistency.

Today AO stores project state under generated hash directories and keeps a storageKey indirection alive so the rest of the system can find it. That indirection leaks into core, CLI, web, recovery, config, and tests.

PR #1466 changes the storage model to the same unit the product already exposes: projectId. It also moves session metadata to JSON so lifecycle state, runtime handles, agent reports, and dashboard data are represented as structured data instead of encoded strings.

The design becomes obvious on disk.

~/.agent-orchestrator/{hash}-{project}/sessions/{sessionId}
~/.agent-orchestrator/{hash}-{project}/worktrees/
metadata: key=value strings
config: storageKey required
identity: sha256(configDir).slice(0,12)

~/.agent-orchestrator/projects/{projectId}/sessions/{sessionId}.json
~/.agent-orchestrator/projects/{projectId}/worktrees/
metadata: typed JSON
config: projectId is enough
identity: basename_sha256(path+origin).slice(0,10)

Where the lines actually go.

80 files, but not all files are equal. Most changes are mechanical (path replacements, test updates). The core logic that needs careful review is concentrated in a few files.

Core subsystem detail

The core package contains the highest-impact changes. Here is the breakdown by subsystem:

The old abstraction is becoming a tax on every feature.

Hashed identity, JSON metadata, safe migration.

Project ID safety

assertSafeProjectId validates all project IDs at the path boundary: must match /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/, length 1-128, no path traversal. Legacy IDs that don't match are sanitized during migration via sanitizeLegacyProjectId.

The risky part is migration. The PR treats migration as the product.

The branch went through 11 review rounds focused on the failure modes that matter: rollback, moved worktrees, corrupt metadata, active tmux sessions, archive collisions, cross-device moves, partial failures, and interrupted migration state.

11 review rounds shaped this PR.

This is not a one-shot branch. The migration logic was iterated across multiple review cycles, each catching real edge cases that would have hit production users.

How to review this efficiently.

This is a large PR. Not all 80 files need equal attention. Most changes are mechanical (path replacements, test updates). Focus review time on the design decisions below.

Priority 1: Migration safety (read carefully)

Priority 2: Metadata format (scan for correctness)

Priority 3: Mechanical changes (skim or skip)

40 test files. 54 migration-specific tests.

The migration is the riskiest part of this PR, so it has the deepest test coverage. The migration test suite covers every failure mode that was found during review.

• ao migrate-storage --dry-run previews without writing.
• ao migrate-storage converts legacy hash dirs to projects/{projectId}.
• ao migrate-storage --rollback restores legacy dirs and preserves post-migration sessions.
• Partial migration failure leaves config and marker intact for re-run.
• Moved worktrees have metadata patched to point at new location.
• Unsafe legacy project IDs are sanitized during migration.
• Shell hooks write valid JSON even without jq installed.
• Project collision returns structured 409 with resolution options.
• DELETE route handles unsafe project IDs gracefully (400, not crash).

Issues found and fixed during review.

These are the concrete issues caught during the review process. Each was fixed, tested, and pushed before this guide was written.

Merge this so future AO work does not build on the wrong storage abstraction.

The alternative is to keep teaching every new feature about storageKey, hash directories, flat metadata, and legacy collision behavior. That is not cheaper; it spreads the migration cost across future PRs.

PR #1466 pays that cost once across 80 files, with a visible migration command, 54 migration-specific tests, 11 review rounds of hardening, and the safety checks expected for production user data.