Keep Pathfinder from ending a session while its research subagents are still running: wait for every one, show a running count in the web console, mark finished research with a completion line, and re-run interrupted research on resume

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-03 10:23:38 -07:00
1 parent bfb47f3a8e
commit d49f2d5792
21 files changed
+229 -12

No files matched your search

+2 -2
View File
@@ -89,7 +89,7 @@ Read references/chart.md
5. `[Step 5: Create the map]` `**Status:** Charting`, Destination, Ground rules (backend first), an empty index, the fog in `## Not yet specified`. Say once where it lives and who sees it.
6. `[Step 6: Write the questions]` One per decision you can phrase sharply NOW, dependency order, `Blocked by:` filled the same pass — on `github`, create all first, wire edges second. The rest stays fog. Include a `grill · HITL` testing-posture question; `/plan2code-1-plan` Phase 1 needs it.
7. `[Step 7: Index]` Fill `## Question Checklist` from the files (`local` only). Set `**Status:** Working`.
8. `[Step 8: Fire research]` One subagent per `research` question, in parallel. Each reads primary sources, writes to its `## Evidence` — never decides. Then Session End.
8. `[Step 8: Fire research]` One subagent per `research` question, in parallel. Each writes only its `## Evidence`, never decides. **Wait for all** (they die with the terminal), then Session End.
**No fog at Step 4?** Small enough to plan directly: create no map, keep the recon as a local file, attach it to `/plan2code-1-plan`, STOP. Charting resolves nothing by hand — stop at Step 8.
@@ -102,7 +102,7 @@ Read references/resolve.md
Assume NO memory of any prior session.
1. `[Step 1: Load]` Read the map whole. No question yet.
2. `[Step 2: Reconcile]` **Always.** Read every question. `## Answer` written but the state disagrees? The answer wins. Claimed with no `## Answer`? A crash: release it, say so. Rebuild every marker from the questions; backfill a missing `Resolved:` date from the claim.
2. `[Step 2: Reconcile]` **Always.** Read every question. `## Answer` written but the state disagrees? The answer wins. Claimed with no `## Answer`? A crash: release it, say so. Rebuild every marker from the questions; backfill a missing `Resolved:` date from the claim. Research without `Research complete:`? Re-fire it.
3. `[Step 3: Frontier]` Every question open, unclaimed, and unblocked. First in order.
4. `[Step 4: Choose and claim]` The one the user named, else first on the frontier. Mark it claimed on the question and the map, **saved before any work.** Frontier empty but questions remain? All blocked — report the chain, STOP. Stranded on an `out-of-scope` blocker? Re-frame or rule out, re-run Step 3. Nothing open? The Clearing Gate.
5. `[Step 5: Zoom]` Read the claimed question in full, plus any closed question it references. Obey `## Ground rules`.
@@ -349,12 +349,13 @@ Then one line under the map's `## Out of scope`, giving the name as a link plus
## Reconcile (Work Step 2)
Much shorter here — the tracker holds the state, so there is no checklist to rebuild. Three checks:
Much shorter here — the tracker holds the state, so there is no checklist to rebuild. Four checks:
| Check | Symptom | Repair |
|---|---|---|
| Crashed mid-answer | Open, assigned, and an `## Answer` comment already exists | The comment wins. Close as completed, add the gist to Decisions so far, say so. |
| Stale claim | Open, assigned, no `## Answer`, and the assignee is you from a dead session | Unassign, say so, put it back on the frontier. **If it is someone else's login, leave it** — that is a live session, not a crash. |
| Interrupted research | An open `research` question with no `## Evidence` comment ending in `**Research complete:**` | Re-fire its subagent (`resolve.md` → Interrupted research), say so in one line. |
| Index drift | A closed, completed question with no line under `## Decisions so far` | Read its `## Answer` comment, append the gist. |
Then re-read `## Not yet specified` in full — that part is identical to local mode, and the bullet left behind after its question exists is just as corrosive here.
@@ -375,7 +376,7 @@ Three things never move to the tracker, whatever the backend:
Sketch directories are named for the issue number rather than a local `NN`, so `sketch-42` belongs to the question at `#42`. Same rules otherwise: throwaway, one command to run, never merged.
Research subagents work the same way with one substitution: the brief carries the **issue URL** instead of a file path, and the instruction is to post findings as a comment opening `## Evidence` via `gh issue comment` — and to decide nothing. `## Answer` and the close are still written by the session that fired it.
Research subagents work the same way with one substitution: the brief carries the **issue URL** instead of a file path, and the instruction is to post findings as a comment opening `## Evidence` via `gh issue comment` — and to decide nothing. The comment ends with the `**Research complete:** <YYYY-MM-DD>` line, and the firing session waits for every subagent before Session End, exactly as on local disk. `## Answer` and the close are still written by the session that fired it.
---
@@ -409,7 +410,7 @@ The report is identical either way, and the file still lands on **local disk** a
| `brief.md` says | Here |
|---|---|
| Filter resolved questions by `Resolved:` in range | Filter the map's sub-issues closed as completed by `closedAt` in range |
| Reconcile backfills absent `Resolved:` dates | Nothing to backfill; run the three reconcile checks above instead |
| Reconcile backfills absent `Resolved:` dates | Nothing to backfill; run the four reconcile checks above instead |
| Open / blocked / out-of-scope sections read the checklist | They read the frontier query — unassigned-unblocked, `blocked_by > 0`, and `pathfinder:out-of-scope` respectively |
`## Not yet specified`, `## Destination`, and `**Confidence:**` come from the map issue body, same as always. The no-machinery rule tightens rather than relaxes: no `#numbers`, no label names, no `gh` commands in the file. The reader may never have opened the tracker either.
@@ -65,6 +65,20 @@ The subagent's brief must carry, verbatim:
3. The instruction to write into `## Evidence` of THAT file and nothing else — `## Answer` and `State:` are written by the session that fired it, at Work Step 7.
4. The primary-source rule below.
5. The no-deciding rule below.
6. The instruction to end `## Evidence` with `**Research complete:** <YYYY-MM-DD>` as its last line, written only once every claim is in. Without that line, the next session cannot tell finished research from research that was cut off.
### Wait for every subagent
Subagents run inside this session's process, even when the harness runs them in the background. Close the terminal, or end the session, and they die mid-write, leaving `## Evidence` half-filled. So:
- **Do not reach Session End, or post a web console `finish`, while any research subagent is still running.** Wait for each one to report back. The main session does not read the sources while it waits; it only collects completions.
- While waiting in the web console, post `{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}` and update the count as each returns, so the page never says "done" while work is still in flight.
- Never tell the human the research "will finish on its own" or is "running in the background, ready for next time". It is not: it lives in this terminal.
- Once all are back, Session End reports each research question with a one-line summary of what was found (not decided).
### Interrupted research
At Work Step 2 (Reconcile), any research question that is not resolved and whose `## Evidence` lacks the `**Research complete:**` line was never finished: a closed terminal, a crash, a rate limit. Re-fire its subagent with the same brief, plus one instruction: keep what is already in `## Evidence`, verify it, fill the gaps, then write the line. Say so in one line to the human. A map written before this line existed shows the same symptom; re-firing it costs a little time and nothing else.
### Primary sources only
@@ -165,9 +179,11 @@ bypassable — and Object Lock cannot be added to the existing bucket.
- UNVERIFIED: whether our compliance counsel treats GOVERNANCE as sufficient
for the SEC 17a-4 attestation. No primary source exists for this — it is a
human judgment, not a fact. Belongs in a grill.
**Research complete:** 2026-08-03
```
Note what the example does: every claim carries its own citation, a live command counts as a primary source, and the one thing that cannot be sourced is flagged rather than smoothed over.
Note what the example does: every claim carries its own citation, a live command counts as a primary source, the one thing that cannot be sourced is flagged rather than smoothed over, and the closing `**Research complete:**` line marks the subagent's work as whole.
---
@@ -759,6 +759,9 @@ that is what the person is there to download. The finish carries no
- Every probe, recap and menu goes through the page.
- Post `"stopWarning"` while no map exists (Steps 0 to 4) and `"stopWarning": ""`
once it does, and `"specDir": "specs/<idea>"` when the folder is created.
- Chart Step 8's research subagents must all report back before the
finish (Finishing → Nothing of yours may still be running); the finish
body then names what each one found.
- At every session end, post `finish` (headline, `body`, and Form A's command as
`command`) BEFORE `stop`. Someone who spent the session in the browser never
sees the Trail Footer, and without this their last screen promises a question
@@ -1100,6 +1103,15 @@ open, the next question will appear here on its own" about a session that is
over, and the one thing they need is a command in a terminal they are not
looking at.
**Nothing of yours may still be running.** Before the finish, every
subagent or background job you started this session must have reported
back. They run inside your terminal's process, not the console's: the page
cannot see them, and the moment it says the session ended, the person is
free to close that terminal and kill them mid-write. While you wait, post
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
and update the count as each returns. Never write a `finish.body` that says
work "is running in the background" or "will finish on its own".
### 1. Post the finish
The same closer you are about to print in the terminal, as data:
@@ -1201,6 +1213,7 @@ answers were submitted but never picked up.
| Your session ends mid-flight | Their answers still land on disk. A fresh session runs `status` (or `open --resume`, which reports `pendingResult: true`), and `wait` returns them. An uncollected result is never discarded. |
| They ask to go back to the terminal | `stop` the session and continue. The files under `specs/` are unchanged. |
| The session ends and they are still in the browser | Post `finish` **before** `stop`, and wait for the dashboard button first unless it is a pause. See Finishing, above. Without it their last screen says the next question is coming, and then says contact was lost. |
| You started subagents or background jobs | Wait for every one to report back before `finish`, posting `working` with a count meanwhile. A finish while they run tells the person it is safe to close the terminal, and that kills them. |
| Any session end, not only the last one | Also post `finish`: an off-ramp that routes elsewhere, a checkpoint that saves and stops, a stop request. Anything that ends the session without it leaves the page promising a question that is not coming. |
| Picking up a paused session | `open --resume <sid>` (or `open --session <sid>`) clears a paused `finish` itself, and the questions left open at the pause with it: the finish body already said what was still open, so re-ask whatever the new session needs in your own words rather than leaving the old asks on the page as duplicates. Settled items stay. For any other ending you are deliberately taking back, post `"finish": null` in your first patch. |
| The same result arrives twice | Your harness killed `wait` after it handed the result over but before it recorded that. Handle it once. Most of a repeated patch is harmless, because items merge by id, but `thread` and `comments` **append**: leave out any thread entry you already sent, or the person sees your reply twice. |