Droids: Refactor sessions to use explicit repository associations

.factory/init.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+if [ ! -d node_modules ]; then
+  pnpm install
+fi
+
+if [ ! -f packages/core/dist/index.js ] || [ ! -f packages/edge-worker/dist/index.js ] || [ ! -f apps/f1/dist/src/cli.js ]; then
+  pnpm build
+fi

.factory/library/architecture.md

@@ -0,0 +1,12 @@
+# Architecture
+
+Architectural decisions and discovered patterns for this mission.
+
+**What belongs here:** steady-state state-model decisions, ownership boundaries, runtime lookup rules, migration constraints.
+**What does NOT belong here:** exhaustive audit checklists (use the repository-association audit file).
+
+---
+
+- Mission target: repository participation for `CyrusAgentSession` must be explicit and support `0`, `1`, or `N` associated repositories.
+- Steady-state runtime behavior must not derive repository identity from repo-keyed outer storage, singular issue-to-repository caches, or a singular workspace field.
+- Backwards compatibility is limited to loading older persisted config/state and migrating it into the latest normalized model.

.factory/library/environment.md

@@ -0,0 +1,13 @@
+# Environment
+
+Environment variables, external dependencies, and setup notes for this mission.
+
+**What belongs here:** required local tools, env variables, dependency quirks, validation prerequisites.
+**What does NOT belong here:** service ports/commands (use `.factory/services.yaml`).
+
+---
+
+- Required local tools confirmed during planning: `pnpm`, `node`, `bun`, `vitest`, `typescript` via workspace dependencies.
+- Build package outputs before edge-worker tests that import workspace `dist/` artifacts.
+- No new third-party credentials are required for this mission.
+- Existing baseline validation noise in `packages/edge-worker` should be treated as pre-existing unless a feature intentionally changes those areas.

.factory/library/user-testing.md

