​

Session-First Architecture

​

Problem Statement

1. Agent-centric (controller path): config.Agent → buildOneAgent() → agent.Agent → runtime.Provider.Start(). The controller rebuilds the full agent list from config on every tick. Sessions are an implementation detail — tmux session names derived from agent names.
2. Session-centric (gc session path): session.Manager.Create() → bead (type=“session”) → runtime.Provider.Start(). Sessions are persistent, resumable, bead-backed. But the controller doesn’t know about them.

• Pool members have no persistence. When a pool member is stopped, its history disappears. There’s no way to query old pool sessions.
• The agent.Agent interface is redundant. It’s a thin wrapper around runtime.Provider + session name. session.Manager already provides the same operations plus persistence.
• Config-driven identity is fragile. Pool instances get slot-based names (worker-3) that change when scaling happens. Sessions need stable identity.
• Two code paths to maintain. buildOneAgent (200+ lines) and session.Manager.Create do overlapping work with different models.

​

Design Principles

1. Session is the primitive. A session is a persistent, bead-backed conversation between a human/system and an agent. It has stable identity (bead ID), lifecycle state, and history.
2. Templates replace agent types. config.Agent becomes a session template. The single/multi/pool distinction becomes a policy on how many concurrent sessions a template allows and how they’re scaled.
3. The controller manages sessions, not agents. Instead of rebuilding agent.Agent objects from config each tick, the controller reconciles session beads against desired state.
4. Pool growth = new session. Pool shrink = drain + archive session. Old pool sessions remain queryable but don’t receive new work.
5. Single-writer per lifecycle. At every migration phase, exactly one system owns runtime lifecycle mutations. No dual-writer ambiguity.
6. Fail closed. On partial failure (bead store errors, stale reads), the controller aborts the tick rather than acting on incomplete data.

​

Core Invariants

​

Architecture

​

Session Bead Schema

type:       "session"
status:     "open" | "closed"
labels:     ["gc:session", "template:{name}"]  # pool sessions also get "member:{name}"
title:      "{user-provided or auto-generated}"

metadata:
  template:       "polecat"              # source template name
  state:          "creating" | "active" | "suspended" | "draining" | "archived" | "quarantined"
  state_reason:   "scale_down"           # why this state was entered (see below)
  provider:       "claude"               # resolved provider name
  command:        "claude --dangerously..." # resolved start command
  work_dir:       "/path/to/workdir"
  session_name:   "polecat-a3f2"         # tmux session name ({template}-{short-hash})
  session_key:    "{uuid}"               # provider resume handle (scrubbed on close)
  resume_flag:    "--resume"
  resume_style:   "flag"
  config_hash:    "{fingerprint}"        # canonical hash for drift detection
  pool_template:  "worker"               # set only for pool sessions
  generation:     "3"                    # incremented on each reactivation
  instance_token: "{random}"             # set on create/reactivate, checked on drain
  created_at:     "2026-03-08T..."
  suspended_at:   "2026-03-08T..."
  archived_at:    "2026-03-08T..."
  drain_started:  "2026-03-08T..."
  crash_count:    "0"                    # crashes in current window
  last_crash_at:  ""                     # timestamp of most recent crash
  quarantine_until: ""                   # earliest time to attempt restart
  quarantine_cycle: "0"                  # number of quarantine→active attempts
  creating_at:    ""                     # when state=creating was set

  # Overlay fields (only if overridden at creation)
  overlay.model:  "sonnet"
  overlay.name:   "quick-fix"

​

State Reason Values

​

Two-Axis State Model

• bead.status ∈ : Record-level lifecycle. closed is terminal and immutable. Maps to the bead store’s native status field.
• metadata.state ∈ : Operational lifecycle within an open bead.

• closed beads MUST have bead.status = "closed". The state field is not meaningful for closed beads (set to empty string on close).
• All other states require bead.status = "open".
• CLI output maps both axes: a bead with status=closed shows state closed regardless of the metadata state field.

​

Pool Occupancy Accounting

​

