# MediaMagic Action Desk — architecture proposal

Status: proposal, 10 September 2026. The accompanying interactive report is an illustrative prototype. No production task service, account session, notification integration, or store action is enabled by it.

## 1. Product decision

Add an **Actions** workspace to MediaMagic Studio. Automation owns preparation, diagnosis, verification and continuation. A person owns the action that requires their presence, authority, information or judgment. The interface holds the context across people, browser sessions and agent restarts.

The unit of work is an **outcome**, such as “restore access to this publisher,” with an explicit completion test. It is not a chat message or a fixed sequence of browser clicks. Different screens become branches of the same task. Unknown screens preserve observations and ask for a bounded next step.

Initial recommendation, pending owner decisions: owner-first, English, existing private Studio access, account roles in the model from day one. Start with one Play publisher and one Apple publisher. Product goal: fewer human minutes and fewer repeated explanations per verified release. Account enrollment, identity checks, recovery, payments, legal agreements and platform review remain real external dependencies.

## 2. Evidence and scope

The checked-out baseline is `e07eff9` on branch `chief/341244515d`. Inspected source is evidence of implementation, not proof of live operational state. Sibling-branch work is identified separately and has not been merged here.

| Evidence | What it shows | Design implication |
| --- | --- | --- |
| [Studio contract](https://github.com/PytaichukBohdan/MediaMagicASO/blob/e07eff9/docs/OWNER-STUDIO.md) and [owner state](https://github.com/PytaichukBohdan/MediaMagicASO/blob/e07eff9/ship-game/src/owner-state.js) | Owner-facing steps, stage events, feedback and scoped authorization already exist; no general cross-app human task lifecycle is exposed. | Extend Studio; preserve existing stage and release authority. |
| [Upload-key incident, 27 Aug](https://github.com/PytaichukBohdan/MediaMagicASO/commit/0623f7b) | A lost key led to a reset and a recorded waiting period. | Preserve custody outside worktrees; show what must wait and what can proceed. Never silently replace signing identity. |
| [Feedback store](https://github.com/PytaichukBohdan/MediaMagicASO/blob/e07eff9/ship-game/src/feedback-store.js) and [repair worker](https://github.com/PytaichukBohdan/MediaMagicASO/blob/e07eff9/ship-game/src/repair-worker.js) | Deduplicated cases and separate code, listing, build and account/legal responses exist. | Link human tasks to cases; a login fix must not trigger a source rewrite. |
| [Worker claim guards, 7 Sep](https://github.com/PytaichukBohdan/MediaMagicASO/commit/30386cc) and [submission intents](https://github.com/PytaichukBohdan/MediaMagicASO/blob/e07eff9/ship-game/src/submission-intents.js) | Stale workers and unknown write outcomes need explicit guards. | Transactional human claims; shared browser leases; reconcile before replaying writes. |
| [Proxy blocker changes, 9 Sep, sibling branch](https://github.com/PytaichukBohdan/MediaMagicASO/commit/bb18b4e) and [harness error preservation, sibling branch](https://github.com/PytaichukBohdan/MediaMagicASO/commit/1821d43) | Recovery instructions and retry behavior were added as individual code paths. | Normalize failures into reusable task templates and structured prerequisites. |
| [Publisher registry](https://github.com/PytaichukBohdan/MediaMagicASO/blob/e07eff9/ship-game/src/publisher-registry.js) | A private binding already ties each store to identity, profile, network and app IDs; the schema currently has two fixed lanes. | Evolve to publisher IDs and per-action capabilities before many-account operation. |

The recorded September publishing session also describes sign-in, proxy and bridge blockers and an owner-requested Mac pause. These are historical reports, not current health measurements. This proposal performs no live account inspection.

## 3. One operator journey

1. Automation observes a blocker and tries only bounded, permitted recovery.
2. It creates or updates one task for the root dependency, listing every affected app and release.
3. It prepares an action packet: plain-language problem, exact publisher alias, actor role, latest observation and time, workspace route, prerequisites, numbered instructions, prepared artifacts, expected result, fallback and next automatic step.
4. The person claims the task. “Open workspace” resolves a private route to the approved browser session or external workflow. It first checks identity, access, network readiness and exclusive control.
5. The person acts. SMS and passwords go directly into the platform UI. Documents go to the platform or a restricted evidence store only when retention is needed.
6. The person submits “Ready to check,” “Waiting for platform,” “Blocked,” “Different screen,” or “Decline / cancel.” A text result, file, URL, receipt, choice or secure credential reference may accompany it.
7. A verifier rereads the authoritative state. Only a matching, fresh result can resolve the dependency. The scheduler then reevaluates the affected work under its existing scope.
8. Studio shows both the human outcome and what automation did next, including continued waiting or another blocker.

Opening a task link does not open a store tab in the person's ordinary browser. The broker resolves the correct profile on the approved host. Some flows require a trusted phone, local platform app or account holder; the same task supports that mode and retains its return path.

## 4. Components and ownership

| Component | Responsibility | Reuse / addition |
| --- | --- | --- |
| Studio Actions | Inbox, task detail, “mine / owner / waiting,” affected apps, history and result entry. Progressive disclosure for technical evidence. | Add to current Studio. |
| Action service in control server | Authenticated task APIs, authorization, input validation, claim transactions, events and outbox. | Add alongside existing routes and CSRF/origin protections. |
| Blocker adapters | Convert scheduler failures, harness outcomes, account health and feedback cases into structured observations. | Extend current scheduler, executor and feedback ingestion. |
| Planner and template registry | Produce versioned instructions and response schemas; choose deterministic handlers for known failures; use model suggestions for unfamiliar ones. | New. Model output never grants permissions or executes arbitrary page instructions. |
| Task database | Global tasks, dependencies, claims, event history, artifact references, checks, sessions and notification outbox. | New SQLite database on the coordinator, with transactions and backups. |
| Publisher registry and secret store | Bind legal publisher, platform identity, app IDs, actor capabilities, approved profile and network, credential references, renewal and verification dates. | Generalize private two-lane registry; keep secrets out of task payloads. |
| Session broker | Acquire shared exclusive profile lease, prepare workspace, transfer human/automation control, revoke access and quarantine uncertain sessions. | Extend harness lifecycle and existing lease ownership. |
| Verifier | Read-only API/browser checks, artifact validation, freshness and identity comparisons; authorized attestation when a machine check is impossible. | Extend current observation/evidence modules. |
| Scheduler and release executor | Consume resolved-dependency events; recheck build, scope and authorization; perform the next eligible action. | Reuse; task service never writes a stage directly to “done.” |
| Notification dispatcher | Deliver minimal task links and reminders; persist attempts and delivery status. | New outbox; in-app first, one external channel after selection. |

Choose one coordinator and one transactional task store initially. This avoids a second workflow engine and keeps network-sensitive store calls on the established host. Do not put a second authoritative task database in Cloudflare KV or browser storage. Existing file ledgers remain authoritative for pipeline stages; task state is authoritative only for human work.

A later authenticated Cloudflare front door can use Access and Tunnel to reach the private action service. Verify identity tokens at the origin and require per-task authorization; a URL is not permission. The public proposal site remains static and contains example aliases only. [Cloudflare deployment model](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/).

## 5. Durable task contract

Proposed logical payload; names and values are illustrative:

```json
{
  "id": "action_example",
  "schemaVersion": 1,
  "revision": 3,
  "kind": "account.sign_in",
  "state": "ready",
  "publisherId": "apple-primary",
  "resourceId": "publisher-session",
  "dedupeKey": "publisher+dependency+challenge-generation",
  "subject": {"type": "account", "id": "apple-primary"},
  "dependencies": [{"releaseRef": "release-example", "stage": "A2"}],
  "observationRef": "observation-example",
  "instructionVersion": 2,
  "requiredCapability": "publisher.sign_in",
  "assigneeId": null,
  "claim": null,
  "preparedAssetRefs": [],
  "workspace": {"mode": "remote_profile", "routeRef": "workspace-example"},
  "responseSchema": "sign-in-result-v1",
  "verification": {"handler": "console_identity", "expectedPublisherRef": "apple-primary", "freshnessSeconds": 300},
  "resume": {"dependencyRef": "apple-session", "scopeRef": "existing-scope"},
  "dueAt": null,
  "nextCheckAt": null,
  "sensitivity": "restricted"
}
```

Also persist: event sequence, actor ID, timestamps, reason, resource generation, session fencing token, expiry, attachment digest/MIME/size, platform receipt, verifier version, target release identity and next observation time. Server-owned fields cannot be overwritten by submitted forms. Store credentials and OTPs are not valid result fields.

Account tasks deduplicate across releases by publisher + dependency + challenge generation. A new prompt or changed legal document creates a new generation. App tasks bind to release, artifact digest, listing revision or case ID as appropriate. Build replacement invalidates an old upload task; account authentication can remain valid independently if rechecked.

### Proposed API surface

| API | Meaning |
| --- | --- |
| `GET /api/studio/actions` | Authorized task summaries with pagination and event cursor. |
| `GET /api/studio/actions/:id` | Full authorized packet with signed artifact access. |
| `POST /api/studio/actions/:id/claim` | Compare revision and atomically claim; conflicts return 409. |
| `POST /api/studio/actions/:id/workspace` | Create a short-lived, actor-bound workspace after acquiring the shared lease. |
| `POST /api/studio/actions/:id/results` | Idempotent result submission; schedules verification, never implies success. |
| `POST /api/studio/actions/:id/release` | Relinquish claim, finish workspace teardown, retain evidence. |
| `POST /api/studio/actions/:id/defer` | Record waiting reason and next check or escalation date. |
| `POST /api/internal/actions/:id/check` | Service-authorized verifier result; not callable by the task actor. |
| `GET /api/studio/action-events?after=cursor` | Polling fallback; optional server-sent events for immediate UI updates. |

User-provided URLs are evidence or proposed destinations, not commands to fetch arbitrary internal resources. Validate scheme and allowlisted destination; handle new domains through review. Scan and limit uploaded attachments, enforce per-object authorization, redact views and define retention before delegation.

## 6. State machine and reliable continuation

`detected → preparing → ready → claimed → in_progress → submitted → verifying → resolved`

- Missing prerequisites during preparation create linked dependency tasks; the parent waits with a clear reason.
- `in_progress → waiting_external` records platform processing or a scheduled return time and releases active browser control safely.
- A different screen, failed check or expired result returns to `ready` with revised instructions and retained history. Unknown evidence routes to specialist triage; no blind retry.
- `cancelled` and `superseded` are terminal. Neither unlocks a dependency.
- A claim timeout revokes the viewing session and asks the broker to stop/reconcile the profile. The resource stays quarantined until control is known to be released. Only then may another actor acquire it.
- A stale build or authorization at resume creates a replacement task or blocks the relevant release; it cannot promote old approval to a new artifact.

In one database transaction the verifier appends its evidence event, marks the task resolved and inserts `dependency.resolved` into an outbox. The dispatcher delivers at least once. The scheduler records event IDs and deduplicates them, then rereads authoritative task, resource and release state. A periodic reconciliation scan repairs missed wakeups and cross-store crash windows. Delivery acknowledgment and actual stage resumption are separate audit events.

There is no claim of exactly-once external writes. Existing write intents, fresh preflight and read-back protect submission. A timeout with an unknown write outcome opens “Check whether this already happened” and blocks replay until reconciled.

A person saying “done” is evidence of an attempt. An authoritative check is evidence of the outcome. If no machine-readable confirmation exists, keep `awaiting_attestation` verification status; an appropriately authorized reviewer can record an explicitly labeled attested result. High-impact attestation cannot silently substitute for a required platform receipt.

## 7. Browser and identity architecture

Model these as separate identities: Studio actor → publisher organization → platform user → Octo account/profile → approved network assignment → permitted app/release. A person's ability to view a task does not confer platform authority.

1. Pause new browser work for the resource; let an in-flight mutation reconcile before handoff.
2. Acquire the same broker lease used by automation, scoped initially to publisher/profile; serialize overlapping API writes to the same release.
3. Check approved network, selected account, visible role, target app and task revision. Detect a dead proxy before navigating to an account page. Never fall back silently to direct egress or another publisher.
4. Prepare a clean workspace with only the selected profile, needed files and short instructions. Temporarily suspend credential-screen capture and any automation observer that could read password/OTP fields.
5. Human control is exclusive. On return, revoke viewer access, confirm detachment, reacquire automation control and recheck state.
6. Store actor/time/action receipts and scrubbed evidence. The broker survives process restarts by treating outstanding sessions as unknown until reconciled.

The existing broad noVNC desktop is acceptable only for the fully trusted owner pilot. It is not per-task isolation. Delegation requires a per-profile desktop/session or a reviewed Octo team setup plus store-native least-privilege users. Hiding controls in Studio cannot restrict what a privileged browser session can do. Proxy administration goes to a designated infrastructure role; avoid exposing every publisher to that operator.

Octo documents folder-level profile access and action rights, with team features dependent on subscription. Confirm the actual account's entitlement before choosing this route. These features do not replace Google or Apple permissions. [Octo team documentation](https://docs.octobrowser.net/en/start/team-settings/).

Project-specific publisher/network isolation is an operational constraint, not a guarantee against account challenges or a universal platform requirement. Prefer supported account invitations and legitimate enrollment or transfer procedures. Buying or rotating accounts is not a recovery strategy in this proposal; ownership and signing custody must be established at onboarding.

## 8. Task families and outcome checks

| Family | System prepares | Human action | Outcome check / continuation |
| --- | --- | --- | --- |
| Login / SMS / recovery | Correct session, last challenge, recovery options, holder routing. | Authenticate directly on the platform or trusted device. | Fresh visible account and permitted role; resume only affected account work. |
| Proxy / connection | Connectivity diagnosis, approved assignment, vendor route, replacement constraints. | Renew service or enter replacement through a secure setup flow. | Broker connectivity + approved egress + browser and API checks separately; then open any dependent login task. |
| Enrollment / identity | Required-fields checklist, documents list, fees, known eligibility and deadlines. | Account holder supplies facts, verifies identity or completes support steps. | Receipt and actual verified/eligible state; receipt alone can mean waiting. |
| Agreement / declarations | Current official text, what is blocked, relevant factual app data, required role. | Authorized person reads, accepts or declines on platform. | Correct agreement/declaration version and status; no automatic consent from a generic completion click. |
| Upload / console form | Artifact identity, QA receipt, correct app/version, listing copy and upload directory. | Perform the unsupported upload or form interaction. | Correct build appears and processing result is known; no duplicate upload while outcome is unknown. |
| Store review / support | Original feedback, affected release, reproduction, patch or reply draft. | Clarify facts, supply a document or send a prepared reply when needed. | Case-linked receipt plus further review observation; fix → QA → existing submission gate. |
| Credentials / permissions | Exact missing scope, invite/setup route, secure destination. | Authorized administrator provisions access. | Minimal API call / role observation succeeds; a file's existence is insufficient. |
| Device / payment / other | Named dependency, expected result and return route. | Act on the trusted device, approved billing page, phone call or external site. | Typed verifier or authorized attestation; clarify unknown cases before changing code. |

Apple documents an Account Holder requirement for paid agreement acceptance and possible 2FA. [Apple agreements](https://developer.apple.com/help/app-store-connect/manage-agreements/sign-and-update-agreements/).

Google documents account-level and app-level permissions; verification can require official documents and subsequent processing. Exact requirements depend on account type and the live console. [Play permissions](https://support.google.com/googleplay/android-developer/answer/9844686), [verification guidance for older accounts](https://support.google.com/googleplay/android-developer/answer/14177239?hl=en).

Use APIs wherever the operation and permissions support them. Google's Edits documentation retains console prerequisites and excludes legal consents; do not assume a universal API-only first publication flow. [Play Edits](https://developers.google.com/android-publisher/edits).

Apple supports webhooks for selected build, beta, app-version and feedback events. They are useful wakeups, not coverage of every account prompt. Verify deliveries, deduplicate, and read back authoritative state. Other sources use bounded polling or an explicit human capture task. Expose last observation, coverage gaps and next check. [Apple webhooks](https://developer.apple.com/help/app-store-connect/manage-your-team/manage-webhooks/).

## 9. Feedback that changes the application

Every incoming observation creates or joins a feedback case with source, platform, app, release, original text and time. The existing classifier is advisory. Permit correction and mixed cases with multiple linked tasks.

- Code defect: reproduce → scoped source fix → new build → affected QA → existing authorization → resubmit → observe.
- Listing mismatch: prepare corrected metadata → validate against the actual app → update the affected listing; rebuild only if behavior changes.
- Build processing: signing or packaging diagnosis → new identified artifact → affected checks.
- Account or agreement: human task, affected publisher waits; unrelated build work can continue.
- Unclear message: evidence/clarification task; do not promise the agent understands every new screen.

Validated recoveries become versioned playbooks containing the observed screen class, prerequisites, successful instructions, verifier and known failure modes. Scrub sensitive content; test changes before promoting them. History improves preparation; it never turns one person's prior consent into authority for another action.

## 10. Delivery plan and acceptance gates

Planning estimates only, assuming one experienced engineer and available owner/account access. These are not measured delivery commitments. External platform waits are excluded; confirm after phase 0.

| Phase | Work | Exit proof | Estimate |
| --- | --- | --- | --- |
| 0. Replay and decisions | Inventory actual blocker codes, permissions and observation coverage; define five fixtures and deployment boundaries. | Login, proxy, agreement, review and unknown cases each have a packet and explicit verifier. | 1–2 engineering days |
| 1. Useful owner inbox | Task DB, adapters, cross-app dedupe, claim/result APIs, Studio list/detail, simple private owner workspace handoff. | A historical blocker can be resolved in a controlled rehearsal without shell commands or chat context. Restart preserves it; repeated events create one task. | 3–5 days |
| 2. Verified continuation | Verifiers, durable outbox, dependency wakeup, browser ownership handoff and stale-result handling. | Read-back resumes exactly the intended eligible work; failed verification, crashes and duplicate events do not submit twice. | 4–6 days |
| 3. Delegation and feedback | Per-profile isolation, real role permissions, notification channel, due dates, case linking and playbook review. | Operator cannot reach another publisher or holder-only session; unknown-screen and store-rejection rehearsals complete end to end. | 4–7 days |
| 4. Broader automation | More task families, supported store webhooks, account renewals, metrics and optional public authenticated access. | Coverage and task-time measurements justify each addition. | Re-estimate from pilot |

Stages 0–3 total roughly 12–20 engineering days, not elapsed calendar time. The fastest useful slice is the owner inbox; broad delegation is a separate milestone.

Verification suite for implementation: repeated blocker dedupe; two-person claim race; human-versus-agent session race; restart during handoff; unknown upload outcome; expired workspace link; stale build/approval; copied task link across users; OTP/log redaction; attachment authorization; notifier outage; verifier unavailable; waiting platform versus resolved state; decline/cancel; macOS worker paused; wrong publisher/egress; feedback that affects only one store; keyboard/mobile UI use.

Keep paused devices paused. Resolving a login task cannot start a laptop worker or change its availability policy. The current CLI, ledgers and guarded executor remain usable during rollout. Feature-flag task creation and continuation separately; rollback stops new desk actions and leaves an actionable read-only queue.

## 11. Benefits, costs and alternatives

| Decision | Benefit | Cost / limitation |
| --- | --- | --- |
| Studio extension | One context and one release authority. | Requires adapters around current file-based state. |
| Outcome-based tasks | Handles new screens and non-browser steps. | Unknown outcomes still need diagnosis or attestation. |
| Verification before continuation | Reduces false completion and repeated writes. | Verifiers need upkeep; platform latency can delay resumption. |
| One task per account dependency | One login can unblock multiple releases. | Resource graph and invalidation rules add complexity. |
| Same approved browser session | Preserves the configured publisher context. | Remote interaction quality, device-specific challenges and broker maintenance. |
| Local transactional store | Small operational footprint; atomic claims/outbox. | Coordinator is a failure domain; encrypted backups and restore drills are required. |
| Human signatures and identity steps | Keeps authority with the appropriate person. | Owner availability remains on the critical path. |

Chat-only handoffs are a useful fallback but lose claims, evidence and reliable wakeups. A third-party ticket queue can mirror assignments later, but would still need the broker and verifier. A full cloud workflow-engine rewrite adds migration and distributed-state cost before proving the task model. Fully automated browser behavior can reduce routine work but does not eliminate identity, legal, novel-screen or recovery dependencies.

Measure median and p90 human active minutes per task, time waiting for a person versus platform versus verification, first-pass verification rate, reopened-task rate, duplicate-task rate, age of stale observations and verified-resume latency. Instrument a two-week pilot before setting outcome targets. Suggested reliability acceptance: zero duplicate external submissions in fault tests; all resolved tasks have a verifier or explicit attestation; all failed notifications remain visible and retryable.

## 12. Owner decisions

The prototype decision worksheet is local to the current browser session. Its export is a draft for discussion, not an approval or a live command. Nothing is sent automatically.

### Decide before implementation

1. Who is the first actor: you, a trusted assistant, or multiple operators? Recommendation: owner-first with future roles modeled.
2. What can each role actually do per publisher, especially signing, identity, payments, key changes and publication? Recommendation: holder retains high-impact authority; explicit app-scoped access for operators.
3. Where should the real desk be accessible: existing private Studio or a Cloudflare-authenticated domain? Recommendation: private pilot; Access/Tunnel after identity review if off-tailnet access is needed.
4. After verification, should automation continue under existing authority or stop again? Recommendation: continue within the already recorded scope; request a new decision only for changed scope or an explicit hold.

### Decide during the pilot

5. Which channel and destination should notify you, with what quiet hours and escalation delay? In-app queue exists first; add one chosen channel.
6. Who can supply SMS/2FA and how long can they be available? Use direct platform entry and an explicit “waiting for holder” state.
7. Is remote desktop acceptable, and must tasks work entirely from a phone? Triage can be mobile; document/device workflows may need desktop or a trusted device.
8. Which publishers and services are in scope, who legitimately controls each, and who owns recovery? Start with current Play/Apple lanes; validate registry facts privately.
9. Who may renew proxies, choose replacement vendors or authorize expenses? Record limits and ownership; no silent network reassignment.
10. Which release decisions remain manual? Preserve current track, territories, version and authorization gates until explicitly changed.
11. What evidence may be stored, for how long, and who may view it? Proposal: minimal receipts and redacted captures; no OTP retention; identity documents stay at source where possible.
12. What is acceptable when verification is impossible: authorized attestation, escalation, or continued blocking? Define by task risk, not a universal “done” override.
13. How should mixed or unclear review feedback be assigned, and who settles product decisions? Keep the case linked to all resulting work.
14. Which devices may automation use, and during which hours? Preserve existing pause state; no implicit permission from task completion.
15. What volume, staffing, target response time and engineering budget should guide rollout? Measure the owner pilot before many-account scaling.
16. What language should the desk and its instructions use? English is the current report assumption; localize the operator-facing text without changing verifier semantics.

No live account values, credentials, internal viewer links or private evidence are published in this proposal. Source links may require repository access.