FEAT-013: Managed Session Lifecycle

.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/014-app-dashboard-extensions"
+  "feature_directory": "specs/013-managed-session-lifecycle"
 }

CLAUDE.md

@@ -1,7 +1,7 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan:
-`specs/014-app-dashboard-extensions/plan.md`.
+`specs/013-managed-session-lifecycle/plan.md`.
 <!-- SPECKIT END -->
 
 # AgentTower Agent Context

docs/app-contract-client-guide.md

@@ -123,3 +123,23 @@ for a working reference client.
 - Check `capability_flags` before calling an optional method introduced
   in a later minor (none exist at v1.0 — `capability_flags == {}`).
 - Surface unknown closed-set codes gracefully; never hard-fail on them.
+
+## 8. FEAT-013 managed-session methods
+
+FEAT-013 adds 8 new methods to the `app.*` namespace — `app.managed_*`
+— for operator-driven creation of multi-agent tmux layouts inside bench
+containers. They are **required** surfaces at `app_contract_version =
+"1.0"` (not advertised in `capability_flags`; reached through the
+additive-evolution rule).
+
+See **[`docs/managed-sessions.md`](managed-sessions.md)** for the full
+operator reference: templates, launch profiles, lifecycle states, the
+M1–M8 method table, closed-set error codes, and the YAML override
+directories.
+
+Quick method list:
+
+- `app.managed_layout_create` / `app.managed_layout_list` / `app.managed_layout_detail` — layout creation + read
+- `app.managed_pane_list` / `app.managed_pane_detail` — pane read
+- `app.managed_pane_remove` / `app.managed_pane_recreate` — destructive lifecycle
+- `app.managed_pane_promote_from_adopted` — reserved stub (returns `not_implemented`)

docs/managed-sessions-quickstart-walkthrough.md