Session Name Convention

​

Generation and Instance Token

• generation: Incremented each time a session transitions from archived → active (reactivation). Starts at 1 on creation. Used for auditing how many incarnations a pool slot has had.
• instance_token: Random value set on create and reactivate. The drain protocol checks this token — if the token on the bead doesn’t match the controller’s expected value, the drain targets a stale incarnation and is aborted. Prevents races where a drain for incarnation N arrives after incarnation N+1 has started.

​

Session States

                create
                  │
                  ▼
              ┌──────────┐
              │ creating  │──── stale? ──▶ closed
              └─────┬─────┘
                    │ runtime alive
                    ▼
              ┌─────────┐
         ┌───▶│  active  │◀──── resume / reactivate
         │    └────┬─────┘
         │         │
         │    suspend │ drain    crash-loop
         │         │    │           │
         │         ▼    ▼           ▼
         │    ┌────────┐ ┌────────┐ ┌─────────────┐
    resume│   │suspended│ │draining│ │ quarantined │
         │    └────┬───┘ └───┬────┘ └──────┬──────┘
         │         │    crash│  │           │
         │    archive*  ─────┘ archive  cooldown (if room)
         │         │           │           │
         │         ▼           ▼           ▼
         │    ┌──────────────────┐    back to active
         │    │    archived      │    (or archived if at max)
         │    └────────┬─────────┘
         │             │
         └─────────────┘ (reactivate, pool only)

         Any state ──close──▶ closed (bead.status="closed", terminal)

  * suspended → archived only for pool sessions during scale-down

​

Orphan Work Cleanup

​

Atomic State Mutations

1. Create bead with state=creating, NO pool: label
2. Start runtime
3. Confirm liveness (IsRunning())
4. Set state=active, state_reason=creation_complete (batch)
5. Add pool: label (enables routing — only after runtime confirmed)

1. Remove pool: label (stops routing)
2. Set state=suspended, suspended_at, state_reason (batch)
3. Kill runtime

1. Remove pool: label (stops routing — safe even if crash follows)
2. Set state=archived, archived_at, state_reason (batch)
3. Kill runtime

1. Start runtime (session must be alive before routing)
2. Confirm runtime liveness (IsRunning())
3. Set state=active, state_reason=reactivated, generation++ (batch)
4. Add pool: label (enables routing — only after runtime confirmed)

1. Start runtime
2. Confirm runtime liveness (IsRunning())
3. Set state=active, state_reason=resumed (batch)
4. Add pool: label (enables routing — only after runtime confirmed)

​

ExecStore Partial-Failure Repair Table

​

Template Model

[[agent]]
name = "polecat"
provider = "claude"
prompt_template = "polecat.md"

# Pool policy (optional)
[agent.pool]
min = 0
max = 5                    # max active sessions
check = "bd ready --label=pool:polecat | jq length"
routing_label = "pool:polecat"  # label managed by controller for routing
drain_timeout = "30s"      # max time to wait for in-flight work
archive_order = "lifo"     # "lifo" | "fifo" | "idle-first"
reactivate_order = "lifo"  # "lifo" | "fifo" (which archived session to wake)
max_archived = 10           # retention cap per template
quarantine_max_attempts = 3 # quarantine cycles before eviction
quarantine_backoff_cap = "5m" # max backoff between quarantine attempts
quarantine_healthy_duration = "5m" # healthy time to reset quarantine cycle
creation_timeout = "60s"    # max time in creating state before cleanup
max_unavailable = 1         # max sessions drained simultaneously for drift
archived_secret_ttl = "24h" # scrub secrets from wake_mode=fresh archives

# Session defaults (overridable per-session)
[agent.defaults]
model = "opus"             # default model
wake_mode = "fresh"        # "fresh" or "resume"
allow_overlay = ["model", "name", "title"]  # prompt requires explicit opt-in
allow_env_override = []    # no env overrides by default

​

Controller Reconciliation

​

Current Flow (agent-centric)

