approval-md 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "approval-md",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Human approval for agent actions. CLI runtime for the approval.md convention (pre-release).",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "schema",
     "docs/adapter-api.md",
     "docs/cli-reference.md",
+    "docs/README-extended.md",
     "SPEC.md",
     "README.md",
     "LICENSE",
@@ -57,5 +58,6 @@
     "ajv-formats": "3.0.1",
     "better-sqlite3": "12.11.1",
     "yaml": "2.9.0"
-  }
+  },
+  "gitHead": "5f9b9c3da2b0b220b344590d6d5319d27edf3b61"
 }

package/schema/event.schema.json

@@ -54,6 +54,7 @@
         "audit.decision_refused",
         "audit.gesture_refused",
         "audit.question_preempted",
+        "audit.lock_reclaimed",
         "reconciliation.required",
         "reconciliation.satisfied",
         "payload.pruned",
@@ -64,7 +65,7 @@
         "gate.path.signed_off",
         "log.checkpoint"
       ],
-      "description": "SPEC.md §8 'Event types (v0.1)': the closed set of thirty-four event types. Closed by design — an unrecognized type fails closed at the write boundary rather than entering the log unvalidated. `payload.pruned` (APRV-38) is the first addition after the v0.1 draft set of sixteen, `approval.withdrawn` (APRV-106) the second, `execution.indeterminate` with `execution.reconciled` (APRV-120) the third and fourth, `reconciliation.required` / `reconciliation.satisfied` (APRV-127) the fifth and sixth, `policy.proposed` / `policy.declined` (APRV-109) the seventh and eighth, `audit.dark_session` (APRV-192) the ninth, `gate.opened` / `gate.closed` / `gate.bypassed` (APRV-214) the tenth, eleventh and twelfth, `log.checkpoint` (APRV-220) the thirteenth, `audit.decision_refused` (APRV-235) the fourteenth, `gate.organ.attested` (APRV-272) the fifteenth, `gate.path.signed_off` (APRV-338) the sixteenth, `audit.gesture_refused` (APRV-355) the seventeenth, and `audit.question_preempted` (APRV-378) the eighteenth: a reader of a v0.1 log may encounter any of them, and a verifier written against the draft enum must be updated to accept them all."
+      "description": "SPEC.md §8 'Event types (v0.1)': the closed set of thirty-five event types. Closed by design — an unrecognized type fails closed at the write boundary rather than entering the log unvalidated. `payload.pruned` (APRV-38) is the first addition after the v0.1 draft set of sixteen, `approval.withdrawn` (APRV-106) the second, `execution.indeterminate` with `execution.reconciled` (APRV-120) the third and fourth, `reconciliation.required` / `reconciliation.satisfied` (APRV-127) the fifth and sixth, `policy.proposed` / `policy.declined` (APRV-109) the seventh and eighth, `audit.dark_session` (APRV-192) the ninth, `gate.opened` / `gate.closed` / `gate.bypassed` (APRV-214) the tenth, eleventh and twelfth, `log.checkpoint` (APRV-220) the thirteenth, `audit.decision_refused` (APRV-235) the fourteenth, `gate.organ.attested` (APRV-272) the fifteenth, `gate.path.signed_off` (APRV-338) the sixteenth, `audit.gesture_refused` (APRV-355) the seventeenth, `audit.question_preempted` (APRV-378) the eighteenth, and `audit.lock_reclaimed` (APRV-479) the nineteenth: a reader of a v0.1 log may encounter any of them, and a verifier written against the draft enum must be updated to accept them all."
     },
     "actor": {
       "type": "string",
@@ -92,6 +93,13 @@
         }
       ]
     },
