# HITL-004 evidence pack — composed V1 human authority

## Work-package charter

- **Task ID:** `HITL-004`
- **Owner:** Oshun BFF, Agentic Studio, creative-autonomy, Lilith, Yemaya, and
  Studio Authoring maintainers; implementation owner: Codex
- **Accountable product:** V1 Oshun autonomous-content platform
- **Priority:** P0
- **Target milestone:** 2026-07-15 SOTA gap-closure program
- **Risk tier:** Critical interruption, delegated authority, provenance,
  release-placement, and learning integrity risk
- **Dependencies:** RUN-001 common run protocol, RUN-002 durable snapshots,
  RUN-005 approval lifecycle, and HITL-001 through HITL-003
- **Affected runtime:** V1 AgentRun lifecycle BFF, V1 creative-autonomy plane,
  and shared authority/provenance contracts
- **Rollback strategy:** Revert the source commits. Legacy AgentRun and autonomy
  snapshots remain readable because every new authority/authoring field has a
  migration default or is optional at the durable snapshot boundary.
- **Evidence-pack location:** This file

## Agentic Studio controls and the common run

`AgentRunLifecycleStore.control` now invokes the existing Agentic Studio
`pause`, `resume`, `cancel`, `kill`, `fork`, `retryWithChanges`, and
`operatorStep` functions. It does not reproduce their state machines. The BFF
validates typed command bodies and non-empty rationale, preserves owner and
same-tenant operator authority, requires operator authority for kill and
operator-step, and invokes the existing dashboard authorization check for
operator pause/kill.

Every accepted control appends its real `RunControlAuditEvent` to the same
durable `StoredRun` as the product envelope. The new
`adaptAgenticStudioEnvelopeToCommonRun` adapter derives a stable RUN-001
identity, common steps, measurements, artifacts, releases, and intervention
history from that record. Fork creates a separately stored child envelope and
common run whose canonical parent is the source common run. Operators can read
the same-tenant common state they govern; unrelated customers receive 404.

Focused HTTP coverage exercises all seven named controls, including retry step
overrides and operator-only step-through, and proves the common intervention
sequence rather than only checking the product envelope.

## Scoped Lilith override authority

The BFF delegates every override decision to the existing
`evaluateLilithOperatorOverride` implementation. Actor, tenant, and elevated
authorization grant identity are derived from and matched to the authenticated
operator. The request retains surface, policy check, target decision, tenant,
optional user/session, start/expiry, authorization expiry, outcome, and
rationale scope.

Allowed audit records are stored durably and projected as common `override`
interventions. Active reads exclude not-yet-occurred, expired, and explicitly
revoked records. Revocation is same-tenant/operator gated, retains the original
audit hash, appends a durable revocation record, and projects a reversed common
intervention. All prior uses remain in recurrence history; the third matching
override within Lilith's configured window requires review and routes to the
`lilith-policy-review-board` even if an earlier use is later revoked.

## Yemaya emergency stop, takeover, and checkpoint handback

`HumanOverrideSystem` now has a JSON-safe snapshot/restore boundary, so its
overrides, checkpoints, audit trail, emergency flag, pause flag, and takeover
owner live inside the durable AgentRun record. A checkpoint captures the exact
AgentRun envelope and common run. Emergency stop checkpoints pre-stop state and
then invokes the same Agentic pause control; takeover pauses first and records
the accountable takeover owner and checkpoint.

Handback requires an active override, verifies the checkpoint checksum, revokes
the override with actor/rationale audit, asks Yemaya to permit resume, and only
then invokes Agentic resume. Route tests prove both takeover and emergency-stop
checkpoint/handback sequences return the run to `running`. A fresh store
restores Yemaya checkpoints alongside the common control and Lilith histories
and can resume the restored paused run.

## Studio Authoring bound to autonomous artifacts

The autonomy plane now owns a durable `AutonomousAuthoringStore`. Opening a
draft binds one real review-queue item and target plan node to its RUN-001
artifact and initializes the HITL-003 lifecycle/transaction record.
Authenticated operator routes expose structured blocks, lock-aware Lamport
autosave, named checkpoints, three-way branches, inline comments, checklist
signoff, and the real Studio Authoring editorial lifecycle. Zod validates the
recursive block, document, checklist, comment, and lifecycle bodies at the HTTP
boundary.