@@ -0,0 +1,59 @@
+# Managed Sessions Quickstart Walkthrough (T052)
+
+This document records how to run the [`specs/013-managed-session-lifecycle/quickstart.md`](../specs/013-managed-session-lifecycle/quickstart.md) walkthrough end-to-end against a real `agenttowerd` and a real bench container, plus the in-process verification harness that stands in for it during CI.
+
+T052's intent: prove the quickstart matches observed behavior, and capture any drift between the spec/contracts and what the daemon actually does.
+
+---
+
+## In-process verification (CI)
+
+The full quickstart sequence is exercised in-process by these tests, which use canned spawn-pipeline backends instead of a real tmux/docker channel:
+
+| Test file | Quickstart section covered |
+|---|---|
+| `tests/integration/test_story1_create_standard_layout.py` | §US1 (pending Phase 4c production tmux backend; module-level skip) |
+| `tests/integration/test_story2_auto_prepare_operations.py` | §US2 — every step from "Verify in agent surfaces" through FR-015 FIFO + FR-021 redaction shape |
+| `tests/integration/test_story3_lifecycle_operations.py` | §US3 — remove + recreate (with chain-traversal via M5) + adopted-pane protection |
+| `tests/integration/test_managed_edge_cases.py` | §Edge cases table (bullets 1, 5, 7, 9, 11 explicitly; others covered by contract tests) |
+| `tests/contract/test_managed_dispatch.py` | Dispatcher reachability + per-method envelope shape (M1-M8) |
+| `tests/contract/test_managed_perf_sla.py` | SC-001 + SC-008 + SC-009 wall-clock SLAs (in-process bounds) |
+
+Together these cover every observable behavior the quickstart asserts. Drift between quickstart prose and tests should produce a test-failure first; if you see drift only at quickstart-run time, **fix the code** (the quickstart is the spec-side truth, not the snapshot).
+
+---
+
+## Production walkthrough (manual)
+
+For a real end-to-end demo against a running `agenttowerd` plus a real bench container, follow the quickstart in order:
+
+1. Verify preconditions (§Preconditions): `agenttowerd` running, socket reachable, a bench container available, two operator YAML files in `~/.config/opensoft/agenttower/launch_commands/`.
+2. Run §US1 step-by-step. Confirm `state == "ready"` within SC-001's 2-minute budget.
+3. Run §US2 §"Verify in agent surfaces" — confirm `app.agent.list` returns the 3 managed agents with `origin == "managed"`.
+4. Run §US3 §"Remove and recreate a managed pane" — confirm tmux kill happens, recreate produces a `predecessor_id`-linked row, adopted pane attempt returns `managed_pane_protected_adopted`.
+5. Run §US3 §"Daemon restart (SC-008)" — stop the daemon, confirm tmux panes alive, start the daemon, hit `app.managed_layout_detail` within ~5s, confirm `state == "ready"`.
+6. Run §Edge cases — at minimum exercise the `managed_session_name_conflict` and `managed_layout_capacity_exceeded` paths.
+
+Production end-to-end requires:
+
+- The tmux spawn backend composition (`tmux_create.py` + `pending_marker.py` + FEAT-004 docker-exec channel) — documented as a follow-up in `src/agenttower/managed_sessions/spawn_backends.py`.
+- The daemon-boot wiring of `spawn_layout_in_background` (handler kick-off after `create_layout` returns) — same follow-up.
+- The daemon-boot wiring of `recovery.reconcile()` (run before the socket accepts requests per SC-008) — documented in `src/agenttower/managed_sessions/recovery.py`'s module docstring.
+- The daemon-boot wiring of `pending_marker.sweep()` (60-second periodic) — documented in `src/agenttower/managed_sessions/pending_marker.py`.
+
+All four wiring follow-ups share the same DaemonContext field additions; they're tracked together as the "daemon-boot wiring follow-up" outside of FEAT-013's natural per-task scope.
+
+---
+
+## Drift report (last run)
+
+| Date | Run by | Result | Notes |
+|---|---|---|---|
+| _(none yet — quickstart is exercised in-process via the test suites listed above; manual production walkthrough is gated on the daemon-boot wiring follow-up)_ | | | |
+
+When the production walkthrough is run (after the daemon-boot wiring follow-up lands), add a row above with the date, runner, pass/fail, and any drift between the quickstart prose and observed behavior. Then either:
+
+- The quickstart is canonical → file a code fix for the divergence.
+- The behavior is canonical → file a spec amendment + re-run.
+
+Per T052: drift is a signal to fix code, not the spec.

docs/managed-sessions.md

