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-visibletreatment. - 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.tspasses 5/5 with retries disabled;operator-surfaces.spec.tspasses 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:typecheckpass; 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 --checkpasses. - 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