The store invokes the existing Studio Authoring primitives for autosave,
version/activity history, checkpoints, branch merge, signoff, authoring
findings, and editorial transitions. The complete workspace—including common
run, common lifecycle, intervention journal, and head sequence—is included in
the autonomy plane's durable snapshot and proven across a JSON round-trip
restart.

Mixed human/agent lineage signing resolves from `OSHUN_HITL_LINEAGE_SIGNING_KEY`
and optional `OSHUN_HITL_LINEAGE_SIGNER_KEY_ID`. Keys shorter than 32 bytes are
treated as unconfigured. Replacement fails closed when the signing key or judge
panel is absent.

## Exact human-replacement path

| Required path | Evidence of equality with agent output                                                                                                                                                                                                             |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Provenance    | The merged branch executes HITL-003 `merge-human-branch`, parent-links the replacement, records the structured edit diff and branch coordinates, invalidates prior authorities, and emits a verifiable HMAC-SHA256 `mixed` lineage attestation.    |
| Quality       | The replacement invokes the same V1 `evaluateCompellingness` judge panel, learner calibration, original category bar, and `publishGate`; the exact pending common gate refs are then resolved from that panel result through `record-gate-result`. |
| Release       | `ReviewQueueStore.applyHumanReplacement` puts the replacement back into its existing `human-approval`, `review-window`, or autonomous approval path; a failed gate parks it. No manual bypass state exists.                                        |
| Placement     | The original `publicationRef` is retained, placement receipts are invalidated in the common transaction, and the editorial publisher runs `published -> updated -> published` under the same gates at the same artifact ID.                        |
| Learning      | `PreferenceLearner.recordEdit` receives the original agent output, human replacement, original machine score, category, and angle; the integration test proves the category observation count increments.                                          |

The HTTP integration test creates and autosaves a draft, checkpoints and edits a
branch, opens a comment, signs the checklist, advances through review/approval,
replaces a published autonomous item, verifies the mixed signature and gate
rerun, checks placement invalidation/identity, observes learning, and restores
the entire result into a fresh plane.

## Authorization and recovery matrix

| Scenario                    | Enforced result                                                                                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Non-owner customer          | Cannot observe or control another customer's run or authoring authority.                                                                                       |
| Same-tenant operator        | Can perform governed controls and read common/override state needed for oversight.                                                                             |
| Customer kill/operator-step | Rejected with 403 before an Agentic control is invoked.                                                                                                        |
| Short/missing lineage key   | Human branch replacement fails closed with 503.                                                                                                                |
| Missing judge panel         | Human replacement fails closed with 503 rather than bypassing quality.                                                                                         |
| Expired/revoked override    | Excluded from active authority while its immutable use audit remains.                                                                                          |
| Recurring override          | Third matching use requires Lilith policy review.                                                                                                              |
| Invalid checkpoint          | Yemaya handback fails before Agentic resume.                                                                                                                   |
| Restart                     | Common controls, Lilith audit/revocation, Yemaya checkpoints, authoring state, transactional lineage, review queue, and learner state survive durable restore. |
| Re-publication              | Same placement identity advances through `updated` and back to `published`; it is not duplicated.                                                              |

## Automated verification

- V1 AgentRun lifecycle HTTP integration: **8/8** passing, including every named
  Agentic control, owner/operator denial boundaries, Lilith recurrence and
  revocation, Yemaya takeover, emergency stop, checkpoint, and handback.
- AgentRun store and restart coverage: **6/6** passing, including actionable
  restoration of common controls, Lilith authority, and Yemaya checkpoints.
- Autonomous authoring/replacement HTTP integration: **7/7** passing.
- BFF autonomy binding and publisher coverage: **28/28** passing; bound-plane
  restart/end-to-end coverage: **6/6** passing.
- Agentic Studio run regression: **45/45** across **5/5** files.
- Creative-autonomy regression: **255/255** across **17/17** files.
- Studio Authoring regression: **138/138** across **6/6** files.
- Yemaya human-override regression: **19/19**; Lilith operator-override
  governance regression: **8/8**.
