Reviewed by Codex

PR #1466 board brief

Storage V2 lands with hashed identity, migration tooling, and broader stop recovery.

Replaces hash-based storage with projects/{projectId}, introduces deterministic hashed project IDs, removes the storageKey system, adds crash-safe migration with rollback, and makes ao stop/ao start recoverable.

Base: upstream/main Head: storage-redesign Diff: +7,276 / -2,423

1. Start and Stop

The corrected direction shows ao stop becoming broader, and ao start gaining a restore prompt for sessions stopped previously.

ao start

Startup now offers to restore stopped sessions

Before, upstream/main

Started dashboard, lifecycle worker, and ensured the orchestrator.
No last-stop.json recovery prompt after startup.
Already-running flow offered open, new orchestrator, restart, or quit.

After, PR head

Still starts dashboard, lifecycle worker, and orchestrator.
Reads last-stop.json including otherProjects field.
Prompts to restore ALL sessions — current project and cross-project.
Loads global config for cross-project session manager access.
Skips restoring the orchestrator when already restored by ensureOrchestrator().

ao stop

Stop now tears down all sessions across all projects

Before, upstream/main

Located the most recently active orchestrator session.
Killed only that orchestrator session.
Stopped dashboard and unregistered running.json.
Only saw sessions from the local config (1 project).

After, PR head

Loads global config to see ALL registered projects.
ao stop (no args): kills all sessions across all projects, stops parent process and dashboard.
ao stop <project>: kills only that project's sessions, parent process and dashboard stay alive.
Records killed IDs to last-stop.json with otherProjects field for cross-project restore.
Groups killed sessions by project in output display.

Ctrl+C

Ctrl+C performs full graceful shutdown

Before, upstream/main

Stopped lifecycle workers and exited immediately.
Left sessions alive in tmux as orphans.
No last-stop.json recorded.
running.json left stale (auto-pruned on next read).

After, PR head

Mirrors ao stop: kills all sessions, writes last-stop.json, unregisters.
10s hard timeout ensures exit even if cleanup hangs.
Next ao start can restore sessions that were killed.

2. Kill and Restore Buttons

The web endpoints still call the same session-manager methods, but the PR changes metadata lifecycle semantics underneath those actions.

Dashboard action behavior

Action	Before, upstream/main	After, PR head	Implication
Kill button	Calls `POST /api/sessions/:id/kill`. Kill updated lifecycle and archived metadata by deleting the active metadata file with archive enabled.	Same endpoint, but killed sessions remain represented as metadata with a terminated lifecycle. Idempotency checks look for terminated lifecycle state instead of archive presence.	Killed sessions are easier for restore/status flows to find without archive lookup.
Restore button	Restore checked active metadata first, then archived metadata. Archived restore rehydrated metadata and set status to `spawning`.	Restore finds active metadata only, validates restorability, recreates workspace if needed, relaunches runtime, resets lifecycle to working, and clears terminal PR state.	Restore becomes lifecycle-reset based and tied to the active V2 metadata record.
Done bar restore	Done cards suppress Restore for merged cards using `canRestore && !isMerged`.	Restore is shown whenever the status is not in `NON_RESTORABLE_STATUSES`, so more done-card states expose recovery.	More completed/terminal-looking sessions can be resumed from the UI.

3. Hashed Project Identity

Project IDs become deterministic hashes instead of bare basenames, eliminating collisions across checkouts of the same repo.

New system

`generateExternalId(path, originUrl?)`

Format: {sanitized_basename}_{SHA256(path+originUrl)[0:10]}
Example: agent-orchestrator_a1b2c3d4e5
Deterministic — same path + origin always produces the same ID.
Collision throws instead of silently degrading.
Basename capped at 30 chars; parsed via id.match(/^(.+)_([0-9a-f]{10})$/).

Replaces bare basenames (e.g. agent-orchestrator) and the 12-char SHA-256 storage key from upstream/main. Same-name repos no longer need manual -1 / -2 suffixes, and re-cloning the same repo no longer produces a different storage key.

Removed

storageKey system fully removed

ensureProjectStorageIdentity
relinkProjectInGlobalConfig
deriveProjectStorageIdentity
findStorageKeyOwner, StorageKeyCollisionError
storageKey kept as optional schema field until ao migrate-storage strips it.
registerProjectInGlobalConfig now returns the effective hashed project ID.

4. migrate-storage

In the corrected diff, migrate-storage is introduced, not removed.