@@ -0,0 +1,79 @@
+# User Testing
+
+Testing surface, startup steps, and known quirks for this mission.
+
+**What belongs here:** user-facing entry points, validation commands, setup steps, known manual-testing limitations.
+**What does NOT belong here:** low-level service definitions (use `.factory/services.yaml`).
+
+---
+
+## Available Surfaces
+
+- F1 CLI help is runnable via `node apps/f1/dist/src/cli.js --help`.
+- Primary interactive validation surface for this mission: F1 server in multi-repo mode on port `3600`.
+- Audit milestone artifact-validation surface: direct repository file inspection from the checked-out worktree (Markdown artifact plus git-visible path/status checks). This surface is read-only and does not require an app server.
+- Core session-state refactor validation surface: the built `cyrus-core` public API via `node --input-type=module` importing `packages/core/dist/index.js`, using isolated persistence directories under `.factory/validation/core-session-state-refactor/user-testing/namespaces/`.
+
+## Startup Notes
+
+1. Run `.factory/init.sh` if dependencies or build outputs are missing.
+2. Start the `f1-multi-repo` service from `.factory/services.yaml`.
+3. Use the F1 flows to validate:
+   - ambiguous routing with no immediate repository match
+   - repository selection response handling
+   - multi-repository routing-context visibility
+   - zero-association behavior staying explicit until selection
+4. For the `audit-and-target-model` milestone, no service startup is required when validating the committed audit artifact assertions; use repository file inspection and git-visible path checks instead.
+5. For the `core-session-state-refactor` milestone, no app service startup is required; run `.factory/init.sh`, then exercise `PersistenceManager` and the exported session types through the built `cyrus-core` package using namespace-specific persistence paths.
+
+## Known Quirks
+
+- `packages/edge-worker` full-suite Vitest runs currently have unrelated baseline failures in feedback-delivery, screenshot-upload-hooks, and parts of runner-selection.
+- Some edge-worker tests may also hit `/tmp/test-cyrus-home` permission errors during temp log creation.
+- Prefer targeted tests for changed areas during iteration, then use F1/manual validation plus typechecks/build for mission-level confidence.
+- For inline package-API validation scripts, use `node --input-type=module` so ESM imports from `packages/core/dist/index.js` work reliably.
+- `apps/f1/server.ts` generates a fresh temp `CYRUS_HOME` on each start, so post-restart restore coverage is better validated with targeted `packages/edge-worker` restore tests than by restarting the same F1 instance.
+- Avoid `::` in F1 validation issue titles/descriptions; the sanitized branch-name path can still produce invalid branch names. Use hyphenated namespace prefixes instead.
+
+## Flow Validator Guidance: Repository audit artifact
+
+- Surface: read-only repository inspection of `.factory/library/repository-association-audit.md` and related git-visible paths.
+- Do not start app services or mutate product code for this surface.
+- Allowed evidence sources: `Read`, `Grep`, `LS`, and read-only git/jq commands.
+- Off-limits: editing the audit artifact, using generated outputs as primary evidence, or inferring checklist coverage from partial excerpts when the file can be read directly.
+- Isolation rule: each validator must use only its assigned report path and keep any temporary notes scoped to its own namespace; there is no shared account or seeded data for this surface.
+
+## Flow Validator Guidance: cyrus-core persistence api
+
+- Surface: public `cyrus-core` API exercised through `node --input-type=module` scripts that import `packages/core/dist/index.js`.
+- No app server or browser is required for this surface; use isolated persistence/state directories created under `.factory/validation/core-session-state-refactor/user-testing/namespaces/<namespace>/`.
+- Allowed evidence sources: `Execute` for Node scripts and targeted package tests, plus `Read`/`Grep` for exported type inspection when needed to confirm public API shape.
+- Off-limits: editing product code, using repo-keyed legacy containers as the primary success criterion, or sharing persistence directories between validator runs.
+- Isolation rule: each validator must stay inside its assigned namespace directory and only write its assigned flow report file.
+
+## Flow Validator Guidance: f1 multi-repo cli
+
+- Surface: the running `f1-multi-repo` service on port `3600`, exercised through `node apps/f1/dist/src/cli.js`.
+- Parent validator owns service startup/teardown; flow validators should assume the service is already healthy before they begin.
+- Required runtime evidence for this milestone comes from real CLI flows: `status`, `create-issue`, `assign-issue`, `start-session`, `view-session`, and `prompt-session`.
+- The key behaviors to confirm are: zero-association sessions stay unresolved until selection, exact-name and natural-language repository selections resolve cleanly, selected sessions continue into runner initialization without losing issue/session state, and orchestrator routing context enumerates both repositories.
+- Also inspect the shared F1 server log provided by the parent validator for absence of avoidable optional-local-prompt noise and for repository-selection / routing-context continuation evidence.
+- Off-limits: editing product code, reconfiguring the service port, or reusing another validator's issue/session identifiers.
+- Isolation rule: each validator must use only issue titles/descriptions prefixed with its assigned namespace, keep to its assigned session IDs, and write only its assigned flow report.
+
+## Flow Validator Guidance: repository-association docs surface
+
+- Surface: committed repository files that users and validators read directly, especially `README.md`, `packages/edge-worker/README.md`, and `apps/f1/test-drives/2026-01-13-multi-repo-orchestration.md` / `apps/f1/test-drives/2026-03-08-zero-one-many-association-validation.md`.
+- No app server is required for this surface; use repository inspection only.
+- Allowed evidence sources: `Read`, `Grep`, `Glob`, `LS`, and read-only git commands.
+- The key behaviors to confirm are that public/internal examples describe explicit repository associations and selection behavior, avoid teaching a session-wide primary/current repository model, and that the F1 validation assets describe ambiguous-routing plus multi-repository routing-context flows.
+- Off-limits: editing documentation, inferring coverage from one file when the assertion names require checking multiple surfaces, or using generated artifacts as a substitute for the committed sources.
+- Isolation rule: each validator must keep notes within its own report and avoid creating any shared scratch files.
+
+## Flow Validator Guidance: edge-worker restore test surface
+
+- Surface: targeted `packages/edge-worker` runtime restore tests that exercise persisted session/repository-association restoration without relying on a long-lived F1 temp home.
+- Preferred command: `pnpm --filter cyrus-edge-worker exec vitest run test/EdgeWorker.missing-session-recovery.test.ts test/GlobalSessionRegistry.test.ts test/AgentSessionManager.repository-associations.test.ts`.
+- Use direct file inspection of those tests when you need to tie a passing command back to explicit repository-association restore behavior.
+- Off-limits: running the full edge-worker suite as primary evidence, editing product code, or inferring restore behavior from unrelated runner-selection/feedback failures.
+- Isolation rule: each validator writes only its assigned report file and treats unrelated baseline failures outside the targeted restore command as noise, not assertion evidence.

.factory/services.yaml

@@ -0,0 +1,14 @@
+commands:
+  install: pnpm install
+  build: pnpm build
+  typecheck: pnpm typecheck
+  lint: pnpm lint
+  test: pnpm test:packages:run -- --maxWorkers=8
+
+services:
+  f1-multi-repo:
+    start: CYRUS_PORT=3600 CYRUS_REPO_PATH="/Users/connor/code/cyrus/worktrees/multirepo" CYRUS_REPO_PATH_2="/Users/connor/code/cyrus/worktrees/multirepo" bun "/Users/connor/code/cyrus/worktrees/multirepo/apps/f1/server.ts"
+    stop: lsof -ti :3600 | xargs kill
+    healthcheck: curl -sf http://localhost:3600/status
+    port: 3600
+    depends_on: []

