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