New command

Purpose-built migration from legacy hash storage to V2 project storage

1 Inventory Scans ~/.agent-orchestrator for legacy hash-based directories.

2 Guard Detects active tmux sessions and blocks migration unless --force is used.

3 Convert Moves sessions/worktrees into projects/{projectId} and converts key/value metadata to JSON.

4 Rollback Supports --rollback by restoring *.migrated directories and repairing git worktree references.

Before, upstream/main

No registered ao migrate-storage command.
Runtime used storage-key directories and flat key/value metadata.
Project relinking handled storage-key changes.

After, PR head

CLI registers ao migrate-storage.
Options: --dry-run, --force, --rollback.
New core module: packages/core/src/migration/storage-v2.ts.
Large test coverage added in migration-storage-v2.test.ts.

Safety hardening

Migration crash safety and concurrency fixes

Five post-review fixes applied to make the migration safe for production data:

1 Atomic writes All session JSON writes use atomicWriteFileSync. Crash mid-write no longer truncates files.

2 Config lock stripStorageKeysFromConfig wrapped in withFileLockSync. No more race with concurrent ao start.

3 macOS collision Case-insensitive projectId collision detection prevents silent data merge on HFS+/APFS.

4 Partial failure Stray worktree moves skip failed projects. Rollback calls repairGitWorktrees.

5. Storage Layout: Before vs Now

This is the architectural center of the PR: AO moves from storage-key/hash buckets to stable project directories with JSON session metadata.

Before, upstream/main

Storage key was the filesystem identity

~/.agent-orchestrator/
├── 7dc54da05c9e-agent-orchestrator/
│   ├── sessions/
│   │   ├── ao-79              # key=value metadata
│   │   ├── ao-orchestrator    # key=value metadata
│   │   └── archive/
│   │       └── ao-79_20260422T083732Z
│   └── worktrees/
│       └── ao-79/
├── eca743472f76-donna/
│   ├── sessions/
│   └── worktrees/
└── config.yaml
    projects.*.storageKey: 7dc54da05c9e

After, PR head

Project ID is the filesystem identity

~/.agent-orchestrator/
├── projects/
│   ├── agent-orchestrator/
│   │   ├── sessions/
│   │   │   ├── ao-79.json
│   │   │   ├── ao-orchestrator.json
│   │   │   └── .agent-report-audit/
│   │   │       └── ao-79.ndjson
│   │   ├── worktrees/
│   │   │   └── ao-79/
│   │   └── worker-prompt-ao-79.md
│   └── donna/
│       ├── sessions/
│       └── worktrees/
├── 7dc54da05c9e-agent-orchestrator.migrated/
└── config.yaml
    projects.*.projectId: agent-orchestrator

What moved where

Object

Before

Now

Projects

Project data was spread across hash/storage-key directories such as ~/.agent-orchestrator/7dc54da05c9e-agent-orchestrator.

Project data is grouped under ~/.agent-orchestrator/projects/{projectId}, for example projects/agent-orchestrator.

Sessions

Session files lived in {storageKey}/sessions/{sessionId} without a JSON extension.

Session files live in projects/{projectId}/sessions/{sessionId}.json.

Metadata

Metadata was flat key=value text. Status, runtime handle, lifecycle, and report fields were split across scalar keys.

Metadata is canonical JSON. Lifecycle, runtime handle, dashboard, agent report, and report watcher data are structured objects.

Archived sessions

Deleted/killed records moved into sessions/archive/{sessionId}_{timestamp}.

Terminated sessions remain visible as JSON metadata in sessions/. Migration flattens legacy archive files into terminated records.

Worktrees

Worktrees lived under {storageKey}/worktrees/{sessionId}, tied to the derived storage key.

Worktrees live under projects/{projectId}/worktrees/{sessionId}, tied to project identity.

Config

Global config carried storageKey per project to locate the hash bucket.

Runtime lookup is project-ID based. On successful migration, storageKey is stripped and old hash dirs are renamed to *.migrated.

Local legacy evidence Many 12hex-name.migrated dirs remain under ~/.agent-orchestrator.