+    "daemon": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z0-9][a-z0-9._-]*$",
+      "description": "SPEC.md §8 (amended, APRV-383): WHICH daemon instance appended this record. Present exactly on the records a daemon wrote, so a tenant whose daemon is hosted by another party can open their own log and tell which host process acted on their behalf — before this field every daemon-written record carried the same generic `system:daemon` actor and nothing else. The value is either the id declared in the daemon's launch environment (`APPROVAL_DAEMON_ID`) or `daemon-` followed by the eight hex digits of the instance id `approval doctor` prints as its `keychain-scope` suffix, so it is stable across restarts on one machine and keystore without anything being stored.\n\nOPTIONAL and additive: every record written before the field existed still validates and still verifies, and the ABSENCE of the field is absence — it is never read as a claim that no daemon wrote the record, because until this task no daemon could say.\n\nSELF-REPORTED, and bounded by SPEC.md §11.1 invariant 4 in the only way a self-reported field may be: a policy MAY list the ids permitted to write (`daemons` in `policy.schema.json`), an id the list does not name is REFUSED at the write boundary (`daemon-not-allowed`), and an id the list DOES name gains nothing at all — no verdict, autonomy, budget, floor, sampling draw, token or TTL reads this field or that list. Its SHAPE is constrained here for the reason `payload.harness_version`'s is: the value comes from a launch environment and is being written into an append-only log, so a banner, a path, a newline or a shell fragment cannot arrive through it, and two ids differing only in case would be two ids nobody can tell apart on a phone."
+    },
     "task": {
       "type": "string",
       "minLength": 1,
@@ -118,9 +126,10 @@
             "cursor",
             "codex",
             "grok",
-            "muse"
+            "muse",
+            "hermes"
           ],
-          "description": "SPEC.md §10.1 (amended, APRV-227): which harness hook wrote this record. A closed set, extended only by a task that adds the case, because it is the discriminator a reader scopes `harness_version` by: one log holds the records of every harness that ever wrote to it, and a version with no binary named beside it is a string nobody can compare against anything. OPTIONAL and additive — every record written before the field existed still validates and still verifies, and the two fields travel together or not at all. APRV-358 added `grok`, which APRV-243 shipped an adapter for and never added here: a Grok session's manual-class registration failed validation at the write boundary, so the request never reached a human. Closed does not mean hand-maintained any more. This list is pinned set-equal to `HARNESS_KINDS` in `src/core/harness-version.ts` by `tests/harness-enum.test.ts`, along with every other place a harness name is enumerated, so the next adapter cannot land with the enum left behind."
+          "description": "SPEC.md §10.1 (amended, APRV-227): which harness hook wrote this record. A closed set, extended only by a task that adds the case, because it is the discriminator a reader scopes `harness_version` by: one log holds the records of every harness that ever wrote to it, and a version with no binary named beside it is a string nobody can compare against anything. OPTIONAL and additive — every record written before the field existed still validates and still verifies, and the two fields travel together or not at all. APRV-358 added `grok`, which APRV-243 shipped an adapter for and never added here: a Grok session's manual-class registration failed validation at the write boundary, so the request never reached a human. Closed does not mean hand-maintained any more. This list is pinned set-equal to `HARNESS_KINDS` in `src/core/harness-version.ts` by `tests/harness-enum.test.ts`, along with every other place a harness name is enumerated, so the next adapter cannot land with the enum left behind. APRV-398 added `hermes`, the Hermes Agent adapter, through that pinning rather than after it."
         },
         "harness_version": {
           "type": "string",
@@ -232,6 +241,156 @@
         { "type": "number", "minimum": 0 }
       ],
       "description": "The read form: the decimal string, or the pre-APRV-121 JSON number. The log is append-only, so a verifier must accept every shape the write boundary ever admitted. Used only in historical validation mode."
