@selesai/code 0.8.4 → 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/docs/quickstart.md

@@ -1,42 +1,26 @@
 # Quickstart
 
-This page gets you from install to a useful first pi session.
+This page gets you from install to a useful first Selesai session.
 
 ## Install
 
-Pi is distributed as an npm package:
+Selesai is distributed as an npm package:
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+npm install -g @selesai/code
 ```
 
-`--ignore-scripts` disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.
-
-### Uninstall
-
-Use the package manager that installed pi. The curl installer uses npm globally, so curl and npm installs are removed with npm:
+Then start Selesai in the project directory you want it to work on:
 
 ```bash
-# curl installer or npm install -g
-npm uninstall -g @earendil-works/pi-coding-agent
-
-# pnpm
-pnpm remove -g @earendil-works/pi-coding-agent
-
-# Yarn
-yarn global remove @earendil-works/pi-coding-agent
-
-# Bun
-bun uninstall -g @earendil-works/pi-coding-agent
+cd /path/to/project
+selesai
 ```
 
-Uninstalling pi leaves settings, credentials, sessions, and installed pi packages in `~/.pi/agent/`.
-
-Then start pi in the project directory you want it to work on:
+To install directly from the public repository (builds the latest `main` from source):
 
 ```bash
-cd /path/to/project
-pi
+npm install -g github:SelesaiInTech/selesai-code
 ```
 
 ## Authenticate
@@ -45,7 +29,7 @@ Pi can use subscription providers through `/login`, or API-key providers through
 
 ### Option 1: subscription login
 
-Start pi and run:
+Start Selesai and run:
 
 ```text
 /login
@@ -55,26 +39,26 @@ Then select a provider. Built-in subscription logins include Claude Pro/Max, Cha
 
 ### Option 2: API key
 
-Set an API key before launching pi:
+Set an API key before launching Selesai:
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
-pi
+selesai
 ```
 
-You can also run `/login` and select an API-key provider to store the key in `~/.pi/agent/auth.json`.
+You can also run `/login` and select an API-key provider to store the key in `~/.selesai/agent/auth.json`.
 
 See [Providers](providers.md) for all supported providers, environment variables, and cloud-provider setup.
 
 ## First session
 
-Once pi starts, type a request and press Enter:
+Once Selesai starts, type a request and press Enter:
 
 ```text
 Summarize this repository and tell me how to run its checks.
 ```
 
-By default, pi gives the model four tools:
+By default, Selesai gives the model four tools:
 
 - `read` - read files
 - `write` - create or overwrite files
@@ -83,7 +67,7 @@ By default, pi gives the model four tools:
 
 Additional built-in read-only tools (`grep`, `find`, `ls`) are available through tool options. Pi runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.
 
-## Give pi project instructions
+## Give Selesai project instructions
 
 Pi loads context files at startup. Add an `AGENTS.md` file to tell it how to work in a project:
 
@@ -97,10 +81,10 @@ Pi loads context files at startup. Add an `AGENTS.md` file to tell it how to wor
 
 Pi loads:
 
-- `~/.pi/agent/AGENTS.md` for global instructions
+- `~/.selesai/agent/AGENTS.md` for global instructions
 - `AGENTS.md` or `CLAUDE.md` from parent directories and the current directory
 
-Restart pi, or run `/reload`, after changing context files.
+Restart Selesai, or run `/reload`, after changing context files.
 
 ## Common things to try
 
@@ -109,8 +93,8 @@ Restart pi, or run `/reload`, after changing context files.
 Type `@` in the editor to fuzzy-search files, or pass files on the command line:
 
 ```bash
-pi @README.md "Summarize this"
-pi @src/app.ts @src/app.test.ts "Review these together"
+selesai @README.md "Summarize this"
+selesai @src/app.ts @src/app.test.ts "Review these together"
 ```
 
 Images can be pasted with Ctrl+V (Alt+V on Windows) or dragged into supported terminals.
@@ -134,22 +118,22 @@ Use `/model` or Ctrl+L to choose a model. Use Shift+Tab to cycle thinking level.
 Sessions are saved automatically:
 
 ```bash
-pi -c                  # Continue most recent session
-pi -r                  # Browse previous sessions
-pi --name "my task"    # Set session display name at startup
-pi --session <path|id> # Open a specific session
+selesai -c                  # Continue most recent session
+selesai -r                  # Browse previous sessions
+selesai --name "my task"    # Set session display name at startup
+selesai --session <path|id> # Open a specific session
 ```
 
-Inside pi, use `/resume`, `/new`, `/tree`, `/fork`, and `/clone` to manage sessions.
+Inside Selesai, use `/resume`, `/new`, `/tree`, `/fork`, and `/clone` to manage sessions.
 
 ### Non-interactive mode
 
 For one-shot prompts:
 
 ```bash
-pi -p "Summarize this codebase"
-cat README.md | pi -p "Summarize this text"
-pi -p @screenshot.png "What's in this image?"
+selesai -p "Summarize this codebase"
+cat README.md | selesai -p "Summarize this text"
+selesai -p @screenshot.png "What's in this image?"
 ```
 
 Use `--mode json` for JSON event output or `--mode rpc` for process integration.

package/docs/settings.md

@@ -322,3 +322,7 @@ Project settings (`.selesai/settings.json`) override global settings. Nested obj
   "compaction": { "enabled": true, "reserveTokens": 8192 }
 }
 ```
+
+## Factory Reset
+
+Run `/settings-factory-reset` inside a session to restore the global settings file (`~/.selesai/agent/settings.json`) to the bundled factory defaults. The command warns before replacing the file, saves a backup as `settings.json.bak` next to it, and leaves credentials (`auth.json`), sessions, extensions, skills, and themes untouched. Settings take effect immediately after the reset (equivalent to `/reload`).

package/docs/usage.md

@@ -43,6 +43,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/model` | Switch models |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Thinking level, theme, message delivery, transport |
+| `/settings-factory-reset` | Reset settings to factory defaults (with confirmation) |
 | `/resume` | Pick from previous sessions |
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@selesai/code",
-	"version": "0.8.4",
+	"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,9 @@
 	],
 	"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/"
 	},
@@ -88,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"