docs: describe agent authority, broker trust boundaries, and implementation gaps

README.md

@@ -109,7 +109,7 @@ Caller identity and audit records are useful building blocks, not a complete
 tenant-isolation boundary. Cross-process cryptographic proof and authority
 attenuation remain active design work. See the
 [agent identity tracker](https://github.com/stacklok/mecatl/issues/377) and the
-[working identity model](./docs/drafts/agent-identity-model.md).
+[agent identity and authority design](./docs/drafts/agent-identity/README.md).
 
 ## Try it locally
 

docs/architecture/domain-model.md

@@ -22,6 +22,13 @@ letting a restarted process rebuild the same per-session engine. `SessionKind` (
 scheduled, subagent, parallel branch, team member, or debug) and `SessionRelationship`
 record who produced the session; legacy data restores as `unknown`, which fails closed.
 
+`SessionID` addresses the conversation; `session.IncarnationID` identifies this
+lifetime of that ID. Restoration preserves the incarnation, while a newly created
+session with a reused ID gets a new one. A host-supplied `RunID` identifies one
+unit of work: fresh work gets a new ID, while approval or external-authorization
+continuation retains the pending run's ID across restart. Engine callers may omit
+`RunID`; it is a correlation label, not an authorization grant.
+
 `Limits` and `Counters` drive the stop conditions; a zero limit disables that check.
 `StopReason` is the loop's pre-turn guard and mixes the recorded reason with a limit
 check, so persistence uses `RecordedStopReason` instead.

docs/architecture/mecatl.modelith.md

@@ -270,7 +270,7 @@ A disposable harness instance — one running process — that loads `Sessions`
 
 **Relationships**
 
-- `Run` — 1:n — referenced — executes
+- `Run` — n:n — referenced — executes — A paused run can continue in another process with the same run identity.
 - `SessionLease` — 1:n — referenced — holds
 
 **Invariants**
@@ -326,7 +326,7 @@ A session's evidence of the file versions it has read, stored independently of t
 
 ### `Run`
 
-A single drive of a `Session` from a starting state to a terminal one — one invocation of the agent loop. A `Run` sequences `Turns`, emits a stream of `Events`, and ends with a stop reason (end-of-turn, budget, no-progress, cancelled, error). It is the execution, not the state: the `Session` it drives outlives it.
+One unit of work driven through a `Session` by the agent loop. It sequences `Turns` and emits `Events`. It can pause awaiting approval or external authorization and continue with the same logical run identity, even if a new in-process loop handle drives the continuation. The `Session` outlives the `Run` and can host later runs.
 
 **Relationships**
 
@@ -336,14 +336,14 @@ A single drive of a `Session` from a starting state to a terminal one — one in
 
 **Invariants**
 
-- **run-one-terminal-stop** — A `Run` drives its `Session` to exactly one terminal state and reports exactly one stop reason.
+- **run-one-terminal-stop** — A paused `Run` has no terminal stop. Its continuation retains the same run identity; on completion it reports one terminal stop reason.
 
 - **run-no-replay-after-first-chunk** — Once a `Turn` has streamed its first chunk, the `Run` never retries or replays that `Turn`.
 
 
 ### `Session`
 
-The central aggregate and unit of work: a stateful conversation between a principal and a model, with an `Environment` binding, usage accounting, and limits. A `Session` is a state machine (idle, running, awaiting, completed, cancelled, failed) and is bound to one `Provider`. Its effective `Model` is fixed for each `Turn`; a `PermissionMode` change can re-resolve the model between turns within that provider. It survives process restarts when backed by a store.
+The central aggregate: a stateful conversation between a principal and a model, with an `Environment` binding, usage accounting, and limits. A `Session` is a state machine (idle, running, awaiting, completed, cancelled, failed) and is bound to one `Provider`. Its effective `Model` is fixed for each `Turn`; a `PermissionMode` change can re-resolve the model between turns within that provider. It survives process restarts when backed by a store, preserving its incarnation identity across restoration.
 
 **Relationships**
 
@@ -368,6 +368,8 @@ The central aggregate and unit of work: a stateful conversation between a princi
 
 - **session-recover-before-reuse** — A `Session` in a terminal state (completed, cancelled, or failed) is returned to idle before any new `Run` reuses it.
 
+- **session-incarnation-persists** — A `Session` has one incarnation identity for the lifetime of its ID. Restoration preserves it; a new `Session` reusing the ID gets a new incarnation.
+
 - **session-usage-survives-restart** — Cumulative token usage is preserved across reopen, interrupt, recover, and process restart.
 
 
@@ -576,7 +578,7 @@ erDiagram
     PermissionMode ||--|| Session : "posture of"
     PermissionMode }o--|| Model : "selects via slot"
     PermissionRule }o--o{ ToolCall : "authorizes"
-    Process ||--o{ Run : "executes"
+    Process }o--o{ Run : "executes"
     Process ||--o{ SessionLease : "holds"
     Provider ||--o{ Model : "offers"
     ProviderDiscovery }o--|| Provider : "discovers metadata for"
@@ -1005,7 +1007,7 @@ erDiagram
 
 - **run-no-replay-after-first-chunk** — Once a `Turn` has streamed its first chunk, the `Run` never retries or replays that `Turn`.
 
-- **run-one-terminal-stop** — A `Run` drives its `Session` to exactly one terminal state and reports exactly one stop reason.
+- **run-one-terminal-stop** — A paused `Run` has no terminal stop. Its continuation retains the same run identity; on completion it reports one terminal stop reason.
 
 
 ### A session resumes after a restart at a pending ask
@@ -1015,12 +1017,14 @@ erDiagram
 **Steps**
 
 1. A `Session` is parked on a `PermissionAsk` when the process dies; the `EventLog` holds every `Event` up to that point.
-2. `Operator` restarts the harness; a new `Process` recovers the `Session` to idle before reuse, preserving cumulative usage.
-3. `Client` approves the pending ask; the `Run` re-enters the loop at the ask and the pending `ToolCall` executes exactly once.
+2. `Operator` restarts the harness; a new `Process` restores the awaiting `Session`, preserving its incarnation, run identity and cumulative usage.
+3. `Client` approves the pending ask; the same logical `Run` continues at the ask and the pending `ToolCall` executes exactly once.
 
 **Invariants touched**
 
-- **session-recover-before-reuse** — A `Session` in a terminal state (completed, cancelled, or failed) is returned to idle before any new `Run` reuses it.
+- **session-incarnation-persists** — A `Session` has one incarnation identity for the lifetime of its ID. Restoration preserves it; a new `Session` reusing the ID gets a new incarnation.
+
+- **run-one-terminal-stop** — A paused `Run` has no terminal stop. Its continuation retains the same run identity; on completion it reports one terminal stop reason.
 
 - **event-log-records-terminal-tail** — The `EventLog` records every `Event` a `Run` emits, including the terminal result emitted after a `Client` disconnects.
 

docs/architecture/mecatl.modelith.yaml

@@ -27,13 +27,13 @@ glossary:
 entities:
   Session:
     definition: >
-      The central aggregate and unit of work: a stateful conversation between a
-      principal and a model, with an `Environment` binding, usage accounting, and
-      limits. A `Session` is a state machine (idle, running, awaiting, completed,
+      The central aggregate: a stateful conversation between a principal and a
+      model, with an `Environment` binding, usage accounting, and limits. A
+      `Session` is a state machine (idle, running, awaiting, completed,
       cancelled, failed) and is bound to one `Provider`. Its effective `Model`
       is fixed for each `Turn`; a `PermissionMode` change can re-resolve the model
       between turns within that provider. It survives process restarts when
-      backed by a store.
+      backed by a store, preserving its incarnation identity across restoration.
     relationships:
       - entity: Conversation
         cardinality: "1:1"
@@ -110,6 +110,11 @@ entities:
         statement: >
           A `Session` in a terminal state (completed, cancelled, or failed) is
           returned to idle before any new `Run` reuses it.
+      - id: session-incarnation-persists
+        statement: >
+          A `Session` has one incarnation identity for the lifetime of its ID.
+          Restoration preserves it; a new `Session` reusing the ID gets a new
+          incarnation.
       - id: session-usage-survives-restart
         statement: >
           Cumulative token usage is preserved across reopen, interrupt, recover,
@@ -157,11 +162,11 @@ entities:
 
   Run:
     definition: >
-      A single drive of a `Session` from a starting state to a terminal one —
-      one invocation of the agent loop. A `Run` sequences `Turns`, emits a stream
-      of `Events`, and ends with a stop reason (end-of-turn, budget, no-progress,
-      cancelled, error). It is the execution, not the state: the `Session` it
-      drives outlives it.
+      One unit of work driven through a `Session` by the agent loop. It sequences
+      `Turns` and emits `Events`. It can pause awaiting approval or external
+      authorization and continue with the same logical run identity, even if a
+      new in-process loop handle drives the continuation. The `Session` outlives
+      the `Run` and can host later runs.
     relationships:
       - entity: Session
         cardinality: "n:1"
@@ -178,8 +183,8 @@ entities:
     invariants:
       - id: run-one-terminal-stop
         statement: >
-          A `Run` drives its `Session` to exactly one terminal state and reports
-          exactly one stop reason.
+          A paused `Run` has no terminal stop. Its continuation retains the same
+          run identity; on completion it reports one terminal stop reason.
       - id: run-no-replay-after-first-chunk
         statement: >
           Once a `Turn` has streamed its first chunk, the `Run` never retries or
@@ -864,9 +869,10 @@ entities:
       `Session` from its snapshot plus the `EventLog`.
     relationships:
       - entity: Run
-        cardinality: "1:n"
+        cardinality: "n:n"
         ownership: referenced
         role: executes
+        note: A paused run can continue in another process with the same run identity.
       - entity: SessionLease
         cardinality: "1:n"
         ownership: referenced
@@ -1110,10 +1116,10 @@ scenarios:
     actors: [Operator, Client]
     steps:
       - "A `Session` is parked on a `PermissionAsk` when the process dies; the `EventLog` holds every `Event` up to that point."
-      - "`Operator` restarts the harness; a new `Process` recovers the `Session` to idle before reuse, preserving cumulative usage."
-      - "`Client` approves the pending ask; the `Run` re-enters the loop at the ask and the pending `ToolCall` executes exactly once."
+      - "`Operator` restarts the harness; a new `Process` restores the awaiting `Session`, preserving its incarnation, run identity and cumulative usage."
+      - "`Client` approves the pending ask; the same logical `Run` continues at the ask and the pending `ToolCall` executes exactly once."
     invariants_touched:
-      [session-recover-before-reuse, event-log-records-terminal-tail, ask-suspends-run-until-resolved, session-usage-survives-restart, rehydrate-tool-exactly-once]
+      [session-incarnation-persists, run-one-terminal-stop, event-log-records-terminal-tail, ask-suspends-run-until-resolved, session-usage-survives-restart, rehydrate-tool-exactly-once]
 
   - name: A rehydrated session does not re-ask a previously granted tool
     actors: [Operator, Client]

docs/drafts/README.md

@@ -5,8 +5,8 @@ rely on them for how Mecatl works.
 
 | File | Author | Summary | Decide by (keep, move to an issue, or delete) |
 |---|---|---|---|
-| [agent-identity-model.md](agent-identity-model.md) | Juan Antonio Osorio | Strawman for agent identity: Mecatl as its own SPIFFE trust domain with JWT delegation chains. | **2026-11-06** |
-| [agent-identity-outbound.md](agent-identity-outbound.md) | Juan Antonio Osorio | Part 2 of the identity model: how the harness reaches tools and gateways on the outbound hop. | **2026-11-06** |
+| [agent-identity/README.md](agent-identity/README.md) | Juan Antonio Osorio | Proposed broker-centered agent identity, authority, audit, and credential lifecycle. | **2026-11-06** |
+| [agent-identity-outbound.md](agent-identity-outbound.md) | Juan Antonio Osorio | Historical companion to the former identity model: how the harness reaches tools and gateways on the outbound hop. | **2026-11-06** |
 | [cloud-native-harness-kit.md](cloud-native-harness-kit.md) | Juan Antonio Osorio | Positioning definition of the cloud-native harness kit and where its responsibility ends. | **2026-11-06** |
 | [cloud-native-harness-systems.md](cloud-native-harness-systems.md) | Joe Beda | Speculative scoping of open questions for cloud-native harness systems. | **2026-11-06** |
 | [scoped-resource-grants.md](scoped-resource-grants.md) | Joe Beda | Strawman for short-lived, attenuable grants and direct tool-to-service data paths. | **2026-11-06** |