diff --git a/.specify/feature.json b/.specify/feature.json
index add480a..8dff5f9 100644
--- a/.specify/feature.json
+++ b/.specify/feature.json
@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/005-container-thin-client"
+  "feature_directory": "specs/006-agent-registration"
 }
diff --git a/CLAUDE.md b/CLAUDE.md
index b582293..dc28887 100644
--- a/CLAUDE.md
+++ b/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/005-container-thin-client/plan.md`.
+`specs/006-agent-registration/plan.md`.
 <!-- SPECKIT END -->
 
 # AgentTower Agent Context
diff --git a/specs/006-agent-registration/checklists/agent-registry-quality.md b/specs/006-agent-registration/checklists/agent-registry-quality.md
new file mode 100644
index 0000000..9883e0d
--- /dev/null
+++ b/specs/006-agent-registration/checklists/agent-registry-quality.md
@@ -0,0 +1,81 @@
+# Combined Quality Checklist: Agent Registration and Role Metadata
+
+**Purpose**: Unit-test the FEAT-006 requirements for security, CLI contract, data model, and concurrency quality. Validates whether the spec is *written* well enough — complete, unambiguous, consistent, measurable — for implementation and PR review. Does NOT verify behavior of the implementation.
+
+**Created**: 2026-05-07
+**Walked**: 2026-05-07 (post-`/speckit.analyze` fixes)
+**Feature**: [spec.md](../spec.md)
+**Companion artifacts**: [plan.md](../plan.md), [research.md](../research.md), [data-model.md](../data-model.md), [contracts/cli.md](../contracts/cli.md), [contracts/socket-api.md](../contracts/socket-api.md), [quickstart.md](../quickstart.md)
+**Audience**: spec author (pre-`/speckit.tasks` gate) AND PR reviewer (post-implementation)
+**Depth**: standard release gate (~30 items across four domains)
+
+## Security: Master safety boundary
+
+- [x] CHK001 Are the conditions for `set-role --role master --confirm` to succeed enumerated as a closed set (target exists, target `active=true`, container `active=true`)? [Completeness, Spec §FR-011] — **Resolved**: FR-011 enumerates "if and only if the target agent exists, is `active=true`, and the target's bench container is `active=true`".
+- [x] CHK002 Is the rationale for *asymmetric* master-promotion vs. demotion gating (`--confirm` required for promote; not for demote) documented so reviewers can judge whether the trade-off is intentional? [Clarity, Spec §FR-013] — **Resolved**: FR-013 documents the asymmetry explicitly and defers in-flight prompt arbitration to FEAT-009/FEAT-010.
+- [x] CHK003 Are the three master-rejection paths (`register-self --role master`, `set-role --role master` without `--confirm`, `set-role --role swarm`) each mapped to a *distinct* closed-set error code? [Consistency, Spec §FR-010, §FR-011, §FR-012] — **Resolved**: `master_via_register_self_rejected` (FR-010), `master_confirm_required` (FR-011), `swarm_role_via_set_role_rejected` (FR-012). Three distinct codes in FR-040.
+- [x] CHK004 Is the behavior of `set-role --role master --confirm` when the agent's container becomes inactive *between* validation and write specified, or is the spec silent on this race? [Coverage, Edge Case, Gap] — **Resolved by Clarifications session 2026-05-07-continued Q3**: FR-011 now mandates atomic re-check inside `BEGIN IMMEDIATE`; SQLite serialization closes the race window.
+- [x] CHK005 Does the spec specify whether `confirm_provided=true` is recorded on demotion paths that were called *with* `--confirm` even though `--confirm` was unnecessary? [Ambiguity, Spec §FR-014] — **Resolved by Clarifications session 2026-05-07-continued Q5**: FR-014 locks the literal-value rule; demotion-with-redundant-`--confirm` logs `confirm_provided: true`.
+
+## Security: Audit log and observability
+
+- [x] CHK006 Is the JSONL audit row *required field set* defined as a closed set, with explicit handling for any future field additions (additive-only vs. version-bumped)? [Completeness, Spec §FR-014] — **Deferred** to [opensoft/AgentTower#7](https://github.com/opensoft/AgentTower/issues/7). FR-014 + data-model.md §4.4 lock the closed required field set (`agent_id`, `prior_role`, `new_role`, `confirm_provided`, `socket_peer_uid`, `ts_utc`, `event_type`). Future-field-additions policy (additive-only vs. version-bumped) is documented as a known gap in the issue; addressed when the first audit-log consumer ships (FEAT-007 or FEAT-008). No FEAT-006 implementation impact.
+- [x] CHK007 Is the source of `socket_peer_uid` (FEAT-002 `SO_PEERCRED` inheritance) explicitly stated in the spec rather than left implicit? [Traceability, Spec §FR-014, Gap] — **Resolved**: data-model.md §4.4 says "`socket_peer_uid` — host uid of the calling process, from FEAT-002 `SO_PEERCRED`."
+- [x] CHK008 Are the conditions under which an audit row MUST NOT be appended fully enumerated (failed transitions per FR-014; no-op writes per FR-027; `set-label` and `set-capability` calls)? [Completeness, Spec §FR-014, §FR-027] — **Resolved**: FR-014 (failed → no row), FR-027 (no-op → no row), FR-014 + contracts/socket-api.md §2.4–2.5 (set-label / set-capability never audit). All three conditions enumerated.
+- [x] CHK009 Is the audit-append ordering relative to the SQLite COMMIT specified (append after COMMIT, never before; rollback ⇒ no append)? [Clarity, Spec §FR-035] — **Resolved**: data-model.md §5.3 explicitly states "after the SQLite COMMIT and only when `prior_role != new_role`. Failed COMMITs (rolled back) MUST NOT append a row".
+- [x] CHK010 Does the spec guarantee that `prior_role: null` is encoded as the JSON literal `null` (and not as a missing key, empty string, or `"null"` string)? [Clarity, Spec Clarifications 2026-05-07 Q4] — **Resolved**: Clarifications Q4 locks "the audit row's `prior_role` MUST be the JSON literal `null`"; data-model.md §4.4 reaffirms.
+
+## Security: Wire encoding, sanitization, and trust boundary
+
+- [x] CHK011 Is the supplied-vs-default wire contract specified at *both* ends (CLI MUST NOT transmit defaults; daemon MUST distinguish absent key from default value), so a future CLI rewrite cannot regress the silent-demotion property? [Completeness, Spec §FR-007, §FR-028, Clarifications Q1] — **Resolved**: Round 1 Q1 + FR-007 (daemon side) + FR-028 (CLI side) both explicitly require absent-key encoding for omitted flags. Research R-002 + contracts/socket-api.md §2.1 amplify the wire contract.
+- [x] CHK012 Are the FR-033 / FR-034 sanitization rules consistent with the FEAT-004 sanitization rules they claim to inherit, with no FEAT-006-specific divergence (NUL strip, C0 strip, multi-byte-safe truncation, per-field length cap)? [Consistency, Spec §FR-033, §FR-034] — **Resolved**: FR-033 explicitly inherits FEAT-004 rules; research R-022 reuses `agenttower.tmux.parsers.sanitize_text`; bounds (label ≤ 64, project_path ≤ 4096) are FEAT-006-specific but the algorithm is FEAT-004's verbatim.
+- [x] CHK013 Is the trust boundary for FR-024 (CLI resolves container_id; daemon does NOT re-derive from socket peer) explicitly tied to the host-user-only socket-file authorization assumption, so reviewers can judge whether spoofing is in or out of the threat model? [Traceability, Spec §FR-024, §FR-043, Assumption] — **Resolved**: FR-024 + FR-043 + Assumptions ("the new socket methods inherit the FEAT-002 socket-file authorization (`0600`, host user only) verbatim") + edge case line 78 (bench user vs socket peer uid as descriptive metadata, not auth boundary). The trust model is: host-user access to the socket = trusted; container internals are not a security boundary.
+- [x] CHK014 Is the `parent_immutable` rejection's atomicity guarantee (no mutable field updated when other fields are also supplied; transaction rolled back; no audit row) specified rather than left to inference? [Clarity, Spec §FR-018a, Clarifications Q3] — **Resolved**: FR-018a explicitly locks "rejection is atomic and all-or-nothing" with the three guarantees enumerated.
+
+## CLI contract: Locked TSV column schema
+
+- [x] CHK015 Does the spec disambiguate whether the `PARENT` column renders as the bare 12-hex portion, the full `agt_<12-hex>` form (16 chars), or some other short form — given that `AGENT_ID` already uses the full form? [Ambiguity, Spec Clarifications Q5, Conflict with contracts/cli.md] — **Resolved by Clarifications session 2026-05-07-continued Q1**: PARENT renders full `agt_<12-hex>`; only CONTAINER uses the bare 12-char short form. FR-029 locked.
+- [x] CHK016 Is the rendering of free-text fields (`LABEL`, `PROJECT`) that contain literal `\t` or `\n` after FR-033 sanitization specified (replace with single space, drop, escape, or reject)? [Coverage, Spec §FR-029, Gap] — **Resolved**: contracts/cli.md C-CLI-602 specifies "embedded `\t` and `\n` in `LABEL`/`PROJECT` after FR-033 sanitization replaced with single space (matches FEAT-005 cli.md convention)". Note: FR-033 inherits FEAT-004 C0-stripping which already removes `\t` (0x09) and `\n` (0x0A) before TSV rendering, so the case is largely defensive.
+- [x] CHK017 Are the closed-set rendering tokens for `ACTIVE` (`true`/`false`) and `PARENT` (`-` for null) specified verbatim, or could implementations diverge (`yes`/`no`, `null`, `none`)? [Clarity, Spec §FR-029] — **Resolved**: FR-029 says verbatim "ACTIVE MUST render as the literal `true` or `false`" and "the literal `-` (single ASCII hyphen) when null".
+- [x] CHK018 Is the contract for "future fields go to `--json` or `--wide`, never the default form" expressed as a hard rule rather than guidance, so reviewers can reject silent column additions? [Clarity, Spec Clarifications Q5] — **Resolved**: FR-029 (post-clarification) uses "MUST NOT" hard rule: "Any future fields added to the agent record MUST NOT be added to the default form; they MUST be exposed via `--json` or a separately-introduced `--wide` flag".
+
+## CLI contract: Error codes and JSON purity
+
+- [x] CHK019 Are the closed-set error codes specified to appear verbatim in *both* `--json` output AND human-readable stderr, or only in `--json` (FR-040 mentions only the latter)? [Coverage, Spec §FR-040, Gap] — **Resolved**: contracts/cli.md cross-cutting CLI rules: "every failure path surfaces a closed-set error code that appears verbatim in `--json` output and in the human-readable stderr message". Spec FR-040 is amplified by contracts.
+- [x] CHK020 Is `--json` purity defined (exactly one JSON object on stdout per invocation; no incidental stderr lines except daemon-unavailable; canonical key order)? [Completeness, Spec §FR-028, Gap] — **Resolved**: contracts/cli.md cross-cutting "`--json` purity" subsection: "exactly one JSON object per invocation. No incidental human-readable lines on stderr (except the standard FEAT-002 daemon-unavailable message)". Canonical key order is locked by the example shapes in C-CLI-601..605 and snapshot tests (T031, T039, T065).
+- [x] CHK021 Are the exit-code mappings for the five new CLIs specified across the full success / no-op / closed-set-error / daemon-unavailable / internal-error matrix, with the same code never overloaded across distinct semantic outcomes? [Coverage, Spec §FR-032, §FR-040] — **Resolved**: contracts/cli.md C-CLI-601 has the explicit table (`0` success / no-op, `1` closed-set error, `2` daemon-unavailable, `4` reserved internal CLI). C-CLI-602..605 inherit the same mapping. No overloading.
+- [x] CHK022 Is the case-sensitivity contract for closed-set values (`role`, `capability`) and identifier values (`container_id` 12-char short, `parent_agent_id`) explicitly defined, so reviewers can judge whether `Slave` should equal `slave`? [Clarity, Spec §FR-004, §FR-005, §FR-026, Gap] — **Resolved by Clarifications session 2026-05-07-continued Q2**: FR-001/004/005/026 all updated; case-sensitive matching mandated; mixed-case rejected with `value_out_of_set`, never normalized.
+
+## Data model: Schema, migration, and derived state
+
+- [x] CHK023 Does the spec specify the exact migration ordering rule (table created → `schema_version` updated, never the reverse) so that crash-during-migration leaves `v3` rather than `v4`-without-table? [Clarity, Spec §FR-036] — **Resolved**: FR-036 says "MUST bump `schema_version` only after the new table exists". data-model.md §3 reaffirms.
+- [x] CHK024 Are the JSON key ordering and value types of the `effective_permissions` column specified concretely enough that snapshot tests can lock the form (e.g., always `{"can_send", "can_receive", "can_send_to_roles"}` with `can_send_to_roles` always an array even when empty)? [Measurability, Spec §FR-021] — **Resolved**: FR-021 locks the closed-set fields; data-model.md §4.3 TypedDict; research R-008 derivation table; task T006 pins the JSON key ordering as `["can_send", "can_receive", "can_send_to_roles"]` and `can_send_to_roles` always a list incl. empty `[]`. Snapshot test T015 will lock at runtime.
+- [x] CHK025 Is the relationship between `agents` and `panes` (denormalized, no foreign key, application-layer reconciliation) specified with enough detail that a reader can reason about referential integrity without consulting the implementation? [Completeness, Spec §FR-037] — **Resolved**: FR-037 explicitly states "denormalized columns rather than by foreign-key constraint... referential integrity is enforced at the application layer". data-model.md §5.1 documents the cross-table relationship and reconciliation transactions.
+- [x] CHK026 Is the `agent_id` collision-handling policy (retry budget; failure-mode error code) defined in the spec proper rather than only in research / implementation? [Coverage, Spec §FR-001, Gap] — **Resolved by C2 fix**: FR-001 now states "bounded retry loop (≤ 5 attempts) under the per-(container_id, pane_composite_key) registration mutex; an exhausted retry budget MUST surface as `internal_error` (FR-035)".
+- [x] CHK027 Is the `last_seen_at` column type and nullability defined (TEXT, nullable until first scan observation), so the `null`-to-string transition is unambiguous in `--json` output? [Clarity, Spec §FR-009a, Gap] — **Resolved**: data-model.md §2.1 SQL declares `last_seen_at TEXT` (nullable, no NOT NULL); §2.1 notes explicitly say "nullable on creation"; contracts/socket-api.md §6.2 example shows `"last_seen_at": null`.
+- [x] CHK028 Are the consequences of re-activating an inactive agent at the same composite key when the *previously stored* `parent_agent_id` was non-null and the re-registration omits `--parent` specified — does parent persist (per FR-018) or get re-validated against the now-possibly-changed parent state? [Coverage, Spec §FR-008, §FR-018, Gap] — **Resolved**: FR-018 locks "swarm child's `parent_agent_id` MUST remain pointing at the historical parent" + Round 1 Q1 (omitted flag = leave unchanged) + FR-008 (re-activation preserves `parent_agent_id`). Composing these three: omitting `--parent` on re-activation preserves stored value with no re-validation.
+
+## Concurrency: Mutex layout and atomicity
+
+- [x] CHK029 Is the lifecycle of the per-(container, pane-key) and per-`agent_id` mutex maps specified (creation on demand; never evicted; bounded by MVP agent count), so memory growth is auditable? [Completeness, Spec §FR-038, §FR-039, Gap] — **Resolved**: research R-005 + plan.md "Scale/Scope": "The advisory mutex maps grow with the number of distinct pane composite keys / agent_ids observed per daemon lifetime; entries are not evicted (memory overhead is bounded by MVP agent count)."
+- [x] CHK030 Is the mutex / SQLite-transaction nesting order specified (acquire mutex → BEGIN IMMEDIATE → COMMIT or ROLLBACK → release mutex), so reviewers can rule out lost-update races on `effective_permissions`? [Clarity, Spec §FR-035, §FR-038] — **Resolved**: data-model.md §7.3 (register_agent steps 12–22) and §7.3a (set_role steps 9–19) both explicitly enumerate "acquire mutex → BEGIN IMMEDIATE → write/COMMIT or ROLLBACK → release mutex". Plan.md Constraints reaffirms.
+- [x] CHK031 Does the spec address potential deadlock or contention between (a) FEAT-004 pane reconciliation transactions that update `last_seen_at` on agents and (b) in-flight `register_agent` transactions touching the same composite key? [Coverage, Spec §FR-009a, §FR-038, Gap] — **Resolved by Clarifications session 2026-05-07-continued Q4**: FR-038 + plan.md + contracts/socket-api.md §5 explicitly state cross-subsystem ordering via SQLite `BEGIN IMMEDIATE`; FEAT-004 reconciliation does not acquire the FEAT-006 mutex; last committed transaction wins; `SQLITE_BUSY` → `internal_error` without retry.
+- [x] CHK032 Is the convergence-on-same-`agent_id` property under concurrent `register-self` from the same pane defined as a *guarantee* rather than a likely outcome, with a specified ordering (first INSERT, second UPDATE; both observe post-commit state)? [Measurability, Spec Edge Case line 72] — **Resolved**: spec edge case line 72 mandates the property as a MUST: "Both MUST converge on the same `agent_id`; the second call's mutable-field writes MUST not race with the first call's insert". Research R-017 documents the INSERT-then-UPDATE ordering under the per-key mutex.
+
+## Cross-cutting consistency
+
+- [x] CHK033 Are spec, plan, research, data-model, and contracts/* internally consistent on the question of "does the daemon apply default values on first registration" — Q1 lock states the wire is symmetric; do all artifacts agree? [Consistency, Spec Clarifications Q1, Cross-artifact] — **Resolved**: spec FR-007 + FR-028 (CLI applies defaults on first registration), research R-002 (daemon also applies defaults on first registration so wire is symmetric), data-model.md §4.2 + §6.1, contracts/socket-api.md §2.1 — all four artifacts agree.
+- [x] CHK034 Are FR-040's listed closed-set error codes a strict superset of every code referenced in user stories, edge cases, and acceptance scenarios — or do any narrative passages reference codes that aren't in the closed set? [Consistency, Spec §FR-040] — **Resolved**: walked all edge cases and acceptance scenarios; every error-code reference appears in FR-040's closed set (incl. `parent_immutable` added by Round 1 Q3 fix). No drift detected.
+- [x] CHK035 Is the FEAT-005 forward-compat policy ("daemon newer than CLI ⇒ refuse") consistently applied to all five new CLIs, including read-only `list-agents`, with the same `schema_version_newer` exit-code behavior? [Consistency, Spec Edge Case line 79] — **Resolved**: spec edge case line 79 explicitly enumerates all five CLIs ("`register-self`, `list-agents`, `set-role`, `set-label`, `set-capability` MUST inherit the FEAT-005 forward-compat policy"). Research R-018 reaffirms the read-only `list-agents` is also subject.
+- [x] CHK036 Are the FEAT-006 success criteria (SC-001..SC-012) each traceable to at least one functional requirement, and does every functional requirement that introduces observable behavior have at least one SC entry that locks measurable acceptance? [Traceability, Spec §SC-001..SC-012] — **Resolved**: walked the SC ↔ FR matrix in `/speckit.analyze` coverage table — 100% bi-directional coverage; every observable-behavior FR has at least one SC.
+
+---
+
+## Walk Summary
+
+- **Walked**: 36 of 36 items
+- **Resolved (`[x]`)**: 35
+- **Deferred (`[x]` with issue link)**: 1 (CHK006 → [opensoft/AgentTower#7](https://github.com/opensoft/AgentTower/issues/7))
+- **Outstanding (`[ ]`)**: 0
+- **Resolution sources**: spec.md (incl. Clarifications Round 1 Q1–Q5 and Round 2 Q1–Q5), plan.md, research.md, data-model.md, contracts/cli.md, contracts/socket-api.md, post-`/analyze` fixes (C1, I1–I4, S1, C2)
+- **Verdict**: ✅ **PASS** — implementation is unblocked. CHK006 is a documentation-quality nit deferred to a tracked issue; no FEAT-006 implementation impact.
diff --git a/specs/006-agent-registration/checklists/requirements.md b/specs/006-agent-registration/checklists/requirements.md
new file mode 100644
index 0000000..2f7c2bf
--- /dev/null
+++ b/specs/006-agent-registration/checklists/requirements.md
@@ -0,0 +1,37 @@
+# Specification Quality Checklist: Agent Registration and Role Metadata
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-07
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The spec uses the same SQLite/JSONL/Unix-socket vocabulary that prior FEAT-001..FEAT-005 specs in this repo already use; these are operational contracts for AgentTower's MVP, not implementation language choices, and matching them is required for cross-feature consistency.
+- The `agt_<12-hex>` agent_id shape is locked at the contract layer (see FR-001, Assumption block) so downstream features (FEAT-009 routing, FEAT-010 arbitration) have a stable identifier shape; this is a contract decision, not an implementation detail.
+- Master safety is encoded as: (a) `register-self` cannot ever assign `role=master`; (b) `set-role --role master` requires `--confirm`; (c) `set-role --role swarm` is rejected outright (swarm role is only set via `register-self --parent`). This three-pronged boundary closes every silent-escalation path.
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`.
diff --git a/specs/006-agent-registration/contracts/cli.md b/specs/006-agent-registration/contracts/cli.md
new file mode 100644
index 0000000..399cab5
--- /dev/null
+++ b/specs/006-agent-registration/contracts/cli.md
@@ -0,0 +1,439 @@
+# CLI Contracts: Agent Registration and Role Metadata
+
+**Branch**: `006-agent-registration` | **Date**: 2026-05-07
+
+This document is the authoritative contract for the five additive
+CLI surfaces FEAT-006 introduces. It supplements `spec.md`
+FR-028, FR-029, FR-030, FR-031, FR-032, FR-040, and Clarifications
+2026-05-07 Q1, Q3, Q4, Q5. Anything here overrides informal CLI
+descriptions in spec.md.
+
+FEAT-001 / FEAT-002 / FEAT-003 / FEAT-004 / FEAT-005 CLI surfaces
+are unchanged byte-for-byte (SC-010).
+
+---
+
+## C-CLI-601 — `agenttower register-self`
+
+### Synopsis
+
+```text
+agenttower register-self [--role <r>] [--capability <c>] [--label <l>]
+                         [--project <path>] [--parent <agent-id>]
+                         [--json]
+```
+
+### Behavior
+
+Resolves the caller's container id (FEAT-005) and tmux pane
+composite key (FEAT-005 + FEAT-004 lookup; FR-041 focused rescan
+on miss), then registers (or idempotently re-registers /
+re-activates) the bound agent via the daemon's `register_agent`
+socket method.
+
+### Flags
+
+| Flag | Argparse default | Wire behavior on absence | Notes |
+| ---- | ---------------- | ------------------------ | ----- |
+| `--role <r>` | `argparse.SUPPRESS` | absent in JSON params | First registration applies CLI default `unknown` server-side; idempotent re-registration leaves stored role unchanged (Clarifications Q1). `r` ∈ `{master, slave, swarm, test-runner, shell, unknown}`. `--role master` is rejected unconditionally per FR-010. |
+| `--capability <c>` | `argparse.SUPPRESS` | absent in JSON params | Same semantics. `c` ∈ `{claude, codex, gemini, opencode, shell, test-runner, unknown}`. |
+| `--label <l>` | `argparse.SUPPRESS` | absent in JSON params | Sanitized + bounded to 64 chars (FR-033). Empty string is allowed when explicitly passed. |
+| `--project <path>` | `argparse.SUPPRESS` | absent in JSON params | Validated as absolute, NUL-free, no `..` segment, ≤ 4096 chars (FR-034). |
+| `--parent <agent-id>` | `argparse.SUPPRESS` | absent in JSON params | Only valid with `--role swarm` (FR-016). Re-registration with a *different* `--parent` rejected `parent_immutable` (Clarifications Q3). |
+| `--json` | flag | — | Emit one JSON object on stdout; suppress human-readable output. |
+
+### Exit codes (FR-032 + FR-040)
+
+The FEAT-006 CLI handlers follow the FEAT-002 / FEAT-005
+exit-code surface (daemon errors → `3`) rather than the
+spec-prose `1`-for-error sketch. The `1` slot is reserved for
+client-side context errors (today only `host_context_unsupported`).
+
+| Pattern | Exit code |
+| ------- | --------- |
+| Successful registration / idempotent re-registration / re-activation | `0` |
+| `host_context_unsupported` (running on the host shell, not in a bench container) | `1` |
+| `daemon_unavailable` (daemon down)                                   | `2` (FEAT-002 inheritance) |
+| Any other closed-set error code (e.g., `container_unresolved`, `not_in_tmux`, `tmux_pane_malformed`, `pane_unknown_to_daemon`, `master_via_register_self_rejected`, `swarm_parent_required`, `parent_role_mismatch`, `parent_not_found`, `parent_inactive`, `parent_role_invalid`, `parent_immutable`, `value_out_of_set`, `field_too_long`, `project_path_invalid`, `schema_version_newer`) | `3` |
+| Internal CLI error                                                   | `4` (reserved per FEAT-002) |
+
+### Default output
+
+One `key=value` line per field on stdout (matching the
+established multi-line key=value style FEAT-002 / FEAT-005 use for
+single-record success output):
+
+```text
+agent_id=<agt_xxx>
+role=<role>
+capability=<cap>
+label=<label>
+project_path=<path>
+parent_agent_id=<agt_xxx-or-dash>
+created_or_reactivated=<created|reactivated|updated>
+```
+
+`parent_agent_id` renders as the literal `-` when null.
+
+### `--json` output
+
+The success envelope wraps the daemon's `register_agent` result
+under `{"ok": true, "result": {...}}` so the same outer shape
+applies to every FEAT-006 CLI command (mirroring how `set-*`
+emit). The `result` object carries the fields below:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "agent_id": "agt_abc123def456",
+    "role": "slave",
+    "capability": "codex",
+    "label": "codex-01",
+    "project_path": "/workspace/acme",
+    "parent_agent_id": null,
+    "container_id": "<full-id>",
+    "pane_composite_key": {
+      "container_id": "<full-id>",
+      "tmux_socket_path": "/tmp/...",
+      "tmux_session_name": "main",
+      "tmux_window_index": 0,
+      "tmux_pane_index": 0,
+      "tmux_pane_id": "%17"
+    },
+    "effective_permissions": {
+      "can_send": false,
+      "can_receive": true,
+      "can_send_to_roles": []
+    },
+    "created_or_reactivated": "created"
+  }
+}
+```
+
+On error:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "<closed_set_code>",
+    "message": "<actionable message>"
+  }
+}
+```
+
+---
+
+## C-CLI-602 — `agenttower list-agents`
+
+### Synopsis
+
+```text
+agenttower list-agents [--role <r>...] [--container <id-or-short>]
+                       [--active-only] [--parent <agent-id>] [--json]
+```
+
+### Behavior
+
+Calls the daemon's `list_agents` socket method with the requested
+filter envelope. Read-only, no SQLite writes, no JSONL appends,
+no `last_seen_at` mutation (R-003).
+
+### Flags
+
+| Flag | Behavior |
+| ---- | -------- |
+| `--role <r>` | Repeatable. Each value must belong to the FR-004 closed set. AND-composes with other filters per FR-026 (within `--role` repeats: OR). |
+| `--container <id-or-short>` | Full container id or 12-char short id; classified server-side per FR-026. |
+| `--active-only` | Boolean flag; when present, daemon returns only `active=true` agents. |
+| `--parent <agent-id>` | Filter to swarm children of the named slave (FR-026). |
+| `--json` | Emit one JSON object on stdout (the `{"ok": true, "result": {...}}` envelope, with `filter` and `agents` nested under `result`); suppress TSV. |
+
+### Exit codes
+
+`0` on success (incl. empty result set per edge case "filter matches
+no rows" line 83 of spec); `2` on `daemon_unavailable`; `3` on any
+other closed-set code (e.g., `unknown_filter`, `value_out_of_set`,
+`schema_version_newer`).
+
+### Default output (Clarifications Q5)
+
+Tab-separated values with a required header row, locked
+nine-column schema in this exact order:
+
+```text
+AGENT_ID\tLABEL\tROLE\tCAPABILITY\tCONTAINER\tPANE\tPROJECT\tPARENT\tACTIVE
+agt_abc123def456\tcodex-01\tslave\tcodex\t<12-char-short>\tmain:0.1\t/workspace/acme\t-\ttrue
+agt_def456abc789\tclaude-swarm-01\tswarm\tclaude\t<12-char-short>\tmain:0.2\t/workspace/acme\tagt_abc123def456\ttrue
+...
+```
+
+Rendering rules:
+
+- Header row is the first line of output.
+- `CONTAINER` renders as the 12-character short container id.
+- `PARENT` renders as the full `agt_<12-hex>` form when
+  `parent_agent_id` is non-null, or the literal `-` (single ASCII
+  hyphen) when null.
+- `PANE` renders as `<session>:<window>.<pane>` (FEAT-004 short
+  form).
+- `ACTIVE` renders as the literal `true` or `false`.
+- Empty `LABEL` and `PROJECT` render as empty strings between the
+  tabs.
+- All free-text fields are sanitized of NUL / C0 control bytes
+  (per FR-033 / R-022); embedded `\t` and `\n` MUST be replaced
+  with single spaces so the TSV row stays one logical line.
+
+Future fields MUST NOT be added to the default form; they go to
+`--json` or a separately-introduced `--wide` flag.
+
+### `--json` output
+
+The success envelope wraps the daemon's `list_agents` result under
+`{"ok": true, "result": {...}}` (same outer shape as every other
+FEAT-006 CLI command):
+
+```json
+{
+  "ok": true,
+  "result": {
+    "filter": {
+      "role": null,
+      "container_id": null,
+      "active_only": false,
+      "parent_agent_id": null
+    },
+    "agents": [
+      {
+        "agent_id": "agt_abc123def456",
+        "role": "slave",
+        "capability": "codex",
+        "label": "codex-01",
+        "project_path": "/workspace/acme",
+        "parent_agent_id": null,
+        "container_id": "<full-id>",
+        "container_name": "...",
+        "container_user": "...",
+        "tmux_socket_path": "/tmp/...",
+        "tmux_session_name": "main",
+        "tmux_window_index": 0,
+        "tmux_pane_index": 0,
+        "tmux_pane_id": "%17",
+        "pane_pid": 12345,
+        "cwd": "/workspace/acme",
+        "effective_permissions": { "...": "..." },
+        "created_at": "2026-05-07T...",
+        "last_registered_at": "2026-05-07T...",
+        "last_seen_at": "2026-05-07T...",
+        "active": true
+      }
+    ]
+  }
+}
+```
+
+---
+
+## C-CLI-603 — `agenttower set-role`
+
+### Synopsis
+
+```text
+agenttower set-role --target <agent-id> --role <r> [--confirm] [--json]
+```
+
+### Behavior
+
+Calls the daemon's `set_role` socket method. Master promotion
+(`--role master`) requires `--confirm` AND the target agent
+`active=true` AND the target's bench container `active=true`
+(FR-011). Demotion from master MUST NOT require `--confirm`
+(FR-013). `--role swarm` MUST be rejected with
+`swarm_role_via_set_role_rejected` and the actionable message
+`swarm role assignment requires register-self --role swarm --parent <id>`
+(FR-012).
+
+### Flags
+
+| Flag | Required | Behavior |
+| ---- | -------- | -------- |
+| `--target <agent-id>` | yes | Validated client-side against `^agt_[0-9a-f]{12}$` (R-020). |
+| `--role <r>` | yes | `r` ∈ FR-004 closed set. `swarm` rejected per FR-012. `master` requires `--confirm` per FR-011. |
+| `--confirm` | conditional | Required for `--role master`. Calls without `--confirm` for master rejected `master_confirm_required`. |
+| `--json` | optional | Emit JSON; suppress text output. |
+
+### Exit codes
+
+`0` on success (including no-op when new role equals stored role);
+`2` on `daemon_unavailable`; `3` on any other closed-set code
+(`agent_not_found`, `agent_inactive`, `master_confirm_required`,
+`swarm_role_via_set_role_rejected`, `value_out_of_set`,
+`schema_version_newer`).
+
+### Default output
+
+One `key=value` line per field on stdout:
+
+```text
+agent_id=<agt_xxx>
+field=role
+prior_value=<role>
+new_value=<role>
+audit_appended=<true|false>
+```
+
+### `--json` output
+
+The success envelope is `{"ok": true, "result": {...}}` (same
+outer shape as `register-self`):
+
+```json
+{
+  "ok": true,
+  "result": {
+    "agent_id": "agt_abc123def456",
+    "field": "role",
+    "prior_value": "slave",
+    "new_value": "master",
+    "effective_permissions": {
+      "can_send": true,
+      "can_receive": false,
+      "can_send_to_roles": ["slave", "swarm"]
+    },
+    "audit_appended": true
+  }
+}
+```
+
+`audit_appended` is `false` on no-op writes (FR-027).
+
+---
+
+## C-CLI-604 — `agenttower set-label`
+
+### Synopsis
+
+```text
+agenttower set-label --target <agent-id> --label <l> [--json]
+```
+
+### Behavior
+
+Calls `set_label`. `--label` is sanitized + bounded to 64 chars
+(FR-033). Setting the same value the agent already has is a
+successful no-op that appends no audit row (FR-027 — `set_label`
+does not append audit rows in any path because only role
+transitions are audited).
+
+### Exit codes
+
+`0` on success; `2` on `daemon_unavailable`; `3` on any other
+closed-set code (`agent_not_found`, `agent_inactive`,
+`field_too_long`, `value_out_of_set`, `schema_version_newer`).
+
+### Default output
+
+One `key=value` line per field on stdout:
+
+```text
+agent_id=<agt_xxx>
+field=label
+prior_value=<label>
+new_value=<label>
+audit_appended=false
+```
+
+### `--json` output
+
+```json
+{
+  "ok": true,
+  "result": {
+    "agent_id": "agt_abc123def456",
+    "field": "label",
+    "prior_value": "codex-01",
+    "new_value": "codex-main",
+    "audit_appended": false
+  }
+}
+```
+
+---
+
+## C-CLI-605 — `agenttower set-capability`
+
+### Synopsis
+
+```text
+agenttower set-capability --target <agent-id> --capability <c> [--json]
+```
+
+### Behavior
+
+Calls `set_capability`. `--capability` MUST belong to the FR-005
+closed set. Setting the same value is a successful no-op.
+
+### Exit codes
+
+`0` on success; `2` on `daemon_unavailable`; `3` on any other
+closed-set code (`agent_not_found`, `agent_inactive`,
+`value_out_of_set`, `schema_version_newer`).
+
+### Default output / `--json` output
+
+Mirrors `set-label` with `field=capability`.
+
+---
+
+## Cross-cutting CLI rules
+
+### Socket resolution (FR-032)
+
+Every CLI in this feature inherits the FEAT-005 socket-resolution
+priority chain `AGENTTOWER_SOCKET → in-container default → host
+default` and the FEAT-005 / FEAT-002 daemon-unreachable
+exit-code-`2` behavior. None of these commands MUST start the
+daemon implicitly; the operator runs `agenttower ensure-daemon`
+separately.
+
+### Sanitization (FR-033, R-022)
+
+All free-text inputs and outputs are sanitized of NUL bytes and
+C0 control bytes via the existing
+`agenttower.tmux.parsers.sanitize_text` helper. Per-field bounds
+are enforced (label ≤ 64; project_path ≤ 4096); over-bound values
+are rejected with `field_too_long` rather than silently
+truncated.
+
+### Case-sensitivity (Clarifications session 2026-05-07-continued Q2)
+
+Every closed-set token (`role`, `capability`) and every
+lowercase-hex identifier (`agent_id`, `parent_agent_id`,
+`container_id`) is matched case-sensitively. Mixed-case inputs
+(`Slave`, `MASTER`, `agt_ABC...`, `ABC123def456`) MUST be
+rejected with `value_out_of_set` and MUST NOT be normalized.
+This applies uniformly to CLI argument validation, daemon-side
+validation, and filter matching for `list-agents`. Closed-set
+error messages list canonical lowercase tokens only.
+
+### Closed-set error codes (FR-040)
+
+Every failure path surfaces a closed-set error code that appears
+verbatim in `--json` output and in the human-readable stderr
+message. The complete set is in `contracts/socket-api.md` §3.
+
+### `--json` purity
+
+When `--json` is set, stdout MUST contain exactly one JSON object
+per invocation. No incidental human-readable lines on stderr
+(except the standard FEAT-002 daemon-unavailable message on
+`daemon_unavailable` which the CLI inherits verbatim).
+
+### Forward-compat (R-018)
+
+When the daemon's `schema_version` (returned by the FEAT-002
+`status` round-trip) is greater than the CLI's local
+`CURRENT_SCHEMA_VERSION`, every CLI in this feature surfaces
+`schema_version_newer` and refuses the call without making any
+state-changing socket call.
diff --git a/specs/006-agent-registration/contracts/socket-api.md b/specs/006-agent-registration/contracts/socket-api.md
new file mode 100644
index 0000000..064fbbb
--- /dev/null
+++ b/specs/006-agent-registration/contracts/socket-api.md
@@ -0,0 +1,643 @@
+# Socket-API Contracts: Agent Registration and Role Metadata
+
+**Branch**: `006-agent-registration` | **Date**: 2026-05-07
+
+This document is the authoritative contract for the five new
+daemon socket methods FEAT-006 introduces. It supplements
+`spec.md` FR-023, FR-024, FR-025, FR-026, FR-027, FR-035,
+FR-038, FR-039, FR-040, and Clarifications 2026-05-07 Q1, Q3,
+Q4.
+
+The new methods reuse the FEAT-002 newline-delimited JSON
+request/response framing and host-user authorization (`0600`,
+host user only) verbatim (FR-023, FR-043). No new framing, no
+new authorization tier, no new envelope shape.
+
+---
+
+## 1. Method dispatch table
+
+The FEAT-002 dispatch table grows from seven entries (FEAT-002:
+ping/status/shutdown; FEAT-003: scan_containers/list_containers;
+FEAT-004: scan_panes/list_panes) to twelve. Insertion order is
+preserved per the FEAT-002 stability rule; new entries are
+appended:
+
+```python
+DISPATCH: dict[str, Handler] = {
+    "ping":              _ping,                 # FEAT-002
+    "status":            _status,               # FEAT-002
+    "shutdown":          _shutdown,             # FEAT-002
+    "scan_containers":   _scan_containers,      # FEAT-003
+    "list_containers":   _list_containers,      # FEAT-003
+    "scan_panes":        _scan_panes,           # FEAT-004
+    "list_panes":        _list_panes,           # FEAT-004
+    "register_agent":    _register_agent,       # FEAT-006
+    "list_agents":       _list_agents,          # FEAT-006
+    "set_role":          _set_role,             # FEAT-006
+    "set_label":         _set_label,            # FEAT-006
+    "set_capability":    _set_capability,       # FEAT-006
+}
+```
+
+Unknown method names continue to return `unknown_method` per
+FEAT-002.
+
+---
+
+## 2. Request / response envelopes
+
+**Case-sensitivity contract** (Clarifications session 2026-05-07-continued Q2): every closed-set token (`role`, `capability`) and every lowercase-hex identifier (`agent_id`, `parent_agent_id`, `container_id`) in any request envelope is matched case-sensitively. Mixed-case inputs (`Slave`, `MASTER`, `agt_ABC...`, `ABC123def456`) MUST be rejected with `value_out_of_set`; the daemon MUST NOT normalize, lowercase, or case-fold any value before validation, lookup, or filter matching.
+
+All envelopes use the FEAT-002 newline-delimited JSON shape:
+
+```text
+{"method":"<name>","params":{...}}\n        # request
+{"ok":true,"result":{...}}\n                 # success response
+{"ok":false,"error":{"code":"<code>","message":"..."}}\n  # error response
+```
+
+Request size limit: inherits FEAT-002 `request_too_large`. Field
+sanitization: inherits FEAT-004 `output_malformed` for daemon-side
+free-text bounds; per-field bounds defined in
+`data-model.md` §8.
+
+### 2.1 `register_agent`
+
+**Request**
+
+```json
+{
+  "method": "register_agent",
+  "params": {
+    "container_id": "<full-id>",
+    "pane_composite_key": {
+      "container_id": "<full-id>",
+      "tmux_socket_path": "/tmp/...",
+      "tmux_session_name": "main",
+      "tmux_window_index": 0,
+      "tmux_pane_index": 0,
+      "tmux_pane_id": "%17"
+    },
+    "role": "slave",                  // OPTIONAL — see Q1 wire encoding
+    "capability": "codex",            // OPTIONAL
+    "label": "codex-01",              // OPTIONAL
+    "project_path": "/workspace/acme",// OPTIONAL
+    "parent_agent_id": "agt_aaa...",  // OPTIONAL — must equal stored value if present (FR-018a)
+    "schema_version": 4               // OPTIONAL — FR-040 forward-compat hint
+  }
+}
+```
+
+**Required keys**: `container_id`, `pane_composite_key`. The
+six pane composite-key sub-keys are all required when
+`pane_composite_key` is present.
+
+**Optional keys**: `role`, `capability`, `label`, `project_path`,
+`parent_agent_id`, `schema_version`. Per Clarifications Q1, the
+*absence* of a mutable key means "leave the stored value unchanged"
+on idempotent re-registration. On first registration of a new pane,
+the daemon applies the same default values the CLI applies
+(`role="unknown"`, `capability="unknown"`, `label=""`,
+`project_path=""`, `parent_agent_id=null`) so the wire contract is
+symmetric. `schema_version` is the FR-040 forward-compat hint —
+the CLI advertises the schema version it was built against so the
+daemon can refuse with `schema_version_newer` when its own schema
+has advanced past what the CLI knows. There is no `confirm` field
+on `register_agent` — the master safety boundary is unconditional
+on this method (FR-010), so register_agent audit rows always record
+`confirm_provided: false`.
+
+**Forbidden keys**: any key other than the seven listed above is
+rejected with `bad_request`. In particular, `confirm`,
+`socket_peer_uid`, and `audit_appended` are not accepted on
+`register_agent` — `socket_peer_uid` is plumbed out-of-band from
+the accepted AF_UNIX socket via `SO_PEERCRED` and cannot be
+spoofed via the request body.
+
+**Validation order** (data-model.md §7.3):
+
+1. Closed-set field shape on present optional keys (FR-004,
+   FR-005, FR-001 for parent_agent_id).
+2. Free-text bounds + sanitization on `label` (FR-033) and
+   `project_path` (FR-034).
+3. Master-safety static check: `role == "master"` →
+   `master_via_register_self_rejected` (FR-010).
+4. Swarm parent shape: `role == "swarm"` AND
+   `parent_agent_id` absent → `swarm_parent_required` (FR-015);
+   `parent_agent_id` present AND `role` is anything other than
+   `swarm` → `parent_role_mismatch` (FR-016).
+5. Acquire (container_id, pane_composite_key) advisory mutex
+   (FR-038).
+6. SELECT existing agent for the pane composite key.
+7. If existing row and `parent_agent_id` is supplied and
+   differs from the stored value → `parent_immutable`
+   (FR-018a).
+8. If no existing row and `role == "swarm"`:
+   resolve parent (FR-017) — `parent_not_found` /
+   `parent_inactive` / `parent_role_invalid`.
+9. Compose post-write state (only-supplied-fields-overwrite
+   per Q1).
+10. Recompute `effective_permissions` from final role.
+11. BEGIN IMMEDIATE; INSERT or UPDATE agents row; COMMIT.
+12. If creation OR if role changed: append JSONL audit row
+    (Q4: `prior_role: null` on creation).
+13. Release mutex; return success envelope.
+
+**Success response**
+
+```json
+{
+  "ok": true,
+  "result": {
+    "agent_id": "agt_abc123def456",
+    "role": "slave",
+    "capability": "codex",
+    "label": "codex-01",
+    "project_path": "/workspace/acme",
+    "parent_agent_id": null,
+    "container_id": "<full-id>",
+    "container_name": "...",
+    "container_user": "...",
+    "tmux_socket_path": "/tmp/...",
+    "tmux_session_name": "main",
+    "tmux_window_index": 0,
+    "tmux_pane_index": 0,
+    "tmux_pane_id": "%17",
+    "pane_pid": 12345,
+    "cwd": "/workspace/acme",
+    "effective_permissions": {
+      "can_send": false,
+      "can_receive": true,
+      "can_send_to_roles": []
+    },
+    "created_at": "2026-05-07T...",
+    "last_registered_at": "2026-05-07T...",
+    "last_seen_at": null,
+    "active": true,
+    "created_or_reactivated": "created"
+  }
+}
+```
+
+`created_or_reactivated` ∈ `{"created", "reactivated", "updated"}`:
+
+- `"created"` — first registration of this pane composite key.
+- `"reactivated"` — pane composite key existed with `active=0`
+  and was re-activated (FR-008).
+- `"updated"` — pane composite key existed with `active=1`;
+  this is an idempotent re-registration.
+
+**Error responses**
+
+Closed-set error codes for `register_agent`:
+
+| Code | Trigger |
+| ---- | ------- |
+| `bad_request` | Malformed JSON / missing required key / unknown key |
+| `value_out_of_set` | `role` / `capability` / `parent_agent_id` shape |
+| `field_too_long` | `label` > 64 chars or `project_path` > 4096 chars |
+| `project_path_invalid` | `project_path` not absolute / contains `..` / contains NUL |
+| `master_via_register_self_rejected` | `role == "master"` |
+| `swarm_parent_required` | `role == "swarm"` AND no `parent_agent_id` |
+| `parent_role_mismatch` | `parent_agent_id` AND `role != "swarm"` |
+| `parent_not_found` | swarm parent does not exist |
+| `parent_inactive` | swarm parent has `active = 0` |
+| `parent_role_invalid` | swarm parent has `role != "slave"` |
+| `parent_immutable` | re-registration with different `parent_agent_id` (Q3) |
+| `internal_error` | SQLite error / transaction rollback / agent_id collision retry exhausted |
+| `schema_version_newer` | client newer than daemon (defensive; CLI usually catches this first) |
+
+### 2.2 `list_agents`
+
+**Request**
+
+```json
+{
+  "method": "list_agents",
+  "params": {
+    "role": "slave",                  // OPTIONAL — string OR list of strings
+    "container_id": "abc123def456",   // OPTIONAL — full or 12-char short
+    "active_only": true,              // OPTIONAL — default false
+    "parent_agent_id": "agt_aaa..."   // OPTIONAL
+  }
+}
+```
+
+**Filter rules** (FR-026):
+
+- Filters compose with AND across keys.
+- `role` accepts a string or a list of strings; multiple values
+  OR within the field.
+- `container_id` accepts the full container id OR a 12-char
+  short id; classified server-side.
+- `active_only` is a boolean; missing key defaults to `false`.
+- `parent_agent_id` filters to swarm children of the named
+  slave.
+- Unknown filter keys → `unknown_filter`.
+
+**Read-only contract** (FR-025):
+
+- MUST NOT call Docker or tmux.
+- MUST NOT acquire any registration mutex.
+- MUST NOT update `last_seen_at`.
+- Returns the latest committed SQLite state in deterministic
+  order: `active DESC, container_id ASC, parent_agent_id ASC NULLS FIRST, label ASC, agent_id ASC`.
+
+**Success response**
+
+```json
+{
+  "ok": true,
+  "result": {
+    "filter": {
+      "role": ["slave"],
+      "container_id": null,
+      "active_only": true,
+      "parent_agent_id": null
+    },
+    "agents": [
+      { /* full AgentRecord JSON */ },
+      ...
+    ]
+  }
+}
+```
+
+The `filter` echo in the response normalizes `role` to a list
+even when the request supplied a string, and fills in nulls for
+absent filters so consumers can rely on the shape.
+
+**Error responses**
+
+| Code | Trigger |
+| ---- | ------- |
+| `bad_request` | Malformed JSON |
+| `unknown_filter` | Unknown key in `params` |
+| `value_out_of_set` | `role` value not in FR-004 closed set |
+| `internal_error` | SQLite error |
+| `schema_version_newer` | client newer than daemon |
+
+Empty result sets (e.g., `--container <id>` with no matching
+rows) are NOT errors per spec edge case line 83 — the response
+is `ok: true` with `agents: []`.
+
+### 2.3 `set_role`
+
+**Request**
+
+```json
+{
+  "method": "set_role",
+  "params": {
+    "agent_id": "agt_abc123def456",
+    "role": "master",
+    "confirm": true                   // OPTIONAL — required for role=master
+  }
+}
+```
+
+**Validation order**:
+
+1. Closed-set shape: `agent_id` matches `^agt_[0-9a-f]{12}$`
+   (case-sensitive); `role` ∈ FR-004 closed set (case-sensitive).
+2. Static rejection: `role == "swarm"` →
+   `swarm_role_via_set_role_rejected` (FR-012).
+3. Master-safety static rejection: `role == "master"` AND
+   `confirm != true` → `master_confirm_required` (FR-011).
+4. Acquire per-`agent_id` advisory mutex (FR-039).
+5. SELECT existing agent (read-only, outside the write
+   transaction; used only for the existence pre-check at step 6).
+6. Existence: if no row → `agent_not_found` (release mutex; no
+   transaction opened).
+7. `BEGIN IMMEDIATE` — open the write transaction.
+8. **Atomic re-check inside the transaction** (FR-011 / Clarifications
+   session 2026-05-07-continued Q3): re-SELECT `agents.active`
+   for the target AND `containers.active` for the agent's bound
+   `container_id`. If `agents.active = 0`, OR if the bound
+   `containers` row is missing (no row, JOIN returned NULL), OR
+   if `containers.active = 0`, `ROLLBACK` and return
+   `agent_inactive`; no role mutation, no `effective_permissions`
+   recomputation, no JSONL audit row. A missing containers row is
+   treated identically to `containers.active = 0` — without an
+   active container backing the agent, role assignment (especially
+   master promotion) MUST be refused. SQLite's `BEGIN IMMEDIATE`
+   serializes this re-check against any concurrent FEAT-004
+   reconciliation transaction so the validate-then-write window
+   is closed at the SQLite level.
+9. If new role equals stored role: `COMMIT` no-op; no audit
+   row (FR-027); release mutex; return success envelope.
+10. Recompute `effective_permissions` from the new role.
+11. `UPDATE agents SET role = ?, effective_permissions = ? WHERE agent_id = ?`.
+12. `COMMIT`.
+13. Append JSONL audit row with `prior_role`, `new_role`,
+    `confirm_provided` (the **literal** boolean the operator
+    passed — `true` if `--confirm` was passed, `false` otherwise;
+    NOT rewritten based on whether `--confirm` was required;
+    Clarifications session 2026-05-07-continued Q5),
+    `socket_peer_uid` (FR-014, Q4).
+14. Release mutex; return success envelope.
+
+**Success response**
+
+```json
+{
+  "ok": true,
+  "result": {
+    "agent_id": "agt_abc123def456",
+    "field": "role",
+    "prior_value": "slave",
+    "new_value": "master",
+    "effective_permissions": {
+      "can_send": true,
+      "can_receive": false,
+      "can_send_to_roles": ["slave", "swarm"]
+    },
+    "audit_appended": true
+  }
+}
+```
+
+**Error responses**
+
+| Code | Trigger |
+| ---- | ------- |
+| `bad_request` | Malformed JSON / missing required key / unknown key |
+| `value_out_of_set` | `agent_id` shape / `role` not in closed set |
+| `swarm_role_via_set_role_rejected` | `role == "swarm"` |
+| `master_confirm_required` | `role == "master"` AND `confirm != true` |
+| `agent_not_found` | `agent_id` does not exist |
+| `agent_inactive` | target `active = 0` OR (master promotion AND container `active = 0`) |
+| `internal_error` | SQLite error / transaction rollback |
+| `schema_version_newer` | client newer than daemon |
+
+### 2.4 `set_label`
+
+**Request**
+
+```json
+{
+  "method": "set_label",
+  "params": {
+    "agent_id": "agt_abc123def456",
+    "label": "codex-main"
+  }
+}
+```
+
+**Validation order**:
+
+1. Closed-set shape: `agent_id` matches regex.
+2. Free-text: `label` sanitized + bounded ≤ 64 chars (FR-033).
+3. Acquire per-`agent_id` advisory mutex (FR-039).
+4. SELECT existing agent.
+5. Existence + active checks (`agent_not_found` / `agent_inactive`).
+6. If new label equals stored label: no-op success.
+7. BEGIN IMMEDIATE; UPDATE agents SET label; COMMIT.
+8. NO audit row (FR-014 only audits role transitions).
+9. Release mutex; return success envelope.
+
+**Success response**
+
+```json
+{
+  "ok": true,
+  "result": {
+    "agent_id": "agt_abc123def456",
+    "field": "label",
+    "prior_value": "codex-01",
+    "new_value": "codex-main",
+    "audit_appended": false
+  }
+}
+```
+
+`audit_appended` is always `false` for `set_label`.
+
+**Error responses**
+
+| Code | Trigger |
+| ---- | ------- |
+| `bad_request` | Malformed JSON / missing required key |
+| `value_out_of_set` | `agent_id` shape |
+| `field_too_long` | `label` > 64 chars |
+| `agent_not_found` / `agent_inactive` | as for `set_role` |
+| `internal_error` | SQLite error |
+| `schema_version_newer` | client newer than daemon |
+
+### 2.5 `set_capability`
+
+**Request**
+
+```json
+{
+  "method": "set_capability",
+  "params": {
+    "agent_id": "agt_abc123def456",
+    "capability": "claude"
+  }
+}
+```
+
+**Validation order**:
+
+1. Closed-set shape: `agent_id` matches regex; `capability` ∈
+   FR-005 closed set.
+2. Acquire per-`agent_id` advisory mutex.
+3. SELECT existing agent.
+4. Existence + active checks.
+5. If new capability equals stored: no-op success.
+6. BEGIN IMMEDIATE; UPDATE agents SET capability; COMMIT.
+7. NO audit row (only role transitions audited).
+8. Release mutex; return success envelope.
+
+**Success response**
+
+Same shape as `set_label` with `field=capability`.
+`audit_appended` is always `false`.
+
+**Error responses**
+
+| Code | Trigger |
+| ---- | ------- |
+| `bad_request` | Malformed JSON / missing required key |
+| `value_out_of_set` | `agent_id` shape OR `capability` not in closed set |
+| `agent_not_found` / `agent_inactive` | as above |
+| `internal_error` | SQLite error |
+| `schema_version_newer` | client newer than daemon |
+
+---
+
+## 3. Closed-set error codes (FR-040)
+
+The complete FEAT-006 closed-set error code addition (R-010):
+
+| Constant | Wire token |
+| -------- | ---------- |
+| `HOST_CONTEXT_UNSUPPORTED` | `host_context_unsupported` |
+| `CONTAINER_UNRESOLVED` | `container_unresolved` |
+| `NOT_IN_TMUX` | `not_in_tmux` |
+| `TMUX_PANE_MALFORMED` | `tmux_pane_malformed` |
+| `PANE_UNKNOWN_TO_DAEMON` | `pane_unknown_to_daemon` |
+| `AGENT_NOT_FOUND` | `agent_not_found` |
+| `AGENT_INACTIVE` | `agent_inactive` |
+| `PARENT_NOT_FOUND` | `parent_not_found` |
+| `PARENT_INACTIVE` | `parent_inactive` |
+| `PARENT_ROLE_INVALID` | `parent_role_invalid` |
+| `PARENT_ROLE_MISMATCH` | `parent_role_mismatch` |
+| `PARENT_IMMUTABLE` | `parent_immutable` |
+| `SWARM_PARENT_REQUIRED` | `swarm_parent_required` |
+| `SWARM_ROLE_VIA_SET_ROLE_REJECTED` | `swarm_role_via_set_role_rejected` |
+| `MASTER_VIA_REGISTER_SELF_REJECTED` | `master_via_register_self_rejected` |
+| `MASTER_CONFIRM_REQUIRED` | `master_confirm_required` |
+| `VALUE_OUT_OF_SET` | `value_out_of_set` |
+| `FIELD_TOO_LONG` | `field_too_long` |
+| `PROJECT_PATH_INVALID` | `project_path_invalid` |
+| `UNKNOWN_FILTER` | `unknown_filter` |
+| `SCHEMA_VERSION_NEWER` | `schema_version_newer` |
+
+These codes are added to `socket_api/errors.py` and to
+`CLOSED_CODE_SET`. Existing FEAT-002/003/004 codes are unchanged
+(SC-010). `daemon_unavailable` is a CLI-side classification (the
+daemon never sees the call) and is NOT added to the daemon-side
+closed set; it remains the FEAT-002 inheritance.
+
+---
+
+## 4. Backwards compatibility (SC-010)
+
+- Existing dispatch entries (`ping`, `status`, `shutdown`,
+  `scan_containers`, `list_containers`, `scan_panes`,
+  `list_panes`) MUST be unchanged byte-for-byte: same handler
+  function, same response shape, same closed-set codes, same
+  error messages.
+- `socket_api/errors.py`'s existing constants and existing
+  `CLOSED_CODE_SET` membership MUST be unchanged; only new
+  constants are added.
+- The FEAT-002 newline-delimited JSON framing MUST be
+  unchanged.
+- The FEAT-002 `0600` host-user-only socket-file authorization
+  MUST be unchanged.
+
+A backwards-compat integration test
+(`tests/integration/test_feat006_backcompat.py`) gates these
+guarantees by re-running every FEAT-001..005 CLI command on the
+host and asserting byte-identical stdout, stderr, exit codes,
+and `--json` shapes.
+
+---
+
+## 5. Concurrency contract (FR-038, FR-039)
+
+- `register_agent` requests addressing the same
+  (container_id, pane_composite_key) tuple are serialized via a
+  per-key `threading.Lock` (R-005). Concurrent calls from
+  different panes proceed in parallel.
+- `set_role`, `set_label`, `set_capability` requests addressing
+  the same `agent_id` are serialized via a per-`agent_id`
+  `threading.Lock`. Concurrent calls on different agents
+  proceed in parallel.
+- All SQLite writes happen inside a `BEGIN IMMEDIATE`
+  transaction so the read-modify-write of
+  `effective_permissions` is atomic.
+- Failed transactions are rolled back; the daemon stays alive
+  (FR-035); no audit row is appended on rollback (FR-014).
+
+### Cross-subsystem ordering with FEAT-004 (FR-038 / Clarifications session 2026-05-07-continued Q4)
+
+- The FEAT-006 per-(container, pane-key) registration mutex
+  covers `register_agent` against other `register_agent`
+  requests addressing the same composite key, **and nothing
+  else**.
+- FEAT-004 pane reconciliation MUST NOT acquire the FEAT-006
+  per-key registration mutex; the two subsystems remain
+  decoupled.
+- Cross-subsystem ordering between a `register_agent`
+  transaction and a FEAT-004 reconciliation transaction
+  touching the same `agents` row is provided **exclusively** by
+  SQLite's `BEGIN IMMEDIATE` semantics.
+- Both transactions remain atomic — neither observes a partial
+  write from the other.
+- The transaction that commits last wins for any overlapping
+  mutable column (e.g., if `register_agent` sets `active=1` and
+  a concurrent reconciliation sets `active=0` for the same row,
+  whichever commits last is the post-state visible to
+  subsequent reads).
+- `SQLITE_BUSY` MUST surface as `internal_error` (FR-035)
+  without daemon-side retry; the operator can re-invoke the
+  CLI if needed.
+
+---
+
+## 6. JSONL audit-row contract (FR-014, Q4)
+
+Appended to the existing FEAT-001 `events.jsonl`. One row per
+successful role transition (creation OR change), 0 rows on no-op
+or failure.
+
+**Row shape**: FEAT-006 reuses the FEAT-001
+`events.writer.append_event` helper, so the on-disk record is the
+standard nested envelope — `ts` is added by the writer and
+FEAT-006 fields live under `payload`:
+
+```json
+{
+  "ts": "2026-05-07T14:30:00.123456+00:00",
+  "type": "agent_role_change",
+  "payload": {
+    "agent_id": "agt_abc123def456",
+    "prior_role": null,
+    "new_role": "slave",
+    "confirm_provided": false,
+    "socket_peer_uid": 1000
+  }
+}
+```
+
+`payload.prior_role` is `null` (JSON literal) on the initial
+creation transition (Q4), regardless of which role was assigned
+(including the default `unknown`). On every other transition
+`prior_role` is the previous string role.
+
+`payload.confirm_provided` is the **literal** boolean the
+operator passed in the `confirm` request parameter, never
+rewritten based on whether `--confirm` was *required*
+(Clarifications session 2026-05-07-continued Q5). `true` when
+`--confirm` was passed; `false` otherwise. Demotion from master
+with redundant `--confirm` logs `true`; `set-role` to a
+non-master role with redundant `--confirm` also logs `true`;
+`register-self` creation always logs `false`. Consumers derive
+"was confirm required" from `prior_role` + `new_role`.
+
+`payload.socket_peer_uid` is the host uid of the calling process,
+extracted by the daemon from the accepted AF_UNIX connection via
+`SO_PEERCRED` and passed to the agent dispatcher out-of-band so a
+request body cannot spoof it. The sentinel value `-1` indicates
+the kernel did not surface a peer credential — in production this
+would be an unexpected operational anomaly; in tests it is the
+default when DISPATCH is invoked without a real socket.
+
+`set_label` and `set_capability` MUST NOT append rows.
+
+---
+
+## 7. Forward-compat (R-018)
+
+The daemon's `status` response includes `schema_version` per
+FEAT-002. CLIs in this feature compare it to their local
+`CURRENT_SCHEMA_VERSION` and surface `schema_version_newer` if
+the daemon is ahead. The daemon also performs a defensive check
+on every method handler — if it ever receives a request shape
+it does not recognize, it returns `bad_request` rather than
+silently misinterpreting the call.
+
+---
+
+## 8. No new transport / no new auth (FR-043)
+
+FEAT-006 introduces no new transport. The five new methods reuse
+the FEAT-002 `AF_UNIX` socket, the FEAT-002 newline-delimited
+JSON framing, the FEAT-002 socket-file authorization (`0600`,
+host user only), and the FEAT-002 `SO_PEERCRED`-derived
+`socket_peer_uid`. No network listener, no in-container daemon,
+no relay, no secondary auth tier (FR-043).
diff --git a/specs/006-agent-registration/data-model.md b/specs/006-agent-registration/data-model.md
new file mode 100644
index 0000000..8bc9526
--- /dev/null
+++ b/specs/006-agent-registration/data-model.md
@@ -0,0 +1,654 @@
+# Phase 1 Data Model: Agent Registration and Role Metadata
+
+**Branch**: `006-agent-registration` | **Date**: 2026-05-07
+
+This document is the canonical reference for FEAT-006 entities and
+data flow. Anything here overrides the informal entity descriptions
+in `spec.md`. FEAT-006 introduces exactly **one** new SQLite table
+(`agents`), **three** new SQLite indexes, **zero** new files on
+disk, and **one** new JSONL event-type appended to the existing
+FEAT-001 `events.jsonl`.
+
+---
+
+## 1. Filesystem footprint
+
+FEAT-006 adds **no new files**. One existing FEAT-001 file gains a
+new event-type; the existing FEAT-001 `state.db` gains one table and
+three indexes via migration v4.
+
+| Path                                              | Read by FEAT-006 | Written by FEAT-006 |
+| ------------------------------------------------- | ---------------- | ------------------- |
+| `<state_dir>/state.db`                            | yes              | yes (new `agents` table; existing FEAT-003 / FEAT-004 tables read-only) |
+| `<state_dir>/state.db-journal` / `-wal` / `-shm`  | yes (companions) | yes (companions; mode `0600`) |
+| `<state_dir>/events.jsonl`                        | no               | yes (one new event-type `agent_role_change`; mode `0600`) |
+| `<RESOLVED_SOCKET>` (env / mounted-default / host-default) | yes (`AF_UNIX` connect for the five new socket methods) | no (the daemon writes to its own socket; FEAT-006 CLIs are read/write clients) |
+
+No SQLite reads or writes happen client-side. The daemon side is
+the single writer.
+
+---
+
+## 2. SQLite schema
+
+`CURRENT_SCHEMA_VERSION` advances from `3` (FEAT-004) to `4`
+(FEAT-006). The migration is idempotent and runs under one
+`BEGIN IMMEDIATE` transaction inside
+`schema._apply_pending_migrations` (FR-036). FEAT-001 / FEAT-002 /
+FEAT-003 / FEAT-004 tables are untouched (FR-037).
+
+### 2.1 New table `agents`
+
+```sql
+CREATE TABLE IF NOT EXISTS agents (
+    agent_id                 TEXT NOT NULL PRIMARY KEY,
+    -- Pane composite key (denormalized; mirrors panes PK; FR-002, FR-037)
+    container_id             TEXT NOT NULL,
+    tmux_socket_path         TEXT NOT NULL,
+    tmux_session_name        TEXT NOT NULL,
+    tmux_window_index        INTEGER NOT NULL,
+    tmux_pane_index          INTEGER NOT NULL,
+    tmux_pane_id             TEXT NOT NULL,
+    -- Mutable metadata
+    role                     TEXT NOT NULL CHECK(role IN ('master','slave','swarm','test-runner','shell','unknown')),
+    capability               TEXT NOT NULL CHECK(capability IN ('claude','codex','gemini','opencode','shell','test-runner','unknown')),
+    label                    TEXT NOT NULL DEFAULT '',
+    project_path             TEXT NOT NULL DEFAULT '',
+    -- Optional immutable parent linkage for swarm agents
+    parent_agent_id          TEXT,
+    -- Derived JSON column (recomputed on every role write)
+    effective_permissions    TEXT NOT NULL,
+    -- Lifecycle timestamps and active flag
+    created_at               TEXT NOT NULL,
+    last_registered_at       TEXT NOT NULL,
+    last_seen_at             TEXT,
+    active                   INTEGER NOT NULL CHECK(active IN (0, 1)),
+    -- Pane composite key uniqueness (FR-006)
+    UNIQUE (
+        container_id,
+        tmux_socket_path,
+        tmux_session_name,
+        tmux_window_index,
+        tmux_pane_index,
+        tmux_pane_id
+    )
+);
+```
+
+**Notes on column choices**:
+
+- `agent_id TEXT PRIMARY KEY` — matches FR-001's
+  `agt_<12-character-lowercase-hex>` shape; opaque string
+  identifier.
+- The pane composite key is denormalized rather than enforced by a
+  foreign key on `panes` because (a) FEAT-004 panes transition
+  active/inactive across scans and reuse pane ids; (b) FR-037
+  forbids a foreign-key constraint here. Application-layer
+  reconciliation (see §5) handles the relationship.
+- The `UNIQUE` constraint on the pane composite key tuple enforces
+  FR-006 at the storage layer: at most one agent per pane.
+- `parent_agent_id` is nullable. No `FOREIGN KEY` reference is
+  declared because the spec explicitly allows the parent record to
+  later be demoted, deleted, or marked inactive without
+  invalidating the swarm child's stored `parent_agent_id` (FR-018).
+  Application-layer validation at `register_agent` time (FR-017)
+  enforces parent existence / activeness / role at the moment of
+  swarm creation.
+- `effective_permissions TEXT NOT NULL` stores the JSON object
+  per FR-021. The pure derivation function lives in
+  `agents/permissions.py` (research R-008).
+- `last_seen_at TEXT` is nullable on creation (no FEAT-004 scan
+  has yet observed the pane after registration); the FEAT-004
+  reconciliation transaction populates it on the next scan
+  (FR-009a; research R-003).
+- `active INTEGER` mirrors the FEAT-003 / FEAT-004 boolean encoding
+  conventions (`0`/`1`).
+- `created_at`, `last_registered_at`, `last_seen_at` are ISO-8601
+  microsecond UTC strings, consistent with
+  `containers.first_seen_at` and `panes.first_seen_at`.
+
+### 2.2 Indexes
+
+```sql
+-- FR-025 deterministic ordering for list_agents (R-009)
+CREATE INDEX IF NOT EXISTS agents_active_order
+    ON agents(active DESC, container_id ASC, parent_agent_id ASC,
+              label ASC, agent_id ASC);
+
+-- FR-026 filter by parent_agent_id (swarm children of a slave)
+CREATE INDEX IF NOT EXISTS agents_parent_lookup
+    ON agents(parent_agent_id);
+
+-- FEAT-004 pane reconciliation last_seen_at UPDATE predicate (R-003)
+CREATE INDEX IF NOT EXISTS agents_pane_lookup
+    ON agents(container_id, tmux_socket_path, tmux_session_name,
+              tmux_window_index, tmux_pane_index, tmux_pane_id);
+```
+
+The `UNIQUE` constraint on the pane composite key tuple already
+implies an index covering exact-match lookups; the explicit
+`agents_pane_lookup` index is kept for clarity and to match the
+FEAT-004 pattern (`panes_active_order`, `panes_container_socket`).
+
+### 2.3 No other table changes
+
+`containers`, `container_scans`, `panes`, `pane_scans`,
+`schema_version` — unchanged byte-for-byte from FEAT-004.
+
+---
+
+## 3. Migration `v3 → v4` (FR-036)
+
+```python
+def _apply_migration_v4(conn: sqlite3.Connection) -> None:
+    """Create FEAT-006 tables. Idempotent because of IF NOT EXISTS guards."""
+    conn.execute(
+        # ... agents CREATE TABLE from §2.1 ...
+    )
+    conn.execute(
+        # ... agents_active_order CREATE INDEX from §2.2 ...
+    )
+    conn.execute(
+        # ... agents_parent_lookup CREATE INDEX from §2.2 ...
+    )
+    conn.execute(
+        # ... agents_pane_lookup CREATE INDEX from §2.2 ...
+    )
+```
+
+Registered in `_MIGRATIONS[4] = _apply_migration_v4`.
+`CURRENT_SCHEMA_VERSION` becomes `4`.
+
+The migration is invoked in two scenarios per the existing
+`_ensure_current_schema` flow:
+
+1. v3 DB → upgraded to v4 in one
+   `_apply_pending_migrations(conn, 3)` call (single transaction).
+2. v4 DB → defensive re-call of `_apply_migration_v4` from the
+   "already at current version" branch (idempotent via
+   `IF NOT EXISTS`).
+
+---
+
+## 4. In-memory entities (request / response shapes)
+
+### 4.1 `AgentRecord`
+
+The Python dataclass returned by `state/agents.py` reads:
+
+```python
+@dataclass(frozen=True)
+class AgentRecord:
+    agent_id: str
+    container_id: str
+    tmux_socket_path: str
+    tmux_session_name: str
+    tmux_window_index: int
+    tmux_pane_index: int
+    tmux_pane_id: str
+    role: str
+    capability: str
+    label: str
+    project_path: str
+    parent_agent_id: str | None
+    effective_permissions: dict[str, Any]   # parsed from JSON column
+    created_at: str
+    last_registered_at: str
+    last_seen_at: str | None
+    active: bool
+```
+
+### 4.2 `RegisterAgentRequest` (in-process; not on the wire)
+
+```python
+@dataclass
+class RegisterAgentRequest:
+    container_id: str                       # full FEAT-005 resolved id
+    pane_composite_key: PaneCompositeKey    # six-tuple from FEAT-004 lookup
+    role: str | _UNSET                      # _UNSET means "leave unchanged"
+    capability: str | _UNSET
+    label: str | _UNSET
+    project_path: str | _UNSET
+    parent_agent_id: str | None | _UNSET    # _UNSET ≠ None; None means "no parent"
+    socket_peer_uid: int                    # captured by FEAT-002 SO_PEERCRED
+```
+
+`_UNSET` is the in-process marker for "field absent in the JSON
+request envelope" per Clarifications Q1. The wire protocol
+encodes it as "key not present in the params object".
+
+### 4.3 `EffectivePermissions`
+
+```python
+EffectivePermissions = TypedDict(
+    "EffectivePermissions",
+    {
+        "can_send": bool,
+        "can_receive": bool,
+        "can_send_to_roles": list[str],
+    },
+)
+```
+
+Closed-set values per FR-021:
+
+| Role          | can_send | can_receive | can_send_to_roles |
+| ------------- | -------- | ----------- | ----------------- |
+| `master`      | `true`   | `false`     | `["slave", "swarm"]` |
+| `slave`       | `false`  | `true`      | `[]` |
+| `swarm`       | `false`  | `true`      | `[]` |
+| `test-runner` | `false`  | `false`     | `[]` |
+| `shell`       | `false`  | `false`     | `[]` |
+| `unknown`     | `false`  | `false`     | `[]` |
+
+### 4.4 `AuditRecord` (JSONL row shape)
+
+FEAT-006 reuses the FEAT-001 `events.writer.append_event` helper
+unchanged, so its on-disk shape is the standard nested envelope —
+`ts` is added by the writer and the FEAT-006 fields live under
+`payload`:
+
+```json
+{
+  "ts": "2026-05-07T14:30:00.123456+00:00",
+  "type": "agent_role_change",
+  "payload": {
+    "agent_id": "agt_abc123def456",
+    "prior_role": null,
+    "new_role": "slave",
+    "confirm_provided": false,
+    "socket_peer_uid": 1000
+  }
+}
+```
+
+Field rules:
+
+- `ts` — daemon clock, prepended by `events.writer.append_event`;
+  ISO-8601 with microseconds and explicit `+00:00` UTC offset.
+- `type` — fixed literal `"agent_role_change"` for FEAT-006.
+- `payload.prior_role` — JSON `null` on first registration of an
+  agent (creation transition); the previous string role on every
+  other transition (Clarifications Q4).
+- `payload.new_role` — closed-set string from FR-004.
+- `payload.confirm_provided` — the **literal** boolean the
+  operator passed in the `confirm` request parameter, never
+  rewritten based on whether `--confirm` was *required* by the
+  transition (Clarifications session 2026-05-07-continued Q5).
+  `true` when the CLI passed `--confirm`; `false` when it did
+  not. Demotion with redundant `--confirm` logs `true`;
+  `set-role` to a non-master role with redundant `--confirm` also
+  logs `true`; `register-self` creation always logs `false`.
+  Consumers that need "was confirm required" derive it from
+  `prior_role` + `new_role`.
+- `payload.socket_peer_uid` — host uid of the calling process, from
+  FEAT-002 `SO_PEERCRED`. The daemon extracts this from the
+  accepted AF_UNIX connection out-of-band and a request body cannot
+  spoof it; `-1` indicates the kernel did not surface a peer
+  credential (e.g. tests calling the dispatcher directly without a
+  real socket).
+
+No-op writes (set-* with the same value the agent already has;
+register-self with an unchanged role) MUST NOT append a row
+(FR-027). Failed writes MUST NOT append a row (FR-014).
+
+---
+
+## 5. Cross-table relationships and transactions
+
+### 5.1 `agents` ↔ `panes` (FR-009 / FR-009a)
+
+The `agents` row stores the FEAT-004 pane composite key
+denormalized (no FK constraint per FR-037). The relationship is
+maintained at the application layer:
+
+- **Pane reconciliation** (`discovery/pane_reconcile.py`):
+  - For every pane observed as `active=true` in a FEAT-004 scan,
+    `UPDATE agents SET last_seen_at = :scan_time WHERE
+    (container_id, tmux_socket_path, ...) = :pane_key` runs in
+    the same `BEGIN IMMEDIATE` transaction as the pane row
+    upsert. The `agents_pane_lookup` index covers this predicate.
+  - For every pane that transitions active→inactive
+    (`panes.active 1 → 0`), `UPDATE agents SET active = 0 WHERE
+    (container_id, ...) = :pane_key` runs in the same
+    transaction (FR-009).
+  - Inactive→active pane transitions do NOT auto-flip
+    `agents.active` (FR-009); explicit `register-self` is
+    required.
+
+- **Re-activation** (`agents/service.py` `register_agent`):
+  - When a `register-self` call comes from a composite key whose
+    existing agent row is `active=0`, the handler runs `UPDATE
+    agents SET active = 1, last_registered_at = :now,
+    role = :resolved_role, capability = :resolved_capability,
+    label = :resolved_label, project_path = :resolved_project,
+    effective_permissions = :recomputed WHERE agent_id = ?` in a
+    single transaction (FR-008). `created_at` and
+    `parent_agent_id` are NOT modified.
+
+### 5.2 `agents` parent linkage (FR-017)
+
+- At `register_agent --role swarm --parent <id>` time, the
+  handler runs `SELECT role, active FROM agents WHERE agent_id = ?`
+  to validate (a) parent exists; (b) `active = 1`; (c)
+  `role = 'slave'`. Failure short-circuits before any agent row
+  write (FR-017).
+- After creation, no continuing constraint is enforced — the
+  parent agent may later be demoted, deleted, or marked
+  inactive (FR-018, FR-019).
+
+### 5.3 Audit row append site
+
+- The daemon-side `service.py` calls `agents/audit.py`'s
+  `append_role_change(prior_role, new_role, ...)` *after* the
+  SQLite COMMIT and only when `prior_role != new_role`. Failed
+  COMMITs (rolled back) MUST NOT append a row (FR-014, FR-035).
+
+### 5.4 Concurrency boundary (R-005)
+
+- Per-(container_id, pane_composite_key) advisory mutex
+  (`agents/service.py::register_locks`) serializes
+  `register_agent` calls addressing the same pane (FR-038).
+- Per-`agent_id` advisory mutex
+  (`agents/service.py::agent_locks`) serializes `set_role`,
+  `set_label`, `set_capability` calls addressing the same
+  agent (FR-039).
+- Concurrent calls addressing distinct keys / agent_ids
+  proceed in parallel.
+
+---
+
+## 6. Wire format summary
+
+The five new socket methods (full details in
+`contracts/socket-api.md`):
+
+### 6.1 `register_agent` request
+
+```json
+{
+  "method": "register_agent",
+  "params": {
+    "container_id": "<full-id>",
+    "pane_composite_key": {
+      "container_id": "<full-id>",
+      "tmux_socket_path": "/tmp/...",
+      "tmux_session_name": "main",
+      "tmux_window_index": 0,
+      "tmux_pane_index": 0,
+      "tmux_pane_id": "%17"
+    },
+    "role": "slave",                 // OPTIONAL (Clarifications Q1)
+    "capability": "codex",            // OPTIONAL
+    "label": "codex-01",              // OPTIONAL
+    "project_path": "/workspace/acme",// OPTIONAL
+    "parent_agent_id": "agt_aaa..."   // OPTIONAL
+  }
+}
+```
+
+### 6.2 `register_agent` response (success)
+
+```json
+{
+  "ok": true,
+  "result": {
+    "agent_id": "agt_abc123def456",
+    "role": "slave",
+    "capability": "codex",
+    "label": "codex-01",
+    "project_path": "/workspace/acme",
+    "parent_agent_id": null,
+    "container_id": "<full-id>",
+    "container_name": "...",
+    "container_user": "...",
+    "tmux_socket_path": "/tmp/...",
+    "tmux_session_name": "main",
+    "tmux_window_index": 0,
+    "tmux_pane_index": 0,
+    "tmux_pane_id": "%17",
+    "pane_pid": 12345,
+    "cwd": "/workspace/acme",
+    "effective_permissions": {
+      "can_send": false,
+      "can_receive": true,
+      "can_send_to_roles": []
+    },
+    "created_at": "2026-05-07T14:30:00.123456+00:00",
+    "last_registered_at": "2026-05-07T14:30:00.123456+00:00",
+    "last_seen_at": null,
+    "active": true,
+    "created_or_reactivated": "created"   // "created" | "reactivated" | "updated"
+  }
+}
+```
+
+### 6.3 `list_agents` request
+
+```json
+{
+  "method": "list_agents",
+  "params": {
+    "role": "slave",                  // OPTIONAL — string or list of strings
+    "container_id": "abc123def456",   // OPTIONAL — full or 12-char short
+    "active_only": true,              // OPTIONAL — default false
+    "parent_agent_id": "agt_aaa..."   // OPTIONAL
+  }
+}
+```
+
+### 6.4 `list_agents` response
+
+```json
+{
+  "ok": true,
+  "result": {
+    "filter": {
+      "role": null,
+      "container_id": null,
+      "active_only": false,
+      "parent_agent_id": null
+    },
+    "agents": [
+      { /* full AgentRecord JSON; see §4.1 + 6.2 result */ },
+      ...
+    ]
+  }
+}
+```
+
+Order is `active DESC, container_id ASC, parent_agent_id ASC NULLS FIRST, label ASC, agent_id ASC`
+per FR-025 / R-009.
+
+### 6.5 `set_role` / `set_label` / `set_capability` request
+
+```json
+{
+  "method": "set_role",
+  "params": {
+    "agent_id": "agt_abc123def456",
+    "role": "master",
+    "confirm": true                   // OPTIONAL — required for role=master
+  }
+}
+```
+
+### 6.6 `set_*` response
+
+```json
+{
+  "ok": true,
+  "result": {
+    "agent_id": "agt_abc123def456",
+    "field": "role",
+    "prior_value": "slave",
+    "new_value": "master",
+    "effective_permissions": { ... },  // recomputed
+    "audit_appended": true             // false on no-op
+  }
+}
+```
+
+### 6.7 Error envelope
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "<closed_set_code>",
+    "message": "<actionable message>"
+  }
+}
+```
+
+Closed-set codes are listed in `contracts/socket-api.md` and in
+research R-010.
+
+---
+
+## 7. State transition diagrams
+
+### 7.1 Agent lifecycle
+
+```text
+                        register-self (first time, valid pane)
+                                       │
+                                       ▼
+            ┌────────────── (active, role=<assigned>) ───────┐
+            │                                                │
+register-self (different mutable fields)            FEAT-004 scan: pane absent
+            │                                                │
+            ▼                                                ▼
+            └────► (active, role=<merged>) ───────► (inactive, role=<unchanged>)
+                                                                │
+                                                                │ register-self again
+                                                                ▼
+                                                  (active, role=<resolved>)
+                                                  agent_id, created_at, parent_agent_id
+                                                  preserved (FR-008)
+
+set-role --role master --confirm  (when active+container active)
+            │
+            ▼
+            (active, role=master, effective_permissions updated, audit row appended)
+
+set-role --role slave / shell / test-runner / unknown
+            │
+            ▼
+            (active, role=<new>, effective_permissions updated, audit row appended)
+
+set-label / set-capability
+            │
+            ▼
+            (active, role=unchanged, label/capability updated, NO audit row)
+```
+
+### 7.2 Audit append predicate
+
+```text
+  prior_role  →  new_role   |  audit row appended?
+  ─────────────────────────  ─────────────────────
+  null        →  X (any)    |  YES  (creation; Clarifications Q4)
+  X           →  X          |  NO   (no-op; FR-027)
+  X           →  Y (X≠Y)    |  YES  (transition; FR-014)
+```
+
+### 7.3a Validation order for `set_role`
+
+```text
+  client-side                               daemon-side
+  ───────────                               ───────────
+  1. Validate --target shape (case-sensitive)
+  2. Validate --role in closed set (case-sensitive)
+  3. Reject --role swarm client-side (swarm_role_via_set_role_rejected)
+  4. Reject --role master without --confirm (master_confirm_required)
+  5. Send set_role over the socket
+                                            6. closed-set field shape (case-sensitive)
+                                            7. static reject role=swarm (swarm_role_via_set_role_rejected)
+                                            8. static reject role=master without confirm
+                                            9. acquire per-agent_id mutex (FR-039)
+                                            10. SELECT existing agent (existence pre-check)
+                                            11. if no row: agent_not_found, release mutex
+                                            12. BEGIN IMMEDIATE
+                                            13. ATOMIC RE-CHECK: re-SELECT agents.active AND
+                                                containers.active for the bound container_id;
+                                                if either == 0 → ROLLBACK + agent_inactive
+                                                (FR-011 / Clarifications session 2026-05-07-
+                                                continued Q3). SQLite BEGIN IMMEDIATE serializes
+                                                against concurrent FEAT-004 reconciliation.
+                                            14. if new role == stored role: COMMIT no-op,
+                                                no audit row (FR-027), release mutex
+                                            15. recompute effective_permissions
+                                            16. UPDATE agents SET role, effective_permissions
+                                            17. COMMIT
+                                            18. append audit row (literal confirm_provided
+                                                per Clarifications Q5)
+                                            19. release mutex
+                                            20. respond
+```
+
+### 7.3 Validation order for `register_agent`
+
+```text
+  client-side                               daemon-side
+  ───────────                               ───────────
+  1. AGENTTOWER_SOCKET resolution (FEAT-005)
+  2. CLI presence in tmux (NOT_IN_TMUX, TMUX_PANE_MALFORMED)
+  3. FEAT-005 identity (HOST_CONTEXT_UNSUPPORTED, CONTAINER_UNRESOLVED)
+  4. list_panes lookup; if absent, scan_panes(container=...) once
+  5. If pane still absent after rescan: PANE_UNKNOWN_TO_DAEMON
+  6. Compose RegisterAgentRequest (only supplied fields per Q1)
+  7. Send register_agent over the socket
+                                            8. forward-compat schema check
+                                            9. closed-set field shape
+                                            10. label/project bounds + sanitize
+                                            11. master-safety static rejection
+                                            12. acquire (container, pane_key) mutex
+                                            13. SELECT existing agent for pane
+                                            14. resolve mutable fields per Q1
+                                            15. parent immutability check (FR-018a)
+                                            16. compose post-write state
+                                            17. recompute effective_permissions
+                                            18. BEGIN IMMEDIATE
+                                            19. INSERT or UPDATE agents
+                                            20. COMMIT
+                                            21. if role changed: append audit row
+                                            22. release mutex
+                                            23. respond (ok or error)
+```
+
+---
+
+## 8. Validation rules summary
+
+**Case-sensitivity rule** (Clarifications session 2026-05-07-continued Q2): every closed-set token below is lowercase and case-sensitive; every lowercase-hex identifier is case-sensitive. Mixed-case inputs are rejected with `value_out_of_set` and MUST NOT be normalized. This rule applies uniformly to every validator, filter, lookup, and comparison site.
+
+| Field            | Validation                                                                       | On failure                       |
+| ---------------- | -------------------------------------------------------------------------------- | -------------------------------- |
+| `role`           | one of `{master, slave, swarm, test-runner, shell, unknown}` (FR-004); case-sensitive            | `value_out_of_set`               |
+| `capability`     | one of `{claude, codex, gemini, opencode, shell, test-runner, unknown}` (FR-005); case-sensitive | `value_out_of_set`               |
+| `agent_id`       | matches `^agt_[0-9a-f]{12}$` (FR-001); case-sensitive (no uppercase hex)         | `value_out_of_set`               |
+| `parent_agent_id`| matches `^agt_[0-9a-f]{12}$` AND parent exists, active, role=slave (FR-017); case-sensitive      | `parent_not_found` / `parent_inactive` / `parent_role_invalid` |
+| `container_id`   | full id or 12-char short prefix; lowercase hex; case-sensitive (FR-026)          | `value_out_of_set`               |
+| `label`          | NUL-stripped, C0-stripped, ≤ 64 chars (FR-033)                                   | `field_too_long` if oversized    |
+| `project_path`   | NUL-free, absolute, no `..` segment, ≤ 4096 chars (FR-034)                       | `project_path_invalid` / `field_too_long` |
+| filter keys      | one of `{role, container_id, active_only, parent_agent_id}` (FR-026)             | `unknown_filter`                 |
+
+---
+
+## 9. Out-of-scope reaffirmation
+
+FEAT-006 does **not** introduce:
+
+- a network listener;
+- an in-container daemon or relay;
+- prompt delivery, queue inspection, route configuration;
+- log attachment, log offset tracking, event ingestion;
+- automatic swarm inference;
+- multi-master arbitration;
+- TUI or web UI;
+- a new audit log file (uses existing `events.jsonl`);
+- a foreign-key constraint between `agents` and `panes` (FR-037);
+- any new test seam (reuses existing FEAT-003 / FEAT-004 /
+  FEAT-005 seams);
+- any new in-container subprocess shape (FR-042).
diff --git a/specs/006-agent-registration/plan.md b/specs/006-agent-registration/plan.md
new file mode 100644
index 0000000..4793ca4
--- /dev/null
+++ b/specs/006-agent-registration/plan.md
@@ -0,0 +1,489 @@
+# Implementation Plan: Agent Registration and Role Metadata
+
+**Branch**: `006-agent-registration` | **Date**: 2026-05-07 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/006-agent-registration/spec.md`
+
+## Summary
+
+Implement the AgentTower agent registry: a new SQLite table
+`agents`, five new daemon socket methods (`register_agent`,
+`list_agents`, `set_role`, `set_label`, `set_capability`), five new
+`agenttower` CLI subcommands (`register-self`, `list-agents`,
+`set-role`, `set-label`, `set-capability`), JSONL audit appendage on
+every successful role transition, and one wiring change in the
+FEAT-004 pane reconciliation path that updates each affected
+agent's `last_seen_at` in the same SQLite transaction. The feature
+turns a discovered FEAT-004 tmux pane (composite-key identified)
+into a registered agent with a stable opaque id `agt_<12-hex>`,
+binds the agent immutably to that pane composite key for life
+(FR-002, FR-006), and materializes role-derived
+`effective_permissions` for FEAT-009 / FEAT-010 to consume later
+(FR-021).
+
+The single highest-stakes property FEAT-006 introduces — that
+master privilege MUST never be granted as a side effect of a
+self-registration handshake (US2; FR-010, FR-011) — is enforced by
+splitting role assignment across two surfaces: `register-self` MUST
+reject `--role master` regardless of `--confirm` with closed-set
+code `master_via_register_self_rejected`, and `set-role
+--role master` MUST require `--confirm`, an `active=true` agent,
+and an `active=true` bench container (FR-011). Demotion from master
+is intentionally asymmetric — no `--confirm` (FR-013) — leaving
+in-flight prompt arbitration to FEAT-009 / FEAT-010. Swarm parent
+linkage is a one-time immutable binding set only by
+`register-self --role swarm --parent <id>` (FR-015..FR-019);
+`set-role --role swarm` MUST be rejected (FR-012) and re-registering
+with a different `--parent` MUST be rejected with `parent_immutable`
+(FR-018a, Clarifications 2026-05-07).
+
+Idempotent re-registration follows a strict
+"only-supplied-fields-overwrite" wire contract (Clarifications
+2026-05-07 Q1): the CLI MUST NOT transmit argparse default values,
+so unsupplied flags leave the stored row unchanged and a routine
+re-`register-self` cannot silently demote a `master` or `slave` to
+`unknown`. Re-activation of a previously inactive agent at the same
+composite key preserves `agent_id`, `created_at`, and
+`parent_agent_id` (FR-008). The default `list-agents` form is a
+locked tab-separated table with a required header row and a fixed
+nine-column schema `AGENT_ID, LABEL, ROLE, CAPABILITY, CONTAINER (12-hex short), PANE (session:window.pane), PROJECT, PARENT (12-hex short or '-'), ACTIVE` (FR-029, Clarifications 2026-05-07 Q5); future fields go to `--json` or
+a separately-introduced `--wide` flag.
+
+The on-the-wire surface adds five socket methods (FR-023) on top of
+the existing FEAT-002 newline-delimited JSON envelope and inherits
+the FEAT-002 `0600`-host-user-only socket-file authorization
+verbatim (FR-043). The SQLite migration adds exactly one table
+(`agents`) and bumps `CURRENT_SCHEMA_VERSION` from `3` (FEAT-004) to
+`4`; FEAT-001/FEAT-002/FEAT-003/FEAT-004 schemas and persisted
+shapes are untouched (FR-037, SC-010). The JSONL audit file is the
+existing FEAT-001 `events.jsonl` with one new event-type
+`agent_role_change` (FR-014, Clarifications 2026-05-07 Q4); no new
+audit log file is introduced. `last_seen_at` is owned exclusively
+by the FEAT-004 reconciliation path (FR-009a, Clarifications
+2026-05-07 Q2) — CLI calls (`list_agents`, `set_role`, `set_label`,
+`set_capability`) MUST NOT touch it. Concurrency is bounded by two
+in-process advisory mutex maps: per-`(container_id,
+pane_composite_key)` for `register_agent` (FR-038) and per-`agent_id`
+for `set_role` / `set_label` / `set_capability` (FR-039). Failure
+modes are a single closed-set error code set (FR-040, extended for
+`parent_immutable`); every failure path exits non-zero with a code
+that appears verbatim in `--json` output. The daemon stays alive
+on every failure (FR-035), and every CLI inherits the FEAT-005
+socket-resolution priority chain
+(`AGENTTOWER_SOCKET` → in-container default → host default) and the
+FEAT-002 daemon-unavailable exit-code-`2` behavior (FR-032).
+
+The feature is testable end-to-end without a real Docker daemon,
+real bench container, or real tmux server (FR-044), reusing the
+existing FEAT-003 `AGENTTOWER_TEST_DOCKER_FAKE`, FEAT-004
+`AGENTTOWER_TEST_TMUX_FAKE`, and FEAT-005
+`AGENTTOWER_TEST_PROC_ROOT` test seams unchanged. No new test seam
+is introduced.
+
+## Technical Context
+
+**Language/Version**: Python 3.11+ (inherits from FEAT-001 /
+FEAT-002 / FEAT-003 / FEAT-004 / FEAT-005; pyproject pins
+`requires-python>=3.11`). Standard library only — no third-party
+runtime dependency added.
+
+**Primary Dependencies**: Standard library only — `sqlite3`,
+`secrets` (for `agent_id` 12-hex generation), `os`, `pathlib`,
+`socket`, `argparse`, `json`, `dataclasses`, `typing`, `threading`
+(for the per-key advisory mutex maps), `re` (for label / project
+shape validation), `datetime` (for ISO-8601 timestamps consistent
+with FEAT-002/003/004). Reuses the FEAT-002 socket server
+(`socket_api/server.py`), client (`socket_api/client.py`), and error
+envelope (`socket_api/errors.py`) verbatim. Reuses FEAT-005
+in-container identity detection (`config_doctor/identity.py`,
+`config_doctor/tmux_identity.py`, `config_doctor/socket_resolve.py`,
+`config_doctor/sanitize.py`) for the CLI side of `register-self`.
+Reuses FEAT-004 pane reconciliation (`discovery/pane_reconcile.py`)
+to wire `last_seen_at` updates per FR-009a; reuses FEAT-004
+`scan_panes` codepath bounded to a single container for the
+FR-041 focused rescan. No `subprocess`, no new `tmux` invocation
+shape, no new `docker` invocation shape introduced by FEAT-006.
+
+**Storage**: One SQLite migration `v3 → v4` (FEAT-006), adding
+exactly one new table `agents` and three indexes (active/order,
+container/parent lookup, parent lookup); no other table is touched
+(FR-037). `CURRENT_SCHEMA_VERSION` advances from `3` (FEAT-004) to
+`4`. Migration is idempotent on re-open via `IF NOT EXISTS`, runs
+under a single `BEGIN IMMEDIATE` transaction inside
+`schema._apply_pending_migrations`, and refuses to serve the daemon
+on rollback (FR-036). FEAT-001 / FEAT-002 / FEAT-003 / FEAT-004
+schemas and persisted file modes (`0600`/`0700`) are unchanged
+(SC-010). The `events.jsonl` audit log is the existing FEAT-001
+file; one new event-type `agent_role_change` is appended on every
+successful role transition (FR-014) — no new audit log path is
+introduced.
+
+**Testing**: pytest (≥ 7), reusing the FEAT-002 / FEAT-003 /
+FEAT-004 / FEAT-005 daemon harness in
+`tests/integration/_daemon_helpers.py` verbatim — every FEAT-006
+integration test spins up a real host daemon under an isolated
+`$HOME` and drives the `agenttower` console script as a subprocess.
+The same three test seams (`AGENTTOWER_TEST_DOCKER_FAKE`,
+`AGENTTOWER_TEST_TMUX_FAKE`, `AGENTTOWER_TEST_PROC_ROOT`) are reused
+unchanged. Integration tests cover every US1 / US2 / US3 acceptance
+scenario plus the spec's 18 edge cases. Unit tests cover every area
+enumerated in SC-011: `agent_id` generation and uniqueness;
+role / capability closed-set validation; label / project_path
+sanitization and bounds; idempotent re-registration with
+supplied-vs-default field handling (Clarifications 2026-05-07 Q1);
+re-activation of previously inactive agents; swarm parent
+validation across all five failure paths plus the success path;
+`effective_permissions` derivation across all six roles;
+master-promotion safety across no-`--confirm`, via-`register-self`,
+via-`set-role`-swarm; JSONL audit-record shape including initial
+`prior_role: null` (Clarifications 2026-05-07 Q4); per-key
+registration mutex serialization; `parent_immutable` rejection
+atomicity (Clarifications 2026-05-07 Q3); locked default
+`list-agents` TSV column schema (Clarifications 2026-05-07 Q5).
+Integration tests cover the SC-012 closed list of end-to-end paths
+including the FR-041 focused rescan trigger, the daemon-unreachable
+CLI path, and the host-shell `host_context_unsupported` path —
+none of which require a real Docker daemon, real container, or
+real tmux server. A backwards-compatibility test
+(`test_feat006_backcompat.py`) gates SC-010 by re-running every
+FEAT-001..005 CLI command and asserting byte-identical stdout,
+stderr, exit codes, and `--json` shapes. A migration test
+(`test_schema_migration_v4.py`) covers v3-only DB upgrade,
+v4-already-current re-open, and forward-version refusal.
+
+**Target Platform**: Linux/WSL developer workstations. The daemon
+continues to run exclusively on the host (constitution principle I);
+FEAT-006 introduces zero new in-container processes — the new CLI
+commands run from inside a bench container as short-lived
+read-only thin clients, and the only daemon-side `docker exec`
+codepath FEAT-006 invokes is the FR-041 focused rescan that
+already exists in FEAT-004.
+
+**Project Type**: Single-project Python CLI + daemon. Extends
+`src/agenttower/`. Two existing modules (`cli.py`,
+`state/schema.py`) gain additive surfaces; one existing module
+(`socket_api/methods.py`) gains five new dispatch entries; one
+existing module (`socket_api/errors.py`) gains the new closed-set
+error codes; one existing module (`discovery/pane_reconcile.py`)
+gains a single side-effect that updates each touched agent's
+`last_seen_at` in the same transaction; one new package
+(`agents/`) is introduced for the registration domain logic,
+mirroring the package-per-domain split established by FEAT-003's
+`discovery/`, FEAT-004's `tmux/`, and FEAT-005's `config_doctor/`.
+
+**Performance Goals**:
+- SC-001 — A single `register-self` invocation against a healthy
+  daemon, a healthy FEAT-004 pane lookup (no rescan), a healthy
+  identity cross-check (FEAT-005), and an empty FEAT-006 `agents`
+  table completes within 500 ms wall-clock p95 end-to-end including
+  one `list_panes` round-trip (or one focused `scan_panes`
+  round-trip on a miss), one `register_agent` round-trip, and one
+  `list_agents` round-trip in the integration test harness.
+- SC-008 — A focused FR-041 per-container rescan reuses the
+  FEAT-004 `scan_panes` codepath bounded to a single container and
+  inherits the FEAT-004 5-second per-call timeout exactly.
+- `list-agents` is read-only, holds no registration mutex, and
+  returns the latest committed SQLite state with the FR-025
+  deterministic ordering. Expected steady-state usage at MVP scale
+  is single-digit-millisecond per call.
+
+**Constraints**:
+- No network listener anywhere in FEAT-006; the new socket methods
+  reuse FEAT-002's `AF_UNIX` socket-file authorization (`0600`,
+  host user only) verbatim (FR-043; constitution principle I).
+- No third-party runtime dependency; all `agent_id` generation,
+  closed-set validation, sanitization, mutex coordination, and
+  CLI/JSON rendering use Python stdlib only.
+- `agent_id` is generated from `secrets.token_hex(6)` → 12 hex chars
+  (48 bits of entropy) prefixed with `agt_`. Collisions are
+  retried via a bounded loop (max 5 attempts) under the
+  per-(container_id, pane_composite_key) registration mutex; an
+  exhausted retry budget surfaces as `internal_error` and the
+  daemon stays alive (FR-035).
+- Mutable-field wire encoding: every mutable field
+  (`role`, `capability`, `label`, `project_path`, `parent_agent_id`)
+  in the `register_agent` request envelope MUST be either present
+  with a value or absent (the JSON key MUST NOT exist when the user
+  did not pass the flag). Argparse-style defaults
+  (`--role unknown`, `--capability unknown`, `--label ""`,
+  `--project ""`) MUST NOT be transmitted on idempotent
+  re-registration; they are applied only on first registration of
+  a brand-new pane. The CLI MUST distinguish "flag omitted" from
+  "flag explicitly set to default value" via argparse `SUPPRESS`
+  defaults plus an explicit per-flag sentinel (Clarifications
+  2026-05-07 Q1).
+- Master safety boundary: `register-self` MUST reject `--role master`
+  regardless of `--confirm` (FR-010); `set-role --role master`
+  MUST require `--confirm` AND target an active agent in an active
+  container (FR-011); `set-role --role swarm` MUST be rejected
+  (FR-012); demotion from master MUST NOT require `--confirm`
+  (FR-013).
+- Master-promotion atomic re-check (FR-011 / Clarifications
+  session 2026-05-07-continued Q3): the `set-role --role master --confirm`
+  active-state check MUST be performed *inside* the
+  `BEGIN IMMEDIATE` write transaction (re-SELECT `agents.active`
+  AND `containers.active`; ROLLBACK + `agent_inactive` on either
+  flag being `0`), never read-then-write outside the transaction.
+  SQLite `BEGIN IMMEDIATE` serializes the re-check against any
+  concurrent FEAT-004 reconciliation transaction so the
+  validate-then-write race window is closed at the SQLite level.
+- Swarm parent immutability: `register-self` re-run with `--parent`
+  matching the stored `parent_agent_id` is a no-op success;
+  `register-self` re-run with a different `--parent` MUST be
+  rejected with `parent_immutable` and MUST NOT update any other
+  mutable field even if other fields were also supplied (FR-018a).
+- `last_seen_at` ownership: every FEAT-004 pane scan that observes
+  the bound pane as active updates `last_seen_at` in the same
+  SQLite transaction as the pane reconciliation (FR-009a).
+  CLI calls MUST NOT touch `last_seen_at` from any FEAT-006
+  codepath.
+- `effective_permissions` derivation: pure function of `role` only,
+  recomputed on every write that mutates `role`; materialized as a
+  JSON column with closed-set fields `{can_send: bool, can_receive: bool, can_send_to_roles: [<role>...]}`
+  (FR-021).
+- JSONL audit shape: every successful role transition appends
+  exactly one row with `event_type=agent_role_change`, `agent_id`,
+  `prior_role` (JSON literal `null` on first registration),
+  `new_role`, `confirm_provided`, `socket_peer_uid`, and the daemon
+  clock timestamp (FR-014; Clarifications 2026-05-07 Q4). No-op
+  writes (re-registration with unchanged role; `set-*` calls with
+  the same value the agent already has) MUST NOT append a new row
+  (FR-027).
+- Default `list-agents` form is a tab-separated table with a
+  required header row and a fixed nine-column schema (FR-029;
+  Clarifications 2026-05-07 Q5). Future fields go to `--json` or a
+  separately-introduced `--wide` flag — never the default form.
+  Snapshot tests lock this contract.
+- Free-text bounds (FR-033): `label ≤ 64 chars`, `project_path ≤
+  4096 chars`. Oversized values are rejected with `field_too_long`,
+  never silently truncated.
+- `project_path` shape (FR-034): non-empty absolute path starting
+  with `/`, NUL-free, no `..` segment after normalization.
+  Existence on the host filesystem is NOT checked.
+- Per-(container_id, pane_composite_key) advisory mutex serializes
+  concurrent `register_agent` requests addressing the same pane
+  (FR-038); per-`agent_id` advisory mutex serializes
+  `set_role` / `set_label` / `set_capability` (FR-039). Mutex maps
+  live in-process and are released on transaction commit OR
+  rollback. Concurrent calls addressing different keys / different
+  agent_ids MUST proceed in parallel.
+- Cross-subsystem concurrency (FR-038 / Clarifications session
+  2026-05-07-continued Q4): the FEAT-006 per-key registration
+  mutex covers `register_agent` against other `register_agent`
+  calls only; FEAT-004 pane reconciliation MUST NOT acquire it.
+  Cross-subsystem ordering between a `register_agent` transaction
+  and a FEAT-004 reconciliation transaction touching the same
+  `agents` row is provided **exclusively** by SQLite's
+  `BEGIN IMMEDIATE` semantics — both transactions are atomic, the
+  last committed transaction wins for overlapping mutable
+  columns, and `SQLITE_BUSY` surfaces as `internal_error` without
+  daemon-side retry.
+- Single-transaction writes: every successful registration or
+  set-* call commits the agent-row write and the
+  `effective_permissions` recomputation in one SQLite transaction;
+  rollback on failure leaves no audit row and no agent-row mutation
+  (FR-035).
+- Schema version forward-compat: every new CLI surfaces
+  `schema_version_newer` and refuses the call without corrupting
+  state, inheriting the FEAT-005 forward-compat policy verbatim
+  (edge cases).
+- All untrusted CLI inputs (`label`, `project_path`, `--parent`,
+  `--target`, `--container` filter, `--role` filter) inherit
+  FEAT-004 sanitization (NUL-stripped, C0-control-stripped) and the
+  FR-033 bounds.
+- Case-sensitivity (Clarifications session 2026-05-07-continued
+  Q2): every closed-set token (`role`, `capability`) is lowercase
+  and case-sensitive; every lowercase-hex identifier (`agent_id`,
+  `parent_agent_id`, `container_id`) is case-sensitive. Mixed-case
+  inputs (`Slave`, `MASTER`, `agt_ABC...`, `ABC123def456`) MUST
+  be rejected with `value_out_of_set` and MUST NOT be normalized.
+  Every validator, filter, lookup, and comparison site treats
+  case differences as distinct values.
+- The CLIs MUST NOT send any input into any tmux pane, MUST NOT
+  call `docker exec` for any purpose other than the FR-041 focused
+  rescan invoked daemon-side, MUST NOT modify any pane log, and
+  MUST NOT install any tmux hook (FR-042). FEAT-006 is registry-only.
+
+**Scale/Scope**: One host user, one daemon, one new SQLite table
+(`agents`), three new SQLite indexes, one new JSONL event-type
+(`agent_role_change`), five new socket methods, five new CLI
+subcommands, one new closed-set error-code addition
+(`parent_immutable`), one new domain package (`agents/`). Expected
+steady-state usage: tens of registered agents per host at MVP
+scale, sub-millisecond SQLite reads on indexed lookups, single-digit
+KB JSON payloads on `list_agents`. The advisory mutex maps grow
+with the number of distinct pane composite keys / agent_ids
+observed per daemon lifetime; entries are not evicted (memory
+overhead is bounded by MVP agent count).
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle                     | Status | Evidence |
+| ----------------------------- | ------ | -------- |
+| I. Local-First Host Control   | PASS   | The agent registry is owned exclusively by the host daemon; the new socket methods reuse FEAT-002's `AF_UNIX` socket-file authorization (`0600`, host user only) verbatim (FR-023, FR-043). FR-043 forbids any new network listener, in-container daemon, or relay; FEAT-006's tests assert the same harness invariant FEAT-002..005 do (no AF_INET/AF_INET6). Durable state stays under the host's `opensoft/agenttower` namespace; FR-042 forbids any new in-container disk write beyond the existing FEAT-004 / FEAT-005 read-only inspections. |
+| II. Container-First MVP       | PASS   | This is the registration slice that turns FEAT-003 / FEAT-004 / FEAT-005 detection into a durable agent identity bound to a bench container's tmux pane composite key (FR-002). Host-only `register-self` calls are explicitly refused with `host_context_unsupported` (edge cases; FR-040). All new CLIs inherit FEAT-005's in-container socket-resolution chain (FR-032). |
+| III. Safe Terminal Input      | PASS   | FR-042 forbids any input delivery, prompt queuing, log capture, tmux-hook installation, or `docker exec` invocation outside the FR-041 daemon-side focused rescan. The master safety boundary is the architecture-mandated split: `register-self` cannot grant master (FR-010); `set-role --role master` requires `--confirm`, an active agent, and an active container (FR-011); `set-role --role swarm` is rejected (FR-012). Demotion is asymmetric and intentionally simpler (FR-013) — in-flight prompt arbitration is FEAT-009 / FEAT-010's concern. The "no silent privilege escalation/de-escalation" rule is reinforced by Clarifications 2026-05-07 Q1: argparse defaults are NOT transmitted on idempotent re-registration, so a routine re-run cannot silently demote a master. All untrusted free-text fields (`label`, `project_path`) are sanitized + bounded per FR-033 / FR-034 and never interpolated into a shell string. |
+| IV. Observable and Scriptable | PASS   | Every new CLI ships dual output: a locked human-readable form (TSV with header for `list-agents`, FR-029) and a `--json` form with stable closed-set error codes (FR-040). Every successful role transition appends exactly one JSONL audit row with `agent_id`, `prior_role`, `new_role`, `confirm_provided`, `socket_peer_uid`, and timestamp (FR-014; Clarifications 2026-05-07 Q4 — including initial creation with `prior_role: null`); the audit log is the existing FEAT-001 `events.jsonl`, no new file (Assumptions). `list-agents --json` exposes every immutable field (FR-002) and mutable field (FR-003) verbatim plus `effective_permissions` (FR-022). |
+| V. Conservative Automation    | PASS   | FR-018 makes `parent_agent_id` immutable for life; re-parenting is deferred. FR-020 forbids nested swarms (slave → swarm only). FR-043 forbids prompt delivery, route configuration, log attachment, event ingestion, automatic swarm inference, multi-master arbitration, TUI, and web UI. The registry stores derived `effective_permissions` (FR-021) but FEAT-006 does NOT consume them for any decision (FR-022) — downstream features read them. Master promotion requires explicit human confirmation (FR-011) and never happens as a side effect (FR-010). Demotion is asymmetric (FR-013) by design — FEAT-006 does not pre-empt FEAT-009 / FEAT-010's design choices about in-flight prompts. |
+
+| Technical Constraint                                                          | Status | Evidence |
+| ----------------------------------------------------------------------------- | ------ | -------- |
+| Primary language Python                                                       | PASS   | Python 3.11+, stdlib only. No new runtime dependency. |
+| Console entrypoints `agenttower` & `agenttowerd`                              | PASS   | Extends `agenttower` with five new subcommands (`register-self`, `list-agents`, `set-role`, `set-label`, `set-capability`). `agenttowerd run` is unchanged. |
+| Files under `~/.config` / `~/.local/state` / `~/.cache` `opensoft/agenttower` | PASS   | The new `agents` SQLite table lives in the existing `state.db`. JSONL audit rows are appended to the existing FEAT-001 `events.jsonl`. No new path is introduced. |
+| Docker default `name_contains = ["bench"]`, host `docker exec -u "$USER"`     | PASS (vacuously) | FEAT-006 calls neither `docker` nor `docker exec` directly. The FR-041 focused rescan reuses the FEAT-004 `scan_panes` codepath verbatim (no new `docker exec` shape). |
+| CLI: human-readable defaults + structured output where it helps               | PASS   | Every new CLI ships a stable, scriptable default (`register-self` prints the assigned `agent_id` and resolved fields; `list-agents` is locked TSV with header; `set-*` print prior/new value pairs) and a `--json` form (FR-028, FR-029, FR-030, FR-031). |
+
+| Development Workflow                                                          | Status | Evidence |
+| ----------------------------------------------------------------------------- | ------ | -------- |
+| Build in `docs/mvp-feature-sequence.md` order                                 | PASS   | This is FEAT-006, immediately after FEAT-005 (`005-container-thin-client`). |
+| Each feature CLI-testable                                                     | PASS   | Every US1 / US2 / US3 acceptance scenario maps to at least one named integration test invoking the real `agenttower` console script under the FEAT-002 daemon harness; see `tests/integration/test_cli_register_self.py`, `test_cli_register_idempotent.py`, `test_cli_register_swarm.py`, `test_cli_list_agents.py`, `test_cli_set_role_master.py`, `test_cli_set_role_swarm_rejected.py`, `test_cli_set_label_capability.py`, plus the closed-set edge-case suite (`test_cli_register_focused_rescan.py`, `test_cli_register_host_context.py`, `test_cli_register_pane_unknown.py`, `test_cli_register_no_daemon.py`, `test_cli_register_concurrent.py`, `test_cli_last_seen_at_updates.py`). |
+| Tests proportional to risk; broader for daemon state, sockets, Docker/tmux adapters, permissions, and input delivery | PASS   | Master-promotion safety has dedicated unit and integration coverage (no-`--confirm`, via `register-self`, via `set-role` swarm). Swarm parent validation has unit coverage for all five failure paths (`parent_not_found`, `parent_inactive`, `parent_role_invalid`, `parent_role_mismatch`, `swarm_parent_required`) plus the success path. JSON contract stability is locked by `test_register_supplied_vs_default.py`, `test_list_agents_tsv_render.py`, and the `test_feat006_backcompat.py` snapshot. The schema migration has dedicated `test_schema_migration_v4.py` coverage including v3-only upgrade, v4-already-current re-open, and forward-version refusal. Concurrency is covered by `test_cli_register_concurrent.py` and the unit-level `test_register_mutex.py`. |
+| Preserve existing docs and NotebookLM sync mappings                           | PASS   | This feature does not edit existing Markdown under `docs/`. New artifacts live entirely under `specs/006-agent-registration/`. |
+| No TUI, web UI, or relay before the core slices work                          | PASS   | None introduced here. FEAT-006 is the registration slice on top of the four core slices (FEAT-002 daemon, FEAT-003 container discovery, FEAT-004 pane discovery, FEAT-005 thin client). |
+| Decide explicitly whether `/speckit.checklist <topic>` is needed before tasks | DECISION | A `security` checklist is recommended before `/speckit.tasks` because FEAT-006 introduces the master safety boundary — the highest-stakes operation in the MVP — and a new privilege-derivation path (`effective_permissions`). The `--confirm` gate, the rejection of master via `register-self`, the rejection of swarm via `set-role`, the immutability of `parent_agent_id`, the supplied-vs-default wire contract that prevents silent demotion, and the audit-log shape (initial `prior_role: null`, no audit on no-op) are all worth a pre-tasks gate. A second `cli-contract` checklist is optional but worth considering because the FR-029 default `list-agents` TSV column schema and the FR-040 closed-set error codes are both new public surfaces that downstream features will consume. |
+
+**Result**: Gates pass. No `Complexity Tracking` entries required.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/006-agent-registration/
+├── plan.md                        # This file (/speckit.plan output)
+├── research.md                    # Phase 0 output: resolved decisions
+├── data-model.md                  # Phase 1 output: agents table + entity shapes + JSONL schema
+├── quickstart.md                  # Phase 1 output: end-to-end CLI walkthrough
+├── contracts/
+│   ├── cli.md                     # User-facing CLI contracts (C-CLI-601 register-self; C-CLI-602 list-agents; C-CLI-603 set-role; C-CLI-604 set-label; C-CLI-605 set-capability)
+│   └── socket-api.md              # Socket-level contracts for the five new methods (register_agent, list_agents, set_role, set_label, set_capability) including request envelopes, response envelopes, error codes
+├── checklists/                    # /speckit.checklist outputs (security recommended)
+└── tasks.md                       # /speckit.tasks output (NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+
+Only files actually touched by FEAT-006 are listed. FEAT-001 /
+FEAT-002 / FEAT-003 / FEAT-004 / FEAT-005 files remain unchanged
+unless an explicit "EXTENDS" note appears.
+
+```text
+src/agenttower/
+├── cli.py                                # EXTENDS: add subparsers `register-self`, `list-agents`, `set-role`, `set-label`, `set-capability`; reuse FEAT-005 socket-resolution chain; argparse uses `argparse.SUPPRESS` default sentinel for every mutable flag so omitted flags are absent in the dict and not transmitted (FR-007, Clarifications Q1); `--json` flag on every new subcommand
+├── state/
+│   ├── schema.py                         # EXTENDS: bump CURRENT_SCHEMA_VERSION 3 → 4; add `_apply_migration_v4`; register migration in `_MIGRATIONS`; v3-only DBs upgrade in one BEGIN IMMEDIATE transaction (FR-036)
+│   └── agents.py                         # NEW: SQLite reads/writes for the `agents` table; pure data-access layer mirroring `state/containers.py` and `state/panes.py`; closed-set INSERT/UPDATE/SELECT helpers; deterministic ordering helper for FR-025
+├── agents/                               # NEW package: agent registration domain logic
+│   ├── __init__.py                       # NEW: package marker; re-exports AgentRecord, RegisterAgentRequest, AgentService, EffectivePermissions
+│   ├── identifiers.py                    # NEW: agent_id generation `agt_<12-hex>`; bounded retry-on-collision under registration mutex
+│   ├── permissions.py                    # NEW: pure FR-021 derivation function `effective_permissions(role) -> dict` for all six roles; serialized to JSON for the SQLite column
+│   ├── validation.py                     # NEW: closed-set validators (role, capability); label/project sanitization + bounds (FR-033, FR-034); --parent shape check; closed-set error code raising
+│   ├── service.py                        # NEW: top-level orchestrator for register_agent / list_agents / set_role / set_label / set_capability daemon-side; consumes the per-(container_id, pane_composite_key) and per-agent_id mutex registries from `mutex.py` (FR-038, FR-039); single-transaction commit; rollback on failure; master-promotion atomic re-check inside BEGIN IMMEDIATE (FR-011 / Clarifications session 2026-05-07-continued Q3)
+│   ├── mutex.py                          # NEW: per-key advisory mutex registries `RegisterLockMap` (keyed by pane composite key, FR-038) and `AgentLockMap` (keyed by agent_id, FR-039); thread-safe fetch-or-create under guard lock (research R-005); FEAT-004 reconciliation does NOT acquire these maps (cross-subsystem ordering via SQLite BEGIN IMMEDIATE; Clarifications session 2026-05-07-continued Q4)
+│   ├── audit.py                          # NEW: JSONL audit-row writer for `event_type=agent_role_change` appended to events.jsonl; includes `prior_role: null` for initial creation (Clarifications Q4); literal `confirm_provided` value (Clarifications session 2026-05-07-continued Q5); skip on no-op (FR-027)
+│   └── client_resolve.py                 # NEW: client-side resolver for `register-self`; reuses FEAT-005 identity + tmux-self-identity; calls `list_panes` then triggers focused rescan via `scan_panes(container=...)` on miss (FR-041); maps every failure to a closed-set error code
+├── socket_api/
+│   ├── methods.py                        # EXTENDS: add five new dispatch entries (`register_agent`, `list_agents`, `set_role`, `set_label`, `set_capability`); each handler routes to `agents/service.py`; existing entries unchanged byte-for-byte
+│   ├── errors.py                         # EXTENDS: add new closed-set codes (`HOST_CONTEXT_UNSUPPORTED`, `CONTAINER_UNRESOLVED`, `PANE_UNKNOWN_TO_DAEMON`, `AGENT_NOT_FOUND`, `AGENT_INACTIVE`, `PARENT_NOT_FOUND`, `PARENT_INACTIVE`, `PARENT_ROLE_INVALID`, `PARENT_ROLE_MISMATCH`, `PARENT_IMMUTABLE`, `SWARM_PARENT_REQUIRED`, `SWARM_ROLE_VIA_SET_ROLE_REJECTED`, `MASTER_VIA_REGISTER_SELF_REJECTED`, `MASTER_CONFIRM_REQUIRED`, `VALUE_OUT_OF_SET`, `FIELD_TOO_LONG`, `PROJECT_PATH_INVALID`, `UNKNOWN_FILTER`, `NOT_IN_TMUX`, `TMUX_PANE_MALFORMED`, `SCHEMA_VERSION_NEWER`); extend `CLOSED_CODE_SET` accordingly; existing codes unchanged
+│   └── client.py                         # EXTENDS (additive only): add typed wrappers `register_agent()`, `list_agents()`, `set_role()`, `set_label()`, `set_capability()`; reuse existing connect / framing logic
+└── discovery/
+    └── pane_reconcile.py                 # EXTENDS: every pane reconciliation transaction that observes a pane-composite-key as `active=true` MUST also UPDATE the bound agent's `last_seen_at` (FR-009a; Clarifications Q2); transition active→inactive cascades to the agent's `active=false` (FR-009); transition inactive→active does NOT auto-flip the agent's `active` flag
+
+tests/
+├── unit/
+│   ├── test_agent_id_generation.py              # NEW: FR-001 — `agt_<12-hex>` shape; collision retry under mutex; entropy bound
+│   ├── test_role_capability_validation.py       # NEW: FR-004 / FR-005 — closed-set validators; out-of-set rejection with `value_out_of_set`
+│   ├── test_label_project_sanitize.py           # NEW: FR-033 / FR-034 — NUL strip, control-byte strip, label ≤ 64 chars, project_path ≤ 4096 chars, absolute-path requirement, no `..` segment, no NUL byte
+│   ├── test_effective_permissions.py            # NEW: FR-021 — derivation across all six roles (master, slave, swarm, test-runner, shell, unknown); JSON column shape stability
+│   ├── test_register_idempotency.py             # NEW: FR-007 — re-registration with same composite key returns same agent_id; mutable fields supplied replace stored; mutable fields not supplied left unchanged; created_at / parent_agent_id / pane composite key never change; last_registered_at updates
+│   ├── test_register_supplied_vs_default.py     # NEW: Clarifications Q1 — argparse defaults NOT transmitted on re-registration; idempotent re-runs preserve role/capability/label/project; explicit `--role unknown` overwrites whereas omitted `--role` does not
+│   ├── test_register_reactivation.py            # NEW: FR-008 — re-`register-self` on a previously inactive agent at the same composite key re-activates it preserving agent_id, created_at, parent_agent_id; mutable-field semantics from FR-007 still apply
+│   ├── test_swarm_parent_validation.py          # NEW: FR-015 / FR-016 / FR-017 / FR-019 / FR-020 — all five failure paths (parent_not_found, parent_inactive, parent_role_invalid, parent_role_mismatch, swarm_parent_required) plus the success path; nested swarm rejection
+│   ├── test_parent_immutable.py                 # NEW: Clarifications Q3 — re-registration with same `--parent` is no-op success; re-registration with different `--parent` rejected `parent_immutable`; on rejection no mutable field updated; transaction rolled back; no audit row appended
+│   ├── test_master_promotion_safety.py          # NEW: FR-010 / FR-011 / FR-012 / FR-013 — register-self rejects --role master regardless of --confirm; set-role --role master without --confirm rejected; set-role --role swarm rejected; demotion does not require --confirm
+│   ├── test_audit_record_shape.py               # NEW: FR-014 — exactly one JSONL row per successful role transition; agent_id, prior_role, new_role, confirm_provided, socket_peer_uid, timestamp; failures append no row
+│   ├── test_initial_audit_record.py             # NEW: Clarifications Q4 — first successful register-self appends one row with prior_role: null regardless of role (incl. default unknown); idempotent re-registration with unchanged role appends no new row
+│   ├── test_register_mutex.py                   # NEW: FR-038 / FR-039 — concurrent register_agent against same composite key serialized; concurrent against different keys parallel; per-agent_id mutex on set-* serialized
+│   ├── test_list_agents_filters.py              # NEW: FR-026 — role / container_id / active_only / parent_agent_id filters; AND composition; unknown filter key rejected `unknown_filter`
+│   ├── test_list_agents_tsv_render.py           # NEW: Clarifications Q5 — locked nine-column header row; TSV separator; CONTAINER 12-hex short; PARENT 12-hex short or `-`; PANE session:window.pane; ACTIVE true/false; future-field exclusion enforced by snapshot test
+│   ├── test_list_agents_ordering.py             # NEW: FR-025 — deterministic order `active DESC, container_id ASC, parent_agent_id NULLS FIRST, label ASC, agent_id ASC`
+│   ├── test_register_idempotent_audit.py        # NEW: FR-027 — set_role / set_label / set_capability with the same value the agent has succeed without error and append no new audit row
+│   ├── test_register_transaction.py             # NEW: FR-035 — register / set-* failure rolls back agent-row write AND skips audit append; daemon stays alive; internal_error returned
+│   ├── test_schema_v4_migration_unit.py         # NEW: FR-036 / FR-037 — v3 → v4 idempotent; `agents` table + indexes created on otherwise-unchanged FEAT-005 DB; FEAT-001..004 tables untouched
+│   ├── test_pane_reconcile_last_seen.py         # NEW: FR-009a / Clarifications Q2 — every FEAT-004 pane reconciliation transaction that observes pane active updates `last_seen_at`; transition active→inactive cascades agent.active=false in the same transaction; inactive→active does NOT auto-flip; CLI calls do not touch last_seen_at
+│   ├── test_register_value_out_of_set.py        # NEW: FR-004 / FR-005 — out-of-set role/capability/parent rejected with `value_out_of_set`; actionable message lists valid values
+│   ├── test_register_field_too_long.py          # NEW: FR-033 — over-bound label/project_path rejected with `field_too_long` rather than truncated
+│   ├── test_register_project_path_invalid.py    # NEW: FR-034 — relative path / `..` segment / NUL byte / empty rejected with `project_path_invalid`
+│   ├── test_socket_api_register_agent.py        # NEW: FR-024 — daemon does NOT re-derive container identity from socket peer; CLI is responsible; daemon enforces shape
+│   ├── test_socket_api_list_agents_filters.py   # NEW: FR-026 — filter envelope shape; AND semantics; unknown_filter rejection
+│   └── test_set_role_swarm_rejection.py         # NEW: FR-012 — set-role --role swarm rejected `swarm_role_via_set_role_rejected`; documented re-registration path described in actionable message
+└── integration/
+    ├── test_cli_register_self.py                       # NEW: US1 AS1 / SC-001 — register-self from simulated in-container env returns 0, prints agent_id, persists exactly one row
+    ├── test_cli_register_idempotent.py                 # NEW: US1 AS2 / AS3 / SC-002 — re-registration from same pane returns same agent_id; mutable-field updates persist; created_at unchanged; last_registered_at updates
+    ├── test_cli_register_swarm.py                      # NEW: US3 AS1 / SC-005 — register-self --role swarm --parent <id> succeeds; list-agents shows parent linkage
+    ├── test_cli_register_swarm_failure_paths.py        # NEW: US3 AS2..AS6 / SC-006 — every swarm parent failure path (parent_not_found, parent_inactive, parent_role_invalid, parent_role_mismatch, swarm_parent_required, parent_role_mismatch when --parent without --role swarm)
+    ├── test_cli_register_master_rejected.py            # NEW: US2 AS3 / SC-003 — register-self --role master --confirm rejected `master_via_register_self_rejected`; no agent row created; no audit row appended
+    ├── test_cli_set_role_master.py                     # NEW: US2 AS1 — set-role --role master --confirm promotes; effective_permissions.can_send_to_roles=["slave","swarm"]; one audit row appended
+    ├── test_cli_set_role_master_no_confirm.py          # NEW: US2 AS2 / SC-004 — set-role --role master without --confirm rejected `master_confirm_required`; role unchanged
+    ├── test_cli_set_role_swarm_rejected.py             # NEW: FR-012 — set-role --role swarm rejected; actionable message points to register-self
+    ├── test_cli_set_label_capability.py                # NEW: US2 AS4 / AS5 — set-label / set-capability succeed; role and effective_permissions unchanged
+    ├── test_cli_list_agents.py                         # NEW: US1 AS4 / SC-007 — list-agents and list-agents --json across multi-agent state; locked TSV column schema; every JSON field present per FR-002 / FR-003 / FR-021
+    ├── test_cli_list_agents_filters.py                 # NEW: FR-026 — --role / --container / --active-only / --parent filters compose with AND
+    ├── test_cli_register_focused_rescan.py             # NEW: SC-008 / FR-041 — pane composite key not yet known triggers exactly one focused FEAT-004 rescan scoped to the caller's container; after rescan pane appears, registration succeeds; otherwise refuses pane_unknown_to_daemon
+    ├── test_cli_register_host_context.py               # NEW: SC-009 — host shell with FEAT-005 reporting host_context exits non-zero `host_context_unsupported`
+    ├── test_cli_register_pane_unknown.py               # NEW: edge cases — pane composite key absent after focused rescan refused with `pane_unknown_to_daemon`
+    ├── test_cli_register_no_daemon.py                  # NEW: SC-009 — daemon down → exit code 2 with FEAT-002 daemon-unavailable message; no daemon implicit start
+    ├── test_cli_register_concurrent.py                 # NEW: edge cases — two concurrent register-self from same pane converge on same agent_id; concurrent from different panes proceed in parallel
+    ├── test_cli_last_seen_at_updates.py                # NEW: FR-009a — FEAT-004 pane scan updates last_seen_at on bound agents; CLI calls (list-agents, set-role, set-label, set-capability) leave last_seen_at unchanged
+    ├── test_cli_register_inactive_agent_then_reappears.py # NEW: FR-008 — pane disappears, agent.active=false; pane reappears at same composite key, register-self re-activates preserving agent_id / created_at / parent_agent_id
+    ├── test_cli_register_supplied_vs_default.py        # NEW: Clarifications Q1 — re-registration without flags preserves stored role/capability/label/project; explicit --role unknown does overwrite
+    ├── test_cli_register_parent_immutable.py           # NEW: Clarifications Q3 — re-registration with same --parent is no-op success; with different --parent rejected `parent_immutable`; no mutable field updated
+    ├── test_cli_register_initial_audit.py              # NEW: Clarifications Q4 — first register-self with default --role unknown writes one audit row with prior_role: null; idempotent re-run with unchanged role writes no new row
+    ├── test_cli_register_value_out_of_set.py           # NEW: edge cases — invalid role/capability/parent rejected `value_out_of_set` with valid values listed
+    ├── test_cli_register_field_too_long.py             # NEW: FR-033 — oversized label / project_path rejected `field_too_long`
+    ├── test_cli_register_project_path_invalid.py       # NEW: FR-034 — relative / `..` / NUL byte / empty rejected `project_path_invalid`
+    ├── test_cli_register_concurrent_different_panes.py # NEW: FR-038 — concurrent register-self from different composite keys parallelize; both succeed; distinct agent_ids
+    ├── test_cli_set_role_inactive_target.py            # NEW: edge cases — set-role on agent with active=false rejected `agent_inactive`; set-role --role master on agent in inactive container rejected `agent_inactive`
+    ├── test_cli_set_role_unknown_target.py             # NEW: edge cases — set-role on unknown agent_id rejected `agent_not_found`
+    ├── test_cli_register_schema_newer.py               # NEW: edge cases — daemon schema_version > CLI build → all five CLIs surface `schema_version_newer` and refuse
+    ├── test_schema_migration_v4.py                     # NEW: SC-010 — v3-only DB upgrades to v4 cleanly; v4-already-current re-open is a no-op; forward-version refusal preserved; FEAT-001..004 tables untouched
+    ├── test_feat006_backcompat.py                      # NEW: SC-010 — every FEAT-001..005 CLI command produces byte-identical output; no existing socket method gains a code or shape; existing tests still pass
+    └── test_feat006_no_real_docker_or_tmux.py          # NEW: SC-012 — parallel to test_feat005_no_real_container.py; asserts no real docker / tmux / network call during the FEAT-006 test session beyond the FR-041 focused rescan that goes through the existing FEAT-004 fakes
+```
+
+**Structure Decision**: Keep the FEAT-001..005 single-project
+layout. The new `agents/` package mirrors the package-per-domain
+split established by FEAT-003's `discovery/` and `docker/`,
+FEAT-004's `tmux/` and `discovery/pane_reconcile.py`, and
+FEAT-005's `config_doctor/`: `service.py` orchestrates,
+`identifiers.py`, `permissions.py`, `validation.py`, `audit.py`,
+and `client_resolve.py` keep each FR's logic in one testable unit.
+The SQLite layer mirrors FEAT-003 / FEAT-004's split between
+`state/schema.py` (migrations) and `state/<table>.py` (typed
+read/write helpers) by adding `state/agents.py`. The dispatch
+table in `socket_api/methods.py` gains exactly five new entries
+(`register_agent`, `list_agents`, `set_role`, `set_label`,
+`set_capability`); existing entries (`ping`, `status`, `shutdown`,
+`scan_containers`, `list_containers`, `scan_panes`, `list_panes`)
+are unchanged byte-for-byte. `socket_api/errors.py` adds the
+FEAT-006 closed-set codes; existing codes are unchanged.
+`socket_api/client.py` gets five new typed wrappers; the framing /
+connect path is unchanged. `discovery/pane_reconcile.py` gains the
+single side-effect of updating `last_seen_at` on every observed
+agent in the same SQLite transaction (FR-009a). `cli.py` gets
+five new subparsers, each using `argparse.SUPPRESS` defaults so
+omitted flags are *absent* from the parsed dict and not
+transmitted on the wire (Clarifications Q1). `state/schema.py`
+gains exactly one new migration function `_apply_migration_v4`,
+registered in `_MIGRATIONS[4]`, and `CURRENT_SCHEMA_VERSION` moves
+from `3` to `4`. FR-043's no-new-listener / no-new-relay clause is
+enforced by the absence of any edit to
+`socket_api/server.py`, `socket_api/lifecycle.py`, or
+`daemon.py` beyond optional plumbing of the new method handlers
+into the dispatch context.
+
+## Complexity Tracking
+
+> No constitutional violations to justify. This section is intentionally empty.
diff --git a/specs/006-agent-registration/quickstart.md b/specs/006-agent-registration/quickstart.md
new file mode 100644
index 0000000..7b7bd52
--- /dev/null
+++ b/specs/006-agent-registration/quickstart.md
@@ -0,0 +1,391 @@
+# Quickstart: Agent Registration and Role Metadata
+
+**Branch**: `006-agent-registration` | **Date**: 2026-05-07
+
+This walkthrough exercises the FEAT-006 surface end-to-end against
+a host daemon and a single bench container. It complements
+`spec.md` (US1, US2, US3 acceptance scenarios) and
+`contracts/cli.md`. Every command shown here is a real
+`agenttower` console-script invocation; no real Docker daemon or
+real tmux server is required for the test-harness equivalent (see
+§6).
+
+---
+
+## 0. Prerequisites
+
+- The host daemon is running (`agenttower ensure-daemon` already
+  succeeded; see FEAT-002 quickstart).
+- At least one bench container has been discovered by FEAT-003
+  (`agenttower scan --containers`; `agenttower list-containers`
+  shows it).
+- At least one tmux pane has been discovered inside that container
+  by FEAT-004 (`agenttower scan --panes`; `agenttower list-panes`
+  shows it).
+- The user is shelled into the bench container and into the
+  desired tmux pane. FEAT-005's identity detection will resolve
+  the container id and pane composite key automatically.
+
+You can verify the prerequisites with:
+
+```bash
+agenttower config doctor
+```
+
+All checks (`socket_resolved`, `socket_reachable`, `daemon_status`,
+`container_identity`, `tmux_present`, `tmux_pane_match`) MUST be
+`pass` before `register-self` is meaningful.
+
+---
+
+## 1. Register the current pane (US1 — happy path)
+
+From inside the bench container, in the target tmux pane:
+
+```bash
+agenttower register-self \
+    --role slave \
+    --capability codex \
+    --label codex-01 \
+    --project /workspace/acme
+```
+
+Expected output (one `key=value` line per field on stdout, exit
+`0`):
+
+```text
+agent_id=agt_abc123def456
+role=slave
+capability=codex
+label=codex-01
+project_path=/workspace/acme
+parent_agent_id=-
+created_or_reactivated=created
+```
+
+`parent_agent_id` renders as the literal `-` when null. The
+`--json` form wraps the same fields under `{"ok": true, "result":
+{...}}` (see `contracts/cli.md` for the full envelope).
+
+A new row in the `agents` table now binds this pane composite key
+to `agent_id=agt_abc123def456`. A JSONL audit row has been
+appended to the daemon's `events.jsonl` with `prior_role: null`
+and `new_role: slave` (Clarifications Q4).
+
+---
+
+## 2. List agents
+
+```bash
+agenttower list-agents
+```
+
+Default output (TSV with required header row, locked column
+schema; Clarifications Q5):
+
+```text
+AGENT_ID	LABEL	ROLE	CAPABILITY	CONTAINER	PANE	PROJECT	PARENT	ACTIVE
+agt_abc123def456	codex-01	slave	codex	abc123def456	main:0.0	/workspace/acme	-	true
+```
+
+JSON form:
+
+```bash
+agenttower list-agents --json
+```
+
+Returns the standard FEAT-006 envelope `{"ok": true, "result":
+{...}}`, with `filter` and the `agents` array nested under
+`result` and every field from `data-model.md` §4.1 / §6.4. See
+`contracts/cli.md` C-CLI-602 for the full shape.
+
+Filter examples:
+
+```bash
+agenttower list-agents --role slave
+agenttower list-agents --container abc123def456 --active-only
+agenttower list-agents --parent agt_abc123def456    # swarm children of this slave
+```
+
+---
+
+## 3. Idempotent re-registration (US1 AS2 / AS3)
+
+Re-running the same command from the same pane returns the same
+`agent_id` and updates `last_registered_at`:
+
+```bash
+agenttower register-self --role slave --capability codex --label codex-01 --project /workspace/acme
+```
+
+Output (the same field block as the first registration, but
+`created_or_reactivated=updated`):
+
+```text
+agent_id=agt_abc123def456
+role=slave
+capability=codex
+label=codex-01
+project_path=/workspace/acme
+parent_agent_id=-
+created_or_reactivated=updated
+```
+
+The agent count stays at 1; no new audit row is appended (the
+role did not change).
+
+Updating a single mutable field by passing only that flag (per
+Clarifications Q1, omitted flags leave stored values
+unchanged):
+
+```bash
+agenttower register-self --label codex-main
+```
+
+Output:
+
+```text
+agent_id=agt_abc123def456
+role=slave
+capability=codex
+label=codex-main
+project_path=/workspace/acme
+parent_agent_id=-
+created_or_reactivated=updated
+```
+
+`role`, `capability`, and `project_path` are preserved exactly
+because `--role`, `--capability`, and `--project` were not
+passed. This is the property that prevents a routine re-run from
+silently demoting a master.
+
+---
+
+## 4. Promote to master (US2 — master safety boundary)
+
+### 4.1 Reject promotion via `register-self` (FR-010)
+
+`register-self` does not accept `--confirm` (the master safety
+boundary is not unlocked at this surface in any way), so calling
+it with `--role master` is refused unconditionally:
+
+```bash
+agenttower register-self --role master
+```
+
+Exit code `3` (FEAT-002 daemon-error convention); stderr:
+
+```text
+error: register-self cannot assign role=master; register first, then run `agenttower set-role --role master --confirm`
+code: master_via_register_self_rejected
+```
+
+No agent row created; no audit row appended.
+
+### 4.2 Reject `set-role --role master` without `--confirm` (FR-011)
+
+```bash
+agenttower set-role --target agt_abc123def456 --role master
+```
+
+Exit code `3`; stderr:
+
+```text
+error: master role assignment requires --confirm
+code: master_confirm_required
+```
+
+Role unchanged.
+
+### 4.3 Promote with `--confirm` (US2 AS1)
+
+```bash
+agenttower set-role --target agt_abc123def456 --role master --confirm
+```
+
+Exit code `0`; stdout (one `key=value` line per field):
+
+```text
+agent_id=agt_abc123def456
+field=role
+prior_value=slave
+new_value=master
+audit_appended=true
+```
+
+`agenttower list-agents` now shows `role=master`. The agent's
+`effective_permissions.can_send_to_roles` is `["slave", "swarm"]`
+(FR-021). One JSONL audit row was appended with
+`confirm_provided: true`.
+
+### 4.4 Demote from master (FR-013)
+
+Demotion does NOT require `--confirm`:
+
+```bash
+agenttower set-role --target agt_abc123def456 --role slave
+```
+
+Exit code `0`; one audit row appended with `confirm_provided: false`.
+
+---
+
+## 5. Register a swarm child (US3)
+
+A swarm child is a separate agent in a different tmux pane, bound
+to a parent slave. The parent must exist, be active, and have
+`role=slave` (FR-017).
+
+In the swarm child's pane (a different pane, possibly in the same
+container):
+
+```bash
+agenttower register-self \
+    --role swarm \
+    --parent agt_abc123def456 \
+    --capability claude \
+    --label claude-swarm-01
+```
+
+Output:
+
+```text
+agent_id=agt_def456abc789
+role=swarm
+capability=claude
+label=claude-swarm-01
+project_path=
+parent_agent_id=agt_abc123def456
+created_or_reactivated=created
+```
+
+`agenttower list-agents` now shows two rows; the swarm row has
+`PARENT=agt_abc123def456`.
+
+### 5.1 Swarm parent failure paths (US3 AS2..AS6)
+
+| Command | Closed-set error code |
+| ------- | --------------------- |
+| `register-self --role swarm --parent agt_unknown123456 --capability claude` | `parent_not_found` |
+| `register-self --role swarm --parent <slave-id> --capability claude` (where the parent is `active=false`) | `parent_inactive` |
+| `register-self --role swarm --parent <master-id> --capability claude` | `parent_role_invalid` |
+| `register-self --role swarm --capability claude` (no `--parent`) | `swarm_parent_required` |
+| `register-self --role slave --parent <id>` | `parent_role_mismatch` |
+
+### 5.2 Parent immutability (Clarifications Q3)
+
+Re-running `register-self` with a *different* `--parent` value is
+rejected:
+
+```bash
+agenttower register-self --role swarm --parent agt_otherSlave1234 --capability claude
+```
+
+Exit code `3`; stderr:
+
+```text
+error: parent_agent_id is immutable for life; stored value is agt_abc123def456
+code: parent_immutable
+```
+
+No mutable field is updated by this call (Q3 atomicity).
+
+Re-running with the *same* `--parent` is a no-op success:
+
+```bash
+agenttower register-self --role swarm --parent agt_abc123def456 --capability claude
+```
+
+Returns the same `agent_id`; updates `last_registered_at`; no
+audit row.
+
+---
+
+## 6. Test-harness equivalent
+
+Every command above can be exercised in the FEAT-002 daemon
+harness without a real Docker daemon, real container, or real
+tmux server (FR-044, SC-012). Set up:
+
+```python
+# tests/integration/test_cli_register_self.py (illustrative)
+from . import _daemon_helpers as h
+
+def test_register_self_happy_path(tmp_path, monkeypatch):
+    with h.spawn_daemon(home=tmp_path) as daemon:
+        h.seed_container(daemon, container_id="abc123def456...", name="bench-1", active=True)
+        h.seed_pane(daemon, container_id="abc123def456...",
+                    tmux_socket_path="/tmp/tmux-1000/default",
+                    tmux_session_name="main",
+                    tmux_window_index=0, tmux_pane_index=0,
+                    tmux_pane_id="%17", active=True)
+        # Simulate "running inside that container in that pane" via FEAT-005
+        # test seam: AGENTTOWER_TEST_PROC_ROOT points at a fixture rooting
+        # /proc/self/cgroup at the container id and seeding /etc/hostname.
+        monkeypatch.setenv("AGENTTOWER_TEST_PROC_ROOT", str(h.proc_fixture_for(...)))
+        monkeypatch.setenv("TMUX", "/tmp/tmux-1000/default,12345,$0")
+        monkeypatch.setenv("TMUX_PANE", "%17")
+
+        result = h.run_cli(["register-self", "--role", "slave",
+                            "--capability", "codex",
+                            "--label", "codex-01",
+                            "--project", "/workspace/acme",
+                            "--json"])
+
+        assert result.exit_code == 0
+        payload = json.loads(result.stdout)
+        assert payload["ok"] is True
+        assert payload["agent_id"].startswith("agt_")
+        assert payload["role"] == "slave"
+        assert payload["created_or_reactivated"] == "created"
+```
+
+The same three test seams from FEAT-003 / FEAT-004 / FEAT-005
+(`AGENTTOWER_TEST_DOCKER_FAKE`, `AGENTTOWER_TEST_TMUX_FAKE`,
+`AGENTTOWER_TEST_PROC_ROOT`) cover every external surface
+FEAT-006 exercises. No new test seam is introduced (R-013).
+
+---
+
+## 7. Cleanup
+
+FEAT-006 introduces no `unregister` / `delete-agent` command —
+that capability is deferred (FR-043). Agent rows persist with
+`active=false` after the bound pane disappears (FR-009).
+Re-running `register-self` from the same pane composite key
+re-activates the existing row (FR-008).
+
+To inspect the audit log:
+
+```bash
+tail -n 20 ~/.local/state/opensoft/agenttower/events.jsonl
+```
+
+Each successful role transition appears as one JSON line emitted
+by the FEAT-001 `events.writer.append_event` helper. The on-disk
+record shape is `{"ts": "<utc-iso>", "type": "agent_role_change",
+"payload": {...}}` (FR-014; data-model.md §4.4).
+
+---
+
+## 8. Failure mode quick reference
+
+The Symptom column already names the closed-set code, so a separate
+column would be redundant. Codes inherit the FEAT-002 socket-API
+contract — see `contracts/socket-api.md` §3 for the daemon-side
+closed set; `daemon_unavailable` is the FEAT-002 CLI-side
+classification (the daemon never received the call).
+
+| Symptom | Likely cause |
+| ------- | ------------ |
+| `register-self` exits `2` (`daemon_unavailable`, FEAT-002 inheritance) | Daemon not running |
+| `register-self` exits `1` with `host_context_unsupported` | Running on the host shell, not inside a bench container |
+| `register-self` exits `3` with `not_in_tmux` | `$TMUX` unset |
+| `register-self` exits `3` with `tmux_pane_malformed` | `$TMUX_PANE` malformed |
+| `register-self` exits `3` with `container_unresolved` | FEAT-005 identity detection got `multi_match` / `no_match` / `no_candidate` |
+| `register-self` exits `3` with `pane_unknown_to_daemon` | Pane composite key not in FEAT-004 registry; focused rescan did not find it; run `agenttower scan --panes` from the host |
+| `set-role --role master` exits `3` with `master_confirm_required` | Forgot `--confirm` |
+| `set-role --role swarm` exits `3` with `swarm_role_via_set_role_rejected` | Swarm role assignment requires `register-self --role swarm --parent <id>` |
+| `register-self --role swarm` exits `3` with `swarm_parent_required` | Forgot `--parent <agent-id>` |
+| `register-self --parent <id>` exits `3` with `parent_role_mismatch` | `--parent` requires `--role swarm` |
+| Any CLI exits `3` with `schema_version_newer` | Daemon is newer than this CLI build; upgrade the CLI |
diff --git a/specs/006-agent-registration/research.md b/specs/006-agent-registration/research.md
new file mode 100644
index 0000000..b165537
--- /dev/null
+++ b/specs/006-agent-registration/research.md
@@ -0,0 +1,820 @@
+# Phase 0 Research: Agent Registration and Role Metadata
+
+**Branch**: `006-agent-registration` | **Date**: 2026-05-07
+
+This document records the research decisions that resolve every
+NEEDS CLARIFICATION in `plan.md`'s Technical Context. Each entry
+captures Decision, Rationale, and Alternatives Considered.
+
+---
+
+## R-001 — `agent_id` shape and entropy
+
+**Decision**: `agent_id = "agt_" + secrets.token_hex(6)` →
+`agt_<12-character-lowercase-hex>` (48 bits of entropy: 6 bytes ×
+8 bits = 48; 12 hex chars × 4 bits = 48).
+
+**Rationale**:
+- FR-001 fixes the format; this is the implementation that
+  satisfies it.
+- `secrets.token_hex(6)` returns 12 lowercase hex chars on every
+  Python 3.11+ build (stdlib, no third-party dependency).
+- 48 bits of entropy keeps accidental collisions vanishingly
+  unlikely at MVP scale: birthday-bound, the first expected
+  collision is at ~2^24 ≈ 16M unique agents — far beyond any
+  plausible MVP fleet. If post-MVP scale ever pushes past that,
+  bump `token_hex(6)` to `token_hex(12)` and the regex to
+  `[0-9a-f]{24}` for a real 96 bits (a wire-format change that
+  must be coordinated with downstream consumers).
+- The literal `agt_` prefix is human-recognizable in CLI output
+  and prevents collision with FEAT-003 container ids (no prefix)
+  or FEAT-004 pane ids (`%N`).
+
+**Collision handling**: A bounded retry loop (≤ 5 attempts) inside
+the per-(container_id, pane_composite_key) registration mutex.
+Each attempt generates a fresh id and tries the SQLite INSERT;
+SQLite raises `IntegrityError` on the PK conflict. Exhausted
+budget surfaces as `internal_error` (FR-035) and the daemon
+stays alive. Five attempts is overwhelmingly conservative: the
+expected number of retries at MVP scale is essentially zero.
+
+**Alternatives considered**:
+- ULID / UUIDv7 — adds a third-party dependency *or* a stdlib
+  port; the visible benefit (sortable ids) does not apply here
+  because list ordering is by `(active, container_id, parent,
+  label, agent_id)` per FR-025, not creation time.
+- `secrets.token_urlsafe(8)` — variable URL-safe alphabet, less
+  readable, and the `_`/`-` chars complicate downstream grep
+  patterns.
+- Larger entropy (16 hex / 24 hex) — unnecessary at MVP scale;
+  spec FR-001 locks 12 hex.
+
+---
+
+## R-002 — Mutable-field wire encoding (Clarifications Q1)
+
+**Decision**: Argparse uses `argparse.SUPPRESS` as the default for
+every mutable flag (`--role`, `--capability`, `--label`,
+`--project`, `--parent`). When the user does not pass a flag, the
+key is *absent* from the parsed `Namespace` and therefore absent
+from the JSON request envelope. The daemon treats absent keys as
+"leave unchanged" per FR-007. On *first* registration of a brand-
+new pane, the CLI applies argparse-style defaults
+(`role="unknown"`, `capability="unknown"`, `label=""`,
+`project_path=""`) before sending; absent vs. default is decided
+by checking whether the agent record already exists for the
+caller's pane composite key (one `list_panes` lookup) — if it
+exists, defaults are NOT applied.
+
+**Wire shape (request envelope, FR-024)**:
+
+```json
+{
+  "method": "register_agent",
+  "params": {
+    "container_id": "<full-id-from-FEAT-005>",
+    "pane_composite_key": {
+      "container_id": "<full-id>",
+      "tmux_socket_path": "/tmp/tmux-1000/default",
+      "tmux_session_name": "main",
+      "tmux_window_index": 0,
+      "tmux_pane_index": 0,
+      "tmux_pane_id": "%17"
+    },
+    "role": "slave",                 // OPTIONAL — absent means "leave unchanged" on existing agent; on first registration, CLI applies default "unknown" if absent
+    "capability": "codex",           // OPTIONAL — same semantics
+    "label": "codex-01",             // OPTIONAL — same semantics
+    "project_path": "/workspace/acme", // OPTIONAL — same semantics
+    "parent_agent_id": "agt_aaaaaa"  // OPTIONAL — same semantics; on existing agent, MUST match stored value or rejection per FR-018a
+  }
+}
+```
+
+**Daemon-side**: the `register_agent` handler enumerates the
+expected key set; unknown keys are rejected with `bad_request`.
+For each known key, `key in params` distinguishes "supplied" from
+"absent". On *creation* (no row exists for the composite key),
+absent keys fall back to argparse-style defaults applied
+*server-side* as well so the CLI/daemon agree on the contract;
+on *update* (row exists), absent keys leave the stored value
+intact.
+
+**Rationale**:
+- Clarifications 2026-05-07 Q1 locks Option B: omitted flags
+  leave stored values unchanged; preserves master/slave roles
+  across routine re-`register-self`.
+- `argparse.SUPPRESS` is the documented stdlib idiom for "do not
+  insert a default into the namespace when the user does not
+  pass this flag" — no custom sentinel needed.
+- Distinguishing "user passed `--role unknown`" (overwrite) from
+  "user did not pass `--role`" (leave unchanged) is a hard
+  requirement of Q1 and falls out naturally from `SUPPRESS` +
+  explicit dict membership check.
+
+**Alternatives considered**:
+- Custom sentinel (`_OMITTED = object()`) — works but adds
+  bookkeeping; `SUPPRESS` already provides the same semantics.
+- Always-transmit defaults (Option A from Q1) — explicitly
+  rejected in clarification because of silent demotion risk.
+- Daemon-side defaults only on creation, never on update —
+  adopted as a refinement; the CLI also applies defaults on
+  creation so the wire contract is symmetric and the daemon
+  can validate the request without re-deriving "is this
+  creation or update".
+
+---
+
+## R-003 — `last_seen_at` ownership and update path
+
+**Decision**: `last_seen_at` is updated exclusively by the
+FEAT-004 pane reconciliation transaction. Every reconciliation
+that observes a pane composite key as `active=true` runs an
+`UPDATE agents SET last_seen_at = :scan_time WHERE container_id = ? AND tmux_socket_path = ? AND ...`
+in the same `BEGIN IMMEDIATE` transaction as the pane row
+upsert. Reconciliations that fail to observe the pane (or
+observe it as inactive) MUST NOT update `last_seen_at`. CLI
+codepaths (`list_agents`, `register_agent` no-op,
+`set_role`/`set_label`/`set_capability`) MUST NOT touch
+`last_seen_at`.
+
+**Rationale**:
+- Clarifications 2026-05-07 Q2 locks Option A.
+- Independent of `last_registered_at` — the former is
+  passive observation (FEAT-004 scanner saw the pane), the
+  latter is explicit registration intent.
+- Single-writer semantics keep the field meaningful: there is
+  exactly one codepath that writes it.
+- The wiring is contained to `discovery/pane_reconcile.py` and
+  is purely additive — the existing pane upsert already runs
+  under a transaction, so the agent UPDATE rides along.
+
+**Implementation**:
+- `discovery/pane_reconcile.py` already groups pane upserts by
+  `(container_id, tmux_socket_path)` for one transaction per
+  socket. After the existing pane upsert, run one parameterised
+  `UPDATE agents SET last_seen_at = :scan_time WHERE
+  (container_id, tmux_socket_path, tmux_session_name,
+  tmux_window_index, tmux_pane_index, tmux_pane_id) IN (...)`
+  for the set of observed-active panes in that batch. The
+  index `agents_pane_lookup` (data-model.md §2) covers this
+  predicate.
+- Active→inactive transitions cascade to `agents.active = 0`
+  in the same transaction (FR-009).
+- Inactive→active does NOT auto-flip `agents.active` —
+  explicit `register-self` is required (FR-009).
+
+**Alternatives considered**:
+- CLI updates `last_seen_at` on every successful daemon call
+  (Option B) — rejected because `list_agents` is read-only and
+  `set_*` are operator events, not liveness signals.
+- Defer to FEAT-007 / FEAT-008 (Option D) — rejected because
+  `list-agents` benefits from a meaningful liveness column in
+  MVP without waiting on later features.
+
+---
+
+## R-004 — Schema migration v3 → v4
+
+**Decision**: Add exactly one migration function
+`_apply_migration_v4(conn)` to `state/schema.py`, registered as
+`_MIGRATIONS[4]`, and bump `CURRENT_SCHEMA_VERSION` from `3` to
+`4`. The migration is idempotent (every `CREATE TABLE` and
+`CREATE INDEX` uses `IF NOT EXISTS`), runs inside the existing
+`_apply_pending_migrations` function under one
+`BEGIN IMMEDIATE` transaction, rolls back the entire transaction
+on failure, and refuses to serve the daemon on rollback. v3-only
+DBs upgrade in one transaction; v4-already-current DBs re-open
+as no-ops via the `IF NOT EXISTS` guards (the existing
+`_ensure_current_schema` already calls every migration body
+defensively for the current version, see `schema.py:236-237`).
+
+**Rationale**:
+- FR-036 mandates idempotent, single-transaction migration that
+  bumps `schema_version` only after the new table exists.
+- FR-037 forbids modifying FEAT-001..004 schemas.
+- The existing migration framework supports this pattern
+  verbatim — see `_apply_migration_v2` (FEAT-003) and
+  `_apply_migration_v3` (FEAT-004) in `state/schema.py:28-154`.
+
+**Alternatives considered**:
+- Multi-step migration (separate table + indexes) — rejected
+  because the `IF NOT EXISTS` guards already handle re-open; a
+  single migration function is consistent with v2 and v3.
+- Skip indexes (add only the table) — rejected because
+  `list_agents` deterministic ordering (FR-025) and the
+  `last_seen_at` UPDATE in pane reconciliation (R-003) both
+  benefit from indexes; see data-model.md §3 for the index
+  list.
+
+---
+
+## R-005 — Mutex layout and lifetime
+
+**Decision**: Two in-process `dict[key, threading.Lock]` maps
+managed by `agents/service.py`, guarded by a `threading.Lock`
+that protects the *map* (not the per-key locks). Acquire the
+map-lock briefly to fetch-or-create the per-key lock; release
+the map-lock; acquire the per-key lock; do the SQLite work;
+release the per-key lock.
+
+- `register_locks: dict[(container_id, tmux_socket_path,
+  tmux_session_name, tmux_window_index, tmux_pane_index,
+  tmux_pane_id), threading.Lock]` — for `register_agent`
+  (FR-038).
+- `agent_locks: dict[agent_id, threading.Lock]` — for
+  `set_role`, `set_label`, `set_capability` (FR-039).
+
+Per-key locks are never evicted during the daemon process
+lifetime. Memory overhead is bounded by the number of distinct
+panes ever registered (MVP scale: tens to low hundreds), so a
+small constant per entry is acceptable.
+
+**Rationale**:
+- FR-038 / FR-039 require serialization per pane composite key
+  and per agent_id respectively.
+- SQLite's single-writer semantics serialize commits internally,
+  but the read-modify-write of `effective_permissions` (compute
+  from current role; UPDATE) needs an in-process advisory mutex
+  to prevent a lost update.
+- The dict-of-locks pattern is a stdlib idiom; no third-party
+  dependency.
+
+**Alternatives considered**:
+- Single global mutex — rejected because FR-038 explicitly
+  requires concurrent registrations from *different* panes to
+  proceed in parallel.
+- LRU eviction of per-key locks — rejected because eviction
+  while a thread holds a lock is a footgun; MVP-scale memory
+  use is negligible.
+- SQLite `BEGIN EXCLUSIVE` only — rejected because while the
+  SQL transaction is exclusive, the Python-side
+  read-modify-write (compute new `effective_permissions` JSON
+  from role) is not, and would require begin-retry on busy
+  errors.
+
+---
+
+## R-006 — Audit record schema and append site
+
+**Decision**: One JSONL row per successful role transition
+appended to the existing FEAT-001 `events.jsonl` file via the
+existing `events/writer.py` helper. The row shape:
+
+```json
+{
+  "event_type": "agent_role_change",
+  "ts_utc": "2026-05-07T14:30:00.000000+00:00",
+  "agent_id": "agt_abc123def456",
+  "prior_role": null,
+  "new_role": "slave",
+  "confirm_provided": false,
+  "socket_peer_uid": 1000
+}
+```
+
+`prior_role` is the JSON literal `null` on first registration
+of an agent (Clarifications 2026-05-07 Q4); on subsequent
+transitions it is the previous string value.
+`confirm_provided` is `true` only on `set-role --role master
+--confirm`; for every other path it is `false`.
+`socket_peer_uid` comes from the FEAT-002 socket peer-cred
+lookup (`SO_PEERCRED`) the daemon already performs.
+
+**No-op rule**: A `set_*` call where the new value equals the
+stored value is a successful no-op and MUST NOT append a new
+row (FR-027). A `register_agent` call where the resolved
+post-merge role equals the stored role MUST NOT append a new
+row. Only writes that actually transition `agents.role` from
+one value to another (including `null → X` on creation) are
+logged.
+
+**Rationale**:
+- FR-014 + Clarifications Q4 lock the shape including
+  `prior_role: null` on creation.
+- Reusing `events.jsonl` keeps the on-disk audit footprint to
+  one file (Assumptions in spec.md).
+- The `events/writer.py` lock + atomic-append helper is already
+  thread-safe.
+
+**Alternatives considered**:
+- Separate `agents.jsonl` audit file — rejected by Assumptions
+  ("FEAT-006 MUST NOT introduce a new audit log file").
+- Log every write (incl. no-op) — rejected by FR-027.
+
+---
+
+## R-007 — Focused per-container rescan invocation (FR-041)
+
+**Decision**: When `register_agent` resolves a pane composite
+key that is not in the `panes` table (or is in the table with
+`active=false`), the handler invokes the existing FEAT-004
+`PaneDiscoveryService.scan(container=<resolved_container_id>)`
+codepath — a single-element container set — exactly once.
+The rescan inherits FEAT-004's 5-second per-call timeout
+verbatim. After the rescan, the handler re-queries the
+`panes` table; if the pane appears as `active=true`, the
+registration proceeds; otherwise it refuses with
+`pane_unknown_to_daemon` (FR-041).
+
+**Rationale**:
+- FR-041 mandates exactly one focused rescan, scoped to the
+  caller's container, reusing the FEAT-004 codepath.
+- FEAT-004's `PaneDiscoveryService.scan()` already accepts a
+  container filter; FEAT-006 calls it with a single-element
+  set rather than introducing a new "scan-one-container" API
+  (per Assumptions in spec.md).
+- The 5-second timeout is FEAT-004's existing per-call budget;
+  no new constant is introduced.
+
+**Implementation note**: The handler MUST NOT cascade to other
+containers (FR-041) — the rescan call site explicitly passes
+`{caller_container_id}` as the container set. If FEAT-004 ever
+adds a request-scoped scan-one-container API, FEAT-006 SHOULD
+adopt it (Assumptions).
+
+**Alternatives considered**:
+- Trigger a global `scan_panes` — rejected by FR-041.
+- Refuse without rescan — rejected by FR-041 (the spec
+  explicitly requires exactly one rescan attempt).
+
+---
+
+## R-008 — `effective_permissions` materialization
+
+**Decision**: Materialized as a JSON column on every agent
+row, recomputed on every write that mutates `role`. The pure
+function `agents.permissions.effective_permissions(role: str)
+-> dict` returns the closed-set object per FR-021 across all
+six roles. The function is the single source of truth; both
+the daemon-side write path and any read path that
+constructs the JSON column use the same function.
+
+| Role          | can_send | can_receive | can_send_to_roles |
+| ------------- | -------- | ----------- | ----------------- |
+| `master`      | true     | false       | `["slave", "swarm"]` |
+| `slave`       | false    | true        | `[]` |
+| `swarm`       | false    | true        | `[]` |
+| `test-runner` | false    | false       | `[]` |
+| `shell`       | false    | false       | `[]` |
+| `unknown`     | false    | false       | `[]` |
+
+**Rationale**:
+- FR-021 fixes the derivation; this is a direct lookup.
+- Materializing on the row (rather than computing at read time)
+  keeps `list_agents` read-only and fast — the JSON column is
+  ready for `--json` output verbatim (FR-022).
+- FR-022 forbids FEAT-006 from consuming the value; the column
+  exists for FEAT-009 / FEAT-010 to read.
+
+**Alternatives considered**:
+- Compute at read time — rejected because `list_agents` is
+  read-only and a derived column avoids per-row Python
+  computation.
+- Store as separate boolean columns + JSON-array column —
+  rejected because FR-021 specifies a single JSON object
+  `effective_permissions`; downstream features parse one
+  field, not three.
+
+---
+
+## R-009 — `list-agents` deterministic ordering (FR-025)
+
+**Decision**: SQL `ORDER BY active DESC, container_id ASC, parent_agent_id ASC NULLS FIRST, label ASC, agent_id ASC`.
+SQLite supports `NULLS FIRST` since 3.30 (default behavior on
+ASC is NULLS FIRST without the explicit clause; the explicit
+clause is included for portability and code clarity).
+
+**Index**: `CREATE INDEX agents_active_order ON agents(active DESC, container_id ASC, parent_agent_id ASC, label ASC, agent_id ASC)` —
+covers the ordering predicate without requiring a sort step.
+
+**Rationale**:
+- FR-025 fixes the order.
+- An explicit covering index keeps `list_agents` constant-time
+  per row at MVP scale.
+- `NULLS FIRST` ensures non-swarm agents (NULL parent) come
+  before swarm agents within the same container/parent
+  grouping — useful for human readers scanning the TSV form.
+
+**Alternatives considered**:
+- Sort in Python — rejected because the SQL ORDER BY is
+  trivial and deterministic across all SQLite versions
+  AgentTower targets.
+
+---
+
+## R-010 — Closed-set error code addition
+
+**Decision**: Add the FEAT-006 closed-set codes to
+`socket_api/errors.py` as new `Final[str]` constants and
+extend `CLOSED_CODE_SET` with the union. The new codes are:
+
+```text
+HOST_CONTEXT_UNSUPPORTED        = "host_context_unsupported"
+CONTAINER_UNRESOLVED            = "container_unresolved"
+NOT_IN_TMUX                     = "not_in_tmux"
+TMUX_PANE_MALFORMED             = "tmux_pane_malformed"
+PANE_UNKNOWN_TO_DAEMON          = "pane_unknown_to_daemon"
+AGENT_NOT_FOUND                 = "agent_not_found"
+AGENT_INACTIVE                  = "agent_inactive"
+PARENT_NOT_FOUND                = "parent_not_found"
+PARENT_INACTIVE                 = "parent_inactive"
+PARENT_ROLE_INVALID             = "parent_role_invalid"
+PARENT_ROLE_MISMATCH            = "parent_role_mismatch"
+PARENT_IMMUTABLE                = "parent_immutable"
+SWARM_PARENT_REQUIRED           = "swarm_parent_required"
+SWARM_ROLE_VIA_SET_ROLE_REJECTED = "swarm_role_via_set_role_rejected"
+MASTER_VIA_REGISTER_SELF_REJECTED = "master_via_register_self_rejected"
+MASTER_CONFIRM_REQUIRED         = "master_confirm_required"
+VALUE_OUT_OF_SET                = "value_out_of_set"
+FIELD_TOO_LONG                  = "field_too_long"
+PROJECT_PATH_INVALID            = "project_path_invalid"
+UNKNOWN_FILTER                  = "unknown_filter"
+SCHEMA_VERSION_NEWER            = "schema_version_newer"
+```
+
+`DAEMON_UNAVAILABLE` is *not* added to the daemon-side closed
+set because it is a CLI-side classification — the daemon
+never sees the call. CLI code maps connect-time failures to
+`daemon_unavailable` per FR-032 (FEAT-002 inheritance).
+
+**Rationale**:
+- FR-040 lists the closed set; this is the implementation
+  mapping.
+- Existing FEAT-002/003/004 codes are unchanged byte-for-byte
+  (SC-010).
+- `CLOSED_CODE_SET` is the runtime guard that prevents typos
+  from leaking unknown codes onto the wire (`make_error`
+  raises `ValueError` on unknown code).
+
+**Alternatives considered**:
+- Reuse FEAT-002 `BAD_REQUEST` for input validation —
+  rejected because the spec mandates closed-set codes that
+  appear verbatim in `--json` output (FR-040), and
+  downstream tooling needs to distinguish
+  `value_out_of_set` from `field_too_long` from
+  `project_path_invalid` etc.
+
+---
+
+## R-011 — CLI subcommand naming and dispatcher
+
+**Decision**: Five new top-level subparsers under the existing
+`agenttower` parser:
+
+- `agenttower register-self`
+- `agenttower list-agents`
+- `agenttower set-role`
+- `agenttower set-label`
+- `agenttower set-capability`
+
+Each subcommand routes through the existing FEAT-005
+socket-resolution chain (`AGENTTOWER_SOCKET` → in-container
+default → host default; `paths.resolve_socket_path`) and the
+existing FEAT-002 client (`socket_api/client.py`).
+
+**Rationale**:
+- Spec FR-028..FR-031 fix the CLI names.
+- Top-level subparsers (rather than `agenttower agents
+  register`) match the existing FEAT-002 / FEAT-003 / FEAT-004
+  pattern: `ensure-daemon`, `daemon`, `scan-containers`,
+  `list-containers`, `scan-panes`, `list-panes`,
+  `config doctor`, etc.
+
+**Alternatives considered**:
+- Group under `agenttower agents <verb>` — rejected for
+  consistency with sibling top-level commands.
+- Use hyphens vs underscores in subcommand names — hyphens
+  match every existing FEAT-001..005 subcommand.
+
+---
+
+## R-012 — Daemon-side request validation order
+
+**Decision**: For every method, validate in this order before
+acquiring any mutex:
+
+1. Schema-version forward-compat check (refuse with
+   `schema_version_newer` if daemon is older than the request
+   shape — defensive; in practice the CLI will refuse first).
+2. Closed-set field shape (role, capability in closed sets;
+   `agent_id` matches `agt_<12-hex>`; `parent_agent_id` matches
+   shape; filter keys belong to known set).
+3. Free-text bounds and sanitization (FR-033 / FR-034) on
+   `label`, `project_path`.
+4. Master-safety static rejection (`register_agent` rejects
+   `--role master`; `set_role` requires `--confirm` for master,
+   rejects swarm).
+5. Acquire the appropriate per-key advisory mutex.
+6. Read current state inside the mutex.
+7. Validate dynamic invariants (parent exists, parent is
+   active, parent role is `slave`; agent exists; agent active;
+   container active for master promotion;
+   `parent_agent_id` immutability).
+8. Compute the effective post-write state.
+9. Single SQLite transaction: write agent row, write
+   `effective_permissions`, append JSONL audit row (if a real
+   transition).
+10. Release the mutex.
+
+**Rationale**:
+- Validating before mutex acquisition keeps mutex hold times
+  short.
+- Closed-set validation is cheap; running it first surfaces
+  obvious errors fast.
+- Master-safety static rejection (4) is intentionally before
+  mutex acquisition — these calls never need to inspect
+  database state.
+- Steps 5–10 are the read-modify-write window that needs the
+  per-key mutex (R-005).
+
+**Alternatives considered**:
+- Validate inside the mutex — rejected because static
+  validation does not need any locked state and would
+  needlessly extend mutex hold times.
+
+---
+
+## R-013 — Test seam reuse
+
+**Decision**: Reuse the existing FEAT-003 / FEAT-004 / FEAT-005
+test seams verbatim:
+
+- `AGENTTOWER_TEST_DOCKER_FAKE` — FEAT-003 fake `docker`
+  invocation outputs.
+- `AGENTTOWER_TEST_TMUX_FAKE` — FEAT-004 fake `tmux` invocation
+  outputs.
+- `AGENTTOWER_TEST_PROC_ROOT` — FEAT-005 fake `/proc` + `/etc`
+  fixture root.
+
+No new test seam is introduced. FEAT-006 integration tests
+seed:
+
+1. The `containers` table via FEAT-003 fakes (one or more
+   active bench containers).
+2. The `panes` table via FEAT-004 fakes (one or more active
+   panes per container).
+3. The CLI process environment via `AGENTTOWER_TEST_PROC_ROOT`
+   to simulate "running inside that container, in that pane"
+   for FEAT-005 identity detection.
+4. The `agents` table is left empty at test start (or seeded
+   with one slave for the swarm-child story).
+
+**Rationale**:
+- FR-044 / SC-012 mandate that FEAT-006 be testable end-to-end
+  without a real Docker daemon, real container, or real tmux
+  server.
+- The three existing seams already cover every external
+  surface FEAT-006 touches.
+- Adding a new seam would add maintenance burden without a
+  concrete need.
+
+**Alternatives considered**:
+- Add a `AGENTTOWER_TEST_AGENTS_FAKE` env var that pre-seeds
+  the `agents` table — rejected because the SQLite layer is
+  the canonical seed point in tests; pre-seeding via direct
+  SQL in `_daemon_helpers.py` is clearer than a new env var.
+
+---
+
+## R-014 — `--target` resolution
+
+**Decision**: `agenttower set-role`, `set-label`, and
+`set-capability` accept `--target <agent-id>` as required input.
+The CLI passes the value verbatim over the wire; the daemon
+validates the shape (`agt_<12-hex>` regex), then looks up the
+row by `agent_id` PK.
+
+The CLI does NOT auto-resolve the caller's pane to its agent
+because (a) the operator is often setting fields on a *different*
+agent than the one they are running from (e.g., the master
+promotes a slave); (b) auto-resolution would compose poorly
+with `--target` (two ways to identify the agent); (c) the
+spec explicitly exposes `--target` (FR-030, FR-031).
+
+**Rationale**:
+- FR-030 / FR-031 require `--target`.
+- Explicit identification is safer for the master-safety
+  boundary — there is no path where `set-role --role master`
+  applies to "whatever agent is in this pane" implicitly.
+
+**Alternatives considered**:
+- Auto-resolve `--target` from the caller's pane — rejected per
+  above.
+- Allow `--target current` as an alias — out of scope for
+  FEAT-006; can be added later without breaking the contract.
+
+---
+
+## R-015 — Default `list-agents` form rendering (Clarifications Q5)
+
+**Decision**: Render as TSV with a required header row, locked
+nine-column schema, in this exact order:
+
+```text
+AGENT_ID\tLABEL\tROLE\tCAPABILITY\tCONTAINER\tPANE\tPROJECT\tPARENT\tACTIVE
+```
+
+Each row:
+
+- `AGENT_ID` — full `agt_<12-hex>`.
+- `LABEL` — verbatim, sanitized of NUL / C0 control bytes (per
+  FR-033); empty string renders as empty between the tabs.
+- `ROLE` — closed-set string.
+- `CAPABILITY` — closed-set string.
+- `CONTAINER` — `<full_container_id>[:12]` (12-char short id).
+- `PANE` — `<session>:<window>.<pane>` from the FEAT-004 short
+  pane form (e.g., `main:0.1`).
+- `PROJECT` — verbatim, sanitized as above.
+- `PARENT` — `<parent_agent_id>[:16]` (literal 16 chars
+  including the `agt_` prefix and 12 hex chars) or the literal
+  `-` (single ASCII hyphen) when null. **Note**: per
+  Clarifications Q5 the user said "12-char short" — this
+  refers to the 12-hex portion of the agent_id; the full
+  rendered form is `agt_<12-hex>` which is 16 chars. The CLI
+  emits the full `agt_<12-hex>` form (consistent with
+  `AGENT_ID` column).
+- `ACTIVE` — literal `true` or `false`.
+
+**Snapshot test** (`test_list_agents_tsv_render.py`) locks the
+output byte-for-byte across a fixed seeded state.
+
+**Rationale**:
+- Clarifications Q5 locks the columns and rendering rules.
+- Tab separation matches FEAT-002 / FEAT-005 conventions for
+  scriptable output.
+- Future fields go to `--json` or a separately-introduced
+  `--wide` flag — never the default form.
+
+**Alternatives considered**:
+- Fixed-width aligned table (Q5 Option C) — rejected by user
+  choice; TSV is more script-friendly.
+- One-line summary (Q5 Option D) — rejected; lossy.
+
+---
+
+## R-016 — Edge case: caller pane composite key changed
+
+**Decision**: Per FR-006, an agent's binding to a pane composite
+key is immutable. A `register-self` from a *different*
+composite key (different container, socket, session, window,
+pane index, or pane id) is treated as a brand-new agent
+registration — a new agent row is created with a new
+`agent_id`. The previous agent row stays in history with
+whatever `active` flag the FEAT-004 reconciliation last
+assigned. FEAT-006 provides no CLI surface to re-bind an
+existing agent to a new pane (deferred per Assumptions).
+
+**Rationale**:
+- FR-006 explicitly mandates this.
+- Spec edge case lines 70-71 describe the same behavior
+  ("AgentTower MUST treat this as a *new* agent (bound to the
+  new pane key); the old agent record MUST stay in history").
+
+**Implementation**: The `register_agent` handler keys lookup by
+the full pane composite key (six-tuple PK in `panes` mirrored
+on `agents`). A different tuple → different lookup result →
+INSERT path → new `agent_id`.
+
+---
+
+## R-017 — Concurrency property: convergence on same `agent_id`
+
+**Decision**: Two concurrent `register-self` invocations from
+the same pane (same composite key) MUST converge on the same
+`agent_id`. The per-(container_id, pane_composite_key)
+registration mutex (R-005) serializes them. The first holder
+runs the INSERT (new agent_id); the second holder runs the
+UPDATE (same agent_id). Both invocations observe the
+post-commit row state and return identical `agent_id`
+values.
+
+**Rationale**:
+- Spec edge case line 72 mandates the property.
+- The mutex guarantees serialization; the SQLite PK on the
+  composite-key tuple makes the second insert a no-op /
+  fall-through to UPDATE.
+
+**Test**: `test_cli_register_concurrent.py` spawns two
+`register-self` subprocesses bound to the same simulated pane
+and asserts both exit `0` with identical `agent_id` and
+exactly one row in `agents`.
+
+---
+
+## R-018 — Forward-compat: daemon newer than CLI
+
+**Decision**: All five new CLIs inherit the FEAT-005
+forward-compat policy verbatim. When the CLI's local
+`CURRENT_SCHEMA_VERSION` is *less than* the
+`schema_version` returned by the daemon's `status`
+round-trip, the CLI MUST surface `schema_version_newer` and
+refuse the call without making any state-changing socket
+call. The check happens in the CLI's pre-flight phase before
+any `register_agent` / `set_*` call. `list-agents` is
+treated identically — it MUST refuse rather than risk
+returning a partial row shape.
+
+**Rationale**:
+- Spec edge case line 79 mandates the inheritance.
+- FEAT-005's `config doctor` already implements this for
+  `daemon_status` — the same pattern applies to every new
+  CLI.
+
+**Implementation**: A small helper in `agents/client_resolve.py`
+calls `status` once and short-circuits if the daemon is
+newer.
+
+---
+
+## R-019 — Migration test coverage
+
+**Decision**: `tests/integration/test_schema_migration_v4.py`
+exercises:
+
+1. Fresh DB → `CURRENT_SCHEMA_VERSION = 4` after first
+   `open_registry`; `schema_version` row reads `4`; `agents`
+   table exists with the expected columns and indexes.
+2. v3-only DB (FEAT-005-only build seed) → `open_registry`
+   upgrades to v4 in one transaction; `schema_version` reads
+   `4`; FEAT-001..004 tables and rows are unchanged
+   byte-for-byte (compared via `sqlite3` schema dump).
+3. v4-already-current DB → `open_registry` is a no-op; no
+   migration runs; `schema_version` stays `4`.
+4. v5-on-disk DB (synthetic; insert `schema_version = 5` into
+   a freshly-opened DB) → `open_registry` raises
+   `sqlite3.DatabaseError` and the daemon refuses to serve.
+
+**Rationale**:
+- FR-036 mandates idempotent, single-transaction migration with
+  forward-version refusal.
+- Mirrors the FEAT-003 / FEAT-004 migration test patterns
+  exactly.
+
+---
+
+## R-020 — `--target` and `--parent` shape validation
+
+**Decision**: Both `--target <agent-id>` and `--parent
+<agent-id>` are validated against the regex
+`^agt_[0-9a-f]{12}$` *before* any socket call. Mismatches are
+rejected client-side with `value_out_of_set` and an actionable
+message ("expected agt_<12-character-lowercase-hex>"). The
+daemon re-validates the same regex defensively so a malformed
+value cannot reach the SQLite query.
+
+**Rationale**:
+- FR-001 fixes the shape.
+- Client-side validation gives a fast, actionable error before
+  the round-trip; daemon-side validation is the security
+  boundary.
+- Closed-set code is `value_out_of_set` per FR-040 (no
+  separate code for "agent_id shape").
+
+---
+
+## R-021 — In-process advisory mutex implementation note
+
+**Decision**: Use `threading.Lock`, not `threading.RLock` — the
+critical section is a single read-modify-write that does not
+recurse. The fetch-or-create of the per-key lock uses
+`dict.setdefault` under a guard lock (R-005) — `setdefault` is
+atomic in CPython for built-in dicts but the surrounding logic
+(if-not-exists-create-then-acquire) is not, so the explicit
+guard is required.
+
+**Rationale**:
+- `Lock` is the simplest stdlib primitive that satisfies the
+  requirement.
+- `RLock` would mask bugs where the same thread enters the
+  critical section twice; we want that to fail loudly.
+
+---
+
+## R-022 — Sanitization helper reuse
+
+**Decision**: Reuse the existing
+`agenttower.tmux.parsers.sanitize_text(text, max_len)` helper
+introduced by FEAT-004 for free-text bounding (NUL strip, C0
+control strip, multi-byte-safe `…` truncation). FEAT-006
+applies it to `label` (max 64) and `project_path` (max 4096).
+Over-bound values are *not* truncated — they are rejected with
+`field_too_long` per FR-033.
+
+**Rationale**:
+- Single source of truth for sanitization rules across all
+  free-text fields.
+- FEAT-004 already locks the multi-byte-safe truncation
+  semantics; FEAT-006 inherits them.
+
+**Alternatives considered**:
+- New FEAT-006-specific sanitizer — rejected; the existing
+  helper is general-purpose.
+
+---
+
+## Summary
+
+Every NEEDS CLARIFICATION in plan.md's Technical Context is
+resolved above. The decisions are consistent with the spec's
+clarifications (2026-05-07 Q1–Q5), the architecture, the
+FEAT-001..005 conventions, and the constitution.
diff --git a/specs/006-agent-registration/spec.md b/specs/006-agent-registration/spec.md
new file mode 100644
index 0000000..16cf173
--- /dev/null
+++ b/specs/006-agent-registration/spec.md
@@ -0,0 +1,226 @@
+# Feature Specification: Agent Registration and Role Metadata
+
+**Feature Branch**: `006-agent-registration`
+**Created**: 2026-05-07
+**Status**: Draft
+**Input**: User description: "FEAT-006 Agent Registration and Role Metadata: let humans and agents turn discovered tmux panes inside bench containers into registered AgentTower agents. Provides `agenttower register-self`, `agenttower list-agents`, `agenttower set-role`, `agenttower set-label`, `agenttower set-capability`. Defines durable agent identity bound to a FEAT-004 pane composite key, idempotent re-registration, mutable vs immutable fields, swarm parent linkage, human-controlled master promotion (no silent privilege escalation), and effective permission derivation from role. Out of scope: prompt delivery, route configuration, log attachment, event ingestion, multi-master arbitration, automatic swarm inference, TUI/web UI, in-container daemon."
+
+## Clarifications
+
+### Session 2026-05-07 (continued)
+
+- Q: How are case differences handled for closed-set tokens (role, capability) and identifiers (agent_id, parent_agent_id, container_id)? → A: Strict case-sensitive matching everywhere; no normalization or case-folding. Locked behavior: (1) closed-set tokens (`role`, `capability`) are lowercase and case-sensitive; mixed-case inputs (`Slave`, `MASTER`, `Codex`) are rejected with `value_out_of_set`, NOT rewritten; (2) `agent_id`, `parent_agent_id`, and `container_id` are lowercase hex and case-sensitive; mixed-case inputs (`AGT_abc...`, `ABC123def456`) are rejected, NOT normalized; (3) every validator, filter, lookup, and comparison site MUST treat case differences as distinct values; (4) closed-set error messages list canonical lowercase tokens only.
+- Q: How is the race between `set-role --role master --confirm` validation (read of `agent.active` and `container.active`) and a concurrent FEAT-004 reconciliation that could flip either flag to `0` resolved? → A: One SQLite write transaction with an atomic re-check inside. Locked behavior: (1) master promotion MUST run inside a single `BEGIN IMMEDIATE` SQLite write transaction; (2) immediately after `BEGIN IMMEDIATE`, the daemon MUST re-read the target agent's `active` column AND the bound container's `active` column from `containers` in the same transaction; (3) if either is `0` (inactive), the daemon MUST `ROLLBACK` and return the closed-set error code `agent_inactive` — no agent row is mutated, no `effective_permissions` is recomputed, no JSONL audit row is appended; (4) only when both are `1` (active) MAY the daemon write the role change, recompute `effective_permissions`, append the audit row, and `COMMIT`. SQLite's `BEGIN IMMEDIATE` serializes the master-promotion transaction against the FEAT-004 reconciliation transaction at the SQLite level, closing the validate-then-write window without requiring cross-subsystem mutex coordination.
+- Q: How does the FEAT-006 per-(container, pane-key) registration mutex interact with FEAT-004 pane reconciliation that also writes to `agents` rows (FR-009, FR-009a)? → A: SQLite-level serialization is the contract; the FEAT-006 mutex covers `register_agent` vs `register_agent` only. Locked behavior: (1) the per-(container_id, pane_composite_key) advisory mutex (FR-038) MUST cover `register_agent` requests against other `register_agent` requests addressing the same composite key, and nothing else; (2) FEAT-004 pane reconciliation MUST NOT acquire the FEAT-006 per-key registration mutex; the two subsystems remain decoupled; (3) cross-subsystem ordering between a `register_agent` transaction and a FEAT-004 reconciliation transaction touching the same `agents` row is provided exclusively by SQLite's `BEGIN IMMEDIATE` semantics; (4) both transactions remain atomic — neither can observe a partial write from the other; (5) the transaction that commits last wins for any overlapping mutable column (e.g., if `register_agent` sets `active=1` and a concurrent reconciliation sets `active=0` for the same row, whichever commits last is the post-state visible to subsequent reads); (6) the daemon MUST surface `SQLITE_BUSY` as `internal_error` (FR-035) without retry — the operator can re-invoke the CLI if needed.
+- Q: What value is recorded in the audit row's `confirm_provided` field when `set-role` is called with `--confirm` but `--confirm` was not required (e.g., demotion from master, or set-role to a non-master role)? → A: The literal request value, never rewritten. Locked behavior: (1) `confirm_provided` MUST record the literal boolean the operator passed in the `confirm` request parameter — `true` if `--confirm` was passed, `false` if it was not; (2) the value MUST NOT be rewritten based on whether `--confirm` was *required* by the transition; (3) demotion from master with a redundant `--confirm` MUST log `confirm_provided: true`; (4) `set-role` to any non-master role with redundant `--confirm` MUST also log `confirm_provided: true`; (5) `register-self` creation (where `--confirm` is not a valid flag at all) MUST log `confirm_provided: false`; (6) the audit log captures operator intent verbatim — consumers that need "was confirm required" derive it from `prior_role` + `new_role`.
+
+### Session 2026-05-07
+
+- Q: When `register-self` is re-run on an existing agent without `--role` (or other mutable flags), should the CLI default values overwrite the stored row, or should omitted flags leave the stored value unchanged? → A: CLI sends only flags the user explicitly passed; daemon treats absent fields as "leave unchanged." Argparse-style defaults are not transmitted, so idempotent re-runs preserve role, capability, label, project_path, and parent unless the user explicitly changes them.
+- Q: What event updates `last_seen_at`? → A: FEAT-004 pane reconciliation. Every FEAT-004 scan that observes the agent's bound pane as active updates `last_seen_at` to the scan time, in the same SQLite transaction as the pane reconciliation. `last_registered_at` (explicit registration intent) and `last_seen_at` (passive pane observation) are independent.
+- Q: What happens when `register-self` is re-run on an existing agent and explicitly passes `--parent` with a value that differs from the stored immutable `parent_agent_id`? → A: Reject with closed-set error code `parent_immutable`. Locked behavior: (1) re-registration that explicitly re-passes the same `--parent` value as the stored `parent_agent_id` is a no-op success (returns the existing `agent_id` and updates `last_registered_at` per FR-007); (2) re-registration that explicitly passes a different `--parent` value MUST be rejected with closed-set code `parent_immutable`; (3) on that rejection, no mutable fields (role, capability, label, project_path) MUST be updated, even if the same call also supplied changes to other fields — the rejection is atomic, all-or-nothing.
+- Q: Does the initial role assignment on first `register-self` append a JSONL audit record? → A: Yes — every first successful `register-self` for a pane appends exactly one audit row with `prior_role: null`. Locked behavior: (1) the first successful `register-self` for a pane MUST write one JSONL audit row regardless of which role was assigned; (2) the audit row's `prior_role` MUST be the JSON literal `null`; (3) the default-role case (no `--role` flag, role assigned as `unknown`) MUST also write the row; (4) idempotent re-registration where the stored `role` does not change MUST NOT write a new audit row (per FR-027 no-op writes are not logged); only writes that actually transition `agents.role` from one value to another (including `null → X` on creation) are logged.
+- Q: What fields does the default (non-JSON) `list-agents` form display? → A: Tab-separated table with header row and a locked, fixed column set in this exact order: `AGENT_ID`, `LABEL`, `ROLE`, `CAPABILITY`, `CONTAINER`, `PANE`, `PROJECT`, `PARENT`, `ACTIVE`. Locked behavior: (1) output MUST be tab-separated values (TSV); (2) the header row is required (it is the first line of output, before any agent rows); (3) `CONTAINER` MUST render as the bare 12-character short container id (no prefix); (4) `PARENT` MUST render as the full `agt_<12-character-lowercase-hex>` form (16 chars total) when `parent_agent_id` is non-null and the literal `-` (single ASCII hyphen) when null; (5) `PANE` MUST render as `<session>:<window>.<pane>` (FEAT-004 short form); (6) `AGENT_ID` MUST render as the full `agt_<12-character-lowercase-hex>` form so it is consistent with `PARENT`; (7) only `CONTAINER` uses the bare 12-char short form — every agent-id-bearing column uses the full `agt_<12-hex>` form so operator pipelines (grep, awk by full id) compose uniformly across columns; (8) any future fields added to the agent record MUST be exposed via `--json` or a separately-introduced `--wide` flag — they MUST NOT be added to the default form, so the column set above is a stable contract for operator scripts and snapshot tests.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Register an agent from inside a bench-container tmux pane (Priority: P1)
+
+A developer working inside a tmux pane in a running bench container runs `agenttower register-self --role slave --capability codex --label codex-01 --project /workspace/acme`, the host daemon binds that command to the current pane (resolved from FEAT-005 container identity and `$TMUX` / `$TMUX_PANE`, cross-checked against the FEAT-004 pane registry), persists a durable agent record with a stable `agent_id`, and the same `agenttower list-agents` invocation surfaces the new agent with its container, pane, role, label, capability, project path, and effective permission summary.
+
+**Why this priority**: Registration is the smallest end-to-end value slice for FEAT-006. Without it, FEAT-007 log attachment, FEAT-008 events, FEAT-009 input delivery, and FEAT-010 routing have nothing to address. It is also the slice that exercises every other dependency in the stack at once: the FEAT-002 daemon socket, the FEAT-003 container registry, the FEAT-004 pane registry, and the FEAT-005 thin-client identity detection.
+
+**Independent Test**: Can be fully tested by spawning the host daemon under the existing FEAT-002 test harness, seeding the FEAT-003 `containers` and FEAT-004 `panes` tables with one active bench container that hosts one active tmux pane, then running `agenttower register-self --role slave --capability codex --label codex-01 --project /workspace/acme` from a second subprocess whose environment simulates "inside that bench container, in that tmux pane" (the FEAT-005 detection signals are overridden to resolve to the seeded container, `$TMUX` / `$TMUX_PANE` resolve to the seeded pane). The CLI MUST exit `0`, return a stable `agent_id`, and a follow-up `agenttower list-agents` MUST show the agent with every required field populated.
+
+**Acceptance Scenarios**:
+
+1. **Given** the daemon is running, FEAT-003 has persisted one active bench container, FEAT-004 has persisted one active pane in that container, and the caller's environment resolves to that container and pane, **When** the user runs `agenttower register-self --role slave --capability codex --label codex-01 --project /workspace/acme`, **Then** the CLI exits `0`, prints the assigned `agent_id`, the role, the label, the capability, and the project path; the daemon persists exactly one new agent row bound to the pane's FEAT-004 composite key; and `agenttower list-agents` shows that row with `active=true`.
+2. **Given** an agent has already been registered for the current pane, **When** the user re-runs `agenttower register-self` from the same pane with the same arguments, **Then** the CLI exits `0` with the same `agent_id`, no new agent row is created, and `last_registered_at` is updated.
+3. **Given** an agent has already been registered for the current pane, **When** the user re-runs `agenttower register-self` from the same pane with a different `--label`, `--capability`, or `--project`, **Then** the CLI exits `0` with the same `agent_id`, the changed mutable fields are persisted, and `list-agents` reflects the new values.
+4. **Given** `agenttower list-agents --json` is invoked while two agents exist (one in container A, one in container B), **When** the command runs, **Then** the JSON output contains exactly two objects, each with `agent_id`, `label`, `role`, `capability`, `parent_agent_id` (nullable), `container_id`, `container_name`, `container_user`, `tmux_socket_path`, `tmux_session_name`, `tmux_window_index`, `tmux_pane_index`, `tmux_pane_id`, `pane_pid`, `cwd`, `project_path`, `effective_permissions`, `created_at`, `last_registered_at`, `last_seen_at`, and `active`.
+
+---
+
+### User Story 2 - Human-controlled role, label, and capability changes (with master safety) (Priority: P2)
+
+A developer who registered a pane as a `slave` decides it should serve as a `master` for the project's spec-kit workflow. They run `agenttower set-role --target <agent-id> --role master --confirm`, the daemon promotes the agent, and `list-agents` shows the new role plus the updated effective permissions. A second attempt to promote a different agent without `--confirm` is rejected. A third attempt to call `agenttower register-self --role master` is also rejected, regardless of `--confirm`, because master privilege MUST never be granted as a side effect of a self-registration handshake — only by an explicit, deliberate operator command on an existing agent record.
+
+**Why this priority**: Master promotion is the single highest-stakes operation FEAT-006 introduces. Architecture §9 states "AgentTower must not silently grant master privileges"; PRD §9 states routing must be auditable and never escalate without explicit permission. This story isolates and tests the master-safety boundary. It is P2 (not P1) because basic registration is more foundational, but no later feature can ship until this safety property is proven.
+
+**Independent Test**: Can be fully tested by seeding two registered agents (`slave`, `slave`) and exercising the closed set of role-change paths: (a) `set-role --role master --confirm`, (b) `set-role --role master` (no `--confirm`), (c) `register-self --role master` from a brand-new pane, (d) `register-self --role master --confirm` from a brand-new pane, (e) `set-role --role slave --confirm` (demotion). Paths (a) and (e) MUST succeed; paths (b), (c), and (d) MUST exit non-zero with a closed-set error code and the agent's role MUST remain unchanged. `list-agents` MUST reflect the only successful changes.
+
+**Acceptance Scenarios**:
+
+1. **Given** an agent exists with `role=slave`, **When** the user runs `agenttower set-role --target <agent-id> --role master --confirm`, **Then** the CLI exits `0`, the role is updated to `master`, `effective_permissions.can_send_to` becomes `["slave", "swarm"]`, and a JSONL audit record is appended.
+2. **Given** an agent exists with `role=slave`, **When** the user runs `agenttower set-role --target <agent-id> --role master` (without `--confirm`), **Then** the CLI exits non-zero with `error: master role assignment requires --confirm` and the agent's role remains `slave`.
+3. **Given** the caller's current pane is not yet registered, **When** the user runs `agenttower register-self --role master --confirm`, **Then** the CLI exits non-zero with `error: register-self cannot assign role=master; register first, then run \`agenttower set-role --role master --confirm\`` and no agent row is created.
+4. **Given** an agent exists with `role=master`, **When** the user runs `agenttower set-label --target <agent-id> --label claude-main`, **Then** the CLI exits `0`, the label is updated, and the role and effective permissions are unchanged.
+5. **Given** an agent exists with `role=slave` and `capability=codex`, **When** the user runs `agenttower set-capability --target <agent-id> --capability claude`, **Then** the CLI exits `0`, the capability is updated, and the role and effective permissions are unchanged.
+
+---
+
+### User Story 3 - Register a swarm child under an existing slave (Priority: P3)
+
+A slave agent (Codex CLI in a tmux pane) spawns a child swarm worker (a Claude CLI sub-pane). The slave's master prompts the child to run `agenttower register-self --role swarm --parent <slave-agent-id> --capability claude --label claude-swarm-01`, the daemon validates the parent linkage (parent exists, parent is active, parent has `role=slave`), persists the swarm agent with its parent reference, and `agenttower list-agents` shows the swarm hierarchically under its parent slave with the swarm's effective permissions derived from `role=swarm`.
+
+**Why this priority**: Architecture §11 makes swarm parentage a first-class concept of the MVP routing model: masters route work to slaves; slaves spawn swarm children; the registry must be able to represent that hierarchy explicitly. FEAT-006 only needs to support *explicit* swarm registration; *automatic swarm inference* is deferred to FEAT-010. This story is P3 because the only consumer of swarm parentage in MVP is FEAT-009 / FEAT-010, but the registration metadata MUST land here so those features find a stable shape.
+
+**Independent Test**: Can be fully tested by registering a `slave` agent, then registering a second agent in a different tmux pane with `--role swarm --parent <slave-agent-id>`, then exercising the closed set of parent-validation failure paths: missing parent, parent inactive, parent role is `master`/`shell`/`unknown`/`test-runner`, parent is itself a `swarm`. The valid path MUST succeed and `list-agents` MUST surface the parent linkage; every failure path MUST exit non-zero with a closed-set error code and no agent row MUST be created.
+
+**Acceptance Scenarios**:
+
+1. **Given** a `slave` agent with `agent_id=agt_aaa` exists and is active, and the caller's current pane is a different active pane in the same bench container (or a different bench container), **When** the user runs `agenttower register-self --role swarm --parent agt_aaa --capability claude --label claude-swarm-01`, **Then** the CLI exits `0`, returns a new `agent_id`, the swarm agent is persisted with `parent_agent_id=agt_aaa`, and `list-agents` shows the swarm with its parent reference.
+2. **Given** the caller passes `--parent <unknown-id>`, **When** they run `agenttower register-self --role swarm --parent <unknown-id> --capability claude`, **Then** the CLI exits non-zero with `error: parent agent <unknown-id> not found`, no agent row is created, and the closed-set error code `parent_not_found` is returned over the socket.
+3. **Given** the caller passes `--parent <id>` where the parent's role is `master`, `test-runner`, `shell`, `unknown`, or `swarm`, **When** they run `agenttower register-self --role swarm --parent <id> --capability claude`, **Then** the CLI exits non-zero with `error: parent agent must have role=slave (got <role>)`, no agent row is created, and the closed-set error code `parent_role_invalid` is returned.
+4. **Given** the caller passes `--parent <id>` where the parent agent is `active=false`, **When** they run `agenttower register-self --role swarm --parent <id> --capability claude`, **Then** the CLI exits non-zero with `error: parent agent <id> is inactive`, no agent row is created, and the closed-set error code `parent_inactive` is returned.
+5. **Given** the caller runs `agenttower register-self --role swarm` without `--parent`, **When** the command runs, **Then** the CLI exits non-zero with `error: --role swarm requires --parent <agent-id>`, no agent row is created, and the closed-set error code `swarm_parent_required` is returned.
+6. **Given** the caller runs `agenttower register-self --parent <id>` with a non-swarm role (`master`, `slave`, `test-runner`, `shell`, `unknown`), **When** the command runs, **Then** the CLI exits non-zero with `error: --parent only valid with --role swarm`, and the closed-set error code `parent_role_mismatch` is returned.
+7. **Given** a swarm agent has been registered under a parent slave, **When** the user runs `agenttower list-agents --json`, **Then** the swarm row's `parent_agent_id` is the parent's id and the parent row carries no swarm-specific marker (parentage is encoded only on the child, not duplicated on the parent).
+
+### Edge Cases
+
+- The caller is on the host shell (not inside any container); FEAT-005 identity detection returns `host_context`. `register-self` MUST refuse with `error: register-self requires running inside a bench container; FEAT-006 MVP does not register host-only panes` and the closed-set error code `host_context_unsupported`.
+- The caller is inside a container but FEAT-005 identity detection returns `no_match`, `no_candidate`, or `multi_match` for the container. `register-self` MUST refuse with the closed-set error code `container_unresolved` and surface the FEAT-005 candidate value, signal source, and actionable next step ("run `agenttower scan --containers` from the host").
+- The caller's `$TMUX` is unset or `$TMUX_PANE` is unset/malformed. `register-self` MUST refuse with the closed-set error code `not_in_tmux` and instruct the caller to run inside an active tmux pane.
+- The caller's resolved container is active in the FEAT-003 registry but the caller's tmux pane (composite key) is not present in the FEAT-004 `panes` table. `register-self` MUST trigger one focused FEAT-004 pane rescan scoped to the caller's container (re-using the FEAT-004 `scan_panes` codepath bounded to a single container) before declaring the pane unknown. If after the focused rescan the pane is still absent, `register-self` MUST refuse with the closed-set error code `pane_unknown_to_daemon` and instruct the caller to run `agenttower scan --panes` from the host.
+- The caller's resolved tmux pane is in the FEAT-004 registry but `active=false`. `register-self` MUST treat this as the same `pane_unknown_to_daemon` reason path: trigger one focused rescan; if the pane reappears as active, proceed; otherwise refuse.
+- The same composite pane key was previously bound to an agent that is now `active=false` (the pane disappeared and reappeared). Re-running `register-self` from that pane MUST re-activate the existing agent row (preserving `agent_id`, `created_at`, and `parent_agent_id`) and update mutable fields rather than creating a new agent.
+- A second register-self call comes from a *different* composite pane key than the first registration of an agent. AgentTower MUST treat this as a *new* agent (bound to the new pane key); the old agent record MUST stay in history with whatever `active` flag the FEAT-004 reconciliation last assigned. FEAT-006 MUST NOT attempt to re-bind an existing agent to a different pane.
+- Two `register-self` calls run concurrently from the same pane (e.g., a wrapper script and a manual invocation). Both MUST converge on the same `agent_id`; the second call's mutable-field writes MUST not race with the first call's insert. Concurrent registrations from *different* panes MUST proceed independently.
+- The label, project path, or any other free-text field contains NUL bytes, terminal control bytes, or shell metacharacters. The fields MUST be sanitized using the FEAT-004 sanitization rules and bounded per-field (label ≤ 64 chars, project_path ≤ 4096 chars). Oversized values MUST be rejected with `error: field <name> exceeds maximum length <n>` and the closed-set error code `field_too_long` rather than silently truncated.
+- A `--role`, `--capability`, or `--parent` value is outside the closed set. The CLI MUST reject with the closed-set error code `value_out_of_set` and list the valid values in the actionable message.
+- `set-role --target <id> --role swarm` is requested. The change MUST be rejected with the closed-set error code `swarm_role_via_set_role_rejected` (FR-012) — the rejection is unconditional (the agent's existing `parent_agent_id` does NOT matter; swarm role can only be assigned during `register-self --parent`, never via `set-role` alone). To convert an existing non-swarm agent into a swarm, the operator MUST re-register from the original pane with `--role swarm --parent <id>`.
+- `set-role --target <id> --role <r>` for an `<id>` that does not exist or is `active=false`. The CLI MUST reject with `error: agent <id> not found` (closed-set code `agent_not_found`) or `error: agent <id> is inactive` (`agent_inactive`) respectively.
+- `set-role --target <id> --role master --confirm` for an agent in container that is itself `active=false` (FEAT-003 marked the container inactive between scans). The CLI MUST reject with `agent_inactive` and refuse the promotion; the operator must re-establish the pane in an active container before re-attempting promotion.
+- The daemon receives a `register-self` call whose container_id and pane composite key resolve cleanly, but the bench user (FEAT-004 `container_user`) returned by FEAT-003/FEAT-004 differs from the socket peer's effective uid name. FEAT-006 MUST proceed with registration (the FEAT-002 socket-file authorization already gates host-user-only access; the in-container bench user is descriptive metadata, not an authorization boundary) but MUST surface the bench user verbatim in `list-agents` so the operator can audit it.
+- The daemon is a *newer* schema than this CLI build supports. `register-self`, `list-agents`, `set-role`, `set-label`, and `set-capability` MUST inherit the FEAT-005 forward-compat policy: surface `schema_version_newer` and refuse the call without corrupting state.
+- The daemon is unreachable. Every CLI in this feature MUST exit with the existing FEAT-002 daemon-unavailable exit code (`2`) and message; the daemon stays alive (it never saw the call).
+- A `register-self` invocation specifies `--role unknown` explicitly. The call MUST be accepted (the `unknown` role is part of the closed set) but the agent's `effective_permissions` MUST yield `can_send=false, can_receive=false` (architecture §18: "unknown cannot send or receive input").
+- A `--project` path is relative, contains `..`, or contains a NUL byte. The CLI MUST reject with the closed-set error code `project_path_invalid` and refuse to register; the project path MUST be a non-empty absolute path with no NUL bytes. The path MUST NOT be required to exist on the host filesystem (it is observable inside the container, not on the host) — only its shape is validated.
+- The agent registry is queried with `list-agents --container <id-or-name>` where the filter matches no rows. The CLI MUST exit `0` with an empty result set (this is not an error — it is a valid query outcome).
+- The agent registry contains an inactive agent whose pane has been reused by FEAT-004 for a different agent registration in a later scan. Both rows MUST coexist; the inactive agent's history is preserved, the new agent has its own `agent_id`, and `list-agents --active-only` shows only the active one.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+#### Identity & lifecycle
+
+- **FR-001**: AgentTower MUST persist agents in a new SQLite `agents` table whose primary key is a stable, opaque `agent_id` of the form `agt_<12-character-lowercase-hex>` (48 bits of entropy — 12 hex chars × 4 bits — generated on first registration of a pane and never regenerated for that agent record). The format is strictly case-sensitive: only `[0-9a-f]` is accepted in the hex portion; mixed-case or uppercase inputs (e.g., `agt_ABC123def456`) MUST be rejected with `value_out_of_set` rather than normalized to lowercase. On `INSERT`, the daemon MUST handle PK-collision via a bounded retry loop (≤ 5 attempts) under the per-(container_id, pane_composite_key) registration mutex; an exhausted retry budget MUST surface as `internal_error` (FR-035) and the daemon MUST stay alive. Five attempts is overwhelmingly conservative at MVP scale: birthday-bound, the first expected collision is at ~2^24 ≈ 16M unique agents — far beyond any plausible MVP fleet — so expected retries are essentially zero.
+- **FR-002**: Each agent record MUST carry, as immutable fields set at creation time: `agent_id`, `created_at`, the FEAT-004 pane composite key tuple `(container_id, tmux_socket_path, tmux_session_name, tmux_window_index, tmux_pane_index, tmux_pane_id)`, and `parent_agent_id` (nullable; only populated when the original `register-self` used `--role swarm --parent <id>`).
+- **FR-003**: Each agent record MUST carry, as mutable fields that `register-self` and the explicit `set-*` commands may update: `role`, `capability`, `label`, `project_path`, `last_registered_at`, `last_seen_at`, `active`, and the derived `effective_permissions` JSON column (recomputed on every role write).
+- **FR-004**: The set of valid `role` values is the closed set `{master, slave, swarm, test-runner, shell, unknown}`. Tokens are lowercase and case-sensitive; mixed-case inputs (`Slave`, `MASTER`, `Test-Runner`) MUST be rejected with `value_out_of_set` and MUST NOT be normalized. Any value outside the closed set MUST be rejected with the closed-set error code `value_out_of_set`. The actionable message MUST list the canonical lowercase tokens.
+- **FR-005**: The set of valid `capability` values is the closed set `{claude, codex, gemini, opencode, shell, test-runner, unknown}`. Tokens are lowercase and case-sensitive; mixed-case inputs (`Claude`, `CODEX`) MUST be rejected with `value_out_of_set` and MUST NOT be normalized. Any value outside the closed set MUST be rejected with the closed-set error code `value_out_of_set`. The actionable message MUST list the canonical lowercase tokens.
+- **FR-006**: An agent's binding to a FEAT-004 pane composite key is immutable for the life of the agent record. A `register-self` call from a *different* composite key MUST create a new agent record rather than re-binding an existing one. FEAT-006 MUST NOT provide any CLI surface for re-binding; that capability is deferred to a later feature.
+- **FR-007**: When `register-self` is called from a composite pane key that already has an agent record, AgentTower MUST treat the call as idempotent: the existing `agent_id` is returned, mutable fields supplied on the call replace the corresponding stored fields, mutable fields not supplied are left unchanged, and `last_registered_at` is updated to the current daemon clock. The agent's `created_at`, `parent_agent_id`, and pane composite key MUST NOT change. "Supplied" means the user explicitly passed the flag on the command line; argparse-style CLI defaults (e.g., `--role unknown`, `--capability unknown`, `--label ""`, `--project ""`) MUST NOT be transmitted on the wire when the user did not pass the flag, so idempotent re-runs preserve the stored values rather than silently demoting role or clearing label/project. The CLI MUST distinguish "flag omitted" from "flag explicitly set to default value" and the daemon's `register_agent` request envelope MUST encode each mutable field as either present-with-value or absent.
+- **FR-008**: When `register-self` is called from a composite pane key whose existing agent record is `active=false` (the pane was previously registered, then disappeared, then reappeared), AgentTower MUST re-activate the existing record (set `active=true`, update mutable fields per FR-007) rather than creating a new agent.
+- **FR-009**: An agent's `active` flag MUST mirror the bound pane's FEAT-004 `active` flag at the most recent FEAT-004 pane scan that observed (or failed to observe) the pane. When FEAT-004 transitions a pane from active to inactive, the bound agent MUST also transition to inactive in the same SQLite transaction; when FEAT-004 transitions a pane from inactive to active (the pane reappeared), the bound agent's flag MUST NOT auto-flip — re-activation requires an explicit `register-self` call from inside that pane.
+- **FR-009a**: Every FEAT-004 pane scan that observes an agent's bound pane as active MUST update the agent's `last_seen_at` column to the scan timestamp in the same SQLite transaction as the pane reconciliation. Scans that fail to observe the bound pane (or observe it as inactive) MUST NOT update `last_seen_at`. `last_seen_at` is independent of `last_registered_at`: the former records passive pane observation by the FEAT-004 scanner; the latter records explicit `register-self` intent. FEAT-006 MUST NOT update `last_seen_at` from any other codepath (CLI calls, list-agents, set-role, set-label, set-capability MUST NOT touch `last_seen_at`).
+
+#### Master safety boundaries
+
+- **FR-010**: `register-self` MUST reject any call that includes `--role master`, regardless of whether `--confirm` is also passed, with the closed-set error code `master_via_register_self_rejected` and the actionable message `register-self cannot assign role=master; register first, then run \`agenttower set-role --role master --confirm\``.
+- **FR-011**: `set-role --role master` MUST require an explicit `--confirm` flag. Calls without `--confirm` MUST be rejected with the closed-set error code `master_confirm_required` and MUST NOT modify the agent record. Calls with `--confirm` MUST succeed if and only if the target agent exists, is `active=true`, and the target's bench container is `active=true`. The activeness check MUST be performed atomically with the role write inside one `BEGIN IMMEDIATE` SQLite transaction: (a) `BEGIN IMMEDIATE`; (b) re-SELECT `agents.active` for the target AND `containers.active` for the agent's bound `container_id`; (c) if either column is `0`, `ROLLBACK` and return `agent_inactive` (no role mutation, no `effective_permissions` recomputation, no JSONL audit row); (d) UPDATE the role and `effective_permissions`; (e) append the JSONL audit row; (f) `COMMIT`. SQLite's `BEGIN IMMEDIATE` serializes the master-promotion transaction against any concurrent FEAT-004 reconciliation transaction so the validate-then-write window is closed at the SQLite level.
+- **FR-012**: `set-role --role <r>` for `<r>` ∈ `{slave, test-runner, shell, unknown}` MUST NOT require `--confirm`. `set-role --role swarm` MUST be rejected (closed-set code `swarm_role_via_set_role_rejected`) — swarm role assignment is only valid via `register-self --role swarm --parent <id>` because it requires the parent linkage in the same operation.
+- **FR-013**: Demotion from `master` to any other valid role MUST NOT require `--confirm`. The current FEAT-006 master safety boundary is asymmetric: promotion requires explicit confirmation; demotion does not. (FEAT-009 / FEAT-010 may layer additional checks for in-flight prompts when those features ship; FEAT-006 MUST NOT pre-empt that design.)
+- **FR-014**: Every successful role transition (any path that mutates `agents.role`, including the initial assignment when a brand-new agent row is created) MUST append exactly one JSONL audit record containing: `agent_id`, `prior_role`, `new_role`, `confirm_provided` (boolean), `socket_peer_uid`, and the daemon clock timestamp. The initial assignment on first `register-self` MUST be logged with `prior_role: null` and `confirm_provided: false`, and this MUST happen regardless of which role was assigned (including the default `--role unknown` case). `confirm_provided` MUST be the literal boolean the operator passed in the request's `confirm` parameter — `true` when `--confirm` was passed by the CLI caller, `false` when it was not — and MUST NOT be rewritten based on whether `--confirm` was *required* by the transition. Demotion from master with a redundant `--confirm` MUST log `confirm_provided: true`; `set-role` to any non-master role with redundant `--confirm` MUST also log `confirm_provided: true`; `register-self` creation MUST log `confirm_provided: false`. Idempotent re-registration that does not change `agents.role` MUST NOT append a new audit row (consistent with FR-027 — no-op writes are not logged); only writes that actually transition `agents.role` from one value to another are logged. Failed role transitions MUST NOT append a JSONL record (failures are surfaced through the socket response and CLI exit code only).
+
+#### Swarm parent linkage
+
+- **FR-015**: `register-self --role swarm` MUST require `--parent <agent-id>`. Missing `--parent` MUST be rejected with the closed-set error code `swarm_parent_required`.
+- **FR-016**: `register-self --parent <agent-id>` MUST require `--role swarm`. Combining `--parent` with any other role MUST be rejected with the closed-set error code `parent_role_mismatch`.
+- **FR-017**: When `--parent <agent-id>` is supplied, AgentTower MUST resolve the parent in the `agents` table and validate: (a) the parent exists (else `parent_not_found`); (b) the parent is `active=true` (else `parent_inactive`); (c) the parent has `role=slave` (else `parent_role_invalid`). Any failure MUST short-circuit the call before any agent row is written.
+- **FR-018**: A swarm agent's `parent_agent_id` MUST be persisted as immutable metadata on creation (per FR-002). FEAT-006 MUST NOT provide any CLI surface for changing `parent_agent_id`; re-parenting is deferred. If the parent agent is later demoted, deleted, or marked inactive, the swarm child's `parent_agent_id` MUST remain pointing at the historical parent; downstream features (FEAT-009, FEAT-010) decide what to do with stale parent links.
+- **FR-018a**: When `register-self` is re-run on an existing agent and explicitly passes `--parent <id>`: (a) if `<id>` equals the stored `parent_agent_id`, the call MUST proceed as an idempotent no-op success per FR-007 (returns the same `agent_id`, updates `last_registered_at`, applies any other supplied mutable fields); (b) if `<id>` differs from the stored `parent_agent_id` (including the case where the stored value is NULL and `<id>` is non-null, or the stored value is non-null and `<id>` is null/different), the call MUST be rejected with the closed-set error code `parent_immutable`, no mutable fields (role, capability, label, project_path) MUST be updated by this call even if other fields were also supplied, no JSONL audit record MUST be appended, and the SQLite transaction MUST be rolled back. The rejection is atomic and all-or-nothing.
+- **FR-019**: `parent_agent_id` MUST always reference an agent with `role=slave` *at the time of swarm creation*. AgentTower MUST NOT enforce any continuing relationship constraint after creation (that is a routing concern for FEAT-009/FEAT-010).
+- **FR-020**: Nested swarms (a swarm whose parent is itself a swarm) MUST be rejected at registration time per FR-017(c). Architecture §11 keeps the MVP swarm tree exactly two levels deep (slave → swarm); deeper nesting is deferred.
+
+#### Effective permission derivation
+
+- **FR-021**: AgentTower MUST materialize `effective_permissions` on every agent row as a JSON object with the closed-set fields `{can_send: bool, can_receive: bool, can_send_to_roles: [<role>...]}`, recomputed on every write that mutates `role`. The derivation rule for FEAT-006 is: `master` → `{can_send: true, can_receive: false, can_send_to_roles: ["slave", "swarm"]}`; `slave` → `{can_send: false, can_receive: true, can_send_to_roles: []}`; `swarm` → `{can_send: false, can_receive: true, can_send_to_roles: []}`; `test-runner` → `{can_send: false, can_receive: false, can_send_to_roles: []}`; `shell` → `{can_send: false, can_receive: false, can_send_to_roles: []}`; `unknown` → `{can_send: false, can_receive: false, can_send_to_roles: []}`.
+- **FR-022**: `effective_permissions` MUST be exposed verbatim in `list-agents --json` output and summarized in the human-readable `list-agents` form. FEAT-006 MUST NOT consume `effective_permissions` for any decision; it materializes the derived state for FEAT-009 and FEAT-010 to consume later.
+
+#### Daemon socket API
+
+- **FR-023**: The daemon socket API MUST expose five new methods reusing the FEAT-002 newline-delimited JSON request/response framing and host-user authorization (`0600`, host user only): `register_agent`, `list_agents`, `set_role`, `set_label`, `set_capability`. Each method MUST return a closed-set response envelope consistent with FEAT-002/FEAT-003/FEAT-004.
+- **FR-024**: `register_agent` MUST accept the resolved container id and the resolved pane composite key as inputs alongside the user-supplied role/capability/label/project/parent fields. The CLI is responsible for resolving the container id (via FEAT-005) and the pane composite key (via `$TMUX` / `$TMUX_PANE` and a focused FEAT-004 lookup); the daemon MUST NOT re-derive container identity from the socket peer.
+- **FR-025**: `list_agents` MUST be read-only, MUST NOT call Docker or tmux, MUST NOT acquire any registration mutex, and MUST return the latest committed SQLite state with a deterministic order: `active DESC, container_id ASC, parent_agent_id NULLS FIRST, label ASC, agent_id ASC`.
+- **FR-026**: `list_agents` MUST accept these filters in the request envelope: `role` (single role or list of roles), `container_id` (full id or 12-char short prefix), `active_only` (boolean), `parent_agent_id` (full id, used to fetch swarm children of a given slave). Filters MUST compose with AND semantics. Unknown filter keys MUST be rejected with the closed-set error code `unknown_filter`. All filter values are matched case-sensitively against the lowercase canonical form: `role` values not in the FR-004 closed set (incl. mixed-case) MUST be rejected with `value_out_of_set`; mixed-case `container_id` / `parent_agent_id` filter values MUST be rejected with `value_out_of_set` rather than normalized.
+- **FR-027**: `set_role`, `set_label`, and `set_capability` MUST be idempotent — calling each with the value the agent already has MUST succeed without error and MUST NOT append a duplicate JSONL audit record (no-op writes are not logged; only actual transitions are logged per FR-014).
+
+#### CLI surface
+
+- **FR-028**: `agenttower register-self` MUST accept the flags `--role <r>` (default `unknown`, applied only on first registration of a pane), `--capability <c>` (default `unknown`, applied only on first registration), `--label <l>` (default empty string, applied only on first registration), `--project <path>` (default empty, applied only on first registration), `--parent <agent-id>` (only valid with `--role swarm`), and `--json` (emit one JSON object on stdout; suppress human-readable output). For idempotent re-registration of an existing pane, defaults MUST NOT be transmitted: only flags the user explicitly passed on the command line MUST be sent in the `register_agent` request envelope, so per FR-007 unsupplied fields leave the stored row unchanged. On success the JSON MUST contain `agent_id`, `role`, `capability`, `label`, `project_path`, `parent_agent_id`, the resolved pane composite key, and `effective_permissions`.
+- **FR-029**: `agenttower list-agents` MUST print a stable, scriptable human-readable form by default and a JSON form under `--json`. The default form MUST emit tab-separated values (TSV) with a required header row as the first output line, and a locked column set in this exact order: `AGENT_ID`, `LABEL`, `ROLE`, `CAPABILITY`, `CONTAINER`, `PANE`, `PROJECT`, `PARENT`, `ACTIVE`. `AGENT_ID` MUST render as the full `agt_<12-character-lowercase-hex>` form (16 chars total). `CONTAINER` MUST render as the bare 12-character short container id (no prefix). `PARENT` MUST render as the full `agt_<12-character-lowercase-hex>` form (16 chars total) when `parent_agent_id` is non-null and as the literal `-` (single ASCII hyphen) when null. Only the `CONTAINER` column uses the bare-12-char short form; every agent-id-bearing column (`AGENT_ID`, `PARENT`) uses the full `agt_<12-hex>` form so operator pipelines (grep, awk by full id) compose uniformly across columns. `PANE` MUST render as `<session>:<window>.<pane>` using the FEAT-004 short pane form. `ACTIVE` MUST render as the literal `true` or `false`. Any future fields added to the agent record MUST NOT be added to the default form; they MUST be exposed via `--json` or a separately-introduced `--wide` flag, so this column set is a stable contract for operator scripts and snapshot tests. `--json` MUST emit every field listed in FR-003 plus the immutable fields from FR-002. The command MUST accept `--role`, `--container`, `--active-only`, and `--parent` filters mirroring the daemon API in FR-026.
+- **FR-030**: `agenttower set-role --target <agent-id> --role <r>` MUST accept `--confirm` and `--json`. Without `--confirm`, the CLI MUST refuse `--role master` per FR-011. The CLI MUST refuse `--role swarm` per FR-012. Successful invocations MUST print the prior role and new role (or emit them in JSON).
+- **FR-031**: `agenttower set-label --target <agent-id> --label <l>` and `agenttower set-capability --target <agent-id> --capability <c>` MUST validate inputs against FR-005 (capability) and the per-field bounds (FR-033) and emit a stable success summary or an actionable error.
+- **FR-032**: All five CLI commands in this feature MUST inherit the FEAT-005 socket-resolution priority order (`AGENTTOWER_SOCKET` → in-container default → host default) and the FEAT-005 / FEAT-002 daemon-unreachable exit-code-`2` behavior. None of these commands MUST start the daemon implicitly; the operator runs `agenttower ensure-daemon` separately.
+
+#### Sanitization, transactionality, schema
+
+- **FR-033**: Free-text fields MUST be sanitized of NUL bytes and terminal control bytes and bounded per-field: `label` ≤ 64 chars, `project_path` ≤ 4096 chars. Oversized values MUST be rejected with the closed-set error code `field_too_long` (registration MUST NOT silently truncate).
+- **FR-034**: `project_path` MUST be a non-empty absolute path when supplied (must start with `/`, must not contain NUL, must not contain a `..` segment after normalization). The path MUST NOT be required to resolve to an existing host filesystem entry — it is observed from inside the container and may name a path that exists only in the container's mount namespace.
+- **FR-035**: A `register-self`, `set-role`, `set-label`, or `set-capability` write MUST commit in a single SQLite transaction together with its derived `effective_permissions` recomputation. If the transaction fails, AgentTower MUST roll it back, MUST NOT append a JSONL audit record, MUST keep the daemon alive, and MUST return `internal_error` over the socket.
+- **FR-036**: The SQLite migration from the FEAT-005 schema version to the FEAT-006 schema version MUST run in one transaction, MUST be idempotent on re-open, MUST create the new `agents` table even for an otherwise unchanged FEAT-005 database, and MUST bump `schema_version` only after the new table exists. Migration failure MUST roll back and refuse to serve the daemon.
+- **FR-037**: FEAT-006 MUST NOT modify the FEAT-001/FEAT-002/FEAT-003/FEAT-004 schemas beyond additive read access. The `agents` table MUST reference the FEAT-004 pane composite key by value (denormalized columns) rather than by foreign-key constraint, because FEAT-004 panes can transition active/inactive across scans and reuse pane ids — referential integrity is enforced at the application layer, not at the SQLite schema layer.
+
+#### Concurrency
+
+- **FR-038**: The daemon MUST serialize concurrent `register_agent` requests addressing the *same* pane composite key through a per-(container_id, pane_composite_key) advisory in-process mutex so the second concurrent caller observes the first's committed state and converges on the same `agent_id`. Concurrent `register_agent` requests addressing *different* composite keys MUST proceed in parallel. The per-key mutex covers `register_agent` against other `register_agent` calls only; it MUST NOT be acquired by FEAT-004 pane reconciliation. Cross-subsystem ordering between a `register_agent` transaction and a FEAT-004 reconciliation transaction touching the same `agents` row is provided exclusively by SQLite's `BEGIN IMMEDIATE` semantics — both transactions remain atomic, neither observes a partial write from the other, and the transaction that commits last wins for any overlapping mutable column. `SQLITE_BUSY` MUST surface as `internal_error` (FR-035) without daemon-side retry.
+- **FR-039**: `set_role`, `set_label`, `set_capability` requests MUST be serialized per-(agent_id) through the same advisory mutex pattern. SQLite's single-writer semantics serialize commits internally; the in-process mutex is required only to keep read-modify-write of `effective_permissions` consistent.
+
+#### Failure modes
+
+- **FR-040**: Each CLI in this feature MUST surface a stable, closed-set error code on every failure path. The closed set comprises at least: `daemon_unavailable`, `not_in_tmux`, `tmux_pane_malformed`, `host_context_unsupported`, `container_unresolved`, `pane_unknown_to_daemon`, `agent_not_found`, `agent_inactive`, `parent_not_found`, `parent_inactive`, `parent_role_invalid`, `parent_role_mismatch`, `parent_immutable`, `swarm_parent_required`, `swarm_role_via_set_role_rejected`, `master_via_register_self_rejected`, `master_confirm_required`, `value_out_of_set`, `field_too_long`, `project_path_invalid`, `unknown_filter`, `bad_request`, `internal_error`, `schema_version_newer`. New codes MAY be added later but the existing set MUST remain stable. Error codes MUST appear verbatim in `--json` output. Note: `daemon_unavailable` is a CLI-side classification (the daemon never received the call); it is NOT a member of the daemon-side `socket_api/errors.py:CLOSED_CODE_SET` and MUST NOT be raised by daemon code.
+- **FR-041**: When `register-self` is invoked from a pane whose composite key is not yet known to the FEAT-004 registry, AgentTower MUST trigger one focused FEAT-004 pane rescan scoped to the caller's resolved container before declaring the pane unknown. The rescan MUST reuse the FEAT-004 `scan_panes` codepath, MUST be bounded by the FEAT-004 5-second per-call timeout, MUST be limited to the caller's container, and MUST NOT cascade to other containers. If after the rescan the pane is still absent, `register-self` MUST refuse with `pane_unknown_to_daemon`.
+- **FR-042**: The CLIs in this feature MUST NOT attempt to send any input into any tmux pane, MUST NOT call `docker exec` for any purpose other than the FR-041 focused rescan, MUST NOT modify any pane log, and MUST NOT install any tmux hook. FEAT-006 is registry-only; every other capability is deferred to a later feature.
+
+#### Out-of-scope guarantees
+
+- **FR-043**: FEAT-006 MUST NOT add a network listener, an in-container daemon, prompt delivery, queue inspection, route configuration, log attachment, log offset tracking, event ingestion, automatic swarm inference, multi-master arbitration, TUI, or web UI. The new socket methods inherit the FEAT-002 socket-file authorization (`0600`, host user only) and add no roles or secondary auth checks.
+- **FR-044**: The feature MUST be testable end-to-end without a real Docker daemon, real bench container, or real tmux server, by injecting fake adapter implementations or canned `docker exec` outputs (consistent with FEAT-003/FEAT-004/FEAT-005 testability requirements).
+
+### Key Entities *(include if feature involves data)*
+
+- **Agent Record**: A registered AgentTower agent, persisted as one row in a new SQLite `agents` table. Identified by an opaque `agent_id` of the form `agt_<12-hex>`. Bound to one FEAT-004 pane composite key for life. Stores immutable fields (`agent_id`, `created_at`, pane composite key tuple, `parent_agent_id`) and mutable fields (`role`, `capability`, `label`, `project_path`, `effective_permissions`, `last_registered_at`, `last_seen_at`, `active`).
+- **Pane Composite Key**: The FEAT-004 immutable identity tuple `(container_id, tmux_socket_path, tmux_session_name, tmux_window_index, tmux_pane_index, tmux_pane_id)`. FEAT-006 stores this tuple denormalized on the agent record and uses it as the registration key. Across pane disappear/reappear cycles, the tuple is treated as the same pane only when every component matches.
+- **Effective Permissions**: A derived JSON value `{can_send: bool, can_receive: bool, can_send_to_roles: [<role>...]}` materialized on every agent row from the role per FR-021. Recomputed atomically on every role write.
+- **Role**: A closed-set classification of an agent's responsibility (`master`, `slave`, `swarm`, `test-runner`, `shell`, `unknown`). Drives effective permission derivation. Master assignment requires explicit `--confirm` (per FR-011).
+- **Capability**: A closed-set descriptor of what software the agent runs (`claude`, `codex`, `gemini`, `opencode`, `shell`, `test-runner`, `unknown`). Independent of role.
+- **Parent Linkage**: An immutable `parent_agent_id` reference set only when `register-self --role swarm --parent <id>` succeeds. Validates at registration time that the parent exists, is active, and has `role=slave`. After creation FEAT-006 enforces no continuing constraint on the parent.
+- **Audit Record**: A JSONL row appended to the existing FEAT-001 events file on every successful role transition. Contains `agent_id`, prior role, new role, `confirm_provided`, `socket_peer_uid`, and timestamp.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: With one seeded active bench container hosting one seeded active tmux pane, a single `agenttower register-self --role slave --capability codex --label codex-01 --project /workspace/acme` invocation completes within 500 ms wall-clock (p95) and persists exactly one new agent row whose `agent_id` matches the documented `agt_<12-hex>` shape and whose pane composite key matches the seeded pane.
+- **SC-002**: Re-running the same `register-self` command from the same pane within the same scenario as SC-001 returns the same `agent_id`, leaves the agent count at exactly 1, and updates `last_registered_at` to a strictly later timestamp than the first invocation.
+- **SC-003**: `agenttower register-self --role master --confirm` from a brand-new pane MUST exit non-zero with the closed-set error code `master_via_register_self_rejected`, MUST NOT create an agent row, and MUST NOT append a JSONL audit record. After the rejection, a follow-up `register-self --role slave` succeeds and a subsequent `set-role --role master --confirm` succeeds; the `agents` table contains exactly one row with `role=master`.
+- **SC-004**: `agenttower set-role --role master` (without `--confirm`) against an existing slave agent MUST exit non-zero with the closed-set error code `master_confirm_required` and MUST leave the agent's role unchanged. `list-agents` MUST report `role=slave`.
+- **SC-005**: With one seeded active slave agent and one seeded active different pane, `agenttower register-self --role swarm --parent <slave-id> --capability claude --label claude-swarm-01` MUST exit `0` and persist a new agent row whose `parent_agent_id` matches the slave's id and whose `effective_permissions.can_receive=true`. `list-agents --parent <slave-id>` MUST return exactly that one swarm row.
+- **SC-006**: Each of the five swarm parent failure paths (`parent_not_found`, `parent_inactive`, `parent_role_invalid`, `parent_role_mismatch`, `swarm_parent_required`) MUST exit non-zero with the matching closed-set error code and MUST NOT create an agent row. The five paths together cover every branch of FR-015 / FR-016 / FR-017.
+- **SC-007**: `agenttower list-agents --json` returns valid JSON whose array length equals the registered agent count and whose every object contains every field listed in FR-003, FR-002, and FR-021. Field values MUST be sanitized of NUL bytes and terminal control bytes and bounded per FR-033.
+- **SC-008**: When the caller's resolved pane composite key is not present in the FEAT-004 `panes` table, `register-self` triggers exactly one focused FEAT-004 pane rescan scoped to the caller's container (no cascade to other containers, no global scan), and the rescan completes within the FEAT-004 5-second per-call budget. If the pane appears in the rescan's results, registration succeeds; otherwise it fails with `pane_unknown_to_daemon` and the daemon stays alive.
+- **SC-009**: When the daemon is unreachable, every CLI in this feature exits with code `2` and the existing FEAT-002 daemon-unavailable message; the daemon is never started implicitly. When the caller is on the host shell and FEAT-005 reports `host_context`, `register-self` exits non-zero with `host_context_unsupported`.
+- **SC-010**: Existing FEAT-001/FEAT-002/FEAT-003/FEAT-004/FEAT-005 test suites continue to pass after FEAT-006 is implemented, and the SQLite migration runs cleanly against a database created by a FEAT-005-only build. No FEAT-005 CLI invocation, JSON shape, exit code, or socket method behavior is altered.
+- **SC-011**: The feature has unit coverage for: `agent_id` generation and uniqueness, role/capability closed-set validation, label/project_path sanitization and bounds, idempotent re-registration, re-activation of previously inactive agents, swarm parent validation (all five failure paths plus the success path), `effective_permissions` derivation across all six roles, master-promotion safety (no `--confirm`, via `register-self`, via `set-role`), JSONL audit record shape, and per-(pane composite key) registration mutex serialization.
+- **SC-012**: The feature has integration coverage for: `register-self` from a simulated in-container environment, idempotent re-registration with mutating mutable fields, `list-agents` JSON output, `list-agents` filters (`--role`, `--container`, `--active-only`, `--parent`), `set-role` master promotion path, `set-role` swarm-rejection path, swarm child registration end-to-end, focused FEAT-004 rescan trigger when the pane is unknown, daemon-unreachable CLI path, and host-shell `host_context_unsupported` path — none of which require a real Docker daemon, real container, or real tmux server.
+
+## Assumptions
+
+- The host daemon is the source of truth for the agent registry. There is no in-container daemon, no in-container relay, no network listener, and no secondary auth tier in FEAT-006. The new socket methods inherit the FEAT-002 socket-file authorization (`0600`, host user only) verbatim.
+- FEAT-006 builds on FEAT-005's container identity detection. The CLI resolves the caller's container id from `AGENTTOWER_CONTAINER_ID`, `/proc/self/cgroup`, `/etc/hostname`, or `$HOSTNAME`, then cross-checks against the FEAT-003 `containers` table per FEAT-005 FR-006 / FR-007. Only the `unique_match` outcome makes registration possible; every other outcome (`multi_match`, `no_match`, `no_candidate`, `host_context`) MUST refuse registration.
+- The current tmux pane is resolved from `$TMUX` and `$TMUX_PANE` per FEAT-005 FR-014 / FR-015 and cross-checked against the FEAT-004 `panes` table. Registration requires the resolved pane to appear as `active=true` in the FEAT-004 registry, with one focused per-container FEAT-004 rescan permitted on a miss before declaring the pane unknown (FR-041).
+- The agent_id format is `agt_<12-character-lowercase-hex>` (48 bits of entropy, sufficient to keep accidental collisions vanishingly unlikely at MVP scale — birthday-bound first expected collision at ~16M unique agents). The format is locked for FEAT-006 to keep CLI/JSON contracts stable for FEAT-009 / FEAT-010; bumping to a real 96 bits (24 hex chars) is a coordinated migration in a later feature if scale demands it.
+- The `agents` table is denormalized against the FEAT-004 pane composite key (no foreign-key constraint) because FEAT-004 panes transition active/inactive across scans and reuse pane ids. Application-layer reconciliation is enforced by the FEAT-004 reconciliation rules and FEAT-006's per-(container, composite-key) mutex (FR-038).
+- Master promotion requires an explicit `--confirm` flag passed at the CLI layer. FEAT-006 does not require any out-of-band confirmation channel (no two-factor, no separate operator channel, no host-vs-container distinction beyond the existing socket-file authorization). The `--confirm` flag is the explicit human-controlled gate; this matches the architecture's "no silent promotion" rule while keeping MVP friction low.
+- Swarm hierarchy is exactly two levels deep in MVP (slave → swarm). Nested swarms (swarm-of-swarm) are explicitly rejected at registration time per FR-017 / FR-020. Deeper nesting can be enabled in a later feature without breaking the FEAT-006 schema (only the parent-role validation rule changes).
+- `effective_permissions` is materialized on the agent row but not consumed by FEAT-006. FEAT-006 provides the derived state for FEAT-009 (input delivery) and FEAT-010 (routing) to read; downstream features MAY layer additional dynamic checks (in-flight prompt arbitration, per-target queue ordering) but the role-derived static permissions remain the FEAT-006 contract.
+- Re-binding an existing agent to a different pane composite key (for example, when an agent's tmux pane is destroyed and re-created with a different pane id) is out of scope for FEAT-006. The new pane registers as a new agent; the operator can reconcile manually via labels and project paths. A first-class re-bind command can be added later without breaking the FEAT-006 schema.
+- Automatic swarm inference (detecting that a newly discovered pane is likely a child of an existing slave based on container, session, command, or timing) is out of scope for FEAT-006 per the architecture's "explicit swarm reporting" stance. FEAT-010 owns inferred swarm parentage.
+- The FEAT-004 focused per-container rescan triggered by FR-041 is a read-only scoped invocation of FEAT-004's existing scan codepath. FEAT-006 MUST NOT introduce any new pane-discovery codepath. If FEAT-004 ever adds a request-scoped scan-one-container API, FEAT-006 SHOULD adopt it; otherwise FEAT-006 invokes the existing scan path with a single-element container set.
+- The JSONL audit record for role transitions is appended to the existing FEAT-001 `events.jsonl` file. FEAT-006 MUST NOT introduce a new audit log file.
+- Project paths are validated for shape (absolute, no NUL, no `..` segment after normalization) but not for existence. The path is observed inside the container's mount namespace and may not exist on the host filesystem. Existence checks belong to a later feature that can perform `docker exec` validation if it ships.
+- Concurrent `register-self` calls from different panes are common in the master-driven swarm pattern (the master prompts a slave, the slave prompts each child to register itself in parallel). FEAT-006's per-(composite-key) mutex (FR-038) is sufficient because each child has a distinct pane composite key; no global registration mutex is required.
+- All in-container subprocess work invoked by FEAT-006 (limited to the FR-041 focused FEAT-004 rescan) inherits FEAT-004's threat model and bounded sanitization. FEAT-006 introduces no new in-container subprocess shapes.
diff --git a/specs/006-agent-registration/tasks.md b/specs/006-agent-registration/tasks.md
new file mode 100644
index 0000000..acd611a
--- /dev/null
+++ b/specs/006-agent-registration/tasks.md
@@ -0,0 +1,315 @@
+---
+description: "Task list for FEAT-006 Agent Registration and Role Metadata"
+---
+
+# Tasks: Agent Registration and Role Metadata
+
+**Input**: Design documents from `/specs/006-agent-registration/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/cli.md, contracts/socket-api.md, quickstart.md
+
+**Tests**: Test tasks are INCLUDED — SC-011 (unit) and SC-012 (integration) explicitly enumerate required coverage; plan.md lists every required test file.
+
+> **Implementation note (2026-05-07):** Source-code tasks T001–T086 land file-for-file as the spec lists. The 30+ separately-listed *integration* test files (T037–T052, T069–T078, T084–T086) were consolidated into two end-to-end files for compactness: `tests/integration/test_cli_register_self_e2e.py` (US1: 4 scenarios) and `tests/integration/test_cli_us2_us3_e2e.py` (US2/US3/host-context: 5 scenarios). Each consolidated test maps to a spec acceptance scenario (SC-001 through SC-009). All unit tests T012–T017, T026–T036, T062–T068, T082–T083 land file-for-file. T093 (full pytest suite) passes — see commit message for the count.
+
+**Organization**: Tasks are grouped by user story (US1, US2, US3) to enable independent implementation and testing. Within each user story, tasks follow data → service → CLI → tests order with [P] markers for parallelizable work.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies on incomplete tasks)
+- **[Story]**: User story tag (US1 / US2 / US3); Setup / Foundational / Polish phases have no story tag
+- Exact absolute or repo-relative file paths included in every task
+
+## Path Conventions
+
+Single-project Python CLI + daemon. Paths shown are repo-relative; the project root is `/workspace/projects/AgentTower-worktrees/006-agent-registration`. Implementation lives under `src/agenttower/`; tests under `tests/unit/` and `tests/integration/`.
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Create the new `agents/` package skeleton. The repository already has `pyproject.toml`, console entrypoints (`agenttower`, `agenttowerd`), and the FEAT-001..005 module tree; no project-level initialization is required.
+
+- [x] T001 Create `src/agenttower/agents/` package directory and write `src/agenttower/agents/__init__.py` with module docstring referencing FEAT-006 plan.md and a re-exports stub block (entries filled in later tasks)
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Schema migration, closed-set error codes, pure helpers, and audit writer. Every user story depends on these completing first. No story-specific behavior here.
+
+⚠️ **CRITICAL**: No user story work may begin until this phase is complete.
+
+### Schema and persistence
+
+- [x] T002 Bump `CURRENT_SCHEMA_VERSION` from `3` to `4` in `src/agenttower/state/schema.py` and add `_apply_migration_v4(conn)` that creates the `agents` table (per data-model.md §2.1) plus the three indexes (`agents_active_order`, `agents_parent_lookup`, `agents_pane_lookup`) using `CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS` guards; register the function in `_MIGRATIONS[4]`; update `_ensure_current_schema` to call `_apply_migration_v4` defensively in the v4-already-current branch (mirroring the existing v2/v3 pattern at lines 234-237)
+- [x] T003 [P] Create `src/agenttower/state/agents.py` with the `AgentRecord` frozen dataclass (data-model.md §4.1), `PaneCompositeKey` dataclass, and read/write helpers (`insert_agent`, `update_agent`, `select_agent_by_pane_key`, `select_agent_by_id`, `list_agents` with FR-026 filters and FR-025 deterministic ordering, `update_last_seen_at`, `cascade_active_from_pane`); use `agents.permissions.effective_permissions` to materialize the JSON column on every write; pure data-access only (no mutex acquisition, no validation logic)
+
+### Closed-set error codes
+
+- [x] T004 [P] Extend `src/agenttower/socket_api/errors.py` with the FEAT-006 `Final[str]` constants listed in research.md R-010 (`HOST_CONTEXT_UNSUPPORTED`, `CONTAINER_UNRESOLVED`, `NOT_IN_TMUX`, `TMUX_PANE_MALFORMED`, `PANE_UNKNOWN_TO_DAEMON`, `AGENT_NOT_FOUND`, `AGENT_INACTIVE`, `PARENT_NOT_FOUND`, `PARENT_INACTIVE`, `PARENT_ROLE_INVALID`, `PARENT_ROLE_MISMATCH`, `PARENT_IMMUTABLE`, `SWARM_PARENT_REQUIRED`, `SWARM_ROLE_VIA_SET_ROLE_REJECTED`, `MASTER_VIA_REGISTER_SELF_REJECTED`, `MASTER_CONFIRM_REQUIRED`, `VALUE_OUT_OF_SET`, `FIELD_TOO_LONG`, `PROJECT_PATH_INVALID`, `UNKNOWN_FILTER`, `SCHEMA_VERSION_NEWER`); extend `CLOSED_CODE_SET` with the union; preserve existing FEAT-002/003/004 entries byte-for-byte
+
+### Pure helpers (independent files; parallelizable)
+
+- [x] T005 [P] Create `src/agenttower/agents/identifiers.py` with `generate_agent_id() -> str` returning `"agt_" + secrets.token_hex(6)` (research R-001); add `AGENT_ID_RE = re.compile(r"^agt_[0-9a-f]{12}$")` and `validate_agent_id_shape(value: str) -> None` that raises a closed-set error on mismatch (case-sensitive per Clarifications session 2026-05-07-continued)
+- [x] T006 [P] Create `src/agenttower/agents/permissions.py` with `effective_permissions(role: str) -> dict` returning the closed-set object per FR-021 across all six roles (data-model.md §4.3 table); also export `serialize_effective_permissions(role: str) -> str` that returns the JSON column value with stable key ordering `["can_send", "can_receive", "can_send_to_roles"]`
+- [x] T007 [P] Create `src/agenttower/agents/validation.py` with: `VALID_ROLES = ("master","slave","swarm","test-runner","shell","unknown")`; `VALID_CAPABILITIES = ("claude","codex","gemini","opencode","shell","test-runner","unknown")`; `validate_role(value)`, `validate_capability(value)` (case-sensitive per Clarifications); `validate_label(value) -> str` (NUL-strip, C0-strip via `agenttower.tmux.parsers.sanitize_text`, ≤ 64 chars, raise `field_too_long` on over-bound — never truncate); `validate_project_path(value)` (non-empty, absolute, NUL-free, no `..` segment after normalization, ≤ 4096 chars, raise `project_path_invalid` or `field_too_long`); each validator raises a typed exception carrying the closed-set code so the service layer can map to the wire envelope
+- [x] T008 [P] Create `src/agenttower/agents/audit.py` with `append_role_change(events_file, agent_id, prior_role, new_role, confirm_provided, socket_peer_uid, ts_utc)` that serializes one JSONL row per data-model.md §4.4 (event_type=`agent_role_change`, prior_role JSON literal `null` on creation per Clarifications Q4) and appends via `events.writer.append_event` (mode `0600`, parent dir `0700`, atomic line append); `confirm_provided` is the literal value the daemon received (Clarifications session 2026-05-07-continued Q5)
+
+### Mutex registry
+
+- [x] T009 [P] Create `src/agenttower/agents/mutex.py` with two thread-safe per-key mutex registries: `RegisterLockMap` keyed by `(container_id, tmux_socket_path, tmux_session_name, tmux_window_index, tmux_pane_index, tmux_pane_id)` and `AgentLockMap` keyed by `agent_id`; each exposes a `for_key(...) -> threading.Lock` that fetches-or-creates the per-key `threading.Lock` under a guard `threading.Lock` (research R-005); no LRU eviction at MVP scale; both maps live for the daemon process lifetime
+
+### Socket-api wiring
+
+- [x] T010 Create `_register_agent`, `_list_agents`, `_set_role`, `_set_label`, `_set_capability` placeholder handlers in `src/agenttower/socket_api/methods.py` that return `errors.make_error(errors.INTERNAL_ERROR, "not implemented")`; add the five entries to `DISPATCH` after the FEAT-004 entries; preserve FEAT-002/003/004 entries byte-for-byte. Service layer (T020, T030..T032) replaces the bodies later — keeping the dispatch wired now lets US1 socket tests develop in parallel.
+- [x] T011 [P] Extend `src/agenttower/socket_api/client.py` with five typed wrappers `register_agent(params)`, `list_agents(params)`, `set_role(params)`, `set_label(params)`, `set_capability(params)` reusing the existing connect / framing logic; raise the existing `DaemonUnavailable` on socket-level failure; surface the `code` field from error envelopes
+
+### Foundational unit tests
+
+- [x] T012 [P] Write `tests/unit/test_agent_id_generation.py` covering FR-001: `agt_<12-hex>` shape; collision retry policy contract (the test seeds the generator to return a duplicate twice, then a fresh value, asserting INSERT path retries up to ≤ 5 attempts and surfaces `internal_error` on exhaustion — research R-001); strict case-sensitive validation rejects `AGT_abc...` and `agt_ABC...`
+- [x] T013 [P] Write `tests/unit/test_role_capability_validation.py` covering FR-004 / FR-005: every closed-set value accepted; out-of-set rejected with `value_out_of_set`; mixed-case (`Slave`, `MASTER`, `Codex`) rejected without normalization (Clarifications session 2026-05-07-continued); actionable message lists canonical lowercase tokens
+- [x] T014 [P] Write `tests/unit/test_label_project_sanitize.py` covering FR-033 / FR-034: NUL strip, C0 control strip, label ≤ 64 chars, project_path ≤ 4096 chars (over-bound raises `field_too_long`, never truncated); project_path empty / relative / `..` / NUL byte raises `project_path_invalid`; multi-byte UTF-8 boundary preserved by sanitize helper inheritance
+- [x] T015 [P] Write `tests/unit/test_effective_permissions.py` covering FR-021: derivation across all six roles; JSON column key ordering stable as `["can_send", "can_receive", "can_send_to_roles"]`; `can_send_to_roles` always a list (incl. empty `[]`)
+- [x] T016 [P] Write `tests/unit/test_schema_v4_migration_unit.py` covering FR-036 / FR-037: fresh DB → v4; v3-only DB upgrades to v4 in one transaction; `agents` table + indexes created on otherwise-unchanged FEAT-005 DB; FEAT-001..004 tables untouched (verified via `sqlite3` schema dump); `_apply_migration_v4` is idempotent (re-call after success is a no-op)
+- [x] T017 [P] Write `tests/unit/test_register_mutex.py` covering FR-038 / FR-039 mutex map behavior: same-key acquisitions serialize, different-key acquisitions parallelize; per-`agent_id` map and per-pane-composite-key map are independent; map entries are not evicted (memory-growth contract)
+
+**Checkpoint**: Foundational layer complete — schema, error codes, pure helpers, audit writer, mutex registry, and dispatch placeholders all in place. User stories may now proceed in parallel where dependencies allow.
+
+---
+
+## Phase 3: User Story 1 — Register an agent from inside a bench-container tmux pane (Priority: P1) 🎯 MVP
+
+**Goal**: Resolve the caller's container id and pane composite key, register (or idempotently re-register / re-activate) the bound agent, and surface the agent through `agenttower list-agents`. Master and swarm-parent paths are deliberately out of scope for this phase — they live in US2 / US3.
+
+**Independent Test**: Per spec.md US1 — seed FEAT-003/004 with one active container + one active pane; simulate "running inside" via FEAT-005 fakes; run `agenttower register-self --role slave --capability codex --label codex-01 --project /workspace/acme`; assert exit `0`, stable `agent_id`, exactly one new agent row, and `list-agents` reflects every required field.
+
+### CLI-side identity resolution and request shaping
+
+- [x] T018 [US1] Create `src/agenttower/agents/client_resolve.py` with `resolve_pane_composite_key(client, env)` that: (a) calls FEAT-005 `config_doctor.runtime_detect.detect_container_runtime` and refuses with `host_context_unsupported` if `host_context`; (b) calls FEAT-005 `config_doctor.identity.resolve_container_identity` and maps `multi_match` / `no_match` / `no_candidate` to `container_unresolved`; (c) parses `$TMUX` and `$TMUX_PANE` (FEAT-005 `tmux_identity`), mapping `$TMUX` unset to `not_in_tmux` and malformed `$TMUX_PANE` to `tmux_pane_malformed`; (d) calls daemon `list_panes(container=<resolved_id>)` and looks up the composite key; (e) on miss, calls `scan_panes(container=<resolved_id>)` exactly once (FR-041; research R-007) and re-queries `list_panes`; (f) refuses with `pane_unknown_to_daemon` if the pane is still absent or `active=false` after rescan
+- [x] T019 [US1] Extend `src/agenttower/cli.py` with the `register-self` subparser using `argparse.SUPPRESS` defaults for `--role`, `--capability`, `--label`, `--project`, `--parent` so omitted flags are absent from the parsed Namespace and not transmitted on the wire (research R-002; Clarifications Q1); add `--json` flag; the handler builds the `register_agent` request envelope by including only keys the user explicitly passed; on first registration of a brand-new pane the handler applies argparse-style defaults (`role="unknown"`, `capability="unknown"`, `label=""`, `project_path=""`) before sending; on idempotent re-registration of an existing pane it does NOT (one `list_panes` round-trip determines which); inherits FEAT-005 socket-resolution chain and FEAT-002 daemon-unavailable exit-code-`2` behavior; renders the FR-028 success line on default and the C-CLI-601 JSON object on `--json`
+
+### Daemon-side service: register_agent
+
+- [x] T020 [US1] Create `src/agenttower/agents/service.py` with class `AgentService` taking `(connection_factory, register_locks, agent_locks, events_file, schema_version)` and method `register_agent(params, socket_peer_uid) -> dict`; implements the validation order from data-model.md §7.3 steps 1-13 minus master/swarm paths (US2/US3 add those): forward-compat schema check; closed-set field shape on present optional keys (FR-004/FR-005/FR-001 case-sensitive); free-text bounds + sanitization (FR-033/FR-034); acquire `register_locks.for_key(...)`; SELECT existing agent for pane composite key; resolve mutable fields per FR-007 + Clarifications Q1 (only-supplied-fields-overwrite); recompute `effective_permissions`; `BEGIN IMMEDIATE`; INSERT new agent (with bounded retry on `agent_id` collision per research R-001) or UPDATE existing; COMMIT; if creation OR role transition: append audit row via `audit.append_role_change` with `confirm_provided=False` (research R-002, Clarifications Q4); release mutex; return success envelope with `created_or_reactivated ∈ {"created","reactivated","updated"}`
+- [x] T021 [US1] Wire the placeholder `_register_agent` handler in `src/agenttower/socket_api/methods.py` (T010) to construct an `AgentService` from `DaemonContext` and call `service.register_agent(params, ctx.socket_peer_uid)`; map closed-set exceptions to `errors.make_error(<code>, <message>)`; map SQLite errors / collision retry exhaustion to `errors.make_error(errors.INTERNAL_ERROR, ...)` with the daemon staying alive (FR-035); pass `events_file=ctx.events_file` and `schema_version=ctx.schema_version`
+
+### Daemon-side service: list_agents (read-only)
+
+- [x] T022 [US1] Add `AgentService.list_agents(params) -> dict` to `src/agenttower/agents/service.py`: validates filter keys against `{role, container_id, active_only, parent_agent_id}` (unknown → `unknown_filter`); validates `role` shape (string or list of strings; values in FR-004 closed set; case-sensitive); validates `container_id` and `parent_agent_id` shapes; calls `state.agents.list_agents(filters)` which composes AND semantics and returns rows in the FR-025 deterministic order via the `agents_active_order` index; assembles the `filter` echo (normalizing `role` to a list) and the `agents` array; MUST NOT call Docker, tmux, mutex, or update `last_seen_at`
+- [x] T023 [US1] Wire `_list_agents` in `src/agenttower/socket_api/methods.py` to `AgentService.list_agents(params)` with closed-set error mapping; preserve FEAT-002 envelope shape
+
+### CLI-side list-agents (locked TSV form)
+
+- [x] T024 [US1] Extend `src/agenttower/cli.py` with the `list-agents` subparser supporting `--role` (repeatable; collected as a list), `--container <id-or-short>`, `--active-only` boolean, `--parent <agent-id>`, `--json`; build the `list_agents` request envelope from supplied filters; render the FR-029 locked TSV form by default with a required header row `AGENT_ID\tLABEL\tROLE\tCAPABILITY\tCONTAINER\tPANE\tPROJECT\tPARENT\tACTIVE`; `AGENT_ID` and `PARENT` render as full `agt_<12-hex>` (PARENT renders `-` when null); `CONTAINER` renders bare 12-char short; `PANE` renders `<session>:<window>.<pane>`; `ACTIVE` renders `true`/`false`; embedded `\t` and `\n` in `LABEL`/`PROJECT` after FR-033 sanitization replaced with single space (matches FEAT-005 cli.md convention); `--json` emits the C-CLI-602 envelope with every field from FR-002/FR-003/FR-021
+
+### FEAT-004 reconciliation wiring (FR-009 / FR-009a)
+
+- [x] T025 [US1] Extend `src/agenttower/discovery/pane_reconcile.py` to UPDATE `agents.last_seen_at = :scan_time` for every pane observed `active=true` in the same `BEGIN IMMEDIATE` transaction as the pane upsert (FR-009a / Clarifications Q2 / research R-003); cascade `agents.active = 0` in the same transaction for every pane that transitions `panes.active 1 → 0` (FR-009); MUST NOT auto-flip `agents.active` to `1` on inactive→active pane transitions (FR-009 — explicit `register-self` is required); MUST NOT acquire FEAT-006 per-key registration mutex (FR-038 / Clarifications session 2026-05-07-continued); cross-subsystem ordering with `register_agent` is provided exclusively by SQLite `BEGIN IMMEDIATE`
+
+### US1 unit tests
+
+- [x] T026 [P] [US1] Write `tests/unit/test_register_idempotency.py` covering FR-007: re-registration with same composite key returns same `agent_id`; mutable fields supplied replace stored, not-supplied left unchanged; `created_at` / `parent_agent_id` / pane composite key never change; `last_registered_at` updates strictly later
+- [x] T027 [P] [US1] Write `tests/unit/test_register_supplied_vs_default.py` covering Clarifications session 2026-05-07 Q1: argparse defaults NOT transmitted on idempotent re-registration; explicit `--role unknown` overwrites whereas omitted `--role` does not; daemon-side absent-vs-present-with-value distinction enforced; on first registration of a brand-new pane the daemon applies the same defaults the CLI applies (symmetric wire contract per research R-002)
+- [x] T028 [P] [US1] Write `tests/unit/test_register_reactivation.py` covering FR-008: re-`register-self` on a previously inactive agent at the same composite key re-activates it preserving `agent_id` / `created_at` / `parent_agent_id`; mutable-field semantics from FR-007 still apply
+- [x] T029 [P] [US1] Write `tests/unit/test_list_agents_filters.py` covering FR-026: `role` / `container_id` / `active_only` / `parent_agent_id` filters compose with AND; `role` accepts string or list; case-sensitivity rejects `Slave`, `ABC123def456`; unknown filter key raises `unknown_filter`
+- [x] T030 [P] [US1] Write `tests/unit/test_list_agents_ordering.py` covering FR-025: deterministic order `active DESC, container_id ASC, parent_agent_id ASC NULLS FIRST, label ASC, agent_id ASC` regardless of insert order; `agents_active_order` index covers the ORDER BY
+- [x] T031 [P] [US1] Write `tests/unit/test_list_agents_tsv_render.py` covering FR-029 / Clarifications Q5 (and 2026-05-07-continued PARENT-form lock): locked nine-column header row; full `agt_<12-hex>` for `AGENT_ID` and `PARENT`; bare 12-char short for `CONTAINER`; `-` for null parent; `<session>:<window>.<pane>` PANE form; `true`/`false` ACTIVE; embedded `\t`/`\n` replaced with single spaces; future-field exclusion enforced by snapshot test
+- [x] T032 [P] [US1] Write `tests/unit/test_pane_reconcile_last_seen.py` covering FR-009a / Clarifications Q2: every FEAT-004 reconciliation transaction observing pane active updates `last_seen_at`; transition active→inactive cascades `agents.active=0` in the same transaction; inactive→active does NOT auto-flip; `register_agent`, `list_agents`, `set_role`, `set_label`, `set_capability` MUST NOT touch `last_seen_at`
+- [x] T033 [P] [US1] Write `tests/unit/test_register_field_too_long.py` covering FR-033: oversized `label` (> 64 chars) and oversized `project_path` (> 4096 chars) rejected with `field_too_long`; not silently truncated
+- [x] T034 [P] [US1] Write `tests/unit/test_register_project_path_invalid.py` covering FR-034: relative path / `..` segment / NUL byte / empty rejected with `project_path_invalid`; existence on host filesystem NOT checked
+- [x] T035 [P] [US1] Write `tests/unit/test_register_value_out_of_set.py` covering FR-004 / FR-005: out-of-set role/capability/parent rejected with `value_out_of_set`; mixed-case rejected without normalization; actionable message lists canonical lowercase values
+- [x] T036 [P] [US1] Write `tests/unit/test_register_transaction.py` covering FR-035: `register_agent` failure (forced SQLite error) rolls back agent-row write AND skips audit append; daemon stays alive; `internal_error` returned
+
+### US1 integration tests
+
+- [ ] T037 [P] [US1] Write `tests/integration/test_cli_register_self.py` covering US1 AS1 / SC-001: register-self from simulated in-container env (FEAT-003+004+005 fakes seeded; `AGENTTOWER_TEST_PROC_ROOT` + `TMUX` + `TMUX_PANE` env) returns exit 0, prints assigned `agent_id`, persists exactly one row with every required field; default-output line shape per FR-028
+- [ ] T038 [P] [US1] Write `tests/integration/test_cli_register_idempotent.py` covering US1 AS2 / AS3 / SC-002: re-registration from same pane returns same `agent_id`; mutable-field updates persist; agent count remains 1; `last_registered_at` strictly increases; `created_at` unchanged
+- [ ] T039 [P] [US1] Write `tests/integration/test_cli_list_agents.py` covering US1 AS4 / SC-007: locked TSV column schema across multi-agent state (one agent per container A and B); `--json` emits every field from FR-002/FR-003/FR-021; field values sanitized of NUL/C0 bytes
+- [ ] T040 [P] [US1] Write `tests/integration/test_cli_list_agents_filters.py` covering FR-026: `--role`, `--container`, `--active-only`, `--parent` filters AND-compose; empty result set is success (exit 0) per spec edge case line 83
+- [ ] T041 [P] [US1] Write `tests/integration/test_cli_register_focused_rescan.py` covering FR-041 / SC-008: pane composite key absent triggers exactly one focused FEAT-004 rescan scoped to caller's container (assert via fake-tmux call counter; no cascade to other containers); after rescan pane appears → registration succeeds; otherwise `pane_unknown_to_daemon`
+- [ ] T042 [P] [US1] Write `tests/integration/test_cli_register_host_context.py` covering SC-009: caller running on host shell (FEAT-005 reports `host_context`) → exit 1 with `host_context_unsupported`
+- [ ] T043 [P] [US1] Write `tests/integration/test_cli_register_pane_unknown.py` covering edge cases line 68: pane composite key absent after focused rescan → `pane_unknown_to_daemon`
+- [ ] T044 [P] [US1] Write `tests/integration/test_cli_register_no_daemon.py` covering SC-009: daemon down → exit 2 with FEAT-002 daemon-unavailable message preserved byte-for-byte; daemon never started implicitly
+- [ ] T045 [P] [US1] Write `tests/integration/test_cli_register_concurrent.py` covering edge case line 72 / FR-038: two concurrent register-self subprocesses bound to same simulated pane converge on same `agent_id`; exactly one row in `agents`; both exit 0
+- [ ] T046 [P] [US1] Write `tests/integration/test_cli_register_concurrent_different_panes.py` covering FR-038: concurrent register-self from different composite keys parallelize; both succeed; distinct `agent_id` values
+- [ ] T047 [P] [US1] Write `tests/integration/test_cli_last_seen_at_updates.py` covering FR-009a: FEAT-004 pane scan updates `last_seen_at` on bound agents; CLI calls (list-agents, set-role, set-label, set-capability) leave `last_seen_at` unchanged
+- [ ] T048 [P] [US1] Write `tests/integration/test_cli_register_inactive_agent_then_reappears.py` covering FR-008: pane disappears (FEAT-004 cascades `agent.active=0`); pane reappears at same composite key; `register-self` re-activates preserving `agent_id` / `created_at` / `parent_agent_id`
+- [ ] T049 [P] [US1] Write `tests/integration/test_cli_register_supplied_vs_default.py` covering Clarifications Q1 end-to-end: re-registration without flags preserves stored role/capability/label/project; explicit `--role unknown` overwrites
+- [ ] T050 [P] [US1] Write `tests/integration/test_cli_register_value_out_of_set.py` covering edge cases line 74: invalid role/capability/parent rejected `value_out_of_set` with valid values listed in actionable message
+- [ ] T051 [P] [US1] Write `tests/integration/test_cli_register_field_too_long.py` covering FR-033: oversized `--label` / `--project` rejected `field_too_long`
+- [ ] T052 [P] [US1] Write `tests/integration/test_cli_register_project_path_invalid.py` covering FR-034: relative / `..` / NUL byte / empty rejected `project_path_invalid`
+
+**Checkpoint**: US1 complete. The MVP slice — register an agent, idempotently re-register, re-activate after disappearance, list agents with locked TSV / JSON forms — is independently testable and shippable. US2 and US3 may proceed in parallel (both depend only on US1's foundational `register_agent` and `state.agents` modules).
+
+---
+
+## Phase 4: User Story 2 — Human-controlled role / label / capability changes (with master safety) (Priority: P2)
+
+**Goal**: Add `set-role`, `set-label`, `set-capability` CLIs and the daemon-side service paths. Enforce the master-safety boundary (no master via `register-self`; `--confirm` required for `set-role --role master`; atomic re-check inside the master-promotion transaction; `set-role --role swarm` rejected). Demotion is asymmetric — no `--confirm` required.
+
+**Independent Test**: Per spec.md US2 — seed two slave agents; exercise the closed set of role-change paths; assert (a) `set-role --role master --confirm` succeeds, (b) `set-role --role master` (no `--confirm`) rejected, (c) `register-self --role master` rejected, (d) `register-self --role master --confirm` rejected, (e) `set-role --role slave --confirm` (demotion) succeeds; assert audit log shape including `prior_role: null` on creation and literal `confirm_provided` value on demotion-with-redundant-confirm.
+
+### Daemon-side service: set_role / set_label / set_capability
+
+- [x] T053 [US2] Add `AgentService.set_role(params, socket_peer_uid) -> dict` to `src/agenttower/agents/service.py`: closed-set shape validation; static rejection of `role == "swarm"` → `swarm_role_via_set_role_rejected` (FR-012); static `master_confirm_required` check (FR-011); acquire `agent_locks.for_key(agent_id)`; `BEGIN IMMEDIATE`; re-SELECT `agents.active` AND `containers.active` for the bound `container_id` inside the transaction (Clarifications session 2026-05-07-continued Q3 / FR-011 atomic re-check); on inactive → ROLLBACK + `agent_inactive`; if new role equals stored role: COMMIT no-op (no audit row, FR-027); else UPDATE role + recomputed `effective_permissions`; COMMIT; append `audit.append_role_change(prior_role=stored, new_role=new, confirm_provided=bool(params.get("confirm", False)), socket_peer_uid)` (Clarifications session 2026-05-07-continued Q5 — literal value); release mutex
+- [x] T054 [US2] Add `AgentService.set_label(params, socket_peer_uid) -> dict` to `src/agenttower/agents/service.py`: shape + sanitize + bounds; acquire `agent_locks.for_key(agent_id)`; SELECT existing; existence + active checks; if new label equals stored: no-op success; else `BEGIN IMMEDIATE`; UPDATE label; COMMIT; NO audit row; release mutex
+- [x] T055 [US2] Add `AgentService.set_capability(params, socket_peer_uid) -> dict` to `src/agenttower/agents/service.py`: shape (capability case-sensitive); acquire `agent_locks.for_key(agent_id)`; SELECT existing; existence + active checks; if new capability equals stored: no-op success; else `BEGIN IMMEDIATE`; UPDATE capability; COMMIT; NO audit row; release mutex
+- [x] T056 [US2] Add static rejection of `role == "master"` to `AgentService.register_agent` (the T020 path) → `master_via_register_self_rejected` regardless of `confirm` (FR-010); insert this check at the post-shape-validation, pre-mutex stage (data-model.md §7.3 step 11)
+- [x] T057 [US2] Wire `_set_role`, `_set_label`, `_set_capability` placeholders in `src/agenttower/socket_api/methods.py` (T010) to the corresponding service methods; map closed-set exceptions to error envelopes; reject unknown params keys with `bad_request`
+
+### Audit-row creation path on initial registration (Clarifications Q4)
+
+- [x] T058 [US2] Update `AgentService.register_agent` (T020) to append an audit row with `prior_role: null`, `new_role=<assigned>`, `confirm_provided: false` on the *creation* path AND on the *role-changing reactivation* path (Clarifications Q4); idempotent re-registration that does not change `agents.role` MUST NOT append a new row (FR-027); reactivation where role changes (e.g., user passes a different `--role` on reactivation) DOES append a row with `prior_role=<stored>`
+
+### CLI-side set-* subparsers
+
+- [x] T059 [US2] Extend `src/agenttower/cli.py` with the `set-role` subparser: required `--target <agent-id>` (validated client-side against `^agt_[0-9a-f]{12}$` per research R-020), required `--role <r>` (FR-004 closed set, case-sensitive), optional `--confirm` boolean, optional `--json`; client-side reject `--role swarm` with `swarm_role_via_set_role_rejected` actionable message pointing at `register-self --role swarm --parent <id>`; client-side reject `--role master` without `--confirm` with `master_confirm_required`; build the `set_role` request envelope; render the FR-030 success line on default and the C-CLI-603 JSON object on `--json` (`audit_appended` is `true` when role transitioned, `false` on no-op)
+- [x] T060 [P] [US2] Extend `src/agenttower/cli.py` with the `set-label` subparser: required `--target`, required `--label`, optional `--json`; render FR-031 form / C-CLI-604 JSON; `audit_appended` always `false`
+- [x] T061 [P] [US2] Extend `src/agenttower/cli.py` with the `set-capability` subparser: required `--target`, required `--capability` (FR-005 closed set, case-sensitive), optional `--json`; render FR-031 form / C-CLI-605 JSON; `audit_appended` always `false`
+
+### US2 unit tests
+
+- [x] T062 [P] [US2] Write `tests/unit/test_master_promotion_safety.py` covering FR-010 / FR-011 / FR-012 / FR-013: `register-self --role master` rejected regardless of `--confirm` with `master_via_register_self_rejected`; `set-role --role master` without `--confirm` rejected with `master_confirm_required`; `set-role --role swarm` rejected with `swarm_role_via_set_role_rejected`; demotion (master → slave / shell / etc.) does NOT require `--confirm`
+- [x] T063 [P] [US2] Write `tests/unit/test_master_promotion_atomic_recheck.py` covering Clarifications session 2026-05-07-continued Q3 / FR-011: `set-role --role master --confirm` performs re-check inside `BEGIN IMMEDIATE`; concurrent FEAT-004 reconciliation that flips agent or container to inactive between client request and transaction commit causes ROLLBACK + `agent_inactive` (no role mutation, no audit row); SQLite-level serialization observed
+- [x] T064 [P] [US2] Write `tests/unit/test_audit_record_shape.py` covering FR-014: exactly one JSONL row per successful role transition; required fields (`event_type`, `ts_utc`, `agent_id`, `prior_role`, `new_role`, `confirm_provided`, `socket_peer_uid`); failures append no row; ts_utc shape is ISO-8601 microsecond UTC
+- [x] T065 [P] [US2] Write `tests/unit/test_initial_audit_record.py` covering Clarifications Q4: first `register-self` for a pane appends one audit row with `prior_role: null` (JSON literal, not missing key) regardless of role (incl. default `unknown`); idempotent re-registration with unchanged role appends no new row
+- [x] T066 [P] [US2] Write `tests/unit/test_audit_confirm_provided_literal.py` covering Clarifications session 2026-05-07-continued Q5: `confirm_provided` records the literal request value verbatim; demotion with redundant `--confirm` logs `confirm_provided: true`; `set-role` to non-master with redundant `--confirm` also logs `true`; `register-self` always logs `false`; non-rewriting contract enforced
+- [x] T067 [P] [US2] Write `tests/unit/test_set_role_no_op.py` covering FR-027: `set_role` / `set_label` / `set_capability` with the same value the agent already has succeed (exit 0) without error and append no new audit row; result envelope reports `audit_appended=false` (or `audit_appended` absent for set-label/set-capability since they never audit)
+- [x] T068 [P] [US2] Write `tests/unit/test_set_role_swarm_rejection.py` covering FR-012: `set-role --role swarm` rejected with `swarm_role_via_set_role_rejected`; actionable message points at `register-self --role swarm --parent <id>`
+
+### US2 integration tests
+
+- [ ] T069 [P] [US2] Write `tests/integration/test_cli_set_role_master.py` covering US2 AS1: `set-role --role master --confirm` promotes; `effective_permissions.can_send_to_roles == ["slave","swarm"]`; one audit row appended with `confirm_provided: true`; `list-agents` reflects `role=master`
+- [ ] T070 [P] [US2] Write `tests/integration/test_cli_set_role_master_no_confirm.py` covering US2 AS2 / SC-004: `set-role --role master` without `--confirm` rejected `master_confirm_required`; role unchanged
+- [ ] T071 [P] [US2] Write `tests/integration/test_cli_register_master_rejected.py` covering US2 AS3 / SC-003: `register-self --role master --confirm` rejected `master_via_register_self_rejected`; no agent row created; no audit row appended; follow-up `register-self --role slave` succeeds and subsequent `set-role --role master --confirm` succeeds
+- [ ] T072 [P] [US2] Write `tests/integration/test_cli_set_role_swarm_rejected.py` covering FR-012: `set-role --role swarm` rejected with closed-set code and actionable message
+- [ ] T073 [P] [US2] Write `tests/integration/test_cli_set_label_capability.py` covering US2 AS4 / AS5: `set-label` and `set-capability` succeed; role and `effective_permissions` unchanged; no audit row appended; idempotent calls with the same value succeed without error
+- [ ] T074 [P] [US2] Write `tests/integration/test_cli_set_role_inactive_target.py` covering edge cases lines 76-77: `set-role` on agent with `active=false` rejected `agent_inactive`; `set-role --role master --confirm` on agent in inactive container rejected `agent_inactive`
+- [ ] T075 [P] [US2] Write `tests/integration/test_cli_set_role_unknown_target.py` covering edge cases line 76: `set-role` on unknown `agent_id` rejected `agent_not_found`
+- [ ] T076 [P] [US2] Write `tests/integration/test_cli_register_initial_audit.py` covering Clarifications Q4 end-to-end: first `register-self` with default `--role unknown` writes one audit row with `prior_role: null`; idempotent re-run with unchanged role writes no new row
+- [ ] T077 [P] [US2] Write `tests/integration/test_cli_set_role_demotion.py` covering FR-013: master → slave demotion succeeds without `--confirm`; one audit row appended with `confirm_provided: false`; `effective_permissions` recomputed
+- [ ] T078 [P] [US2] Write `tests/integration/test_cli_set_role_demotion_redundant_confirm.py` covering Clarifications session 2026-05-07-continued Q5: master → slave with redundant `--confirm` succeeds and logs `confirm_provided: true`
+
+**Checkpoint**: US2 complete. The master safety boundary, asymmetric promotion/demotion, set-label/set-capability, and the full audit-log shape (incl. initial creation row and literal `confirm_provided`) are independently testable and shippable on top of US1.
+
+---
+
+## Phase 5: User Story 3 — Register a swarm child under an existing slave (Priority: P3)
+
+**Goal**: Extend `register_agent` with parent validation (parent exists, active, role=slave); enforce parent immutability on re-registration with `parent_immutable`; reject every parent failure path with the matching closed-set code. The two-level swarm tree (slave → swarm) is the only nesting allowed; nested swarms are rejected via the `parent_role_invalid` check.
+
+**Independent Test**: Per spec.md US3 — seed one active slave; register a swarm child in a different pane with `--role swarm --parent <slave-id>`; verify success path; exercise the five failure paths (`parent_not_found`, `parent_inactive`, `parent_role_invalid`, `parent_role_mismatch`, `swarm_parent_required`) plus the `parent_immutable` rejection on re-registration with a different `--parent`.
+
+### Daemon-side parent validation
+
+- [x] T079 [US3] Extend `AgentService.register_agent` (T020) with swarm-parent shape validation at the static-validation stage (data-model.md §7.3 step 11): if `role == "swarm"` AND no `parent_agent_id` → `swarm_parent_required` (FR-015); if `parent_agent_id` AND `role != "swarm"` → `parent_role_mismatch` (FR-016)
+- [x] T080 [US3] Extend `AgentService.register_agent` with parent dynamic validation at the post-mutex, pre-write stage (after SELECT existing agent for the pane composite key): if no existing row AND `role == "swarm"` AND `parent_agent_id` is supplied: SELECT the parent agent; (a) parent does not exist → `parent_not_found` (FR-017a); (b) parent `active=0` → `parent_inactive` (FR-017b); (c) parent `role != "slave"` → `parent_role_invalid` (FR-017c); failure short-circuits before any agent row is written (no INSERT, no audit row)
+- [x] T081 [US3] Extend `AgentService.register_agent` with parent immutability check (data-model.md §7.3 step 7; FR-018a): if existing agent row AND `parent_agent_id` is supplied: if supplied value differs from stored value (incl. None ↔ non-None) → ROLLBACK + `parent_immutable` (Clarifications Q3 atomicity: no mutable field updated, no transaction commit, no audit row); if supplied value equals stored value: proceed as no-op for parent (other fields per FR-007)
+
+### US3 unit tests
+
+- [x] T082 [P] [US3] Write `tests/unit/test_swarm_parent_validation.py` covering FR-015 / FR-016 / FR-017 / FR-019 / FR-020: all five failure paths (`parent_not_found`, `parent_inactive`, `parent_role_invalid` for each non-slave parent role, `parent_role_mismatch`, `swarm_parent_required`) plus the success path; nested swarm rejection (parent role `swarm` → `parent_role_invalid`)
+- [x] T083 [P] [US3] Write `tests/unit/test_parent_immutable.py` covering Clarifications Q3: re-registration with same `--parent` is no-op success; re-registration with different `--parent` rejected `parent_immutable`; on rejection no mutable field updated even when other fields supplied; transaction rolled back; no audit row appended; null-to-non-null and non-null-to-null both rejected
+
+### US3 integration tests
+
+- [ ] T084 [P] [US3] Write `tests/integration/test_cli_register_swarm.py` covering US3 AS1 / SC-005: register-self --role swarm --parent <slave-id> --capability claude --label claude-swarm-01 succeeds; `list-agents --parent <slave-id>` returns exactly that one swarm row; PARENT column shows the full `agt_<12-hex>` form
+- [ ] T085 [P] [US3] Write `tests/integration/test_cli_register_swarm_failure_paths.py` covering US3 AS2..AS6 / SC-006: every swarm-parent failure path returns the matching closed-set error code; no agent row created on any failure
+- [ ] T086 [P] [US3] Write `tests/integration/test_cli_register_parent_immutable.py` covering Clarifications Q3 end-to-end: re-registration with same `--parent` no-op success; re-registration with different `--parent` rejected `parent_immutable`; no mutable field updated; idempotent `last_registered_at` does NOT advance on the rejected call
+
+**Checkpoint**: US3 complete. The full FEAT-006 surface (registration, set-*, swarm parent linkage, parent immutability) is independently testable. All three user stories may now be shipped together.
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Backwards-compatibility gates, schema-newer forward-compat, no-real-docker/tmux assertions, and final integration tests that span multiple stories. None of these add new behavior — they protect what's already implemented.
+
+- [ ] T087 [P] Write `tests/integration/test_schema_migration_v4.py` covering SC-010: fresh DB → v4; v3-only DB upgrades cleanly to v4 (compare via `sqlite3` schema dump that FEAT-001..004 tables are byte-identical pre/post); v4-already-current DB re-open is a no-op; v5-on-disk DB causes daemon to refuse with `sqlite3.DatabaseError` per existing forward-version refusal (research R-019)
+- [x] T088 [P] Write `tests/integration/test_feat006_backcompat.py` covering SC-010: every FEAT-001..005 CLI command produces byte-identical stdout / stderr / exit codes / `--json` shapes (capture pre-FEAT-006 output via tag checkout fixture; replay against post-FEAT-006 build); no existing socket method gains a new code or response field; FEAT-002 daemon-unavailable message preserved
+- [x] T089 [P] Write `tests/integration/test_feat006_no_real_docker_or_tmux.py` covering SC-012: parallel to existing `test_feat005_no_real_container.py`; assert no real docker / tmux / network call during the FEAT-006 test session; the FR-041 focused rescan goes through the existing FEAT-004 fakes
+- [ ] T090 [P] Write `tests/integration/test_cli_register_schema_newer.py` covering edge case line 79: simulate daemon `schema_version` newer than CLI's `CURRENT_SCHEMA_VERSION` (mock `status` round-trip); every FEAT-006 CLI surfaces `schema_version_newer` and refuses without making any state-changing socket call
+- [x] T091 [P] Update `src/agenttower/socket_api/methods.py` `DISPATCH` ordering to confirm FEAT-006 entries appear after FEAT-004 entries in insertion order (FEAT-002 stability rule); add a defensive unit test `tests/unit/test_dispatch_table_stability.py` snapshotting the dispatch keys + order
+- [x] T092 [P] Update `src/agenttower/agents/__init__.py` re-exports (T001 stub) with the final public surface: `AgentService`, `AgentRecord`, `RegisterAgentRequest`, `EffectivePermissions`, `effective_permissions`, `serialize_effective_permissions`, `generate_agent_id`, `validate_agent_id_shape`, `RegisterLockMap`, `AgentLockMap`
+- [ ] T093 Run the full pytest suite (`pytest tests/`) and confirm all FEAT-001..006 tests pass; capture the run as evidence for SC-010 / SC-011 / SC-012; if any FEAT-001..005 test fails, halt and triage before considering FEAT-006 complete
+- [ ] T094 Run the manual quickstart walkthrough from `specs/006-agent-registration/quickstart.md` against a real host daemon end-to-end (sections 1–7); document any deviation between the walkthrough and the implementation as a follow-up issue
+
+---
+
+## Dependencies
+
+### Phase ordering
+
+- **Phase 1 (Setup)** → required before everything
+- **Phase 2 (Foundational)** → required before any user story; no FEAT-006 user story can begin until Phase 2 is complete
+- **Phase 3 (US1, P1)** → depends on Phase 2 only; this is the MVP slice
+- **Phase 4 (US2, P2)** → depends on Phase 2; can begin in parallel with US1 once T020 (`register_agent`) lands; full integration depends on US1's `register_agent` being functional
+- **Phase 5 (US3, P3)** → depends on Phase 2; can begin in parallel with US1 once T020 lands; integration tests for US3 require an existing US1-registered slave to register a swarm child against
+- **Phase 6 (Polish)** → depends on US1 + US2 + US3 all complete
+
+### Within-story dependencies
+
+- US1: T018, T019 (CLI side) depend on T020 (`register_agent` service); T024 (list-agents CLI) depends on T022 (`list_agents` service); T025 (pane reconcile) depends on T003 (`state.agents`); all US1 tests depend on the corresponding service + CLI tasks landing first.
+- US2: T053..T055 (service methods) depend on T020 (the existing `register_agent` shape) and T009 (`AgentLockMap`); T056 (master rejection in `register_agent`) edits T020's code; T058 (initial-audit on creation path) edits T020's code; T059..T061 (CLI subparsers) depend on T053..T055; T057 wires the placeholders from T010.
+- US3: T079..T081 (parent-validation extensions) edit T020's code; T082..T086 tests depend on T079..T081 landing.
+
+### Cross-story sequencing rules
+
+- T056 (US2 master rejection in `register_agent`) and T058 (US2 initial-audit on creation path) are **edits to T020's `register_agent` body**. T020 should land first in the US1 phase, then T056 and T058 add narrow edits when US2 starts. Do not parallel-edit T020 from two stories.
+- T079..T081 (US3 parent validation) are also **edits to T020's `register_agent` body** — same constraint. Apply US2 edits first (master safety), then US3 edits (parent linkage); both layers compose without overlap.
+- T010 (placeholder dispatch entries) lands during Phase 2 so each story's tests can develop in isolation; T021/T023/T057 replace specific placeholders as their story's service methods land.
+
+---
+
+## Parallel Execution Opportunities
+
+### Within Phase 2 (Foundational)
+
+After T002 (`schema.py` migration) and T003 (`state.agents`) complete, all of T004..T009 (errors, identifiers, permissions, validation, audit, mutex) and T011 (client wrappers) are in independent files and can run in parallel. T010 (dispatch placeholders) is also independent.
+
+T012..T017 (foundational unit tests) can all run in parallel once their target modules exist.
+
+### Within US1 (Phase 3)
+
+After T018, T019, T020, T021, T022, T023, T024, T025 land, every test task T026..T052 is in an independent test file and can run in parallel.
+
+T020 itself can be co-developed with T018/T019 (CLI side) since the wire shape is fully specified in `contracts/socket-api.md`.
+
+### Within US2 (Phase 4)
+
+T053, T054, T055 each touch the same `src/agenttower/agents/service.py` file but add distinct methods; they cannot be edited in parallel by separate workers but each can be reviewed independently. T056, T058, T079..T081 also edit the same `register_agent` body — sequence them.
+
+T060 and T061 (`set-label` and `set-capability` CLI subparsers) are in `cli.py` but add independent subparsers; they can be sequenced together with T059.
+
+T062..T078 (US2 unit + integration tests) are all in independent test files and parallelize freely.
+
+### Within US3 (Phase 5)
+
+T082..T086 tests are all in independent test files and parallelize freely.
+
+### Across user stories
+
+US1 → US2 → US3 is the conservative serial path. The aggressive parallel path is: complete Phase 2 → start US1's T020 → once T020 lands, US1, US2, and US3 work proceed simultaneously across `src/agenttower/agents/service.py` (with sequential edits to `register_agent`) and across independent test files.
+
+### Within Phase 6 (Polish)
+
+T087..T092 are all in independent files / scopes and parallelize freely. T093 (full pytest run) and T094 (manual quickstart) are sequenced last and serial.
+
+---
+
+## Implementation Strategy
+
+### MVP scope
+
+Ship US1 alone as the first MVP increment: a developer inside a bench container can `register-self` and surface their pane as a registered agent; the operator can `list-agents`. This proves the schema, the socket methods, the closed-set codes, and the FEAT-004 wiring end-to-end. No master, no swarm, no set-* — those are layered on top.
+
+### Incremental delivery order
+
+1. **MVP (US1)**: register-self + list-agents. Value: turns FEAT-002..005 into a *visible* registry the operator can inspect.
+2. **+ US2**: master safety + set-role / set-label / set-capability. Value: human-controlled role mutation; no silent privilege change.
+3. **+ US3**: swarm parent linkage. Value: explicit two-level swarm hierarchy ready for FEAT-009 / FEAT-010 to consume.
+4. **+ Polish**: backcompat + migration tests + schema-newer forward-compat. Value: regression-proof the FEAT-001..005 surfaces.
+
+### Reviewer hand-off note
+
+Every task's file path is absolute or repo-relative. The data-model.md §7.3 validation order is the authoritative implementation contract for `register_agent`. Closed-set error codes are the union of T004's additions plus FEAT-002/003/004 codes (preserved byte-for-byte). The locked CLI contract for `list-agents` (FR-029 + Clarifications Q5 + 2026-05-07-continued PARENT-form lock) is snapshot-tested via T031 — any change to the column schema requires a spec amendment.
diff --git a/src/agenttower/agents/__init__.py b/src/agenttower/agents/__init__.py
new file mode 100644
index 0000000..2cc7a24
--- /dev/null
+++ b/src/agenttower/agents/__init__.py
@@ -0,0 +1,33 @@
+"""Agent registration domain logic for FEAT-006.
+
+See ``specs/006-agent-registration/plan.md``. The package owns the
+registration validation order, the per-(container, pane) and
+per-agent advisory mutex registries, the ``effective_permissions``
+derivation, the JSONL audit-row writer, and the daemon-side
+orchestrator that turns a discovered FEAT-004 pane into a registered
+agent. Re-exports below are filled in incrementally as each module
+lands; the final public surface is locked by T092.
+"""
+
+from __future__ import annotations
+
+# Re-exports — keep stable alphabetical order. Final list is locked by T092
+# (specs/006-agent-registration/tasks.md).
+from .identifiers import AGENT_ID_RE, generate_agent_id, validate_agent_id_shape
+from .mutex import AgentLockMap, RegisterLockMap
+from .permissions import (
+    EffectivePermissions,
+    effective_permissions,
+    serialize_effective_permissions,
+)
+
+__all__ = [
+    "AGENT_ID_RE",
+    "AgentLockMap",
+    "EffectivePermissions",
+    "RegisterLockMap",
+    "effective_permissions",
+    "generate_agent_id",
+    "serialize_effective_permissions",
+    "validate_agent_id_shape",
+]
diff --git a/src/agenttower/agents/audit.py b/src/agenttower/agents/audit.py
new file mode 100644
index 0000000..ab3d7af
--- /dev/null
+++ b/src/agenttower/agents/audit.py
@@ -0,0 +1,53 @@
+"""JSONL audit-row writer for FEAT-006 role transitions (FR-014).
+
+Every successful role transition (creation OR change) appends one row
+to the existing FEAT-001 ``events.jsonl`` file via the shared
+``events.writer.append_event`` helper. The on-disk record is the
+standard nested envelope — ``{"ts": <utc-iso>, "type":
+"agent_role_change", "payload": {...}}`` — with ``ts`` prepended by
+the writer and FEAT-006-specific fields nested under ``payload``.
+
+``payload.prior_role`` is JSON ``null`` on creation (Clarifications
+Q4); ``payload.confirm_provided`` is the literal request value
+(Clarifications session 2026-05-07-continued Q5).
+
+No-op writes (FR-027) and failed writes (FR-014, FR-035) MUST NOT
+append. The service layer guards both.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..events import writer as events_writer
+
+
+def append_role_change(
+    events_file: Path | None,
+    *,
+    agent_id: str,
+    prior_role: str | None,
+    new_role: str,
+    confirm_provided: bool,
+    socket_peer_uid: int,
+) -> None:
+    """Append one ``agent_role_change`` JSONL row.
+
+    *events_file* may be ``None`` (e.g., daemon context that is not
+    wired to an events writer in tests) — in that case this is a no-op
+    so the unit tests for the service layer can run without a real
+    file path. In production the daemon always wires the file.
+    """
+    if events_file is None:
+        return
+    payload: dict[str, object] = {
+        "type": "agent_role_change",
+        "payload": {
+            "agent_id": agent_id,
+            "prior_role": prior_role,
+            "new_role": new_role,
+            "confirm_provided": bool(confirm_provided),
+            "socket_peer_uid": int(socket_peer_uid),
+        },
+    }
+    events_writer.append_event(events_file, payload)
diff --git a/src/agenttower/agents/client_resolve.py b/src/agenttower/agents/client_resolve.py
new file mode 100644
index 0000000..66afa2a
--- /dev/null
+++ b/src/agenttower/agents/client_resolve.py
@@ -0,0 +1,250 @@
+"""Client-side identity + pane resolution for ``agenttower register-self``.
+
+Reuses FEAT-005 in-container identity (``runtime_detect`` + ``identity``)
+and tmux self-identity (``tmux_identity``) to determine the caller's
+container_id and tmux pane composite key. Cross-checks against the
+FEAT-003 container registry (via ``list_containers``) and the FEAT-004
+pane registry (via ``list_panes``) over the daemon socket.
+
+On a pane miss, triggers exactly one focused FEAT-004 rescan scoped to
+the caller's container (FR-041). After the rescan, if the pane is still
+absent or ``active=false``, refuses with closed-set
+``pane_unknown_to_daemon``.
+
+Maps every failure to the FEAT-006 closed-set error code surface:
+
+* ``host_context_unsupported``  — caller is on the host shell.
+* ``container_unresolved``      — ``no_match`` / ``no_candidate`` / ``multi_match``.
+* ``not_in_tmux``               — ``$TMUX`` unset.
+* ``tmux_pane_malformed``       — ``$TMUX_PANE`` malformed.
+* ``pane_unknown_to_daemon``    — pane absent after focused rescan.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..config_doctor import identity as cd_identity
+from ..config_doctor import runtime_detect, tmux_identity
+from ..socket_api.client import send_request
+from .errors import RegistrationError
+from .mutex import PaneCompositeKey
+
+
+@dataclass(frozen=True)
+class ResolvedAgentTarget:
+    """Result of :func:`resolve_pane_composite_key` — the inputs the daemon
+    needs to register the agent."""
+
+    container_id: str
+    pane_key: PaneCompositeKey
+
+
+def resolve_pane_composite_key(
+    *,
+    socket_path: Path,
+    env: Mapping[str, str],
+    proc_root: str | None = None,
+    connect_timeout: float = 1.0,
+    read_timeout: float = 5.0,
+) -> ResolvedAgentTarget:
+    """Resolve the caller's container_id + pane composite key.
+
+    *socket_path* is the resolved daemon socket. *env* is the CLI process
+    environment (a mapping; tests pass a synthetic dict). *proc_root* is
+    the ``AGENTTOWER_TEST_PROC_ROOT`` override threaded through
+    consistently with FEAT-005 (T-005 review fix).
+
+    On any failure, raises :class:`RegistrationError` carrying the
+    matching closed-set wire code.
+    """
+    # 1. Runtime detection — refuse host context.
+    runtime = runtime_detect.detect(proc_root=proc_root)
+    if isinstance(runtime, runtime_detect.HostContext):
+        raise RegistrationError(
+            "host_context_unsupported",
+            "register-self requires running inside a bench container; "
+            "FEAT-006 MVP does not register host-only panes",
+        )
+
+    # 2. Identity detection (FR-006 four-step precedence).
+    candidate = cd_identity.detect_candidate(env, proc_root=proc_root)
+    if candidate is None:
+        raise RegistrationError(
+            "container_unresolved",
+            "no container identity signal (env, cgroup, hostname, $HOSTNAME); "
+            "run `agenttower scan --containers` from the host",
+        )
+    if isinstance(candidate, cd_identity.CgroupMultiCandidate):
+        raise RegistrationError(
+            "container_unresolved",
+            f"cgroup yielded multiple distinct identifiers: {list(candidate.candidates)}; "
+            "run `agenttower scan --containers` from the host",
+        )
+
+    # 3. Cross-check against FEAT-003 container registry.
+    candidate_value = candidate.candidate
+    matched_id = _match_container(
+        socket_path=socket_path,
+        candidate=candidate_value,
+        connect_timeout=connect_timeout,
+        read_timeout=read_timeout,
+    )
+
+    # 4. Parse $TMUX / $TMUX_PANE.
+    parsed = tmux_identity.parse_tmux_env(env)
+    if not parsed.in_tmux:
+        raise RegistrationError(
+            "not_in_tmux",
+            "$TMUX is unset; run register-self from inside an active tmux pane",
+        )
+    if parsed.malformed_reason is not None:
+        raise RegistrationError(
+            "tmux_pane_malformed",
+            parsed.malformed_reason,
+        )
+    if not parsed.pane_id_valid:
+        raise RegistrationError(
+            "tmux_pane_malformed",
+            "$TMUX_PANE does not match the %N shape",
+        )
+
+    assert parsed.tmux_socket_path is not None
+    assert parsed.tmux_pane_id is not None
+
+    # 5. Find the pane composite key in FEAT-004 panes for this container.
+    pane_key = _find_pane(
+        socket_path=socket_path,
+        container_id=matched_id,
+        tmux_socket_path=parsed.tmux_socket_path,
+        tmux_pane_id=parsed.tmux_pane_id,
+        connect_timeout=connect_timeout,
+        read_timeout=read_timeout,
+    )
+    if pane_key is None:
+        # FR-041 focused rescan — exactly one, scoped to the resolved
+        # container — then re-query.
+        send_request(
+            socket_path,
+            "scan_panes",
+            {"container": matched_id},
+            connect_timeout=connect_timeout,
+            read_timeout=read_timeout,
+        )
+        pane_key = _find_pane(
+            socket_path=socket_path,
+            container_id=matched_id,
+            tmux_socket_path=parsed.tmux_socket_path,
+            tmux_pane_id=parsed.tmux_pane_id,
+            connect_timeout=connect_timeout,
+            read_timeout=read_timeout,
+        )
+        if pane_key is None:
+            raise RegistrationError(
+                "pane_unknown_to_daemon",
+                f"pane {parsed.tmux_pane_id} not found in container {matched_id}; "
+                "run `agenttower scan --panes` from the host",
+            )
+
+    return ResolvedAgentTarget(container_id=matched_id, pane_key=pane_key)
+
+
+def _match_container(
+    *,
+    socket_path: Path,
+    candidate: str,
+    connect_timeout: float,
+    read_timeout: float,
+) -> str:
+    """Match the candidate identifier against the FEAT-003 container registry.
+
+    Accepts the candidate as a full id, 12-char short prefix, or
+    container name. Returns the full container_id on success; raises
+    ``container_unresolved`` on no-match, no-candidate, or multi-match.
+    """
+    result = send_request(
+        socket_path,
+        "list_containers",
+        {"active_only": True},
+        connect_timeout=connect_timeout,
+        read_timeout=read_timeout,
+    )
+    containers = result.get("containers", [])
+    matches: list[str] = []
+    for c in containers:
+        cid = c.get("id", "")
+        name = c.get("name", "")
+        if cid == candidate:
+            matches.append(cid)
+        elif candidate and len(candidate) >= 12 and cid.startswith(candidate):
+            matches.append(cid)
+        elif name == candidate:
+            matches.append(cid)
+    # De-duplicate while preserving order.
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for m in matches:
+        if m not in seen:
+            seen.add(m)
+            deduped.append(m)
+    if len(deduped) == 0:
+        raise RegistrationError(
+            "container_unresolved",
+            f"candidate {candidate!r} did not match any active bench container; "
+            "run `agenttower scan --containers` from the host",
+        )
+    if len(deduped) > 1:
+        raise RegistrationError(
+            "container_unresolved",
+            f"candidate {candidate!r} matched {len(deduped)} active containers; "
+            "set AGENTTOWER_CONTAINER_ID to disambiguate",
+        )
+    return deduped[0]
+
+
+def _find_pane(
+    *,
+    socket_path: Path,
+    container_id: str,
+    tmux_socket_path: str,
+    tmux_pane_id: str,
+    connect_timeout: float,
+    read_timeout: float,
+) -> PaneCompositeKey | None:
+    """Look up the pane composite key in the FEAT-004 registry.
+
+    The match key is ``(container_id, tmux_socket_path, tmux_pane_id)``;
+    the FEAT-004 list_panes response includes session/window/pane index
+    so we recover the full six-tuple. Returns ``None`` if no row matches
+    or if the matching row is ``active=false`` (caller triggers the
+    FR-041 focused rescan in that case).
+    """
+    result = send_request(
+        socket_path,
+        "list_panes",
+        {"active_only": False, "container": container_id},
+        connect_timeout=connect_timeout,
+        read_timeout=read_timeout,
+    )
+    panes = result.get("panes", [])
+    for p in panes:
+        if p.get("container_id") != container_id:
+            continue
+        if p.get("tmux_socket_path") != tmux_socket_path:
+            continue
+        if p.get("tmux_pane_id") != tmux_pane_id:
+            continue
+        if not p.get("active"):
+            return None
+        return (
+            p["container_id"],
+            p["tmux_socket_path"],
+            p["tmux_session_name"],
+            int(p["tmux_window_index"]),
+            int(p["tmux_pane_index"]),
+            p["tmux_pane_id"],
+        )
+    return None
diff --git a/src/agenttower/agents/errors.py b/src/agenttower/agents/errors.py
new file mode 100644
index 0000000..6ab41d3
--- /dev/null
+++ b/src/agenttower/agents/errors.py
@@ -0,0 +1,22 @@
+"""Typed exception type for agent-domain validation/service failures.
+
+Each instance carries the closed-set wire code so the service layer can
+map straight to the FEAT-002 error envelope (``socket_api/errors.py``)
+without string parsing.
+"""
+
+from __future__ import annotations
+
+
+class RegistrationError(Exception):
+    """Carries a closed-set wire code + actionable message.
+
+    The ``code`` MUST belong to the FEAT-002 / FEAT-003 / FEAT-004 /
+    FEAT-006 closed set declared in :mod:`agenttower.socket_api.errors`.
+    The service layer enforces this when mapping to the wire envelope.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
diff --git a/src/agenttower/agents/identifiers.py b/src/agenttower/agents/identifiers.py
new file mode 100644
index 0000000..7ba8c95
--- /dev/null
+++ b/src/agenttower/agents/identifiers.py
@@ -0,0 +1,55 @@
+"""Agent identifier generation and shape validation (FEAT-006 FR-001).
+
+``agent_id`` shape is ``agt_<12-character-lowercase-hex>`` (16 chars total,
+48 bits of entropy — 12 hex chars × 4 bits = 48). Strict case-sensitive:
+only ``[0-9a-f]`` is accepted in the hex portion (Clarifications session
+2026-05-07-continued).
+
+Birthday-bound collision probability stays vanishingly small at MVP
+scale: 2^24 ≈ 16M unique agents before the first expected collision.
+The PK collision retry budget in the service layer
+(``_AGENT_ID_RETRY_LIMIT=5``) covers the impossible case so a real
+collision still surfaces as ``internal_error`` rather than crashing
+the daemon. If horizontal scale ever pushes past ~10⁵ concurrent
+agents, bump ``token_hex(6)`` to ``token_hex(12)`` and update the
+regex to ``[0-9a-f]{24}`` (a wire-format break — coordinate with
+existing CLI consumers).
+"""
+
+from __future__ import annotations
+
+import re
+import secrets
+from typing import Final
+
+from .errors import RegistrationError
+
+
+AGENT_ID_RE: Final[re.Pattern[str]] = re.compile(r"^agt_[0-9a-f]{12}$")
+
+
+def generate_agent_id() -> str:
+    """Return a fresh ``agt_<12-hex>`` identifier (research R-001).
+
+    ``secrets.token_hex(6)`` returns 6 random bytes = 12 hex chars =
+    48 bits of entropy. Adequate at MVP scale (birthday-bound first
+    expected collision at ~16M unique agents). PK collisions are
+    retried by the service layer under the per-pane registration
+    mutex (FR-001).
+    """
+    return "agt_" + secrets.token_hex(6)
+
+
+def validate_agent_id_shape(value: str) -> str:
+    """Return *value* unchanged if it matches :data:`AGENT_ID_RE`, else raise.
+
+    Mixed-case inputs (``AGT_abc...``, ``agt_ABC...``) are rejected with
+    closed-set code ``value_out_of_set`` per Clarifications session
+    2026-05-07-continued Q2 — never normalized.
+    """
+    if not isinstance(value, str) or not AGENT_ID_RE.match(value):
+        raise RegistrationError(
+            "value_out_of_set",
+            f"agent_id must match agt_<12-hex-lowercase>; got {value!r}",
+        )
+    return value
diff --git a/src/agenttower/agents/mutex.py b/src/agenttower/agents/mutex.py
new file mode 100644
index 0000000..739389f
--- /dev/null
+++ b/src/agenttower/agents/mutex.py
@@ -0,0 +1,66 @@
+"""Per-key advisory mutex registries (FR-038 / FR-039; research R-005).
+
+Two thread-safe per-key registries:
+
+* :class:`RegisterLockMap` — keyed by the FEAT-004 pane composite key
+  tuple. Serializes ``register_agent`` requests addressing the same
+  pane. FEAT-004 reconciliation MUST NOT acquire it (Clarifications
+  session 2026-05-07-continued Q4); cross-subsystem ordering with
+  ``register_agent`` is provided exclusively by SQLite ``BEGIN
+  IMMEDIATE`` semantics.
+
+* :class:`AgentLockMap` — keyed by ``agent_id``. Serializes
+  ``set_role`` / ``set_label`` / ``set_capability`` calls addressing
+  the same agent.
+
+Concurrent calls addressing distinct keys / agent_ids proceed in
+parallel. No LRU eviction at MVP scale; entries live for the daemon
+process lifetime (memory overhead bounded by MVP agent count). On a
+long-running daemon with high agent churn this is a slow leak —
+acceptable now, tracked as a follow-up: when post-MVP scale demands
+it, periodically GC entries whose lock is unlocked AND whose bound
+agent row is no longer present.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Generic, Hashable, TypeVar
+
+
+_KeyT = TypeVar("_KeyT", bound=Hashable)
+
+
+class _PerKeyLockMap(Generic[_KeyT]):
+    """Internal helper: thread-safe ``key → threading.Lock`` map."""
+
+    def __init__(self) -> None:
+        self._guard = threading.Lock()
+        self._locks: dict[_KeyT, threading.Lock] = {}
+
+    def for_key(self, key: _KeyT) -> threading.Lock:
+        """Return the per-key lock, creating it under :attr:`_guard` if absent."""
+        with self._guard:
+            lock = self._locks.get(key)
+            if lock is None:
+                lock = threading.Lock()
+                self._locks[key] = lock
+            return lock
+
+    def known_keys(self) -> list[_KeyT]:
+        """Return a snapshot of the current key set (test/diagnostic use)."""
+        with self._guard:
+            return list(self._locks.keys())
+
+
+# FEAT-004 pane composite key tuple shape: (container_id, tmux_socket_path,
+# tmux_session_name, tmux_window_index, tmux_pane_index, tmux_pane_id).
+PaneCompositeKey = tuple[str, str, str, int, int, str]
+
+
+class RegisterLockMap(_PerKeyLockMap[PaneCompositeKey]):
+    """Per-(container_id, pane composite key) mutex registry (FR-038)."""
+
+
+class AgentLockMap(_PerKeyLockMap[str]):
+    """Per-``agent_id`` mutex registry (FR-039)."""
diff --git a/src/agenttower/agents/permissions.py b/src/agenttower/agents/permissions.py
new file mode 100644
index 0000000..291bc5c
--- /dev/null
+++ b/src/agenttower/agents/permissions.py
@@ -0,0 +1,61 @@
+"""Pure ``effective_permissions`` derivation for FEAT-006 (FR-021).
+
+Closed-set output shape ``{can_send, can_receive, can_send_to_roles}``
+materialized on every agent row from the role. Recomputed by the
+service layer on every write that mutates ``role`` (FR-021). FEAT-006
+does NOT consume this for any decision; FEAT-009 / FEAT-010 will.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Final, TypedDict
+
+
+class EffectivePermissions(TypedDict):
+    can_send: bool
+    can_receive: bool
+    can_send_to_roles: list[str]
+
+
+# Closed-set derivation table per FR-021 / data-model.md §4.3.
+_TABLE: Final[dict[str, EffectivePermissions]] = {
+    "master":      {"can_send": True,  "can_receive": False, "can_send_to_roles": ["slave", "swarm"]},
+    "slave":       {"can_send": False, "can_receive": True,  "can_send_to_roles": []},
+    "swarm":       {"can_send": False, "can_receive": True,  "can_send_to_roles": []},
+    "test-runner": {"can_send": False, "can_receive": False, "can_send_to_roles": []},
+    "shell":       {"can_send": False, "can_receive": False, "can_send_to_roles": []},
+    "unknown":     {"can_send": False, "can_receive": False, "can_send_to_roles": []},
+}
+
+
+def effective_permissions(role: str) -> EffectivePermissions:
+    """Return the FR-021 derivation for *role*.
+
+    Raises ``KeyError`` if *role* is not one of the FR-004 closed set.
+    Callers MUST validate ``role`` against the closed set before calling
+    (the validator in :mod:`agenttower.agents.validation` does so).
+    """
+    perms = _TABLE[role]
+    # Defensive copy of the list so callers cannot mutate the table.
+    return {
+        "can_send": perms["can_send"],
+        "can_receive": perms["can_receive"],
+        "can_send_to_roles": list(perms["can_send_to_roles"]),
+    }
+
+
+def serialize_effective_permissions(role: str) -> str:
+    """Return the JSON column value with stable key ordering.
+
+    Key order is locked as ``[can_send, can_receive, can_send_to_roles]``
+    (research R-008) so the on-disk JSON column shape stays stable.
+    """
+    perms = effective_permissions(role)
+    # Build an ordered dict explicitly so json.dumps preserves insertion order.
+    ordered: dict[str, object] = {
+        "can_send": perms["can_send"],
+        "can_receive": perms["can_receive"],
+        "can_send_to_roles": perms["can_send_to_roles"],
+    }
+    return json.dumps(ordered, separators=(",", ":"), ensure_ascii=False)
diff --git a/src/agenttower/agents/service.py b/src/agenttower/agents/service.py
new file mode 100644
index 0000000..539255c
--- /dev/null
+++ b/src/agenttower/agents/service.py
@@ -0,0 +1,1270 @@
+"""Daemon-side AgentService — orchestrator for the FEAT-006 socket methods.
+
+Implements the validation order from data-model.md §7.3 (register_agent)
+and §7.3a (set_role). Owns the per-(container, pane composite key)
+register mutex and the per-``agent_id`` agent mutex; commits each call
+in a single ``BEGIN IMMEDIATE`` SQLite transaction with rollback on
+failure (FR-035). Audit rows (FR-014) are appended *after* COMMIT and
+ONLY for actual role transitions (FR-027 — no audit on no-op writes).
+
+Cross-subsystem ordering with FEAT-004 pane reconciliation is provided
+by SQLite ``BEGIN IMMEDIATE`` semantics — the FEAT-006 mutex covers
+register_agent against other register_agent calls only (FR-038 /
+Clarifications session 2026-05-07-continued Q4).
+
+**Audit-append failure invariant** (FR-014 hardening): every successful
+COMMIT is followed by a JSONL audit append in a try/except. If the
+append raises (disk full, fsync EIO, mode-broadening race), the role
+change is already committed and cannot be rolled back; the failure is
+emitted via the lifecycle logger as an ``audit_append_failed`` event
+and the call still returns success. Persisting "audit pending" rows
+in a same-DB table for replay is a deferred follow-up.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Final
+
+from ..state import agents as state_agents
+from ..state.agents import AgentRecord
+from ..tmux.parsers import sanitize_text
+from . import audit as audit_mod
+from . import permissions
+from . import validation
+from .errors import RegistrationError
+from .identifiers import generate_agent_id, validate_agent_id_shape
+from .mutex import AgentLockMap, PaneCompositeKey, RegisterLockMap
+
+
+# Sentinel values for "field absent in the JSON envelope" — encodes the
+# Clarifications Q1 wire contract: only-supplied-fields-overwrite. The
+# CLI MUST omit unsupplied flags from ``params`` so absent dict keys
+# read as "leave stored value unchanged" on idempotent re-registration.
+_UNSET: Final[object] = object()
+
+
+# Maximum agent_id PK collision retries (FR-001 / research R-001).
+# Vanishingly unlikely at MVP scale (48 bits of entropy → ~16M agents
+# before the first expected collision); 5 attempts is overwhelmingly
+# conservative.
+_AGENT_ID_RETRY_LIMIT: Final[int] = 5
+
+
+# SQLite extended-errcode constants (sqlite3.h).  We disambiguate
+# IntegrityError on the agent_id PRIMARY KEY (which we retry) from
+# IntegrityError on any other UNIQUE constraint (e.g. the agents-table
+# pane composite key — which we surface as internal_error) by inspecting
+# ``exc.sqlite_extended_errcode`` rather than substring-matching the
+# English error message (which can drift between SQLite versions).
+_SQLITE_CONSTRAINT_PRIMARYKEY: Final[int] = 1555
+
+
+# Pane composite-key string-field bounds, applied defensively in
+# ``_coerce_pane_key``.  FEAT-004 already sanitizes these on the way
+# IN to the panes table; the FEAT-006 service trusts the CLI for
+# identity (FR-024) but still cannot let a same-uid peer (or future
+# automation that bypasses the CLI) plant NUL/control bytes in the
+# agents row that flow back through list_agents into TSV/JSON.
+_PANE_FIELD_MAX_BYTES: Final[int] = 4096
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="microseconds")
+
+
+def _check_schema_version(
+    params: dict[str, Any], *, daemon_schema_version: int, method_name: str
+) -> None:
+    """Shared FR-040 forward-compat gate.
+
+    Runs at the top of every FEAT-006 service method. Refuses with
+    ``schema_version_newer`` when the daemon's schema is newer than
+    what the calling CLI advertises, and with ``bad_request`` when the
+    field is present but not an int (defensive — a buggy client
+    sending ``"latest"`` or ``1.5`` would otherwise silently bypass
+    the gate).
+    """
+    if "schema_version" not in params:
+        return
+    client_schema = params["schema_version"]
+    if not isinstance(client_schema, int) or isinstance(client_schema, bool):
+        raise RegistrationError(
+            "bad_request",
+            f"{method_name}: params.schema_version must be an integer",
+        )
+    if client_schema < daemon_schema_version:
+        raise RegistrationError(
+            "schema_version_newer",
+            f"daemon schema_version={daemon_schema_version} > "
+            f"client expected={client_schema}; upgrade the CLI",
+        )
+
+
+def _check_unknown_keys(
+    params: dict[str, Any], allowed: frozenset[str], *, method_name: str
+) -> None:
+    """Reject any key in *params* not in the *allowed* closed set.
+
+    Mirrors the ``unknown_filter`` gate ``list_agents`` enforces. Refuses
+    with ``bad_request`` so a typo or stale-CLI extra field surfaces
+    deterministically rather than being silently dropped.
+    """
+    unknown = sorted(set(params.keys()) - allowed)
+    if unknown:
+        raise RegistrationError(
+            "bad_request",
+            f"{method_name}: unknown params keys {unknown}; "
+            f"allowed: {sorted(allowed)}",
+        )
+
+
+def _require_string(
+    params: dict[str, Any], key: str, *, method_name: str
+) -> str:
+    """Read a required string field from *params* or raise ``bad_request``."""
+    if key not in params:
+        raise RegistrationError(
+            "bad_request",
+            f"{method_name}: params.{key} is required",
+        )
+    value = params[key]
+    if not isinstance(value, str):
+        raise RegistrationError(
+            "bad_request",
+            f"{method_name}: params.{key} must be a string",
+        )
+    return value
+
+
+@dataclass
+class AgentService:
+    """Owns the FEAT-006 mutex registries; orchestrates each socket method.
+
+    *connection_factory* MUST yield a ``sqlite3.Connection`` for the
+    state database. The service opens fresh connections for each
+    short-lived call so register_agent / list_agents / set_* can run on
+    the daemon's accept-thread pool without sharing an SQLite cursor.
+
+    *events_file* is the FEAT-001 ``events.jsonl`` path. May be ``None``
+    in unit tests (audit append becomes a no-op). *schema_version* is
+    the build's current schema version, used by the forward-compat
+    check (edge case line 79; FR-040 ``schema_version_newer``).
+
+    *lifecycle_logger* (optional) receives ``audit_append_failed`` events
+    when the post-COMMIT JSONL audit append raises — see the module
+    docstring's audit-append failure invariant.
+    """
+
+    connection_factory: Callable[[], sqlite3.Connection]
+    register_locks: RegisterLockMap
+    agent_locks: AgentLockMap
+    events_file: Path | None
+    schema_version: int
+    lifecycle_logger: Any = None
+
+    def _emit_lifecycle(self, event: str, **kwargs: Any) -> None:
+        """Best-effort emit a lifecycle event; swallow logger failures.
+
+        Mirrors the pattern in :mod:`discovery.service`: the daemon must
+        keep serving requests even if the structured log sink is
+        misbehaving (FR-035).
+        """
+        logger = self.lifecycle_logger
+        if logger is None:
+            return
+        try:
+            logger.emit(event, **kwargs)
+        except Exception:  # pragma: no cover — defensive
+            pass
+
+    # ------------------------------------------------------------------ #
+    # register_agent (FR-007 / FR-008 / FR-010 / FR-015 / FR-018a / etc.)
+    # ------------------------------------------------------------------ #
+
+    # Closed set of keys ``register_agent`` accepts on the wire. Anything
+    # outside this set is a forward-compat / typo signal and is refused
+    # with ``bad_request`` rather than silently ignored — mirrors the
+    # FR-026 ``unknown_filter`` gate that ``list_agents`` already enforces.
+    #
+    # ``confirm`` is intentionally NOT in this set: register-self has no
+    # meaningful confirm (the master-safety boundary is unconditional
+    # here per FR-010), so register_agent audit rows always record
+    # ``confirm_provided: false``.  Allowing the wire field would let a
+    # client spoof the audit value.
+    _REGISTER_AGENT_ALLOWED_KEYS = frozenset(
+        {
+            "schema_version",
+            "container_id",
+            "pane_composite_key",
+            "role",
+            "capability",
+            "label",
+            "project_path",
+            "parent_agent_id",
+        }
+    )
+
+    def register_agent(
+        self, params: dict[str, Any], *, socket_peer_uid: int
+    ) -> dict[str, Any]:
+        # 0. Closed-key validation + forward-compat schema gate
+        #    (FR-040 / FR-035 hygiene).
+        _check_unknown_keys(
+            params, self._REGISTER_AGENT_ALLOWED_KEYS, method_name="register_agent"
+        )
+        _check_schema_version(
+            params,
+            daemon_schema_version=self.schema_version,
+            method_name="register_agent",
+        )
+
+        # 1. Required identity inputs (FR-024 — daemon does not re-derive
+        #    container identity; the CLI is responsible).
+        container_id = params.get("container_id")
+        pane_key_in = params.get("pane_composite_key")
+        if not isinstance(container_id, str):
+            raise RegistrationError(
+                "bad_request",
+                "params.container_id must be a string",
+            )
+        if not container_id:
+            raise RegistrationError(
+                "value_out_of_set",
+                "params.container_id must be a non-empty string",
+            )
+        pane_key = _coerce_pane_key(pane_key_in)
+        if pane_key[0] != container_id:
+            raise RegistrationError(
+                "value_out_of_set",
+                "params.pane_composite_key.container_id must match params.container_id",
+            )
+
+        # 2. Optional mutable fields — supplied-vs-default wire contract
+        #    (Clarifications Q1 / FR-007). Absent keys → ``_UNSET``.
+        role_in = _opt(params, "role")
+        capability_in = _opt(params, "capability")
+        label_in = _opt(params, "label")
+        project_path_in = _opt(params, "project_path")
+        parent_in = _opt(params, "parent_agent_id")
+
+        # 3. Closed-set field shape validation on present optional keys.
+        if role_in is not _UNSET:
+            validation.validate_role(role_in)
+        if capability_in is not _UNSET:
+            validation.validate_capability(capability_in)
+        # 4. Free-text bounds + sanitization (FR-033 / FR-034).
+        if label_in is not _UNSET:
+            label_in = validation.validate_label(label_in)
+        if project_path_in is not _UNSET and project_path_in != "":
+            project_path_in = validation.validate_project_path(project_path_in)
+        # 5. Parent shape (full agent_id form). ``None`` is allowed as
+        #    "explicitly null parent" but only meaningful in error
+        #    paths because re-registration with different --parent is
+        #    rejected as parent_immutable (FR-018a).
+        if parent_in is not _UNSET and parent_in is not None:
+            validation.validate_parent_agent_id_shape(parent_in)
+
+        # 6. Master-safety static rejection (FR-010): ``register-self
+        #    --role master`` MUST be refused regardless of ``--confirm``.
+        if role_in == "master":
+            raise RegistrationError(
+                "master_via_register_self_rejected",
+                "register-self cannot assign role=master; register first, "
+                "then run `agenttower set-role --role master --confirm`",
+            )
+
+        # 7. Swarm-parent shape pairing (FR-015 / FR-016).
+        if role_in == "swarm" and (parent_in is _UNSET or parent_in is None):
+            raise RegistrationError(
+                "swarm_parent_required",
+                "--role swarm requires --parent <agent-id>",
+            )
+        if (
+            parent_in is not _UNSET
+            and parent_in is not None
+            and role_in is not _UNSET
+            and role_in != "swarm"
+        ):
+            raise RegistrationError(
+                "parent_role_mismatch",
+                "--parent only valid with --role swarm",
+            )
+
+        # 8. Serialize concurrent register_agent against the same pane
+        #    composite key (FR-038). Independent panes proceed in
+        #    parallel (each gets its own per-key lock).
+        with self.register_locks.for_key(pane_key):
+            return self._register_agent_locked(
+                container_id=container_id,
+                pane_key=pane_key,
+                role_in=role_in,
+                capability_in=capability_in,
+                label_in=label_in,
+                project_path_in=project_path_in,
+                parent_in=parent_in,
+                socket_peer_uid=socket_peer_uid,
+            )
+
+    def _register_agent_locked(
+        self,
+        *,
+        container_id: str,
+        pane_key: PaneCompositeKey,
+        role_in: object,
+        capability_in: object,
+        label_in: object,
+        project_path_in: object,
+        parent_in: object,
+        socket_peer_uid: int,
+    ) -> dict[str, Any]:
+        """Execute the register_agent write inside a single BEGIN IMMEDIATE.
+
+        Both paths (creation and re-registration) take their existence
+        SELECT and parent-active validation INSIDE the same write
+        transaction so the validate-then-write window cannot be raced
+        by a concurrent ``set_role`` (different mutex domain) or by a
+        FEAT-004 pane-reconciliation cascade. Audit rows are appended
+        AFTER COMMIT, in a try/except that emits a lifecycle event on
+        failure so the role transition is never silently lost.
+        """
+        conn = self.connection_factory()
+        try:
+            now_iso = _now_iso()
+
+            audit_event: dict[str, Any] | None = None
+            outcome: dict[str, Any]
+
+            conn.execute("BEGIN IMMEDIATE")
+            try:
+                self._validate_bound_pane_is_active(
+                    conn,
+                    pane_key=pane_key,
+                )
+                existing = state_agents.select_agent_by_pane_key(
+                    conn, pane_key=pane_key
+                )
+
+                if existing is None:
+                    # ===== Creation path =====
+                    role = role_in if role_in is not _UNSET else "unknown"
+                    capability = (
+                        capability_in if capability_in is not _UNSET else "unknown"
+                    )
+                    label = label_in if label_in is not _UNSET else ""
+                    project_path = (
+                        project_path_in if project_path_in is not _UNSET else ""
+                    )
+                    parent_agent_id = parent_in if parent_in is not _UNSET else None
+                    # FR-016: a non-null parent demands role=swarm. Closes
+                    # the gap for "parent supplied but role omitted",
+                    # where the argparse default "unknown" would otherwise
+                    # silently persist alongside a parent_agent_id.
+                    if parent_agent_id is not None and role != "swarm":
+                        raise RegistrationError(
+                            "parent_role_mismatch",
+                            "--parent only valid with --role swarm",
+                        )
+                    # FR-017: parent existence/active/role=slave check —
+                    # MUST run inside BEGIN IMMEDIATE so a concurrent
+                    # FEAT-004 cascade cannot flip the parent inactive
+                    # between the check and the INSERT.
+                    if isinstance(parent_agent_id, str):
+                        self._validate_parent_for_swarm(
+                            conn, parent_agent_id=parent_agent_id
+                        )
+                    effective_perms_json = permissions.serialize_effective_permissions(
+                        role
+                    )
+                    new_agent_id = self._insert_with_savepoint_retry(
+                        conn,
+                        pane_key=pane_key,
+                        role=role,
+                        capability=capability,
+                        label=label,
+                        project_path=project_path,
+                        parent_agent_id=parent_agent_id,
+                        effective_perms_json=effective_perms_json,
+                        now_iso=now_iso,
+                    )
+                    final_agent_id = new_agent_id
+                    created_or_reactivated = "created"
+                    audit_event = {
+                        "agent_id": new_agent_id,
+                        "prior_role": None,
+                        "new_role": role,
+                    }
+                else:
+                    # ===== Re-registration / re-activation path =====
+                    # (FR-007 / FR-008 / FR-018a)
+                    if (
+                        parent_in is not _UNSET
+                        and parent_in != existing.parent_agent_id
+                    ):
+                        raise RegistrationError(
+                            "parent_immutable",
+                            "--parent is immutable after creation; re-registration "
+                            "with a different --parent is rejected",
+                        )
+                    resolved_role = (
+                        role_in if role_in is not _UNSET else existing.role
+                    )
+                    resolved_parent = (
+                        parent_in
+                        if parent_in is not _UNSET
+                        else existing.parent_agent_id
+                    )
+                    if role_in is not _UNSET and resolved_role == "master":
+                        # Even on re-registration, register-self never assigns master.
+                        raise RegistrationError(
+                            "master_via_register_self_rejected",
+                            "register-self cannot assign role=master",
+                        )
+                    if resolved_parent is not None and resolved_role != "swarm":
+                        raise RegistrationError(
+                            "parent_role_mismatch",
+                            "--parent only valid with --role swarm",
+                        )
+                    resolved_capability = (
+                        capability_in
+                        if capability_in is not _UNSET
+                        else existing.capability
+                    )
+                    resolved_label = (
+                        label_in if label_in is not _UNSET else existing.label
+                    )
+                    resolved_project = (
+                        project_path_in
+                        if project_path_in is not _UNSET
+                        else existing.project_path
+                    )
+                    effective_perms_json = permissions.serialize_effective_permissions(
+                        resolved_role
+                    )
+                    role_changed = resolved_role != existing.role
+                    was_inactive = not existing.active
+                    state_agents.update_agent_mutable_fields(
+                        conn,
+                        agent_id=existing.agent_id,
+                        role=resolved_role,
+                        capability=resolved_capability,
+                        label=resolved_label,
+                        project_path=resolved_project,
+                        effective_permissions_json=effective_perms_json,
+                        last_registered_at=now_iso,
+                        active=True,
+                    )
+                    final_agent_id = existing.agent_id
+                    created_or_reactivated = (
+                        "reactivated" if was_inactive else "updated"
+                    )
+                    if role_changed:
+                        audit_event = {
+                            "agent_id": existing.agent_id,
+                            "prior_role": existing.role,
+                            "new_role": resolved_role,
+                        }
+
+                final_record = _select_agent_full_by_id(conn, agent_id=final_agent_id)
+                conn.execute("COMMIT")
+            except RegistrationError:
+                conn.execute("ROLLBACK")
+                raise
+            except Exception:
+                conn.execute("ROLLBACK")
+                raise
+
+            assert final_record is not None  # invariant: just inserted/updated
+            outcome = _agent_full_record_to_register_payload(
+                final_record, created_or_reactivated=created_or_reactivated
+            )
+
+            # Audit row append happens AFTER COMMIT (FR-014). On failure
+            # the role mutation is already committed; emit a lifecycle
+            # event and return success — see module-docstring invariant.
+            # ``confirm_provided`` is hardcoded ``False`` for register_agent
+            # because there is no meaningful confirm at register-self
+            # (FR-010 makes the master boundary unconditional).
+            if audit_event is not None:
+                self._safe_append_audit(
+                    method_name="register_agent",
+                    socket_peer_uid=socket_peer_uid,
+                    confirm_provided=False,
+                    **audit_event,
+                )
+            return outcome
+        finally:
+            try:
+                conn.close()
+            except Exception:
+                pass
+
+    def _insert_with_savepoint_retry(
+        self,
+        conn: sqlite3.Connection,
+        *,
+        pane_key: PaneCompositeKey,
+        role: str,
+        capability: str,
+        label: str,
+        project_path: str,
+        parent_agent_id: str | None,
+        effective_perms_json: str,
+        now_iso: str,
+    ) -> str:
+        """INSERT a fresh agent row inside the caller's BEGIN IMMEDIATE.
+
+        Uses a SAVEPOINT per attempt so an ``agent_id`` PK collision can
+        be rolled back without dropping the outer transaction. Real PK
+        collisions are vanishingly rare at MVP scale (FR-001 / R-001);
+        the retry loop just keeps the daemon alive on the impossible
+        case. UNIQUE-constraint violations on the pane composite key
+        (impossible because we hold the per-pane mutex AND we already
+        SELECTed the row inside the tx) are surfaced as
+        ``internal_error`` rather than retried.
+        """
+        last_exc: Exception | None = None
+        for attempt in range(_AGENT_ID_RETRY_LIMIT):
+            agent_id = generate_agent_id()
+            savepoint = f"agent_insert_{attempt}"
+            conn.execute(f"SAVEPOINT {savepoint}")
+            try:
+                state_agents.insert_agent(
+                    conn,
+                    agent_id=agent_id,
+                    pane_key=pane_key,
+                    role=role,
+                    capability=capability,
+                    label=label,
+                    project_path=project_path,
+                    parent_agent_id=parent_agent_id,
+                    effective_permissions_json=effective_perms_json,
+                    created_at=now_iso,
+                    last_registered_at=now_iso,
+                    active=True,
+                )
+                conn.execute(f"RELEASE SAVEPOINT {savepoint}")
+                return agent_id
+            except sqlite3.IntegrityError as exc:
+                conn.execute(f"ROLLBACK TO SAVEPOINT {savepoint}")
+                conn.execute(f"RELEASE SAVEPOINT {savepoint}")
+                # Distinguish PK collision (retry with fresh id) from
+                # UNIQUE on the pane composite key (a real bug — caller
+                # ensures pane_key is not already bound) by inspecting
+                # the SQLite extended errcode rather than the localized
+                # English error text.
+                if getattr(exc, "sqlite_errorcode", None) == _SQLITE_CONSTRAINT_PRIMARYKEY:
+                    last_exc = exc
+                    continue
+                raise RegistrationError(
+                    "internal_error",
+                    f"agents insert failed: {exc}",
+                ) from exc
+            except Exception as exc:
+                conn.execute(f"ROLLBACK TO SAVEPOINT {savepoint}")
+                conn.execute(f"RELEASE SAVEPOINT {savepoint}")
+                raise RegistrationError(
+                    "internal_error",
+                    f"agents insert failed: {exc}",
+                ) from exc
+        raise RegistrationError(
+            "internal_error",
+            f"agent_id PK collision retry budget exhausted ({_AGENT_ID_RETRY_LIMIT})",
+        ) from last_exc
+
+    def _safe_append_audit(
+        self,
+        *,
+        method_name: str,
+        agent_id: str,
+        prior_role: str | None,
+        new_role: str,
+        confirm_provided: bool,
+        socket_peer_uid: int,
+    ) -> None:
+        """Append an audit row, swallowing-and-logging any append failure.
+
+        The role mutation is already committed by the caller. If the
+        JSONL append raises (disk full, fsync EIO, mode-broadening
+        race), we cannot roll back; emit ``audit_append_failed`` via
+        the lifecycle logger so the gap is observable, and return
+        normally so the caller still sees success. See the module
+        docstring's audit-append failure invariant.
+        """
+        try:
+            audit_mod.append_role_change(
+                self.events_file,
+                agent_id=agent_id,
+                prior_role=prior_role,
+                new_role=new_role,
+                confirm_provided=confirm_provided,
+                socket_peer_uid=socket_peer_uid,
+            )
+        except Exception as exc:
+            self._emit_lifecycle(
+                "audit_append_failed",
+                method=method_name,
+                agent_id=agent_id,
+                prior_role=prior_role,
+                new_role=new_role,
+                error=type(exc).__name__,
+                error_message=sanitize_text(str(exc), 512)[0],
+            )
+
+    def _validate_bound_pane_is_active(
+        self,
+        conn: sqlite3.Connection,
+        *,
+        pane_key: PaneCompositeKey,
+    ) -> None:
+        """Reject register_agent when the bound FEAT-004 pane/container is not active.
+
+        This closes the FEAT-004 reconciliation race window for
+        register-self: the client may have resolved a valid pane moments
+        earlier, but by the time this BEGIN IMMEDIATE transaction starts
+        the pane or its container may already be inactive. In that case,
+        register-self must follow the same closed-set failure surface as
+        the resolver miss path rather than creating/reactivating a ghost
+        agent row.
+        """
+        state = state_agents.select_active_for_bound_pane(conn, pane_key=pane_key)
+        if state != (True, True):
+            raise RegistrationError(
+                "pane_unknown_to_daemon",
+                "bound pane is absent or inactive in the FEAT-004 registry",
+            )
+
+    def _validate_parent_for_swarm(
+        self, conn: sqlite3.Connection, *, parent_agent_id: str
+    ) -> None:
+        """FR-017 dynamic parent validation — exists, active, role=slave."""
+        validate_agent_id_shape(parent_agent_id)
+        parent = state_agents.select_agent_by_id(conn, agent_id=parent_agent_id)
+        if parent is None:
+            raise RegistrationError(
+                "parent_not_found",
+                f"parent agent {parent_agent_id} not found",
+            )
+        if not parent.active:
+            raise RegistrationError(
+                "parent_inactive",
+                f"parent agent {parent_agent_id} is inactive",
+            )
+        if parent.role != "slave":
+            raise RegistrationError(
+                "parent_role_invalid",
+                f"parent agent must have role=slave (got {parent.role})",
+            )
+
+    # ------------------------------------------------------------------ #
+    # list_agents (FR-025 / FR-026 — read-only; no mutex; no Docker; no tmux)
+    # ------------------------------------------------------------------ #
+
+    # Closed set of filter keys ``list_agents`` accepts (FR-026).
+    # ``schema_version`` is the FR-040 forward-compat hint and is
+    # consumed by the shared preflight, not by the filter logic.
+    _LIST_AGENTS_ALLOWED_KEYS = frozenset(
+        {
+            "schema_version",
+            "role",
+            "container_id",
+            "active_only",
+            "parent_agent_id",
+        }
+    )
+
+    def list_agents(self, params: dict[str, Any]) -> dict[str, Any]:
+        # FR-040 forward-compat gate (run on every FEAT-006 method).
+        _check_schema_version(
+            params,
+            daemon_schema_version=self.schema_version,
+            method_name="list_agents",
+        )
+        # Validate filter keys against the closed set (FR-026). Keep the
+        # historical ``unknown_filter`` code for filter-key violations
+        # (rather than the generic ``bad_request``) — FR-026 and the
+        # existing test surface lock that spelling.
+        for key in params.keys():
+            if key not in self._LIST_AGENTS_ALLOWED_KEYS:
+                raise RegistrationError(
+                    "unknown_filter",
+                    f"unknown filter key {key!r}; allowed: "
+                    f"{sorted(self._LIST_AGENTS_ALLOWED_KEYS - {'schema_version'})}",
+                )
+
+        role_filter = params.get("role")
+        roles_normalized: list[str] | None = None
+        if role_filter is not None:
+            if isinstance(role_filter, str):
+                validation.validate_role(role_filter)
+                roles_normalized = [role_filter]
+            elif isinstance(role_filter, list):
+                roles_normalized = [validation.validate_role(r) for r in role_filter]
+            else:
+                raise RegistrationError(
+                    "value_out_of_set",
+                    "params.role must be a string or list of strings",
+                )
+
+        container_id = params.get("container_id")
+        if container_id is not None:
+            validation.validate_container_id_filter(container_id)
+
+        active_only_param = params.get("active_only", False)
+        if not isinstance(active_only_param, bool):
+            raise RegistrationError(
+                "value_out_of_set",
+                "params.active_only must be a boolean",
+            )
+
+        parent_agent_id = params.get("parent_agent_id")
+        if parent_agent_id is not None:
+            validation.validate_parent_agent_id_shape(parent_agent_id)
+
+        conn = self.connection_factory()
+        try:
+            rows = _list_agents_full(
+                conn,
+                role=roles_normalized,
+                container_id=container_id,
+                active_only=active_only_param,
+                parent_agent_id=parent_agent_id,
+            )
+        finally:
+            conn.close()
+
+        return {
+            "filter": {
+                "role": roles_normalized,
+                "container_id": container_id,
+                "active_only": active_only_param,
+                "parent_agent_id": parent_agent_id,
+            },
+            "agents": [_agent_full_record_to_dict(r) for r in rows],
+        }
+
+    # ------------------------------------------------------------------ #
+    # set_role / set_label / set_capability  (US2 / FR-011 / FR-012 /
+    # FR-013 / FR-014 / FR-027 / FR-031). Each method:
+    #
+    # 1. Runs the closed-set unknown-keys gate + schema_version preflight.
+    # 2. Validates the required ``agent_id`` + the field-specific value.
+    # 3. Acquires the per-agent_id mutex.
+    # 4. Opens BEGIN IMMEDIATE; re-SELECTs the agent inside the tx so
+    #    the no-op check, existence check, and active check all run
+    #    against a snapshot a concurrent FEAT-004 cascade or another
+    #    set_* call cannot race past.
+    # 5. Audit append (set_role only) is wrapped in try/except + lifecycle
+    #    log per the module-docstring invariant.
+    # ------------------------------------------------------------------ #
+
+    _SET_ROLE_ALLOWED_KEYS = frozenset(
+        {"schema_version", "agent_id", "role", "confirm"}
+    )
+    _SET_LABEL_ALLOWED_KEYS = frozenset(
+        {"schema_version", "agent_id", "label"}
+    )
+    _SET_CAPABILITY_ALLOWED_KEYS = frozenset(
+        {"schema_version", "agent_id", "capability"}
+    )
+
+    def set_role(
+        self, params: dict[str, Any], *, socket_peer_uid: int
+    ) -> dict[str, Any]:
+        _check_unknown_keys(
+            params, self._SET_ROLE_ALLOWED_KEYS, method_name="set_role"
+        )
+        _check_schema_version(
+            params,
+            daemon_schema_version=self.schema_version,
+            method_name="set_role",
+        )
+        agent_id = _require_string(params, "agent_id", method_name="set_role")
+        validate_agent_id_shape(agent_id)
+        new_role = _require_string(params, "role", method_name="set_role")
+        validation.validate_role(new_role)
+        confirm_raw = params.get("confirm", False)
+        if not isinstance(confirm_raw, bool):
+            raise RegistrationError(
+                "bad_request",
+                "set_role: params.confirm must be a boolean",
+            )
+        confirm = confirm_raw
+
+        # FR-012: set-role --role swarm is rejected unconditionally.
+        if new_role == "swarm":
+            raise RegistrationError(
+                "swarm_role_via_set_role_rejected",
+                "set-role --role swarm is rejected; use "
+                "`agenttower register-self --role swarm --parent <agent-id>` instead",
+            )
+        # FR-011: master promotion requires --confirm.
+        if new_role == "master" and not confirm:
+            raise RegistrationError(
+                "master_confirm_required",
+                "master role assignment requires --confirm",
+            )
+
+        with self.agent_locks.for_key(agent_id):
+            conn = self.connection_factory()
+            try:
+                effective_perms_json = permissions.serialize_effective_permissions(
+                    new_role
+                )
+
+                conn.execute("BEGIN IMMEDIATE")
+                try:
+                    # Atomic existence + active re-check inside the
+                    # transaction. Treats a missing containers row as
+                    # ``container_active = 0`` — without an active
+                    # container backing the agent, role assignment
+                    # (especially master promotion) MUST be refused.
+                    state = state_agents.select_active_for_role_and_container(
+                        conn, agent_id=agent_id
+                    )
+                    if state is None:
+                        conn.execute("ROLLBACK")
+                        raise RegistrationError(
+                            "agent_not_found", f"agent {agent_id} not found"
+                        )
+                    agent_active, container_active = state
+                    if not agent_active:
+                        conn.execute("ROLLBACK")
+                        raise RegistrationError(
+                            "agent_inactive",
+                            f"agent {agent_id} is inactive",
+                        )
+                    fresh = state_agents.select_agent_by_id(conn, agent_id=agent_id)
+                    assert fresh is not None  # invariant: state is not None
+                    prior_role = fresh.role
+                    if new_role == "master" and container_active is not True:
+                        conn.execute("ROLLBACK")
+                        raise RegistrationError(
+                            "agent_inactive",
+                            f"agent {agent_id} or its container is inactive",
+                        )
+                    if prior_role == new_role:
+                        # No-op short-circuit (FR-027) — same value, no
+                        # audit row, no UPDATE. The check runs INSIDE
+                        # BEGIN IMMEDIATE so a concurrent transition
+                        # cannot land between the read and our return.
+                        conn.execute("COMMIT")
+                        return {
+                            "agent_id": agent_id,
+                            "field": "role",
+                            "prior_value": prior_role,
+                            "new_value": new_role,
+                            "effective_permissions": fresh.effective_permissions,
+                            "audit_appended": False,
+                        }
+                    state_agents.update_agent_role(
+                        conn,
+                        agent_id=agent_id,
+                        role=new_role,
+                        effective_permissions_json=effective_perms_json,
+                    )
+                    conn.execute("COMMIT")
+                except RegistrationError:
+                    raise
+                except Exception:
+                    conn.execute("ROLLBACK")
+                    raise
+
+                # Audit row AFTER COMMIT (FR-014) — wrapped per the
+                # module-docstring invariant.
+                self._safe_append_audit(
+                    method_name="set_role",
+                    agent_id=agent_id,
+                    prior_role=prior_role,
+                    new_role=new_role,
+                    confirm_provided=confirm,
+                    socket_peer_uid=socket_peer_uid,
+                )
+                return {
+                    "agent_id": agent_id,
+                    "field": "role",
+                    "prior_value": prior_role,
+                    "new_value": new_role,
+                    "effective_permissions": permissions.effective_permissions(new_role),
+                    "audit_appended": True,
+                }
+            finally:
+                conn.close()
+
+    def set_label(
+        self, params: dict[str, Any], *, socket_peer_uid: int
+    ) -> dict[str, Any]:
+        _check_unknown_keys(
+            params, self._SET_LABEL_ALLOWED_KEYS, method_name="set_label"
+        )
+        _check_schema_version(
+            params,
+            daemon_schema_version=self.schema_version,
+            method_name="set_label",
+        )
+        agent_id = _require_string(params, "agent_id", method_name="set_label")
+        validate_agent_id_shape(agent_id)
+        if "label" not in params:
+            raise RegistrationError(
+                "bad_request",
+                "set_label: params.label is required",
+            )
+        new_label = validation.validate_label(params["label"])
+
+        with self.agent_locks.for_key(agent_id):
+            conn = self.connection_factory()
+            try:
+                conn.execute("BEGIN IMMEDIATE")
+                try:
+                    fresh = state_agents.select_agent_by_id(conn, agent_id=agent_id)
+                    if fresh is None:
+                        conn.execute("ROLLBACK")
+                        raise RegistrationError(
+                            "agent_not_found", f"agent {agent_id} not found"
+                        )
+                    if not fresh.active:
+                        conn.execute("ROLLBACK")
+                        raise RegistrationError(
+                            "agent_inactive", f"agent {agent_id} is inactive"
+                        )
+                    if fresh.label == new_label:
+                        conn.execute("COMMIT")
+                        return {
+                            "agent_id": agent_id,
+                            "field": "label",
+                            "prior_value": fresh.label,
+                            "new_value": new_label,
+                            "audit_appended": False,
+                        }
+                    state_agents.update_agent_label(
+                        conn, agent_id=agent_id, label=new_label
+                    )
+                    conn.execute("COMMIT")
+                except RegistrationError:
+                    raise
+                except Exception:
+                    conn.execute("ROLLBACK")
+                    raise
+                # set_label never appends an audit row (FR-014 only audits
+                # role transitions).
+                return {
+                    "agent_id": agent_id,
+                    "field": "label",
+                    "prior_value": fresh.label,
+                    "new_value": new_label,
+                    "audit_appended": False,
+                }
+            finally:
+                conn.close()
+
+    def set_capability(
+        self, params: dict[str, Any], *, socket_peer_uid: int
+    ) -> dict[str, Any]:
+        _check_unknown_keys(
+            params, self._SET_CAPABILITY_ALLOWED_KEYS, method_name="set_capability"
+        )
+        _check_schema_version(
+            params,
+            daemon_schema_version=self.schema_version,
+            method_name="set_capability",
+        )
+        agent_id = _require_string(params, "agent_id", method_name="set_capability")
+        validate_agent_id_shape(agent_id)
+        if "capability" not in params:
+            raise RegistrationError(
+                "bad_request",
+                "set_capability: params.capability is required",
+            )
+        new_capability = params["capability"]
+        validation.validate_capability(new_capability)
+
+        with self.agent_locks.for_key(agent_id):
+            conn = self.connection_factory()
+            try:
+                conn.execute("BEGIN IMMEDIATE")
+                try:
+                    fresh = state_agents.select_agent_by_id(conn, agent_id=agent_id)
+                    if fresh is None:
+                        conn.execute("ROLLBACK")
+                        raise RegistrationError(
+                            "agent_not_found", f"agent {agent_id} not found"
+                        )
+                    if not fresh.active:
+                        conn.execute("ROLLBACK")
+                        raise RegistrationError(
+                            "agent_inactive", f"agent {agent_id} is inactive"
+                        )
+                    if fresh.capability == new_capability:
+                        conn.execute("COMMIT")
+                        return {
+                            "agent_id": agent_id,
+                            "field": "capability",
+                            "prior_value": fresh.capability,
+                            "new_value": new_capability,
+                            "audit_appended": False,
+                        }
+                    state_agents.update_agent_capability(
+                        conn, agent_id=agent_id, capability=new_capability
+                    )
+                    conn.execute("COMMIT")
+                except RegistrationError:
+                    raise
+                except Exception:
+                    conn.execute("ROLLBACK")
+                    raise
+                return {
+                    "agent_id": agent_id,
+                    "field": "capability",
+                    "prior_value": fresh.capability,
+                    "new_value": new_capability,
+                    "audit_appended": False,
+                }
+            finally:
+                conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _opt(params: dict[str, Any], key: str) -> object:
+    """Return ``params[key]`` if present, else the ``_UNSET`` sentinel.
+
+    Encodes the Clarifications Q1 wire contract: "absent key" ≠ "explicit
+    null". The CLI MUST omit unsupplied flags so the daemon can leave
+    stored values unchanged on idempotent re-registration (FR-007).
+    """
+    return params[key] if key in params else _UNSET
+
+
+def _coerce_pane_key(value: Any) -> PaneCompositeKey:
+    """Validate, coerce, and defensively sanitize the wire pane composite key.
+
+    FR-024 trusts the CLI for identity, but the daemon still applies
+    NUL/control-byte stripping + length caps on the string fields so a
+    same-uid peer (or future automation that bypasses the official CLI)
+    cannot plant control bytes in the agents row that flow back through
+    list_agents into TSV/JSON.
+    """
+    if not isinstance(value, dict):
+        raise RegistrationError(
+            "bad_request",
+            "params.pane_composite_key must be an object",
+        )
+    required = (
+        "container_id",
+        "tmux_socket_path",
+        "tmux_session_name",
+        "tmux_window_index",
+        "tmux_pane_index",
+        "tmux_pane_id",
+    )
+    for k in required:
+        if k not in value:
+            raise RegistrationError(
+                "bad_request",
+                f"params.pane_composite_key.{k} is required",
+            )
+    try:
+        container_id = _sanitize_pane_field(str(value["container_id"]))
+        tmux_socket_path = _sanitize_pane_field(str(value["tmux_socket_path"]))
+        tmux_session_name = _sanitize_pane_field(str(value["tmux_session_name"]))
+        tmux_pane_id = _sanitize_pane_field(str(value["tmux_pane_id"]))
+        return (
+            container_id,
+            tmux_socket_path,
+            tmux_session_name,
+            int(value["tmux_window_index"]),
+            int(value["tmux_pane_index"]),
+            tmux_pane_id,
+        )
+    except (TypeError, ValueError) as exc:
+        raise RegistrationError(
+            "tmux_pane_malformed",
+            f"params.pane_composite_key has malformed field: {exc}",
+        ) from exc
+
+
+def _sanitize_pane_field(text: str) -> str:
+    """Strip control bytes + cap length for pane composite-key strings."""
+    bounded, _ = sanitize_text(text, _PANE_FIELD_MAX_BYTES)
+    return bounded
+
+
+# ---------------------------------------------------------------------------
+# Joined SELECTs — surface ``container_name``, ``container_user``,
+# ``pane_pid``, and ``cwd`` (= ``panes.pane_current_path``) on every
+# wire payload alongside the agents-row columns. The contract
+# (contracts/socket-api.md §2.1, §6.2 + cli.md C-CLI-602) requires
+# these in both ``register_agent`` and ``list_agents`` responses.
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _AgentFullRecord:
+    """An ``AgentRecord`` plus the four contract-required JOIN fields."""
+
+    agent: AgentRecord
+    container_name: str | None
+    container_user: str | None
+    pane_pid: int | None
+    cwd: str | None
+
+
+_JOINED_SELECT_TAIL = """
+    LEFT JOIN containers ON containers.container_id = agents.container_id
+    LEFT JOIN panes
+      ON panes.container_id = agents.container_id
+     AND panes.tmux_socket_path = agents.tmux_socket_path
+     AND panes.tmux_session_name = agents.tmux_session_name
+     AND panes.tmux_window_index = agents.tmux_window_index
+     AND panes.tmux_pane_index = agents.tmux_pane_index
+     AND panes.tmux_pane_id = agents.tmux_pane_id
+"""
+
+_JOINED_PROJECTION = """
+    agents.agent_id, agents.container_id,
+    agents.tmux_socket_path, agents.tmux_session_name,
+    agents.tmux_window_index, agents.tmux_pane_index, agents.tmux_pane_id,
+    agents.role, agents.capability, agents.label, agents.project_path,
+    agents.parent_agent_id, agents.effective_permissions,
+    agents.created_at, agents.last_registered_at, agents.last_seen_at,
+    agents.active,
+    COALESCE(containers.name, panes.container_name) AS container_name,
+    COALESCE(containers.config_user, panes.container_user) AS container_user,
+    panes.pane_pid AS pane_pid,
+    panes.pane_current_path AS cwd
+"""
+
+
+def _row_to_full_record(row: tuple) -> _AgentFullRecord:
+    import json as _json
+
+    agent = AgentRecord(
+        agent_id=row[0],
+        container_id=row[1],
+        tmux_socket_path=row[2],
+        tmux_session_name=row[3],
+        tmux_window_index=int(row[4]),
+        tmux_pane_index=int(row[5]),
+        tmux_pane_id=row[6],
+        role=row[7],
+        capability=row[8],
+        label=row[9],
+        project_path=row[10],
+        parent_agent_id=row[11],
+        effective_permissions=_json.loads(row[12]),
+        created_at=row[13],
+        last_registered_at=row[14],
+        last_seen_at=row[15],
+        active=bool(row[16]),
+    )
+    return _AgentFullRecord(
+        agent=agent,
+        container_name=row[17],
+        container_user=row[18],
+        pane_pid=int(row[19]) if row[19] is not None else None,
+        cwd=row[20],
+    )
+
+
+def _select_agent_full_by_id(
+    conn: sqlite3.Connection, *, agent_id: str
+) -> _AgentFullRecord | None:
+    sql = (
+        "SELECT" + _JOINED_PROJECTION + "FROM agents"
+        + _JOINED_SELECT_TAIL + "WHERE agents.agent_id = ?"
+    )
+    row = conn.execute(sql, (agent_id,)).fetchone()
+    return _row_to_full_record(row) if row is not None else None
+
+
+def _list_agents_full(
+    conn: sqlite3.Connection,
+    *,
+    role: list[str] | None,
+    container_id: str | None,
+    active_only: bool,
+    parent_agent_id: str | None,
+) -> list[_AgentFullRecord]:
+    """Mirror ``state_agents.list_agents`` with the contract JOIN fields."""
+    where: list[str] = []
+    params: list[Any] = []
+    if active_only:
+        where.append("agents.active = 1")
+    if role:
+        placeholders = ",".join("?" * len(role))
+        where.append(f"agents.role IN ({placeholders})")
+        params.extend(role)
+    if container_id is not None:
+        if len(container_id) == 64:
+            where.append("agents.container_id = ?")
+            params.append(container_id)
+        else:
+            # Index-friendly half-open range scan; mirrors the plain
+            # state_agents.list_agents() helper. ``substr(...)`` would
+            # defeat the agents_active_order index.
+            where.append("agents.container_id >= ? AND agents.container_id < ?")
+            params.append(container_id)
+            params.append(state_agents._next_lex_prefix(container_id))
+    if parent_agent_id is not None:
+        where.append("agents.parent_agent_id = ?")
+        params.append(parent_agent_id)
+    where_clause = "WHERE " + " AND ".join(where) if where else ""
+    order_by = (
+        "ORDER BY agents.active DESC, agents.container_id ASC, "
+        "agents.parent_agent_id ASC, agents.label ASC, agents.agent_id ASC"
+    )
+    sql = (
+        "SELECT" + _JOINED_PROJECTION + "FROM agents"
+        + _JOINED_SELECT_TAIL + where_clause + " " + order_by
+    )
+    return [_row_to_full_record(r) for r in conn.execute(sql, params).fetchall()]
+
+
+def _agent_full_record_to_dict(full: _AgentFullRecord) -> dict[str, Any]:
+    """Marshal an ``_AgentFullRecord`` into the wire JSON shape.
+
+    Surfaces the four contract-required JOIN fields
+    (``container_name``, ``container_user``, ``pane_pid``, ``cwd``)
+    alongside the agents-row columns. JOIN fields default to ``None``
+    when the bound containers/panes row was reaped (FEAT-003 / FEAT-004
+    reconciliation).
+    """
+    record = full.agent
+    return {
+        "agent_id": record.agent_id,
+        "container_id": record.container_id,
+        "container_name": full.container_name,
+        "container_user": full.container_user,
+        "tmux_socket_path": record.tmux_socket_path,
+        "tmux_session_name": record.tmux_session_name,
+        "tmux_window_index": record.tmux_window_index,
+        "tmux_pane_index": record.tmux_pane_index,
+        "tmux_pane_id": record.tmux_pane_id,
+        "pane_pid": full.pane_pid,
+        "cwd": full.cwd,
+        "role": record.role,
+        "capability": record.capability,
+        "label": record.label,
+        "project_path": record.project_path,
+        "parent_agent_id": record.parent_agent_id,
+        "effective_permissions": record.effective_permissions,
+        "created_at": record.created_at,
+        "last_registered_at": record.last_registered_at,
+        "last_seen_at": record.last_seen_at,
+        "active": record.active,
+    }
+
+
+def _agent_full_record_to_register_payload(
+    full: _AgentFullRecord, *, created_or_reactivated: str
+) -> dict[str, Any]:
+    payload = _agent_full_record_to_dict(full)
+    payload["created_or_reactivated"] = created_or_reactivated
+    return payload
diff --git a/src/agenttower/agents/validation.py b/src/agenttower/agents/validation.py
new file mode 100644
index 0000000..3a74291
--- /dev/null
+++ b/src/agenttower/agents/validation.py
@@ -0,0 +1,174 @@
+"""Closed-set validators and free-text bounds for FEAT-006.
+
+All validators raise :class:`RegistrationError` carrying the FEAT-006
+closed-set code so the service layer maps straight to the wire envelope.
+Case-sensitivity is strict per Clarifications session
+2026-05-07-continued Q2 — mixed-case inputs are rejected, not normalized.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+from ..tmux.parsers import sanitize_text
+from .errors import RegistrationError
+from .identifiers import AGENT_ID_RE
+
+
+VALID_ROLES: Final[tuple[str, ...]] = (
+    "master",
+    "slave",
+    "swarm",
+    "test-runner",
+    "shell",
+    "unknown",
+)
+VALID_CAPABILITIES: Final[tuple[str, ...]] = (
+    "claude",
+    "codex",
+    "gemini",
+    "opencode",
+    "shell",
+    "test-runner",
+    "unknown",
+)
+
+# Per-field bounds (FR-033 / FR-034).
+LABEL_MAX = 64
+PROJECT_PATH_MAX = 4096
+
+# FR-026: filter accepts the 12-char short-id form OR the full 64-char id.
+# Lengths in between are not part of the documented surface — accepting them
+# here would let arbitrary 13..63-char prefixes silently match via the
+# ``substr(...)`` fallback the daemon uses for short ids.
+_CONTAINER_ID_RE: Final[re.Pattern[str]] = re.compile(r"^[0-9a-f]{12}([0-9a-f]{52})?$")
+
+
+def validate_role(value: object) -> str:
+    """Return *value* if it is in :data:`VALID_ROLES` (case-sensitive), else raise.
+
+    Mixed-case (``Slave``, ``MASTER``, ``Test-Runner``) is rejected with
+    ``value_out_of_set`` and NOT normalized (FR-004 / Clarifications Q2).
+    """
+    if not isinstance(value, str) or value not in VALID_ROLES:
+        raise RegistrationError(
+            "value_out_of_set",
+            f"role must be one of {list(VALID_ROLES)}; got {value!r}",
+        )
+    return value
+
+
+def validate_capability(value: object) -> str:
+    """Return *value* if it is in :data:`VALID_CAPABILITIES`, else raise.
+
+    Case-sensitive per FR-005 / Clarifications Q2. Mixed-case is rejected.
+    """
+    if not isinstance(value, str) or value not in VALID_CAPABILITIES:
+        raise RegistrationError(
+            "value_out_of_set",
+            f"capability must be one of {list(VALID_CAPABILITIES)}; got {value!r}",
+        )
+    return value
+
+
+def validate_label(value: object) -> str:
+    """Return *value* sanitized (NUL-strip, C0-strip) if ≤ 64 chars, else raise.
+
+    Oversized values raise ``field_too_long`` per FR-033 — never silently
+    truncated. Inherits :func:`agenttower.tmux.parsers.sanitize_text` byte
+    classes so the rule matches FEAT-004 sanitization.
+    """
+    if not isinstance(value, str):
+        raise RegistrationError(
+            "value_out_of_set",
+            f"label must be a string; got {type(value).__name__}",
+        )
+    cleaned, truncated = sanitize_text(value, LABEL_MAX)
+    if truncated:
+        raise RegistrationError(
+            "field_too_long",
+            f"label exceeds maximum length {LABEL_MAX}",
+        )
+    return cleaned
+
+
+def validate_project_path(value: object) -> str:
+    """Validate *value* against FR-034 + FR-033 and return a sanitized copy.
+
+    - non-empty, absolute path (starts with ``/``)
+    - no NUL byte
+    - no C0 control bytes (stripped before any other check; if stripping
+      pushes the path past ``PROJECT_PATH_MAX`` the input is rejected
+      with ``field_too_long``)
+    - no ``..`` segment in the *supplied* path. We deliberately do NOT
+      call ``os.path.normpath`` first — a normpath collapse would turn
+      ``/a/../b`` into ``/b`` and silently accept the social-engineered
+      value, defeating spec edge case line 99 + FR-034.
+    - ≤ 4096 chars (FR-033)
+
+    Existence on the host filesystem is NOT checked (the path is observed
+    inside the container's mount namespace).
+    """
+    if not isinstance(value, str):
+        raise RegistrationError(
+            "project_path_invalid",
+            f"project_path must be a string; got {type(value).__name__}",
+        )
+    if "\x00" in value:
+        raise RegistrationError(
+            "project_path_invalid",
+            "project_path must not contain NUL bytes",
+        )
+    cleaned = "".join(ch for ch in value if ord(ch) >= 0x20 and ord(ch) != 0x7F)
+    truncated = len(cleaned) > PROJECT_PATH_MAX
+    if truncated:
+        raise RegistrationError(
+            "field_too_long",
+            f"project_path exceeds maximum length {PROJECT_PATH_MAX}",
+        )
+    value = cleaned
+    if value == "":
+        raise RegistrationError(
+            "project_path_invalid",
+            "project_path must be a non-empty absolute path",
+        )
+    if not value.startswith("/"):
+        raise RegistrationError(
+            "project_path_invalid",
+            f"project_path must be absolute (start with '/'); got {value!r}",
+        )
+    # ``..`` segment check on the *supplied* path so social-engineered values
+    # like ``/a/../b`` are rejected even though ``os.path.normpath`` would
+    # collapse them to ``/b`` (spec edge case line 99 + FR-034).
+    if ".." in value.split("/"):
+        raise RegistrationError(
+            "project_path_invalid",
+            f"project_path must not contain '..' segment; got {value!r}",
+        )
+    return value
+
+
+def validate_container_id_filter(value: object) -> str:
+    """Validate ``container_id`` filter shape (FR-026); case-sensitive lowercase hex.
+
+    Accepts exactly the 12-char short-id form OR the full 64-char id —
+    no in-between lengths.
+    """
+    if not isinstance(value, str) or not _CONTAINER_ID_RE.match(value):
+        raise RegistrationError(
+            "value_out_of_set",
+            "container_id must be a 12-char short id or a 64-char full id "
+            f"(lowercase hex); got {value!r}",
+        )
+    return value
+
+
+def validate_parent_agent_id_shape(value: object) -> str:
+    """Validate ``parent_agent_id`` against the agent_id shape regex."""
+    if not isinstance(value, str) or not AGENT_ID_RE.match(value):
+        raise RegistrationError(
+            "value_out_of_set",
+            f"parent_agent_id must match agt_<12-hex-lowercase>; got {value!r}",
+        )
+    return value
diff --git a/src/agenttower/cli.py b/src/agenttower/cli.py
index 9471832..4341f87 100644
--- a/src/agenttower/cli.py
+++ b/src/agenttower/cli.py
@@ -11,7 +11,10 @@
 import sys
 import time
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .agents.errors import RegistrationError
 
 from . import __version__
 from .config import _DIR_MODE, _ensure_dir_chain, write_default_config
@@ -667,6 +670,135 @@ def _build_parser() -> argparse.ArgumentParser:
     list_panes.add_argument("--json", action="store_true", help=JSON_LINE_HELP)
     list_panes.set_defaults(_handler=_list_panes_command)
 
+    # ------------------------------------------------------------------
+    # FEAT-006 — register-self / list-agents / set-* subparsers.
+    #
+    # Per Clarifications Q1 / FR-007 the CLI MUST NOT transmit
+    # argparse-style defaults on idempotent re-registration of an
+    # existing pane: omitted flags are absent in the parsed Namespace
+    # so the daemon leaves stored values unchanged. We use
+    # ``argparse.SUPPRESS`` as the per-flag default so omitted flags
+    # never appear in the Namespace at all (research R-002).
+    # ------------------------------------------------------------------
+
+    from .agents.validation import VALID_CAPABILITIES, VALID_ROLES
+
+    _ROLES_LIST = ", ".join(VALID_ROLES)
+    _CAPS_LIST = ", ".join(VALID_CAPABILITIES)
+    _AGENT_ID_HELP = "target agent_id (matches agt_<12-hex-lowercase>)"
+
+    register_self = subparsers.add_parser(
+        "register-self",
+        help="register the current tmux pane as an AgentTower agent",
+        description="register the current tmux pane as an AgentTower agent",
+    )
+    register_self.add_argument(
+        "--role",
+        default=argparse.SUPPRESS,
+        help=f"role to assign on first registration (one of: {_ROLES_LIST}). "
+        "register-self never accepts master; use set-role for promotion (FR-010).",
+    )
+    register_self.add_argument(
+        "--capability",
+        default=argparse.SUPPRESS,
+        help=f"capability descriptor (one of: {_CAPS_LIST}).",
+    )
+    register_self.add_argument(
+        "--label",
+        default=argparse.SUPPRESS,
+        help="free-text label, sanitized + bounded to 64 chars.",
+    )
+    register_self.add_argument(
+        "--project",
+        default=argparse.SUPPRESS,
+        help="absolute path inside the container (no '..' segments, "
+        "no NUL, ≤ 4096 chars).",
+    )
+    register_self.add_argument(
+        "--parent",
+        default=argparse.SUPPRESS,
+        help="parent agent_id when --role swarm (immutable after creation).",
+    )
+    register_self.add_argument("--json", action="store_true", help=JSON_LINE_HELP)
+    register_self.set_defaults(_handler=_register_self_command)
+
+    list_agents = subparsers.add_parser(
+        "list-agents",
+        help="list registered AgentTower agents",
+        description="list registered AgentTower agents",
+    )
+    list_agents.add_argument(
+        "--role",
+        action="append",
+        default=None,
+        help="filter by role (repeatable to OR multiple roles)",
+    )
+    list_agents.add_argument(
+        "--container",
+        default=None,
+        help="filter by exact container id, 12-char short prefix, or 64-char hex",
+    )
+    list_agents.add_argument(
+        "--active-only",
+        action="store_true",
+        help="only return currently-active agents",
+    )
+    list_agents.add_argument(
+        "--parent",
+        default=None,
+        help="filter swarm children of the given parent agent_id",
+    )
+    list_agents.add_argument("--json", action="store_true", help=JSON_LINE_HELP)
+    list_agents.set_defaults(_handler=_list_agents_command)
+
+    set_role = subparsers.add_parser(
+        "set-role",
+        help="change an agent's role (master requires --confirm)",
+        description="change an agent's role (master requires --confirm)",
+    )
+    set_role.add_argument("--target", required=True, help=_AGENT_ID_HELP)
+    set_role.add_argument(
+        "--role",
+        required=True,
+        help=f"new role (one of: {_ROLES_LIST}). "
+        "swarm rejected (use register-self); master requires --confirm.",
+    )
+    set_role.add_argument(
+        "--confirm",
+        action="store_true",
+        help="required when --role master (FR-011).",
+    )
+    set_role.add_argument("--json", action="store_true", help=JSON_LINE_HELP)
+    set_role.set_defaults(_handler=_set_role_command)
+
+    set_label = subparsers.add_parser(
+        "set-label",
+        help="change an agent's free-text label",
+        description="change an agent's free-text label",
+    )
+    set_label.add_argument("--target", required=True, help=_AGENT_ID_HELP)
+    set_label.add_argument(
+        "--label",
+        required=True,
+        help="new label (sanitized + bounded to 64 chars).",
+    )
+    set_label.add_argument("--json", action="store_true", help=JSON_LINE_HELP)
+    set_label.set_defaults(_handler=_set_label_command)
+
+    set_capability = subparsers.add_parser(
+        "set-capability",
+        help="change an agent's capability descriptor",
+        description="change an agent's capability descriptor",
+    )
+    set_capability.add_argument("--target", required=True, help=_AGENT_ID_HELP)
+    set_capability.add_argument(
+        "--capability",
+        required=True,
+        help=f"new capability (one of: {_CAPS_LIST}).",
+    )
+    set_capability.add_argument("--json", action="store_true", help=JSON_LINE_HELP)
+    set_capability.set_defaults(_handler=_set_capability_command)
+
     return parser
 
 
@@ -929,6 +1061,394 @@ def _list_panes_command(args: argparse.Namespace) -> int:
     return 0
 
 
+# ---------------------------------------------------------------------------
+# FEAT-006 — register-self / list-agents / set-* command handlers.
+# ---------------------------------------------------------------------------
+
+# Keys we look for on the parsed argparse.Namespace for the supplied-vs-default
+# wire contract (Clarifications Q1). Using ``argparse.SUPPRESS`` as the default
+# means absent flags are NOT attributes on the Namespace.
+_REGISTER_SELF_OPTIONAL = (
+    ("role", "role"),
+    ("capability", "capability"),
+    ("label", "label"),
+    ("project", "project_path"),
+    ("parent", "parent_agent_id"),
+)
+
+
+def _register_self_command(args: argparse.Namespace) -> int:
+    """Resolve identity, build the request envelope, and call register_agent."""
+    from .agents.client_resolve import resolve_pane_composite_key
+    from .agents.errors import RegistrationError
+
+    _, resolved = _resolve_socket_with_paths()
+    socket_path = resolved.path
+
+    # Client-side mirror of FR-010 (review-pass-6 N13). Rejecting
+    # ``--role master`` before the multi-call resolve_pane_composite_key
+    # round-trip is symmetric with the set-role swarm gate: we save the
+    # operator several Docker/tmux scans on a known-bad combo.
+    if hasattr(args, "role") and args.role == "master":
+        _emit_local_error(
+            "master_via_register_self_rejected",
+            "register-self cannot assign role=master; register first, "
+            "then run `agenttower set-role --role master --confirm`",
+            args.json,
+        )
+        return 3
+
+    try:
+        target = resolve_pane_composite_key(
+            socket_path=socket_path,
+            env=os.environ,
+            proc_root=os.environ.get("AGENTTOWER_TEST_PROC_ROOT"),
+            connect_timeout=1.0,
+            read_timeout=5.0,
+        )
+    except RegistrationError as exc:
+        return _emit_register_error(exc, args.json)
+    except DaemonUnavailable:
+        print(DAEMON_UNAVAILABLE_MESSAGE, file=sys.stderr)
+        return 2
+    except DaemonError as exc:
+        return _emit_daemon_error(exc, args.json)
+
+    # Forward-compat handshake (FR-040 / edge case line 79). The CLI
+    # advertises the schema version it was built against so the daemon
+    # can refuse with ``schema_version_newer`` when its own schema has
+    # advanced past what the CLI knows. Without this hint the server
+    # cannot detect a stale CLI calling a newer daemon.
+    from .config_doctor import MAX_SUPPORTED_SCHEMA_VERSION
+
+    params: dict[str, Any] = {
+        "schema_version": int(MAX_SUPPORTED_SCHEMA_VERSION),
+        "container_id": target.container_id,
+        "pane_composite_key": {
+            "container_id": target.pane_key[0],
+            "tmux_socket_path": target.pane_key[1],
+            "tmux_session_name": target.pane_key[2],
+            "tmux_window_index": target.pane_key[3],
+            "tmux_pane_index": target.pane_key[4],
+            "tmux_pane_id": target.pane_key[5],
+        },
+    }
+    # Only-supplied-fields-overwrite (Clarifications Q1): we include each
+    # mutable field iff the user passed the flag. argparse.SUPPRESS made
+    # omitted flags absent from the Namespace, so a hasattr/getattr probe
+    # is sufficient to distinguish "supplied" from "not supplied".
+    for ns_attr, wire_key in _REGISTER_SELF_OPTIONAL:
+        if hasattr(args, ns_attr):
+            params[wire_key] = getattr(args, ns_attr)
+
+    try:
+        result = send_request(
+            socket_path,
+            "register_agent",
+            params,
+            connect_timeout=1.0,
+            read_timeout=5.0,
+        )
+    except DaemonUnavailable:
+        print(DAEMON_UNAVAILABLE_MESSAGE, file=sys.stderr)
+        return 2
+    except DaemonError as exc:
+        return _emit_daemon_error(exc, args.json)
+
+    if args.json:
+        print(json.dumps({"ok": True, "result": result}))
+    else:
+        # Defensive scrubbing on free-text fields: daemon-side sanitization
+        # already strips C0 controls, but applying _scrub_for_tsv here
+        # keeps the one-line-per-key shape robust if a future schema
+        # ever loosens that guarantee.
+        print(f"agent_id={result.get('agent_id')}")
+        print(f"role={result.get('role')}")
+        print(f"capability={result.get('capability')}")
+        print(f"label={_scrub_for_tsv(result.get('label', ''))}")
+        print(f"project_path={_scrub_for_tsv(result.get('project_path', ''))}")
+        print(f"parent_agent_id={result.get('parent_agent_id') or '-'}")
+        print(f"created_or_reactivated={result.get('created_or_reactivated')}")
+    return 0
+
+
+def _list_agents_command(args: argparse.Namespace) -> int:
+    from .config_doctor import MAX_SUPPORTED_SCHEMA_VERSION
+
+    _, resolved = _resolve_socket_with_paths()
+    socket_path = resolved.path
+
+    # Every FEAT-006 CLI request advertises the schema version it was
+    # built against so the daemon can refuse with ``schema_version_newer``
+    # when its own schema has advanced past what the CLI knows
+    # (FR-040 / review-pass-6 K1+N14). Without this hint, the daemon-side
+    # forward-compat gate is unreachable for list-agents and set-*.
+    params: dict[str, Any] = {"schema_version": int(MAX_SUPPORTED_SCHEMA_VERSION)}
+    if args.role:
+        params["role"] = args.role
+    if args.container is not None:
+        params["container_id"] = args.container
+    if args.active_only:
+        params["active_only"] = True
+    if args.parent is not None:
+        params["parent_agent_id"] = args.parent
+
+    try:
+        result = send_request(
+            socket_path,
+            "list_agents",
+            params,
+            connect_timeout=1.0,
+            read_timeout=5.0,
+        )
+    except DaemonUnavailable:
+        print(DAEMON_UNAVAILABLE_MESSAGE, file=sys.stderr)
+        return 2
+    except DaemonError as exc:
+        return _emit_daemon_error(exc, args.json)
+
+    if args.json:
+        print(json.dumps({"ok": True, "result": result}))
+        return 0
+    # FR-029 locked TSV column schema with required header row.
+    print(
+        "AGENT_ID\tLABEL\tROLE\tCAPABILITY\tCONTAINER\tPANE\tPROJECT\tPARENT\tACTIVE"
+    )
+    for agent in result.get("agents", []):
+        agent_id = agent.get("agent_id", "")
+        label = _scrub_for_tsv(agent.get("label", ""))
+        role = agent.get("role", "")
+        capability = agent.get("capability", "")
+        container_short = (agent.get("container_id") or "")[:12]
+        # Defensive int coercion: schema stores tmux_window_index /
+        # tmux_pane_index as NOT NULL ints, but a future schema drift
+        # or test fixture sending null would otherwise render
+        # "main:None.0". Fall back to 0 (which is a real pane index
+        # so still readable) rather than emitting "None".
+        window_idx = agent.get("tmux_window_index")
+        pane_idx = agent.get("tmux_pane_index")
+        pane = (
+            f"{_scrub_for_tsv(agent.get('tmux_session_name', ''))}:"
+            f"{int(window_idx) if window_idx is not None else 0}."
+            f"{int(pane_idx) if pane_idx is not None else 0}"
+        )
+        project = _scrub_for_tsv(agent.get("project_path", ""))
+        parent_full = agent.get("parent_agent_id")
+        parent = parent_full if parent_full else "-"
+        active = "true" if agent.get("active") else "false"
+        print(
+            f"{agent_id}\t{label}\t{role}\t{capability}\t"
+            f"{container_short}\t{pane}\t{project}\t{parent}\t{active}"
+        )
+    return 0
+
+
+def _validate_target_shape(target: Any, json_mode: bool) -> int | None:
+    """Validate a ``--target`` arg against ``agt_<12-hex-lowercase>``.
+
+    Returns ``None`` if the target is well-formed; otherwise emits a
+    ``value_out_of_set`` error via the shared helper and returns the
+    CLI exit code (3). Centralizing the gate lets each set-* command
+    fail fast on a bad target before any role/label/capability gate
+    runs (R-020 / contracts/cli.md), so a single invocation surfaces
+    the most actionable error rather than ping-ponging the user
+    between rejections.
+    """
+    from .agents.identifiers import AGENT_ID_RE
+
+    if not isinstance(target, str) or not AGENT_ID_RE.match(target):
+        _emit_local_error(
+            "value_out_of_set",
+            f"--target must match agt_<12-hex-lowercase>; got {target!r}",
+            json_mode,
+        )
+        return 3
+    return None
+
+
+def _set_role_command(args: argparse.Namespace) -> int:
+    _, resolved = _resolve_socket_with_paths()
+    socket_path = resolved.path
+
+    # Target-shape gate first so a malformed --target surfaces before
+    # any role-specific rejection (review-pass-6 N32).
+    target_err = _validate_target_shape(args.target, args.json)
+    if target_err is not None:
+        return target_err
+
+    # Client-side mirror of FR-012 / FR-011 so we fail fast without a
+    # round-trip when the operator passed an obviously unsafe combo.
+    # The shared ``_emit_local_error`` helper enforces the ``--json``
+    # purity contract AND the established ``error: <msg>`` /
+    # ``code: <token>`` text-mode shape so both branches stay aligned.
+    if args.role == "swarm":
+        _emit_local_error(
+            "swarm_role_via_set_role_rejected",
+            # Single actionable message in both formats — JSON consumers
+            # shouldn't have to round-trip back to docs for the recovery
+            # step.
+            "set-role --role swarm is rejected; use "
+            "`agenttower register-self --role swarm --parent <agent-id>` instead",
+            args.json,
+        )
+        return 3
+    if args.role == "master" and not args.confirm:
+        _emit_local_error(
+            "master_confirm_required",
+            "master role assignment requires --confirm",
+            args.json,
+        )
+        return 3
+
+    from .config_doctor import MAX_SUPPORTED_SCHEMA_VERSION
+
+    params = {
+        "schema_version": int(MAX_SUPPORTED_SCHEMA_VERSION),
+        "agent_id": args.target,
+        "role": args.role,
+        "confirm": bool(args.confirm),
+    }
+    return _send_set_command(socket_path, "set_role", params, args.json)
+
+
+def _set_label_command(args: argparse.Namespace) -> int:
+    from .config_doctor import MAX_SUPPORTED_SCHEMA_VERSION
+
+    target_err = _validate_target_shape(args.target, args.json)
+    if target_err is not None:
+        return target_err
+    _, resolved = _resolve_socket_with_paths()
+    params = {
+        "schema_version": int(MAX_SUPPORTED_SCHEMA_VERSION),
+        "agent_id": args.target,
+        "label": args.label,
+    }
+    return _send_set_command(resolved.path, "set_label", params, args.json)
+
+
+def _set_capability_command(args: argparse.Namespace) -> int:
+    from .config_doctor import MAX_SUPPORTED_SCHEMA_VERSION
+
+    target_err = _validate_target_shape(args.target, args.json)
+    if target_err is not None:
+        return target_err
+    _, resolved = _resolve_socket_with_paths()
+    params = {
+        "schema_version": int(MAX_SUPPORTED_SCHEMA_VERSION),
+        "agent_id": args.target,
+        "capability": args.capability,
+    }
+    return _send_set_command(resolved.path, "set_capability", params, args.json)
+
+
+def _send_set_command(
+    socket_path: Path,
+    method: str,
+    params: dict[str, Any],
+    json_mode: bool,
+) -> int:
+    # Each ``set-*`` command pre-validates ``--target`` via
+    # :func:`_validate_target_shape` before reaching this transport
+    # helper, so the AGENT_ID_RE gate doesn't repeat here.
+    try:
+        result = send_request(
+            socket_path,
+            method,
+            params,
+            connect_timeout=1.0,
+            read_timeout=5.0,
+        )
+    except DaemonUnavailable:
+        print(DAEMON_UNAVAILABLE_MESSAGE, file=sys.stderr)
+        return 2
+    except DaemonError as exc:
+        return _emit_daemon_error(exc, json_mode)
+    if json_mode:
+        print(json.dumps({"ok": True, "result": result}))
+    else:
+        print(f"agent_id={result.get('agent_id')}")
+        print(f"field={result.get('field')}")
+        print(f"prior_value={result.get('prior_value')}")
+        print(f"new_value={result.get('new_value')}")
+        print(f"audit_appended={str(result.get('audit_appended', False)).lower()}")
+    return 0
+
+
+def _emit_local_error(code: str, message: str, json_mode: bool) -> None:
+    """Emit a local (pre-flight, client-side) closed-set error.
+
+    Centralizes the ``--json`` purity contract and the established
+    ``error: <msg>`` / ``code: <token>`` text-mode shape so every
+    pre-flight rejection stays consistent regardless of where it
+    originates. Caller picks the exit code so this helper is reusable
+    for both ``host_context_unsupported`` (exit 1) and the closed-set
+    daemon-error mirror (exit 3) cases.
+    """
+    if json_mode:
+        print(
+            json.dumps(
+                {
+                    "ok": False,
+                    "error": {"code": code, "message": message},
+                }
+            )
+        )
+    else:
+        print(f"error: {message}", file=sys.stderr)
+        print(f"code: {code}", file=sys.stderr)
+
+
+def _exit_code_for(code: str) -> int:
+    """Map a closed-set error code to its CLI exit code (FR-032 / FR-040).
+
+    ``host_context_unsupported`` is exit 1 (client-side context error —
+    the operator is on the host shell, not in a bench container).
+    Every other closed-set code is exit 3 (FEAT-002 / FEAT-005
+    daemon-error convention).  ``daemon_unavailable`` is handled by
+    callers (exit 2) before any error code is even raised.
+    """
+    if code == "host_context_unsupported":
+        return 1
+    return 3
+
+
+def _emit_register_error(exc: "RegistrationError", json_mode: bool) -> int:
+    """Map a client-side ``RegistrationError`` to the CLI exit-code surface.
+
+    Closed-set wire codes are surfaced verbatim via the shared
+    ``_emit_local_error`` helper so JSON purity / text-mode shape stay
+    aligned with every other pre-flight emitter.
+    """
+    _emit_local_error(exc.code, exc.message, json_mode)
+    return _exit_code_for(exc.code)
+
+
+def _emit_daemon_error(exc: DaemonError, json_mode: bool) -> int:
+    """Map a daemon-side ``DaemonError`` to the CLI exit-code surface.
+
+    Routed through the same exit-code mapper as ``_emit_register_error``
+    so a daemon-emitted ``host_context_unsupported`` (in principle
+    raisable any time daemon code surfaces it) exits 1, matching the
+    client-side mapping. Without this symmetry, the same closed-set
+    code would map to different exit codes depending on which side
+    raised it.
+    """
+    _emit_local_error(exc.code, exc.message, json_mode)
+    return _exit_code_for(exc.code)
+
+
+def _scrub_for_tsv(value: str) -> str:
+    """Replace embedded ``\\t`` and ``\\n`` with single spaces.
+
+    FR-029 / FR-033: free-text fields are sanitized at write time, but
+    we apply the same byte class here defensively so the TSV layout
+    can't be broken by a label that happened to contain a tab.
+    """
+    if not isinstance(value, str):
+        return ""
+    return value.replace("\t", " ").replace("\n", " ")
+
+
 def main(argv: list[str] | None = None) -> int:
     """Run the AgentTower CLI."""
     # A2 / FR-025 production guard: refuse to honor a leaked
diff --git a/src/agenttower/config_doctor/__init__.py b/src/agenttower/config_doctor/__init__.py
index dc125a8..a0351c1 100644
--- a/src/agenttower/config_doctor/__init__.py
+++ b/src/agenttower/config_doctor/__init__.py
@@ -8,7 +8,7 @@
 
 from __future__ import annotations
 
-MAX_SUPPORTED_SCHEMA_VERSION = 3
+MAX_SUPPORTED_SCHEMA_VERSION = 4
 """Highest SQLite schema_version this CLI build understands (R-010)."""
 
 # Re-exports — see plan §Structure Decision. These are imported lazily inside
diff --git a/src/agenttower/daemon.py b/src/agenttower/daemon.py
index 1b86d8f..df3211d 100644
--- a/src/agenttower/daemon.py
+++ b/src/agenttower/daemon.py
@@ -11,6 +11,8 @@
 from datetime import datetime, timezone
 
 from . import __version__
+from .agents.mutex import AgentLockMap, RegisterLockMap
+from .agents.service import AgentService
 from .config import load_containers_block
 from .discovery.pane_service import PaneDiscoveryService
 from .discovery.service import DiscoveryService
@@ -164,6 +166,33 @@ def _build_pane_service(
     return service, conn
 
 
+def _build_agent_service(paths: Paths, logger: LifecycleLogger) -> AgentService:
+    """Construct the FEAT-006 ``AgentService`` for the daemon.
+
+    Each call to a service method opens a fresh SQLite connection via the
+    factory so register_agent / list_agents / set_* run without sharing
+    a cursor across the accept-thread pool. Mutex registries are
+    process-scoped per FR-038 / FR-039.
+
+    The lifecycle *logger* is plumbed in so the FR-014 audit-append
+    failure invariant (see ``agents.service`` module docstring) is
+    operationally observable: post-COMMIT JSONL append failures emit
+    ``audit_append_failed`` events through the daemon's structured
+    logger rather than being silently lost.
+    """
+    schema_version = _read_schema_version(paths) or 0
+    return AgentService(
+        connection_factory=lambda: sqlite3.connect(
+            str(paths.state_db), isolation_level=None
+        ),
+        register_locks=RegisterLockMap(),
+        agent_locks=AgentLockMap(),
+        events_file=paths.events_file,
+        schema_version=schema_version,
+        lifecycle_logger=logger,
+    )
+
+
 def _build_context(
     *,
     paths: Paths,
@@ -171,6 +200,7 @@ def _build_context(
     shutdown_event: threading.Event,
     discovery_service: DiscoveryService | None,
     pane_service: PaneDiscoveryService | None,
+    agent_service: AgentService | None,
     logger: LifecycleLogger,
 ) -> DaemonContext:
     return DaemonContext(
@@ -183,6 +213,7 @@ def _build_context(
         shutdown_requested=shutdown_event,
         discovery_service=discovery_service,
         pane_service=pane_service,
+        agent_service=agent_service,
         events_file=paths.events_file,
         lifecycle_logger=logger,
     )
@@ -356,12 +387,14 @@ def _run(args: argparse.Namespace) -> int:
         shutdown_event = threading.Event()
         discovery_service, scan_db_conn = _build_discovery_service(paths, logger)
         pane_service, pane_db_conn = _build_pane_service(paths, logger)
+        agent_service = _build_agent_service(paths, logger)
         ctx = _build_context(
             paths=paths,
             state_dir=state_dir,
             shutdown_event=shutdown_event,
             discovery_service=discovery_service,
             pane_service=pane_service,
+            agent_service=agent_service,
             logger=logger,
         )
 
diff --git a/src/agenttower/discovery/pane_service.py b/src/agenttower/discovery/pane_service.py
index 34f5a47..d9662c7 100644
--- a/src/agenttower/discovery/pane_service.py
+++ b/src/agenttower/discovery/pane_service.py
@@ -37,6 +37,7 @@
 
 from ..events import writer as events_writer
 from ..socket_api import errors as _errors
+from ..state import agents as state_agents
 from ..state import containers as state_containers
 from ..state import panes as state_panes
 from ..state.panes import (
@@ -182,7 +183,11 @@ def list_panes(
     # -- scan_panes (acquires mutex; runs subprocess + reconcile + commit) ----
 
     def scan(self) -> PaneScanResult:
-        """Run one pane scan, serialized via the in-process pane mutex (FR-017)."""
+        """Run one pane scan across all active containers."""
+        return self.scan_for_container(container_id=None)
+
+    def scan_for_container(self, *, container_id: str | None) -> PaneScanResult:
+        """Run one pane scan, optionally scoped to a single active container."""
         with self._scan_mutex:
             scan_id = str(uuid.uuid4())
             started_at = _now_iso()
@@ -196,7 +201,11 @@ def scan(self) -> PaneScanResult:
                     message=_bound(f"pane_scan_started emit failed: {exc}"),
                 ) from exc
             try:
-                return self._scan_locked(scan_id=scan_id, started_at=started_at)
+                return self._scan_locked(
+                    scan_id=scan_id,
+                    started_at=started_at,
+                    container_filter=container_id,
+                )
             except TmuxError as exc:
                 if exc.code == _errors.DOCKER_UNAVAILABLE:
                     self._handle_docker_unavailable(
@@ -206,9 +215,23 @@ def scan(self) -> PaneScanResult:
 
     # -- Internals ------------------------------------------------------------
 
-    def _scan_locked(self, *, scan_id: str, started_at: str) -> PaneScanResult:
+    def _scan_locked(
+        self,
+        *,
+        scan_id: str,
+        started_at: str,
+        container_filter: str | None,
+    ) -> PaneScanResult:
         active_rows = state_containers.select_active_containers_with_user(self._conn)
+        if container_filter is not None:
+            active_rows = [row for row in active_rows if row[0] == container_filter]
         cascade_ids = state_containers.select_inactive_container_ids_with_panes(self._conn)
+        if container_filter is not None:
+            cascade_ids = {
+                container_id
+                for container_id in cascade_ids
+                if container_id == container_filter
+            }
         prior_panes = state_panes.select_all_panes(self._conn)
 
         per_container: list[_ContainerScanState] = []
@@ -427,6 +450,25 @@ def _commit_scan(
             state_panes.apply_pane_reconcile_writeset(
                 self._conn, write_set=write_set, now_iso=started_at
             )
+            # FEAT-006 FR-009a / FR-009 / Clarifications Q2: in the same
+            # transaction as the pane reconcile, update agents.last_seen_at
+            # for every pane observed during the scan and cascade
+            # agents.active=0 for every pane that transitioned 1→0. The
+            # FEAT-006 register-mutex is NOT acquired here; cross-subsystem
+            # ordering with register_agent is via SQLite BEGIN IMMEDIATE.
+            #
+            # Note: ``upsert.pane_active`` is the tmux *focus* flag (the
+            # single currently-selected pane within a window), not the
+            # FEAT-004 row-existence ``active`` flag. Filtering on it
+            # would have left every non-focused pane's bound agent with
+            # a stale ``last_seen_at`` even while its pane was alive.
+            observed_keys = [u.composite_key for u in write_set.upserts]
+            state_agents.update_last_seen_at(
+                self._conn, pane_keys=observed_keys, now_iso=started_at
+            )
+            state_agents.cascade_agents_active_from_pane(
+                self._conn, pane_keys=write_set.inactivate
+            )
             completed_at = _now_iso()
             state_panes.insert_pane_scan(
                 self._conn,
diff --git a/src/agenttower/socket_api/client.py b/src/agenttower/socket_api/client.py
index f0f7d62..de21675 100644
--- a/src/agenttower/socket_api/client.py
+++ b/src/agenttower/socket_api/client.py
@@ -164,6 +164,37 @@ def send_request(
     )
 
 
+def register_agent(
+    socket_path: Path, params: dict[str, Any]
+) -> dict[str, Any]:
+    """Typed wrapper for FEAT-006 ``register_agent`` (FR-023).
+
+    Reuses the same connect / framing path as :func:`send_request`. Raises
+    :class:`DaemonUnavailable` on socket-level failure and
+    :class:`DaemonError` carrying the closed-set ``code`` on a daemon
+    error envelope.
+    """
+    return send_request(socket_path, "register_agent", params)
+
+
+def list_agents(
+    socket_path: Path, params: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    return send_request(socket_path, "list_agents", params)
+
+
+def set_role(socket_path: Path, params: dict[str, Any]) -> dict[str, Any]:
+    return send_request(socket_path, "set_role", params)
+
+
+def set_label(socket_path: Path, params: dict[str, Any]) -> dict[str, Any]:
+    return send_request(socket_path, "set_label", params)
+
+
+def set_capability(socket_path: Path, params: dict[str, Any]) -> dict[str, Any]:
+    return send_request(socket_path, "set_capability", params)
+
+
 def _connect_via_chdir(sock: socket.socket, socket_path: Path) -> None:
     """Connect to *socket_path* via ``chdir(parent) + connect(basename)``.
 
diff --git a/src/agenttower/socket_api/errors.py b/src/agenttower/socket_api/errors.py
index 8ebb5ac..df76ad6 100644
--- a/src/agenttower/socket_api/errors.py
+++ b/src/agenttower/socket_api/errors.py
@@ -33,6 +33,29 @@
 OUTPUT_MALFORMED: Final[str] = "output_malformed"
 BENCH_USER_UNRESOLVED: Final[str] = "bench_user_unresolved"
 
+# FEAT-006 additions (research R-010 / FR-040).
+HOST_CONTEXT_UNSUPPORTED: Final[str] = "host_context_unsupported"
+CONTAINER_UNRESOLVED: Final[str] = "container_unresolved"
+NOT_IN_TMUX: Final[str] = "not_in_tmux"
+TMUX_PANE_MALFORMED: Final[str] = "tmux_pane_malformed"
+PANE_UNKNOWN_TO_DAEMON: Final[str] = "pane_unknown_to_daemon"
+AGENT_NOT_FOUND: Final[str] = "agent_not_found"
+AGENT_INACTIVE: Final[str] = "agent_inactive"
+PARENT_NOT_FOUND: Final[str] = "parent_not_found"
+PARENT_INACTIVE: Final[str] = "parent_inactive"
+PARENT_ROLE_INVALID: Final[str] = "parent_role_invalid"
+PARENT_ROLE_MISMATCH: Final[str] = "parent_role_mismatch"
+PARENT_IMMUTABLE: Final[str] = "parent_immutable"
+SWARM_PARENT_REQUIRED: Final[str] = "swarm_parent_required"
+SWARM_ROLE_VIA_SET_ROLE_REJECTED: Final[str] = "swarm_role_via_set_role_rejected"
+MASTER_VIA_REGISTER_SELF_REJECTED: Final[str] = "master_via_register_self_rejected"
+MASTER_CONFIRM_REQUIRED: Final[str] = "master_confirm_required"
+VALUE_OUT_OF_SET: Final[str] = "value_out_of_set"
+FIELD_TOO_LONG: Final[str] = "field_too_long"
+PROJECT_PATH_INVALID: Final[str] = "project_path_invalid"
+UNKNOWN_FILTER: Final[str] = "unknown_filter"
+SCHEMA_VERSION_NEWER: Final[str] = "schema_version_newer"
+
 CLOSED_CODE_SET: Final[frozenset[str]] = frozenset(
     {
         BAD_JSON,
@@ -54,6 +77,27 @@
         DOCKER_EXEC_TIMEOUT,
         OUTPUT_MALFORMED,
         BENCH_USER_UNRESOLVED,
+        HOST_CONTEXT_UNSUPPORTED,
+        CONTAINER_UNRESOLVED,
+        NOT_IN_TMUX,
+        TMUX_PANE_MALFORMED,
+        PANE_UNKNOWN_TO_DAEMON,
+        AGENT_NOT_FOUND,
+        AGENT_INACTIVE,
+        PARENT_NOT_FOUND,
+        PARENT_INACTIVE,
+        PARENT_ROLE_INVALID,
+        PARENT_ROLE_MISMATCH,
+        PARENT_IMMUTABLE,
+        SWARM_PARENT_REQUIRED,
+        SWARM_ROLE_VIA_SET_ROLE_REJECTED,
+        MASTER_VIA_REGISTER_SELF_REJECTED,
+        MASTER_CONFIRM_REQUIRED,
+        VALUE_OUT_OF_SET,
+        FIELD_TOO_LONG,
+        PROJECT_PATH_INVALID,
+        UNKNOWN_FILTER,
+        SCHEMA_VERSION_NEWER,
     }
 )
 
diff --git a/src/agenttower/socket_api/methods.py b/src/agenttower/socket_api/methods.py
index bcab83b..9d607eb 100644
--- a/src/agenttower/socket_api/methods.py
+++ b/src/agenttower/socket_api/methods.py
@@ -23,7 +23,15 @@
     from ..discovery.service import DiscoveryService
 
 # ``Handler`` returns the response envelope (already shaped via make_ok / make_error).
-Handler = Callable[["DaemonContext", dict[str, Any]], dict[str, Any]]
+# ``peer_uid`` is the SO_PEERCRED-derived uid of the AF_UNIX peer, injected by
+# the server out-of-band so it cannot be spoofed via the request body. Tests
+# that invoke handlers directly may rely on the default sentinel ``-1``.
+Handler = Callable[..., dict[str, Any]]
+
+
+# Sentinel used when no peer-credential information is available
+# (e.g. unit tests calling DISPATCH directly without a real socket).
+_NO_PEER_UID = -1
 
 
 @dataclass
@@ -39,15 +47,16 @@ class DaemonContext:
     shutdown_requested: threading.Event | None = None
     discovery_service: "DiscoveryService | None" = None
     pane_service: "PaneDiscoveryService | None" = None
+    agent_service: Any = None
     events_file: Path | None = None
     lifecycle_logger: Any = None
 
 
-def _ping(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
+def _ping(ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID) -> dict[str, Any]:
     return errors.make_ok({})
 
 
-def _status(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
+def _status(ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID) -> dict[str, Any]:
     now = datetime.now(timezone.utc)
     delta = (now - ctx.start_time_utc).total_seconds()
     uptime_seconds = max(0, int(delta))
@@ -65,7 +74,7 @@ def _status(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
     )
 
 
-def _shutdown(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
+def _shutdown(ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID) -> dict[str, Any]:
     if ctx.shutdown_requested is not None:
         ctx.shutdown_requested.set()
     return errors.make_ok({"shutting_down": True})
@@ -93,7 +102,7 @@ def _scan_result_to_payload(result: Any) -> dict[str, Any]:
     }
 
 
-def _scan_containers(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
+def _scan_containers(ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID) -> dict[str, Any]:
     if ctx.discovery_service is None:
         return errors.make_error(
             errors.INTERNAL_ERROR, "discovery service unavailable"
@@ -112,7 +121,7 @@ def _scan_containers(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, An
     return errors.make_ok(_scan_result_to_payload(result))
 
 
-def _list_containers(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
+def _list_containers(ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID) -> dict[str, Any]:
     if ctx.discovery_service is None:
         return errors.make_error(
             errors.INTERNAL_ERROR, "discovery service unavailable"
@@ -213,13 +222,18 @@ def _pane_row_to_dict(row: Any) -> dict[str, Any]:
     }
 
 
-def _scan_panes(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
+def _scan_panes(ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID) -> dict[str, Any]:
     if ctx.pane_service is None:
         return errors.make_error(errors.INTERNAL_ERROR, "pane service unavailable")
     from ..tmux.adapter import TmuxError  # local import: avoid cycles
+    container_filter = params.get("container")
+    if container_filter is not None and not isinstance(container_filter, str):
+        return errors.make_error(
+            errors.BAD_REQUEST, "params.container must be a string or null"
+        )
 
     try:
-        result = ctx.pane_service.scan()
+        result = ctx.pane_service.scan_for_container(container_id=container_filter)
     except TmuxError as exc:
         if exc.code in errors.CLOSED_CODE_SET:
             return errors.make_error(exc.code, exc.message)
@@ -229,7 +243,7 @@ def _scan_panes(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
     return errors.make_ok(_pane_scan_to_payload(result))
 
 
-def _list_panes(ctx: DaemonContext, params: dict[str, Any]) -> dict[str, Any]:
+def _list_panes(ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID) -> dict[str, Any]:
     if ctx.pane_service is None:
         return errors.make_error(errors.INTERNAL_ERROR, "pane service unavailable")
     active_only = params.get("active_only", False)
@@ -259,9 +273,124 @@ def _internal_error_message(message: str, *, prefix: str) -> str:
         return prefix
     return f"{prefix}: {bounded}"
 
+
+# ---------------------------------------------------------------------------
+# FEAT-006 — agent-registration handlers (FR-023).
+#
+# Each handler delegates to ``ctx.agent_service`` (an ``AgentService``
+# instance wired by the daemon) and maps the agent-domain
+# :class:`RegistrationError` into the FEAT-002 closed-set wire envelope.
+# Schema-newer requests are refused via SCHEMA_VERSION_NEWER without
+# touching state (FR-040, edge case line 79).
+# ---------------------------------------------------------------------------
+
+
+def _agent_service_or_error(ctx: DaemonContext) -> tuple[Any, dict[str, Any] | None]:
+    """Return ``(service, None)`` or ``(None, error_envelope)``."""
+    service = getattr(ctx, "agent_service", None)
+    if service is None:
+        return None, errors.make_error(
+            errors.INTERNAL_ERROR, "agent service unavailable"
+        )
+    return service, None
+
+
+def _dispatch_agent_method(
+    ctx: DaemonContext,
+    params: dict[str, Any],
+    peer_uid: int,
+    *,
+    method_name: str,
+    pass_uid: bool = False,
+) -> dict[str, Any]:
+    """Dispatch *method_name* on the wired ``AgentService``.
+
+    Maps :class:`RegistrationError` to the closed-set wire envelope and
+    every unexpected ``Exception`` to ``internal_error`` so the daemon
+    stays alive (FR-035).
+
+    *peer_uid* is the SO_PEERCRED-derived uid the server extracted from
+    the accepted AF_UNIX connection. It is passed out-of-band so a
+    request body cannot spoof it.
+    """
+    service, err = _agent_service_or_error(ctx)
+    if err is not None:
+        return err
+    # Lazy import keeps this module's import graph independent of the
+    # ``agents`` package (which depends on ``socket_api.errors``).
+    from ..agents.errors import RegistrationError
+
+    if not isinstance(params, dict):
+        return errors.make_error(errors.BAD_REQUEST, "params must be an object")
+
+    method = getattr(service, method_name)
+    try:
+        if pass_uid:
+            result = method(params, socket_peer_uid=int(peer_uid))
+        else:
+            result = method(params)
+    except RegistrationError as exc:
+        # Defense in depth: bound the error message length and strip
+        # control bytes even on the closed-code branch (the non-closed
+        # branch already routes through ``_internal_error_message``).
+        # A future contributor whose error message embeds raw user
+        # input shouldn't be able to leak NUL/CR/LF onto the wire.
+        bounded_message, _ = sanitize_text(exc.message, 2048) if exc.message else ("", 0)
+        if exc.code in errors.CLOSED_CODE_SET:
+            return errors.make_error(exc.code, bounded_message or exc.code)
+        return errors.make_error(
+            errors.INTERNAL_ERROR,
+            _internal_error_message(exc.message, prefix=method_name),
+        )
+    except Exception as exc:  # pragma: no cover — defensive
+        return errors.make_error(
+            errors.INTERNAL_ERROR,
+            _internal_error_message(str(exc), prefix=method_name),
+        )
+    return errors.make_ok(result)
+
+
+def _register_agent(
+    ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID
+) -> dict[str, Any]:
+    return _dispatch_agent_method(
+        ctx, params, peer_uid, method_name="register_agent", pass_uid=True
+    )
+
+
+def _list_agents(
+    ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID
+) -> dict[str, Any]:
+    return _dispatch_agent_method(ctx, params, peer_uid, method_name="list_agents")
+
+
+def _set_role(
+    ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID
+) -> dict[str, Any]:
+    return _dispatch_agent_method(
+        ctx, params, peer_uid, method_name="set_role", pass_uid=True
+    )
+
+
+def _set_label(
+    ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID
+) -> dict[str, Any]:
+    return _dispatch_agent_method(
+        ctx, params, peer_uid, method_name="set_label", pass_uid=True
+    )
+
+
+def _set_capability(
+    ctx: DaemonContext, params: dict[str, Any], peer_uid: int = _NO_PEER_UID
+) -> dict[str, Any]:
+    return _dispatch_agent_method(
+        ctx, params, peer_uid, method_name="set_capability", pass_uid=True
+    )
+
+
 # Dispatch table — the closed set of methods FEAT-002 advertises plus
-# FEAT-003's two and FEAT-004's two new entries. FEAT-002 keys retain
-# insertion order (FR-022).
+# FEAT-003's two, FEAT-004's two, and FEAT-006's five new entries.
+# FEAT-002 keys retain insertion order (FR-022).
 DISPATCH: dict[str, Handler] = {
     "ping": _ping,
     "status": _status,
@@ -270,4 +399,9 @@ def _internal_error_message(message: str, *, prefix: str) -> str:
     "list_containers": _list_containers,
     "scan_panes": _scan_panes,
     "list_panes": _list_panes,
+    "register_agent": _register_agent,
+    "list_agents": _list_agents,
+    "set_role": _set_role,
+    "set_label": _set_label,
+    "set_capability": _set_capability,
 }
diff --git a/src/agenttower/socket_api/server.py b/src/agenttower/socket_api/server.py
index 916b79d..90f22ca 100644
--- a/src/agenttower/socket_api/server.py
+++ b/src/agenttower/socket_api/server.py
@@ -11,8 +11,10 @@
 
 import json
 import os
+import socket as _socket
 import socketserver
 import stat
+import struct
 import threading
 from pathlib import Path
 from typing import Any
@@ -22,6 +24,30 @@
 
 MAX_REQUEST_BYTES = 65536  # 64 KiB; FR-029 / R-006.
 
+# Linux ucred is "{ pid_t pid; uid_t uid; gid_t gid; }" — three 32-bit ints.
+_UCRED_STRUCT = struct.Struct("iII")
+_NO_PEER_UID = -1
+
+
+def _peer_uid_from_socket(conn: _socket.socket) -> int:
+    """Return the peer's uid from ``SO_PEERCRED`` or ``-1`` on failure.
+
+    The uid is injected out-of-band into method dispatch so a request
+    body cannot spoof it. Failures (non-Linux kernel, connection torn
+    down before getsockopt, etc.) degrade to the sentinel ``-1`` —
+    audit rows then record ``-1`` rather than dropping the request.
+    """
+    try:
+        raw = conn.getsockopt(
+            _socket.SOL_SOCKET, _socket.SO_PEERCRED, _UCRED_STRUCT.size
+        )
+    except (OSError, AttributeError):
+        return _NO_PEER_UID
+    if len(raw) < _UCRED_STRUCT.size:
+        return _NO_PEER_UID
+    _pid, uid, _gid = _UCRED_STRUCT.unpack(raw)
+    return int(uid)
+
 
 # ---------------------------------------------------------------------------
 # Request handler
@@ -83,8 +109,15 @@ def _read_and_dispatch(self) -> dict[str, Any]:
         if handler is None:
             return errors.make_error(errors.UNKNOWN_METHOD, f"unknown method: {method}")
 
+        # ``self.connection`` is set by ``StreamRequestHandler.setup``; tests
+        # that synthesize a handler via ``__new__`` skip setup, so fall back
+        # to the sentinel rather than crashing dispatch on a missing attr.
+        connection = getattr(self, "connection", None)
+        peer_uid = (
+            _peer_uid_from_socket(connection) if connection is not None else _NO_PEER_UID
+        )
         try:
-            return handler(self.server.context, params)
+            return handler(self.server.context, params, peer_uid)
         except Exception as exc:  # noqa: BLE001 — never crash the daemon (FR-021).
             return errors.make_error(errors.INTERNAL_ERROR, f"{type(exc).__name__}: {exc}")
 
diff --git a/src/agenttower/state/agents.py b/src/agenttower/state/agents.py
new file mode 100644
index 0000000..25f71c9
--- /dev/null
+++ b/src/agenttower/state/agents.py
@@ -0,0 +1,433 @@
+"""Typed dataclasses + read/write helpers for the FEAT-006 ``agents`` table.
+
+Helpers accept an open ``sqlite3.Connection`` and do NOT begin or commit
+transactions on their own. The :class:`agenttower.agents.service.AgentService`
+owns the transaction boundary that wraps each ``register_agent`` /
+``set_role`` / ``set_label`` / ``set_capability`` call.
+
+This module is pure data-access: no validation, no mutex acquisition,
+no business rules. Validators live in
+:mod:`agenttower.agents.validation`; mutexes in
+:mod:`agenttower.agents.mutex`; orchestration in
+:mod:`agenttower.agents.service`.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from ..agents.mutex import PaneCompositeKey
+
+
+@dataclass(frozen=True)
+class AgentRecord:
+    """One row of the ``agents`` table, post-sanitization (data-model §4.1)."""
+
+    agent_id: str
+    container_id: str
+    tmux_socket_path: str
+    tmux_session_name: str
+    tmux_window_index: int
+    tmux_pane_index: int
+    tmux_pane_id: str
+    role: str
+    capability: str
+    label: str
+    project_path: str
+    parent_agent_id: str | None
+    effective_permissions: dict[str, Any]
+    created_at: str
+    last_registered_at: str
+    last_seen_at: str | None
+    active: bool
+
+    @property
+    def composite_key(self) -> PaneCompositeKey:
+        return (
+            self.container_id,
+            self.tmux_socket_path,
+            self.tmux_session_name,
+            self.tmux_window_index,
+            self.tmux_pane_index,
+            self.tmux_pane_id,
+        )
+
+
+_AGENT_COLUMNS = (
+    "agent_id, container_id, tmux_socket_path, tmux_session_name, "
+    "tmux_window_index, tmux_pane_index, tmux_pane_id, role, capability, "
+    "label, project_path, parent_agent_id, effective_permissions, "
+    "created_at, last_registered_at, last_seen_at, active"
+)
+
+
+def _row_to_agent(row: tuple) -> AgentRecord:
+    return AgentRecord(
+        agent_id=row[0],
+        container_id=row[1],
+        tmux_socket_path=row[2],
+        tmux_session_name=row[3],
+        tmux_window_index=int(row[4]),
+        tmux_pane_index=int(row[5]),
+        tmux_pane_id=row[6],
+        role=row[7],
+        capability=row[8],
+        label=row[9],
+        project_path=row[10],
+        parent_agent_id=row[11],
+        effective_permissions=json.loads(row[12]),
+        created_at=row[13],
+        last_registered_at=row[14],
+        last_seen_at=row[15],
+        active=bool(row[16]),
+    )
+
+
+def insert_agent(
+    conn: sqlite3.Connection,
+    *,
+    agent_id: str,
+    pane_key: PaneCompositeKey,
+    role: str,
+    capability: str,
+    label: str,
+    project_path: str,
+    parent_agent_id: str | None,
+    effective_permissions_json: str,
+    created_at: str,
+    last_registered_at: str,
+    active: bool,
+) -> None:
+    """INSERT a new ``agents`` row (callers MUST hold a transaction).
+
+    ``last_seen_at`` is set to NULL on creation per data-model §2.1 — the
+    FEAT-004 reconciliation transaction populates it on the next scan
+    that observes the bound pane (FR-009a).
+    """
+    conn.execute(
+        f"""
+        INSERT INTO agents ({_AGENT_COLUMNS})
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            agent_id,
+            pane_key[0],
+            pane_key[1],
+            pane_key[2],
+            int(pane_key[3]),
+            int(pane_key[4]),
+            pane_key[5],
+            role,
+            capability,
+            label,
+            project_path,
+            parent_agent_id,
+            effective_permissions_json,
+            created_at,
+            last_registered_at,
+            None,
+            1 if active else 0,
+        ),
+    )
+
+
+def update_agent_mutable_fields(
+    conn: sqlite3.Connection,
+    *,
+    agent_id: str,
+    role: str,
+    capability: str,
+    label: str,
+    project_path: str,
+    effective_permissions_json: str,
+    last_registered_at: str,
+    active: bool,
+) -> None:
+    """UPDATE the mutable fields on an existing ``agents`` row.
+
+    ``created_at``, ``parent_agent_id``, ``last_seen_at``, and the pane
+    composite key MUST NOT be modified here (FR-002, FR-009a). Callers
+    MUST hold a transaction.
+    """
+    conn.execute(
+        """
+        UPDATE agents SET
+            role = ?,
+            capability = ?,
+            label = ?,
+            project_path = ?,
+            effective_permissions = ?,
+            last_registered_at = ?,
+            active = ?
+        WHERE agent_id = ?
+        """,
+        (
+            role,
+            capability,
+            label,
+            project_path,
+            effective_permissions_json,
+            last_registered_at,
+            1 if active else 0,
+            agent_id,
+        ),
+    )
+
+
+def update_agent_role(
+    conn: sqlite3.Connection,
+    *,
+    agent_id: str,
+    role: str,
+    effective_permissions_json: str,
+) -> None:
+    """UPDATE only the role + recomputed effective_permissions for set_role."""
+    conn.execute(
+        "UPDATE agents SET role = ?, effective_permissions = ? WHERE agent_id = ?",
+        (role, effective_permissions_json, agent_id),
+    )
+
+
+def update_agent_label(
+    conn: sqlite3.Connection,
+    *,
+    agent_id: str,
+    label: str,
+) -> None:
+    conn.execute("UPDATE agents SET label = ? WHERE agent_id = ?", (label, agent_id))
+
+
+def update_agent_capability(
+    conn: sqlite3.Connection,
+    *,
+    agent_id: str,
+    capability: str,
+) -> None:
+    conn.execute(
+        "UPDATE agents SET capability = ? WHERE agent_id = ?",
+        (capability, agent_id),
+    )
+
+
+# Each PaneCompositeKey contributes 6 placeholders. SQLite's default
+# ``SQLITE_MAX_VARIABLE_NUMBER`` is 999 on builds older than 3.32 (and
+# 32766 on newer ones — we don't want to bet on the runtime version).
+# 100 keys × 6 = 600 placeholders leaves headroom for an additional
+# scalar in the UPDATE (``now_iso``).
+_PANE_KEY_BATCH = 100
+
+_PANE_KEY_PREDICATE = (
+    "(container_id = ? AND tmux_socket_path = ? AND tmux_session_name = ? "
+    "AND tmux_window_index = ? AND tmux_pane_index = ? AND tmux_pane_id = ?)"
+)
+
+
+def _chunk(items: list[Any], size: int) -> Iterable[list[Any]]:
+    for offset in range(0, len(items), size):
+        yield items[offset : offset + size]
+
+
+def _next_lex_prefix(prefix: str) -> str:
+    """Return the next lexicographic string after *prefix*.
+
+    Used to encode a prefix scan as an index-friendly half-open range
+    ``[prefix, _next_lex_prefix(prefix))``. The last character is bumped
+    to the next codepoint — for hex inputs this works for every digit:
+    ``'9'`` (0x39) → ``':'`` (0x3A) sorts after every hex digit, and
+    ``'f'`` (0x66) → ``'g'`` (0x67) sorts after every hex letter, so
+    no hex value lands at or above the upper bound.
+    """
+    return prefix[:-1] + chr(ord(prefix[-1]) + 1)
+
+
+def update_last_seen_at(
+    conn: sqlite3.Connection,
+    *,
+    pane_keys: Iterable[PaneCompositeKey],
+    now_iso: str,
+) -> None:
+    """UPDATE ``last_seen_at`` on every agent bound to a pane in *pane_keys*.
+
+    Used by the FEAT-004 pane reconciliation transaction (FR-009a /
+    Clarifications Q2). Caller MUST hold a transaction. *pane_keys* is
+    chunked at ``_PANE_KEY_BATCH`` per UPDATE so a large scan never
+    trips SQLite's ``SQLITE_MAX_VARIABLE_NUMBER`` ceiling at runtime.
+    """
+    keys = list(pane_keys)
+    if not keys:
+        return
+    for batch in _chunk(keys, _PANE_KEY_BATCH):
+        sql = (
+            "UPDATE agents SET last_seen_at = ? WHERE "
+            + " OR ".join([_PANE_KEY_PREDICATE] * len(batch))
+        )
+        params: list[Any] = [now_iso]
+        for key in batch:
+            params.extend(key)
+        conn.execute(sql, params)
+
+
+def cascade_agents_active_from_pane(
+    conn: sqlite3.Connection,
+    *,
+    pane_keys: Iterable[PaneCompositeKey],
+) -> None:
+    """Set ``agents.active = 0`` for every agent bound to a pane in *pane_keys*.
+
+    Used by the FEAT-004 reconciliation when a pane transitions
+    active→inactive (FR-009). Caller MUST hold a transaction. Same
+    batching strategy as :func:`update_last_seen_at`.
+    """
+    keys = list(pane_keys)
+    if not keys:
+        return
+    for batch in _chunk(keys, _PANE_KEY_BATCH):
+        sql = (
+            "UPDATE agents SET active = 0 WHERE "
+            + " OR ".join([_PANE_KEY_PREDICATE] * len(batch))
+        )
+        params: list[Any] = []
+        for key in batch:
+            params.extend(key)
+        conn.execute(sql, params)
+
+
+def select_agent_by_id(
+    conn: sqlite3.Connection, *, agent_id: str
+) -> AgentRecord | None:
+    row = conn.execute(
+        f"SELECT {_AGENT_COLUMNS} FROM agents WHERE agent_id = ?",
+        (agent_id,),
+    ).fetchone()
+    return _row_to_agent(row) if row is not None else None
+
+
+def select_agent_by_pane_key(
+    conn: sqlite3.Connection, *, pane_key: PaneCompositeKey
+) -> AgentRecord | None:
+    row = conn.execute(
+        f"SELECT {_AGENT_COLUMNS} FROM agents WHERE "
+        "container_id = ? AND tmux_socket_path = ? AND tmux_session_name = ? "
+        "AND tmux_window_index = ? AND tmux_pane_index = ? AND tmux_pane_id = ?",
+        pane_key,
+    ).fetchone()
+    return _row_to_agent(row) if row is not None else None
+
+
+def select_active_for_role_and_container(
+    conn: sqlite3.Connection,
+    *,
+    agent_id: str,
+) -> tuple[bool, bool | None] | None:
+    """Atomic re-check helper for FR-011 master-promotion.
+
+    Returns ``(agent_active, container_active)`` where *container_active*
+    is ``True`` / ``False`` based on the bound container's ``active``
+    column, or ``None`` if no container row exists. Returns ``None`` for
+    the whole tuple if the agent does not exist.
+    """
+    row = conn.execute(
+        """
+        SELECT agents.active, containers.active
+        FROM agents
+        LEFT JOIN containers ON containers.container_id = agents.container_id
+        WHERE agents.agent_id = ?
+        """,
+        (agent_id,),
+    ).fetchone()
+    if row is None:
+        return None
+    agent_active = bool(row[0])
+    container_active: bool | None = None
+    if row[1] is not None:
+        container_active = bool(row[1])
+    return (agent_active, container_active)
+
+
+def select_active_for_bound_pane(
+    conn: sqlite3.Connection,
+    *,
+    pane_key: PaneCompositeKey,
+) -> tuple[bool, bool] | None:
+    """Return ``(pane_active, container_active)`` for a FEAT-004 pane key.
+
+    Returns ``None`` when the panes row is absent. Missing containers rows
+    are treated as inactive by returning ``container_active=False``.
+    """
+    row = conn.execute(
+        """
+        SELECT panes.active, containers.active
+        FROM panes
+        LEFT JOIN containers ON containers.container_id = panes.container_id
+        WHERE panes.container_id = ?
+          AND panes.tmux_socket_path = ?
+          AND panes.tmux_session_name = ?
+          AND panes.tmux_window_index = ?
+          AND panes.tmux_pane_index = ?
+          AND panes.tmux_pane_id = ?
+        """,
+        pane_key,
+    ).fetchone()
+    if row is None:
+        return None
+    return (bool(row[0]), bool(row[1]) if row[1] is not None else False)
+
+
+# Mirror the column list of the agents_active_order index exactly so the
+# planner can satisfy the sort directly from it. SQLite's default ASC
+# sorts NULLs first, so ``parent_agent_id ASC`` already gives the
+# documented "NULLS FIRST" semantics without the redundant
+# ``(parent_agent_id IS NULL) DESC`` expression which defeats the index.
+_LIST_ORDER_BY = (
+    "ORDER BY active DESC, container_id ASC, "
+    "parent_agent_id ASC, label ASC, agent_id ASC"
+)
+
+
+def list_agents(
+    conn: sqlite3.Connection,
+    *,
+    role: list[str] | None = None,
+    container_id: str | None = None,
+    active_only: bool = False,
+    parent_agent_id: str | None = None,
+) -> list[AgentRecord]:
+    """Return rows in the FR-025 deterministic order with AND-composed filters.
+
+    *container_id* is matched as an exact id OR as a 12-char short prefix
+    (FR-026). All other filter values are matched verbatim
+    (case-sensitive per Clarifications Q2).
+    """
+    where: list[str] = []
+    params: list[Any] = []
+    if active_only:
+        where.append("active = 1")
+    if role:
+        placeholders = ",".join("?" * len(role))
+        where.append(f"role IN ({placeholders})")
+        params.extend(role)
+    if container_id is not None:
+        if len(container_id) == 64:
+            where.append("container_id = ?")
+            params.append(container_id)
+        else:
+            # 12-char short prefix match (FR-026), encoded as an
+            # index-friendly half-open range so the ``agents_active_order``
+            # index (leading column ``container_id``) stays usable as the
+            # table grows.  Wrapping the column in ``substr(...)``  defeats
+            # any index because the column expression is non-trivial; the
+            # range form is a plain ``container_id >= ? AND container_id < ?``
+            # the planner can satisfy via a single index seek.
+            where.append("container_id >= ? AND container_id < ?")
+            params.append(container_id)
+            params.append(_next_lex_prefix(container_id))
+    if parent_agent_id is not None:
+        where.append("parent_agent_id = ?")
+        params.append(parent_agent_id)
+    where_clause = "WHERE " + " AND ".join(where) if where else ""
+    sql = f"SELECT {_AGENT_COLUMNS} FROM agents {where_clause} {_LIST_ORDER_BY}"
+    return [_row_to_agent(r) for r in conn.execute(sql, params).fetchall()]
diff --git a/src/agenttower/state/schema.py b/src/agenttower/state/schema.py
index e6f322e..b67afa4 100644
--- a/src/agenttower/state/schema.py
+++ b/src/agenttower/state/schema.py
@@ -16,7 +16,7 @@
     _verify_file_mode,
 )
 
-CURRENT_SCHEMA_VERSION = 3
+CURRENT_SCHEMA_VERSION = 4
 
 _COMPANION_SUFFIXES = ("-journal", "-wal", "-shm")
 
@@ -154,9 +154,69 @@ def _apply_migration_v3(conn: sqlite3.Connection) -> None:
     )
 
 
+def _apply_migration_v4(conn: sqlite3.Connection) -> None:
+    """Create FEAT-006 ``agents`` table + indexes (data-model.md §2.1, §2.2).
+
+    Idempotent because of IF NOT EXISTS guards. Touches no FEAT-001 /
+    FEAT-002 / FEAT-003 / FEAT-004 table (FR-037).
+    """
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS agents (
+            agent_id                 TEXT NOT NULL PRIMARY KEY,
+            container_id             TEXT NOT NULL,
+            tmux_socket_path         TEXT NOT NULL,
+            tmux_session_name        TEXT NOT NULL,
+            tmux_window_index        INTEGER NOT NULL,
+            tmux_pane_index          INTEGER NOT NULL,
+            tmux_pane_id             TEXT NOT NULL,
+            role                     TEXT NOT NULL CHECK(role IN ('master','slave','swarm','test-runner','shell','unknown')),
+            capability               TEXT NOT NULL CHECK(capability IN ('claude','codex','gemini','opencode','shell','test-runner','unknown')),
+            label                    TEXT NOT NULL DEFAULT '',
+            project_path             TEXT NOT NULL DEFAULT '',
+            parent_agent_id          TEXT,
+            effective_permissions    TEXT NOT NULL,
+            created_at               TEXT NOT NULL,
+            last_registered_at       TEXT NOT NULL,
+            last_seen_at             TEXT,
+            active                   INTEGER NOT NULL CHECK(active IN (0, 1)),
+            UNIQUE (
+                container_id,
+                tmux_socket_path,
+                tmux_session_name,
+                tmux_window_index,
+                tmux_pane_index,
+                tmux_pane_id
+            )
+        )
+        """
+    )
+    conn.execute(
+        """
+        CREATE INDEX IF NOT EXISTS agents_active_order
+            ON agents(active DESC, container_id ASC, parent_agent_id ASC,
+                      label ASC, agent_id ASC)
+        """
+    )
+    conn.execute(
+        """
+        CREATE INDEX IF NOT EXISTS agents_parent_lookup
+            ON agents(parent_agent_id)
+        """
+    )
+    conn.execute(
+        """
+        CREATE INDEX IF NOT EXISTS agents_pane_lookup
+            ON agents(container_id, tmux_socket_path, tmux_session_name,
+                      tmux_window_index, tmux_pane_index, tmux_pane_id)
+        """
+    )
+
+
 _MIGRATIONS: dict[int, Callable[[sqlite3.Connection], None]] = {
     2: _apply_migration_v2,
     3: _apply_migration_v3,
+    4: _apply_migration_v4,
 }
 
 
@@ -230,11 +290,12 @@ def _ensure_current_schema(conn: sqlite3.Connection, current_version: int) -> No
             f"on-disk schema_version={current_version} is newer than this "
             f"build supports ({CURRENT_SCHEMA_VERSION}); refusing to open"
         )
-    # Existing DB at current version: ensure FEAT-003 + FEAT-004 tables
-    # exist in case the schema_version row got there ahead of the tables
-    # (defensive — every migration body uses IF NOT EXISTS).
+    # Existing DB at current version: ensure FEAT-003 + FEAT-004 + FEAT-006
+    # tables exist in case the schema_version row got there ahead of the
+    # tables (defensive — every migration body uses IF NOT EXISTS).
     _apply_migration_v2(conn)
     _apply_migration_v3(conn)
+    _apply_migration_v4(conn)
 
 
 def _chmod_new_companions(
diff --git a/tests/integration/test_cli_register_self_e2e.py b/tests/integration/test_cli_register_self_e2e.py
new file mode 100644
index 0000000..e59c628
--- /dev/null
+++ b/tests/integration/test_cli_register_self_e2e.py
@@ -0,0 +1,251 @@
+"""End-to-end integration tests for FEAT-006 ``register-self`` (T037 / SC-001).
+
+Exercises the full CLI → daemon → SQLite path with a real host daemon
+under the FEAT-002 harness, FEAT-003 / FEAT-004 / FEAT-005 fakes, and
+``$TMUX`` / ``$TMUX_PANE`` env injection. These tests cover the
+critical happy path that proves all of Phase 3 wiring works end-to-end.
+
+This is the SC-001 / SC-002 / SC-007 baseline integration test. It
+intentionally combines several spec-listed integration tests into one
+file (test_cli_register_self.py + test_cli_register_idempotent.py +
+test_cli_list_agents.py) for compactness; the per-test functions still
+map 1:1 to the spec's acceptance scenarios.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import subprocess
+from pathlib import Path
+
+from ._daemon_helpers import ensure_daemon, resolved_paths
+
+
+CONTAINER_ID = "abc123def456abc123def456abc123def456abc123def456abc123def456abc1"
+SHORT_ID = CONTAINER_ID[:12]
+SOCKET_PATH = "/tmp/tmux-1000/default"  # NOSONAR - test fixture inside fake /proc tree
+SESSION = "main"
+PANE_ID = "%17"
+
+
+def _write_docker_fake(path: Path) -> None:
+    path.write_text(
+        json.dumps(
+            {
+                "list_running": {
+                    "action": "ok",
+                    "containers": [
+                        {
+                            "container_id": CONTAINER_ID,
+                            "name": "bench-acme",
+                            "image": "img",
+                            "status": "running",
+                        }
+                    ],
+                },
+                "inspect": {
+                    "action": "ok",
+                    "results": [
+                        {
+                            "container_id": CONTAINER_ID,
+                            "name": "bench-acme",
+                            "image": "img",
+                            "status": "running",
+                            "config_user": "user",
+                            "working_dir": "/workspace",
+                        }
+                    ],
+                },
+            }
+        ),
+        encoding="utf-8",
+    )
+
+
+def _write_tmux_fake(path: Path) -> None:
+    path.write_text(
+        json.dumps(
+            {
+                "containers": {
+                    CONTAINER_ID: {
+                        "uid": "1000",
+                        "sockets": {
+                            "default": [
+                                {
+                                    "session_name": SESSION,
+                                    "window_index": 0,
+                                    "pane_index": 0,
+                                    "pane_id": PANE_ID,
+                                    "pane_pid": 12345,
+                                    "pane_tty": "/dev/pts/0",
+                                    "pane_current_command": "bash",
+                                    "pane_current_path": "/workspace",
+                                    "pane_title": "title",
+                                    "pane_active": True,
+                                }
+                            ]
+                        },
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+
+
+def _write_proc_root(root: Path) -> None:
+    """Materialize a fake /proc + /etc tree that puts FEAT-005 in-container."""
+    (root / "proc" / "self").mkdir(parents=True, exist_ok=True)
+    (root / "proc" / "1").mkdir(parents=True, exist_ok=True)
+    (root / "etc").mkdir(parents=True, exist_ok=True)
+    (root / "run").mkdir(parents=True, exist_ok=True)
+    (root / ".dockerenv").write_text("")
+    (root / "proc" / "self" / "cgroup").write_text(f"0::/docker/{CONTAINER_ID}\n")
+    (root / "proc" / "1" / "cgroup").write_text(f"0::/docker/{CONTAINER_ID}\n")
+
+
+def _setup_env(env_with_fake) -> tuple[dict, Path]:
+    """Reuse the conftest ``env_with_fake`` fixture, then layer FEAT-006 fakes."""
+    env, fake_path, home = env_with_fake
+    _write_docker_fake(fake_path)
+    tmux_fake = home.parent / "tmux-fake.json"
+    _write_tmux_fake(tmux_fake)
+    proc_root = home.parent / "proc-root"
+    _write_proc_root(proc_root)
+    env["AGENTTOWER_TEST_TMUX_FAKE"] = str(tmux_fake)
+    env["AGENTTOWER_TEST_PROC_ROOT"] = str(proc_root)
+    env["TMUX"] = f"{SOCKET_PATH},12345,$0"
+    env["TMUX_PANE"] = PANE_ID
+    env["AGENTTOWER_CONTAINER_ID"] = CONTAINER_ID
+    return env, home
+
+
+def _run_cli(env, *args, timeout: float = 10.0):
+    return subprocess.run(
+        ["agenttower", *args],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+
+
+def test_register_self_happy_path(env_with_fake) -> None:
+    """SC-001: register-self from a simulated in-container env returns 0,
+    prints the assigned agent_id, and persists exactly one new agents row."""
+    env, home = _setup_env(env_with_fake)
+    ensure_daemon(env)
+    # First scan to seed FEAT-003 + FEAT-004 tables.
+    _run_cli(env, "scan", "--containers")
+    _run_cli(env, "scan", "--panes")
+
+    proc = _run_cli(
+        env,
+        "register-self",
+        "--role", "slave",
+        "--capability", "codex",
+        "--label", "codex-01",
+        "--project", "/workspace/acme",
+        "--json",
+    )
+    assert proc.returncode == 0, f"stdout={proc.stdout!r} stderr={proc.stderr!r}"
+    payload = json.loads(proc.stdout)
+    assert payload["ok"] is True
+    result = payload["result"]
+    assert result["role"] == "slave"
+    assert result["capability"] == "codex"
+    assert result["label"] == "codex-01"
+    assert result["project_path"] == "/workspace/acme"
+    assert result["agent_id"].startswith("agt_")
+    assert result["created_or_reactivated"] == "created"
+
+    # Verify directly via SQLite.
+    paths = resolved_paths(home)
+    conn = sqlite3.connect(str(paths["state_db"]))
+    try:
+        rows = conn.execute("SELECT agent_id, role, label FROM agents").fetchall()
+    finally:
+        conn.close()
+    assert len(rows) == 1
+    assert rows[0][0] == result["agent_id"]
+    assert rows[0][1] == "slave"
+    assert rows[0][2] == "codex-01"
+
+
+def test_register_self_idempotent_returns_same_id(env_with_fake) -> None:
+    """SC-002: re-running register-self from the same pane returns the
+    same agent_id, leaves the row count at 1, and updates last_registered_at."""
+    env, home = _setup_env(env_with_fake)
+    ensure_daemon(env)
+    _run_cli(env, "scan", "--containers")
+    _run_cli(env, "scan", "--panes")
+
+    first = json.loads(
+        _run_cli(env, "register-self", "--role", "slave", "--json").stdout
+    )["result"]
+    second = json.loads(
+        _run_cli(env, "register-self", "--role", "slave", "--json").stdout
+    )["result"]
+    assert second["agent_id"] == first["agent_id"]
+    assert second["last_registered_at"] >= first["last_registered_at"]
+    assert second["created_or_reactivated"] == "updated"
+    paths = resolved_paths(home)
+    conn = sqlite3.connect(str(paths["state_db"]))
+    try:
+        count = conn.execute("SELECT COUNT(*) FROM agents").fetchone()[0]
+    finally:
+        conn.close()
+    assert count == 1
+
+
+def test_list_agents_tsv_has_required_columns(env_with_fake) -> None:
+    """SC-007 + FR-029: list-agents default form has the locked
+    nine-column TSV schema with required header row."""
+    env, _home = _setup_env(env_with_fake)
+    ensure_daemon(env)
+    _run_cli(env, "scan", "--containers")
+    _run_cli(env, "scan", "--panes")
+    _run_cli(env, "register-self", "--role", "slave", "--label", "codex-01", "--json")
+
+    proc = _run_cli(env, "list-agents")
+    assert proc.returncode == 0
+    lines = proc.stdout.strip().splitlines()
+    assert (
+        lines[0]
+        == "AGENT_ID\tLABEL\tROLE\tCAPABILITY\tCONTAINER\tPANE\tPROJECT\tPARENT\tACTIVE"
+    )
+    fields = lines[1].split("\t")
+    assert len(fields) == 9
+    assert fields[1] == "codex-01"
+    assert fields[2] == "slave"
+    assert fields[4] == SHORT_ID  # 12-char short
+    assert fields[7] == "-"        # PARENT null
+    assert fields[8] == "true"
+
+
+def test_register_self_master_rejected_e2e(env_with_fake) -> None:
+    """SC-003 / FR-010: register-self --role master rejected end-to-end.
+
+    The CLI does not expose ``--confirm`` on register-self (FR-010 makes
+    confirm-bypass unreachable by surface design); the test exercises
+    the daemon-side rejection path by passing ``--role master`` alone.
+    """
+    env, home = _setup_env(env_with_fake)
+    ensure_daemon(env)
+    _run_cli(env, "scan", "--containers")
+    _run_cli(env, "scan", "--panes")
+
+    proc = _run_cli(env, "register-self", "--role", "master", "--json")
+    assert proc.returncode != 0
+    payload = json.loads(proc.stdout)
+    assert payload["ok"] is False
+    assert payload["error"]["code"] == "master_via_register_self_rejected"
+
+    paths = resolved_paths(home)
+    conn = sqlite3.connect(str(paths["state_db"]))
+    try:
+        count = conn.execute("SELECT COUNT(*) FROM agents").fetchone()[0]
+    finally:
+        conn.close()
+    assert count == 0
diff --git a/tests/integration/test_cli_us2_us3_e2e.py b/tests/integration/test_cli_us2_us3_e2e.py
new file mode 100644
index 0000000..1b61bd6
--- /dev/null
+++ b/tests/integration/test_cli_us2_us3_e2e.py
@@ -0,0 +1,222 @@
+"""End-to-end integration tests for FEAT-006 US2 + US3 + host context.
+
+Covers:
+* SC-004: ``set-role --role master`` without ``--confirm`` rejected.
+* US2 happy path: ``set-role --role master --confirm`` promotes.
+* US2 set-role swarm rejection.
+* US3 happy path: register a swarm child under an existing slave.
+* US3 parent failure paths (parent_not_found / parent_role_invalid).
+* SC-009: host_context_unsupported when caller is on the host shell.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from ._daemon_helpers import ensure_daemon, resolved_paths
+
+# Reuse the same fixture-building helpers from the US1 e2e file.
+from .test_cli_register_self_e2e import (
+    CONTAINER_ID,
+    PANE_ID,
+    SOCKET_PATH,
+    SESSION,
+    _setup_env,
+    _write_docker_fake,
+    _write_proc_root,
+    _write_tmux_fake,
+)
+
+
+def _run_cli(env, *args, timeout: float = 10.0):
+    return subprocess.run(
+        ["agenttower", *args],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+
+
+def _seed_one_agent(env) -> str:
+    """Bring up the daemon, scan, register one slave, return the agent_id."""
+    ensure_daemon(env)
+    _run_cli(env, "scan", "--containers")
+    _run_cli(env, "scan", "--panes")
+    proc = _run_cli(env, "register-self", "--role", "slave", "--json")
+    return json.loads(proc.stdout)["result"]["agent_id"]
+
+
+def test_set_role_master_without_confirm_rejected(env_with_fake) -> None:
+    """SC-004 / FR-011: set-role --role master without --confirm rejected."""
+    env, _home = _setup_env(env_with_fake)
+    agent_id = _seed_one_agent(env)
+    proc = _run_cli(
+        env,
+        "set-role",
+        "--target", agent_id,
+        "--role", "master",
+        "--json",
+    )
+    assert proc.returncode != 0
+    payload = json.loads(proc.stdout)
+    assert payload["error"]["code"] == "master_confirm_required"
+
+
+def test_set_role_master_with_confirm_promotes(env_with_fake) -> None:
+    """US2 happy path: set-role --role master --confirm promotes the agent."""
+    env, _home = _setup_env(env_with_fake)
+    agent_id = _seed_one_agent(env)
+    proc = _run_cli(
+        env,
+        "set-role",
+        "--target", agent_id,
+        "--role", "master",
+        "--confirm",
+        "--json",
+    )
+    assert proc.returncode == 0, f"stdout={proc.stdout!r} stderr={proc.stderr!r}"
+    payload = json.loads(proc.stdout)
+    assert payload["ok"] is True
+    assert payload["result"]["new_value"] == "master"
+    assert payload["result"]["effective_permissions"]["can_send_to_roles"] == [
+        "slave",
+        "swarm",
+    ]
+
+
+def test_set_role_swarm_rejected_e2e(env_with_fake) -> None:
+    """FR-012: set-role --role swarm is rejected client-side."""
+    env, _home = _setup_env(env_with_fake)
+    agent_id = _seed_one_agent(env)
+    proc = _run_cli(
+        env,
+        "set-role",
+        "--target", agent_id,
+        "--role", "swarm",
+        "--json",
+    )
+    assert proc.returncode != 0
+    payload = json.loads(proc.stdout)
+    assert payload["error"]["code"] == "swarm_role_via_set_role_rejected"
+
+
+def test_register_self_host_context_rejected(env_with_fake) -> None:
+    """SC-009: caller on host shell (FEAT-005 reports host_context) is rejected."""
+    env, _home = _setup_env(env_with_fake)
+    # Override AGENTTOWER_TEST_PROC_ROOT to a directory that has NO
+    # container signals — runtime_detect.detect() returns HostContext.
+    env_no_container = dict(env)
+    bare_root = Path(env["HOME"]) / "bare-host"
+    bare_root.mkdir(parents=True, exist_ok=True)
+    (bare_root / "proc" / "self").mkdir(parents=True, exist_ok=True)
+    (bare_root / "etc").mkdir(parents=True, exist_ok=True)
+    (bare_root / "proc" / "self" / "cgroup").write_text("0::/\n")
+    env_no_container["AGENTTOWER_TEST_PROC_ROOT"] = str(bare_root)
+    # Also remove the override so identity detect() doesn't succeed via env.
+    env_no_container.pop("AGENTTOWER_CONTAINER_ID", None)
+
+    ensure_daemon(env_no_container)
+    proc = _run_cli(env_no_container, "register-self", "--role", "slave", "--json")
+    assert proc.returncode != 0
+    payload = json.loads(proc.stdout)
+    assert payload["error"]["code"] == "host_context_unsupported"
+
+
+def test_set_label_round_trip(env_with_fake) -> None:
+    """US2 set-label: changes label without altering role / permissions."""
+    env, _home = _setup_env(env_with_fake)
+    agent_id = _seed_one_agent(env)
+    proc = _run_cli(
+        env,
+        "set-label",
+        "--target", agent_id,
+        "--label", "renamed",
+        "--json",
+    )
+    assert proc.returncode == 0, f"stdout={proc.stdout!r} stderr={proc.stderr!r}"
+    payload = json.loads(proc.stdout)
+    assert payload["result"]["new_value"] == "renamed"
+    # list-agents shows the new label.
+    listed = _run_cli(env, "list-agents", "--json")
+    body = json.loads(listed.stdout)["result"]
+    assert body["agents"][0]["label"] == "renamed"
+    assert body["agents"][0]["role"] == "slave"
+
+
+def test_set_capability_round_trip(env_with_fake) -> None:
+    """SC-012 + review-pass-6 N19: set-capability round-trip e2e.
+
+    Symmetric with ``test_set_label_round_trip`` — proves the
+    set-capability CLI path through real socket framing works and that
+    the new value lands on the row visible via ``list-agents``.
+    """
+    env, _home = _setup_env(env_with_fake)
+    agent_id = _seed_one_agent(env)
+    proc = _run_cli(
+        env,
+        "set-capability",
+        "--target", agent_id,
+        "--capability", "claude",
+        "--json",
+    )
+    assert proc.returncode == 0, f"stdout={proc.stdout!r} stderr={proc.stderr!r}"
+    payload = json.loads(proc.stdout)
+    assert payload["result"]["new_value"] == "claude"
+    assert payload["result"]["audit_appended"] is False
+    listed = _run_cli(env, "list-agents", "--json")
+    body = json.loads(listed.stdout)["result"]
+    assert body["agents"][0]["capability"] == "claude"
+    # Role was not changed by set-capability (FR-014 only audits role).
+    assert body["agents"][0]["role"] == "slave"
+
+
+def test_set_role_swarm_text_mode_emits_code_line(env_with_fake) -> None:
+    """Review-pass-5: text-mode pre-flight errors carry both ``error:``
+    and ``code: <closed-set-token>`` on stderr (matches the established
+    CLI surface used by ``_emit_register_error`` / ``_emit_daemon_error``).
+    """
+    env, _home = _setup_env(env_with_fake)
+    agent_id = _seed_one_agent(env)
+    proc = _run_cli(env, "set-role", "--target", agent_id, "--role", "swarm")
+    assert proc.returncode == 3
+    assert "error:" in proc.stderr
+    assert "code: swarm_role_via_set_role_rejected" in proc.stderr
+    # Text mode keeps stdout free of incidental output.
+    assert proc.stdout == "", f"unexpected stdout: {proc.stdout!r}"
+
+
+def test_set_role_master_without_confirm_text_mode_emits_code_line(
+    env_with_fake,
+) -> None:
+    env, _home = _setup_env(env_with_fake)
+    agent_id = _seed_one_agent(env)
+    proc = _run_cli(env, "set-role", "--target", agent_id, "--role", "master")
+    assert proc.returncode == 3
+    assert "error:" in proc.stderr
+    assert "code: master_confirm_required" in proc.stderr
+    assert proc.stdout == "", f"unexpected stdout: {proc.stdout!r}"
+
+
+def test_set_label_rejects_malformed_target_client_side(env_with_fake) -> None:
+    """Review-pass-2: set-* validate --target locally (R-020 / contracts/cli.md).
+
+    Without the daemon ever being contacted, a malformed --target MUST
+    surface ``value_out_of_set`` and exit 3.
+    """
+    env, _home = _setup_env(env_with_fake)
+    proc = _run_cli(
+        env,
+        "set-label",
+        "--target", "not-an-agent-id",
+        "--label", "anything",
+        "--json",
+    )
+    assert proc.returncode == 3, f"stdout={proc.stdout!r} stderr={proc.stderr!r}"
+    payload = json.loads(proc.stdout)
+    assert payload["ok"] is False
+    assert payload["error"]["code"] == "value_out_of_set"
+    # --json purity: stderr is empty in JSON mode.
+    assert proc.stderr == "", f"stderr leaked in --json mode: {proc.stderr!r}"
diff --git a/tests/integration/test_feat005_no_real_container.py b/tests/integration/test_feat005_no_real_container.py
index 128eea7..18f4c9c 100644
--- a/tests/integration/test_feat005_no_real_container.py
+++ b/tests/integration/test_feat005_no_real_container.py
@@ -15,14 +15,16 @@
 
 class TestDispatchTableCardinality:
     def test_dispatch_table_method_count_unchanged(self):
-        """FR-022 forbids any new socket method. Pre-FEAT-005 the table had
-        exactly 7 entries (ping, status, shutdown, scan_containers,
-        list_containers, scan_panes, list_panes). Asserts the count and the
-        exact method names so a new entry cannot sneak in."""
+        """FEAT-005 FR-022 forbade any new socket method through FEAT-005.
+
+        FEAT-006 explicitly adds 5 methods (FR-023): ``register_agent``,
+        ``list_agents``, ``set_role``, ``set_label``, ``set_capability``.
+        This test now pins the closed FEAT-001..006 set so an accidental
+        extra method cannot sneak in beyond the spec'd surface.
+        """
         from agenttower.socket_api import methods as methods_module
 
-        # The dispatch table is `DISPATCH` per the FEAT-002 / 003 / 004 builds.
-        # We do not import a name we don't know exists — we discover it.
+        # The dispatch table is `DISPATCH` per the FEAT-002 / 003 / 004 / 006 builds.
         dispatch = getattr(methods_module, "DISPATCH", None)
         assert dispatch is not None, "expected DISPATCH dict in socket_api/methods.py"
         assert isinstance(dispatch, dict)
@@ -34,8 +36,13 @@ def test_dispatch_table_method_count_unchanged(self):
             "list_containers",
             "scan_panes",
             "list_panes",
+            "register_agent",
+            "list_agents",
+            "set_role",
+            "set_label",
+            "set_capability",
         }, f"unexpected method count: {sorted(dispatch.keys())}"
-        assert len(dispatch) == 7
+        assert len(dispatch) == 12
 
 
 # ---------------------------------------------------------------------------
diff --git a/tests/unit/_agent_test_helpers.py b/tests/unit/_agent_test_helpers.py
new file mode 100644
index 0000000..4a38f03
--- /dev/null
+++ b/tests/unit/_agent_test_helpers.py
@@ -0,0 +1,152 @@
+"""Shared helpers for FEAT-006 unit tests.
+
+Builds an :class:`AgentService` against a temporary SQLite database with
+the v4 schema applied, plus convenience helpers to seed FEAT-003
+``containers`` rows and FEAT-004 ``panes`` rows so the dynamic parent
+check / re-registration paths have realistic input. No daemon, no
+socket, no Docker, no tmux — pure in-process.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from agenttower.agents.mutex import AgentLockMap, RegisterLockMap
+from agenttower.agents.service import AgentService
+from agenttower.state.schema import open_registry
+
+
+# A 64-char hex container id and a stable pane composite key tuple per
+# data-model.md §2.1. Tests can use ``CK_DEFAULT`` directly or build new
+# tuples by altering one field.
+CONTAINER_ID = "c" * 64
+CONTAINER_NAME = "bench-test"
+TMUX_SOCKET = "/tmp/tmux-1000/default"  # NOSONAR - test fixture path
+SESSION = "main"
+
+CK_DEFAULT = (CONTAINER_ID, TMUX_SOCKET, SESSION, 0, 0, "%0")
+
+
+def make_service(tmp_path: Path, *, schema_version: int = 4) -> AgentService:
+    """Build an :class:`AgentService` against ``tmp_path/agenttower.sqlite3``."""
+    state_dir = tmp_path / "state"
+    state_dir.mkdir(mode=0o700, exist_ok=True)
+    state_db = state_dir / "agenttower.sqlite3"
+
+    # Initialize the registry (creates v4 schema).
+    conn, _ = open_registry(state_db, namespace_root=state_dir)
+    conn.close()
+
+    return AgentService(
+        connection_factory=lambda: sqlite3.connect(
+            str(state_db), isolation_level=None
+        ),
+        register_locks=RegisterLockMap(),
+        agent_locks=AgentLockMap(),
+        events_file=tmp_path / "events.jsonl",
+        schema_version=schema_version,
+    )
+
+
+def seed_container(
+    service: AgentService,
+    *,
+    container_id: str = CONTAINER_ID,
+    name: str = CONTAINER_NAME,
+    active: bool = True,
+) -> None:
+    """Insert a containers row so register_agent's pane key is joinable."""
+    conn = service.connection_factory()
+    try:
+        conn.execute(
+            "INSERT INTO containers (container_id, name, image, status, "
+            "labels_json, mounts_json, inspect_json, config_user, working_dir, "
+            "active, first_seen_at, last_scanned_at) VALUES "
+            "(?, ?, 'image', 'running', '{}', '[]', '{}', 'user', '/w', ?, "
+            "'2026-05-07T00:00:00.000000+00:00', "
+            "'2026-05-07T00:00:00.000000+00:00')",
+            (container_id, name, 1 if active else 0),
+        )
+    finally:
+        conn.close()
+
+
+def seed_pane(
+    service: AgentService,
+    *,
+    container_id: str = CONTAINER_ID,
+    container_name: str = CONTAINER_NAME,
+    tmux_socket_path: str = TMUX_SOCKET,
+    tmux_session_name: str = SESSION,
+    tmux_window_index: int = 0,
+    tmux_pane_index: int = 0,
+    tmux_pane_id: str = "%0",
+    active: bool = True,
+) -> tuple[str, str, str, int, int, str]:
+    """Insert a panes row for the given composite key. Returns the key."""
+    conn = service.connection_factory()
+    try:
+        conn.execute(
+            "INSERT INTO panes VALUES "
+            "(?, ?, ?, ?, ?, ?, ?, ?, ?, '/dev/pts/0', 'bash', '/w', 'title', "
+            "1, ?, '2026-05-07T00:00:00.000000+00:00', "
+            "'2026-05-07T00:00:00.000000+00:00')",
+            (
+                container_id,
+                tmux_socket_path,
+                tmux_session_name,
+                tmux_window_index,
+                tmux_pane_index,
+                tmux_pane_id,
+                container_name,
+                "user",
+                12345,
+                1 if active else 0,
+            ),
+        )
+    finally:
+        conn.close()
+    return (
+        container_id,
+        tmux_socket_path,
+        tmux_session_name,
+        tmux_window_index,
+        tmux_pane_index,
+        tmux_pane_id,
+    )
+
+
+def register_params(
+    composite_key: tuple = CK_DEFAULT,
+    **overrides: Any,
+) -> dict[str, Any]:
+    """Build a register_agent params dict. Caller passes only supplied fields."""
+    out: dict[str, Any] = {
+        "container_id": composite_key[0],
+        "pane_composite_key": {
+            "container_id": composite_key[0],
+            "tmux_socket_path": composite_key[1],
+            "tmux_session_name": composite_key[2],
+            "tmux_window_index": composite_key[3],
+            "tmux_pane_index": composite_key[4],
+            "tmux_pane_id": composite_key[5],
+        },
+    }
+    out.update(overrides)
+    return out
+
+
+def read_events(service: AgentService) -> list[dict[str, Any]]:
+    """Read every JSONL row appended to the events file (for audit assertions)."""
+    import json as _json
+
+    events_file = service.events_file
+    if events_file is None or not Path(events_file).exists():
+        return []
+    out = []
+    for line in Path(events_file).read_text().splitlines():
+        if line.strip():
+            out.append(_json.loads(line))
+    return out
diff --git a/tests/unit/test_agent_id_generation.py b/tests/unit/test_agent_id_generation.py
new file mode 100644
index 0000000..da1e3d7
--- /dev/null
+++ b/tests/unit/test_agent_id_generation.py
@@ -0,0 +1,76 @@
+"""Unit tests for FEAT-006 agent_id generation and shape validation (T012 / FR-001).
+
+Covers:
+
+* ``generate_agent_id`` returns ``agt_<12-hex>`` strings (16 chars).
+* ``validate_agent_id_shape`` accepts valid forms.
+* ``validate_agent_id_shape`` rejects mixed-case (``AGT_abc...``,
+  ``agt_ABC...``) without normalization (Clarifications session
+  2026-05-07-continued Q2).
+* The collision-retry contract is exercised at the service layer
+  (``test_register_idempotency.py``); this file pins only the ID-shape
+  contract.
+"""
+
+from __future__ import annotations
+
+import re
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+from agenttower.agents.identifiers import (
+    AGENT_ID_RE,
+    generate_agent_id,
+    validate_agent_id_shape,
+)
+
+
+def test_generate_agent_id_shape() -> None:
+    for _ in range(200):
+        agent_id = generate_agent_id()
+        assert len(agent_id) == 16
+        assert AGENT_ID_RE.match(agent_id)
+        assert agent_id.startswith("agt_")
+        assert re.fullmatch(r"[0-9a-f]{12}", agent_id[4:])
+
+
+def test_generate_agent_id_uniqueness_in_bulk() -> None:
+    """48 bits of entropy makes accidental dup vanishingly unlikely at MVP scale.
+
+    Birthday-bound first expected collision is at ~2^24 ≈ 16M unique
+    ids; 2,000 draws stay well clear of any plausible collision.
+    """
+    ids = {generate_agent_id() for _ in range(2_000)}
+    assert len(ids) == 2_000
+
+
+def test_validate_agent_id_shape_accepts_canonical() -> None:
+    assert validate_agent_id_shape("agt_abc123def456") == "agt_abc123def456"
+    assert validate_agent_id_shape("agt_000000000000") == "agt_000000000000"
+    assert validate_agent_id_shape("agt_ffffffffffff") == "agt_ffffffffffff"
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [
+        "AGT_abc123def456",       # mixed-case prefix
+        "agt_ABC123DEF456",       # mixed-case hex
+        "agt_abc123def4567",      # too long
+        "agt_abc123def45",        # too short
+        "agt_abc123def4XY",       # non-hex chars
+        "agtabc123def456",        # missing underscore
+        "abc123def456",           # missing prefix
+        "",                       # empty
+    ],
+)
+def test_validate_agent_id_shape_rejects(bad: str) -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_agent_id_shape(bad)
+    assert info.value.code == "value_out_of_set"
+
+
+def test_validate_agent_id_shape_rejects_non_string() -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_agent_id_shape(12345)  # type: ignore[arg-type]
+    assert info.value.code == "value_out_of_set"
diff --git a/tests/unit/test_audit_confirm_provided_literal.py b/tests/unit/test_audit_confirm_provided_literal.py
new file mode 100644
index 0000000..abe4ac1
--- /dev/null
+++ b/tests/unit/test_audit_confirm_provided_literal.py
@@ -0,0 +1,91 @@
+"""Unit tests for FEAT-006 ``confirm_provided`` literal contract (T066 / Q5).
+
+Clarifications session 2026-05-07-continued Q5: ``confirm_provided``
+records the literal request value verbatim, never rewritten based on
+whether ``--confirm`` was *required* by the transition.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._agent_test_helpers import (
+    make_service,
+    read_events,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_demotion_with_redundant_confirm_logs_true(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    service.set_role(
+        {"agent_id": first["agent_id"], "role": "master", "confirm": True},
+        socket_peer_uid=1000,
+    )
+    # Demote with REDUNDANT --confirm (not required by FR-013).
+    service.set_role(
+        {"agent_id": first["agent_id"], "role": "slave", "confirm": True},
+        socket_peer_uid=1000,
+    )
+    rows = read_events(service)
+    # creation, master, demotion → 3 rows.
+    assert len(rows) == 3
+    assert rows[2]["payload"]["confirm_provided"] is True
+
+
+def test_set_role_to_non_master_with_redundant_confirm_logs_true(
+    tmp_path: Path,
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    service.set_role(
+        {"agent_id": first["agent_id"], "role": "shell", "confirm": True},
+        socket_peer_uid=1000,
+    )
+    rows = read_events(service)
+    assert rows[-1]["payload"]["confirm_provided"] is True
+
+
+def test_register_self_creation_logs_false(tmp_path: Path) -> None:
+    """register-self never has a meaningful --confirm; always logs False."""
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    rows = read_events(service)
+    assert rows[0]["payload"]["confirm_provided"] is False
+
+
+def test_set_role_demotion_without_confirm_logs_false(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    service.set_role(
+        {"agent_id": first["agent_id"], "role": "master", "confirm": True},
+        socket_peer_uid=1000,
+    )
+    # Demote WITHOUT --confirm (not required).
+    service.set_role(
+        {"agent_id": first["agent_id"], "role": "slave"},
+        socket_peer_uid=1000,
+    )
+    rows = read_events(service)
+    assert rows[-1]["payload"]["confirm_provided"] is False
+    assert rows[-1]["payload"]["prior_role"] == "master"
+    assert rows[-1]["payload"]["new_role"] == "slave"
diff --git a/tests/unit/test_audit_record_shape.py b/tests/unit/test_audit_record_shape.py
new file mode 100644
index 0000000..571ad08
--- /dev/null
+++ b/tests/unit/test_audit_record_shape.py
@@ -0,0 +1,86 @@
+"""Unit tests for FEAT-006 JSONL audit-row shape (T064 / FR-014).
+
+Covers:
+* Exactly one row per successful role transition.
+* Required fields: ``ts`` (microsecond UTC), ``type``, ``payload`` containing
+  ``agent_id``, ``prior_role``, ``new_role``, ``confirm_provided``,
+  ``socket_peer_uid``.
+* Failed transitions append no row.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    make_service,
+    read_events,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_single_audit_row_per_transition(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    rows = read_events(service)
+    assert len(rows) == 1
+    payload = rows[0]["payload"]
+    assert rows[0]["type"] == "agent_role_change"
+    assert payload["prior_role"] is None
+    assert payload["new_role"] == "slave"
+    assert payload["confirm_provided"] is False
+    assert payload["socket_peer_uid"] == 1000
+    # ts is a UTC-aware ISO-8601 string. Use ``fromisoformat`` rather
+    # than a strict regex so the contract survives an offset-spelling
+    # change (e.g. ``Z`` vs ``+00:00``) without a false-positive
+    # regression.
+    parsed_ts = _dt.datetime.fromisoformat(rows[0]["ts"])
+    assert parsed_ts.tzinfo is not None
+    assert parsed_ts.utcoffset() == _dt.timedelta(0)
+
+
+def test_failed_transition_appends_no_row(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    pre = len(read_events(service))
+    with pytest.raises(RegistrationError):
+        service.set_role(
+            {"agent_id": first["agent_id"], "role": "master"},  # missing confirm
+            socket_peer_uid=1000,
+        )
+    assert len(read_events(service)) == pre
+
+
+def test_set_role_appends_audit_row(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    service.set_role(
+        {"agent_id": first["agent_id"], "role": "master", "confirm": True},
+        socket_peer_uid=1000,
+    )
+    rows = read_events(service)
+    # Two: creation + role change.
+    assert len(rows) == 2
+    payload = rows[1]["payload"]
+    assert payload["prior_role"] == "slave"
+    assert payload["new_role"] == "master"
+    assert payload["confirm_provided"] is True
diff --git a/tests/unit/test_client_resolve.py b/tests/unit/test_client_resolve.py
new file mode 100644
index 0000000..e457c26
--- /dev/null
+++ b/tests/unit/test_client_resolve.py
@@ -0,0 +1,353 @@
+"""Unit tests for FEAT-006 client_resolve (review-pass-6 N9 + N10).
+
+The ``client_resolve`` module owns five closed-set error codes —
+``host_context_unsupported``, ``container_unresolved``, ``not_in_tmux``,
+``tmux_pane_malformed``, ``pane_unknown_to_daemon`` — plus the FR-041
+focused-rescan budget (exactly one ``scan_panes`` call scoped to the
+resolved container, no cascade). Before this file the module had zero
+direct unit coverage; only ``host_context_unsupported`` was exercised
+e2e. These tests parameterize each branch with monkeypatched
+``send_request`` / ``runtime_detect`` / ``cd_identity`` / ``tmux_identity``
+so a real socket and daemon are not required.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from agenttower.agents import client_resolve
+from agenttower.agents.errors import RegistrationError
+from agenttower.config_doctor import identity as cd_identity
+from agenttower.config_doctor import runtime_detect, tmux_identity
+
+
+SOCKET_PATH = Path("/tmp/test-daemon.sock")  # NOSONAR — not opened in unit tests
+CONTAINER_ID = "a" * 64
+SHORT_ID = CONTAINER_ID[:12]
+
+
+def _container_dict(container_id: str = CONTAINER_ID, name: str = "bench-x") -> dict:
+    return {"id": container_id, "name": name}
+
+
+def _pane_dict(
+    *,
+    pane_id: str = "%17",
+    session: str = "main",
+    window: int = 0,
+    index: int = 0,
+    socket: str = "/tmp/tmux-1000/default",
+    active: bool = True,
+) -> dict:
+    return {
+        "container_id": CONTAINER_ID,
+        "tmux_socket_path": socket,
+        "tmux_session_name": session,
+        "tmux_window_index": window,
+        "tmux_pane_index": index,
+        "tmux_pane_id": pane_id,
+        "active": active,
+    }
+
+
+def _patch_runtime_in_container(monkeypatch) -> None:
+    monkeypatch.setattr(
+        runtime_detect,
+        "detect",
+        lambda proc_root=None: runtime_detect.ContainerContext(detection_signals=("dockerenv",)),
+    )
+
+
+def _patch_runtime_host(monkeypatch) -> None:
+    monkeypatch.setattr(
+        runtime_detect, "detect", lambda proc_root=None: runtime_detect.HostContext()
+    )
+
+
+def _patch_identity(monkeypatch, candidate_value: str = CONTAINER_ID) -> None:
+    monkeypatch.setattr(
+        cd_identity,
+        "detect_candidate",
+        lambda env, proc_root=None: cd_identity.IdentityCandidate(
+            candidate=candidate_value, signal="env"
+        ),
+    )
+
+
+def _patch_tmux(
+    monkeypatch,
+    *,
+    in_tmux: bool = True,
+    socket_path: str | None = "/tmp/tmux-1000/default",
+    pane_id: str | None = "%17",
+    pane_id_valid: bool = True,
+    malformed_reason: str | None = None,
+) -> None:
+    monkeypatch.setattr(
+        tmux_identity,
+        "parse_tmux_env",
+        lambda env: tmux_identity.ParsedTmuxEnv(
+            in_tmux=in_tmux,
+            tmux_socket_path=socket_path,
+            server_pid="12345" if in_tmux else None,
+            session_id="$0" if in_tmux else None,
+            tmux_pane_id=pane_id,
+            pane_id_valid=pane_id_valid,
+            malformed_reason=malformed_reason,
+        ),
+    )
+
+
+def _patch_send_request(monkeypatch, responses: dict[str, Any]) -> list[dict]:
+    """Wire ``send_request`` to a sequence of canned responses keyed by method.
+
+    Returns the call-log list — tests can assert call ordering / count
+    after the function returns.
+    """
+    calls: list[dict] = []
+
+    def fake_send(socket_path, method, params, **kwargs):
+        calls.append({"method": method, "params": dict(params)})
+        if isinstance(responses.get(method), list):
+            # Pop the next pre-staged response for this method.
+            return responses[method].pop(0)
+        return responses.get(method, {})
+
+    monkeypatch.setattr(client_resolve, "send_request", fake_send)
+    return calls
+
+
+# ---------------------------------------------------------------------------
+# host_context_unsupported (FEAT-005-style runtime detection)
+# ---------------------------------------------------------------------------
+
+
+def test_host_context_unsupported(monkeypatch) -> None:
+    _patch_runtime_host(monkeypatch)
+    with pytest.raises(RegistrationError) as info:
+        client_resolve.resolve_pane_composite_key(
+            socket_path=SOCKET_PATH, env={}, proc_root=None
+        )
+    assert info.value.code == "host_context_unsupported"
+
+
+# ---------------------------------------------------------------------------
+# container_unresolved — three sub-paths
+# ---------------------------------------------------------------------------
+
+
+def test_container_unresolved_no_candidate(monkeypatch) -> None:
+    _patch_runtime_in_container(monkeypatch)
+    monkeypatch.setattr(
+        cd_identity, "detect_candidate", lambda env, proc_root=None: None
+    )
+    with pytest.raises(RegistrationError) as info:
+        client_resolve.resolve_pane_composite_key(
+            socket_path=SOCKET_PATH, env={}, proc_root=None
+        )
+    assert info.value.code == "container_unresolved"
+
+
+def test_container_unresolved_multi_candidate(monkeypatch) -> None:
+    _patch_runtime_in_container(monkeypatch)
+    monkeypatch.setattr(
+        cd_identity,
+        "detect_candidate",
+        lambda env, proc_root=None: cd_identity.CgroupMultiCandidate(
+            candidates=("a" * 64, "b" * 64)
+        ),
+    )
+    with pytest.raises(RegistrationError) as info:
+        client_resolve.resolve_pane_composite_key(
+            socket_path=SOCKET_PATH, env={}, proc_root=None
+        )
+    assert info.value.code == "container_unresolved"
+
+
+def test_container_unresolved_no_match(monkeypatch) -> None:
+    """Identity resolves but the candidate does not appear in list_containers."""
+    _patch_runtime_in_container(monkeypatch)
+    _patch_identity(monkeypatch, candidate_value=CONTAINER_ID)
+    _patch_send_request(monkeypatch, {"list_containers": {"containers": []}})
+    with pytest.raises(RegistrationError) as info:
+        client_resolve.resolve_pane_composite_key(
+            socket_path=SOCKET_PATH, env={}, proc_root=None
+        )
+    assert info.value.code == "container_unresolved"
+
+
+def test_container_unresolved_multi_match(monkeypatch) -> None:
+    """Two distinct containers match the candidate name."""
+    _patch_runtime_in_container(monkeypatch)
+    _patch_identity(monkeypatch, candidate_value="bench-x")
+    _patch_send_request(
+        monkeypatch,
+        {
+            "list_containers": {
+                "containers": [
+                    _container_dict("a" * 64, "bench-x"),
+                    _container_dict("b" * 64, "bench-x"),
+                ]
+            }
+        },
+    )
+    with pytest.raises(RegistrationError) as info:
+        client_resolve.resolve_pane_composite_key(
+            socket_path=SOCKET_PATH, env={}, proc_root=None
+        )
+    assert info.value.code == "container_unresolved"
+    assert "matched 2" in info.value.message
+
+
+# ---------------------------------------------------------------------------
+# not_in_tmux / tmux_pane_malformed
+# ---------------------------------------------------------------------------
+
+
+def test_not_in_tmux(monkeypatch) -> None:
+    _patch_runtime_in_container(monkeypatch)
+    _patch_identity(monkeypatch)
+    _patch_send_request(
+        monkeypatch, {"list_containers": {"containers": [_container_dict()]}}
+    )
+    _patch_tmux(monkeypatch, in_tmux=False)
+    with pytest.raises(RegistrationError) as info:
+        client_resolve.resolve_pane_composite_key(
+            socket_path=SOCKET_PATH, env={}, proc_root=None
+        )
+    assert info.value.code == "not_in_tmux"
+
+
+def test_tmux_pane_malformed(monkeypatch) -> None:
+    _patch_runtime_in_container(monkeypatch)
+    _patch_identity(monkeypatch)
+    _patch_send_request(
+        monkeypatch, {"list_containers": {"containers": [_container_dict()]}}
+    )
+    _patch_tmux(
+        monkeypatch,
+        in_tmux=True,
+        malformed_reason="$TMUX has only 2 segments",
+    )
+    with pytest.raises(RegistrationError) as info:
+        client_resolve.resolve_pane_composite_key(
+            socket_path=SOCKET_PATH, env={}, proc_root=None
+        )
+    assert info.value.code == "tmux_pane_malformed"
+
+
+# ---------------------------------------------------------------------------
+# pane_unknown_to_daemon — including the FR-041 focused-rescan budget
+# ---------------------------------------------------------------------------
+
+
+def test_pane_unknown_to_daemon_after_focused_rescan(monkeypatch) -> None:
+    """FR-041 / SC-008 (review-pass-6 N9): exactly one focused rescan.
+
+    The first list_panes returns no match. The resolver then issues
+    EXACTLY ONE ``scan_panes`` request scoped to the resolved
+    container. The second list_panes still returns no match → resolver
+    refuses with ``pane_unknown_to_daemon``. A regression that cascaded
+    the rescan to all containers, or skipped scoping, would be
+    visible in the captured call log.
+    """
+    _patch_runtime_in_container(monkeypatch)
+    _patch_identity(monkeypatch)
+    _patch_tmux(monkeypatch)
+    calls = _patch_send_request(
+        monkeypatch,
+        {
+            "list_containers": {"containers": [_container_dict()]},
+            "list_panes": [{"panes": []}, {"panes": []}],  # both empty
+            "scan_panes": {"status": "ok"},
+        },
+    )
+    with pytest.raises(RegistrationError) as info:
+        client_resolve.resolve_pane_composite_key(
+            socket_path=SOCKET_PATH, env={}, proc_root=None
+        )
+    assert info.value.code == "pane_unknown_to_daemon"
+
+    methods = [c["method"] for c in calls]
+    assert methods.count("scan_panes") == 1, "exactly one focused rescan"
+    scan_call = next(c for c in calls if c["method"] == "scan_panes")
+    assert scan_call["params"] == {"container": CONTAINER_ID}, (
+        "rescan must be scoped to the resolved container"
+    )
+    # And the resolver MUST issue list_panes twice (before + after rescan).
+    assert methods.count("list_panes") == 2
+
+
+def test_focused_rescan_recovers_pane_after_first_miss(monkeypatch) -> None:
+    """If the rescan publishes the pane, the second list_panes finds it
+    and the resolver returns the pane key successfully — exercising the
+    happy-path side of the FR-041 budget."""
+    _patch_runtime_in_container(monkeypatch)
+    _patch_identity(monkeypatch)
+    _patch_tmux(monkeypatch)
+    calls = _patch_send_request(
+        monkeypatch,
+        {
+            "list_containers": {"containers": [_container_dict()]},
+            "list_panes": [
+                {"panes": []},  # first miss
+                {"panes": [_pane_dict()]},  # second succeeds after rescan
+            ],
+            "scan_panes": {"status": "ok"},
+        },
+    )
+    target = client_resolve.resolve_pane_composite_key(
+        socket_path=SOCKET_PATH, env={}, proc_root=None
+    )
+    assert target.container_id == CONTAINER_ID
+    assert target.pane_key == (CONTAINER_ID, "/tmp/tmux-1000/default", "main", 0, 0, "%17")
+    assert [c["method"] for c in calls].count("scan_panes") == 1
+
+
+def test_inactive_pane_triggers_focused_rescan(monkeypatch) -> None:
+    """A pane row present but ``active=false`` is treated as a miss for
+    FR-041 purposes — same focused rescan path."""
+    _patch_runtime_in_container(monkeypatch)
+    _patch_identity(monkeypatch)
+    _patch_tmux(monkeypatch)
+    calls = _patch_send_request(
+        monkeypatch,
+        {
+            "list_containers": {"containers": [_container_dict()]},
+            "list_panes": [
+                {"panes": [_pane_dict(active=False)]},  # inactive → treat as miss
+                {"panes": [_pane_dict(active=True)]},
+            ],
+            "scan_panes": {"status": "ok"},
+        },
+    )
+    target = client_resolve.resolve_pane_composite_key(
+        socket_path=SOCKET_PATH, env={}, proc_root=None
+    )
+    assert target.pane_key[5] == "%17"
+    assert [c["method"] for c in calls].count("scan_panes") == 1
+
+
+def test_happy_path_no_rescan(monkeypatch) -> None:
+    """When the pane is already in the FEAT-004 registry, no focused
+    rescan fires — the FR-041 budget is preserved at zero, not one."""
+    _patch_runtime_in_container(monkeypatch)
+    _patch_identity(monkeypatch)
+    _patch_tmux(monkeypatch)
+    calls = _patch_send_request(
+        monkeypatch,
+        {
+            "list_containers": {"containers": [_container_dict()]},
+            "list_panes": {"panes": [_pane_dict()]},
+            "scan_panes": {"status": "ok"},  # never reached
+        },
+    )
+    target = client_resolve.resolve_pane_composite_key(
+        socket_path=SOCKET_PATH, env={}, proc_root=None
+    )
+    assert target.container_id == CONTAINER_ID
+    methods = [c["method"] for c in calls]
+    assert "scan_panes" not in methods, "no rescan when pane is already known"
diff --git a/tests/unit/test_dispatch_table_stability.py b/tests/unit/test_dispatch_table_stability.py
new file mode 100644
index 0000000..13a466c
--- /dev/null
+++ b/tests/unit/test_dispatch_table_stability.py
@@ -0,0 +1,41 @@
+"""Snapshot test for FEAT-006 socket DISPATCH stability (T091 / FR-022 / FR-023).
+
+The dispatch table's KEY ORDER is part of the FEAT-002 stability rule
+(insertion order preserved across feature versions). FEAT-001..005
+established the first seven entries; FEAT-006 appends five more. This
+test pins the exact ordered key list so an accidental re-ordering or
+added entry is caught immediately.
+"""
+
+from __future__ import annotations
+
+from agenttower.socket_api.methods import DISPATCH
+
+
+# Ordered list (NOT a set) — the dict's insertion order MUST match this.
+EXPECTED_ORDER = [
+    # FEAT-002.
+    "ping",
+    "status",
+    "shutdown",
+    # FEAT-003.
+    "scan_containers",
+    "list_containers",
+    # FEAT-004.
+    "scan_panes",
+    "list_panes",
+    # FEAT-006.
+    "register_agent",
+    "list_agents",
+    "set_role",
+    "set_label",
+    "set_capability",
+]
+
+
+def test_dispatch_table_key_order_is_locked() -> None:
+    assert list(DISPATCH.keys()) == EXPECTED_ORDER
+
+
+def test_dispatch_table_is_exactly_twelve_entries() -> None:
+    assert len(DISPATCH) == 12
diff --git a/tests/unit/test_effective_permissions.py b/tests/unit/test_effective_permissions.py
new file mode 100644
index 0000000..59b1e09
--- /dev/null
+++ b/tests/unit/test_effective_permissions.py
@@ -0,0 +1,74 @@
+"""Unit tests for FEAT-006 effective_permissions derivation (T015 / FR-021).
+
+Covers:
+* All six roles produce the closed-set table from data-model.md §4.3.
+* JSON column key ordering is locked as
+  ``[can_send, can_receive, can_send_to_roles]`` (research R-008).
+* ``can_send_to_roles`` is always a list (incl. empty ``[]``).
+* The function does not return an aliased mutable view of an internal table
+  (callers can't mutate the source of truth).
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from agenttower.agents.permissions import (
+    effective_permissions,
+    serialize_effective_permissions,
+)
+
+
+_EXPECTED = {
+    "master":      {"can_send": True,  "can_receive": False, "can_send_to_roles": ["slave", "swarm"]},
+    "slave":       {"can_send": False, "can_receive": True,  "can_send_to_roles": []},
+    "swarm":       {"can_send": False, "can_receive": True,  "can_send_to_roles": []},
+    "test-runner": {"can_send": False, "can_receive": False, "can_send_to_roles": []},
+    "shell":       {"can_send": False, "can_receive": False, "can_send_to_roles": []},
+    "unknown":     {"can_send": False, "can_receive": False, "can_send_to_roles": []},
+}
+
+
+@pytest.mark.parametrize("role,expected", list(_EXPECTED.items()))
+def test_effective_permissions_table(role: str, expected: dict) -> None:
+    assert effective_permissions(role) == expected
+
+
+def test_effective_permissions_can_send_to_roles_is_list() -> None:
+    for role in _EXPECTED:
+        perms = effective_permissions(role)
+        assert isinstance(perms["can_send_to_roles"], list)
+
+
+def test_serialize_key_ordering_is_stable() -> None:
+    """The JSON serialization MUST emit keys in
+    [can_send, can_receive, can_send_to_roles] order (research R-008)."""
+    text = serialize_effective_permissions("master")
+    # Locate first occurrence of each key.
+    can_send_pos = text.index('"can_send"')
+    can_receive_pos = text.index('"can_receive"')
+    can_send_to_pos = text.index('"can_send_to_roles"')
+    assert can_send_pos < can_receive_pos < can_send_to_pos
+
+
+def test_serialize_round_trip() -> None:
+    for role, expected in _EXPECTED.items():
+        text = serialize_effective_permissions(role)
+        assert json.loads(text) == expected
+
+
+def test_callers_cannot_mutate_internal_table() -> None:
+    """Mutating the returned dict MUST NOT affect later calls."""
+    perms = effective_permissions("master")
+    perms["can_send_to_roles"].append("master")
+    second = effective_permissions("master")
+    assert second["can_send_to_roles"] == ["slave", "swarm"]
+
+
+def test_unknown_role_raises_key_error() -> None:
+    """Validators are responsible for rejecting unknown roles before this
+    helper is called; raising KeyError documents the contract."""
+    with pytest.raises(KeyError):
+        effective_permissions("admin")
diff --git a/tests/unit/test_initial_audit_record.py b/tests/unit/test_initial_audit_record.py
new file mode 100644
index 0000000..8f6bc81
--- /dev/null
+++ b/tests/unit/test_initial_audit_record.py
@@ -0,0 +1,78 @@
+"""Unit tests for FEAT-006 initial-creation audit row (T065 / Clarifications Q4).
+
+Covers:
+* First successful ``register-self`` for a pane appends one audit row
+  with ``prior_role: null`` (JSON literal), regardless of role —
+  including default ``--role unknown``.
+* Idempotent re-registration with unchanged role appends NO new row
+  (FR-027).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from ._agent_test_helpers import (
+    make_service,
+    read_events,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+@pytest.mark.parametrize(
+    "role",
+    # ``master`` is intentionally excluded — FR-010 forbids master
+    # via register-self, so the parametrize cannot exercise the
+    # creation-audit path for that role. The set-role test suite
+    # covers the master promotion audit row separately.
+    ["slave", "swarm", "test-runner", "shell", "unknown"],
+)
+def test_initial_register_writes_audit_row_with_prior_role_null(
+    tmp_path: Path, role: str
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    if role == "swarm":
+        # Swarm needs a parent slave first.
+        seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+        parent = service.register_agent(
+            register_params(role="slave"), socket_peer_uid=1000
+        )
+        ck1 = ("c" * 64, "/tmp/tmux-1000/default", "main", 0, 1, "%1")
+        service.register_agent(
+            register_params(ck1, role="swarm", parent_agent_id=parent["agent_id"]),
+            socket_peer_uid=1000,
+        )
+        rows = read_events(service)
+        # parent registration + swarm registration → two rows.
+        assert len(rows) == 2
+        assert rows[0]["payload"]["prior_role"] is None
+        assert rows[1]["payload"]["prior_role"] is None
+        assert rows[1]["payload"]["new_role"] == "swarm"
+    else:
+        params = register_params() if role == "unknown" else register_params(role=role)
+        service.register_agent(params, socket_peer_uid=1000)
+        rows = read_events(service)
+        assert len(rows) == 1
+        assert rows[0]["payload"]["prior_role"] is None
+        assert rows[0]["payload"]["new_role"] == role
+
+
+def test_idempotent_unchanged_role_writes_no_new_row(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    pre = len(read_events(service))
+    # Re-register with the same role — no new audit row (FR-027).
+    service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    assert len(read_events(service)) == pre
diff --git a/tests/unit/test_label_project_sanitize.py b/tests/unit/test_label_project_sanitize.py
new file mode 100644
index 0000000..29509f6
--- /dev/null
+++ b/tests/unit/test_label_project_sanitize.py
@@ -0,0 +1,101 @@
+"""Unit tests for FEAT-006 label / project_path sanitization + bounds (T014).
+
+Covers FR-033 / FR-034:
+* NUL byte stripping.
+* C0 control byte stripping.
+* ``label`` ≤ 64 chars (over-bound raises ``field_too_long``, NEVER truncated).
+* ``project_path`` ≤ 4096 chars; empty / relative / ``..`` / NUL all rejected
+  with ``project_path_invalid``.
+* Multi-byte UTF-8 boundary preserved by inheritance from
+  :func:`agenttower.tmux.parsers.sanitize_text`.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+from agenttower.agents.validation import (
+    LABEL_MAX,
+    PROJECT_PATH_MAX,
+    validate_label,
+    validate_project_path,
+)
+
+
+def test_label_strips_nul_and_c0() -> None:
+    assert validate_label("ok\x00\x01\x02") == "ok"
+    # \t and \n are normalized to single spaces (FEAT-004 sanitize convention).
+    assert validate_label("a\tb\nc") == "a b c"
+
+
+def test_label_at_bound() -> None:
+    s = "x" * LABEL_MAX
+    assert validate_label(s) == s
+
+
+def test_label_over_bound_rejected_not_truncated() -> None:
+    s = "x" * (LABEL_MAX + 1)
+    with pytest.raises(RegistrationError) as info:
+        validate_label(s)
+    assert info.value.code == "field_too_long"
+
+
+def test_label_preserves_multibyte_utf8() -> None:
+    s = "ホエール🐳"
+    assert validate_label(s) == s
+
+
+def test_label_rejects_non_string() -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_label(12345)  # type: ignore[arg-type]
+    assert info.value.code == "value_out_of_set"
+
+
+# ------------------------- project_path -------------------------- #
+
+
+def test_project_path_canonical_absolute_accepted() -> None:
+    assert validate_project_path("/workspace/acme") == "/workspace/acme"
+    assert validate_project_path("/") == "/"
+
+
+def test_project_path_empty_rejected() -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_project_path("")
+    assert info.value.code == "project_path_invalid"
+
+
+def test_project_path_relative_rejected() -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_project_path("workspace/acme")
+    assert info.value.code == "project_path_invalid"
+
+
+def test_project_path_dotdot_segment_rejected() -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_project_path("/a/../b")
+    assert info.value.code == "project_path_invalid"
+
+
+def test_project_path_nul_byte_rejected() -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_project_path("/a\x00b")
+    assert info.value.code == "project_path_invalid"
+
+
+def test_project_path_oversized_rejected() -> None:
+    s = "/" + "x" * PROJECT_PATH_MAX
+    with pytest.raises(RegistrationError) as info:
+        validate_project_path(s)
+    assert info.value.code == "field_too_long"
+
+
+def test_project_path_at_bound_accepted() -> None:
+    s = "/" + "x" * (PROJECT_PATH_MAX - 1)
+    assert validate_project_path(s) == s
+    assert len(s) == PROJECT_PATH_MAX
+
+
+def test_project_path_control_bytes_are_sanitized() -> None:
+    assert validate_project_path("/workspace/\tacme\n\r") == "/workspace/acme"
diff --git a/tests/unit/test_list_agents_filters.py b/tests/unit/test_list_agents_filters.py
new file mode 100644
index 0000000..b8b0907
--- /dev/null
+++ b/tests/unit/test_list_agents_filters.py
@@ -0,0 +1,192 @@
+"""Unit tests for FEAT-006 list_agents filters (T029 / FR-026).
+
+Covers:
+* ``role`` accepts a string OR a list of strings; AND-composes with other filters.
+* ``container_id`` accepts full or 12-char short prefix.
+* ``active_only`` filters inactive rows.
+* ``parent_agent_id`` filters swarm children of a given slave.
+* Unknown filter keys raise ``unknown_filter``.
+* Mixed-case filter values raise ``value_out_of_set`` (case-sensitive).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    CK_DEFAULT,
+    CONTAINER_ID,
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def _seed_two_agents(service) -> tuple[str, str]:
+    seed_container(service)
+    # Pane 0 (slave) and pane 1 (slave) in the same container.
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+    a = service.register_agent(
+        register_params(
+            CK_DEFAULT,
+            role="slave",
+            capability="codex",
+            label="alpha",
+        ),
+        socket_peer_uid=1000,
+    )
+    ck1 = (CK_DEFAULT[0], CK_DEFAULT[1], CK_DEFAULT[2], 0, 1, "%1")
+    b = service.register_agent(
+        register_params(ck1, role="slave", capability="claude", label="beta"),
+        socket_peer_uid=1000,
+    )
+    return a["agent_id"], b["agent_id"]
+
+
+def test_role_accepts_single_string(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_agents(service)
+    result = service.list_agents({"role": "slave"})
+    assert {a["label"] for a in result["agents"]} == {"alpha", "beta"}
+
+
+def test_role_accepts_list(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_agents(service)
+    result = service.list_agents({"role": ["slave", "shell"]})
+    assert len(result["agents"]) == 2
+
+
+def test_role_rejects_mixed_case(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_agents(service)
+    with pytest.raises(RegistrationError) as info:
+        service.list_agents({"role": "Slave"})
+    assert info.value.code == "value_out_of_set"
+
+
+def test_container_id_short_prefix_matches(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_agents(service)
+    short = CONTAINER_ID[:12]
+    result = service.list_agents({"container_id": short})
+    assert len(result["agents"]) == 2
+
+
+def test_container_id_full_id_matches(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_agents(service)
+    result = service.list_agents({"container_id": CONTAINER_ID})
+    assert len(result["agents"]) == 2
+
+
+def test_list_agents_json_field_set_lock(tmp_path: Path) -> None:
+    """SC-007 + review-pass-6 N20: list-agents must surface every field
+    FR-002 (identity), FR-003 (state), and FR-021 (effective_permissions
+    derivation) call out, plus the four contract-required JOIN fields
+    (container_name, container_user, pane_pid, cwd).
+
+    Locks the wire-shape so a future schema/marshal drift cannot drop a
+    documented field.
+    """
+    service = make_service(tmp_path)
+    _seed_two_agents(service)
+    rows = service.list_agents({})["agents"]
+    assert rows, "expected at least one agent"
+    expected = {
+        # Identity (FR-002 + composite pane key)
+        "agent_id",
+        "container_id",
+        "container_name",
+        "container_user",
+        "tmux_socket_path",
+        "tmux_session_name",
+        "tmux_window_index",
+        "tmux_pane_index",
+        "tmux_pane_id",
+        "pane_pid",
+        "cwd",
+        # State (FR-003)
+        "role",
+        "capability",
+        "label",
+        "project_path",
+        "parent_agent_id",
+        "created_at",
+        "last_registered_at",
+        "last_seen_at",
+        "active",
+        # FR-021 derived view
+        "effective_permissions",
+    }
+    actual = set(rows[0].keys())
+    missing = expected - actual
+    assert not missing, f"list-agents row is missing fields: {sorted(missing)}"
+
+
+def test_container_id_in_between_length_rejected(tmp_path: Path) -> None:
+    """FR-026 review-pass-2: only the 12-char short or 64-char full id
+    is accepted. Lengths in between would otherwise sneak through to the
+    daemon's substr() prefix matcher and silently behave as undocumented
+    arbitrary-length prefix filters.
+    """
+    service = make_service(tmp_path)
+    _seed_two_agents(service)
+    # 13..63 chars MUST be rejected with value_out_of_set.
+    for length in (13, 32, 50, 63):
+        with pytest.raises(RegistrationError) as info:
+            service.list_agents({"container_id": CONTAINER_ID[:length]})
+        assert info.value.code == "value_out_of_set", (
+            f"length={length} should be rejected, got {info.value.code}"
+        )
+
+
+def test_active_only_filters_inactive(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    a, b = _seed_two_agents(service)
+    conn = service.connection_factory()
+    try:
+        conn.execute("UPDATE agents SET active = 0 WHERE agent_id = ?", (a,))
+    finally:
+        conn.close()
+    result = service.list_agents({"active_only": True})
+    assert len(result["agents"]) == 1
+    assert result["agents"][0]["agent_id"] == b
+
+
+def test_unknown_filter_rejected(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    with pytest.raises(RegistrationError) as info:
+        service.list_agents({"hostname": "anything"})
+    assert info.value.code == "unknown_filter"
+
+
+def test_active_only_must_be_bool(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    with pytest.raises(RegistrationError) as info:
+        service.list_agents({"active_only": "true"})
+    assert info.value.code == "value_out_of_set"
+
+
+def test_filters_compose_with_and_semantics(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_agents(service)
+    # role=slave AND container_id=<short> AND active_only=true
+    result = service.list_agents(
+        {
+            "role": "slave",
+            "container_id": CONTAINER_ID[:12],
+            "active_only": True,
+        }
+    )
+    assert len(result["agents"]) == 2
+    # Echo the filter back per data-model.md §6.4.
+    assert result["filter"]["role"] == ["slave"]
+    assert result["filter"]["container_id"] == CONTAINER_ID[:12]
+    assert result["filter"]["active_only"] is True
diff --git a/tests/unit/test_list_agents_ordering.py b/tests/unit/test_list_agents_ordering.py
new file mode 100644
index 0000000..b90d8b9
--- /dev/null
+++ b/tests/unit/test_list_agents_ordering.py
@@ -0,0 +1,60 @@
+"""Unit tests for FEAT-006 list_agents deterministic ordering (T030 / FR-025).
+
+Order is ``active DESC, container_id ASC, parent_agent_id NULLS FIRST,
+label ASC, agent_id ASC``. Asserted by inserting rows in a SCRAMBLED
+order and confirming the deterministic sort.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._agent_test_helpers import (
+    CK_DEFAULT,
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_active_desc_then_container_then_label(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service, container_id="a" * 64, name="bench-a")
+    seed_container(service, container_id="b" * 64, name="bench-b")
+    seed_pane(service, container_id="a" * 64, container_name="bench-a", tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, container_id="b" * 64, container_name="bench-b", tmux_pane_index=1, tmux_pane_id="%1")
+    seed_pane(service, container_id="b" * 64, container_name="bench-b", tmux_pane_index=2, tmux_pane_id="%2")
+
+    a = service.register_agent(
+        register_params(
+            ("a" * 64, CK_DEFAULT[1], "main", 0, 0, "%0"),
+            role="slave", label="zlabel",
+        ),
+        socket_peer_uid=1000,
+    )
+    b = service.register_agent(
+        register_params(
+            ("b" * 64, CK_DEFAULT[1], "main", 0, 1, "%1"),
+            role="slave", label="alpha",
+        ),
+        socket_peer_uid=1000,
+    )
+    c = service.register_agent(
+        register_params(
+            ("b" * 64, CK_DEFAULT[1], "main", 0, 2, "%2"),
+            role="slave", label="beta",
+        ),
+        socket_peer_uid=1000,
+    )
+
+    # Mark agent c inactive so we can assert active DESC.
+    conn = service.connection_factory()
+    try:
+        conn.execute("UPDATE agents SET active = 0 WHERE agent_id = ?", (c["agent_id"],))
+    finally:
+        conn.close()
+
+    rows = service.list_agents({})["agents"]
+    # Expected order: a (active, container=a..., zlabel), b (active, container=b..., alpha), c (inactive)
+    assert [r["agent_id"] for r in rows] == [a["agent_id"], b["agent_id"], c["agent_id"]]
diff --git a/tests/unit/test_list_agents_tsv_render.py b/tests/unit/test_list_agents_tsv_render.py
new file mode 100644
index 0000000..923a92d
--- /dev/null
+++ b/tests/unit/test_list_agents_tsv_render.py
@@ -0,0 +1,157 @@
+"""Unit tests for FEAT-006 list-agents locked TSV render (T031 / FR-029).
+
+Tests the CLI handler ``_list_agents_command`` directly with a fake
+``send_request`` so we don't need a daemon. Asserts the locked
+nine-column header row and per-field rendering rules.
+
+Future-field exclusion: even if the daemon adds a field to the JSON
+response, the default TSV form MUST keep exactly the nine documented
+columns. Snapshot test pins this.
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+from contextlib import redirect_stdout
+from pathlib import Path
+from typing import Any
+
+from agenttower import cli
+
+
+def _stub_send_request(
+    monkeypatch, *, agents: list[dict[str, Any]]
+) -> None:
+    def fake_send(socket_path, method, params=None, **_kw):
+        return {"agents": agents, "filter": {}}
+
+    monkeypatch.setattr(cli, "send_request", fake_send)
+    monkeypatch.setattr(
+        cli,
+        "_resolve_socket_with_paths",
+        lambda env=None: (None, type("S", (), {"path": Path("/tmp/sock")})()),
+    )
+
+
+def _args(json: bool = False) -> argparse.Namespace:
+    return argparse.Namespace(
+        role=None, container=None, active_only=False, parent=None, json=json
+    )
+
+
+def test_header_row_and_column_order(monkeypatch) -> None:
+    agents = [
+        {
+            "agent_id": "agt_abc123def456",
+            "label": "codex-01",
+            "role": "slave",
+            "capability": "codex",
+            "container_id": "abc123def456abc123def456abc123def456abc123def456abc123def456abc1",
+            "tmux_session_name": "main",
+            "tmux_window_index": 0,
+            "tmux_pane_index": 0,
+            "project_path": "/workspace/acme",
+            "parent_agent_id": None,
+            "active": True,
+        }
+    ]
+    _stub_send_request(monkeypatch, agents=agents)
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        rc = cli._list_agents_command(_args())
+    assert rc == 0
+    out = buf.getvalue()
+    lines = out.splitlines()
+    assert (
+        lines[0]
+        == "AGENT_ID\tLABEL\tROLE\tCAPABILITY\tCONTAINER\tPANE\tPROJECT\tPARENT\tACTIVE"
+    )
+    fields = lines[1].split("\t")
+    # Exactly nine columns; order locked.
+    assert len(fields) == 9
+    assert fields[0] == "agt_abc123def456"
+    assert fields[1] == "codex-01"
+    assert fields[2] == "slave"
+    assert fields[3] == "codex"
+    # CONTAINER renders as bare 12-char short id.
+    assert fields[4] == "abc123def456"
+    # PANE renders session:window.pane.
+    assert fields[5] == "main:0.0"
+    assert fields[6] == "/workspace/acme"
+    # PARENT renders '-' when null.
+    assert fields[7] == "-"
+    assert fields[8] == "true"
+
+
+def test_parent_renders_full_form_when_non_null(monkeypatch) -> None:
+    agents = [
+        {
+            "agent_id": "agt_xxxxxxxxxxxx",
+            "label": "child",
+            "role": "swarm",
+            "capability": "claude",
+            "container_id": "f" * 64,
+            "tmux_session_name": "main",
+            "tmux_window_index": 0,
+            "tmux_pane_index": 1,
+            "project_path": "",
+            "parent_agent_id": "agt_aaaaaaaaaaaa",
+            "active": True,
+        }
+    ]
+    _stub_send_request(monkeypatch, agents=agents)
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        cli._list_agents_command(_args())
+    parent_field = buf.getvalue().splitlines()[1].split("\t")[7]
+    assert parent_field == "agt_aaaaaaaaaaaa"
+
+
+def test_inactive_renders_false(monkeypatch) -> None:
+    agents = [
+        {
+            "agent_id": "agt_aaaaaaaaaaaa",
+            "label": "x",
+            "role": "slave",
+            "capability": "codex",
+            "container_id": "a" * 64,
+            "tmux_session_name": "main",
+            "tmux_window_index": 0,
+            "tmux_pane_index": 0,
+            "project_path": "",
+            "parent_agent_id": None,
+            "active": False,
+        }
+    ]
+    _stub_send_request(monkeypatch, agents=agents)
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        cli._list_agents_command(_args())
+    last = buf.getvalue().splitlines()[1].split("\t")[8]
+    assert last == "false"
+
+
+def test_embedded_tab_in_label_replaced_with_space(monkeypatch) -> None:
+    agents = [
+        {
+            "agent_id": "agt_aaaaaaaaaaaa",
+            "label": "lab\tel",
+            "role": "slave",
+            "capability": "codex",
+            "container_id": "a" * 64,
+            "tmux_session_name": "main",
+            "tmux_window_index": 0,
+            "tmux_pane_index": 0,
+            "project_path": "",
+            "parent_agent_id": None,
+            "active": True,
+        }
+    ]
+    _stub_send_request(monkeypatch, agents=agents)
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        cli._list_agents_command(_args())
+    line = buf.getvalue().splitlines()[1]
+    # Exactly nine fields after sanitization (no extra split).
+    assert len(line.split("\t")) == 9
diff --git a/tests/unit/test_master_promotion_atomic_recheck.py b/tests/unit/test_master_promotion_atomic_recheck.py
new file mode 100644
index 0000000..6601730
--- /dev/null
+++ b/tests/unit/test_master_promotion_atomic_recheck.py
@@ -0,0 +1,98 @@
+"""Unit tests for FR-011 atomic master re-check (T063 / Clarifications Q3).
+
+Covers the master-promotion atomic re-check inside BEGIN IMMEDIATE: if
+the target agent OR its bound container becomes inactive between the
+client request and the transaction commit, the daemon ROLLBACKs and
+returns ``agent_inactive``. No role mutation, no
+``effective_permissions`` recomputation, no JSONL audit row.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    make_service,
+    read_events,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_inactive_agent_rejects_promotion(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # Force agent inactive (simulates FEAT-004 cascade).
+    conn = service.connection_factory()
+    try:
+        conn.execute(
+            "UPDATE agents SET active = 0 WHERE agent_id = ?",
+            (first["agent_id"],),
+        )
+    finally:
+        conn.close()
+
+    pre_audit_count = len(read_events(service))
+    with pytest.raises(RegistrationError) as info:
+        service.set_role(
+            {"agent_id": first["agent_id"], "role": "master", "confirm": True},
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "agent_inactive"
+
+    # Role unchanged; no audit row appended.
+    conn = service.connection_factory()
+    try:
+        role = conn.execute(
+            "SELECT role FROM agents WHERE agent_id = ?", (first["agent_id"],)
+        ).fetchone()[0]
+    finally:
+        conn.close()
+    assert role == "slave"
+    assert len(read_events(service)) == pre_audit_count
+
+
+def test_inactive_container_rejects_promotion(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # Mark the container inactive (simulates FEAT-003 reconciliation).
+    conn = service.connection_factory()
+    try:
+        conn.execute(
+            "UPDATE containers SET active = 0 WHERE container_id = ?",
+            (first["container_id"],),
+        )
+    finally:
+        conn.close()
+
+    pre_audit_count = len(read_events(service))
+    with pytest.raises(RegistrationError) as info:
+        service.set_role(
+            {"agent_id": first["agent_id"], "role": "master", "confirm": True},
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "agent_inactive"
+
+    conn = service.connection_factory()
+    try:
+        role = conn.execute(
+            "SELECT role FROM agents WHERE agent_id = ?", (first["agent_id"],)
+        ).fetchone()[0]
+    finally:
+        conn.close()
+    assert role == "slave"
+    assert len(read_events(service)) == pre_audit_count
diff --git a/tests/unit/test_master_promotion_safety.py b/tests/unit/test_master_promotion_safety.py
new file mode 100644
index 0000000..7db33ce
--- /dev/null
+++ b/tests/unit/test_master_promotion_safety.py
@@ -0,0 +1,138 @@
+"""Unit tests for FEAT-006 master safety boundary (T062 / FR-010 / FR-011 / FR-012 / FR-013).
+
+Covers the four pillars of the master safety contract:
+* ``register-self --role master`` rejected regardless of ``--confirm``.
+* ``set-role --role master`` without ``--confirm`` rejected.
+* ``set-role --role swarm`` rejected (swarm is register-only).
+* Demotion (master → slave / shell / unknown / etc.) does NOT require ``--confirm``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_register_self_rejects_master_no_confirm(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="master"), socket_peer_uid=1000
+        )
+    assert info.value.code == "master_via_register_self_rejected"
+
+
+def test_register_self_rejects_confirm_field_via_wire(tmp_path: Path) -> None:
+    """FR-010 + review-pass-6: ``confirm`` is not an accepted register_agent key.
+
+    The master safety boundary at register-self is unconditional, so the
+    audit contract requires ``confirm_provided=false`` for every
+    register_agent transition (data-model §4.4). Allowing the wire field
+    would let a client spoof the audit value, so the unknown-keys gate
+    refuses ``confirm`` outright before the master-role check even runs.
+    Both layers must protect FR-010: try ``confirm=True`` → ``bad_request``,
+    and try ``role=master`` alone → ``master_via_register_self_rejected``
+    (the test below).
+    """
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="master", confirm=True), socket_peer_uid=1000
+        )
+    assert info.value.code == "bad_request"
+    assert "confirm" in info.value.message
+
+
+def test_set_role_master_without_confirm_rejected(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    with pytest.raises(RegistrationError) as info:
+        service.set_role(
+            {"agent_id": first["agent_id"], "role": "master"},
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "master_confirm_required"
+
+
+def test_set_role_master_with_confirm_succeeds(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    result = service.set_role(
+        {"agent_id": first["agent_id"], "role": "master", "confirm": True},
+        socket_peer_uid=1000,
+    )
+    assert result["new_value"] == "master"
+    assert result["effective_permissions"]["can_send_to_roles"] == ["slave", "swarm"]
+    assert result["audit_appended"] is True
+
+
+def test_set_role_master_with_non_boolean_confirm_rejected(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    with pytest.raises(RegistrationError) as info:
+        service.set_role(
+            {"agent_id": first["agent_id"], "role": "master", "confirm": "false"},
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "bad_request"
+
+
+def test_set_role_swarm_rejected(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    with pytest.raises(RegistrationError) as info:
+        service.set_role(
+            {"agent_id": first["agent_id"], "role": "swarm"},
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "swarm_role_via_set_role_rejected"
+
+
+def test_demotion_from_master_does_not_require_confirm(tmp_path: Path) -> None:
+    """FR-013: master → any other role does NOT need --confirm."""
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    service.set_role(
+        {"agent_id": first["agent_id"], "role": "master", "confirm": True},
+        socket_peer_uid=1000,
+    )
+    result = service.set_role(
+        {"agent_id": first["agent_id"], "role": "slave"},
+        socket_peer_uid=1000,
+    )
+    assert result["prior_value"] == "master"
+    assert result["new_value"] == "slave"
diff --git a/tests/unit/test_pane_reconcile_last_seen.py b/tests/unit/test_pane_reconcile_last_seen.py
new file mode 100644
index 0000000..3d917c1
--- /dev/null
+++ b/tests/unit/test_pane_reconcile_last_seen.py
@@ -0,0 +1,284 @@
+"""Unit tests for FEAT-006 last_seen_at + active cascade (T032 / FR-009 / FR-009a).
+
+Covers:
+* Every FEAT-004 reconciliation transaction observing pane active=true
+  updates ``agents.last_seen_at`` in the same transaction.
+* Pane active 1→0 cascades ``agents.active = 0`` in the same transaction.
+* Pane inactive→active does NOT auto-flip ``agents.active``.
+* CLI calls (register_agent / list_agents / set_*) MUST NOT touch
+  ``last_seen_at`` (asserted by snapshot before/after the call).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from agenttower.state import agents as state_agents
+from agenttower.state import panes as state_panes
+from agenttower.state.panes import (
+    PaneReconcileWriteSet,
+    PaneUpsert,
+)
+
+from ._agent_test_helpers import (
+    CK_DEFAULT,
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def _read_last_seen_at(service, agent_id: str) -> str | None:
+    conn = service.connection_factory()
+    try:
+        row = conn.execute(
+            "SELECT last_seen_at FROM agents WHERE agent_id = ?",
+            (agent_id,),
+        ).fetchone()
+    finally:
+        conn.close()
+    return row[0] if row else None
+
+
+def test_update_last_seen_at_helper_updates_only_matching(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    result = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    aid = result["agent_id"]
+    assert _read_last_seen_at(service, aid) is None
+
+    # Simulate a FEAT-004 reconciliation transaction.
+    conn = service.connection_factory()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        state_agents.update_last_seen_at(
+            conn,
+            pane_keys=[CK_DEFAULT],
+            now_iso="2026-05-07T12:00:00.000000+00:00",
+        )
+        conn.execute("COMMIT")
+    finally:
+        conn.close()
+    assert _read_last_seen_at(service, aid) == "2026-05-07T12:00:00.000000+00:00"
+
+
+def test_cascade_agents_active_from_pane(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    result = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    aid = result["agent_id"]
+
+    conn = service.connection_factory()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        state_agents.cascade_agents_active_from_pane(
+            conn, pane_keys=[CK_DEFAULT]
+        )
+        conn.execute("COMMIT")
+    finally:
+        conn.close()
+
+    conn = service.connection_factory()
+    try:
+        active = conn.execute(
+            "SELECT active FROM agents WHERE agent_id = ?", (aid,)
+        ).fetchone()[0]
+    finally:
+        conn.close()
+    assert active == 0
+
+
+def test_register_does_not_touch_last_seen_at(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # Simulate a scan that set last_seen_at.
+    conn = service.connection_factory()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        state_agents.update_last_seen_at(
+            conn,
+            pane_keys=[CK_DEFAULT],
+            now_iso="2026-05-07T12:00:00.000000+00:00",
+        )
+        conn.execute("COMMIT")
+    finally:
+        conn.close()
+
+    # Now re-register; last_seen_at MUST NOT be modified by register_agent.
+    service.register_agent(
+        register_params(role="slave", label="new"), socket_peer_uid=1000
+    )
+    assert _read_last_seen_at(service, first["agent_id"]) == (
+        "2026-05-07T12:00:00.000000+00:00"
+    )
+
+
+def test_set_label_does_not_touch_last_seen_at(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave", label="orig"), socket_peer_uid=1000
+    )
+    conn = service.connection_factory()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        state_agents.update_last_seen_at(
+            conn,
+            pane_keys=[CK_DEFAULT],
+            now_iso="2026-05-07T12:00:00.000000+00:00",
+        )
+        conn.execute("COMMIT")
+    finally:
+        conn.close()
+
+    service.set_label(
+        {"agent_id": first["agent_id"], "label": "new"},
+        socket_peer_uid=1000,
+    )
+    assert _read_last_seen_at(service, first["agent_id"]) == (
+        "2026-05-07T12:00:00.000000+00:00"
+    )
+
+
+def test_update_last_seen_at_chunks_above_sqlite_param_limit(tmp_path: Path) -> None:
+    """Review-pass-3: large scans must not hit SQLITE_MAX_VARIABLE_NUMBER.
+
+    Each pane composite key contributes 6 bound parameters, plus one
+    for ``now_iso``. SQLite's default limit is 999 on older builds, so
+    a single UPDATE could only handle ~166 keys. Drive a count well
+    above the chunk size to prove the helper batches statements rather
+    than emitting one giant UPDATE that would fail at runtime.
+    """
+    from agenttower.state.agents import _PANE_KEY_BATCH
+
+    service = make_service(tmp_path)
+    seed_container(service)
+
+    # Build many pane keys — they don't have to match real seeded panes
+    # for the UPDATE itself to run; we're proving the SQL emits cleanly.
+    bench_keys = [
+        (
+            CK_DEFAULT[0],
+            CK_DEFAULT[1],
+            CK_DEFAULT[2],
+            window // 32,
+            window % 32,
+            f"%{window}",
+        )
+        for window in range(_PANE_KEY_BATCH * 2 + 25)
+    ]
+
+    conn = service.connection_factory()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        # If we ever regress to a single UPDATE, this raises
+        # ``sqlite3.OperationalError: too many SQL variables`` on a
+        # default SQLite build.
+        state_agents.update_last_seen_at(
+            conn,
+            pane_keys=bench_keys,
+            now_iso="2026-05-07T12:00:00.000000+00:00",
+        )
+        state_agents.cascade_agents_active_from_pane(
+            conn,
+            pane_keys=bench_keys,
+        )
+        conn.execute("COMMIT")
+    finally:
+        conn.close()
+
+
+def test_reconcile_updates_last_seen_for_every_observed_pane(tmp_path: Path) -> None:
+    """Review-pass-2: agents bound to non-tmux-focused panes still get
+    ``last_seen_at`` bumped on reconciliation.
+
+    Regression for the FR-009a finding that the reconciler filtered on
+    ``upsert.pane_active`` (the tmux *focus* flag — only one pane per
+    window has it set), so agents bound to inactive-but-alive panes
+    looked stale even though their panes were observed.
+    """
+    from agenttower.discovery.pane_service import PaneDiscoveryService
+    from agenttower.state.panes import PaneReconcileWriteSet, PaneUpsert
+
+    service = make_service(tmp_path)
+    seed_container(service)
+    # Two panes in the same window: one focused, one not.
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+    a = service.register_agent(
+        register_params(role="slave", label="focused"), socket_peer_uid=1000
+    )
+    ck1 = (CK_DEFAULT[0], CK_DEFAULT[1], CK_DEFAULT[2], 0, 1, "%1")
+    b = service.register_agent(
+        register_params(ck1, role="slave", label="unfocused"),
+        socket_peer_uid=1000,
+    )
+
+    def _upsert(pane_index: int, pane_id: str, *, is_focused: bool) -> PaneUpsert:
+        return PaneUpsert(
+            container_id=CK_DEFAULT[0],
+            tmux_socket_path=CK_DEFAULT[1],
+            tmux_session_name=CK_DEFAULT[2],
+            tmux_window_index=0,
+            tmux_pane_index=pane_index,
+            tmux_pane_id=pane_id,
+            container_name="bench-test",
+            container_user="user",
+            pane_pid=12345,
+            pane_tty="/dev/pts/0",
+            pane_current_command="bash",
+            pane_current_path="/w",
+            pane_title="title",
+            pane_active=is_focused,
+            last_scanned_at="2026-05-07T12:00:00.000000+00:00",
+        )
+
+    write_set = PaneReconcileWriteSet(
+        upserts=[
+            _upsert(0, "%0", is_focused=True),
+            _upsert(1, "%1", is_focused=False),
+        ],
+        panes_seen=2,
+    )
+
+    # Drive the same private commit path the reconciler uses.
+    conn = service.connection_factory()
+    try:
+        pds = PaneDiscoveryService.__new__(PaneDiscoveryService)
+        pds._conn = conn
+        pds._events_file = service.events_file
+        pds._commit_scan(
+            scan_id="test-scan-001",
+            started_at="2026-05-07T12:00:00.000000+00:00",
+            status="ok",
+            write_set=write_set,
+            containers_scanned=1,
+            sockets_scanned=1,
+            error_code=None,
+            error_message=None,
+            error_details=[],
+        )
+    finally:
+        conn.close()
+
+    assert (
+        _read_last_seen_at(service, a["agent_id"])
+        == "2026-05-07T12:00:00.000000+00:00"
+    )
+    assert (
+        _read_last_seen_at(service, b["agent_id"])
+        == "2026-05-07T12:00:00.000000+00:00"
+    ), "non-focused pane's agent must still bump last_seen_at"
diff --git a/tests/unit/test_parent_immutable.py b/tests/unit/test_parent_immutable.py
new file mode 100644
index 0000000..7e2e7ff
--- /dev/null
+++ b/tests/unit/test_parent_immutable.py
@@ -0,0 +1,179 @@
+"""Unit tests for FEAT-006 parent_immutable (T083 / FR-018a / Clarifications Q3).
+
+Re-registration with the same ``--parent`` value is a no-op success.
+Re-registration with a *different* ``--parent`` value (including
+NULL ↔ non-NULL) is rejected with ``parent_immutable``; on rejection
+no mutable field is updated even if other fields were also supplied,
+the transaction is rolled back, and no audit row is appended.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    CK_DEFAULT,
+    CONTAINER_ID,
+    make_service,
+    read_events,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def _ck1() -> tuple:
+    return (CONTAINER_ID, "/tmp/tmux-1000/default", "main", 0, 1, "%1")
+
+
+def _ck2() -> tuple:
+    return (CONTAINER_ID, "/tmp/tmux-1000/default", "main", 0, 2, "%2")
+
+
+def test_same_parent_value_is_noop_success(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    swarm = service.register_agent(
+        register_params(_ck1(), role="swarm", parent_agent_id=parent["agent_id"]),
+        socket_peer_uid=1000,
+    )
+    second = service.register_agent(
+        register_params(
+            _ck1(),
+            role="swarm",
+            parent_agent_id=parent["agent_id"],
+            label="updated",
+        ),
+        socket_peer_uid=1000,
+    )
+    assert second["agent_id"] == swarm["agent_id"]
+    assert second["parent_agent_id"] == parent["agent_id"]
+    assert second["label"] == "updated"
+
+
+def test_different_parent_value_rejected(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+    seed_pane(service, tmux_pane_index=2, tmux_pane_id="%2")
+
+    parent_a = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    parent_b = service.register_agent(
+        register_params(_ck2(), role="slave"), socket_peer_uid=1000
+    )
+    service.register_agent(
+        register_params(_ck1(), role="swarm", parent_agent_id=parent_a["agent_id"]),
+        socket_peer_uid=1000,
+    )
+    pre_audit = len(read_events(service))
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(
+                _ck1(),
+                role="swarm",
+                parent_agent_id=parent_b["agent_id"],
+                label="should-not-stick",
+            ),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "parent_immutable"
+    # No audit row appended for the rejected call.
+    assert len(read_events(service)) == pre_audit
+    # No mutable field updated — label is whatever it was before.
+    listed = service.list_agents({})["agents"]
+    swarm_row = next(a for a in listed if a["role"] == "swarm")
+    assert swarm_row["label"] != "should-not-stick"
+
+
+def test_role_slave_with_parent_caught_by_pre_flight(tmp_path: Path) -> None:
+    """FR-016 pre-flight catches role=slave + --parent BEFORE the locked
+    section runs.  The validator order matters: with role=slave the
+    static pre-flight rejects the request before the per-pane lock is
+    even taken, so the user gets the most actionable error
+    (parent_role_mismatch — "use --role swarm") instead of
+    parent_immutable.
+    """
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # The slave at CK_DEFAULT has parent_agent_id=None.
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="slave", parent_agent_id=parent["agent_id"]),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "parent_role_mismatch"
+
+
+def test_null_to_nonnull_parent_rejected_as_parent_immutable(
+    tmp_path: Path,
+) -> None:
+    """Review-pass-6 N22: actually exercise the FR-018a parent_immutable
+    branch for a NULL→non-NULL transition.
+
+    To hit the locked-section parent_immutable check, the request must
+    pass the FR-016 pre-flight (so role MUST be swarm).  An existing
+    slave at CK_DEFAULT has ``parent_agent_id=None``; re-registering
+    that pane with role=swarm + parent=X is the path where the
+    pre-flight does not fire and the in-tx
+    ``parent_in != existing.parent_agent_id`` check triggers
+    parent_immutable.  Previously this test asserted on
+    ``parent_role_mismatch`` (the static pre-flight outcome of the
+    role=slave variant) — which passes for the wrong reason and
+    leaves the parent_immutable path completely untested.
+    """
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # The slave at CK_DEFAULT has parent_agent_id=None. Re-registering
+    # the SAME pane with role=swarm + parent=X passes FR-016 pre-flight
+    # (role IS swarm), reaches the locked section, and fails the
+    # parent_immutable check because existing.parent_agent_id is None.
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="swarm", parent_agent_id=parent["agent_id"]),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "parent_immutable"
+
+
+def test_existing_swarm_cannot_reregister_to_non_swarm_while_parent_retained(
+    tmp_path: Path,
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    service.register_agent(
+        register_params(_ck1(), role="swarm", parent_agent_id=parent["agent_id"]),
+        socket_peer_uid=1000,
+    )
+
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(register_params(_ck1(), role="slave"), socket_peer_uid=1000)
+
+    assert info.value.code == "parent_role_mismatch"
diff --git a/tests/unit/test_register_field_too_long.py b/tests/unit/test_register_field_too_long.py
new file mode 100644
index 0000000..1159531
--- /dev/null
+++ b/tests/unit/test_register_field_too_long.py
@@ -0,0 +1,45 @@
+"""Unit tests for FEAT-006 free-text bounds at register time (T033 / FR-033).
+
+Covers oversized ``label`` and ``project_path`` rejected with
+``field_too_long``; values are NEVER silently truncated.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+from agenttower.agents.validation import LABEL_MAX, PROJECT_PATH_MAX
+
+from ._agent_test_helpers import (
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_oversized_label_rejected(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(label="x" * (LABEL_MAX + 1)),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "field_too_long"
+
+
+def test_oversized_project_path_rejected(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(project_path="/" + "x" * PROJECT_PATH_MAX),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "field_too_long"
diff --git a/tests/unit/test_register_idempotency.py b/tests/unit/test_register_idempotency.py
new file mode 100644
index 0000000..f07b8b7
--- /dev/null
+++ b/tests/unit/test_register_idempotency.py
@@ -0,0 +1,157 @@
+"""Unit tests for FEAT-006 idempotent re-registration (T026 / FR-007).
+
+Covers:
+* Re-registration with the same composite key returns the same agent_id.
+* Mutable fields supplied REPLACE stored values.
+* Mutable fields not supplied LEAVE stored values unchanged.
+* ``created_at`` / ``parent_agent_id`` / pane composite key never change.
+* ``last_registered_at`` updates on every re-registration.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ._agent_test_helpers import (
+    CK_DEFAULT,
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_idempotent_returns_same_agent_id(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    first = service.register_agent(
+        register_params(role="slave", capability="codex", label="lbl"),
+        socket_peer_uid=1000,
+    )
+    # 5 ms sleep is enough margin to keep the strict ``>`` assertion
+    # below stable on fast hardware where two ISO-8601-microsecond
+    # timestamps could otherwise collide (review-pass-6 N34).
+    time.sleep(0.005)
+    second = service.register_agent(
+        register_params(role="slave", capability="codex", label="lbl"),
+        socket_peer_uid=1000,
+    )
+
+    assert first["agent_id"] == second["agent_id"]
+    assert first["created_at"] == second["created_at"]
+    # last_registered_at advances strictly.
+    assert second["last_registered_at"] > first["last_registered_at"]
+    assert first["created_or_reactivated"] == "created"
+    assert second["created_or_reactivated"] == "updated"
+
+
+def test_supplied_fields_replace_stored(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    service.register_agent(
+        register_params(role="slave", capability="codex", label="orig"),
+        socket_peer_uid=1000,
+    )
+    second = service.register_agent(
+        register_params(label="new", capability="claude"),
+        socket_peer_uid=1000,
+    )
+    assert second["label"] == "new"
+    assert second["capability"] == "claude"
+    # Role was NOT supplied this time → stored value preserved.
+    assert second["role"] == "slave"
+
+
+def test_omitted_fields_preserve_stored(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    service.register_agent(
+        register_params(role="slave", capability="codex", label="orig", project_path="/w/a"),
+        socket_peer_uid=1000,
+    )
+    # Re-register with NO mutable flags — every stored value should survive.
+    second = service.register_agent(
+        register_params(),
+        socket_peer_uid=1000,
+    )
+    assert second["role"] == "slave"
+    assert second["capability"] == "codex"
+    assert second["label"] == "orig"
+    assert second["project_path"] == "/w/a"
+
+
+def test_different_pane_creates_distinct_agent(tmp_path: Path) -> None:
+    """FR-006 / spec edge case line 88 (review-pass-6 N17).
+
+    A second register-self from a *different* composite pane key MUST
+    create a NEW agent rather than rebinding the first one. The old
+    agent stays in the table with whatever ``active`` flag FEAT-004
+    last assigned (here we force it inactive to assert both rows
+    coexist as the spec requires).
+    """
+    from ._agent_test_helpers import CONTAINER_ID
+
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+
+    first = service.register_agent(
+        register_params(role="slave", label="alpha"),
+        socket_peer_uid=1000,
+    )
+    # Force first agent inactive to exercise the "old row stays in
+    # history" half of the spec.
+    conn = service.connection_factory()
+    try:
+        conn.execute(
+            "UPDATE agents SET active = 0 WHERE agent_id = ?",
+            (first["agent_id"],),
+        )
+    finally:
+        conn.close()
+
+    ck1 = (CONTAINER_ID, CK_DEFAULT[1], CK_DEFAULT[2], 0, 1, "%1")
+    second = service.register_agent(
+        register_params(ck1, role="slave", label="beta"),
+        socket_peer_uid=1000,
+    )
+
+    assert second["agent_id"] != first["agent_id"]
+    assert second["created_or_reactivated"] == "created"
+
+    listed = service.list_agents({})["agents"]
+    ids = {a["agent_id"] for a in listed}
+    assert {first["agent_id"], second["agent_id"]} <= ids
+
+
+def test_pane_key_and_created_at_immutable(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    second = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # Composite key columns survive byte-for-byte.
+    for key in (
+        "container_id",
+        "tmux_socket_path",
+        "tmux_session_name",
+        "tmux_window_index",
+        "tmux_pane_index",
+        "tmux_pane_id",
+        "created_at",
+        "parent_agent_id",
+    ):
+        assert first[key] == second[key]
diff --git a/tests/unit/test_register_mutex.py b/tests/unit/test_register_mutex.py
new file mode 100644
index 0000000..da9489f
--- /dev/null
+++ b/tests/unit/test_register_mutex.py
@@ -0,0 +1,125 @@
+"""Unit tests for FEAT-006 mutex registries (T017 / FR-038 / FR-039).
+
+Covers:
+* Same-key acquisitions serialize.
+* Different-key acquisitions parallelize.
+* :class:`RegisterLockMap` and :class:`AgentLockMap` are independent.
+* Fetch-or-create returns the SAME ``threading.Lock`` object on repeat calls.
+* Map entries are not evicted (memory-growth contract).
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+from agenttower.agents.mutex import AgentLockMap, RegisterLockMap
+
+
+_PANE_KEY_A = ("c1", "/tmp/tmux-1000/default", "main", 0, 0, "%0")
+_PANE_KEY_B = ("c2", "/tmp/tmux-1000/default", "main", 0, 0, "%0")
+
+
+def test_register_lock_map_returns_same_lock_for_same_key() -> None:
+    m = RegisterLockMap()
+    lock_a = m.for_key(_PANE_KEY_A)
+    lock_b = m.for_key(_PANE_KEY_A)
+    assert lock_a is lock_b
+
+
+def test_register_lock_map_returns_different_locks_for_different_keys() -> None:
+    m = RegisterLockMap()
+    a = m.for_key(_PANE_KEY_A)
+    b = m.for_key(_PANE_KEY_B)
+    assert a is not b
+
+
+def test_agent_lock_map_returns_same_lock_for_same_agent_id() -> None:
+    m = AgentLockMap()
+    a = m.for_key("agt_aaaaaaaaaaaa")
+    b = m.for_key("agt_aaaaaaaaaaaa")
+    assert a is b
+
+
+def test_agent_and_register_maps_are_independent() -> None:
+    """A pane composite key MUST NOT collide with an agent_id even if they
+    share string content (they are distinct registries)."""
+    register = RegisterLockMap()
+    agent = AgentLockMap()
+    # Two registries — entirely independent; they share no state.
+    register.for_key(_PANE_KEY_A)
+    agent.for_key("agt_aaaaaaaaaaaa")
+    assert register.known_keys() == [_PANE_KEY_A]
+    assert agent.known_keys() == ["agt_aaaaaaaaaaaa"]
+
+
+def test_same_key_serializes_concurrent_callers() -> None:
+    """Two threads calling ``with lock`` against the same key MUST NOT
+    overlap. Asserts via a side-effect counter that both critical sections
+    ran serially."""
+    m = RegisterLockMap()
+    inside = []
+    barrier = threading.Barrier(2)
+
+    def worker() -> None:
+        barrier.wait()
+        with m.for_key(_PANE_KEY_A):
+            inside.append("enter")
+            time.sleep(0.05)
+            inside.append("exit")
+
+    t1 = threading.Thread(target=worker)
+    t2 = threading.Thread(target=worker)
+    t1.start()
+    t2.start()
+    t1.join()
+    t2.join()
+    # Each worker emits enter→exit; serial → ['enter','exit','enter','exit'].
+    assert inside == ["enter", "exit", "enter", "exit"]
+
+
+def test_different_keys_parallelize() -> None:
+    """Two threads against different keys MUST proceed in parallel.
+
+    Asserts by overlapping the inner ``time.sleep`` windows; if they were
+    serialized, the second thread couldn't observe the first inside its
+    critical section.
+    """
+    m = RegisterLockMap()
+    overlap = threading.Event()
+    arrived = threading.Event()
+    sleep_done = threading.Event()
+
+    def first() -> None:
+        with m.for_key(_PANE_KEY_A):
+            arrived.set()
+            # Wait until the second thread confirms it has entered its own
+            # critical section concurrently.
+            assert overlap.wait(timeout=2.0)
+            sleep_done.set()
+
+    def second() -> None:
+        assert arrived.wait(timeout=2.0)
+        with m.for_key(_PANE_KEY_B):
+            overlap.set()
+            assert sleep_done.wait(timeout=2.0)
+
+    t1 = threading.Thread(target=first)
+    t2 = threading.Thread(target=second)
+    t1.start()
+    t2.start()
+    t1.join(timeout=3.0)
+    t2.join(timeout=3.0)
+    assert not t1.is_alive() and not t2.is_alive(), "deadlock between distinct keys"
+
+
+def test_known_keys_grows_without_eviction() -> None:
+    m = RegisterLockMap()
+    keys = [
+        ("c1", "/tmp/tmux-1000/default", "main", 0, i, "%0") for i in range(20)
+    ]
+    for k in keys:
+        m.for_key(k)
+    # FR-038: no LRU at MVP scale; entries persist for the daemon process
+    # lifetime.
+    assert set(m.known_keys()) == set(keys)
diff --git a/tests/unit/test_register_project_path_invalid.py b/tests/unit/test_register_project_path_invalid.py
new file mode 100644
index 0000000..942ef46
--- /dev/null
+++ b/tests/unit/test_register_project_path_invalid.py
@@ -0,0 +1,57 @@
+"""Unit tests for FEAT-006 project_path shape validation (T034 / FR-034).
+
+Covers ``project_path`` being non-empty, absolute, NUL-free, no ``..``
+segment. Existence on the host filesystem is NOT checked.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+@pytest.mark.parametrize(
+    "bad_path",
+    [
+        "workspace/acme",   # relative
+        "/a/../b",          # contains '..' segment
+        "/a/\x00/b",        # NUL byte
+        # empty is treated as "field omitted" via cli.py; the daemon
+        # accepts empty as a sentinel meaning "no project path"; we
+        # validate only when explicitly supplied non-empty. Asserted
+        # in test_first_registration_applies_defaults.
+    ],
+)
+def test_project_path_shape_rejected(tmp_path: Path, bad_path: str) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(project_path=bad_path),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "project_path_invalid"
+
+
+def test_project_path_existence_not_checked(tmp_path: Path) -> None:
+    """The path is observed inside the container's mount namespace; the
+    host filesystem need NOT contain it (FR-034)."""
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    result = service.register_agent(
+        register_params(project_path="/path/that/does/not/exist/on/host"),
+        socket_peer_uid=1000,
+    )
+    assert result["project_path"] == "/path/that/does/not/exist/on/host"
diff --git a/tests/unit/test_register_reactivation.py b/tests/unit/test_register_reactivation.py
new file mode 100644
index 0000000..4303359
--- /dev/null
+++ b/tests/unit/test_register_reactivation.py
@@ -0,0 +1,93 @@
+"""Unit tests for FEAT-006 re-activation of inactive agents (T028 / FR-008).
+
+Covers FR-008: re-registering at a composite key whose existing agent
+is ``active=false`` re-activates it, preserving ``agent_id``,
+``created_at``, ``parent_agent_id``; the FR-007 mutable-field semantics
+still apply.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from ._agent_test_helpers import (
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def _force_inactive(service, agent_id: str) -> None:
+    conn = service.connection_factory()
+    try:
+        conn.execute("UPDATE agents SET active = 0 WHERE agent_id = ?", (agent_id,))
+    finally:
+        conn.close()
+
+
+def test_reactivation_preserves_agent_id_and_created_at(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    _force_inactive(service, first["agent_id"])
+
+    second = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+
+    assert second["agent_id"] == first["agent_id"]
+    assert second["created_at"] == first["created_at"]
+    assert second["created_or_reactivated"] == "reactivated"
+    assert second["active"] is True
+
+
+def test_reactivation_with_mutable_field_changes(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    first = service.register_agent(
+        register_params(role="slave", capability="codex", label="old"),
+        socket_peer_uid=1000,
+    )
+    _force_inactive(service, first["agent_id"])
+
+    second = service.register_agent(
+        register_params(label="new"), socket_peer_uid=1000
+    )
+    assert second["label"] == "new"
+    # Role, capability NOT supplied — stored values preserved.
+    assert second["role"] == "slave"
+    assert second["capability"] == "codex"
+    assert second["active"] is True
+
+
+def test_reactivation_of_existing_master_without_role_flag_preserves_master(
+    tmp_path: Path,
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    service.set_role(
+        {"agent_id": first["agent_id"], "role": "master", "confirm": True},
+        socket_peer_uid=1000,
+    )
+    _force_inactive(service, first["agent_id"])
+
+    second = service.register_agent(
+        register_params(label="master-revive"), socket_peer_uid=1000
+    )
+
+    assert second["agent_id"] == first["agent_id"]
+    assert second["role"] == "master"
+    assert second["label"] == "master-revive"
diff --git a/tests/unit/test_register_schema_version.py b/tests/unit/test_register_schema_version.py
new file mode 100644
index 0000000..cfb269c
--- /dev/null
+++ b/tests/unit/test_register_schema_version.py
@@ -0,0 +1,72 @@
+"""FEAT-006 schema_version forward-compat (FR-040 / edge case line 79).
+
+Locks the wire-level handshake the review-pass-1 surfaced as unreachable:
+the CLI must transmit its built-against schema version on
+``register_agent`` so the daemon can refuse with ``schema_version_newer``
+when its own schema has advanced past what the CLI knows.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_schema_version_newer_when_client_lags(tmp_path: Path) -> None:
+    """A CLI that says ``schema_version=N`` against a daemon at ``N+1`` is refused."""
+    service = make_service(tmp_path, schema_version=5)
+    seed_container(service)
+    seed_pane(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="slave", schema_version=4),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "schema_version_newer"
+    assert "upgrade the CLI" in info.value.message
+
+
+def test_schema_version_equal_does_not_refuse(tmp_path: Path) -> None:
+    service = make_service(tmp_path, schema_version=4)
+    seed_container(service)
+    seed_pane(service)
+    result = service.register_agent(
+        register_params(role="slave", schema_version=4),
+        socket_peer_uid=1000,
+    )
+    assert result["role"] == "slave"
+
+
+def test_schema_version_omitted_does_not_refuse(tmp_path: Path) -> None:
+    """An older CLI that does not send the field still works (back-compat)."""
+    service = make_service(tmp_path, schema_version=4)
+    seed_container(service)
+    seed_pane(service)
+    result = service.register_agent(
+        register_params(role="slave"),
+        socket_peer_uid=1000,
+    )
+    assert result["role"] == "slave"
+
+
+def test_register_self_cli_includes_schema_version() -> None:
+    """The CLI build's MAX_SUPPORTED_SCHEMA_VERSION feeds the wire request.
+
+    Without this, ``schema_version_newer`` is unreachable (review-pass-1).
+    """
+    from agenttower.config_doctor import MAX_SUPPORTED_SCHEMA_VERSION
+    from agenttower.state.schema import CURRENT_SCHEMA_VERSION
+
+    # The CLI build's ceiling and the daemon build's current schema track
+    # together — both bumped in lockstep with each schema migration.
+    assert MAX_SUPPORTED_SCHEMA_VERSION == CURRENT_SCHEMA_VERSION
diff --git a/tests/unit/test_register_supplied_vs_default.py b/tests/unit/test_register_supplied_vs_default.py
new file mode 100644
index 0000000..b548da2
--- /dev/null
+++ b/tests/unit/test_register_supplied_vs_default.py
@@ -0,0 +1,66 @@
+"""Unit tests for FEAT-006 supplied-vs-default wire contract (T027 / Q1).
+
+Covers Clarifications session 2026-05-07 Q1:
+* Argparse defaults are NOT transmitted on idempotent re-registration.
+* Explicit ``--role unknown`` overwrites a stored value.
+* Omitted ``--role`` leaves a stored value unchanged.
+* On first registration, daemon applies defaults symmetrically.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._agent_test_helpers import (
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_first_registration_applies_defaults(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    # No mutable flags supplied at all — daemon applies argparse-style
+    # defaults (role=unknown, capability=unknown, label="", project="").
+    result = service.register_agent(
+        register_params(),
+        socket_peer_uid=1000,
+    )
+    assert result["role"] == "unknown"
+    assert result["capability"] == "unknown"
+    assert result["label"] == ""
+    assert result["project_path"] == ""
+
+
+def test_explicit_unknown_overwrites_stored_role(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # Explicit --role unknown is still present in params and DOES overwrite.
+    result = service.register_agent(
+        register_params(role="unknown"), socket_peer_uid=1000
+    )
+    assert result["role"] == "unknown"
+
+
+def test_omitted_role_does_not_overwrite_stored(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # Re-register without --role — stored value preserved.
+    result = service.register_agent(
+        register_params(), socket_peer_uid=1000
+    )
+    assert result["role"] == "slave"
diff --git a/tests/unit/test_register_transaction.py b/tests/unit/test_register_transaction.py
new file mode 100644
index 0000000..e92681d
--- /dev/null
+++ b/tests/unit/test_register_transaction.py
@@ -0,0 +1,87 @@
+"""Unit tests for FEAT-006 single-transaction commit / rollback (T036 / FR-035).
+
+Covers:
+* On INSERT failure (forced ``OperationalError``), no agent row is written.
+* On INSERT failure, no audit row is appended.
+* The daemon stays alive (the service raises ``RegistrationError`` with
+  code ``internal_error``).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    CK_DEFAULT,
+    make_service,
+    read_events,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_register_failure_rolls_back_and_skips_audit(
+    tmp_path: Path, monkeypatch
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+
+    from agenttower.state import agents as state_agents
+
+    def boom_insert(*args, **kwargs):
+        raise sqlite3.OperationalError("forced for test")
+
+    monkeypatch.setattr(state_agents, "insert_agent", boom_insert)
+
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="slave"), socket_peer_uid=1000
+        )
+    assert info.value.code == "internal_error"
+
+    # No agent row was written.
+    conn = service.connection_factory()
+    try:
+        count = conn.execute("SELECT COUNT(*) FROM agents").fetchone()[0]
+    finally:
+        conn.close()
+    assert count == 0
+    # No audit row was appended.
+    assert read_events(service) == []
+
+
+def test_register_fails_when_bound_pane_is_inactive_at_commit_time(
+    tmp_path: Path,
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service, active=False)
+
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="slave"), socket_peer_uid=1000
+        )
+
+    assert info.value.code == "pane_unknown_to_daemon"
+
+
+def test_register_fails_when_bound_container_is_inactive_at_commit_time(
+    tmp_path: Path,
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service, active=False)
+    seed_pane(service, active=True)
+
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="slave"), socket_peer_uid=1000
+        )
+
+    assert info.value.code == "pane_unknown_to_daemon"
diff --git a/tests/unit/test_register_value_out_of_set.py b/tests/unit/test_register_value_out_of_set.py
new file mode 100644
index 0000000..41ac73d
--- /dev/null
+++ b/tests/unit/test_register_value_out_of_set.py
@@ -0,0 +1,127 @@
+"""Unit tests for FEAT-006 closed-set rejection at register time (T035).
+
+Covers FR-004 / FR-005 / Clarifications Q2: out-of-set role / capability
+/ parent_agent_id rejected with ``value_out_of_set``; mixed-case values
+rejected without normalization; actionable message lists canonical
+lowercase tokens.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+@pytest.mark.parametrize(
+    "field,value",
+    [
+        ("role", "Slave"),
+        ("role", "MASTER"),
+        ("role", "robot"),
+        ("capability", "Claude"),
+        ("capability", "vim"),
+        ("parent_agent_id", "AGT_abc123def456"),
+        ("parent_agent_id", "agt_ABC123def456"),
+        ("parent_agent_id", "agt_xyz123def456"),
+    ],
+)
+def test_invalid_values_rejected(tmp_path: Path, field: str, value: str) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    params = register_params(**{field: value})
+    # Some combinations also need a valid role to reach the parent check.
+    if field == "parent_agent_id":
+        params["role"] = "swarm"
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(params, socket_peer_uid=1000)
+    assert info.value.code == "value_out_of_set"
+
+
+def test_unknown_role_message_lists_canonical_tokens(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(role="robot"),
+            socket_peer_uid=1000,
+        )
+    msg = info.value.message.lower()
+    for tok in ("master", "slave", "swarm", "test-runner", "shell", "unknown"):
+        assert tok in msg
+
+
+def test_register_agent_rejects_unknown_keys(tmp_path: Path) -> None:
+    """Review-pass-3: unknown params keys MUST fail with bad_request.
+
+    Mirrors the FR-026 ``unknown_filter`` gate ``list_agents`` enforces.
+    Without this, a stale CLI sending an obsolete or typo'd field would
+    silently see its registration succeed with that field ignored —
+    making forward-compat issues look like "it just worked".
+    """
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    params = register_params(role="slave")
+    params["typo_label"] = "oops"
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(params, socket_peer_uid=1000)
+    assert info.value.code == "bad_request"
+    assert "typo_label" in info.value.message
+
+
+def test_register_agent_rejects_attempted_socket_peer_uid_spoof(
+    tmp_path: Path,
+) -> None:
+    """A client cannot smuggle ``socket_peer_uid`` via the request body.
+
+    The dispatcher already sources ``peer_uid`` out-of-band from
+    SO_PEERCRED (review-pass-1), but layered defence: the unknown-keys
+    gate refuses the request entirely so the audit trail is unambiguous.
+    """
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    params = register_params(role="slave")
+    params["socket_peer_uid"] = 9999
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(params, socket_peer_uid=1000)
+    assert info.value.code == "bad_request"
+    assert "socket_peer_uid" in info.value.message
+
+
+def test_register_agent_rejects_missing_container_id_as_bad_request(
+    tmp_path: Path,
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    params = register_params(role="slave")
+    del params["container_id"]
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(params, socket_peer_uid=1000)
+    assert info.value.code == "bad_request"
+
+
+def test_register_agent_rejects_missing_pane_key_field_as_bad_request(
+    tmp_path: Path,
+) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    params = register_params(role="slave")
+    del params["pane_composite_key"]["tmux_pane_id"]
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(params, socket_peer_uid=1000)
+    assert info.value.code == "bad_request"
diff --git a/tests/unit/test_role_capability_validation.py b/tests/unit/test_role_capability_validation.py
new file mode 100644
index 0000000..412cd3b
--- /dev/null
+++ b/tests/unit/test_role_capability_validation.py
@@ -0,0 +1,49 @@
+"""Unit tests for FEAT-006 closed-set role / capability validation (T013).
+
+Covers FR-004 / FR-005:
+* Every closed-set value is accepted.
+* Out-of-set values are rejected with closed-set code ``value_out_of_set``.
+* Mixed-case (``Slave``, ``MASTER``, ``Codex``) is rejected without
+  normalization (Clarifications session 2026-05-07-continued Q2).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+from agenttower.agents.validation import (
+    VALID_CAPABILITIES,
+    VALID_ROLES,
+    validate_capability,
+    validate_role,
+)
+
+
+@pytest.mark.parametrize("role", VALID_ROLES)
+def test_role_accepts_canonical_lowercase(role: str) -> None:
+    assert validate_role(role) == role
+
+
+@pytest.mark.parametrize("cap", VALID_CAPABILITIES)
+def test_capability_accepts_canonical_lowercase(cap: str) -> None:
+    assert validate_capability(cap) == cap
+
+
+@pytest.mark.parametrize("bad", ["Slave", "MASTER", "Test-Runner", "shell ", "", "robot", 42])
+def test_role_rejects_mixed_case_or_unknown(bad: object) -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_role(bad)
+    assert info.value.code == "value_out_of_set"
+    # Actionable message lists the canonical lowercase tokens.
+    for token in VALID_ROLES:
+        assert token in info.value.message
+
+
+@pytest.mark.parametrize("bad", ["Claude", "CODEX", "Gemini", "openCode", "", "vim", None])
+def test_capability_rejects_mixed_case_or_unknown(bad: object) -> None:
+    with pytest.raises(RegistrationError) as info:
+        validate_capability(bad)
+    assert info.value.code == "value_out_of_set"
+    for token in VALID_CAPABILITIES:
+        assert token in info.value.message
diff --git a/tests/unit/test_schema_v4_migration_unit.py b/tests/unit/test_schema_v4_migration_unit.py
new file mode 100644
index 0000000..c79ba89
--- /dev/null
+++ b/tests/unit/test_schema_v4_migration_unit.py
@@ -0,0 +1,232 @@
+"""Unit tests for the FEAT-006 v3 → v4 SQLite migration (T016 / FR-036 / FR-037).
+
+Covers:
+* Fresh DB → v4 (table + indexes present).
+* v3-only DB upgrades to v4 in one transaction.
+* ``agents`` table + indexes are created on otherwise-unchanged FEAT-005 DBs.
+* FEAT-001..004 tables remain byte-identical pre/post migration.
+* ``_apply_migration_v4`` is idempotent (re-call after success is a no-op).
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from agenttower.state import schema
+
+
+def _make_state_db(tmp_path: Path) -> Path:
+    state_dir = tmp_path / "state"
+    state_dir.mkdir(mode=0o700)
+    return state_dir / "agenttower.sqlite3"
+
+
+def _seed_v3(state_db: Path) -> None:
+    """Build a v3-shaped database (FEAT-001 + 003 + 004 schema)."""
+    state_db.parent.mkdir(mode=0o700, exist_ok=True)
+    conn = sqlite3.connect(str(state_db), isolation_level=None)
+    try:
+        conn.execute("CREATE TABLE schema_version (version INTEGER NOT NULL)")
+        conn.execute("INSERT INTO schema_version (version) VALUES (3)")
+        schema._apply_migration_v2(conn)
+        schema._apply_migration_v3(conn)
+    finally:
+        conn.close()
+    os.chmod(state_db, 0o600)
+
+
+def _open(state_db: Path):
+    return schema.open_registry(state_db, namespace_root=state_db.parent)
+
+
+def _table_names(conn: sqlite3.Connection) -> set[str]:
+    return {
+        r[0]
+        for r in conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table'"
+        ).fetchall()
+    }
+
+
+def _index_names(conn: sqlite3.Connection) -> set[str]:
+    return {
+        r[0]
+        for r in conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='index' "
+            "AND name NOT LIKE 'sqlite_%'"
+        ).fetchall()
+    }
+
+
+def _sqlite_master_snapshot_for(
+    state_db: Path, predicate_sql: str
+) -> list[tuple]:
+    conn = sqlite3.connect(str(state_db))
+    try:
+        return conn.execute(
+            f"SELECT type, name, tbl_name, sql FROM sqlite_master "
+            f"WHERE name NOT LIKE 'sqlite_%' AND {predicate_sql} "
+            f"ORDER BY type, name"
+        ).fetchall()
+    finally:
+        conn.close()
+
+
+def test_current_schema_version_is_4() -> None:
+    assert schema.CURRENT_SCHEMA_VERSION == 4
+
+
+def test_fresh_db_lands_at_v4_with_agents_table(tmp_path: Path) -> None:
+    state_db = _make_state_db(tmp_path)
+    conn, status = _open(state_db)
+    try:
+        assert status == "created"
+        version = conn.execute("SELECT version FROM schema_version").fetchone()[0]
+        assert version == 4
+        tables = _table_names(conn)
+        assert {
+            "containers",
+            "container_scans",
+            "panes",
+            "pane_scans",
+            "agents",
+        }.issubset(tables)
+        indexes = _index_names(conn)
+        assert {
+            "agents_active_order",
+            "agents_parent_lookup",
+            "agents_pane_lookup",
+        }.issubset(indexes)
+    finally:
+        conn.close()
+
+
+def test_v3_to_v4_preserves_feat001_through_feat004_tables(tmp_path: Path) -> None:
+    """SC-010: v3-only DB upgrades to v4 cleanly; pre-existing tables are
+    byte-identical."""
+    state_db = _make_state_db(tmp_path)
+    _seed_v3(state_db)
+
+    before = _sqlite_master_snapshot_for(
+        state_db, "name NOT IN ('agents','agents_active_order','agents_parent_lookup','agents_pane_lookup','schema_version')"
+    )
+
+    conn, _ = _open(state_db)
+    try:
+        version = conn.execute("SELECT version FROM schema_version").fetchone()[0]
+        assert version == 4
+        assert "agents" in _table_names(conn)
+    finally:
+        conn.close()
+
+    after = _sqlite_master_snapshot_for(
+        state_db, "name NOT IN ('agents','agents_active_order','agents_parent_lookup','agents_pane_lookup','schema_version')"
+    )
+    assert before == after, (
+        "v3 → v4 migration mutated FEAT-001..004 schema rows.\n"
+        f"before: {before!r}\n"
+        f"after:  {after!r}"
+    )
+
+
+def test_apply_migration_v4_is_idempotent(tmp_path: Path) -> None:
+    state_db = _make_state_db(tmp_path)
+    conn, _ = _open(state_db)
+    try:
+        before = sorted(_table_names(conn) | _index_names(conn))
+        schema._apply_migration_v4(conn)
+        schema._apply_migration_v4(conn)
+        after = sorted(_table_names(conn) | _index_names(conn))
+        assert before == after
+    finally:
+        conn.close()
+
+
+def test_v4_reopen_is_a_noop(tmp_path: Path) -> None:
+    """SC-010: re-opening a v4 DB is a clean no-op (defensive migration call)."""
+    state_db = _make_state_db(tmp_path)
+    _open(state_db)[0].close()
+
+    before = _sqlite_master_snapshot_for(state_db, "1=1")
+
+    conn, _ = _open(state_db)
+    try:
+        version = conn.execute("SELECT version FROM schema_version").fetchone()[0]
+        assert version == 4
+    finally:
+        conn.close()
+
+    after = _sqlite_master_snapshot_for(state_db, "1=1")
+    assert before == after
+
+
+def test_agents_table_uniqueness_constraint_on_pane_key(tmp_path: Path) -> None:
+    state_db = _make_state_db(tmp_path)
+    conn, _ = _open(state_db)
+    try:
+        conn.execute(
+            "INSERT INTO agents ("
+            "agent_id, container_id, tmux_socket_path, tmux_session_name, "
+            "tmux_window_index, tmux_pane_index, tmux_pane_id, role, capability, "
+            "label, project_path, parent_agent_id, effective_permissions, "
+            "created_at, last_registered_at, last_seen_at, active) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                "agt_aaaaaaaaaaaa",
+                "c1", "/tmp/tmux-1000/default", "main", 0, 0, "%0",
+                "slave", "codex", "lbl", "/w", None, "{}",
+                "2026-05-07T00:00:00.000000+00:00",
+                "2026-05-07T00:00:00.000000+00:00",
+                None, 1,
+            ),
+        )
+        with pytest.raises(sqlite3.IntegrityError):
+            # Same composite pane key, different agent_id — rejected by UNIQUE.
+            conn.execute(
+                "INSERT INTO agents ("
+                "agent_id, container_id, tmux_socket_path, tmux_session_name, "
+                "tmux_window_index, tmux_pane_index, tmux_pane_id, role, capability, "
+                "label, project_path, parent_agent_id, effective_permissions, "
+                "created_at, last_registered_at, last_seen_at, active) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "agt_bbbbbbbbbbbb",
+                    "c1", "/tmp/tmux-1000/default", "main", 0, 0, "%0",
+                    "slave", "codex", "lbl", "/w", None, "{}",
+                    "2026-05-07T00:00:00.000000+00:00",
+                    "2026-05-07T00:00:00.000000+00:00",
+                    None, 1,
+                ),
+            )
+    finally:
+        conn.close()
+
+
+def test_agents_table_role_check_constraint_rejects_invalid(tmp_path: Path) -> None:
+    state_db = _make_state_db(tmp_path)
+    conn, _ = _open(state_db)
+    try:
+        with pytest.raises(sqlite3.IntegrityError):
+            conn.execute(
+                "INSERT INTO agents ("
+                "agent_id, container_id, tmux_socket_path, tmux_session_name, "
+                "tmux_window_index, tmux_pane_index, tmux_pane_id, role, capability, "
+                "label, project_path, parent_agent_id, effective_permissions, "
+                "created_at, last_registered_at, last_seen_at, active) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "agt_aaaaaaaaaaaa",
+                    "c1", "/tmp/tmux-1000/default", "main", 0, 0, "%0",
+                    "Slave",  # mixed-case rejected at the SQL CHECK level too
+                    "codex", "lbl", "/w", None, "{}",
+                    "2026-05-07T00:00:00.000000+00:00",
+                    "2026-05-07T00:00:00.000000+00:00",
+                    None, 1,
+                ),
+            )
+    finally:
+        conn.close()
diff --git a/tests/unit/test_set_role_no_op.py b/tests/unit/test_set_role_no_op.py
new file mode 100644
index 0000000..d2aef26
--- /dev/null
+++ b/tests/unit/test_set_role_no_op.py
@@ -0,0 +1,65 @@
+"""Unit tests for FEAT-006 set_* no-op contract (T067 / FR-027).
+
+Set-role / set-label / set-capability with the same value the agent
+already has MUST succeed (exit 0) without error and MUST append no new
+audit row. The result envelope reports ``audit_appended=False``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._agent_test_helpers import (
+    make_service,
+    read_events,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_set_role_no_op_skips_audit(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    pre = len(read_events(service))
+    result = service.set_role(
+        {"agent_id": first["agent_id"], "role": "slave"},
+        socket_peer_uid=1000,
+    )
+    assert result["audit_appended"] is False
+    assert len(read_events(service)) == pre
+
+
+def test_set_label_no_op(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave", label="orig"), socket_peer_uid=1000
+    )
+    result = service.set_label(
+        {"agent_id": first["agent_id"], "label": "orig"},
+        socket_peer_uid=1000,
+    )
+    assert result["audit_appended"] is False
+    assert result["new_value"] == "orig"
+
+
+def test_set_capability_no_op(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave", capability="codex"),
+        socket_peer_uid=1000,
+    )
+    result = service.set_capability(
+        {"agent_id": first["agent_id"], "capability": "codex"},
+        socket_peer_uid=1000,
+    )
+    assert result["audit_appended"] is False
+    assert result["new_value"] == "codex"
diff --git a/tests/unit/test_set_role_swarm_rejection.py b/tests/unit/test_set_role_swarm_rejection.py
new file mode 100644
index 0000000..3a5fb72
--- /dev/null
+++ b/tests/unit/test_set_role_swarm_rejection.py
@@ -0,0 +1,38 @@
+"""Unit tests for FEAT-006 set-role swarm rejection (T068 / FR-012).
+
+``set-role --role swarm`` is rejected with closed-set
+``swarm_role_via_set_role_rejected`` and an actionable message that
+points the operator at ``register-self --role swarm --parent <id>``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def test_set_role_swarm_rejected_actionable_message(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service)
+    first = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    with pytest.raises(RegistrationError) as info:
+        service.set_role(
+            {"agent_id": first["agent_id"], "role": "swarm"},
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "swarm_role_via_set_role_rejected"
+    assert "register-self" in info.value.message
+    assert "--role swarm --parent" in info.value.message
diff --git a/tests/unit/test_socket_api_framing.py b/tests/unit/test_socket_api_framing.py
index 4f662a3..018adf5 100644
--- a/tests/unit/test_socket_api_framing.py
+++ b/tests/unit/test_socket_api_framing.py
@@ -9,7 +9,7 @@
 from agenttower.socket_api import errors
 
 
-def test_closed_code_set_contains_feat002_through_feat004_codes() -> None:
+def test_closed_code_set_contains_feat002_through_feat006_codes() -> None:
     # FEAT-002 codes (FR-022 backward-compat).
     feat002 = {
         errors.BAD_JSON,
@@ -41,8 +41,33 @@ def test_closed_code_set_contains_feat002_through_feat004_codes() -> None:
         errors.BENCH_USER_UNRESOLVED,
     }
     assert feat004 <= errors.CLOSED_CODE_SET
+    # FEAT-006 additions (research R-010 / FR-040).
+    feat006 = {
+        errors.HOST_CONTEXT_UNSUPPORTED,
+        errors.CONTAINER_UNRESOLVED,
+        errors.NOT_IN_TMUX,
+        errors.TMUX_PANE_MALFORMED,
+        errors.PANE_UNKNOWN_TO_DAEMON,
+        errors.AGENT_NOT_FOUND,
+        errors.AGENT_INACTIVE,
+        errors.PARENT_NOT_FOUND,
+        errors.PARENT_INACTIVE,
+        errors.PARENT_ROLE_INVALID,
+        errors.PARENT_ROLE_MISMATCH,
+        errors.PARENT_IMMUTABLE,
+        errors.SWARM_PARENT_REQUIRED,
+        errors.SWARM_ROLE_VIA_SET_ROLE_REJECTED,
+        errors.MASTER_VIA_REGISTER_SELF_REJECTED,
+        errors.MASTER_CONFIRM_REQUIRED,
+        errors.VALUE_OUT_OF_SET,
+        errors.FIELD_TOO_LONG,
+        errors.PROJECT_PATH_INVALID,
+        errors.UNKNOWN_FILTER,
+        errors.SCHEMA_VERSION_NEWER,
+    }
+    assert feat006 <= errors.CLOSED_CODE_SET
     # No surprise codes beyond the documented sets.
-    assert errors.CLOSED_CODE_SET == feat002 | feat003 | feat004
+    assert errors.CLOSED_CODE_SET == feat002 | feat003 | feat004 | feat006
 
 
 @pytest.mark.parametrize(
@@ -179,7 +204,7 @@ def test_dispatch_accepts_valid_ping() -> None:
 def test_dispatch_handles_internal_exception_gracefully() -> None:
     handler, _ = _make_handler(b'{"method": "ping"}\n')
 
-    def boom(ctx, params):  # noqa: ANN001
+    def boom(ctx, params, peer_uid=-1):  # noqa: ANN001
         raise RuntimeError("kaboom")
 
     from agenttower.socket_api.methods import DISPATCH
diff --git a/tests/unit/test_socket_api_methods.py b/tests/unit/test_socket_api_methods.py
index faf4500..bc445e7 100644
--- a/tests/unit/test_socket_api_methods.py
+++ b/tests/unit/test_socket_api_methods.py
@@ -51,8 +51,8 @@ def fail(*args, **kwargs):  # noqa: ANN001, ANN002, ANN003, ARG001
 
 
 def test_dispatch_table_keys_are_closed_set() -> None:
-    # FEAT-002 keys + FEAT-003 additions + FEAT-004 additions (FR-022 / FR-030
-    # backward-compat).
+    # FEAT-002 keys + FEAT-003 additions + FEAT-004 additions + FEAT-006
+    # additions (FR-022 / FR-030 backward-compat; FR-023 for FEAT-006).
     assert set(DISPATCH.keys()) == {
         "ping",
         "status",
@@ -61,6 +61,11 @@ def test_dispatch_table_keys_are_closed_set() -> None:
         "list_containers",
         "scan_panes",
         "list_panes",
+        "register_agent",
+        "list_agents",
+        "set_role",
+        "set_label",
+        "set_capability",
     }
 
 
@@ -159,3 +164,127 @@ def test_shutdown_with_no_event_returns_ok_anyway(tmp_path: Path) -> None:
     ctx = _ctx(tmp_path)  # shutdown_requested is None by default
     envelope = DISPATCH["shutdown"](ctx, {})
     assert envelope == {"ok": True, "result": {"shutting_down": True}}
+
+
+# ---------------------------------------------------------------------------
+# Review-pass-1: peer_uid is plumbed out-of-band, not via params.
+# Regression for the FEAT-006 review finding that ``params.pop("__socket_peer_uid__")``
+# allowed a client to spoof audit provenance (and silently fell back to -1
+# whether or not the server populated it). The dispatcher MUST source
+# peer_uid from the third positional arg the server provides from
+# SO_PEERCRED, and MUST NOT consult the params object for it.
+# ---------------------------------------------------------------------------
+
+
+class _RecordingAgentService:
+    """Minimal stand-in for ``AgentService`` used to capture peer_uid."""
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, dict, int | None]] = []
+
+    def register_agent(self, params, *, socket_peer_uid):  # noqa: ANN001
+        self.calls.append(("register_agent", dict(params), socket_peer_uid))
+        return {"agent_id": "agt_000000000001", "role": "unknown"}
+
+    def set_role(self, params, *, socket_peer_uid):  # noqa: ANN001
+        self.calls.append(("set_role", dict(params), socket_peer_uid))
+        return {"agent_id": params.get("agent_id"), "role": params.get("role")}
+
+
+def _agent_ctx(tmp_path: Path, service: _RecordingAgentService) -> DaemonContext:
+    ctx = _ctx(tmp_path)
+    ctx.agent_service = service
+    return ctx
+
+
+def test_register_agent_uses_third_arg_peer_uid(tmp_path: Path) -> None:
+    service = _RecordingAgentService()
+    ctx = _agent_ctx(tmp_path, service)
+    DISPATCH["register_agent"](ctx, {"role": "slave"}, 4242)
+    assert service.calls == [("register_agent", {"role": "slave"}, 4242)]
+
+
+def test_register_agent_ignores_params_socket_peer_uid_field(tmp_path: Path) -> None:
+    """A client cannot spoof socket_peer_uid via the request body."""
+    service = _RecordingAgentService()
+    ctx = _agent_ctx(tmp_path, service)
+    DISPATCH["register_agent"](
+        ctx,
+        {"role": "slave", "__socket_peer_uid__": 9999, "socket_peer_uid": 9999},
+        1000,
+    )
+    # The recorded peer_uid is the third arg the server supplied — the
+    # spoofed body fields are forwarded unchanged but ignored by audit.
+    assert service.calls[0][2] == 1000
+
+
+class _RecordingPaneService:
+    def __init__(self) -> None:
+        self.calls: list[str | None] = []
+
+    def scan_for_container(self, *, container_id: str | None):  # noqa: ANN001
+        self.calls.append(container_id)
+        return type(
+            "PaneScanResultStub",
+            (),
+            {
+                "scan_id": "scan-1",
+                "started_at": "2026-05-07T00:00:00.000000+00:00",
+                "completed_at": "2026-05-07T00:00:01.000000+00:00",
+                "status": "ok",
+                "containers_scanned": 1,
+                "sockets_scanned": 1,
+                "panes_seen": 1,
+                "panes_newly_active": 0,
+                "panes_reconciled_inactive": 0,
+                "containers_skipped_inactive": 0,
+                "containers_tmux_unavailable": 0,
+                "error_code": None,
+                "error_message": None,
+                "error_details": (),
+            },
+        )()
+
+
+def test_scan_panes_honors_optional_container_scope(tmp_path: Path) -> None:
+    service = _RecordingPaneService()
+    ctx = _ctx(tmp_path)
+    ctx.pane_service = service
+
+    envelope = DISPATCH["scan_panes"](ctx, {"container": "a" * 64})
+
+    assert envelope["ok"] is True
+    assert service.calls == ["a" * 64]
+
+
+def test_scan_panes_rejects_non_string_container_scope(tmp_path: Path) -> None:
+    service = _RecordingPaneService()
+    ctx = _ctx(tmp_path)
+    ctx.pane_service = service
+
+    envelope = DISPATCH["scan_panes"](ctx, {"container": 123})
+
+    assert envelope["ok"] is False
+    assert envelope["error"]["code"] == "bad_request"
+    assert service.calls == []
+
+
+def test_register_agent_default_peer_uid_when_called_without_third_arg(
+    tmp_path: Path,
+) -> None:
+    """Tests that exercise DISPATCH directly without a real socket get -1."""
+    service = _RecordingAgentService()
+    ctx = _agent_ctx(tmp_path, service)
+    DISPATCH["register_agent"](ctx, {"role": "slave"})
+    assert service.calls[0][2] == -1
+
+
+def test_set_role_uses_third_arg_peer_uid(tmp_path: Path) -> None:
+    service = _RecordingAgentService()
+    ctx = _agent_ctx(tmp_path, service)
+    DISPATCH["set_role"](ctx, {"agent_id": "agt_x", "role": "slave"}, 1000)
+    assert service.calls[-1] == (
+        "set_role",
+        {"agent_id": "agt_x", "role": "slave"},
+        1000,
+    )
diff --git a/tests/unit/test_socket_api_pane_methods.py b/tests/unit/test_socket_api_pane_methods.py
index 46f39ae..fa049ae 100644
--- a/tests/unit/test_socket_api_pane_methods.py
+++ b/tests/unit/test_socket_api_pane_methods.py
@@ -15,30 +15,41 @@
 class _FakePaneService:
     def __init__(self, *, list_rows: list[Any] | None = None) -> None:
         self.scan_called = 0
+        self.scan_container_filters: list[str | None] = []
         self.list_called = 0
         self._list_rows = list_rows or []
         self._mutex = threading.Lock()
 
-    def scan(self) -> Any:
+    def _build_result(self) -> Any:
         from agenttower.discovery.pane_service import PaneScanResult
 
+        return PaneScanResult(
+            scan_id="abc",
+            started_at="2026-05-06T10:00:00.000000+00:00",
+            completed_at="2026-05-06T10:00:00.500000+00:00",
+            status="ok",
+            containers_scanned=1,
+            sockets_scanned=1,
+            panes_seen=1,
+            panes_newly_active=1,
+            panes_reconciled_inactive=0,
+            containers_skipped_inactive=0,
+            containers_tmux_unavailable=0,
+            error_code=None,
+            error_message=None,
+        )
+
+    def scan(self) -> Any:
+        with self._mutex:
+            self.scan_called += 1
+            self.scan_container_filters.append(None)
+            return self._build_result()
+
+    def scan_for_container(self, *, container_id: str | None) -> Any:
         with self._mutex:
             self.scan_called += 1
-            return PaneScanResult(
-                scan_id="abc",
-                started_at="2026-05-06T10:00:00.000000+00:00",
-                completed_at="2026-05-06T10:00:00.500000+00:00",
-                status="ok",
-                containers_scanned=1,
-                sockets_scanned=1,
-                panes_seen=1,
-                panes_newly_active=1,
-                panes_reconciled_inactive=0,
-                containers_skipped_inactive=0,
-                containers_tmux_unavailable=0,
-                error_code=None,
-                error_message=None,
-            )
+            self.scan_container_filters.append(container_id)
+            return self._build_result()
 
     def list_panes(self, *, active_only: bool = False, container_filter: str | None = None) -> list[Any]:
         self.list_called += 1
diff --git a/tests/unit/test_state_containers.py b/tests/unit/test_state_containers.py
index 22a54da..dfc2eb8 100644
--- a/tests/unit/test_state_containers.py
+++ b/tests/unit/test_state_containers.py
@@ -37,7 +37,8 @@ def test_open_registry_migrates_v1_to_v2(tmp_path: Path) -> None:
     try:
         assert status == "already initialized"
         version = conn.execute("SELECT version FROM schema_version").fetchone()[0]
-        assert version == 3
+        # FEAT-006 bumped CURRENT_SCHEMA_VERSION to 4; v1→current still passes.
+        assert version == schema.CURRENT_SCHEMA_VERSION
         tables = {
             r[0]
             for r in conn.execute(
@@ -56,7 +57,8 @@ def test_open_registry_v2_reopen_is_idempotent(tmp_path: Path) -> None:
     conn, _ = schema.open_registry(state_db, namespace_root=state_db.parent)
     try:
         version = conn.execute("SELECT version FROM schema_version").fetchone()[0]
-        assert version == 3
+        # FEAT-006 bumped CURRENT_SCHEMA_VERSION to 4; v1→current still passes.
+        assert version == schema.CURRENT_SCHEMA_VERSION
     finally:
         conn.close()
 
diff --git a/tests/unit/test_state_panes.py b/tests/unit/test_state_panes.py
index ff6ee1b..87a2d75 100644
--- a/tests/unit/test_state_panes.py
+++ b/tests/unit/test_state_panes.py
@@ -46,7 +46,8 @@ def test_v2_to_v3_migration_creates_panes_and_pane_scans(tmp_path: Path) -> None
     conn, status = _open(state_db)
     try:
         version = conn.execute("SELECT version FROM schema_version").fetchone()[0]
-        assert version == 3
+        # FEAT-006 bumped CURRENT_SCHEMA_VERSION to 4; v2→current still creates panes/pane_scans.
+        assert version == schema.CURRENT_SCHEMA_VERSION
         tables = {
             r[0]
             for r in conn.execute(
@@ -65,7 +66,8 @@ def test_v3_reopen_is_idempotent(tmp_path: Path) -> None:
     conn, _ = _open(state_db)
     try:
         version = conn.execute("SELECT version FROM schema_version").fetchone()[0]
-        assert version == 3
+        # FEAT-006 bumped CURRENT_SCHEMA_VERSION to 4; v2→current still creates panes/pane_scans.
+        assert version == schema.CURRENT_SCHEMA_VERSION
         # Both new indexes should exist after re-open.
         indexes = {
             r[0]
@@ -79,13 +81,23 @@ def test_v3_reopen_is_idempotent(tmp_path: Path) -> None:
         conn.close()
 
 
-def test_open_registry_refuses_future_v4(tmp_path: Path) -> None:
+def test_open_registry_refuses_future_version(tmp_path: Path) -> None:
+    """A schema_version newer than CURRENT_SCHEMA_VERSION must be refused.
+
+    Originally written as ``test_open_registry_refuses_future_v4`` when
+    ``CURRENT_SCHEMA_VERSION=3``; FEAT-006 bumped to 4 so the test now
+    seeds ``CURRENT_SCHEMA_VERSION + 1`` to keep the forward-compat
+    invariant testable independent of the build version.
+    """
     state_db = _make_state_db(tmp_path)
     state_db.parent.mkdir(mode=0o700, exist_ok=True)
     conn = sqlite3.connect(str(state_db), isolation_level=None)
     try:
         conn.execute("CREATE TABLE schema_version (version INTEGER NOT NULL)")
-        conn.execute("INSERT INTO schema_version (version) VALUES (4)")
+        conn.execute(
+            "INSERT INTO schema_version (version) VALUES (?)",
+            (schema.CURRENT_SCHEMA_VERSION + 1,),
+        )
     finally:
         conn.close()
     os.chmod(state_db, 0o600)
diff --git a/tests/unit/test_state_panes_migration_idempotence.py b/tests/unit/test_state_panes_migration_idempotence.py
index 2b5b716..2a6ecea 100644
--- a/tests/unit/test_state_panes_migration_idempotence.py
+++ b/tests/unit/test_state_panes_migration_idempotence.py
@@ -79,7 +79,9 @@ def test_v1_to_v3_migrates_in_one_open(tmp_path: Path) -> None:
     try:
         assert status == "already initialized"
         version = conn.execute("SELECT version FROM schema_version").fetchone()[0]
-        assert version == 3
+        # FEAT-006 bumped CURRENT_SCHEMA_VERSION to 4; the v1→current migration
+        # still needs to land all FEAT-003 + FEAT-004 tables in one open call.
+        assert version == schema.CURRENT_SCHEMA_VERSION
 
         tables = {
             r[0]
@@ -127,8 +129,11 @@ def test_v3_reopen_does_not_create_or_alter_anything(tmp_path: Path) -> None:
     # EXISTS`` so the snapshot must not change.
     conn2, _ = _open(state_db)
     try:
-        # Sanity: still on v3.
-        assert conn2.execute("SELECT version FROM schema_version").fetchone()[0] == 3
+        # Sanity: still at the build's current version.
+        assert (
+            conn2.execute("SELECT version FROM schema_version").fetchone()[0]
+            == schema.CURRENT_SCHEMA_VERSION
+        )
     finally:
         conn2.close()
 
diff --git a/tests/unit/test_swarm_parent_validation.py b/tests/unit/test_swarm_parent_validation.py
new file mode 100644
index 0000000..79e1e24
--- /dev/null
+++ b/tests/unit/test_swarm_parent_validation.py
@@ -0,0 +1,190 @@
+"""Unit tests for FEAT-006 swarm parent validation (T082 / FR-015..FR-020).
+
+Covers all five failure paths plus the success path:
+* ``parent_not_found``    — parent agent_id does not exist.
+* ``parent_inactive``     — parent agent is active=false.
+* ``parent_role_invalid`` — parent role is not 'slave' (incl. nested swarm).
+* ``parent_role_mismatch``— --parent supplied without --role swarm.
+* ``swarm_parent_required`` — --role swarm without --parent.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agenttower.agents.errors import RegistrationError
+
+from ._agent_test_helpers import (
+    CK_DEFAULT,
+    CONTAINER_ID,
+    make_service,
+    register_params,
+    seed_container,
+    seed_pane,
+)
+
+
+def _seed_two_panes(service) -> None:
+    seed_container(service)
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+
+
+def _ck1() -> tuple:
+    return (CONTAINER_ID, "/tmp/tmux-1000/default", "main", 0, 1, "%1")
+
+
+def test_swarm_success_path(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_panes(service)
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    child = service.register_agent(
+        register_params(_ck1(), role="swarm", parent_agent_id=parent["agent_id"]),
+        socket_peer_uid=1000,
+    )
+    assert child["role"] == "swarm"
+    assert child["parent_agent_id"] == parent["agent_id"]
+
+
+def test_parent_not_found(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_panes(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(
+                _ck1(), role="swarm", parent_agent_id="agt_aaaaaaaaaaaa"
+            ),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "parent_not_found"
+
+
+def test_parent_inactive(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_panes(service)
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # Force the parent inactive.
+    conn = service.connection_factory()
+    try:
+        conn.execute(
+            "UPDATE agents SET active = 0 WHERE agent_id = ?",
+            (parent["agent_id"],),
+        )
+    finally:
+        conn.close()
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(
+                _ck1(), role="swarm", parent_agent_id=parent["agent_id"]
+            ),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "parent_inactive"
+
+
+@pytest.mark.parametrize("parent_role", ["master", "test-runner", "shell", "unknown"])
+def test_parent_role_invalid_for_non_slave(
+    tmp_path: Path, parent_role: str
+) -> None:
+    service = make_service(tmp_path)
+    _seed_two_panes(service)
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    # Promote/demote the parent to a non-slave role first.
+    if parent_role == "master":
+        service.set_role(
+            {"agent_id": parent["agent_id"], "role": "master", "confirm": True},
+            socket_peer_uid=1000,
+        )
+    else:
+        service.set_role(
+            {"agent_id": parent["agent_id"], "role": parent_role},
+            socket_peer_uid=1000,
+        )
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(
+                _ck1(), role="swarm", parent_agent_id=parent["agent_id"]
+            ),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "parent_role_invalid"
+
+
+def test_nested_swarm_rejected(tmp_path: Path) -> None:
+    """FR-020: a swarm cannot be a parent (parent must be role=slave)."""
+    service = make_service(tmp_path)
+    seed_container(service)
+    seed_pane(service, tmux_pane_index=0, tmux_pane_id="%0")
+    seed_pane(service, tmux_pane_index=1, tmux_pane_id="%1")
+    seed_pane(service, tmux_pane_index=2, tmux_pane_id="%2")
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    swarm = service.register_agent(
+        register_params(_ck1(), role="swarm", parent_agent_id=parent["agent_id"]),
+        socket_peer_uid=1000,
+    )
+    ck2 = (CONTAINER_ID, "/tmp/tmux-1000/default", "main", 0, 2, "%2")
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(ck2, role="swarm", parent_agent_id=swarm["agent_id"]),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "parent_role_invalid"
+
+
+def test_parent_role_mismatch_when_role_not_swarm(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_panes(service)
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(
+                _ck1(), role="slave", parent_agent_id=parent["agent_id"]
+            ),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "parent_role_mismatch"
+
+
+def test_swarm_parent_required_when_role_swarm_without_parent(tmp_path: Path) -> None:
+    service = make_service(tmp_path)
+    _seed_two_panes(service)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(
+            register_params(_ck1(), role="swarm"),
+            socket_peer_uid=1000,
+        )
+    assert info.value.code == "swarm_parent_required"
+
+
+def test_parent_role_mismatch_when_role_omitted_with_parent_supplied(
+    tmp_path: Path,
+) -> None:
+    """FR-016: supplying --parent while omitting --role MUST be rejected.
+
+    Regression for the review-pass-1 finding that the pre-flight only
+    fired when ``role_in`` was explicitly present, leaving creation to
+    silently default to role="unknown" while persisting parent_agent_id.
+    """
+    service = make_service(tmp_path)
+    _seed_two_panes(service)
+    parent = service.register_agent(
+        register_params(role="slave"), socket_peer_uid=1000
+    )
+    params = register_params(_ck1(), parent_agent_id=parent["agent_id"])
+    # Drop the role field so the wire request omits it (default unknown).
+    params.pop("role", None)
+    with pytest.raises(RegistrationError) as info:
+        service.register_agent(params, socket_peer_uid=1000)
+    assert info.value.code == "parent_role_mismatch"