Add read-only companion/mobile surface for local Melix status and session monitoring

[Akane-CN]

Reference scanned

Odysseus pewdiepie-archdaemon/odysseus@f6b0dcb.

Code evidence:

• companion/pairing.py, companion/routes.py: pairing and read-only companion routes.
• tests/test_companion_pairing.py, tests/test_companion_readonly.py.
• README: mobile/PWA is a first-class operator surface.

Why this matters for Melix

Many Melix jobs are long-running local operations. A read-only companion/mobile surface would let the operator check status from a phone or secondary browser without exposing remote control.

In scope

• Pairing flow for local/LAN trusted access.
• Read-only views: loaded models, runtime health, queue/job progress, recent receipts, logs tail, active sessions status.
• Explicit no-control guarantee for companion token scope.
• QR/code pairing and token revocation.

Out of scope

• Public internet exposure.
• Remote shell/control actions from companion mode.
• Syncing private prompt/session contents unless explicitly enabled.

Verification

• Pairing token cannot call mutating endpoints.
• Mobile smoke test for status pages.
• Receipt/log redaction tests.

[Zigfreidish]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add a read-only companion/mobile surface for local Melix status and session monitoring.

Current behavior:
Melix can run long-lived local workflows, but there is no dedicated read-only companion surface for checking local runtime status from a phone or secondary browser. Operator status inspection remains tied to primary app/CLI surfaces or direct local access.

Desired behavior:
Melix should expose a paired, read-only companion surface that shows local runtime and session status without granting remote control. The companion token must be scoped so it cannot mutate state, start jobs, run shell commands, or expose private prompt/session content unless a future explicit setting allows it.

Key interfaces:

• Pairing contract: QR/code or equivalent local/LAN trusted pairing with token revocation.
• Companion authorization scope: read-only token permissions separated from normal operator control tokens.
• Status views: loaded models, runtime health, queue/job progress, recent receipts, logs tail, and active session status.
• Redaction contract: companion views avoid raw prompts, secrets, and sensitive local paths by default.

Acceptance criteria:

• Pairing creates a token that can read allowed status endpoints.
• The companion token cannot call mutating endpoints.
• Status views include runtime health, loaded models, active jobs/queue, recent receipts, and log tail with redaction.
• Token revocation prevents further companion reads.
• Mobile or narrow viewport smoke verification covers the primary read-only status flow.
• Tests prove private prompt/session content is not exposed by default.

Out of scope:

• Public internet exposure.
• Remote shell/control actions from companion mode.
• Syncing private prompt/session contents unless explicitly enabled by a separate future feature.

[Zigfreidish]

This was generated by AI during triage.

PR #2068 has been squash-merged as the server-side authorization foundation for this issue.

Delivered in that slice:

• persistent auth session scopes: operator_control and companion_read_only
• companion read-only allowlist for status/discovery/current-session/self-revocation routes
• structured 403 companion_read_only_scope_violation denial for mutating routes without echoing request bodies/private prompt content
• focused Swift coverage at 99.34% changed-line coverage and PR scoped performance report status ok with 0 regressions

Remaining issue scope includes pairing/QR UX, desktop token management, mobile/narrow viewport status smoke, active-job/recent-receipt status cards, and log-tail redaction UI.

[Zigfreidish]

Merged #2074 as ab1c08d17055ce90d2e7e7e2390f35d5a342e6c1.\n\nCovered in this slice:\n- Added GET /v1/melix/companion/status for read-only companion status monitoring.\n- Returned redacted runtime health, visible model, cache, scheduler queue, image-job, and auth/session summaries.\n- Allowed x-melix-session in browser preflight and covered companion/local trusted/credential auth access paths.\n- Added the minimal latency metric companion.status_latency_ms.\n\nEvidence:\n- Local focused companion status tests passed after latest origin/main merge: 3/3.\n- Local scoped coverage tests passed: 11/11.\n- Changed-line coverage after latest origin/main merge: 99.76% (412/413).\n- Full local pre-commit gate passed before PR update: make swift-test, make py-test, make integration-test, scoped performance status ok.\n- Remote current-head checks passed after merging latest main: CI, PR evidence, and scoped performance.\n- Remote performance report: Status ok, regressions 0, context regressions 0, verification failures 0.\n- Review threads were replied to and resolved before squash merge.\n\nRemaining #1759 scope still includes QR/code pairing UX, desktop companion-token issuance/revocation controls, mobile/narrow viewport smoke, redacted recent receipt views, and log-tail read models/UI.