+    },
+    "audit_reviewed_record": {
+      "$comment": "SPEC.md §5.2/§8 (amended, APRV-481): the write-boundary form of an `audit.reviewed` record. A review must name the sample it answers (`subject_seq`), the execution that sample named (`sampled_subject_hash`), and what it concluded (`verdict`), because the follower and the research models read reviews as approvals and a review that does not say which action it judged, or what it concluded, is one nobody can count. `validate(..., { mode: \"historical\" })` replaces this definition with `audit_reviewed_record_historical`, so a review written before APRV-481 still validates and verifies unchanged.",
+      "type": "object",
+      "properties": {
+        "actor": {
+          "type": "string",
+          "pattern": "^human:"
+        },
+        "payload": {
+          "type": "object",
+          "properties": {
+            "subject_seq": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "SPEC.md §5.2/§8 (amended, APRV-481): the `seq` of the `audit.sampled` record this review answers. Not the execution's seq: the sample is what was offered for review, and the execution it names is joined through `sampled_subject_hash`. REQUIRED on new records."
+            },
+            "sampled_subject_hash": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$",
+              "description": "SPEC.md §5.2/§8 (amended, APRV-481): the `hash` of the `execution.started` record the sample named (the sample's own `subject_hash`), copied by the runtime from the verified log and never supplied by a caller. The join key from a review to the execution it judged. REQUIRED on new records."
+            },
+            "verdict": {
+              "type": "string",
+              "enum": [
+                "ok",
+                "denied"
+              ],
+              "description": "SPEC.md §5.2 (amended, APRV-127): what the reviewer concluded. `ok`: the action should have happened — the spelling the v0.1 fixtures already used, kept rather than renamed, because a second word for a verdict already in logs is the drift this vocabulary exists to avoid. `denied`: it should not have, and the runtime appends a `reconciliation.required` naming the obligation the denial creates. REQUIRED on every record written since APRV-481, because a review that does not say what it concluded cannot count as anybody's approval; a review written before then may carry none and reads as the observation it was (the historical form of this definition), which is why the ABSENCE of this field on an old record is never read as a denial."
+            },
+            "verdict_source": {
+              "type": "string",
+              "const": "explicit",
+              "description": "SPEC.md §5.2 (amended, PR #614 refutation F5): how the verdict was given. `explicit` is the only value: since APRV-482 a verdict is said by the reviewer (`--ok`/`--deny`, a card's OK or second Deny) and never defaulted. A review written before then may carry `verdict: \"ok\"` that the runtime filled in for a grade-only tap or a bare terminal review, and nothing else in the record tells the two apart, so this field is the discriminator a follower reads: present means explicit, absent (on an old record) means the verdict may have been defaulted. REQUIRED on new records."
+            },
+            "payload_hash": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$",
+              "description": "SPEC.md §5.2/§10.3 (amended, APRV-481): the SHA-256/JCS binding of the bytes the sampled execution ran, present ONLY when the surface that collected this review rendered those bytes whole in front of the reviewer (a review card's `bytes` view). Absent when the reviewer saw a hash, saw nothing, or reviewed at a terminal, so the field never claims more than the reviewer read. The runtime checks it equals the execution's recorded binding before appending."
+            },
+            "reaction": {
+              "type": "string",
+              "enum": [
+                "disliked",
+                "indifferent",
+                "liked",
+                "loved"
+              ],
+              "description": "SPEC.md §5.2 (amended, APRV-237): what the human thought of the action, graded. `verdict` remains the ENFORCEMENT field and is the only one any enforcement path reads; `reaction` is guidance travelling the human-to-agent direction and no routing, matching, sampling, budgeting or token decision consults it (SPEC.md §11.1 invariant 10). Optional and additive: a review written before the field existed still validates and still verifies, and the ABSENCE of the field is absence — it is never read as `indifferent`, which is a thing a person had to actually say. The four words are the whole vocabulary; a fifth is refused here rather than left to accumulate synonyms across surfaces."
+            }
+          },
+          "required": [
+            "subject_seq",
+            "sampled_subject_hash",
+            "verdict",
+            "verdict_source"
+          ]
+        }
+      },
+      "required": [
+        "actor",
+        "payload"
+      ]
+    },
+    "audit_reviewed_record_historical": {
+      "$comment": "The read form of `audit_reviewed_record` (APRV-481): every constraint a review has carried since APRV-56 and APRV-237, without the three fields APRV-481 made required or the `verdict_source` PR #614's F5 fix made required. The log is append-only, so a verifier must accept every review the write boundary ever admitted. Used only in historical validation.",
+      "type": "object",
+      "properties": {
+        "actor": {
+          "type": "string",
+          "pattern": "^human:"
+        },
+        "payload": {
+          "type": "object",
+          "properties": {
+            "subject_seq": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "sampled_subject_hash": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            },
+            "verdict": {
+              "type": "string",
+              "enum": [
+                "ok",
+                "denied"
+              ]
+            },
+            "verdict_source": {
+              "type": "string",
+              "const": "explicit"
+            },
+            "payload_hash": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            },
+            "reaction": {
+              "type": "string",
+              "enum": [
+                "disliked",
+                "indifferent",
+                "liked",
+                "loved"
+              ]
+            }
+          }
+        }
+      },
+      "required": [
+        "actor"
+      ]
+    },
+    "audit_sampled_record": {
+      "$comment": "SPEC.md §5.2/§8 (amended, PR #614 refutation F2, recheck NF-3): the write-boundary form of an `audit.sampled` record. A sample pins the attested policy its execution ran under (`policy_sha256`: the latest attestation before the sampled `execution.started`), because a retrospective review is held to the approvers roster of THAT policy: read from whatever policy is in force at review or sampling time, a re-attestation after the run could re-roster the review or leave the sample with no roster at all. `validate(..., { mode: \"historical\" })` replaces this definition with `audit_sampled_record_historical`, so a sample written before the field existed still validates and verifies, and reads as not pinned.",
+      "type": "object",
+      "properties": {
+        "payload": {
+          "type": "object",
+          "properties": {
+            "policy_sha256": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$",
+              "description": "SPEC.md §5.2/§8 (amended, PR #614 refutation F2): the SHA-256 of the policy bytes the latest attestation named when this sample was taken, copied by the runtime from the verified log. A review of this sample reads its roster only from bytes that hash to this value. REQUIRED on new records."
+            }
+          },
+          "required": [
+            "policy_sha256"
+          ]
+        }
+      },
+      "required": [
+        "payload"
+      ]
+    },
+    "audit_sampled_record_historical": {
+      "$comment": "The read form of `audit_sampled_record` (PR #614 refutation F2): the same field shape without the requirement, so a sample written before samples pinned their policy still verifies. Used only in historical validation.",
+      "type": "object",
+      "properties": {
+        "payload": {
+          "type": "object",
+          "properties": {
+            "policy_sha256": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            }
+          }
+        }
+      }
     }
   },
   "allOf": [
@@ -314,39 +473,24 @@
         ]
       },
       "then": {
+        "$ref": "#/$defs/audit_reviewed_record"
+      }
+    },
+    {
+      "$comment": "SPEC.md §5.2/§8 (amended, PR #614 refutation F2): a sample names the attested policy it was taken under, so its review can be held to that policy's roster.",
+      "if": {
         "type": "object",
         "properties": {
-          "actor": {
-            "type": "string",
-            "pattern": "^human:"
-          },
-          "payload": {
-            "type": "object",
-            "properties": {
-              "verdict": {
-                "type": "string",
-                "enum": [
-                  "ok",
-                  "denied"
-                ],
-                "description": "SPEC.md §5.2 (amended, APRV-127): what the reviewer concluded. `ok`: the action should have happened — the spelling the v0.1 fixtures already used, kept rather than renamed, because a second word for a verdict already in logs is the drift this vocabulary exists to avoid. `denied`: it should not have, and the runtime appends a `reconciliation.required` naming the obligation the denial creates. Optional and additive — a review written before the split carries none and reads as the observation it was, which is why the ABSENCE of this field is never read as a denial."
-              },
-              "reaction": {
-                "type": "string",
-                "enum": [
-                  "disliked",
-                  "indifferent",
-                  "liked",
-                  "loved"
-                ],
-                "description": "SPEC.md §5.2 (amended, APRV-237): what the human thought of the action, graded. `verdict` remains the ENFORCEMENT field and is the only one any enforcement path reads; `reaction` is guidance travelling the human-to-agent direction and no routing, matching, sampling, budgeting or token decision consults it (SPEC.md §11.1 invariant 10). Optional and additive: a review written before the field existed still validates and still verifies, and the ABSENCE of the field is absence — it is never read as `indifferent`, which is a thing a person had to actually say. The four words are the whole vocabulary; a fifth is refused here rather than left to accumulate synonyms across surfaces."
-              }
-            }
+          "event": {
+            "const": "audit.sampled"
           }
         },
         "required": [
-          "actor"
+          "event"
         ]
+      },
+      "then": {
+        "$ref": "#/$defs/audit_sampled_record"
       }
     },
     {
@@ -833,6 +977,36 @@
         }
       }
     },