tick:
  1. buildAgentsFromConfig() → []agent.Agent       # rebuild every tick
  2. syncSessionBeads(agents)                       # sync beads to match
  3. reconcileSessionBeads(agents, beads)           # wake/sleep decisions

​

Target Flow (session-first)

tick:
  1. evaluateTemplates(config) → desired state      # which templates, how many
  2. sessionIndex.snapshot() → current state            # in-memory, always consistent
     - Index populated at startup, maintained synchronously on mutations
     - All mutations go through controller (INV-5), no stale reads
  3. reconcile(desired, current):
     a. For each pool template:
        - Count creating + active + suspended + quarantined (= occupancy)
        - Compare to desired count from scale_check
          - Too few: create new (with state=creating marker) or reactivate
          - Too many: select sessions to retire:
            1. Suspended sessions first (no drain needed → archive directly)
            2. Active sessions per archive_order (drain → archive)
        - Check draining sessions: drain_timeout expired? → archive
        - Check creating beads: stale (>60s)? → close or complete
     b. For each session bead:
        - Config drift? → drain + recreate (rolling: max_unavailable per tick)
        - Dependency check → gate wake
        - Idle timeout? → suspend
        - Crash loop? → quarantine
        - Quarantine cooldown expired? → reactivate
     c. For non-pool templates: no count enforcement

​

Reconciliation Idempotency

1. Single-controller exclusivity. controller.lock (flock) ensures only one controller process runs. The reconciliation loop is single- threaded within that process. No concurrent tick execution.
2. Creation-intent markers. When creating a new session, the controller first creates a bead with state=creating and a deterministic key (template:{name}:tick:{tick_id}:slot:{n}). Before creating, it checks for existing creating beads from prior ticks and reconciles them (either complete the creation or terminate the partial bead).
3. Fail-closed startup. If the startup index population (populateIndex()) fails, the controller does not start reconciliation. During normal operation, the in-memory index is the authoritative source (maintained synchronously). If a bead store write fails during a mutation, the index is NOT updated — the mutation is retried next tick.

​

Config Hash Canonicalization

1. Field inclusion list (behavioral fields only): provider, command (resolved), prompt_template (content hash), env (sorted key=value pairs, including overlay env), work_dir, hooks (sorted), model, wake_mode, session_setup, session_setup_script, pre_start.
2. Excluded from hash (non-behavioral): TOML whitespace, comments, key ordering, name, title, description, pool scaling config (min, max, check), drain_timeout, archive_order, max_archived.
3. Canonicalization: Fields sorted lexicographically, values normalized (paths resolved, env sorted), concatenated as key=value\n, SHA-256 hashed, truncated to 16 hex characters.
4. Drift response: On drift detection, sessions are drained in a rolling update — at most max_unavailable (default 1) sessions per template are drained simultaneously per tick. This prevents a template config change from dropping pool capacity to zero. After each drained session is archived, a replacement is created with the updated config. A bounded retry prevents churn: if drift-triggered recreates exceed 3 per 10 minutes (tracked on the bead via drift_recreate_count and drift_recreate_window), the controller logs a warning and skips further drift recreates for that template until the window expires.
5. Unit test requirement: A test MUST prove that semantically identical configs with different TOML formatting produce identical hashes. A separate test MUST prove that template + overlay produces the same hash as the equivalent flat config.

​

Pool Session Lifecycle

1. scale_check says 3 workers needed, 0 active
2. Controller creates 3 session beads from "worker" template
   - Each gets fresh context (wake_mode=fresh)
   - Names: auto-generated (e.g., "worker-a3f2", "worker-b7c1", "worker-d9e4")
   - Labels: ["gc:session", "template:worker", "member:worker"]
   - state=creating (NO pool: label yet), creating_at set
3. Runtime started for each session
4. Controller confirms liveness (IsRunning())
5. Batch-write: state=active + add pool:worker label
6. Sessions now pick up work via pool label
4. scale_check drops to 1
5. Controller selects 2 sessions to drain (per archive_order, default LIFO)
   - State → "draining", state_reason → "scale_down"
   - pool: label removed (stops new work routing)
   - Runtime continues, waiting for in-flight work to complete
   - drain_started timestamp set
