Tracking: Lifecycle Manager + Session Manager lane

[harshitsinghbhandari]

Tracking issue for the Lifecycle Manager (LCM) + Session Manager (SM) lane of the backend rewrite (Go daemon).

Goal

A deterministic supervisor for agent sessions on the OBSERVE → DECIDE → ACT loop:

• LCM — a synchronous reducer. Observers push raw facts; it runs a pure decision, persists, and fires reactions. Never polls.
• SM — the explicit-mutation plumbing: spawn / kill / restore / cleanup. Reports outcomes to the LCM; never derives state itself.

Approach: contract-first, single integration branch

feat/lcm-sm-contracts is the lane integration branch: every sub-PR branches off it and merges into it; the whole lane lands on main as one unit once complete.

PR sequence — implementation COMPLETE ✅

• Repo skeleton — backend/ + frontend/ — chore: scaffold backend/ and frontend/ skeletons for rewrite #1 (merged to main)
• Contracts — domain/ + ports/ + CI workflows — feat(backend): Lifecycle Manager + Session Manager lane #2 (= the integration branch)
• decide core — pure deciders + truth-table tests — feat(decide): pure DECIDE core + exhaustive truth-table tests #4
• LCM — pipeline (split A) — Apply* pipeline, per-session serialisation, store integration — feat(lifecycle): LCM Apply* pipeline (split A) #5
• LCM — reactions (split B) — reaction table + escalation engine + real TickEscalations — feat(lifecycle): ACT layer — reaction table + escalation engine (split B) #6
• Session Manager — spawn / kill / restore / cleanup / list, against fakes — feat(session): Session Manager — spawn/kill/list/get/send/restore/cleanup #7
• Integration — swap fakes for real adapters as the other lanes land (incremental, next phase)
• Land lane → main — review feat/lcm-sm-contracts as the complete lane and merge to main.

All implemented behind fakes; gofmt/build/vet/test -race green across domain, decide, lifecycle, session.

Integration phase — carried-forward items (must address as real adapters land)

• react() out-of-lock dispatch (feat(lifecycle): ACT layer — reaction table + escalation engine (split B) #6) — reactions fire after the per-session lock releases; under concurrent observers a dispatch can run on a stale snapshot / out of order. Documented in reactions.go; needs a per-session react queue or a re-check before dispatch once the live daemon runs concurrent observers.
• ExpectedRevision unused (feat(lifecycle): LCM Apply* pipeline (split A) #5) — in-process per-session mutex covers a single daemon; multi-writer/CDC would need the optimistic-CAS the contract already exposes.
• Store Seed + Get (feat(session): Session Manager — spawn/kill/list/get/send/restore/cleanup #7) — two record-with-identity methods added to LifecycleStore for the SM's create/read-model paths; Tom's real persistence layer must implement them (co-owned; documented in ports/outbound.go).

Open contract questions (from #2) — for integration partners

• SCM facts — does SCMFacts match what the poller can cheaply produce? (adil)
• Persistence — LifecycleStore + LifecyclePatch boundary; lock vs ExpectedRevision. (Tom)
• API — is SessionManager + the Session read-model OpenAPI-friendly? (aditi)

Key invariants (carried from the existing AO)

• Persist canonical state; derive the display status on read (single producer = the SM).
• One authority for death — only the decide pipeline (via detecting) writes terminal states from inferred signals, plus the SM's explicit-kill path via OnKillRequested.
• Failed probe ≠ dead; PR facts dominate soft session states once a PR exists; worktree-remove safety on teardown.

---

Owner: @harshitsinghbhandari (+ coding-agents lane on Runtime/Agent/Workspace)

[neversettle17-101]

API lane response — SessionManager + Session read-model review

Reviewed the contracts walkthrough. Here's the assessment from the API layer.

Context: This is part of the Go backend rewrite tracked in #10. The work is broken into 4 phases — Phase 1 gets the HTTP server + Electron integration running, Phase 2 wires up SSE + frontend subscriptions, Phase 3 implements the core routes (sessions, projects, issues, PRs) against the real SM + LCM adapters, and Phase 4 covers WebSocket /mux. The questions below are blockers specifically for Phase 3.

---

✅ What's OpenAPI-friendly as-is

• SessionManager methods map 1:1 to REST verbs — no translation layer needed:
  • List(ctx, project) → GET /api/v1/sessions?project=
  • Get(ctx, id) → GET /api/v1/sessions/:id
  • Spawn(ctx, cfg) → POST /api/v1/sessions
  • Kill(ctx, id, opts) → POST /api/v1/sessions/:id/kill
  • Send(ctx, id, message) → POST /api/v1/sessions/:id/send
  • Restore(ctx, id) → POST /api/v1/sessions/:id/restore
• SessionStatus being derived on read (never persisted) is correct — the API just serialises whatever the SM returns. No normalisation pass needed.
• CanonicalSessionLifecycle with orthogonal substates (Session, PR, Runtime, Activity) is clean — maps to a nested JSON object naturally.

❓ Needs to come back from this lane before Phase 3

To write OpenAPI schemas (or even basic JSON serialisation), the API needs the concrete shapes for these — they're referenced in the contracts but not enumerated:

Type	Used in	Needed for
Session (read-model)	Get, List return type	response body schema
SpawnConfig	Spawn(ctx, cfg)	POST /sessions request body
KillOptions	Kill(ctx, id, opts)	POST /sessions/:id/kill request body
KillResult	Kill return type	kill response body
CleanupResult	Cleanup return type	needed if cleanup is ever exposed via API

Also: LifecycleStore.List returns []SessionRecord while SessionManager.List returns []Session — are these the same type, or does the SM hydrate/transform before returning? Matters for what fields appear in the list vs detail response.

One design note

SessionStatus is described as "derived, never persisted". For GET /sessions (list), we'll be calling DeriveLegacyStatus() per record. Fine for now at low volume — worth flagging if the list ever gets large and the derivation becomes expensive.

Once the shapes above are available, the OpenAPI strategy question can be closed and Phase 3 route implementations can start.

[harshitsinghbhandari]

LCM/SM lane — all shapes are already defined + JSON-tagged on the integration branch:

• SpawnConfig, KillOptions, KillResult, CleanupResult → backend/internal/ports/inbound.go
• SessionRecord (id / project / issue / kind / lifecycle / metadata / timestamps) and the Session read-model (SessionRecord + derived Status) → backend/internal/domain/session.go

On []SessionRecord vs []Session: not the same type — the SM transforms. LifecycleStore.List returns []SessionRecord (persistence, no status); SessionManager.List hydrates each into domain.Session by calling DeriveLegacyStatus, so the SM is the single producer of Status. List and detail responses are both Session with Status populated — no normalization pass needed, and the derivation happens once per record on the way out.

All types carry json: tags, so code-first OpenAPI generation off these structs should work directly. That should close the shapes blocker for Phase 3.