+    {
+      "$comment": "SPEC.md §8 (amended, APRV-447, pending sign-off): a harness `execution.started` carries `policy_sha256`, the SHA-256 of the attested policy the write boundary re-checked the action's class against when it recorded the start (on the hook route the verdict was drawn from the hook's own earlier read, so a re-attest landing between the two leaves the stamp naming the policy in force at the append). Before it, a policy-authorized start (autonomous, supervised, an unselected supervised-live draw) named no policy at all, and a reader had to reconstruct the rules in force from the latest `policy.updated` before the record's seq; a granted start could reach its policy through `grant_seq` and carries the stamp too, written by the same code. The runtime assigns the value at the write boundary from its own attestation check, exactly as it assigns `policy_sha256` on `approval.requested` and `ts` on every gate-typed event: no caller parameter carries it, and a caller-supplied value of the same name is ignored. No verdict, budget, draw or refusal reads it back, so §11.1 invariant 4 is untouched. It is covered by the record hash like every other payload field. OPTIONAL and additive: every record written before the field existed still validates and still verifies, an `execution.started` written by any other path records none, and only the SHAPE is constrained here, a 64-character lowercase hex digest. Whether the hash names an attestation the log actually carries is not expressible in a schema that sees one record. The field name is a stable contract: downstream followers of the log use it to join a start to the rules it ran under.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "execution.started"
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "policy_sha256": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$",
+                "description": "SPEC.md §8 (amended, APRV-447): SHA-256 (lowercase hex) of the attested policy file's exact bytes the write boundary re-checked this start's class against, stamped by the runtime at the write boundary. Never a caller's parameter and never an input to a verdict.",
+                "examples": ["5f1c0de9a3b7e2d4c6f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e"]
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "$comment": "SPEC.md §10.3 (amended, APRV-38): a decision collected as part of a batch gesture carries the batch's channel delivery id as a first-class payload field. Optional — a unit decision has no batch — and constrained only when present, so the field can never arrive as an empty string or a number that audit would have to guess at.",
       "if": {
@@ -1126,6 +1300,25 @@
                 "type": "string",
                 "pattern": "^[a-f0-9]{64}$",
                 "description": "SPEC.md §9/§10.3 (APRV-119): SHA-256 (lowercase hex) over the UTF-8 text of the canonical rendering of this request's payload, as produced by the versioned deterministic renderer named inside that text."
+              },
+              "harness_cap_ms": {
+                "type": "integer",
+                "minimum": 60001,
+                "maximum": 86400000,
+                "description": "SPEC.md §6 (APRV-423): the ceiling, in milliseconds, that the harness running the requesting hook imposes on that hook's own process — Hermes caps a `pre_tool_call` entry at 300 s, Claude Code kills the hook at the `timeout` in its settings file. A BOUNDED INPUT and never a deadline of its own: the runtime judges the request against the SHORTER of this minus a fixed margin and the policy's `defaults.approval_ttl`, so a stated cap can only move the lapse EARLIER (§11.1 invariant 4). The minimum is HARNESS_CAP_MARGIN_MS + 1 (src/core/harness-wait.ts, 60 000 ms; tests/harness-cap-ttl.test.ts pins the two equal): a cap at or below the margin leaves a zero-length window, a question that lapses as it is asked, and the hook refuses such a configuration before it appends, so a record carrying one could only come from a caller that skipped the hook and is refused here. Above 24 h is a number no harness contract states."
+              }
+            },
+            "dependentSchemas": {
+              "harness_cap_ms": {
+                "$comment": "APRV-423. A record carrying a harness ceiling MUST also declare `execution: \"harness\"`. The ceiling shortens the window in which this request may be decided, and a request that mints an execution token would otherwise hold an authorization with a longer shelf life than the question that produced it. A schema sees one record, which is exactly enough to see both fields, so the pairing is refused at the write boundary rather than left to a caller's discipline.",
+                "properties": {
+                  "execution": {
+                    "const": "harness"
+                  }
+                },
+                "required": [
+                  "execution"
+                ]
               }
             }
           }