6. In-flight work completes (or drain_timeout expires)
   - State → "archived", archived_at set
   - Runtime killed (if still running after timeout)
   - Bead stays open
7. scale_check goes back to 3
8. Controller needs 2 more active sessions
   - If wake_mode=fresh: create 2 new sessions, archived ones stay archived
   - If wake_mode=resume: reactivate 2 archived sessions (per reactivate_order)
     - Drift gate: config_hash must match current template. If drifted, create fresh.
     - generation incremented, new instance_token set
     - Runtime started, liveness confirmed, then pool: label restored

​

Drain Protocol

1. Remove pool: label — prevents new work from being routed.
2. Set state=draining, drain_started, state_reason.
3. Wait for in-flight work. The controller checks each tick whether the session has any open beads claimed by this session (assigned work, not just ready-queue presence). The check uses the session’s session_name or bead ID to identify claimed work, not the pool label.
4. On drain complete (no claimed work): set state=archived, send SIGTERM to runtime, wait 5s, then SIGKILL if still running.
5. On drain timeout (drain_timeout from pool config, default 30s): set state=archived with state_reason=drain_timeout, send SIGTERM then SIGKILL. Any orphaned beads are marked blocked with reason=session_archived.
6. On crash during drain (runtime exits unexpectedly while draining): set state=archived with state_reason=crash_during_drain. Any orphaned beads are marked blocked with reason=session_crash_drain (same cleanup as drain timeout).

​

Work Routing for Pools

• Creating sessions: No pool: label → no routing.
• Active sessions: Have the pool: label → receive work.
• Suspended sessions: pool: label removed on suspend → no routing. The member:{template} label preserves pool membership for queries. On resume, pool: label is restored after runtime liveness confirmed.
• Draining sessions: pool: label already removed → no new work.
• Archived sessions: pool: label removed → no new work. The template: and member: labels preserve associations for queries.

​

Session Creation with Overlay

type CreateFromTemplate struct {
    Template  string            // required: template name
    Title     string            // optional: session title
    Overrides map[string]string // optional: overlay fields (allowlisted)
}

​

Overlay Allowlist

​

Environment Variable Override Security

[agent.defaults]
allow_env_override = ["TARGET_URL", "LOG_LEVEL", "MODEL_TEMPERATURE"]

• Only keys listed in allow_env_override are accepted via env.{KEY}.
• If allow_env_override is omitted, no env overrides are permitted.
• Env key names must match ^[A-Z][A-Z0-9_]{0,127}$.
• This eliminates the fragile denylist approach entirely — templates opt-in to exactly which variables callers may override.

​

Banned Overlay Keys (rejected at Create time)

• Command/provider: command, provider, resume_flag, resume_style
• Internal state: session_key, state, generation, instance_token
• Any key not in the allowlist above

​

Session Key Lifecycle

1. Set on create: Generated by the provider on first start.
2. Preserved on suspend/archive: Enables resume with warm context.
3. Rotated on reactivate (if wake_mode=fresh): New key, fresh context.
4. Scrubbed on close: Set to empty string when bead status → closed.
5. Redacted in CLI output: gc session list and gc session inspect show [redacted] instead of the raw key value.
6. No TTL (by design): The key’s lifetime matches the session’s lifetime. Archived sessions may hold keys for extended periods — the retention policy (see below) bounds this.

​

Archived Bead Retention

1. Per-template cap: max_archived in pool config (default 10). When creating a new archived session would exceed the cap, the oldest archived session is closed (bead status → closed, sensitive metadata scrubbed).
2. Excluded from hot path: The reconciliation loop’s in-memory session index only tracks active, suspended, draining, and quarantined sessions. Archived sessions are not queried per-tick — only on reactivation (filtered query by template + state=archived).
3. Sensitive metadata scrubbed on close: When an archived bead is pruned to closed, session_key and overlay.env.* fields are cleared.
4. Time-based secret scrubbing: Archived sessions with wake_mode=fresh have their session_key and overlay.env.* scrubbed after archived_secret_ttl (default 24h) even while the bead remains open. These sessions will never be resumed with their old key, so early scrubbing is safe. Archived sessions with wake_mode=resume retain secrets until closed (they need the key for reactivation). The reconciler checks archived_at + archived_secret_ttl on each tick for wake_mode=fresh archived beads and scrubs expired secrets in-place.