Local V2 evidence ~/.agent-orchestrator/projects/agent-orchestrator/sessions/*.json exists.

Project worktrees projects/agent-orchestrator/worktrees/ao-84 shows V2 worktree placement.

Report audit sessions/.agent-report-audit/*.ndjson stores report history beside session metadata.

6. UX Changes

The PR exposes the storage-redesign workflow through CLI, dashboard, and project settings.

Start/stop

Stop becomes recoverable

ao stop records stopped sessions, and ao start can restore them interactively on the next launch.

Project identity

Storage key fades from UI

The PR removes storage key from some project settings surfaces as storage moves to projects/{projectId}.

Add project

ID collision UX returns

Add-project conflict handling moves back toward project-ID suggestions instead of storage-key reuse confirmation.

Status CLI

Report history added

ao status --reports <value> can show agent report audit history, with full or a numeric limit.

Project CLI

Relink command removed

The storage-key relink command disappears because V2 storage no longer depends on repo-origin derived storage keys.

Metadata

JSON becomes canonical

Session files become .json, with lifecycle stored as an object and status derived from lifecycle where possible.

Bug fix

Orchestrator tmux double-prefix

getOrchestratorSessionId() already returns {prefix}-orchestrator. The spawn path was prepending the prefix again, producing ao-ao-orchestrator. Fixed to use sessionId directly as the tmux name.

Worktree routing

Plugin routes to V2 layout

Added worktreeDir to WorkspaceCreateConfig. Session manager passes getProjectWorktreesDir(projectId) at all 3 spawn/restore sites, routing worktrees to projects/{id}/worktrees/ instead of ~/.worktrees/.

Archiving removed

No more archive/ directory

Killed/terminated sessions stay as JSON metadata in sessions/ with a terminal lifecycle state. The archive/ directory concept, deleteMetadata archiving, and archive path functions are fully removed.

7. Behavioral Bug Fixes

Cross-cutting fixes discovered during storage redesign testing — runtime reconciliation, dashboard scoping, config resolution, and tab completions.

Bug fix

Stale runtime reconciliation

Sessions with dead tmux runtimes showed as "active" indefinitely. sm.list() now detects dead runtimes during enrichment and persists runtime_lost reason to disk. deriveLegacyStatus() maps runtime_lost → killed.

Bug fix

Dashboard sidebar shows all projects

Sidebar only showed sessions for the currently-viewed project. useSessionEvents in Dashboard.tsx is now called without a project filter. Kanban filters client-side via projectSessions memo. Sidebar always sees every project's sessions.

Bug fix

Tab completions show all projects

listProjects() only called loadConfig(), which found the local config (1 project). Now also reads global config via loadGlobalConfig() and merges both project lists.

Bug fix

Config resolution falls back to global

ao stop donna failed with "project not found" when cwd config didn't contain it. CLI now falls back to global config at ~/.agent-orchestrator/config.yaml for both ao stop and ao start.

8. Documentation Updates

Architecture docs updated to reflect CLI behavior, lifecycle, and dashboard changes.

CLAUDE.md

Session lifecycle, storage, CLI behavior

Added canonical lifecycle states/reasons, stale runtime reconciliation, LastStopState + running.json to storage section, config resolution note, new "CLI Behavior" section (ao start/stop/Ctrl+C semantics, dashboard sidebar behavior), and key files (lifecycle-state.ts, running-state.ts, start.ts).

AGENTS.md + copilot-instructions.md

Key files and common mistakes

Added lifecycle-state.ts, start.ts, running-state.ts to key files. Added common mistakes: runtime_lost without deriveLegacyStatus, sidebar project scoping, ao stop parent process kill scoping.

9. LOC Change Overview

Fetched comparison: git diff --shortstat upstream/main..HEAD.

By area

packages/core

+3,448

STORAGE_REDESIGN.md

+405

packages/cli

+280

packages/web

+103

plugins

+50

integration-tests

-20

Overall summary

This PR ships the storage redesign, cross-project CLI, and behavioral hardening.

The PR moves AO from storage-key based flat metadata to project-scoped JSON storage with deterministic hashed project IDs. It removes the entire storageKey system, removes archiving (terminated sessions stay visible), adds a crash-safe migration command with rollback, and makes stop/start fully recoverable with cross-project awareness. Fixes stale runtime detection, dashboard sidebar scoping, Ctrl+C shutdown, tab completions, and config resolution across all CLI commands.

Strategic direction Adopts V2 storage: projects/{projectId}, JSON metadata, lifecycle-centered status. Removes the entire storageKey system.

Identity model Hashed project IDs ({basename}_{hash}) replace bare basenames. Deterministic, collision-safe, no manual suffixes.

Cross-project CLI ao stop sees all projects via global config, records cross-project sessions. ao stop <project> is surgical. ao start restores all including cross-project. Ctrl+C mirrors ao stop.

Runtime reconciliation Dead tmux sessions detected by sm.list() enrichment and persisted as runtime_lost → killed. No more stale "active" sessions.

Dashboard Sidebar always shows all projects' sessions. Kanban filters client-side. Tab completions merge local + global config.

Migration safety Atomic writes, file-locked config updates, macOS case-insensitive collision detection, git worktree repair in rollback, partial-failure isolation.

Documentation CLAUDE.md, AGENTS.md, copilot-instructions.md, and DESIGN.md updated with CLI behavior, lifecycle states, and architectural invariants.

Commit Story

90 PR commits between upstream/main..HEAD, grouped by theme. The chronology was messy; the themes are not. Click any group to see its commits.

The PR landed in roughly four arcs: a foundational layout move (V2 storage, hashed identity, JSON metadata), a simplification pass (archive removal, status dual-truth elimination), a migration safety harness (rollback, edge cases, atomic ops), and a cross-project CLI rework (stop/start/Ctrl+C, tab completions, sidebar scoping). Review-iteration commits are bucketed separately.

A · Foundation

V2 storage layout & hashed project identity

6 commits

Replaces the storageKey-based flat layout with projects/{projectId}/ where projectId is {basename}_{hash} — deterministic, collision-safe, no manual suffixes. Every downstream consumer (worktree allocator, web tmux resolver, ao status) is updated to use the new path helpers.

Commits

e34b3ec5Implement hashed project identity
f53acd61fix(core,workspace): route new worktrees to V2 project directory
f7118ef1fix(core,cli,web): allocate suffixed project ids on duplicate names
f674422aFix orchestrator identity to use one canonical session per project (#1487)
eca3001cfix(web): resolve tmux sessions when storageKey is wrapped (#1488)
643bb5e3fix(cli): replace removed storageKey reference with getProjectSessionsDir

B · Format

JSON metadata format

1 commit

Session metadata flips from key-value flat files to JSON. The PostToolUse and PATH-wrapper hooks that mutate metadata had to learn the new format and the .json extension.

Commits

721a8726fix(core): update metadata hooks for JSON format and .json extension

C · Simplification

Archive directory removal

11 commits

The archive/ directory is gone. Terminated sessions stay in sessions/ with a terminated lifecycle — restore, status, and dashboard flows no longer need a second lookup path. The migration flattens existing archives in-place.

Commits

f2b7141brefactor(core): remove archive path functions from paths.ts and index.ts
f3ab2206refactor(core): remove archive logic from metadata.ts
72c31489refactor(core): remove archive code from session-manager.ts
479f285efix(core): stop archiving sessions on cleanup in recovery/actions.ts
46c8dbdarefactor(core): flatten archives into sessions/ during migration
b24d225crefactor(core): remove archive directory filter from listMetadata
82adbbb7fix(core): update tests to match archive-removal behavior
45ac35f2fix(core): address build/test issues from archive removal
fe1d7fd8fix(integration-tests): update archive filename regex for PID suffix
1bf90801docs: update handoff doc — archiving removed
c057c1ffdocs: remove handoff document

D · Safety

Crash-safe migration & rollback

14 commits

The most defensive arc of the PR. Real-world migration has to survive partial failures, interrupted runs, macOS case-insensitive collisions, stale tmux sessions, dry-run mode, and recursive worktree paths. Most of these commits are review-driven hardening of migrate-storage's atomic-ops + rollback machinery.

Commits

e530e4e1prevent silent data loss on upgrade — V1 detection, git worktree repair, storageKey preservation
a4923d7eharden storage redesign migration rollback
b36a5f1efinal merge review — Zod schema gaps, worktree repair, rollback safety, status priority
64caef04harden storage-redesign against edge cases (EC-1..EC-8, EC-14, EC-27)
bb4c68fccrash safety, atomic ops, corrupt data handling, test fixes
880930a2skip .migrated dirs in inventory to prevent .migrated.migrated on re-run
ff61ee97fix stray worktree recursion, rollback data loss, worktree path rewrite
3d6f70ebfix 3 critical migration issues
fd4f969frollback worktree preservation, scoped tmux detection, JSON parse whitelist
c800c89cskip active session check during migrate-storage --dry-run
752c01f7correct migration error message to use ao session kill
b18cbe22graceful migration errors + skip orchestrator selector
3aaef7d8address migration review findings and orchestrator tmux double-prefix
8df05b7aaddress review findings — worktree paths, archive location, recovery log

E · Refactor

Status / lifecycle dual-truth elimination

6 commits

The legacy SessionStatus field used to be persisted alongside the lifecycle state — two sources of truth that drifted. Status is now derived from state + reason. Restore flows reset lifecycle and PR state cleanly, including for previously-merged sessions.

Commits

b8867941eliminate status dual truth, fix jsonFields whitelist, add rollback dry-run and tests
e9d9c762remove stale previousStatus args and unused SessionStatus import
d22f0c6freset lifecycle on restore and keep killed sessions in active metadata
fc6fd88breset terminal PR state on session restore
ad6c9f4badd --dangerously-skip-permissions for all restored sessions
b178eb66fix(core,web): allow restoring merged sessions

F · CLI

`ao stop` — cross-project + last-stop persistence

7 commits

ao stop with no args now tears down every project's sessions and writes last-stop.json with an otherProjects field for cross-project restore. ao stop <project> is surgical — does not touch the parent process or the dashboard. Required loading global config instead of just local.

Commits

27590ac4feat(cli): add last-stop state persistence for ao stop/start restore
5b5a1bd4feat(cli): ao stop kills all active sessions and records them
2d1d9df8fix(cli): update stop tests for all-sessions kill behavior
9e2df894fix(core): persist stale runtime state + show cross-project sessions in ao stop/start
97fc8348fix(cli): scope ao stop to target project when explicit arg is given
95cf979dfix(cli): ao stop <project> must not kill parent process or dashboard
6d7bae68fix(cli): always load global config for ao stop to see all projects

G · CLI

`ao start` — restore prompt + project picker

5 commits

Startup reads last-stop.json and offers to restore everything killed in the previous shutdown — including sessions from other projects. The picker also gains an "Add this project" affordance when launched in an unregistered cwd.

Commits

bcab5462feat(cli): ao start offers to restore sessions from last ao stop
8b130964fix(cli): ao start restores all sessions including cross-project ones
1972fa30fix(cli): auto-register flat local config in ao start
d6a56a8ffeat(cli): show "Add project" in already-running menu when cwd is unregistered
e1ecc091feat(cli): show "Add this project" option in ao start project picker

H · CLI

Cross-project visibility — global config & tab completions

2 commits

Commands that need to see beyond the local agent-orchestrator.yaml (tab completions, ao stop <other-project>) now merge in the global config at ~/.agent-orchestrator/config.yaml.

Commits

39ebb07ffix(cli): show all projects in tab completions by merging global config
2db2951afix(cli): fall back to global config when project arg not in local config

I · CLI

Ctrl+C graceful shutdown

1 commit

Ctrl+C on ao start now mirrors ao stop: kills every session, writes last-stop.json, unregisters running.json, with a 10s hard timeout in case cleanup hangs.

Commits

b4feda79fix(cli): Ctrl+C on ao start performs full graceful shutdown

J · Web

Dashboard sidebar scoping

1 commit

The sidebar always renders all sessions across projects; per-project filtering is applied client-side at the kanban level. Fixes a regression where switching active projects hid the sidebar contents.

Commits

53e8476ffix(web): sidebar shows all sessions regardless of active project

K · Feature

`ao status --reports`

1 commit

Adds a --reports flag to surface agent report history from the status command — companion feature shipped alongside the storage rework.

Commits

ea24dbb1feat(cli): add --reports flag to ao status for agent report history

L · Review

Review fixes, lint, conflict resolution

~16 commits

The review-iteration bucket — multiple rounds of Copilot/human review feedback, ESLint fixes, gitleaks false-positive sweeps, and merge-conflict resolution against a moving upstream. Bundled here so the themed groups above stay readable.

Commits

65875bd9fix: address storage redesign review issues
27666c6efix(core): address review — sed JSON corruption, sanitizeBasename dot
cc75471efix(core): address PR review comments
896468a2address PR review comments — parser, docs, delete route, prefix sanitization
0d4563a1fix(core): use strict equality to satisfy eqeqeq lint rule
d173b471fix(core,cli,web): address PR #1466 review findings
57acc4cffix(core,web): address Copilot review comments
8311a3e4fix(core,cli): resolve merge conflicts with upstream/main
49817974fix(cli): prefix unused addCwdOption variable to satisfy lint
e030d6efMerge PR #176 — fix/storage-redesign-review-fixes
7484c001fix(core): address storage redesign review findings
1b404d2ffix(core): remove unused readMetadata import in lifecycle test
31b20ed2fix: replace high-entropy test placeholder to avoid gitleaks
3e23c8dbfix: targeted regex instead of path allowlist for gitleaks
1e97cd21fix(core,cli): align with upstream to reduce merge conflicts
2fac0bd5fix: resolve Phase 1+2 merge conflicts with upstream/main (#1487, #1238)

M · Docs

Architecture & behavior dashboard docs

3 commits

CLAUDE.md, AGENTS.md, copilot-instructions.md, and DESIGN.md updated for the new CLI semantics, lifecycle states, and storage layout. Plus iterations on this behavior dashboard itself.

Commits

2d8fe4e7docs: update architecture docs for CLI, lifecycle, and dashboard changes
6d968b9fdocs: update PR behavior dashboard with behavioral fixes and cross-project CLI
1428caddRevert "docs: update PR behavior dashboard ..."

N · Upstream

Upstream synced via merges

~25 commits, not PR work

Brought in by three Merge upstream/main commits over the lifetime of the branch. Listed here only so the count reconciles with git log upstream/main..HEAD; they are not part of the PR's authored changes.

Examples

210f9d23Merge branch 'main' into storage-redesign
a66a5362Merge remote-tracking branch 'upstream/main' into storage-redesign
452d1937Merge remote-tracking branch 'upstream/main' into storage-redesign
a8bc7469feat(core): opt-in gh CLI tracer + scm/tracker migration (#1238)
dcfb6fe8feat: add $schema support to agent-orchestrator.yaml (#1373)
aa3342bbperf(core): cache sessionManager.list() (#1113)
2bfcbc64refactor(web): break down DirectTerminal.tsx (#1448)
eb7314b0refactor(web): break down SessionDetail.tsx (#1449)
e4706840refactor(web): reconcile duplicate SessionDetailPRCard (#1442)
0538e07bFix root dashboard project selection (#1480)
b086908fadd zsh completion support for ao (#1374)
84cd105cfeat(web): enable tmux status bar in web terminal (#1470)
… and ~13 more upstream commits

LOC Explanation

Scope: every changed file under packages/core. PR headline count: 7,276 additions and 2,423 deletions. GitHub activity: 51 conversations, 90 commits, 10 checks.

Core subtotal

49core files

4,672core additions

1,804core deletions

+2,868core net LOC

Most of the core churn is intentional storage-redesign work: V2 projects/{projectId} paths, JSON metadata, lifecycle-derived status, archive removal, and the migration/rollback harness. Test LOC dominates the additions, especially the new migration coverage.

Core files, sorted by additions

File	LOC	What changed
`packages/core/src/__tests__/migration-storage-v2.test.ts`	+1,561 / -0	Adds comprehensive migration coverage for V1-to-V2 layout conversion, rollback, dry-run, archives, worktrees, collisions, malformed data, active sessions, and idempotency.
`packages/core/src/migration/storage-v2.ts`	+1,367 / -0	Adds the storage migration engine: inventory, dry-run, active session checks, JSON conversion, archive flattening, worktree repair, rollback, idempotency, and recovery logging.
`packages/core/src/metadata.ts`	+229 / -179	Replaces key=value metadata with JSON read/write/mutate flows, handles typed runtime/dashboard/lifecycle fields, treats empty reserved files safely, and removes archive metadata APIs.
`packages/core/src/__tests__/metadata.test.ts`	+210 / -171	Replaces flat-file metadata tests with JSON serialization, typed-field migration, displayName preservation, empty-file mutation, and archive-removal expectations.
`packages/core/src/session-manager.ts`	+181 / -211	Rewires session CRUD to projectId paths, JSON metadata, lifecycle-derived status, stale runtime reconciliation, terminated-session restore, and permanent metadata deletion without archive APIs.
`packages/core/src/__tests__/global-config.test.ts`	+128 / -183	Replaces suffix/storageKey/relink coverage with deterministic hashed ID registration, same-path reconnect, global config behavior, and collision handling.
`packages/core/src/global-config.ts`	+107 / -309	Deletes storageKey collision/relink machinery and replaces suffix allocation with deterministic hashed project IDs, same-path reconnection, and explicit collision failure.
`packages/core/src/paths.ts`	+107 / -17	Adds V2 path helpers for projects, sessions, metadata files, worktrees, migration markers, and V1 detection while removing archive path helpers.
`packages/core/src/__tests__/recovery-actions.test.ts`	+87 / -71	Reworks cleanup tests so terminated sessions stay in sessions/ with lifecycle state instead of moving to archive.
`packages/core/src/__tests__/paths.test.ts`	+81 / -0	Adds path helper tests for V2 project/session/worktree paths, metadata extension behavior, and V1 detection.
`packages/core/src/__tests__/session-manager/restore.test.ts`	+64 / -104	Removes archive restore expectations and adds restore coverage for terminated/merged sessions, permission preservation, and runtimeHandle object shape.
`packages/core/src/__tests__/session-manager/lifecycle.test.ts`	+51 / -40	Adds/updates lifecycle tests for terminal reasons, stale runtime persistence, and derived legacy status behavior.
`packages/core/src/portfolio-session-service.ts`	+42 / -20	Reads sessions from project-scoped JSON metadata and enriches cross-project session listings without archive fallback.
`packages/core/src/__tests__/portfolio-session-service.test.ts`	+35 / -40	Updates portfolio session listing fixtures for JSON metadata, V2 paths, and no archive fallback.
`packages/core/src/lifecycle-state.ts`	+35 / -20	Expands lifecycle derivation so legacy display status is computed from canonical state, terminal reason, and PR state rather than persisted separately.
`packages/core/src/agent-workspace-hooks.ts`	+34 / -11	Reworks hook-side metadata mutation for JSON files and V2 session paths, including safer handling around session metadata writes.
`packages/core/src/__tests__/session-manager/claim-pr.test.ts`	+29 / -29	Refreshes PR claim fixtures to new metadata shape while preserving the claim behavior under test.
`packages/core/src/lifecycle-manager.ts`	+28 / -24	Moves polling and session status decisions onto canonical lifecycle state/reason, including persistence for lost runtimes.
`packages/core/src/__tests__/lifecycle-transition.test.ts`	+26 / -32	Rewrites transition assertions around canonical lifecycle and removes previousStatus expectations.
`packages/core/src/index.ts`	+24 / -4	Exports the new storage V2, lifecycle, migration, and metadata helpers while dropping removed archive/storageKey exports.
`packages/core/src/__tests__/lifecycle-state.test.ts`	+23 / -10	Adds coverage for new state/reason to legacy status mapping, including terminal runtime-lost behavior.
`packages/core/src/__tests__/session-manager/query.test.ts`	+21 / -22	Updates query/list tests for sessions retained in the active sessions directory and lifecycle-derived status.
`packages/core/src/types.ts`	+20 / -39	Changes core types by removing storageKey, nesting runtime/dashboard/lifecycle metadata, and tightening lifecycle/status shapes.
`packages/core/src/lifecycle-status-decisions.ts`	+19 / -21	Updates status decision output to the nested lifecycle/detecting shape and removes previousStatus as an input dependency.
`packages/core/src/__tests__/session-manager/communication.test.ts`	+17 / -17	Updates communication tests for JSON metadata and projectId session lookup paths.
`packages/core/src/lifecycle-transition.ts`	+15 / -19	Simplifies transitions around canonical lifecycle fields and removes now-stale legacy status preservation paths.
`packages/core/src/__tests__/lifecycle-manager.test.ts`	+15 / -15	Adjusts lifecycle polling expectations to canonical lifecycle state and derived legacy status.
`packages/core/src/__tests__/plugin-integration.test.ts`	+14 / -6	Updates plugin integration fixtures to use projectId identity and new metadata layout.
`packages/core/src/utils/metadata-flatten.ts`	+13 / -0	Adds a shared flattening helper for metadata compatibility paths that still need string-record views.
`packages/core/src/__tests__/lifecycle-status-decisions.test.ts`	+10 / -10	Updates decision fixtures for the nested lifecycle/detecting result shape.
`packages/core/src/__tests__/test-utils.ts`	+10 / -16	Simplifies shared test helpers around the new metadata/config shape and removes legacy storageKey setup.
`packages/core/src/__tests__/recovery-validator.test.ts`	+9 / -9	Updates validator fixtures for V2 path names and lifecycle metadata shape.
`packages/core/src/__tests__/session-manager/spawn.test.ts`	+9 / -4	Updates spawn fixtures for projectId storage paths and new metadata defaults.
`packages/core/src/recovery/scanner.ts`	+8 / -6	Scans V2 project/session directories and skips migration artifacts that should not be treated as live projects.
`packages/core/src/portfolio-registry.ts`	+7 / -17	Aligns portfolio registry entries with projectId identity and removes storageKey fields from registry persistence.
`packages/core/src/__tests__/agent-report.test.ts`	+6 / -6	Updates report fixtures and expectations for JSON metadata/V2 paths.
`packages/core/src/__tests__/session-manager.test.ts`	+6 / -6	Adjusts high-level session manager expectations for JSON metadata files and derived status.
`packages/core/src/recovery/actions.ts`	+5 / -6	Stops cleanup from moving sessions into archives and instead marks terminated lifecycle state in-place.
`packages/core/src/__tests__/session-manager/cache.test.ts`	+5 / -3	Updates cache tests for the V2 metadata source and stale runtime enrichment path.
`packages/core/package.json`	+4 / -0	Adds package dependencies or exports needed by the storage migration/runtime changes.
`packages/core/src/__tests__/portfolio-registry.test.ts`	+3 / -4	Adjusts registry expectations after storageKey was removed from persisted project entries.
`packages/core/src/agent-report.ts`	+3 / -3	Swaps report lookup path usage to the new project/session metadata conventions without changing the report surface.
`packages/core/src/config.ts`	+2 / -21	Removes storageKey-era config plumbing and narrows project identity to the project ID based resolver path.
`packages/core/rollup.config.ts`	+1 / -0	Updates the build input/external handling so the new core module graph bundles cleanly.
`packages/core/src/utils/session-from-metadata.ts`	+1 / -1	Updates session materialization to use the new lifecycle/status derivation semantics.
`packages/core/__tests__/config.test.ts`	+0 / -43	Removes storageKey config assertions that no longer apply after project identity moved to projectId.
`packages/core/src/__tests__/config-validation.test.ts`	+0 / -24	Drops validation cases for removed storageKey fields.
`packages/core/src/__tests__/portfolio-projects.test.ts`	+0 / -2	Removes storageKey assertions from portfolio project shape tests.
`packages/core/src/__tests__/project-resolver.test.ts`	+0 / -9	Deletes resolver expectations tied to storageKey wrapping and legacy project identity.

Corrected after git fetch upstream and generated from upstream/main..HEAD in /Users/harshitsinghbhandari/Downloads/side-quests/agent-orchestrator.

Storage V2 lands with hashed identity, migration tooling, and broader stop recovery.

1. Start and Stop

Startup now offers to restore stopped sessions

Stop now tears down all sessions across all projects

Ctrl+C performs full graceful shutdown

2. Kill and Restore Buttons

Dashboard action behavior

3. Hashed Project Identity

generateExternalId(path, originUrl?)

storageKey system fully removed

4. migrate-storage

Purpose-built migration from legacy hash storage to V2 project storage

Migration crash safety and concurrency fixes

5. Storage Layout: Before vs Now

Storage key was the filesystem identity

Project ID is the filesystem identity

What moved where

6. UX Changes

Stop becomes recoverable

Storage key fades from UI

ID collision UX returns

Report history added

Relink command removed

JSON becomes canonical

Orchestrator tmux double-prefix

Plugin routes to V2 layout

No more archive/ directory

7. Behavioral Bug Fixes

Stale runtime reconciliation

Dashboard sidebar shows all projects

Tab completions show all projects

Config resolution falls back to global

8. Documentation Updates

Session lifecycle, storage, CLI behavior

Key files and common mistakes

9. LOC Change Overview

By area

This PR ships the storage redesign, cross-project CLI, and behavioral hardening.

Commit Story

V2 storage layout & hashed project identity

JSON metadata format

Archive directory removal

Crash-safe migration & rollback

Status / lifecycle dual-truth elimination

ao stop — cross-project + last-stop persistence

ao start — restore prompt + project picker

Cross-project visibility — global config & tab completions

Ctrl+C graceful shutdown

Dashboard sidebar scoping

ao status --reports

Review fixes, lint, conflict resolution

Architecture & behavior dashboard docs

Upstream synced via merges

LOC Explanation

Core subtotal

Core files, sorted by additions

`generateExternalId(path, originUrl?)`

`ao stop` — cross-project + last-stop persistence

`ao start` — restore prompt + project picker

`ao status --reports`