@selesai/code 0.8.5 → 0.8.6

package/docs/plans/workflow-handoff-carryover.md

@@ -0,0 +1,108 @@
+# Plan: Carry workflows over compaction & auto-handoff
+
+Status: implemented (P0 + P1). The first workflow attempt timed out in `build-1` with zero changes; the parent session then implemented the plan directly. All changes are in `src/extensions/pi-subagents`; no core changes. Feasibility held at ~90%.
+
+## 1. Problem
+
+Running a scripted workflow (`/workflow-*` → `launchSlashSubagent({ workflowScript, async: true })` → pi-subagents async run) and then triggering **compaction** or **auto-handoff** (`handoff-new` via `_checkAutoHandoff`) makes the workflow "disappear":
+
+- After **auto-handoff** the new session shows no widget/fleet jobs, receives no completion results, cannot resume/steer the workflow, and the handoff document itself omits tool-call details — so the fresh agent doesn't even know a workflow exists.
+- After **compaction** the parent agent loses the workflow manifest (run ids, keys, phases) from its context; the only countermeasure is a generic "resume the parent task" nudge.
+
+## 2. Root cause (trace)
+
+1. Workflow runs are **detached child processes** with state on disk under a global tmp root (`DIRS.async` / `DIRS.results`, `src/extensions/pi-subagents/src/shared/types.ts:2030`). The workflow script itself (worker thread + `runs.run` children + mission-backed `state.get/set`) lives in that spawned run — it keeps running after the parent session is replaced. Nothing about the workflow actually dies.
+2. Auto-handoff replaces the session: `ctx.newSession()` (`src/extensions/handoff-new.ts:146`) → `AgentSessionRuntime.newSession` (`src/core/agent-session-runtime.ts:226`) → `teardownCurrent` + fresh `createRuntime` → **fresh extension instances**. The new pi-subagents instance restores state only for its own session identity.
+3. The identity key is the **session file path** (`resolveCurrentSessionId`, `src/extensions/pi-subagents/src/shared/session-identity.ts` → `getSessionFile() ?? getSessionId()`). Every restore path filters by it and misses the old session's runs:
+
+   | Component | Filter that drops the old session | File |
+   |---|---|---|
+   | Async job tracker | `restoreActiveJobs` → `listAsyncRuns(..., sessionId: state.currentSessionId)` | `runs/background/async-job-tracker.ts:648` |
+   | Result delivery | `ownsSession(sessionId, epoch)` / `identity.sessionId === state.currentSessionId` | `runs/background/result-watcher.ts:168, 211` |
+   | Foreground history | `run.sessionId === sessionId` | `runs/foreground/foreground-history.ts:124` |
+   | Retained children (`children.list`) | `listRetainedChildren(DIRS.async, ownerSessionId)` | `runs/background/retained-children.ts` |
+   | Wait subscriptions | `record.sessionId === state.currentSessionId` | `runs/background/wait-subscriptions.ts:~245` |
+   | Async capacity | `getActiveAsyncCapacitySnapshot(state.currentSessionId, ...)` | `extension/index.ts:757` |
+   | Mission goal notices | `ownerSessionId = state.currentSessionId` | `extension/index.ts:~634` |
+
+4. `session_shutdown` (`extension/index.ts:~843`) clears in-memory jobs, stops the result watcher, and disposes watchers — by design, but nothing re-links the old session's estate.
+5. The new session's header records the parent: `parentSession` in `SessionHeader` (`src/core/session-manager.ts:942`), and `SessionStartEvent` carries `previousSessionFile` for reason `"new"`/`"fork"` (`src/core/extensions/types.ts:562`). The extension never uses either.
+6. Compaction: tool results are summarized away (`compaction.ts` / `branch-summarization.ts` skip tool-result bodies). The `session_compact` handler injects a resume message only when active async jobs exist, with **generic** text (`extension/index.ts:810`) — run ids/keys/phases are lost from the model's context.
+
+## 3. Fix design — session lineage adoption
+
+> Implemented. Files changed: `shared/session-lineage.ts` (new), `shared/types.ts`, `runs/background/async-status.ts`, `runs/background/async-job-tracker.ts`, `runs/background/result-watcher.ts`, `runs/background/notify.ts`, `runs/background/run-status.ts`, `runs/background/run-id-resolver.ts`, `runs/background/retained-children.ts`, `runs/background/wait-subscriptions.ts`, `runs/foreground/foreground-history.ts`, `runs/foreground/subagent-executor.ts`, `tui/fleet.ts`, `extension/index.ts`. Tests: `test/unit/session-lineage.test.ts` (new), `test/unit/handoff-adoption.test.ts` (new), existing `compaction-resume.test.ts` unchanged and passing. One extra find beyond the plan: the completion notifier (`notify.ts`) rejected non-current-session results, so it also needed lineage awareness for adopted result delivery.
+
+One concept fixes the handoff half: **on `session_start` with `previousSessionFile`, adopt the previous session's workflow estate** instead of filtering on the current session id alone. Everything is keyed by stable session-file paths and the chain is recoverable via `SessionManager.getHeader().parentSession` (`session-manager.ts:1291`), so adoption is additive and needs **zero core changes**.
+
+### 3.1 New helper — `shared/session-lineage.ts`
+
+- `resolveSessionLineage(ctx, { depth = 8 })`: `[currentSessionId, ...walk(getHeader().parentSession)]`, depth-bounded, deduped, skipping paths that don't exist (`existsSync` guard, same as `retainedSessionFile` in `retained-children.ts`).
+- Stored as `state.sessionLineage: string[]` in `resetSessionState` (`extension/index.ts:~766`).
+- `listAsyncRuns` gains a `sessionIds: string[]` filter (`async-status.ts`) so all callers share one primitive.
+
+### 3.2 Adopt the estate (P0)
+
+| # | Change | Location |
+|---|---|---|
+| 1 | `restoreActiveJobs`: list `queued|running` runs for `sessionIds: state.sessionLineage`; mark adopted jobs (`adopted: true`) so completion notices can say "started in a previous session". | `async-job-tracker.ts:648` |
+| 2 | Result watcher: treat lineage as owned (`ownsSession` + identity checks accept lineage set); dedupe: at adoption only prime results whose `runId` ∈ adopted set or `completedAt` ≥ session-start epoch — never replay ancient results. | `result-watcher.ts:168–262` |
+| 3 | Foreground history, retained children, wait subscriptions: restore/union over lineage. | `foreground-history.ts:124`, `retained-children.ts`, `wait-subscriptions.ts:~245` |
+| 4 | Async capacity: snapshot over lineage so adopted runs count against `maxActiveAsyncRunsPerSession`. | `active-async-capacity.ts` caller at `extension/index.ts:757` |
+| 5 | Mission goal notices: collect for each lineage owner on `session_start` (reasons `new`/`fork`) in addition to the existing `agent_end` path. Missions themselves already persist per-project (`missions/store.ts`) and `mission.list` works. | `extension/index.ts:~634`, `missions/goal-driver.ts:118` |
+| 6 | Schedules: already re-armed on the new session (`bindSession` → `selectProject` → `restoreOne` → `arm`); `scheduledRunManager.stop()` on shutdown is safe because of that re-arm. Lock in with a regression test. | `scheduled-runs.ts:376–381` |
+
+### 3.3 Make the new agent aware (P0)
+
+- On `session_start` (reason `new`/`fork`) with adopted active workflows, set `state.handoffResumePending`. On the first `agent_settled` after that (avoids racing the handoff doc's first turn), send one custom message — same pattern as `subagent-compaction-resume`:
+
+  ```
+  customType: "subagent-handoff-resume", display: false, triggerTurn: true
+  content: "Session handoff detected. N active background workflows carried over from the previous session:
+    - <id8> workflow[task] builder · step 3/5 · running (last: read)
+    - <id8> single explorer · running
+  Monitor with subagent status <id>, interrupt/resume/steer/approve-checkpoint by run id; children.list shows completed steps."
+  ```
+
+  Built from `state.asyncJobs` (id, mode, `workflowKey`, agent, phase/currentStep, activity).
+
+### 3.4 Enrich the compaction nudge (P1)
+
+- Replace the generic `subagent-compaction-resume` text with the same workflow manifest (one line per active job). Keep the trigger conditions and custom type unchanged — test at `test/unit/compaction-resume.test.ts` covers the pattern.
+
+### 3.5 Out of scope (documented, intentional)
+
+- **Watchdog**: resets on `session_before_switch` by design (`watchdog/register-main.ts:431`). Keep.
+- **Core changes**: none needed. If a third extension later needs cross-session state, revisit with a generic `session_replaced` state-bag API (rejected now — YAGNI).
+- **Blocking handoff while workflows run**: rejected; long workflows would lock the session. Carry-over is the correct fix.
+
+## 4. Tests
+
+- unit: `resolveSessionLineage` (chain walk, depth bound, missing files, dedupe) — `test/unit/session-lineage.test.ts` ✔
+- unit: `restoreActiveJobs` adopts lineage runs — covered by the adoption harness ✔
+- unit: result watcher delivers lineage results; no replay of pre-adoption results (dedupe watermark) — harness asserts adopted result delivery + cleanup ✔
+- unit: `session_start(reason:"new")` + first `agent_settled` injects `subagent-handoff-resume` when adopted workflows exist; nothing when none — `test/unit/handoff-adoption.test.ts` ✔ (repeated-settle no-op also asserted)
+- unit: compaction resume message contains the workflow manifest — harness asserts run id in content ✔
+- regression: full pi-subagents unit suite 1907 pass / 0 fail ✔
+
+## 5. Risk register
+
+| Risk | Mitigation |
+|---|---|
+| Result replay across the boundary (ancient results re-delivered) | Adopt-set + epoch watermark (3.2 #2) |
+| Resume message races the handoff doc's first turn | Defer to first `agent_settled` (3.3) |
+| Stale/deleted parent session files | `existsSync` guard + bounded walk (3.1) |
+| Adopted runs exceeding capacity | Count lineage in capacity snapshot (3.2 #4); existing spawn budgets still enforce |
+| Double-watch in the same process | Old instance fully disposed at `session_shutdown` before the new one starts; watchers are per-instance |
+| Extra turn noise after handoff | One message, `display:false`, same precedent as compaction resume |
+
+## 6. Effort & feasibility
+
+- **Possibility: ~90%.** Everything the workflow needs already persists on disk keyed by stable session-file paths; the spawned workflow process survives the session switch; the new session already knows its parent (`parentSession` header + `previousSessionFile` event); all filters to widen live in one package; the message-injection pattern already exists. The change is additive filtering + one notification — no protocol, no core change, no data migration.
+- **Size:** ~500–700 LOC + ~12–16 tests, all in `src/extensions/pi-subagents`.
+- **Effort:** 2–3 focused dev-days.
+- **Order:** P0 (3.1–3.3) → P1 (3.4) → tests/regression. Each P0 item is independently shippable.
+
+## 7. Verification (manual)
+
+Same as before — worth an interactive smoke test with `/workflow-task` + `/handoff-new` to see the widget adoption and the `subagent-handoff-resume` notice end-to-end. Automated coverage: `src/extensions/pi-subagents/test/unit/{session-lineage,handoff-adoption}.test.ts` + existing compaction-resume test.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@selesai/code",
-	"version": "0.8.5",
+	"version": "0.8.6",
 	"description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
 	"type": "module",
 	"repository": {
@@ -50,6 +50,8 @@
 	],
 	"scripts": {
 		"clean": "shx rm -rf dist",
+		"test": "vitest run src/extensions/undo.test.ts src/extensions/agent-browser.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/web-agent-onboarding.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-onboarding.test.ts src/__tests__/workflow-modes.test.ts",
+		"test:coverage": "vitest run --coverage src/extensions/undo.test.ts src/extensions/agent-browser.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/web-agent-onboarding.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-onboarding.test.ts src/__tests__/workflow-modes.test.ts",
 		"prepare": "npm run build",
 		"build": "npm run clean && tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
 		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/ && shx mkdir -p dist/defaults && shx cp src/defaults/* dist/defaults/ && shx mkdir -p dist/extensions && node scripts/copy-extensions.mjs && shx mkdir -p dist/themes && shx cp -r src/themes/. dist/themes/ && shx mkdir -p dist/skills && shx cp -r src/skills/. dist/skills/"
@@ -89,6 +91,7 @@
 		"@types/proper-lockfile": "4.1.4",
 		"@types/semver": "7.7.1",
 		"@typescript/native-preview": "^7.0.0-dev.20260120.1",
+		"@vitest/coverage-v8": "4.1.9",
 		"shx": "0.4.0",
 		"typescript": "5.9.3",
 		"vitest": "4.1.9"