Eve library

HITL-001 evidence pack — human-usable V1 autonomy operator console

Evidence

Revision 1

On this page

Work-package charter#

  • Task ID: HITL-001
  • Owner: Oshun V1 autonomy and operator-surface 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 human-authority, stale-approval, destructive-release, concurrent-edit, and inaccessible-control risk
  • Dependencies: The bound V1 creative-autonomy plane and its authenticated BFF routes; RUN-004 creative-cycle adapter; RUN-005 common lifecycle vocabulary
  • Affected runtime and UI: /v1/agentic/autonomy/*, editorial lifecycle and durable plane snapshot, /operator/autonomy, shared web API errors, operator surface index, and focused Playwright coverage
  • Rollout strategy: Ship the new operator route beside the existing read-only operator index. Keep the autonomy plane fail-closed when its LLM is unconfigured while leaving authenticated observation and steering available.
  • Rollback strategy: Revert the web route, BFF response/action extensions, post-publication lifecycle methods, run adapter mappings, and tests together. Existing durable snapshots remain readable because publisher records are an optional backward-compatible field.
  • Evidence-pack location: This file

Shipped operator surface#

/operator/autonomy is a client-operated, authenticated route inside the existing Oshun operator shell. Its visual thesis is a calm editorial control ledger: a paper/ink/terracotta queue-to-inspector workspace that keeps authority, evidence, and outcome state above decoration. The console waits for the shell's access token before its first request, sends the bearer on every BFF call, and does not contain fixture data or a fixture/live mode switch.

The overview loads the plane status, cycle history, review queue, standing direction, and learner suggestions in parallel. The inspector exposes seven explicit views—run, artifact, provenance, source, budget, gate, and interventions—while the queue is filterable by the five operational outcomes: held, blocked, failed, review-window, and released. The status band names the configured cycle budget, spent units, active work, queued work, steering version, and whether the director is configured.

Human authority and real endpoint binding#

Operator control BFF operation Concurrency/authority behavior
Approve POST review-queue/:itemId/action with approve Sends expected history length; stale writes return 409 and refresh the item.
Reject Same endpoint with reject Confirmation captures a decision note.
Veto Same endpoint with veto Destructive copy names the stopped release window.
Tweak Same endpoint with request-tweak Applies direction to the canonical review item.
Node tweak Same action plus nodeAddress Preserves a plan-node address in the intervention history.
Standing direction PUT steering Sends expectedVersion; a concurrent write returns the authoritative direction.
Feedback POST feedback Records one 1–5 rating per item/rater and refreshes learner state.
Withdraw Review action plus publisher withdraw Requires a reason and executes the real published -> takedown editorial transition first.
Roll back Review action plus publisher rollback Requires a reason and executes the real published -> deprecated reversible transition first.
Run cycle POST cycles/run A separate confirmation warns that provider usage may be billable.

Withdrawal and rollback are separate terminal review states and map through the RUN-004 creative adapter to cancelled/rollback interventions, withdrawn or invalidated artifacts, and corresponding release transitions. The editorial publisher's records and complete gate/transition history now round-trip in the durable plane snapshot, so a restart does not strand a published item that an operator must later reverse.

Freshness, failures, and recovery#

Every queue summary and detail carries an authority snapshot. Evidence age is compared with its recorded half-life; stale evidence is announced explicitly, and an approval based on that evidence receives a separate stale-approval warning. A 409 stale_review_item or stale_steering_version is retained by the shared API error client, shown as a concurrent-edit message, and followed by a refresh rather than a blind retry.

The console distinguishes initial loading, live, disconnected, and service error states. Browser offline/online events disable mutations and trigger a reconnect refresh. A manual refresh, retry connection, and full page reload all reconstruct state from the BFF. Authorization failure names the missing agentic-operations scope; anonymous navigation remains proxy-gated away from the operator route.

Accessibility and destructive-action law#

  • Queue rows, tabs, dialogs, filters, and actions use native controls or named button/group semantics with visible :focus-visible treatment.
  • Queue items activate by keyboard, tab state is announced, and action dialogs move focus into the first field, trap Tab/Shift+Tab, close on Escape, and restore a predictable inspector state.
  • Withdraw, rollback, veto, and cycle execution use explicit confirmations. Withdrawal copy says the live artifact becomes unavailable; rollback copy says the published version is deprecated and retained in history; cycle copy warns about billable provider work.
  • The 390-pixel mobile journey has no horizontal document overflow, while the desktop layout keeps the queue and inspector in one restrained split view.
  • The shared Playwright fixture runs automated serious/critical Axe checks on the focused browser journeys, and the component honors reduced motion.

Browser-to-real-BFF proof#

operator-autonomy-live-bff.spec.ts starts from the shipped browser route with an authenticated admin:agentic-operations identity and no interception of an autonomy endpoint. Against a fresh real BFF process it observes successful responses from status, cycles, review queue, steering, and suggestions. It then opens the standing-direction drawer, submits a PUT /steering containing the loaded version, observes HTTP 200 and version N + 1, and reopens the control to verify the canonical value returned by the BFF.

The focused run passed 1/1 in Chromium against Next on 127.0.0.1:3011 and a fresh BFF on 127.0.0.1:4110. The BFF log recorded the five authenticated reads, the version-checked mutation, and the subsequent refresh reads. This is browser-to-runtime proof, not only an injected HTTP-handler test or a mocked UI contract. The deeper action matrix remains deterministic: BFF integration tests exercise the real queue/publisher/domain stores, while browser contract tests exercise every corresponding human control and response branch.

Automated scenario matrix#

Scenario Enforced result
All observation views Queue, run, artifact, provenance, source, budget, gate, and intervention data render from response fields.
All human actions Approve, reject, veto, broad tweak, node tweak, direction, feedback, withdraw, rollback, and cycle confirmation issue the intended request.
Outcome truth Held, blocked, failed, review-window, and released are separately visible and filterable.
Stale authority Evidence and approval warnings render; review and direction conflicts refresh instead of overwriting.
Authentication Every autonomy request carries bearer auth; missing operator scope and anonymous navigation fail visibly/closed.
Error recovery Reload, offline/online reconnect, transient service error, refresh, and retry recover the console.
Accessibility Keyboard operation, focus trap, Escape dismissal, native naming, mobile overflow, reduced motion, and Axe serious/critical checks pass.
Post-publication recovery Editorial transition history survives a plane snapshot restore and still accepts a real takedown.
Live browser path A shipped Next route reads and version-mutates a fresh real BFF autonomy plane.

Artifact identity#

Artifact SHA-256
apps/oshun/bff/src/agentic/autonomy-route.ts aceeecf3f155ad6009caea116219531a73c1029d79666c4f3e9b1a22493a1c01
apps/oshun/bff/src/agentic/autonomy-bindings/editorial-publisher.ts c3c5b0649e9f4e502d6b0d220f09c975c7934f5c5870420606c157c6bc330ddc
apps/oshun/bff/src/agentic/autonomy-bindings/plane-persistence.ts f41c6f33c9cd23b7c07cde5dad1ade7a9bde6f496df28277187e28f3b9fb1919
apps/oshun/web/src/components/operator/AutonomyOperatorConsole.tsx eb1eec271031754f936f42919fcc11707289672c201a9152bff1549f383010da
apps/oshun/web/src/components/operator/AutonomyOperatorConsole.module.css fdcf186d743d8f417bb98fb8bf764ecec4613f3016d911a3df0007cf9798857d
apps/oshun/web/e2e/operator-autonomy-console.spec.ts 90738aa15a5e26d293c42f80bbb9c71a3b4cb2a32a38208588bd1586204dceea
apps/oshun/web/e2e/operator-autonomy-live-bff.spec.ts 85595215fd1f7f6838720740d93fd0c2a2d7ac7f598cfea276f9ed36f7c2e203
libs/oshun/creative-autonomy/src/review/review-queue.ts e49c29e34d874af9285bc55e8c56be396cdbbe124b21add86cb9d935dbeec1e5
libs/oshun/creative-autonomy/src/common-run-adapter.ts 1036e6517221fc84c4343212a5d8995e296cca0722252a2f4f63f01be3b3c696
libs/contracts/src/run-protocol/run-model.ts b22b8a192934d6ac3459f4aa3bdfaf5e996bc3df1d24894fcbfd60794078ef50

Automated and adversarial verification#

  • The focused creative-autonomy suite and full package test target pass, including withdrawal/rollback transitions and post-publication common-run mappings. The contracts run-model test passes 19/19.
  • BFF route, binding, and plane integration tests pass 38/38. They cover auth/scope refusal, category/budget status, freshness, queue and steering optimistic concurrency, node-addressed tweaks, live editorial withdrawal and rollback, and snapshot/restored reversal.
  • The shared API-client unit slice passes 4/4, including preservation of BFF error codes and conflict details.
  • operator-autonomy-console.spec.ts passes 5/5 with retries disabled; operator-surfaces.spec.ts passes 7/7; and the real-BFF browser journey passes 1/1. Together these are 13/13 clean focused Playwright journeys, with the shared serious/critical accessibility scan applied to the mocked deep console and operator-surface paths.
  • @oshun/creative-autonomy:typecheck, @oshun/bff:typecheck, and @oshun/web:typecheck pass; both app ratchets report zero baseline errors. The contracts production build and direct BFF production esbuild pass.
  • Direct ESLint across every changed TypeScript/TSX file reports zero errors; the creative-autonomy project lint reports zero errors and only its 87 pre-existing warnings. git diff --check passes.
  • The refreshed canonical AUD-003 record passes all required boundaries at the evidence source commit: creative autonomy 255/255, agentic studio 289/289, studio authoring 138/138, focused BFF autonomy/run lifecycle 43/43, V8 355/355, and V9 176/176. Its deliberately verdict-recording V8 documentation-drift check remains red rather than being misreported as a test-execution failure; all record hashes, bounded logs, commands, source/lockfile identity, and generated audit sections verify.

Resource-safe verification#

The required resource probe reported 15 GiB RAM, 31 GiB swap, about 10 GiB available RAM, and 38 GiB free disk. Checks ran sequentially with one focused worker where applicable. A contracts Nx test wrapper unexpectedly expanded to the repository-wide Vitest configuration and a BFF Nx build wrapper expanded to 269 dependency tasks; each was stopped under the hard memory gate and replaced by its exact targeted Vitest or direct esbuild command. No test assertion had failed when either wrapper was stopped.

A Next production build was not run: the host is below the 32 GiB threshold and the repository instructions prohibit Next production builds by default without explicit approval on this host class. The final web typecheck passed, both Next dev routes compiled, the deep Playwright tests passed, and the retained live-BFF journey exercised a fresh Next/BFF pair. No full-workspace sweep was attempted.

Scope and negative proof#

  • This package proves the in-repository shipped browser route and an isolated local browser-to-real-BFF mutation. It is not evidence of an externally hosted production deployment, production traffic, a release canary, or a current production placement receipt.
  • The isolated BFF intentionally ran without OPENROUTER_API_KEY; its director was fail-closed. No paid provider call, autonomous production cycle, customer publication, or real customer feedback occurred.
  • No product database migration was added. In a database-backed deployment the plane uses its existing durable snapshot store; the new editorial-record field is backward compatible and is covered by restore testing.
  • HITL-002 through HITL-005 still own the complete intervention vocabulary, canonical transactional co-authoring, notifications/escalations, and global shortcuts/presets. This closure does not claim those packages.
  • No mobile-native flow, media/model artifact, or Unreal asset changed. Native mobile automation, media-provider probes, and Unreal execution are therefore inapplicable to HITL-001.

Publication identity#

  • Implementation and first remote-integrated tested source commit: 06fe5f10396c0f52e22ccb92bfbb8f3369cb8401
  • Retained browser-to-real-BFF proof commit: 7244cd392183bc26c1fa4f18b65b61ede1ada8a4
  • Publication metadata commit: 6dd993da7e47c8b52085bedc55be10d8fad174dd
  • Canonical verification refresh: 6e9fe8f8238db551b04bdae39277beef4b615506