/task-orphan-check

name: task-orphan-check
description: "Resolve orphan tasks left in `<workspace>/tasks/` from a previous session that crashed mid-execution. Classifies each live task as done / fresh / stale by cross-referencing per-side-effect markers, then archives or recovers as appropriate. Runs once on startup; safe to re-invoke."
user-invocable: true

Task orphan check

Recovery half of the post-#1049 task-bridge redesign. Replaces the brittle attempts-counter (#1049 + #1066's followup) with a startup-time classification pass that uses existing side-effect markers (PR #1048's `.sending` files for Discord, result files in `results/`, archive presence) to decide what to do with each live task in `<workspace>/tasks/`.

**Usage**: `/task-orphan-check`

Designed to be invoked from `/startup` (PR #1072) as step 1, before `/schedule-crons` starts the task watcher. Also callable standalone for manual recovery.

Why this exists

If the agent crashes mid-task with non-idempotent side effects already executed (Discord message sent, file written, API call made) but the archive of result + task files never ran, on restart the task file is still in `tasks/`. The watcher re-emits it. The agent re-processes. The side effect fires a second time.

PR #1049 tried to solve this with an `attempts: N` counter inside the task file — but the bumper-write fired the watcher's own `Renamed` event, creating an infinite self-trigger loop. PR #1066 tried to patch the loop by switching to in-place writes — but on macOS, `open(file, 'w')` STILL fires the `Created` event because `O_WRONLY|O_CREAT|O_TRUNC` flips the ItemCreated bit. Both PRs are working around the wrong layer.

This skill moves the dedup logic out of the watcher's event surface entirely. The agent does a single classification pass at startup, cross-references markers that already exist (PR #1048 ships them for Discord delivery; result files in `results/` mark "this task was completed"), and decides per-task what to do. No counter, no in-band writes, no self-trigger loop.

On Activation

The procedure below is non-LLM where possible — mechanical file checks + side-effect marker reads. The LLM-judgment parts are bounded (per-task classification with explicit decision rules).

Step 1 — List live tasks

WS="$(bash scripts/sutando-config.sh workspace)"
ls "$WS/tasks/"task-*.txt 2>/dev/null | head -200

If no live tasks, emit "orphan-check: no live tasks, nothing to recover" and idle.

Step 2 — Classify each task

**Run the classifier; do not re-derive the verdicts by hand:**

python3 skills/task-orphan-check/scripts/classify.py        # add --workspace DIR to override

It prints one JSON object — `tasks[]` with `id`, `source`, `access_tier`, `channel_id`, `label` (the readable channel label step 3b uses), `age_s`, `import` (with `import_intent`; `import_task_id` — the `task_id` the current `status.json` carries, `null` when it has none; and for a bound or unbound run `import_phase` / `import_idle_s`), `verdict` (`done` / `fresh` / `orphan` / `import-resume` / `import-stalled` / `import-unbound`) and a `reason` naming the marker or age line it matched — plus `counts`. Read-only: it moves and writes nothing; step 3 acts on its verdicts. The rules it encodes are the ones below (pinned by `tests/task-orphan-check-classify.test.py`); if you change a rule, change the script and its test, then this prose.

For each file in `tasks/`, let `<id>` be the value of the `id:` header line (e.g. `task-1779570142563`). The file is `tasks/<id>.txt`. Per-task paths below use `<id>` consistently — note `<id>` already includes the `task-` prefix; do NOT add it again.

1. **Parse the header** — extract `id`, `timestamp`, `source`, `channel_id` (Discord channel or ag2.space room id — both producers supply it, and the later `contextNotFrom`/requeue workflow needs the exact id, so never discard it in favor of the friendly name), `chat_id` (Telegram), `room_name` / `channel_name` (whichever the surface carries — ag2.space sends `room_name` and no `channel_name`, so a reader that parses only the latter gets nothing and step 3b falls back to the raw id), `user_id`, `access_tier` (`owner` / `team` / `other`; default to `owner` if the field is absent — pre-tier task files predate the field and were authored by the owner). The classifier reads them with `local_task_protocol.parse_task_headers_lenient` — the shape-union parser — because this pass sees files from every writer and era: the desktop's legacy Claude-import writer is task-mid (`task:` before `channel_id:`), and the strict task-last parser would read its `channel_id` and `priority` as absent.

2. **Cross-reference completion markers** (any single match = task already completed):

• **`<workspace>/results/<id>.txt`** exists → **DONE**. The result file is the canonical completion marker; if it exists the task was processed.
• **`<workspace>/results/archive/<id>.txt`** exists → **DONE** (post-archive case).
• **`<workspace>/results/proactive-<id>.txt`** OR `.sending` variant exists → see step 2b below for the in-progress-vs-done split.

**Step 2b — `.sending` contract clarification** (per qingyun-sutando review of #1074):

• `results/<id>.txt` (no suffix) → task completed AND result body written. **DONE.**
• `results/proactive-<id>.txt[.sending]` → the bridge claimed the proactive DM by rename and is mid-delivery. Treat as **DONE** for orphan-check purposes — the bridge owns post-crash recovery via its own startup `.sending` sweep, so we don't second-guess. Read-only either way.
• **`results/<id>.txt.sending` (a TASK result) does not occur — do not classify on it.** Every claim-by-rename site gates on the proactive family *before* applying the suffix, so no `task-*` result is ever renamed:

| site | gate applied before `.sending` | |---|---| | `src/discord-bridge.py` claim loop | `f.name.startswith("proactive-")` | | `src/slack-bridge.py` claim loop | `f.name.