@@ -0,0 +1,253 @@
+# Managed Session Creation and Lifecycle (FEAT-013)
+
+Operator-facing reference for AgentTower's **managed-session** surface:
+how to create a multi-agent tmux layout inside a bench container, how
+the lifecycle states behave, where the operator YAML configuration
+lives, and which CLI / app-contract methods are available.
+
+This is a companion to:
+
+- [`specs/013-managed-session-lifecycle/spec.md`](../specs/013-managed-session-lifecycle/spec.md) — feature requirements.
+- [`specs/013-managed-session-lifecycle/quickstart.md`](../specs/013-managed-session-lifecycle/quickstart.md) — synthetic-client walkthrough (US1/US2/US3 end-to-end).
+- [`specs/013-managed-session-lifecycle/contracts/managed-methods.md`](../specs/013-managed-session-lifecycle/contracts/managed-methods.md) — wire-shape contracts for M1–M8.
+- [`docs/app-contract-client-guide.md`](app-contract-client-guide.md) — the client-facing index for all `app.*` methods (including the new `app.managed_*` set added by this feature).
+
+---
+
+## Overview
+
+FEAT-013 adds operator-driven creation of standard multi-agent tmux
+layouts. Instead of adopting existing panes one-by-one through
+`app.agent.register_from_pane`, the operator picks a **template** (e.g.
+"1 master + 2 slaves") and AgentTower:
+
+1. Creates the tmux panes via `tmux new-session` / `split-window` (no
+   `send-keys` for the first-line command — Principle III safety).
+2. Registers each created pane as a FEAT-006 agent so the existing
+   route / queue / event / log surfaces work uniformly across managed
+   and adopted agents.
+3. Tracks each pane through a 5-state lifecycle (`creating` → `ready` /
+   `degraded` / `failed` → `removed`) with audit-grade events on every
+   transition.
+4. Survives daemon restarts: managed layouts are recovered from durable
+   SQLite storage and reattached to surviving tmux panes within 5
+   seconds of the socket opening (SC-008 + SC-009).
+
+---
+
+## Templates
+
+Two built-in templates ship in code; operator-overridable YAML files
+extend the set without re-compiling the daemon.
+
+### Built-ins
+
+| Name | Panes | Roles |
+|---|---|---|
+| `1m+2s` | 3 | 1 master + 2 slaves |
+| `2m+2s` | 4 | 2 masters + 2 slaves |
+
+### Override directory
+
+```text
+~/.config/opensoft/agenttower/managed_templates/*.yaml
+```
+
+The daemon does NOT auto-create this directory; the operator creates
+it when adding the first override. Sample template YAMLs live in the
+repo under `examples/managed_templates/` for discovery (NOT installed
+by the daemon — per FR-024's no-auto-create rule).
+
+### YAML schema
+
+```yaml
+name: my-custom            # unique; operator file with same name wins
+                            # over a built-in default
+panes:
+  - role: master
+    capability: orchestrator
+    label_pattern: "m{ordinal}"        # {ordinal} → 1, 2, ...
+    default_launch_command_ref: claude-master    # see Launch profiles
+  - role: slave
+    capability: worker
+    label_pattern: "s{ordinal}"
+    default_launch_command_ref: claude-worker
+```
+
+---
+
+## Launch command profiles
+
+Argv-shape command definitions used to start each agent. The argv form
+is mandatory — single-string shell-parsed commands are rejected (the
+shell-interpolation hazard is the reason FEAT-013 exists).
+
+### Override directory
+
+```text
+~/.config/opensoft/agenttower/launch_commands/*.yaml
+```
+
+Sample profile YAMLs live under `examples/launch_commands/` for
+discovery.
+
+### YAML schema
+
+```yaml
+name: claude-master
+command: ["claude", "--model", "opus", "--system-prompt-file", "master.md"]
+env:
+  ANTHROPIC_LOG: warn
+working_dir: /workspace
+```
+
+- `command` — argv (list of strings); the tmux `new-session -d -s ... --
+  <cmd...>` invocation passes these AS-IS, no shell parsing.
+- `env` — optional; merged into the pane's environment via tmux's
+  `-e KEY=VALUE` flag.
+- `working_dir` — optional; the ONLY field where any shell escaping
+  happens (via `shlex.quote`), because tmux's `-c` working-directory
+  flag goes through the shell.
+
+Operator-supplied env-var **values** matching the closed substring set
+`*TOKEN*` / `*SECRET*` / `*KEY*` / `*PASSWORD*` (case-insensitive) are
+redacted in lifecycle event payloads (FR-021). Argv and `working_dir`
+are NOT redacted (operator-visible failure diagnostics rely on them).
+
+---
+
+## Lifecycle states
+
+Both `managed_pane` and `managed_layout` rows track one of five states:
+
+| State | Meaning |
+|---|---|
+| `creating` | Pane is being spawned, agent is being registered, logs are being attached. Pending-managed marker is set on the tmux pane title so the FEAT-004 scan skips it. |
+| `ready` | Pane exists in tmux, agent is registered with FEAT-006, log attach attempted (success or recoverable failure). Marker cleared. |
+| `degraded` | Pane exists but is partly unhealthy: launch command exited within 1s, log attach failed, or agent went unhealthy after `ready`. Recovery is via **recreate**. |
+| `failed` | Pane is unusable until recreated. `failed_stage` is populated. Audit retained indefinitely; a fresh recreated row may take the same label. |
+| `removed` | Operator-initiated removal; tmux pane was killed, routes/log attachments cleaned. Terminal. Audit retained indefinitely. |
+
+`failed_stage` is one of six closed-set values when set:
+`pane_create` / `launch_command` / `registration` / `log_attach` /
+`tmux_kill` / `recovery_reattach`. The full state graph (transitions,
+disallowed transitions, recovery rules) lives in
+[`contracts/state-machine.md`](../specs/013-managed-session-lifecycle/contracts/state-machine.md).
+
+---
+
+## Method list
+
+Eight methods total, available in **both** namespaces. The legacy
+`managed.*` namespace is reachable from host CLI and bench-container
+thin clients (with peer scoping); the `app.managed_*` namespace is
+host-only via the FEAT-011 gate.
+
+| Method (legacy) | Method (app) | What it does |
+|---|---|---|
+| `managed.layout.create` | `app.managed_layout_create` | Create a managed layout from a template. Returns immediately after row insertion; tmux spawn runs in a background task. (M1) |
+| `managed.layout.list` | `app.managed_layout_list` | Paginated list of managed layouts. Ordered by `(state_priority ASC, created_at DESC)` — operational-state first. (M2) |
+| `managed.layout.detail` | `app.managed_layout_detail` | Full layout view including all panes (optionally terminal). Surfaces `failed_stage` at both layout and per-pane levels. (M3) |
+| `managed.pane.list` | `app.managed_pane_list` | Paginated list of managed panes. (M4) |
+| `managed.pane.detail` | `app.managed_pane_detail` | Single-pane detail with optional `predecessor_chain` recursion. (M5) |
+| `managed.pane.remove` | `app.managed_pane_remove` | Kill underlying tmux pane + clean up routes/logs + transition to `removed`. Preserves audit history. (M6) |
+| `managed.pane.recreate` | `app.managed_pane_recreate` | Produce a new pane row linked via `predecessor_id` + `chain_depth+1`. Predecessor must be in `removed` or `failed`. (M7) |
+| `managed.pane.promote_from_adopted` | `app.managed_pane_promote_from_adopted` | **STUB** — always returns `not_implemented` with `reserved_since="FEAT-013"`. Reserved for a later feature. (M8) |
+
+Full request / response shapes for every method are in
+[`contracts/managed-methods.md`](../specs/013-managed-session-lifecycle/contracts/managed-methods.md).
+
+---
+
+## Example: create a layout
+
+```json
+{
+  "method": "app.managed_layout_create",
+  "container_id": "bench-alpha",
+  "template_name": "1m+2s",
+  "tmux_session_name": "session-quickstart",
+  "launch_command_overrides": {
+      "master:m1": "claude-master",
+      "slave:s1":  "claude-worker",
+      "slave:s2":  "claude-worker"
+  },
+  "idempotency_key": "operator-clicked-create-12345"
+}
+```
+
+Response (immediate, before tmux spawn completes):
+
+```json
+{
+  "ok": true,
+  "app_contract_version": "1.0",
+  "result": {
+    "layout_id": "01HZ...",
+    "state": "creating",
+    "intended_pane_count": 3,
+    "panes": [
+        {"pane_id": "01HZ-p1", "role": "master", "label": "m1", "state": "creating"},
+        {"pane_id": "01HZ-p2", "role": "slave",  "label": "s1", "state": "creating"},
+        {"pane_id": "01HZ-p3", "role": "slave",  "label": "s2", "state": "creating"}
+    ],
+    "replay": false
+  }
+}
+```
+
+Poll `app.managed_layout_detail` until `state == "ready"` (or subscribe
+to lifecycle events via `app.event.list`).
+
+---
+
+## Closed-set error codes (FEAT-013 additions)
+
+13 new error codes added on top of FEAT-011's 27-entry registry (40
+total). Full details in
+[`contracts/error-codes.md`](../specs/013-managed-session-lifecycle/contracts/error-codes.md).
+
+| Code | Method(s) | When |
+|---|---|---|
+| `managed_template_not_found` | M1 | `template_name` doesn't resolve via built-ins or operator overrides. |
+| `managed_launch_command_not_found` | M1 / M7 | `launch_command_overrides` references an unknown profile. |
+| `managed_session_name_conflict` | M1 | `tmux_session_name` already exists in the target container. No silent suffixing. |
+| `managed_pane_label_conflict` | M1 | Two non-terminal panes collide on `(container_id, label)`. |
+| `managed_layout_capacity_exceeded` | M1 | Daemon at 40-layout cap (FR-025). |
+| `managed_layout_not_found` | M3 | Unknown `layout_id`. |
+| `managed_pane_not_found` | M4 / M5 / M6 / M7 | Unknown `pane_id` (or `predecessor_pane_id`). |
+| `managed_pane_protected_adopted` | M6 / M7 | Target pane exists in `agents` (adopted) but NOT in `managed_pane` (FR-012). |
+| `managed_pane_illegal_transition` | M6 | E.g., trying to remove a pane in `creating` state. |
+| `managed_pane_illegal_recreate_source` | M7 | Predecessor is `ready` / `degraded` / `creating` (must be `removed` / `failed`). |
+| `managed_pane_recreate_chain_too_deep` | M7 | `predecessor.chain_depth >= 15` (limit is 16; FR-023). |
+| `managed_pane_concurrent_recreate` | M7 | Another recreate of the same predecessor is in flight (FR-027). |
+| `container_not_found` | M1 / M6 / M7 | `container_id` is unknown to the FEAT-003 registry. |
+
+---
+
+## Scope notes (MVP)
+
+**Out of scope** (FR-018): non-tmux backends, semantic task planning,
+cross-host orchestration, adopted-to-managed pane promotion, and
+cancellation of in-flight layout creation.
+
+**Indefinite retention** (FR-021): managed-layout and managed-pane
+audit records are preserved indefinitely in MVP. Pruning is deferred to
+a later feature.
+
+**Authorization** (spec §Assumptions): MVP is socket-access-based —
+any caller with access to the host daemon's local socket can create
+managed layouts. Per-user or per-container ACL is a later hardening
+feature. `app.managed_*` is host-only via FEAT-011's gate; legacy
+`managed.*` is peer-scoped (a bench-container thin client may only act
+on its own container).
+
+---
+
+## See also
+
+- Spec: [`specs/013-managed-session-lifecycle/spec.md`](../specs/013-managed-session-lifecycle/spec.md)
+- Quickstart: [`specs/013-managed-session-lifecycle/quickstart.md`](../specs/013-managed-session-lifecycle/quickstart.md)
+- Contracts: [`specs/013-managed-session-lifecycle/contracts/`](../specs/013-managed-session-lifecycle/contracts/)
+- Research decisions: [`specs/013-managed-session-lifecycle/research.md`](../specs/013-managed-session-lifecycle/research.md)
+- Data model: [`specs/013-managed-session-lifecycle/data-model.md`](../specs/013-managed-session-lifecycle/data-model.md)

examples/launch_commands/bash-placeholder.example.yaml

@@ -0,0 +1,22 @@
+# Example launch command profile.
+#
+# Copy this file to ~/.config/opensoft/agenttower/launch_commands/ and
+# adjust `name:`, `command:`, `env:`, `working_dir:` to your needs.
+#
+# Per research §R9, `command:` MUST be a list of strings (argv) — never
+# a single shell string. The daemon passes argv directly to tmux's
+# new-session / split-window invocations, so shell interpolation does
+# not apply (Principle III safety).
+#
+# `env:` is optional. Per FR-021 the daemon redacts environment-variable
+# values whose key matches `*TOKEN*` / `*SECRET*` / `*KEY*` / `*PASSWORD*`
+# (case-insensitive substring) in the JSONL lifecycle event payloads
+# retained indefinitely. Command argv and working_dir are not redacted.
+#
+# `working_dir:` is optional and applied via tmux's `-c` flag (no shell).
+
+name: bash-placeholder
+command: ["bash", "-lc", "echo 'agent ready'; exec bash"]
+env:
+  AGENTTOWER_ROLE: example
+working_dir: /workspace