[Zigfreidish]

Merged #2080 as a750839.\n\nCovered in this slice:\n- Added redacted recent receipt summaries to GET /v1/melix/companion/status using existing image-job read-model data.\n- Exposed safe companion fields only: ids, model/operation/state/lane/worker, progress, timestamps, prompt digest, artifact count, and failure code.\n- Added per-receipt redaction metadata for raw prompts, prompt deltas, request bodies, artifact URIs, local paths, error messages, and logs.\n- Preserved newest-first deterministic ordering and capped visible receipt summaries at 10 while reporting total count.\n- Addressed review feedback by narrowing response DTOs to Encodable and making deterministic test clocks thread-safe.\n\nEvidence:\n- Local focused companion status tests passed after review fixes: 4/4.\n- Changed-line coverage for touched Swift scope: 100.00% (188/188).\n- Full local pre-commit gate passed after review fixes: make swift-test, make py-test, make integration-test, scoped performance status ok.\n- Remote ci-pr completed successfully for head d1d124d, including integration-tests.\n- Remote pr-scoped-performance completed successfully: regressions 0, context regressions 0, verification failures 0.\n- Review threads were replied to and resolved before squash merge.\n\nRemaining #1759 scope still includes QR/code pairing UX, desktop companion-token issuance/revocation controls, mobile/narrow viewport smoke, and log-tail read models/UI.

[Zigfreidish]

PR #2090 has been squash-merged into main.

Delivered in this slice:

• Added a bounded read-only image job state-event log tail to the companion status read model.
• Exposed redacted logs on GET /v1/melix/companion/status with visible vs total counts.
• Kept raw log lines, prompts, request bodies, artifact URIs, local paths, and raw error messages out of the payload.

Verification before merge:

• Local: make swift-test, make py-test, make integration-test, focused Swift tests, changed-line coverage 99.37%, scoped performance report Status: ok with 0 regressions.
• Remote: pr-evidence, pr-scoped-performance, and ci-pr all passed; performance report Status: ok, 0 regressions; review threads resolved.

Still out of scope for this slice: QR/code pairing UX, desktop token controls, mobile/narrow viewport UI smoke, and companion UI rendering of the log tail.

[Zigfreidish]

Merged #2094 as 2c4cf9e9eb4fc14ea4b09c224c2a3718df93950d.

Covered in this slice:

• Added a pairing descriptor to POST /v1/melix/auth/session only for companion_read_only sessions.
• Documented companion pairing creation and the token handling boundary.
• Covered operator-session non-regression, loopback fallback for wildcard/blank bind hosts, and IPv4/IPv6 status URL formatting.
• Addressed review feedback by hoisting static route/capability arrays and simplifying host formatting.

Verification before merge:

• Local focused Swift tests passed after merging current origin/main: 3/3.
• Changed-line coverage after merging current origin/main: 100.00% (155/155).
• Local PR-scoped performance report: Status ok, selected probes 0, regressions 0.
• Remote CI passed, including integration-tests.
• Remote scoped performance report: Status ok, regressions 0, context regressions 0, verification failures 0.
• Review thread was replied to and resolved before squash merge.

Remaining #1759 scope still includes QR/code pairing UX, desktop companion-token issuance and revocation controls, mobile/narrow viewport smoke, and companion UI rendering of the log tail.