@gotgenes/pi-subagents 6.0.1 → 6.1.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.0.1...pi-subagents-v6.1.0) (2026-05-20)
+
+
+### Features
+
+* create AgentRecord class with transition methods ([#98](https://github.com/gotgenes/pi-packages/issues/98)) ([e5b2170](https://github.com/gotgenes/pi-packages/commit/e5b21704de2d693e4feff8b0c0f80a4f6e3fdabd))
+
+
+### Documentation
+
+* plan AgentRecord state machine extraction ([#98](https://github.com/gotgenes/pi-packages/issues/98)) ([5ca6613](https://github.com/gotgenes/pi-packages/commit/5ca6613ba8e73e042c7f06e2f303ad573048138e))
+* **retro:** add retro notes for issue [#102](https://github.com/gotgenes/pi-packages/issues/102) ([594a61a](https://github.com/gotgenes/pi-packages/commit/594a61a59f04aafba06ab8649c183b5003e95822))
+
 ## [6.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.0.0...pi-subagents-v6.0.1) (2026-05-20)
 
 

package/docs/plans/0098-extract-agent-record-state-machine.md

@@ -0,0 +1,435 @@
+---
+issue: 98
+issue_title: "Extract AgentRecord state machine from scattered status transitions"
+---
+
+# Extract AgentRecord state machine
+
+## Problem Statement
+
+`AgentRecord` status transitions are scattered across 6 locations in `agent-manager.ts`: `startAgent()` `.then()`, `startAgent()` `.catch()`, `resume()`, `abort()`, `abortAll()`, and `drainQueue()` catch.
+Each site sets `record.status` plus associated fields (`completedAt`, `result`, `error`) in ad-hoc combinations, with repeated guards like `if (record.status !== "stopped")`.
+
+There are 15 direct `record.status = ...` writes and 17 associated field writes (`result`, `error`, `completedAt`, `startedAt`) — ~32 scattered mutation sites total.
+`startAgent()` is ~130 lines partly because it manages these transitions inline.
+
+## Goals
+
+- Convert `AgentRecord` from a plain interface to a class that owns and encapsulates its transition state.
+- Extract status-transition methods that centralize the "don't overwrite stopped" guard.
+- Reduce scattered field writes in `agent-manager.ts` to method calls.
+- Encapsulate transition fields (`status`, `result`, `error`, `startedAt`, `completedAt`) behind private backing fields with getters — external code can read but not write.
+- Use lift-and-shift to migrate incrementally: introduce the class alongside the interface, migrate construction sites, switch the re-export, replace writes, then encapsulate.
+
+## Non-Goals
+
+- Parent snapshot extraction (architecture.md Step 2) — separate issue.
+- Session-event observation / callback threading removal (architecture.md Step 3) — separate issue.
+- Stat accumulation methods (`toolUses++`, `addUsage()`, `compactionCount++`) — these are running counters, not status transitions.
+  They could become methods in a follow-up but are out of scope here.
+- Encapsulating non-transition field writes (`session`, `outputFile`, `worktree`, `worktreeResult`, `promise`, `toolCallId`, `resultConsumed`, `pendingSteers`) — these are data capture, not status transitions.
+
+## Prerequisites
+
+- Issue #102 (shared test record factory) — shipped.
+  All 8 test files construct `AgentRecord` objects through `createTestRecord()` in `test/helpers/make-record.ts`.
+  Converting the interface to a class requires updating only this one factory (plus `agent-manager.ts` construction).
+
+## Background
+
+### Relevant modules
+
+| Module                        | Role                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `src/types.ts`                | Defines `AgentRecord` interface — 20+ consumers read from it                   |
+| `src/agent-manager.ts`        | Only file that writes status-transition fields                                 |
+| `src/service.ts`              | Defines `SubagentRecord` (serializable snapshot) — unchanged                   |
+| `src/service-adapter.ts`      | Converts `AgentRecord` → `SubagentRecord` via `toSubagentRecord()` — unchanged |
+| `test/helpers/make-record.ts` | Shared test factory — single construction site for all tests (#102)            |
+
+### External writes to `AgentRecord` (not status transitions)
+
+Several files outside `agent-manager.ts` write non-transition fields:
+
+- `tools/get-result-tool.ts` — `record.resultConsumed = true` (2 sites)
+- `tools/steer-tool.ts` / `service-adapter.ts` — `record.pendingSteers` (push messages)
+- `tools/agent-tool.ts` — `record.toolCallId = toolCallId`
+
+These are data-capture writes, not status transitions, and remain public fields.
+
+### Code-style constraints
+
+The code-style skill's "output arguments" rule applies directly: "If a function sets a field on a received object, it is doing work that belongs inside the owning object.
+Encapsulate the mutation behind a method."
+The "scattered resets" rule also applies: "When the same set of fields is reset to the same values in multiple places, extract a single method."
+
+## Design Overview
+
+### `AgentRecord` becomes a class
+
+`AgentRecord` moves from an interface in `types.ts` to a class in a new `src/agent-record.ts` module.
+`types.ts` re-exports the class so existing `import type { AgentRecord } from "./types.js"` across the codebase continues to work with no import-path changes.
+
+The class encapsulates the 5 transition fields behind private backing fields with getters.
+All other fields remain public (identity fields are `readonly`; non-transition mutable fields stay public).
+
+```typescript
+export type AgentRecordStatus =
+  | "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
+export class AgentRecord {
+  // Identity — readonly, set once at construction
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly invocation?: AgentInvocation;
+
+  // Transition state — private backing fields, public getters
+  private _status: AgentRecordStatus;
+  get status(): AgentRecordStatus { return this._status; }
+
+  private _result?: string;
+  get result(): string | undefined { return this._result; }
+
+  private _error?: string;
+  get error(): string | undefined { return this._error; }
+
+  private _startedAt: number;
+  get startedAt(): number { return this._startedAt; }
+
+  private _completedAt?: number;
+  get completedAt(): number | undefined { return this._completedAt; }
+
+  // Non-transition mutable state — public fields
+  toolUses: number;
+  lifetimeUsage: LifetimeUsage;
+  compactionCount: number;
+  session?: AgentSession;
+  abortController?: AbortController;
+  promise?: Promise<string>;
+  resultConsumed?: boolean;
+  pendingSteers?: string[];
+  worktree?: { path: string; branch: string };
+  worktreeResult?: { hasChanges: boolean; branch?: string };
+  toolCallId?: string;
+  outputFile?: string;
+
+  constructor(init: AgentRecordInit) { /* ... */ }
+
+  // Transition methods — see below
+}
+```
+
+### Constructor and `AgentRecordInit`
+
+The constructor accepts a wide init bag that covers all fields.
+Required fields: `id`, `type`, `description`.
+All others are optional with sensible defaults (`status` defaults to `"queued"`, `toolUses` to 0, etc.).
+
+This wide init bag serves two purposes:
+
+1. Production use (`agent-manager.ts`): passes the 7 fields it needs at spawn time.
+2. Test use (`createTestRecord`): sets arbitrary state (e.g., `status: "completed"`, `result: "done"`) without going through transition methods.
+
+```typescript
+export interface AgentRecordInit {
+  id: string;
+  type: SubagentType;
+  description: string;
+  status?: AgentRecordStatus;
+  startedAt?: number;
+  completedAt?: number;
+  result?: string;
+  error?: string;
+  toolUses?: number;
+  lifetimeUsage?: LifetimeUsage;
+  compactionCount?: number;
+  abortController?: AbortController;
+  invocation?: AgentInvocation;
+  session?: AgentSession;
+  promise?: Promise<string>;
+  resultConsumed?: boolean;
+  pendingSteers?: string[];
+  worktree?: { path: string; branch: string };
+  worktreeResult?: { hasChanges: boolean; branch?: string };
+  toolCallId?: string;
+  outputFile?: string;
+}
+```
+
+### Transition methods
+
+7 methods covering all 6 transition sites plus the resume-reset:
+
+#### `markRunning(startedAt: number): void`
+
+Sets `status = "running"` and `startedAt`.
+Called in `startAgent()` when transitioning from queued to running.
+
+#### `markCompleted(result: string, completedAt?: number): void`
+
+Always sets `result` and `completedAt` (via `??=`).
+Only changes `status` to `"completed"` if not already `"stopped"`.
+Called in the `.then()` success path and in `resume()` try block.
+
+#### `markAborted(result: string, completedAt?: number): void`
+
+Same guard as `markCompleted` — preserves stopped status.
+Sets `status = "aborted"`.
+Called in `.then()` when runner returns `aborted: true`.
+
+#### `markSteered(result: string, completedAt?: number): void`
+
+Same guard as `markCompleted` — preserves stopped status.
+Sets `status = "steered"`.
+Called in `.then()` when runner returns `steered: true`.
+
+#### `markError(error: unknown, completedAt?: number): void`
+
+Always sets `error` (formatted: `Error` → `.message`, otherwise `String(...)`) and `completedAt` (via `??=`).
+Only changes `status` to `"error"` if not already `"stopped"`.
+Called in `.catch()`, `resume()` catch block, and `drainQueue()` catch.
+
+#### `markStopped(completedAt?: number): void`
+
+Always sets `status = "stopped"` and `completedAt`.
+No guard — stopping is always valid.
+Called in `abort()` (2 sites) and `abortAll()` (2 sites).
+
+#### `resetForResume(startedAt: number): void`
+
+Sets `status = "running"`, `startedAt`.
+Clears `completedAt`, `result`, `error` to `undefined`.
+Called in `resume()` before re-running.
+
+### Guard semantics: preserve current behavior
+
+The current `.then()` and `.catch()` blocks guard only the `status` field but always set `result`/`error` and `completedAt`:
+
+```typescript
+// Current .then() — result and completedAt are set even when stopped
+if (record.status !== "stopped") {
+  record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+}
+record.result = responseText;
+record.completedAt ??= Date.now();
+```
+
+This is intentional — `get-result-tool.ts` reads `record.result` from stopped records.
+The transition methods preserve this behavior: data fields are always set, status is only changed when not stopped.
+The `??=` on `completedAt` preserves the abort timestamp when `markStopped()` fires before `.then()`.
+
+### Worktree result-append: reorder, don't add a method
+
+The `.then()` block currently appends worktree branch text to `record.result` after the transition.
+With encapsulated fields, direct writes to `result` are forbidden.
+
+Instead of adding an `appendToResult()` method, reorder the `.then()` block to compute the final result (including worktree text) before calling the transition method:
+
+```typescript
+.then(({ responseText, session, aborted, steered, sessionFile }) => {
+  // Worktree cleanup first — compute final result
+  let finalResult = responseText;
+  if (record.worktree) {
+    const wtResult = this.worktrees.cleanup(record.worktree, options.description);
+    record.worktreeResult = wtResult;
+    if (wtResult.hasChanges && wtResult.branch) {
+      finalResult += `\n\n---\nChanges saved to branch ...`;
+    }
+  }
+
+  // Transition with complete result
+  if (aborted) record.markAborted(finalResult);
+  else if (steered) record.markSteered(finalResult);
+  else record.markCompleted(finalResult);
+
+  record.session = session;
+  if (sessionFile) record.outputFile = sessionFile;
+
+  detach();
+  // ...
+})
+```
+
+The worktree cleanup reads `record.worktree` (a public field set before the promise) and writes `record.worktreeResult` (a public field).
+It does not depend on `record.status` or `record.result`, so the reorder is safe.
+
+### Correctness improvement in `resume()`
+
+The current `resume()` method lacks the "don't overwrite stopped" guard:
+
+```typescript
+// Current — no guard against abort race
+record.status = "completed";
+record.result = responseText;
+record.completedAt = Date.now();
+```
+
+After migration, `record.markCompleted(responseText)` includes the guard.
+This closes a latent race where `abort()` sets status to `"stopped"` between `resetForResume()` and the runner returning.
+The current code would overwrite `"stopped"` back to `"completed"` — the method call does not.
+
+### Circular import avoidance
+
+`agent-record.ts` imports types from `types.ts` (`SubagentType`, `AgentInvocation`).
+`types.ts` re-exports the class from `agent-record.ts`.
+
+This is safe because `agent-record.ts` uses `import type` for its `types.ts` imports — these are erased at runtime, so no runtime circular dependency exists.
+
+## Module-Level Changes
+
+### New files
+
+1. `src/agent-record.ts` — `AgentRecord` class, `AgentRecordInit` interface, `AgentRecordStatus` type.
+2. `test/agent-record.test.ts` — unit tests for constructor and all 7 transition methods.
+
+### Changed files
+
+1. `src/types.ts` — remove `AgentRecord` interface; add re-export: `export { AgentRecord, type AgentRecordInit, type AgentRecordStatus } from "./agent-record.js"`.
+2. `src/agent-manager.ts` — import `AgentRecord` as a value from `./agent-record.js`; replace object literal construction with `new AgentRecord(...)`; replace ~32 scattered field writes with 11 transition method calls.
+3. `test/helpers/make-record.ts` — import `AgentRecord` from `../../src/agent-record.js`; construct with `new AgentRecord(...)` instead of plain object.
+
+### Unchanged files
+
+All other source and test files — they use `import type { AgentRecord } from "./types.js"` and only read fields.
+The re-export from `types.ts` means zero import-path changes.
+
+## Test Impact Analysis
+
+### New tests enabled by the extraction
+
+The state machine is currently untestable in isolation — transitions are buried inside `agent-manager.ts`.
+After extraction:
+
+- Guard logic tested directly (e.g., `markCompleted` on a stopped record preserves status but sets result).
+- Invalid transition sequences tested without mocking the runner.
+- Error formatting (`Error` vs string) tested in isolation.
+- `resetForResume` field clearing tested without the full resume flow.
+
+### Existing tests that stay as-is
+
+`agent-manager.test.ts` tests verify end-to-end behavior (spawn, complete, abort, resume, queue drain, worktree).
+They remain unchanged — they verify the wiring between `AgentManager` and the `AgentRecord` class.
+
+### No test files need updating (except the shared factory)
+
+Issue #102 consolidated all test record construction into `createTestRecord()`.
+Only that one factory changes.
+All 8 consumer test files are untouched.
+
+## TDD Order
+
+### Cycle 1: AgentRecord class tests
+
+Test surface: `test/agent-record.test.ts` (new file).
+
+Tests cover:
+
+- Constructor: defaults (`status` → `"queued"`, `toolUses` → 0, `lifetimeUsage` → zeros, `compactionCount` → 0), passthrough of init values (including optional transition fields like `result`, `completedAt`).
+- `markRunning`: sets status and startedAt.
+- `markCompleted`: sets status/result/completedAt when not stopped; preserves status but still sets result/completedAt when stopped; `completedAt` uses `??=` semantics (does not overwrite existing value).
+- `markAborted` and `markSteered`: same guard behavior as `markCompleted`.
+- `markError`: sets status/error/completedAt when not stopped; preserves status but still sets error/completedAt when stopped; formats `Error` objects to `.message`, non-Error to `String(...)`.
+- `markStopped`: always sets status and completedAt, no guard.
+- `resetForResume`: sets status to `"running"` and startedAt; clears completedAt, result, error.
+
+Commit: `test: add AgentRecord class tests (#98)`
+
+### Cycle 2: AgentRecord class implementation
+
+Source: `src/agent-record.ts` (new file).
+Exports: `AgentRecord` class, `AgentRecordInit` interface, `AgentRecordStatus` type.
+All fields public initially (encapsulation deferred to cycle 6).
+
+All cycle 1 tests pass.
+
+Commit: `feat: create AgentRecord class with transition methods (#98)`
+
+### Cycle 3: Lift — migrate construction sites
+
+Changed files: `test/helpers/make-record.ts`, `src/agent-manager.ts`.
+
+`createTestRecord`: import `AgentRecord` from `agent-record.ts`; construct with `new AgentRecord(...)`.
+`agent-manager.ts`: import `AgentRecord` from `agent-record.ts` (value import); replace object literal in `spawn()` with `new AgentRecord(...)`.
+
+At this point, both the interface (in `types.ts`) and the class (in `agent-record.ts`) coexist.
+`agent-manager.ts` uses the class; all other consumers use the interface.
+Scattered field writes still work because fields are public.
+
+Run: full test suite + `pnpm run check`.
+
+Commit: `refactor: construct AgentRecord class in agent-manager and test factory (#98)`
+
+### Cycle 4: Shift — switch `types.ts` from interface to re-export
+
+Changed file: `src/types.ts`.
+
+Remove the `AgentRecord` interface definition.
+Add re-exports:
+
+```typescript
+export { AgentRecord } from "./agent-record.js";
+export type { AgentRecordInit, AgentRecordStatus } from "./agent-record.js";
+```
+
+All `import type { AgentRecord } from "./types.js"` across the codebase now resolve to the class.
+No consumer constructs `AgentRecord` as a plain object (construction was migrated in cycle 3).
+
+Run: `pnpm run check` (catches any structural incompatibilities).
+
+Commit: `refactor: replace AgentRecord interface with class re-export in types.ts (#98)`
+
+### Cycle 5: Replace scattered field writes with transition methods
+
+Changed file: `src/agent-manager.ts`.
+
+Replace all 11 transition sites:
+
+| Location               | Before                                                             | After                                                               |
+| ---------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `startAgent()` running | `record.status = "running"; record.startedAt = ...`                | `record.markRunning(Date.now())`                                    |
+| `.then()` success      | `if (!stopped) status = ...; result = ...; completedAt ??= ...`    | `record.markCompleted(finalResult)` / `markAborted` / `markSteered` |
+| `.catch()` error       | `if (!stopped) status = "error"; error = ...; completedAt ??= ...` | `record.markError(err)`                                             |
+| `resume()` reset       | `status = ...; startedAt = ...; clear 3 fields`                    | `record.resetForResume(Date.now())`                                 |
+| `resume()` try         | `status = "completed"; result = ...; completedAt = ...`            | `record.markCompleted(responseText)`                                |
+| `resume()` catch       | `status = "error"; error = ...; completedAt = ...`                 | `record.markError(err)`                                             |
+| `abort()` queued       | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abort()` running      | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abortAll()` queued    | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abortAll()` running   | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `drainQueue()` catch   | `status = "error"; error = ...; completedAt = ...`                 | `record.markError(err)`                                             |
+
+Also reorder the `.then()` block: worktree cleanup moves before the transition call so the final result includes worktree branch text (see Design Overview).
+
+Run: full test suite.
+
+Commit: `refactor: replace scattered status transitions with AgentRecord methods (#98)`
+
+### Cycle 6: Encapsulate transition fields
+
+Changed file: `src/agent-record.ts`.
+
+Make `status`, `result`, `error`, `startedAt`, `completedAt` private (`_status`, `_result`, etc.) with public getters.
+Make `id`, `type`, `description`, `invocation` readonly.
+
+Run: `pnpm run check` — verifies no remaining direct writes to encapsulated fields anywhere in `src/` or `test/`.
+Run: full test suite.
+
+Commit: `refactor: encapsulate AgentRecord transition state (#98)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                   | Mitigation                                                                                                      |
+| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Guard semantics drift: transition methods might not exactly match scattered guards                                     | Each method's guard logic has dedicated tests (cycle 1); full agent-manager test suite runs after each cycle    |
+| Data fields on stopped records: `markCompleted` etc. must still set `result`/`completedAt` even when status is guarded | Explicit "stopped guard" test cases verify data fields are set; mirrors current `.then()` / `.catch()` behavior |
+| Worktree result-append after encapsulation: direct `record.result = ...` no longer compiles                            | `.then()` block reordered to compute full result before calling transition method (cycle 5)                     |
+| `types.ts` re-export introduces type-only circular dependency                                                          | `agent-record.ts` → `types.ts` imports are `import type` only (erased at runtime); no runtime cycle             |
+| `resume()` gains a "stopped" guard it didn't have before                                                               | This is a correctness improvement: closes a latent abort race; noted explicitly in design                       |
+
+## Open Questions
+
+- The `markCompleted`/`markAborted`/`markSteered` split is not in the original issue's 5-method list (which only shows `markCompleted`).
+  The split is needed because the `.then()` block dispatches to 3 distinct terminal statuses.
+- Stat accumulation (`toolUses++`, `addUsage(lifetimeUsage, ...)`, `compactionCount++`) is left as direct field writes on public fields.
+  These could become methods in a follow-up if the callback-threading removal (architecture.md Step 3) makes it natural.

package/docs/retro/0102-consolidate-test-record-factory.md

@@ -0,0 +1,30 @@
+---
+issue: 102
+issue_title: "Consolidate test AgentRecord construction into a shared factory"
+---
+
+# Retro: #102 — Consolidate test AgentRecord construction into a shared factory
+
+## Final Retrospective (2026-05-20T15:30:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped a shared `createTestRecord()` factory in `test/helpers/make-record.ts`, migrating 7 test files from local factories and inline literals.
+The session completed in three slash-command phases (plan → TDD → ship) with zero rework, zero test failures, and zero deviations from the plan.
+Released as `pi-subagents-v6.0.1`.
+
+### Observations
+
+#### What went well
+
+- The Explore subagent surveyed all 8 test files' factory patterns in parallel, producing a structured comparison table that directly informed the plan's default-value decisions.
+- Before migrating `service-adapter.test.ts`, reading the `toSubagentRecord` source confirmed that `!== undefined` guards make absent-property vs. property-set-to-undefined semantically equivalent — avoiding a subtle test failure.
+- All 4 TDD steps passed on first run, confirming the plan's migration strategy (preserve old defaults via overrides) was sound.
+
+#### What caused friction (agent side)
+
+No friction points — the mechanical nature of the refactoring and the well-specified plan eliminated ambiguity.
+
+#### What caused friction (user side)
+
+No friction points — the three-phase slash-command workflow required no manual intervention.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-manager.ts

@@ -9,10 +9,11 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner, ToolActivity } from "./agent-runner.js";
 import { debugLog } from "./debug.js";
 import type { RunConfig } from "./runtime.js";
-import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentInvocation, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
 import type { WorktreeManager } from "./worktree.js";
 
@@ -133,18 +134,15 @@ export class AgentManager {
   ): string {
     const id = randomUUID().slice(0, 17);
     const abortController = new AbortController();
-    const record: AgentRecord = {
+    const record = new AgentRecord({
       id,
       type,
       description: options.description,
       status: options.isBackground ? "queued" : "running",
-      toolUses: 0,
       startedAt: Date.now(),
       abortController,
-      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
-      compactionCount: 0,
       invocation: options.invocation,
-    };
+    });
     this.agents.set(id, record);
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
@@ -184,8 +182,7 @@ export class AgentManager {
       worktreeCwd = wt.path;
     }
 
-    record.status = "running";
-    record.startedAt = Date.now();
+    record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
     this.onStart?.(record);
 
@@ -244,27 +241,26 @@ export class AgentManager {
       },
     })
       .then(({ responseText, session, aborted, steered, sessionFile }) => {
-        // Don't overwrite status if externally stopped via abort()
-        if (record.status !== "stopped") {
-          record.status = aborted ? "aborted" : steered ? "steered" : "completed";
-        }
-        record.result = responseText;
-        record.session = session;
-        record.completedAt ??= Date.now();
-        if (sessionFile) record.outputFile = sessionFile;
-
         detach();
 
-        // Clean up worktree if used
+        // Clean up worktree before transition so the final result includes branch text
+        let finalResult = responseText;
         if (record.worktree) {
           const wtResult = this.worktrees.cleanup(record.worktree, options.description);
           record.worktreeResult = wtResult;
           if (wtResult.hasChanges && wtResult.branch) {
-            record.result = (record.result ?? "") +
-              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+            finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
           }
         }
 
+        // Transition — guards against overwriting externally-stopped status
+        if (aborted) record.markAborted(finalResult);
+        else if (steered) record.markSteered(finalResult);
+        else record.markCompleted(finalResult);
+
+        record.session = session;
+        if (sessionFile) record.outputFile = sessionFile;
+
         if (options.isBackground) {
           this.runningBackground--;
           try { this.onComplete?.(record); } catch (err) { debugLog("onComplete callback", err); }
@@ -273,17 +269,10 @@ export class AgentManager {
         return responseText;
       })
       .catch((err) => {
-        // Don't overwrite status if externally stopped via abort()
-        if (record.status !== "stopped") {
-          record.status = "error";
-        }
-        record.error = err instanceof Error ? err.message : String(err);
-        record.completedAt ??= Date.now();
+        record.markError(err);
 
         detach();
 
-
-
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
@@ -314,9 +303,7 @@ export class AgentManager {
       } catch (err) {
         // Late failure (e.g. strict worktree-isolation) — surface on the record
         // so the user/agent can see it via /agents, then keep draining.
-        record.status = "error";
-        record.error = err instanceof Error ? err.message : String(err);
-        record.completedAt = Date.now();
+        record.markError(err);
         this.onComplete?.(record);
       }
     }
@@ -350,11 +337,7 @@ export class AgentManager {
     const record = this.agents.get(id);
     if (!record?.session) return undefined;
 
-    record.status = "running";
-    record.startedAt = Date.now();
-    record.completedAt = undefined;
-    record.result = undefined;
-    record.error = undefined;
+    record.resetForResume(Date.now());
 
     try {
       const responseText = await this.runner.resume(record.session, prompt, {
@@ -370,13 +353,9 @@ export class AgentManager {
         },
         signal,
       });
-      record.status = "completed";
-      record.result = responseText;
-      record.completedAt = Date.now();
+      record.markCompleted(responseText);
     } catch (err) {
-      record.status = "error";
-      record.error = err instanceof Error ? err.message : String(err);
-      record.completedAt = Date.now();
+      record.markError(err);
     }
 
     return record;
@@ -399,15 +378,13 @@ export class AgentManager {
     // Remove from queue if queued
     if (record.status === "queued") {
       this.queue = this.queue.filter(q => q.id !== id);
-      record.status = "stopped";
-      record.completedAt = Date.now();
+      record.markStopped();
       return true;
     }
 
     if (record.status !== "running") return false;
     record.abortController?.abort();
-    record.status = "stopped";
-    record.completedAt = Date.now();
+    record.markStopped();
     return true;
   }
 
@@ -452,8 +429,7 @@ export class AgentManager {
     for (const queued of this.queue) {
       const record = this.agents.get(queued.id);
       if (record) {
-        record.status = "stopped";
-        record.completedAt = Date.now();
+        record.markStopped();
         count++;
       }
     }
@@ -462,8 +438,7 @@ export class AgentManager {
     for (const record of this.agents.values()) {
       if (record.status === "running") {
         record.abortController?.abort();
-        record.status = "stopped";
-        record.completedAt = Date.now();
+        record.markStopped();
         count++;
       }
     }

package/src/agent-record.ts

@@ -0,0 +1,179 @@
+/**
+ * agent-record.ts — AgentRecord class with encapsulated status-transition logic.
+ *
+ * Status transitions (status, result, error, startedAt, completedAt) are owned
+ * by the class and exposed via transition methods. External code reads these
+ * fields through public properties but cannot write them directly.
+ *
+ * Non-transition state (session, toolUses, lifetimeUsage, etc.) remains public.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { AgentInvocation, SubagentType } from "./types.js";
+import type { LifetimeUsage } from "./usage.js";
+
+export type AgentRecordStatus =
+	| "queued"
+	| "running"
+	| "completed"
+	| "steered"
+	| "aborted"
+	| "stopped"
+	| "error";
+
+export interface AgentRecordInit {
+	id: string;
+	type: SubagentType;
+	description: string;
+	status?: AgentRecordStatus;
+	startedAt?: number;
+	completedAt?: number;
+	result?: string;
+	error?: string;
+	toolUses?: number;
+	lifetimeUsage?: LifetimeUsage;
+	compactionCount?: number;
+	abortController?: AbortController;
+	invocation?: AgentInvocation;
+	session?: AgentSession;
+	promise?: Promise<string>;
+	resultConsumed?: boolean;
+	pendingSteers?: string[];
+	worktree?: { path: string; branch: string };
+	worktreeResult?: { hasChanges: boolean; branch?: string };
+	toolCallId?: string;
+	outputFile?: string;
+}
+
+export class AgentRecord {
+	// Identity — set once at construction
+	readonly id: string;
+	readonly type: SubagentType;
+	readonly description: string;
+	readonly invocation?: AgentInvocation;
+
+	// Transition state — encapsulated behind getters, mutated only via transition methods
+	private _status: AgentRecordStatus;
+	get status(): AgentRecordStatus { return this._status; }
+
+	private _result?: string;
+	get result(): string | undefined { return this._result; }
+
+	private _error?: string;
+	get error(): string | undefined { return this._error; }
+
+	private _startedAt: number;
+	get startedAt(): number { return this._startedAt; }
+
+	private _completedAt?: number;
+	get completedAt(): number | undefined { return this._completedAt; }
+
+	// Non-transition mutable state
+	toolUses: number;
+	lifetimeUsage: LifetimeUsage;
+	compactionCount: number;
+	session?: AgentSession;
+	abortController?: AbortController;
+	promise?: Promise<string>;
+	resultConsumed?: boolean;
+	pendingSteers?: string[];
+	worktree?: { path: string; branch: string };
+	worktreeResult?: { hasChanges: boolean; branch?: string };
+	toolCallId?: string;
+	outputFile?: string;
+
+	constructor(init: AgentRecordInit) {
+		this.id = init.id;
+		this.type = init.type;
+		this.description = init.description;
+		this.invocation = init.invocation;
+
+		this._status = init.status ?? "queued";
+		this._result = init.result;
+		this._error = init.error;
+		this._startedAt = init.startedAt ?? Date.now();
+		this._completedAt = init.completedAt;
+
+		this.toolUses = init.toolUses ?? 0;
+		this.lifetimeUsage = init.lifetimeUsage ?? { input: 0, output: 0, cacheWrite: 0 };
+		this.compactionCount = init.compactionCount ?? 0;
+		this.abortController = init.abortController;
+		this.session = init.session;
+		this.promise = init.promise;
+		this.resultConsumed = init.resultConsumed;
+		this.pendingSteers = init.pendingSteers;
+		this.worktree = init.worktree;
+		this.worktreeResult = init.worktreeResult;
+		this.toolCallId = init.toolCallId;
+		this.outputFile = init.outputFile;
+	}
+
+	/** Transition to running state. Sets status and startedAt. */
+	markRunning(startedAt: number): void {
+		this._status = "running";
+		this._startedAt = startedAt;
+	}
+
+	/**
+	 * Transition to completed state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markCompleted(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "completed";
+		}
+	}
+
+	/**
+	 * Transition to aborted state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markAborted(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "aborted";
+		}
+	}
+
+	/**
+	 * Transition to steered state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markSteered(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "steered";
+		}
+	}
+
+	/**
+	 * Transition to error state.
+	 * Always sets error (formatted) and completedAt (??=). Only changes status if not stopped.
+	 */
+	markError(error: unknown, completedAt?: number): void {
+		this._error = error instanceof Error ? error.message : String(error);
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "error";
+		}
+	}
+
+	/** Transition to stopped state. Always valid — no guard. */
+	markStopped(completedAt?: number): void {
+		this._status = "stopped";
+		this._completedAt = completedAt ?? Date.now();
+	}
+
+	/** Reset for resume: running status, new startedAt, clear completedAt/result/error. */
+	resetForResume(startedAt: number): void {
+		this._status = "running";
+		this._startedAt = startedAt;
+		this._completedAt = undefined;
+		this._result = undefined;
+		this._error = undefined;
+	}
+}

package/src/types.ts

@@ -3,9 +3,10 @@
  */
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
-import type { LifetimeUsage } from "./usage.js";
 
+export type { AgentRecordInit, AgentRecordStatus } from "./agent-record.js";
+
+export { AgentRecord } from "./agent-record.js";
 export type { ThinkingLevel };
 
 /** Agent type: any string name (built-in defaults or user-defined). */
@@ -55,43 +56,6 @@ export interface AgentConfig {
   source?: "default" | "project" | "global";
 }
 
-export interface AgentRecord {
-  id: string;
-  type: SubagentType;
-  description: string;
-  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
-  result?: string;
-  error?: string;
-  toolUses: number;
-  startedAt: number;
-  completedAt?: number;
-  session?: AgentSession;
-  abortController?: AbortController;
-  promise?: Promise<string>;
-  /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
-  resultConsumed?: boolean;
-  /** Steering messages queued before the session was ready. */
-  pendingSteers?: string[];
-  /** Worktree info if the agent is running in an isolated worktree. */
-  worktree?: { path: string; branch: string };
-  /** Worktree cleanup result after agent completion. */
-  worktreeResult?: { hasChanges: boolean; branch?: string };
-  /** The tool_use_id from the original Agent tool call. */
-  toolCallId?: string;
-  /** Path to the persisted session transcript file. */
-  outputFile?: string;
-  /**
-   * Lifetime usage breakdown, accumulated via `message_end` events. Survives
-   * compaction. Total = input + output + cacheWrite (cacheRead deliberately
-   * excluded — see issue #38). Initialized to zeros at spawn.
-   */
-  lifetimeUsage: LifetimeUsage;
-  /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
-  compactionCount: number;
-  /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
-  invocation?: AgentInvocation;
-}
-
 export interface AgentInvocation {
   /** Short display name, e.g. "haiku" — only set when different from parent. */
   modelName?: string;