​

Removing agent.Agent

​

Migration Path

​

Phase 0: Bead Schema Migration (no risk)

• TestLegacyBeadRecognition — controller reads agent_session beads
• TestLegacyStateMapping — legacy states map to new model correctly
• TestHybridPoolOccupancy — mixed legacy + new beads count correctly

​

Phase 1: Template Resolution (low risk)

​

Phase 2: Controller Uses session.Manager (medium risk)

​

Phase 3: Pool Archival (medium risk)

1. While the new controller is still running, execute cleanup via socket: gc session drain-all --template=X (drains active sessions) gc session close --state=archived,quarantined,creating (closes beads)
2. Stop the new controller
3. Start the old binary (Phase 2)
4. Old binary skips unknown state values with warning (forward-compat) If the new controller has already crashed (can’t use socket), use gc session admin-close --offline which: (a) acquires controller.lock (non-blocking — fails if another controller is running), (b) kills runtimes by session_name via runtime.Provider.Stop(), (c) marks orphaned beads as blocked, and (d) writes state changes directly to bead store (bypassing socket). Requires --yes flag for non-interactive confirmation. This is the ONLY sanctioned offline mutation path and does NOT require a running controller — it operates directly on the bead store and runtime provider. Forward compatibility: Unknown state values are skipped with a session.unknown_state warning event, not errors. This allows safe rollback from Phase 3 to Phase 2 without crashing on draining/archived beads that the older binary doesn’t understand.

​

Phase 4: Remove agent.Agent (low risk, large diff)

​

Phase 5: Multi-Instance Consolidation

​

Depends-On Across Templates

​

CLI Changes

​

gc session list Default Output

NAME              TEMPLATE   SLOT  STATE       AGE    REASON
polecat-a3f2b7    polecat    -     active      2h     created
worker-b7c1d9     worker     1     active      45m    reactivated
worker-d9e4f5     worker     2     draining    2m     scale_down
worker-e5f6a7     worker     -     archived    1h     drain_complete

• --all — show all states including archived and closed
• --state=archived — filter to specific state
• --template=worker — filter by template name

​

Ambiguity Resolution

Error: "polecat" matches 3 active sessions. Specify a session name:
  polecat-a3f2  (active, 2h)
  polecat-b7c1  (active, 45m)
  polecat-d9e4  (suspended, 1h)

​

Test Strategy

​

Phase 1 Tests

​

Phase 2 Tests

​

Phase 3 Tests

​

Phase 4 Tests

​

Phase 5 Tests

​

Conformance Suite Additions

• TestConformance_CreatingState — creating → active with liveness check
• TestConformance_CreatingStale — creating cleanup after timeout
• TestConformance_DrainState — draining → archived transition
• TestConformance_DrainCrash — crash during drain → immediate archive
• TestConformance_QuarantineState — crash loop → quarantine → recovery
• TestConformance_QuarantineAtMax — quarantine reactivation blocked at max
• TestConformance_ArchivedReactivation — archived → active with generation bump
• TestConformance_OverlayValidation — per-template env allowlist enforcement
• TestConformance_AtomicStateTransitions — batch writes for multi-field transitions
• TestConformance_SuspendedPoolRouting — suspended pool session not routable
• TestConformance_TwoAxisState — bead.status × metadata.state consistency
• TestConformance_UnknownStateForwardCompat — unknown states skipped safely

​

Impact Analysis

​

Files to Change

​

Backward Compatibility