- RUN-001/HITL-003 affected contracts: **35/35** across adapter conformance, run
  model, and transactional intervention.
- BFF OpenAPI/runtime drift: **1/1** passing.
- Repository-standard BFF baseline-ratcheted typecheck: zero new app-owned
  errors with a zero-error baseline. This gate intentionally filters unrelated
  transitive workspace diagnostics, per `tools/typecheck/ratchet.mjs`.
- Contracts, Agentic Studio, creative-autonomy, and Yemaya production/spec
  TypeScript checks: zero errors.
- Changed-source ESLint: zero errors and zero warnings; BFF production build:
  successful; `git diff --check`: successful.

## Artifact identity

| Artifact                                                              | SHA-256                                                            |
| --------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `apps/oshun/bff/src/agentic/run-lifecycle-store.ts`                   | `3023656c2c3aacd5c3e87c4bff2a30decfe62fc123d4ec71ecafbdad29715f86` |
| `apps/oshun/bff/src/routes/agentic-runs-lifecycle.ts`                 | `71182e06cd095206d6ef22c32e41a3f14cb54beb63a0ba321e03b96318f62754` |
| `apps/oshun/bff/src/agentic/autonomous-authoring-store.ts`            | `558531aa43b72b977f9baf6715d7ca549caec2ec1587b852f14c7e1d575ba0da` |
| `apps/oshun/bff/src/agentic/autonomy-route.ts`                        | `00f9d61769da992817d814fad1d3674549cfbd37403f9e7302383ea113447418` |
| `apps/oshun/bff/src/agentic/autonomy-bindings/editorial-publisher.ts` | `e7607c16d6de60ff1d556edf3d26ad4cae6edba36c596b2448758427fe70b265` |
| `libs/oshun/agentic-studio/src/runs/common-run-adapter.ts`            | `e57a54d8b6670b38886adf9f4a9e50142a08fd82f40e70a669c119de6dbe3fbe` |
| `libs/contracts/src/run-protocol/transactional-intervention.ts`       | `2c57c96b1889b823ff5ce39d3c15a8e96652bc0b5f15abe9002702b322871724` |
| `libs/oshun/creative-autonomy/src/review/review-queue.ts`             | `21c88e2dbfb74855c226fcc3420520bbd646e195493ab23ccf4120435ce23bb9` |
| `libs/yemaya/human-override/src/override-system.ts`                   | `5a9f4569b32b71b32fca71a38f8423220b83191d947aa1b3d87cd09f6eba1c55` |

## Resource-safe verification

The final probe reported 15 GiB RAM, 31 GiB swap, approximately 13 GiB available
RAM, and 38 GiB free disk. Detached stale Vitest discovery processes were
identified and terminated before verification continued. All expensive gates
then ran sequentially with one Vitest worker. The BFF ratchet used its
documented 7 GiB heap and completed without host memory pressure. No broad Nx,
Next, Expo, Tauri, or workspace-wide build sweep was attempted.

## Scope and negative proof

- This package changes authenticated backend/control behavior, not a rendered
  web, PWA, admin, mobile, or Unreal UI. The mandatory frontend skill,
  Playwright UI automation, mobile automation, and Unreal validation are
  therefore inapplicable to HITL-004.
- HMAC lineage proves possession of the configured named secret; it is not a
  public-key C2PA signature or proof of an externally deployed key service.
- Provider-backed content generation and external production publication were
  not required to prove authority composition; tests use the real local state
  machines and scripted boundary judges/providers where external calls would be
  non-deterministic.
- HITL-005 owns measured human-authority SLOs and the 100% operational drill
  release gate; this package does not claim those measurements.

## Publication identity

- **Composed authority source commit:**
  `85f4f126f0c79a4e811e42813484aa9e780ca29d`
- **Emergency binding proof commit:** `432ef426e4a27e890bb8d3826ae7ce6e502b99ea`
- **Closure evidence commit:** `f35f30e6755351477bb26a1b65a1e1d6b192e1c9`
