Droids: Refactor sessions to use explicit repository associations

[Connoropolous]

Summary

• replace implicit primary-repository assumptions with explicit 0/1/N repository associations across session state, persistence, routing, prompts, and docs
• normalize persisted session state and runtime restore flows around repository associations, and harden multi-repo CLI/F1 selection behavior
• add audit, validation, and regression coverage plus F1-backed evidence for zero/one/many association flows

Validation

• pnpm --filter cyrus-core test:run -- repository-association
• pnpm --filter cyrus-core test:run -- PersistenceManager
• pnpm --filter cyrus-edge-worker exec vitest run test/RepositoryRouter.test.ts test/EdgeWorker.missing-session-recovery.test.ts
• pnpm --filter cyrus-edge-worker exec vitest run test/GlobalSessionRegistry.test.ts test/AgentSessionManager.repository-associations.test.ts test/EdgeWorker.missing-session-recovery.test.ts
• pnpm --filter cyrus-edge-worker exec vitest run test/prompt-assembly.routing-context.test.ts test/prompt-assembly.system-prompt-behavior.test.ts
• pnpm --filter cyrus-edge-worker exec vitest run test/EdgeWorker.missing-session-recovery.test.ts test/EdgeWorker.procedure-integration.test.ts test/EdgeWorker.cli-workspace-issue-trackers.test.ts test/RepositoryRouter.test.ts test/prompt-assembly.new-sessions.test.ts test/prompt-assembly.routing-context.test.ts
• pnpm --filter cyrus-claude-runner test:run -- ClaudeRunner
• pnpm typecheck
• pnpm lint
• pnpm build
• F1 multi-repo flows covering ambiguous routing, exact-name selection, and natural-language selection

Notes

• Broad pnpm test:packages:run -- --maxWorkers=8 still surfaces pre-existing unrelated edge-worker failures in screenshot-upload-hooks / feedback / runner-selection suites; milestone scrutiny overrides were recorded with validation artifacts for those known baseline issues.

[Connoropolous]

Guided tour of the changes

Here is a simple path through the PR, ordered from the highest-level intent down to the runtime details.

1. Start with the audit / map

If you want the "what problem were we fixing?" view first, start here:

• .factory/library/repository-association-audit.md

What you'll see:

• the old places where the code assumed one implicit repository
• the target 0/1/N repository-association model
• the repo-wide checklist used to make sure the assumption map covered the full codebase

2. Then look at the core session model

This is where the data model changes from implicit repo ownership to explicit associations.

• packages/core/src/CyrusAgentSession.ts
• packages/core/src/PersistenceManager.ts
• packages/core/test/repository-association.persistence.test.ts
• packages/core/test/PersistenceManager.migration.test.ts

What changed:

• sessions now carry explicit repositoryAssociations
• persistence now stores normalized session-keyed state instead of relying on repo buckets as the source of truth
• migration logic upgrades older persisted repo-keyed/session-cache shapes into the new normalized format

3. Then look at runtime routing and lifecycle

This is where the app stops silently picking a repository when routing is unclear.

• packages/edge-worker/src/RepositoryRouter.ts
• packages/edge-worker/src/EdgeWorker.ts
• packages/edge-worker/src/GlobalSessionRegistry.ts
• packages/edge-worker/src/AgentSessionManager.ts
• packages/edge-worker/test/RepositoryRouter.test.ts
• packages/edge-worker/test/EdgeWorker.missing-session-recovery.test.ts
• packages/edge-worker/test/AgentSessionManager.repository-associations.test.ts
• packages/edge-worker/test/GlobalSessionRegistry.test.ts

What to look for:

• unresolved routing now stays unresolved via needs_selection
• invalid repository-selection replies no longer fall back to the first candidate repo
• runtime restore / lookup behavior now follows explicit repository associations
• the global session registry is used as the authoritative runtime store for persisted session state and repo-association lookups

4. Then look at prompt / orchestrator wording

This is where the session-wide "current repository" language was removed.

• packages/edge-worker/src/PromptBuilder.ts
• packages/edge-worker/prompts/orchestrator.md
• packages/edge-worker/test/prompt-assembly.routing-context.test.ts
• packages/edge-worker/test/prompt-assembly.system-prompt-behavior.test.ts

What changed:

• routing context now enumerates all applicable repositories in deterministic order
• the (current) marker was removed from the available repository list
• missing-routing-context guidance now avoids implying an ambient current repo

5. Then look at the CLI / F1 multi-repo flow

This is the easiest place to see the end-to-end behavior change.

• apps/f1/server.ts
• packages/edge-worker/test/EdgeWorker.cli-workspace-issue-trackers.test.ts
• apps/f1/test-drives/2026-01-13-multi-repo-orchestration.md
• apps/f1/test-drives/2026-03-08-repository-association-selection-validation.md
• apps/f1/test-drives/2026-03-08-zero-one-many-association-validation.md

What changed:

• CLI multi-repo workspaces now preserve session / issue continuity after explicit repository selection
• repository selection matching now accepts natural-language wrapper phrases around valid repository names
• the F1 validation artifacts now show zero-association state, exact-name selection, and natural-language selection flows

6. Finally, look at the public docs

These are the easiest files to skim if you want the final mental model without reading the implementation first.

• README.md
• packages/edge-worker/README.md

What changed:

• both docs now describe the explicit 0/1/N repository-association model
• the docs explain repository selection / routing in terms of explicit associations, not a primary/current-repository mental model

If you only want to read 5 files

If you're short on time, I'd recommend this exact order:

1. .factory/library/repository-association-audit.md
2. packages/core/src/CyrusAgentSession.ts
3. packages/core/src/PersistenceManager.ts
4. packages/edge-worker/src/RepositoryRouter.ts
5. README.md

Quick reviewer cheat-sheet

• Data model: packages/core/src/CyrusAgentSession.ts
• Persistence + migration: packages/core/src/PersistenceManager.ts
• Routing behavior: packages/edge-worker/src/RepositoryRouter.ts
• Runtime restore / lifecycle: packages/edge-worker/src/EdgeWorker.ts, packages/edge-worker/src/GlobalSessionRegistry.ts
• Prompt wording: packages/edge-worker/src/PromptBuilder.ts
• End-to-end evidence: apps/f1/test-drives/2026-03-08-zero-one-many-association-validation.md

If it helps, I can also leave a second comment that is just a reviewer checklist ("what to verify in each file") without any narrative.