|
| 1 | +--- |
| 2 | +title: Agent identity provenance |
| 3 | +description: The versioned Squad-owned contract for stable agent identity metadata. |
| 4 | +--- |
| 5 | + |
| 6 | +Squad publishes authoritative agent identity metadata at |
| 7 | +`.squad/casting/registry.json`. Consumers such as dashboards and renderers must |
| 8 | +use this record instead of inferring identity from a roster row, goal owner, |
| 9 | +issue assignee, pull request author or reviewer, workflow actor, branch name, or |
| 10 | +any other incidental signal. |
| 11 | + |
| 12 | +## Version 1 contract |
| 13 | + |
| 14 | +The root schema identifier is `squad-agent-provenance/v1`. Each key in |
| 15 | +`agents` is an immutable lowercase kebab-case agent ID. The record contains a |
| 16 | +mutable `display_name`, a compatibility alias named `persistent_name`, the |
| 17 | +agent role and universe, lifecycle timestamps, status, and an optional avatar. |
| 18 | + |
| 19 | +```json |
| 20 | +{ |
| 21 | + "schema": "squad-agent-provenance/v1", |
| 22 | + "schema_version": 1, |
| 23 | + "revision": 4, |
| 24 | + "transaction_id": "52ab75df-79de-44e7-b0b7-521a45b49204", |
| 25 | + "generated_at": "2026-09-21T20:00:00.000Z", |
| 26 | + "agents": { |
| 27 | + "runtime-engineer": { |
| 28 | + "display_name": "Kepler", |
| 29 | + "persistent_name": "Kepler", |
| 30 | + "role": "Runtime Engineer", |
| 31 | + "universe": "descriptive", |
| 32 | + "status": "active", |
| 33 | + "created_at": "2026-09-20T20:00:00.000Z", |
| 34 | + "updated_at": "2026-09-21T20:00:00.000Z", |
| 35 | + "avatar": { |
| 36 | + "kind": "repository-path", |
| 37 | + "path": ".squad/agents/runtime-engineer/avatar.png" |
| 38 | + } |
| 39 | + } |
| 40 | + } |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +`persistent_name` is retained for older Squad readers and must equal |
| 45 | +`display_name`. New consumers should use the object key as the stable ID and |
| 46 | +`display_name` for presentation. |
| 47 | + |
| 48 | +`transaction_id` is additive publication metadata. Managed |
| 49 | +`casting/history.json` files carry the same `transaction_id` plus a |
| 50 | +`registry_revision` equal to the registry `revision`. Consumers that require a |
| 51 | +consistent registry/history pair must use the SDK pair reader, which validates |
| 52 | +those fields and the durable commit manifest. Registry-only consumers may |
| 53 | +continue reading `registry.json` directly. |
| 54 | + |
| 55 | +## Lifecycle and collision rules |
| 56 | + |
| 57 | +- **Uniqueness:** Canonical IDs use lowercase alphanumeric segments separated |
| 58 | + by single hyphens. IDs and case-folded display names are unique within one |
| 59 | + registry. Producers reject collisions rather than adding suffixes. |
| 60 | +- **Rename or recast:** The producer must supply the existing stable ID |
| 61 | + explicitly; it never discovers identity from display name, role, roster, |
| 62 | + label, path, or other incidental data. Preserve `created_at` and immutable |
| 63 | + `role`; update `display_name`, `persistent_name`, `universe`, and `updated_at`. |
| 64 | +- **Deletion:** Preserve a tombstone with `status: "retired"`, `retired_at`, and |
| 65 | + the original ID. An ID is never reassigned. |
| 66 | +- **Reactivation:** A producer may reactivate the same logical agent under its |
| 67 | + original ID. It must not assign that ID to a different role. |
| 68 | +- **Partial data:** Invalid individual records are excluded by the SDK parser |
| 69 | + and reported as a partial result. Consumers may render valid records but must |
| 70 | + expose that identity data is incomplete. |
| 71 | +- **Missing or malformed data:** Treat identity provenance as unavailable. Do |
| 72 | + not fall back to owner, assignee, author, reviewer, actor, branch, or roster |
| 73 | + display data. |
| 74 | +- **Legacy migration:** A legacy root is accepted only when every record has a |
| 75 | + canonical ID plus valid name, lifecycle, universe, and timestamps. Any |
| 76 | + malformed record rejects the whole producer update; migration never drops it. |
| 77 | +- **Concurrent producers:** Presets and CLI Cast share one durable directory |
| 78 | + lock. Registry/history updates publish through a roll-forward transaction; |
| 79 | + pair readers accept only a complete legacy pair or a stable manifest-backed |
| 80 | + pair. Each successful update observes the latest revision, increments it, |
| 81 | + and preserves all unclaimed IDs as tombstones. |
| 82 | + |
| 83 | +## Consistency, durability, and recovery boundaries |
| 84 | + |
| 85 | +On a local filesystem that provides atomic same-filesystem rename, the shared |
| 86 | +lock, transaction journal, commit manifest, and pair reader provide |
| 87 | +**process-crash consistency**. A crash before the journal is durable leaves the |
| 88 | +previous pair authoritative. After the journal is durable, recovery rolls the |
| 89 | +transaction forward. Pair readers retry an in-progress state for a bounded |
| 90 | +period and then reject it rather than returning a torn registry/history pair. |
| 91 | + |
| 92 | +**Power-loss durability is conditional.** The implementation calls fsync on |
| 93 | +each payload or replacement file and the relevant payload and parent |
| 94 | +directories, but persistence across power loss depends on every fsync |
| 95 | +succeeding and on the operating system, storage device, and filesystem |
| 96 | +honoring those operations and atomic rename semantics. If a required file or |
| 97 | +directory fsync reports an error, the writer fails closed; it does not report |
| 98 | +the update as durably committed. A filesystem that does not provide local |
| 99 | +atomic rename guarantees, including some network filesystems, is outside the |
| 100 | +full guarantee: even if its APIs return success, power-loss durability and |
| 101 | +cross-process consistency are only as strong as that filesystem's documented |
| 102 | +semantics. Use a supported local filesystem when the full guarantee is |
| 103 | +required. |
| 104 | + |
| 105 | +Stale-lock recovery deliberately favors safety over availability. Squad |
| 106 | +automatically removes an abandoned writer lock only when it is old, belongs to |
| 107 | +the current host, and the owner PID is definitively dead. An owner on another |
| 108 | +host, an indeterminate PID, or an abandoned recovery guard is not broken |
| 109 | +automatically; writers time out and require operator intervention after |
| 110 | +verifying that no writer or recovery operation is active. This can delay |
| 111 | +updates, but prevents an uncertain recovery from admitting concurrent writers. |
| 112 | + |
| 113 | +## Fetch, permissions, and caching |
| 114 | + |
| 115 | +Reading the registry requires repository Contents read permission and one |
| 116 | +content fetch. A repository-path avatar requires one additional content fetch |
| 117 | +for that agent. Consumers should cache the registry by Git blob SHA, ETag, or |
| 118 | +equivalent immutable revision marker and revalidate normally. The root |
| 119 | +`revision` is monotonic producer metadata, not a substitute for transport cache |
| 120 | +validation. |
| 121 | + |
| 122 | +Avatar references are optional and restricted to the owning ID's exact, |
| 123 | +case-sensitive `.squad/agents/{id}/` directory. Recasts preserve an existing |
| 124 | +avatar when no avatar operation is supplied; an explicit producer clear removes |
| 125 | +it. When the field is absent, stale, inaccessible, or malformed, render no avatar. Do not |
| 126 | +generate initials, Gravatars, GitHub actor images, or other inferred identity. |
| 127 | + |
| 128 | +## Work-to-agent binding contract |
| 129 | + |
| 130 | +The registry does not identify which agent owns a particular goal, epic, or |
| 131 | +task. Squad activation artifacts therefore include a non-empty `Activation |
| 132 | +bindings:` JSON array using `squad-work-agent-binding/v1`: |
| 133 | + |
| 134 | +```json |
| 135 | +[ |
| 136 | + { |
| 137 | + "binding_schema": "squad-work-agent-binding/v1", |
| 138 | + "binding_version": 1, |
| 139 | + "producer": "squad", |
| 140 | + "repository": "owner/repository", |
| 141 | + "origin_issue": 45, |
| 142 | + "artifact": "activated", |
| 143 | + "registry_schema": "squad-agent-provenance/v1", |
| 144 | + "registry_revision": 4, |
| 145 | + "task": "1", |
| 146 | + "issue": "#2066", |
| 147 | + "epic": "1.1", |
| 148 | + "epic_issue": "#2065", |
| 149 | + "agent_id": "runtime-engineer", |
| 150 | + "epic_agent_ids": ["runtime-engineer"] |
| 151 | + } |
| 152 | +] |
| 153 | +``` |
| 154 | + |
| 155 | +The repository and origin issue identify the goal, `issue` identifies the task, |
| 156 | +and `epic_issue` identifies its parent work artifact. The producer copies |
| 157 | +`agent_id` values directly from the committed registry revision into the |
| 158 | +accepted plan and then the activation record. Display names, labels, owners, |
| 159 | +assignees, authors, reviewers, workflow actors, branches, and roster rows are |
| 160 | +never alternate binding sources. |
| 161 | + |
| 162 | +Rename does not change historical bindings. Retirement leaves the ID resolvable |
| 163 | +through its tombstone; it does not transfer work to another agent. A current |
| 164 | +registry newer than `registry_revision` may resolve the historical ID. A |
| 165 | +binding revision newer than the available registry is stale and unavailable. |
| 166 | +Every row in one binding artifact names the same registry revision; consumers |
| 167 | +reject mixed revisions rather than reconciling rows against different identity |
| 168 | +snapshots. |
| 169 | + |
| 170 | +Missing IDs are allowed only for explicitly external, non-roster, or legacy |
| 171 | +plan assignments: `agent_id` is `null` and `identity_omission_reason` explains |
| 172 | +why. If any epic member lacks an ID, its records add |
| 173 | +`epic_identity_omission_reason: "partial"` and list only known IDs. Every row |
| 174 | +for an epic carries the same sorted `epic_agent_ids` set, equal to all known |
| 175 | +task-agent IDs for that epic. The partial marker appears on every row if any |
| 176 | +task omits `agent_id`, and on no row when the epic identity set is complete. |
| 177 | +One binding document uses one registry revision and maps each epic identifier |
| 178 | +to exactly one epic issue, and each epic issue back to exactly one identifier. |
| 179 | + |
| 180 | +Consumers fail closed for a missing, empty, malformed, partially valid, |
| 181 | +wrong-repository, wrong-origin, unsupported-version, unknown-ID, or |
| 182 | +future-revision binding array, and for duplicate task/issue bindings or |
| 183 | +conflicting epic mappings, revisions, identity sets, or omission markers. A partial registry may still support plain |
| 184 | +metadata rendering, but it cannot authoritatively resolve work bindings. They |
| 185 | +must not salvage valid-looking rows or infer |
| 186 | +the missing identity. Fetching the activation artifact requires Issues read; |
| 187 | +resolving its IDs adds the same one Contents fetch for the registry described |
| 188 | +above. No additional per-task fetch is required. |
0 commit comments