• city.toml format: No breaking changes. [[agent]] syntax is unchanged. Pool config is unchanged. The [agent.defaults] section and new pool fields (drain_timeout, archive_order, etc.) are additive.
• CLI commands: gc session new/suspend/peek/attach are the primary interface. gc agent is config-only (add/suspend/resume).
• Bead schema: New metadata fields are additive. Existing session beads are compatible (missing fields use defaults).
• Environment variables: GC_SESSION_NAME and GC_TEMPLATE (already emitted) become canonical. Legacy GC_AGENT continues during migration.

​

Risks

1. Drain protocol complexity. The draining state adds a transitional lifecycle path. Implementation must handle edge cases: drain of a session that crashes during drain, drain timeout racing with work completion, double-drain of the same session.
2. Migration duration. Five phases over multiple PRs. The intermediate states increase code complexity temporarily, but the single-writer contract and anti-corruption boundary (Phase 2) limit the blast radius.
3. Performance. The reconciliation hot path uses an in-memory session index (same pattern as the convergence active index). The index maps bead ID → for all non-closed, non-archived sessions. It is populated at startup via a one-time full scan, then maintained synchronously on every mutation by the single-writer controller. Since all lifecycle mutations (including CLI commands) go through the controller socket (INV-5), the index is always consistent — no periodic full reconcile needed. The index eliminates per-tick store queries. Archived sessions are queried on-demand only during reactivation.
4. Naming transition. Pool instances today have deterministic names (worker-3). Session-based naming uses {template}-{short-hash}. The pool_slot metadata field provides backward-compatible sequential references for operators who need them.

​

Resolved Questions

1. Archived session pruning: Yes, auto-pruned via max_archived per template (default 10). Oldest archived sessions are closed when the cap is exceeded. Sensitive metadata is scrubbed on close.
2. Reactivation semantics: When wake_mode=resume, the controller reactivates an archived session (same bead, same key, warm context). When wake_mode=fresh, the controller creates a new session bead with fresh context — archived sessions are NOT reactivated. The archived beads stay archived until pruned by max_archived.
3. Template overlay scope: Overlays are limited to a strict allowlist (model, name, title, prompt, env.* with denylist). Unknown keys are rejected at creation time.
4. depends_on across templates: Template-to-template: “at least one active session of the dependency template must be alive.” Generalized from the existing pool dependency check.
5. Routing label as ZFC compromise: The controller manages the pool: routing label (adding/removing it during state transitions). The label string is parameterized via routing_label in pool config, so Go code manipulates a configured value, not a hardcoded prefix. This is a v1 pragmatic compromise — future versions could externalize routing entirely to agent-driven label management via hooks.

​

Open Questions

1. Should draining sessions be visible to gc session peek? They’re still running but about to be archived. Current recommendation: yes, peek works on any running session regardless of state.
2. Multi-template overlays. Could a session combine fields from multiple templates? Current answer: no. One template per session. If needed, create a new template that inherits from others.

​

Appendix: Current vs Target Comparison

​

Creating a Pool Member

1. evaluatePool() → desired count
2. poolAgents() → deep copy config per instance
3. buildOneAgent() → resolve provider, build command, create agent.Agent
4. syncSessionBeads() → create bead to match agent
5. reconcileSessionBeads() → decide to wake
6. agent.Agent.Start() → runtime session
7. Agent picks up work via bd ready --label=pool:{template}

1. evaluatePool() → desired count
2. resolveTemplate() → session.CreateParams from config
3. session.Manager.Create() → bead (state=creating, no pool: label)
4. Runtime starts, liveness confirmed → state=active, pool: label added
5. Session picks up work via pool label on bead

​

Stopping a Pool Member

1. Controller sees excess instances
2. agent.Agent.Stop() → tmux session killed
3. syncSessionBeads() → bead closed
4. History lost

1. Controller sees excess active sessions
2. session.Manager.Drain() → state=draining, pool label removed
3. Wait for in-flight work (or timeout)
4. session.Manager.Archive() → state=archived, runtime killed
5. Queryable via gc session list --state=archived --template=worker
6. Reactivatable if pool grows again