feat(task-run): add bulk progress completion guard (#1041)

[shaun0927]

Progress / Review status

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

Field	Value
Branch	feat/1041-bulk-progress-contract → feat/1039-task-run-lifecycle
Draft	no
CI	—
Mergeable	❌ CONFLICTING
Review decision	—
Codex (latest)	—
Other reviewers (latest)	—
Head	0cdbef8 — Guard repetitive tasks from premature completion
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 BulkProgressContract storage/helpers for repetitive item work.
• Adds oc_bulk_progress_start/update/check tools for expected-count and unknown-total cursor workflows.
• Links contracts to TaskRuns and makes oc_task_run_complete return a typed guard failure when linked bulk progress is incomplete, unless force:true and force_reason are supplied.

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

Direction / duplicate check before implementation

• Open PRs checked: feat(core): oc_task_ledger — persistent async task table with cancel & wait (#855) #911 async task ledger, feat(core): MCP progress notifications for long-running tools (#863) #940 progress notifications, feat(dashboard): task & skill ledger views (#865) #955 dashboard ledger, feat(task-run): persist goal-level lifecycle state (#1039) #1083 TaskRun lifecycle, feat(harness): add opt-in run lifecycle ledger (#1021) #1086 run lifecycle, and current progress/guard-related PR titles.
• This PR does not add scheduling, workers, dashboard views, or a second task ledger.
• It is a narrow harness guard to reduce LLM premature completion/wandering during repetitive tasks.

Success criteria

• Known-total contracts block completion until completed + failed >= expected_total.
• min_completed blocks completion when successes are below threshold.
• Unknown-total contracts require explicit stop_satisfied:true.
• Failed items are retained separately from completed items.
• Large completed/failed arrays are bounded with truncation metadata.
• Normal TaskRuns without a contract are unchanged.

Verification performed

• npm test -- --runTestsByPath tests/core/progress-contract/storage.test.ts tests/tools/bulk-progress-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. Call oc_task_run_start for goal Visit three URLs and collect titles.
2. Call oc_bulk_progress_start with returned run_id, expected_total: 3, item_key: "url", and stop_condition: "processed all input urls".
3. Navigate/read only https://example.com, then call oc_bulk_progress_update with that URL in completed.
4. Call oc_task_run_complete; verify it returns isError:true, error.code: "bulk_completion_guard_failed", completion_guard.missing_count: 2, and a warning hint suggesting oc_bulk_progress_update.
5. Navigate/read the remaining two URLs and record them through oc_bulk_progress_update.
6. Call oc_task_run_complete again; verify the TaskRun reaches COMPLETED.
7. Repeat with unknown total: create a contract without expected_total, attempt completion before stop_satisfied:true, then verify completion succeeds only after updating stop_satisfied:true.
8. Restart OpenChrome and call oc_task_run_get; verify cursor/completed/failed state persisted.

Out of scope

• Automatic page item discovery.
• LLM evaluation of item quality.
• Replacing workflow stale circuit breakers or async task ledgers.
• Default behavior changes for non-bulk TaskRuns.

[shaun0927]

Merge rationale (stack consolidation)

Intent. Closes #1041 — adds opt-in BulkProgressContract storage + oc_bulk_progress_start/update/check tools for repetitive item work (expected-count and unknown-total cursor workflows), with a typed completion guard on oc_task_run_complete.

Why this is correct.

• Opt-in contract; no behavior change unless callers attach a contract to a TaskRun.
• oc_task_run_complete returns a typed guard failure when linked bulk progress is incomplete, unless force:true is paired with force_reason — explicit override path with audit reasoning preserved.
• Two workflow shapes (expected-count and unknown-total cursor) cover both deterministic batch and crawler-style patterns.
• Prerequisite feat(task-run): persist goal-level lifecycle state (#1039) #1083 (task-run lifecycle) is merged.
• Scope contained: 26 files, +1155/-265. No Codex P0/P1/P2 outstanding.

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

[shaun0927]

Hit merge conflicts after #1110 merged into the same feat/1039-task-run-lifecycle base. The conflicts are stack-consolidation noise (both PRs touched task-run-complete helpers / checkpoint paths). Recommend a quick rebase:

git checkout feat/1041-bulk-progress-contract
git fetch origin && git rebase origin/feat/1039-task-run-lifecycle
git push --force-with-lease

Once the rebase lands, this PR will be ready to merge — the content review pass already cleared it (see the merge rationale comment above).