pi-crew 0.9.15 → 0.9.16

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [v0.9.16] — cancel wipes the trace (2026-06-29)
+
+User-driven refinement of the cancellation policy. Previously, cancelled / stopped subagents and crew-agent records were preserved on disk (`agent_*.json` files in `.crew/state/subagents/`, plus `agents.json` + per-task `status.json` in the run state directory) and continued to appear in the UI dashboard / widget / transcript viewer. The user explicitly asked: *"một khi đã cancel thì phải xóa luôn dấu vết về subagent đó chứ để lại làm gì nữa"* — once cancelled, the trace must be wiped. This release implements that policy.
+
+### Changed — terminal-status deletion
+
+- **Subagent records** (`.crew/state/subagents/<id>.json`) — added `removePersistedSubagentRecord(cwd, id)` in `src/runtime/subagent-manager.ts`. On terminal status `cancelled` / `stopped` / `terminated:true`, the persisted file is **deleted immediately** (no linger). The file is saved first so any concurrent reader sees the final status, then `unlink`'d within microseconds — the next widget/dashboard tick sees no entry.
+
+- **Crew-agent records** (per-run `agents.json` index + per-task `status.json`) — added `removeCrewAgent(manifest, taskId)` in `src/runtime/crew-agent-records.ts`. `upsertCrewAgent()` now checks `shouldDeleteCrewAgentOnTerminalStatus(record)` and dispatches to `removeCrewAgent` instead of `saveCrewAgents` for `cancelled` / `stopped` records. Both the index entry AND the per-task status.json are wiped.
+
+### What is preserved vs wiped
+
+| Status | Persisted? | Rationale |
+|---|---|---|
+| `completed` | ✅ yes | Successful work — audit value |
+| `failed` | ✅ yes | Agent errored — debugging value |
+| `error` | ✅ yes | Unexpected exception — debugging value |
+| `cancelled` | ❌ **wiped** | User-initiated cancellation — no trace |
+| `stopped` | ❌ **wiped** | External abort — no trace |
+| `terminated: true` (any status) | ❌ **wiped** | Any termination event — no trace |
+
+### In-memory handles
+
+`terminateLiveAgent` in `src/runtime/live-agent-manager.ts:169` already deletes from the `liveAgents` Map immediately after abort — no change needed. The `evictStaleLiveAgentHandles` fallback (10-min linger for orphan terminal handles) remains as a safety net.
+
+### New helper predicates
+
+- `shouldDeleteOnTerminalStatus(record)` — for `.crew/state/subagents/` records
+- `shouldDeleteCrewAgentOnTerminalStatus(record)` — for per-run `agents.json` records
+
+Both exported for downstream callers and tests.
+
+### Tests
+
+- **NEW `test/unit/cancellation-trace-wipe.test.ts`** — 15 cases covering:
+  - `shouldDeleteOnTerminalStatus` / `shouldDeleteCrewAgentOnTerminalStatus` predicates for all 6 statuses
+  - `removePersistedSubagentRecord` happy path + ENOENT safe-fail
+  - `removeCrewAgent` removes from `agents.json` index AND per-task `status.json`
+  - `upsertCrewAgent` integration: cancelled → wiped, completed/failed → preserved
+
+- **Existing tests still pass** — 118/118 across 9 test files (subagent-manager-cov, subagent-tools-integration, live-manager-cov, direct-agent-run, team-runner-merge, process-lifecycle, preflight-validator, topology-analyzer, cancellation-trace-wipe). 0 regressions.
+
+### Verification
+
+- `tsc --noEmit` → EXIT 0
+- `node scripts/check-lazy-imports.mjs` → "All dynamic imports have `// LAZY:` marker"
+- `npm test` (focused 9-file suite) → 118/118 pass
+
+### Honesty discipline
+
+- **Failed subagents are NOT wiped** — they may carry useful debugging info (error stack, partial output). Different from cancel. If the user later wants failed→wipe too, it's a 1-line predicate change.
+- **No tombstone** — the cancellation event is in `events.jsonl` (the run's audit log) and `notifications/`. Disk-level agent files are intentionally gone after cancel.
+- **Filesystem race window** is microseconds (save then unlink); under heavy concurrent access a reader might briefly see the final status before the file disappears. Acceptable trade-off for the "no trace" policy.
+
+### Files touched
+
+| File | Change |
+|---|---|
+| `src/runtime/subagent-manager.ts` | +2 functions (`removePersistedSubagentRecord`, `shouldDeleteOnTerminalStatus`); modified `markStopped` + `runSubagent` finally block to wipe on cancel |
+| `src/runtime/crew-agent-records.ts` | +2 functions (`removeCrewAgent`, `shouldDeleteCrewAgentOnTerminalStatus`); modified `upsertCrewAgent` to dispatch to remove on cancel |
+| `test/unit/cancellation-trace-wipe.test.ts` | NEW (15 cases, 8.3 KB) |
+| `CHANGELOG.md` | this entry |
+| `package.json` | 0.9.15 → 0.9.16 |
+
 ## [v0.9.15] — workflow topology advisory (2026-06-29)
 
 After a parallel-research assessment of v0.9.13 + v0.9.14 (`research-findings/pi-crew-performance-quality-assessment.md`, effectiveness evaluation at `.crew/research/pi-crew-effectiveness-evaluation.md`), a user-driven refinement showed that the original BLOCK-on-misuse design was too aggressive — **agents know their context better than the orchestrator**. This release ships an **advisory-only** topology classifier that prints measured-cost notes and proceeds either way. The agent (caller) decides.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.15",
+  "version": "0.9.16",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/runtime/crew-agent-records.ts

@@ -206,9 +206,64 @@ export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentReco
 
 const TERMINAL_AGENT_STATUSES = new Set(["completed", "failed", "cancelled", "blocked"]);
 
+/**
+ * User policy (v0.9.16): cancelled / stopped crew-agent records leave NO trace.
+ * `failed` records keep their audit trail (different from cancel — agent errored).
+ */
+export function shouldDeleteCrewAgentOnTerminalStatus(
+	record: Pick<CrewAgentRecord, "status">,
+): boolean {
+	const s = record.status;
+	return s === "cancelled" || s === "stopped";
+}
+
+/**
+ * Remove a single crew-agent record from both `agents.json` (the index file)
+ * and the per-task `status.json`. Called on cancellation to wipe the trace.
+ * Safe-fail: missing files are treated as success (already removed).
+ */
+export function removeCrewAgent(
+	manifest: TeamRunManifest,
+	taskId: string,
+): { removedIndex: boolean; removedStatus: boolean } {
+	let removedIndex = false;
+	let removedStatus = false;
+	// 1. Remove from agents.json index
+	try {
+		const existing = readCrewAgents(manifest);
+		const filtered = existing.filter((r) => r.taskId !== taskId);
+		if (filtered.length !== existing.length) {
+			saveCrewAgents(manifest, filtered);
+			removedIndex = true;
+		}
+	} catch {
+		// best-effort
+	}
+	// 2. Remove per-task status.json
+	try {
+		const statusPath = agentStatusPath(manifest, taskId);
+		if (fs.existsSync(statusPath)) {
+			fs.unlinkSync(statusPath);
+			removedStatus = true;
+		}
+	} catch {
+		// best-effort
+	}
+	return { removedIndex, removedStatus };
+}
+
 export function upsertCrewAgent(manifest: TeamRunManifest, record: CrewAgentRecord): void {
 	// Guard: skip if run state has been deleted (prune/forget/cleanup)
 	try { fs.statSync(manifest.stateRoot); } catch { return; }
+	// User policy (v0.9.16): cancelled / stopped crew agents leave NO trace.
+	// We delete BOTH the index entry (agents.json) and the per-task status.json
+	// immediately so the UI dashboard/widget never see the cancelled agent again.
+	if (shouldDeleteCrewAgentOnTerminalStatus(record)) {
+		removeCrewAgent(manifest, record.taskId);
+		// Invalidate the per-task reader cache so a subsequent read sees fresh state.
+		asyncAgentReaderCache.delete(agentsPath(manifest));
+		return;
+	}
 	// Read current state
 	const existing = readCrewAgents(manifest);
 	// Deduplicate by id: keep newer record when same id appears

package/src/runtime/subagent-manager.ts

@@ -114,6 +114,36 @@ export function savePersistedSubagentRecord(
 	}
 }
 
+/**
+ * Delete the persisted subagent record from disk.
+ * Used when a subagent is cancelled or terminated — the user wants no trace.
+ * Safe-fail: if the file does not exist (already deleted), this is a no-op.
+ * Any other I/O error is logged but not propagated.
+ */
+export function removePersistedSubagentRecord(cwd: string, id: string): boolean {
+	try {
+		const filePath = persistedSubagentPath(cwd, id);
+		fs.unlinkSync(filePath);
+		return true;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException)?.code;
+		if (code === "ENOENT") return false;
+		logInternalError("subagent-manager.remove", error, `id=${id}`);
+		return false;
+	}
+}
+
+/**
+ * Predicate: should this record's persisted file be deleted on terminal status?
+ * Only abnormal terminations (cancelled / stopped / terminated-flag) are wiped.
+ * Successful runs (`completed`) and agent errors (`failed`, `error`) keep their audit trail.
+ */
+export function shouldDeleteOnTerminalStatus(record: SubagentRecord): boolean {
+	if (record.terminated === true) return true;
+	const s = record.status;
+	return s === "cancelled" || s === "stopped";
+}
+
 const ALLOWED_RECORD_FIELDS = new Set([
 	"id",
 	"agentId",
@@ -427,6 +457,12 @@ export class SubagentManager {
 						? Math.max(0, record.completedAt - record.startedAt)
 						: undefined;
 					savePersistedSubagentRecord(options.cwd, record);
+					// User policy (v0.9.16): cancelled / stopped subagents leave NO trace.
+					// Successful runs (`completed`) and agent errors (`failed`, `error`)
+					// keep their audit trail. See shouldDeleteOnTerminalStatus().
+					if (shouldDeleteOnTerminalStatus(record)) {
+						removePersistedSubagentRecord(options.cwd, record.id);
+					}
 					this.onComplete?.(record);
 				}
 				this.drainQueue();
@@ -451,10 +487,16 @@ export class SubagentManager {
 
 	private markStopped(record: SubagentRecord, reason?: string): void {
 		record.status = "stopped";
+		record.terminated = true;
 		record.completedAt = Date.now();
 		if (reason && !record.error) record.error = reason;
 		const cwd = this.cwdByRecord.get(record.id);
+		// User policy (v0.9.16): stopped subagents leave NO trace on disk.
+		// Save first (so any concurrent reader sees the final status), then
+		// unlink. The race window is microseconds and the file is gone before
+		// the next widget/dashboard tick.
 		if (cwd) savePersistedSubagentRecord(cwd, record);
+		if (cwd) removePersistedSubagentRecord(cwd, record.id);
 	}
 
 	private createRunSignal(id: string, signal?: AbortSignal): AbortSignal {