feat(handoff): add secret-safe resume checkpoints (#1040)

[shaun0927]

Progress / Review status

Auto-refreshed 2026-05-13 — owner comments cleaned up to reduce review noise.

Field	Value
Branch	feat/1040-handoff-resume → feat/1039-task-run-lifecycle
Draft	no
CI	—
Mergeable	❌ CONFLICTING
Review decision	—
Codex (latest)	—
Other reviewers (latest)	—
Head	5efe0bc — Enable bounded human takeover recovery
Commits	2

_{Owner comment cleanup: 0 issue + 0 inline review comments deleted. Outstanding feedback from automated/external reviewers above is unchanged.}

---

Summary

• Adds opt-in oc_handoff_start/status/finish/cancel tools for secret-safe human takeover checkpoints.
• Persists only caller-supplied safe snapshot fields (url, title, origin, counts/keys, fingerprint, screenshot ref), with redaction before metadata/events are written.
• On oc_handoff_finish, computes a bounded before/after delta and appends exactly one kind: "handoff" evidence pointer to the linked TaskRun when run_id is supplied.

Closes #1040.
Stacked on #1083 / feat/1039-task-run-lifecycle; merge #1083 first.

Direction / duplicate check before implementation

• Open PRs checked before opening this PR: feat(core): oc_task_ledger — persistent async task table with cancel & wait (#855) #911 (feat(core): oc_task_ledger — persistent async task table with cancel & wait (mcp-browser-use adoption A) #855 async task ledger), feat(core): MCP progress notifications for long-running tools (#863) #940 (feat(core): MCP progress notifications for long-running tools (mcp-browser-use adoption D) #863 progress notifications), feat(dashboard): task & skill ledger views (#865) #955 (feat(dashboard): task & skill ledger views (mcp-browser-use adoption F) #865 dashboard ledger), feat(task-run): persist goal-level lifecycle state (#1039) #1083 (feat(task-run): goal-level lifecycle and evidence state on top of task ledger #1039 TaskRun lifecycle), feat(harness): add opt-in run lifecycle ledger (#1021) #1086 run lifecycle, plus handoff-related title/body search.
• This PR is intentionally narrow: it does not create another task ledger, dashboard, progress notifier, or browser automation scheduler.
• It fits OpenChrome's harness direction by adding recoverable manual-intervention state while keeping browser tools unchanged and avoiding Bytebot-style desktop/noVNC/Postgres infrastructure.

Success criteria

• A handoff can be started for a TaskRun, queried, finished, cancelled, or timed out deterministically.
• Handoff artifacts never persist raw cookies, storage values, DOM text, passwords, tokens, or inline screenshots.
• Finishing a linked handoff updates the TaskRun with one handoff evidence pointer that can be used for resume context.
• Terminal handoffs cannot be modified.

Verification performed

• npm test -- --runTestsByPath tests/core/handoff/storage.test.ts tests/tools/handoff-tools.test.ts tests/core/task-run/storage.test.ts tests/tools/task-run-tools.test.ts --runInBand
• npm run build
• npm run lint:changed

Real OpenChrome verification after merge

1. Start OpenChrome from the merged branch and call oc_task_run_start with goal: "manual login resume smoke".
2. Call oc_handoff_start with the returned run_id, reason: "manual login required", and a safe before snapshot such as { "url": "https://example.test/login", "title": "Login", "cookie_count": 0 }.
3. Simulate human completion, then call oc_handoff_finish with an after snapshot such as { "url": "https://example.test/account", "title": "Account", "cookie_count": 1, "local_storage_keys": ["session_state"] }.
4. Call oc_task_run_get for the original run and verify last_evidence[0].kind === "handoff", ref equals the handoff_id, and summary contains the URL/title/cookie-count delta.
5. Inspect persisted files under $OPENCHROME_HOME/handoffs/<handoff_id>/ and confirm no raw token/password/cookie/storage values are present.
6. Start another handoff with ttl_ms: 1000, wait over one second, call oc_handoff_status, and verify it transitions to TIMED_OUT and cannot be finished.

Out of scope

• Browser-native automatic snapshot capture from a live Page object.
• Dashboard rendering for handoff artifacts (feat(dashboard): surface needs-help and handoff resume evidence in task view #1043 covers dashboard surfacing).
• Replacing or modifying the async task ledger/progress notification work in feat(core): oc_task_ledger — persistent async task table with cancel & wait (#855) #911/feat(core): MCP progress notifications for long-running tools (#863) #940/feat(dashboard): task & skill ledger views (#865) #955.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[shaun0927]

Merge rationale (stack consolidation)

Intent. Closes #1040 — adds opt-in oc_handoff_start / oc_handoff_status / oc_handoff_finish / oc_handoff_cancel tools for secret-safe human-takeover checkpoints.

Why this is correct.

• Secret safety by design: persists only caller-supplied safe snapshot fields (url, title, origin, counts/keys, fingerprint, screenshot ref). Redaction runs before any metadata/event is written.
• oc_handoff_finish computes a bounded before/after delta and appends exactly one kind: "handoff" evidence pointer to the linked TaskRun when run_id is supplied — observable, auditable, idempotent.
• Opt-in tool surface; no behavior change for callers that don't invoke handoff.
• Prerequisite feat(task-run): persist goal-level lifecycle state (#1039) #1083 (task-run lifecycle) is merged.
• Scope contained: 11 files, +732/-223. No Codex P0/P1/P2 outstanding.

CI. Targets the task-run lifecycle feature branch; CI workflow only runs on main/develop PRs.