@@ -1988,6 +2181,196 @@
         }
       }
     },
+    {
+      "$comment": "SPEC.md §8 (proposed, APRV-479, pending sign-off): `<log>.lock` was taken over from a holder that is gone, and this is the first record under the lock that was taken. A `system:log` actor is this runtime's log writer, which proved the holder gone after waiting out its whole lock timeout: its process has exited in the writer's own pid namespace and boot (Linux: `kill(pid, 0)` answers ESRCH with `/proc/<pid>` absent or a zombie, or the pid names a process that started later; elsewhere the same host and boot and `kill(pid, 0)` answering ESRCH), or the lockfile names no holder and is older than the reclaim age. A `human:` actor is a person's `approval log unlock`, for a lock no writer can judge (another container or boot): the reason is then that person's assertion, not a proof. `core/log-lock.ts` states the rules.\n\nNo existing type carries it. The audit records before it are about a gesture on a request, a question answered elsewhere, or a sweep over activity; this is about the log's own lock and nothing else.\n\nAUDIT TIER, on the strict terms `audit.decision_refused` set: it grants nothing, mints no token, settles no request, charges no budget, is not sampled, and NO ENFORCEMENT PATH READS IT. Its `ts` is the write boundary's, like every audit record's.\n\nThe payload names the lockfile by its base name, the reason from a closed set, how long the lock had been held, and, when the lockfile carried a holder record, the holder's pid, kind and start of hold, strictly parsed: nothing else is taken from the file. A start of hold that is not plausible (before the log's last record by more than 24 hours, or after the taker's clock by more than 5 minutes) is recorded as null, with no age. The holder's host is deliberately not recorded: a log is often committed, and a machine name is not the log's business.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "audit.lock_reclaimed"
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "required": [
+          "actor",
+          "payload"
+        ],
+        "allOf": [
+          {
+            "$comment": "`age_ms` is required, and is absent exactly when `holder.created` is null: an implausible `created` is not recorded, and neither is the age derived from it (APRV-479 R3-7).",
+            "if": {
+              "type": "object",
+              "properties": {
+                "payload": {
+                  "type": "object",
+                  "properties": {
+                    "holder": {
+                      "type": "object",
+                      "properties": {
+                        "created": {
+                          "type": "null"
+                        }
+                      },
+                      "required": [
+                        "created"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "holder"
+                  ]
+                }
+              },
+              "required": [
+                "payload"
+              ]
+            },
+            "then": {
+              "type": "object",
+              "properties": {
+                "payload": {
+                  "type": "object",
+                  "not": {
+                    "properties": {
+                      "age_ms": {}
+                    },
+                    "required": [
+                      "age_ms"
+                    ]
+                  }
+                }
+              }
+            },
+            "else": {
+              "type": "object",
+              "properties": {
+                "payload": {
+                  "type": "object",
+                  "properties": {
+                    "age_ms": {}
+                  },
+                  "required": [
+                    "age_ms"
+                  ]
+                }
+              }
+            }
+          },
+          {
+            "$comment": "A person's assertion is never recorded as the writer's proof, nor the reverse: `operator-cleared` if and only if the actor is `human:`.",
+            "if": {
+              "type": "object",
+              "properties": {
+                "payload": {
+                  "type": "object",
+                  "properties": {
+                    "reason": {
+                      "const": "operator-cleared"
+                    }
+                  },
+                  "required": [
+                    "reason"
+                  ]
+                }
+              },
+              "required": [
+                "payload"
+              ]
+            },
+            "then": {
+              "type": "object",
+              "properties": {
+                "actor": {
+                  "type": "string",
+                  "pattern": "^human:"
+                }
+              }
+            },
+            "else": {
+              "type": "object",
+              "properties": {
+                "actor": {
+                  "type": "string",
+                  "pattern": "^system:"
+                }
+              }
+            }
+          }
+        ],
+        "properties": {
+          "actor": {
+            "type": "string",
+            "pattern": "^(system|human):",
+            "description": "`system:log`: the runtime's log writer, which proved the holder gone. `human:<id>`: the person who ran `approval log unlock`, and only with reason `operator-cleared`. An `agent:` actor is refused: no agent takes over the log's lock."
+          },
+          "payload": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "lockfile",
+              "reason"
+            ],
+            "properties": {
+              "lockfile": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[^/\\\\]+$",
+                "description": "The lockfile's base name (`events.jsonl.lock`), never a path."
+              },
+              "reason": {
+                "enum": [
+                  "holder-dead",
+                  "legacy-aged",
+                  "operator-cleared"
+                ],
+                "description": "Why the holder counts as gone. CLOSED, additive-only. `holder-dead`: the writer proved it: no process has the holder's pid in the writer's pid namespace and boot, or the pid names a later process. `legacy-aged`: the writer found the lockfile naming no holder and older than the reclaim age. `operator-cleared`: a person ran `approval log unlock` and asserted the holder gone, which is not a proof; it is the only reason a `human:` actor may carry, and a `system:` actor may never carry it."
+              },
+              "age_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "How long the lock had been held when it was taken over, in milliseconds, by the taker's clock: from the holder record's `created`, or from the lockfile's mtime when it had none. Required, except that it is absent exactly when `holder.created` is null (its `created` was implausible, so no age derived from it is recorded)."
+              },
+              "holder": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "pid",
+                  "op",
+                  "created"
+                ],
+                "description": "The holder record the lockfile carried, strictly parsed. Absent exactly when it carried none.",
+                "properties": {
+                  "pid": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "op": {
+                    "enum": [
+                      "append",
+                      "hold"
+                    ],
+                    "description": "`append`: one record. `hold`: a whole operation under the lock (`log sync`, `log advance`, an export, an unlock)."
+                  },
+                  "created": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "format": "date-time",
+                    "description": "When the holder took the lock, by its own clock. `null` when the value the lockfile carried was not plausible: earlier than the log's last record's `ts` minus 24 hours, or later than the taker's clock plus 5 minutes (a value the file chose, recorded as nothing)."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "$comment": "SPEC.md §5.2 (amended, APRV-214), 'The open window': a person opening the harness gate on themselves so the gate can be debugged from inside. The actor MUST be `^human:`, in the schema as well as in `core/gate-window.ts`, for the reason attestation refuses an agent: this is the one act that suspends the policy, and an agent able to author it could authorize its own next command. The window's state lives here and in no file, so what a reader derives is derived from a verified chain and nothing else. Expiry is `ts` plus `duration`, and a record claiming an `expires_at` beyond that reads as the shorter of the two: the field is a convenience for a human reading the log, never the authority.",
       "if": {

package/schema/fixtures/event/invalid/audit-lock-reclaimed-age-without-created.json

@@ -0,0 +1,19 @@
+{
+  "seq": 217,
+  "ts": "2026-10-05T07:41:12.408Z",
+  "event": "audit.lock_reclaimed",
+  "actor": "system:log",
+  "payload": {
+    "lockfile": "events.jsonl.lock",
+    "reason": "holder-dead",
+    "age_ms": 63958419351790,
+    "holder": {
+      "pid": 48213,
+      "op": "append",
+      "created": null
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",
+  "hash": "2e9b7c1a4d6f08213b5c7e9a0d2f416385a7c9e1b3d5f70921a3c5e7092b4d6f"
+}

package/schema/fixtures/event/invalid/audit-lock-reclaimed-agent-actor.json

@@ -0,0 +1,14 @@
+{
+  "seq": 214,
+  "ts": "2026-10-05T07:41:12.408Z",
+  "event": "audit.lock_reclaimed",
+  "actor": "agent:claude-code",
+  "payload": {
+    "lockfile": "events.jsonl.lock",
+    "reason": "holder-dead",
+    "age_ms": 734211
+  },
+  "alg": "sha256/jcs",
+  "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",
+  "hash": "2e9b7c1a4d6f08213b5c7e9a0d2f416385a7c9e1b3d5f70921a3c5e7092b4d6f"
+}

package/schema/fixtures/event/invalid/audit-lock-reclaimed-lockfile-path.json

@@ -0,0 +1,14 @@
+{
+  "seq": 214,
+  "ts": "2026-10-05T07:41:12.408Z",
+  "event": "audit.lock_reclaimed",
+  "actor": "system:log",
+  "payload": {
+    "lockfile": "/home/tenant/.approval/log/events.jsonl.lock",
+    "reason": "holder-dead",
+    "age_ms": 734211
+  },
+  "alg": "sha256/jcs",
+  "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",
+  "hash": "2e9b7c1a4d6f08213b5c7e9a0d2f416385a7c9e1b3d5f70921a3c5e7092b4d6f"
+}

package/schema/fixtures/event/invalid/audit-lock-reclaimed-operator-cleared-system-actor.json

@@ -0,0 +1,14 @@
+{
+  "seq": 216,
+  "ts": "2026-10-05T11:02:40.115Z",
+  "event": "audit.lock_reclaimed",
+  "actor": "system:log",
+  "payload": {
+    "lockfile": "events.jsonl.lock",
+    "reason": "operator-cleared",
+    "age_ms": 4021877
+  },
+  "alg": "sha256/jcs",
+  "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",
+  "hash": "2e9b7c1a4d6f08213b5c7e9a0d2f416385a7c9e1b3d5f70921a3c5e7092b4d6f"
+}

package/schema/fixtures/event/invalid/audit-lock-reclaimed-unknown-reason.json

@@ -0,0 +1,14 @@
+{
+  "seq": 214,
+  "ts": "2026-10-05T07:41:12.408Z",
+  "event": "audit.lock_reclaimed",
+  "actor": "system:log",
+  "payload": {
+    "lockfile": "events.jsonl.lock",
+    "reason": "holder-looked-old",
+    "age_ms": 734211
+  },
+  "alg": "sha256/jcs",
+  "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",
+  "hash": "2e9b7c1a4d6f08213b5c7e9a0d2f416385a7c9e1b3d5f70921a3c5e7092b4d6f"
+}

package/schema/fixtures/event/invalid/audit-lock-reclaimed-without-age.json

@@ -0,0 +1,13 @@
+{
+  "seq": 215,
+  "ts": "2026-10-05T07:41:12.408Z",
+  "event": "audit.lock_reclaimed",
+  "actor": "system:log",
+  "payload": {
+    "lockfile": "events.jsonl.lock",
+    "reason": "holder-dead"
+  },
+  "alg": "sha256/jcs",
+  "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",
+  "hash": "2e9b7c1a4d6f08213b5c7e9a0d2f416385a7c9e1b3d5f70921a3c5e7092b4d6f"
+}

package/schema/fixtures/event/invalid/audit-reviewed-agent-actor.json

@@ -7,7 +7,12 @@
   "actor": "agent:chaser",
   "channel": "cli",
   "payload": {
-    "verdict": "ok"
+    "subject_seq": 15,
+    "subject_event": "audit.sampled",
+    "reviewed": true,
+    "sampled_subject_hash": "6c1d3f0b9a8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a392817060504",
+    "verdict": "ok",
+    "verdict_source": "explicit"
   },
   "alg": "sha256/jcs",
   "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",