.factory/skills/analysis-worker/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: analysis-worker
+description: Creates exhaustive audit and design artifacts for repository-association refactors.
+---
+
+# Analysis Worker
+
+NOTE: Startup and cleanup are handled by `worker-base`. This skill defines the work procedure.
+
+## When to Use This Skill
+
+Use this skill for artifact-first features: repository-wide audits, checklist-backed maps, architecture/design writeups, migration-boundary documentation, and other non-trivial analysis deliverables that must guide later implementation workers.
+
+## Work Procedure
+
+1. Read `mission.md`, `validation-contract.md`, mission `AGENTS.md`, and the relevant `.factory/library` files before changing anything.
+2. If the feature is an audit, enumerate the full file scope first. Use targeted searches plus directory listings so every in-scope file is accounted for. Record explicit checklist sections in the artifact.
+3. Distinguish clearly between:
+   - direct assumption sites
+   - indirect coupling sites
+   - unaffected files
+   - follow-up notes or validation-only mentions
+4. If the feature defines a target model, state the steady-state source of truth explicitly and name which legacy shapes are migration-only inputs.
+5. Keep the artifact precise and operational. The next worker should be able to implement from it without guessing.
+6. Verify the artifact with targeted `rg` searches and at least one relevant typecheck command if typed/shared artifacts were touched.
+7. In the handoff, list the files reviewed, the artifact path updated, and any uncovered assumption sites or blockers for the orchestrator.
+
+## Example Handoff
+
+```json
+{
+  "salientSummary": "Expanded the repository-association audit into a repo-wide checklist-backed map and documented the normalized source of truth plus migration-only legacy inputs.",
+  "whatWasImplemented": "Updated .factory/library/repository-association-audit.md with high-level assumption categories, detailed file findings across apps/packages/tests/docs, per-directory completion checklists, and a target-model section naming explicit repository-association records as the steady-state source of truth.",
+  "whatWasLeftUndone": "Did not change runtime code; implementation work remains for core persistence, edge-worker routing/session lifecycle, and user-facing materials.",
+  "verification": {
+    "commandsRun": [
+      {
+        "command": "rg -n \"checklist|source of truth|migration-only\" .factory/library/repository-association-audit.md",
+        "exitCode": 0,
+        "observation": "Confirmed the audit file contains checklist sections and target-model language."
+      },
+      {
+        "command": "pnpm --filter cyrus-core typecheck",
+        "exitCode": 0,
+        "observation": "Core package still typechecks after the artifact update."
+      }
+    ],
+    "interactiveChecks": []
+  },
+  "tests": {
+    "added": []
+  },
+  "discoveredIssues": [
+    {
+      "severity": "medium",
+      "description": "EdgeWorker runtime still persists agent sessions under repo-keyed containers and retains singular issue-to-repository cache behavior.",
+      "suggestedFix": "Address in the runtime adoption features before milestone validation."
+    }
+  ]
+}
+```
+
+## When to Return to Orchestrator
+
+- The requested artifact requires a mission-scope decision about the steady-state source of truth that is not yet settled.
+- The repository contains a contradictory pattern that changes milestone decomposition.
+- The audit reveals a blocking pre-existing issue that would invalidate later implementation or validation work.

.factory/skills/session-model-worker/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: session-model-worker
+description: Refactors session, routing, persistence, prompt, and validation surfaces around explicit 0/1/N repository associations.
+---
+
+# Session Model Worker
+
+NOTE: Startup and cleanup are handled by `worker-base`. This skill defines the work procedure.
+
+## When to Use This Skill
+
+Use this skill for implementation features that change core session/state types, persistence, edge-worker routing/session lifecycle, prompt assembly, F1 validation assets, and the required README surfaces for the repository-association refactor.
+
+## Work Procedure
+
+1. Read `mission.md`, `validation-contract.md`, mission `AGENTS.md`, and the relevant `.factory/library` files before making changes.
+2. Read the audit artifact before changing model or runtime code so you know every known assumption site in scope.
+3. Write failing targeted tests first for the behavior you are about to change. Prefer package-local tests that directly prove the relevant validation assertions.
+4. Implement the smallest coherent slice needed to make those tests pass using the normalized explicit repository-association model. Do not add scattered backwards-compatibility branches.
+5. When touching runtime/session code, verify that repository identity is not inferred from repo-keyed containers, singular caches, or singular workspace fields.
+6. If edge-worker tests depend on built workspace `dist/` outputs, run `pnpm build` before the affected test commands.
+7. Run targeted tests for the changed files, then package typechecks for `cyrus-core`, `cyrus-edge-worker`, `apps/cli`, and `apps/f1` as relevant.
+8. For user-surface or end-to-end features, run the F1 validation flow described in `.factory/library/user-testing.md` and capture at least one concrete interactive check in the handoff.
+9. Update only the mission-required docs/examples (`README.md`, `packages/edge-worker/README.md`, relevant F1 materials) when the feature scope requires it.
+10. In the handoff, map changed tests and validations back to the validation assertion IDs completed by the feature.
+
+## Example Handoff
+
+```json
+{
+  "salientSummary": "Refactored core session persistence to store explicit repository associations, migrated legacy repo-keyed state into the normalized format, and updated targeted tests plus typechecks.",
+  "whatWasImplemented": "Updated CyrusAgentSession and PersistenceManager so zero, one, and many repository associations are represented explicitly and migrated from legacy repo-keyed persisted state. Added/updated targeted tests covering zero-association round trip, single-association restore, multi-association preservation, and one-shot migration behavior.",
+  "whatWasLeftUndone": "EdgeWorker runtime still needs follow-up changes to consume the normalized association model end to end.",
+  "verification": {
+    "commandsRun": [
+      {
+        "command": "pnpm --filter cyrus-core test:run -- PersistenceManager",
+        "exitCode": 0,
+        "observation": "Migration and repository-association persistence tests passed."
+      },
+      {
+        "command": "pnpm --filter cyrus-core typecheck",
+        "exitCode": 0,
+        "observation": "Core type surfaces compile after the refactor."
+      },
+      {
+        "command": "pnpm --filter cyrus-edge-worker typecheck",
+        "exitCode": 0,
+        "observation": "Downstream runtime package still typechecks against the updated core types."
+      }
+    ],
+    "interactiveChecks": [
+      {
+        "action": "Reviewed the serialized state fixture produced by the targeted tests and confirmed zero, one, and many repository-association records remain explicit after restore.",
+        "observed": "No repo-keyed wrapper or primary-repository field was needed to recover association state."
+      }
+    ]
+  },
+  "tests": {
+    "added": [
+      {
+        "file": "packages/core/test/PersistenceManager.migration.test.ts",
+        "cases": [
+          {
+            "name": "serializes and restores a zero-repository session explicitly",
+            "verifies": "VAL-CORE-001"
+          },
+          {
+            "name": "migrates legacy repo-keyed persisted state into normalized repository associations",
+            "verifies": "VAL-CORE-004"
+          }
+        ]
+      }
+    ]
+  },
+  "discoveredIssues": [
+    {
+      "severity": "medium",
+      "description": "RepositoryRouter still falls back to the first workspace repository when user selection is invalid.",
+      "suggestedFix": "Address in the routing-and-selection runtime feature before runtime milestone validation."
+    }
+  ]
+}
+```
+
+## When to Return to Orchestrator
+
+- The feature requires a change to mission scope, validation assertions, or milestone order.
+- A pre-existing baseline failure blocks verification of the behavior you changed and cannot be isolated.
+- You find another repository-association assumption outside the feature scope that must be tracked before continuing.
+- The refactor would require a broader architectural reset than the current feature can safely handle in one worker session.

.factory/validation/audit-and-target-model/scrutiny/synthesis.json

@@ -0,0 +1,28 @@
+{
+	"status": "overridden",
+	"summary": "Scrutiny for audit-and-target-model was overridden after the test gate failed only on documented pre-existing edge-worker assertion suites unrelated to the audit artifact or temp-home isolation fixes. Typecheck and lint passed, and the temp-log permission blockers were removed.",
+	"validatorResults": {
+		"test": {
+			"status": "failed",
+			"details": "pnpm test:packages:run -- --maxWorkers=8 still fails only on pre-existing packages/edge-worker assertion suites (feedback-delivery, feedback-timeout, screenshot-upload-hooks, runner-selection)."
+		},
+		"typecheck": {
+			"status": "passed"
+		},
+		"lint": {
+			"status": "passed"
+		}
+	},
+	"appliedUpdates": [],
+	"suggestedGuidanceUpdates": [],
+	"override": {
+		"appliedBy": "orchestrator",
+		"reason": "Mission AGENTS.md already documents these edge-worker failures as unrelated pre-existing validation noise. The audit milestone only changed mission artifacts and test temp-home isolation, and those changes validated cleanly in targeted tests.",
+		"deferredIssues": [
+			"packages/edge-worker/test/EdgeWorker.feedback-delivery.test.ts",
+			"packages/edge-worker/test/EdgeWorker.feedback-timeout.test.ts",
+			"packages/edge-worker/test/EdgeWorker.screenshot-upload-hooks.test.ts",
+			"packages/edge-worker/test/EdgeWorker.runner-selection.test.ts"
+		]
+	}
+}