@aperant/framework 0.6.4 → 0.6.5

package/src/cli/commands/task.mjs

@@ -1,7 +1,7 @@
 /**
  * commands/task.mjs — per-task isolated directories for multi-agent concurrency (C29).
  *
- * task subcommand: create | list | get | close | update | move | complete-subtask | prune
+ * task subcommand: create | list | get | close | update | move | complete-subtask | narration-drain | prune
  *
  * Layer 1 (post-CLI-layering refactor, subtask 9). cmdTask returns
  * { envelope, exitCode } — it MUST NOT call process.exit, output(), or fail()
@@ -15,6 +15,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { getTaskIsolationConfig } from '../config/load.mjs'
+import { findMostRecentEventForTask } from '../coordination/event-log.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { getGitIdentity } from '../git/identity.mjs'
 import { detectWorktree } from '../git/worktree-detect.mjs'
@@ -43,7 +44,7 @@ import { err, exitWith, ok } from '../util/result.mjs'
 export function cmdTask(subcommand, projectDir, extraArgs) {
 	if (!subcommand)
 		return err(
-			'Usage: apt-tools task <create|list|get|close|update|move|complete-subtask|prune> <project-dir> [flags]',
+			'Usage: apt-tools task <create|list|get|close|update|move|complete-subtask|narration-drain|prune> <project-dir> [flags]',
 		)
 	if (!projectDir) return err('Usage: apt-tools task ' + subcommand + ' <project-dir> [flags]')
 
@@ -457,6 +458,11 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			const taskId = flags.get('id')
 			if (!taskId) return err('Required: --id <task-id>')
 			const verdict = flags.get('verdict') || 'completed'
+			// Internal flag set by `task close-merged` when
+			// GitHub confirmed state === 'MERGED'. Threads through to
+			// computeWorktreeCleanup so cleanup skips local merge-back and
+			// runs fetch + ff-only instead.
+			const prMerged = flags.has('pr-merged-remotely')
 
 			if (!existsSync(statePath)) return err('No state.json found')
 
@@ -521,11 +527,14 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 
 					// Worktree cleanup hook — honors task_isolation.cleanup_on_close
 					// (never | ask | auto). See src/cli/task/worktree-cleanup.mjs.
+					// prMerged threads from `task close-merged`
+					// via --pr-merged-remotely; when true, cleanup runs fetch +
+					// ff-only instead of local merge-back.
 					let cleanup = null
 					if (task.worktree_path) {
 						const isolation = getTaskIsolationConfig(targetDir)
 						const mode = isolation.cleanup_on_close || 'ask'
-						cleanup = computeWorktreeCleanup(task, mode, targetDir)
+						cleanup = computeWorktreeCleanup(task, mode, targetDir, { prMerged })
 					}
 
 					// Best-effort team sync: commit shared bookkeeping so teammates
@@ -721,6 +730,21 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					let lifecycleTransition = null
 					if (flags.has('lifecycle-phase')) {
 						task.lifecycle_phase = flags.get('lifecycle-phase')
+						// R6 (roundtable 2026-05-14) — compute elapsed_ms since the
+						// previous LIFECYCLE event (or task.created) for phase-boundary
+						// telemetry. The 'task.lifecycle.' opPrefix is critical: without
+						// it, the most-recent event lookup picks up high-frequency events
+						// like task.tokens.recorded, which would silently corrupt
+						// elapsed_ms attribution (PR #115 review finding LOG-001).
+						const prev = findMostRecentEventForTask(targetDir, taskId, 'task.lifecycle.')
+						let prevTime = prev ? new Date(prev.t).getTime() : null
+						// LOG-003: when no prior lifecycle event exists (first transition),
+						// fall back to task.created_at so planning phase duration is captured.
+						if (!prevTime && task.created_at) {
+							const createdMs = new Date(task.created_at).getTime()
+							if (Number.isFinite(createdMs)) prevTime = createdMs
+						}
+						const elapsed_ms = prevTime ? Date.now() - prevTime : null
 						// R10 — emit the lifecycle transition event even when the
 						// side-effect helper decides the phase spec is a no-op; the
 						// caller still changed task.lifecycle_phase.
@@ -732,6 +756,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 								scope: task.scope || 'project',
 								milestone_id: task.milestone_id ?? null,
 								phase_id: task.phase_id ?? null,
+								elapsed_ms,
 							},
 						})
 						// C56 B5 — exhaustive lifecycle→roadmap-phase map. `null`
@@ -1253,20 +1278,27 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 				// Drive the full close path via an in-process CLI call so all of
 				// task close's side effects (team-sync, worktree cleanup, phase flip
 				// when auto_close_phase is on, event emission, INDEX regen) run.
-				const closeRes = spawnSync(
-					'node',
-					[
-						resolve(import.meta.dirname ?? '.', '..', '..', '..', 'bin', 'apt-tools.mjs'),
-						'task',
-						'close',
-						targetDir,
-						'--id',
-						id,
-						'--verdict',
-						closeVerdict,
-					],
-					{ cwd: targetDir, encoding: 'utf-8', env: { ...process.env } },
-				)
+				const closeArgs = [
+					resolve(import.meta.dirname ?? '.', '..', '..', '..', 'bin', 'apt-tools.mjs'),
+					'task',
+					'close',
+					targetDir,
+					'--id',
+					id,
+					'--verdict',
+					closeVerdict,
+				]
+				// Only signal pr_merged_remotely when GitHub
+				// confirmed MERGED. CLOSED-not-merged is a rejection path; leaving
+				// cleanup behavior unchanged there is intentional (spec §11 R3).
+				if (parsed.state === 'MERGED') {
+					closeArgs.push('--pr-merged-remotely')
+				}
+				const closeRes = spawnSync('node', closeArgs, {
+					cwd: targetDir,
+					encoding: 'utf-8',
+					env: { ...process.env },
+				})
 				if (closeRes.status !== 0) {
 					errors.push({
 						id,
@@ -1317,6 +1349,36 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					verdict: closeVerdict,
 					mergedAt: parsed.mergedAt ?? null,
 				})
+
+				// Append a pending_narration[] ledger entry on successful merged close
+				// so /apt:close-task --narrate-only can drain it later. The ledger is
+				// additive-only; failure to write must never undo the close above
+				// (R4 ledger leak — caller can manually invoke the narrator).
+				if (closeVerdict === 'approved') {
+					try {
+						withFileLock(
+							statePath,
+							() => {
+								const fresh = JSON.parse(readFileSync(statePath, 'utf-8'))
+								if (!Array.isArray(fresh.pending_narration)) fresh.pending_narration = []
+								fresh.pending_narration.push({
+									task_id: id,
+									scope: task.scope || 'project',
+									phase_id: task.phase_id ?? null,
+									closed_at: new Date().toISOString(),
+									pr_number: parsed.number ?? null,
+								})
+								atomicWriteJson(statePath, fresh)
+							},
+							{ projectRoot: targetDir },
+						)
+					} catch (e) {
+						errors.push({
+							id,
+							reason: `ledger-write-failed: ${e.message ?? String(e)}`,
+						})
+					}
+				}
 			}
 
 			return ok({
@@ -1329,6 +1391,51 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			})
 		}
 
+		case 'narration-drain': {
+			// Remove a single pending_narration[] row under the same withFileLock
+			// guard task close uses. Caller (apt:close-task --narrate-only) invokes
+			// this once per drained entry AFTER its background narrator spawn
+			// returns — so a spawn failure leaves the row in place for retry.
+			const taskId = flags.get('task')
+			if (!taskId) return err('Required: --task <task-id>')
+
+			if (!existsSync(statePath)) {
+				return ok({
+					status: 'ok',
+					command: 'task-narration-drain',
+					removed: null,
+					remaining: 0,
+					reason: 'no-state',
+				})
+			}
+
+			let removed = null
+			let remaining = 0
+			withFileLock(
+				statePath,
+				() => {
+					const state = JSON.parse(readFileSync(statePath, 'utf-8'))
+					const ledger = Array.isArray(state.pending_narration) ? state.pending_narration : []
+					const idx = ledger.findIndex((row) => row && row.task_id === taskId)
+					if (idx >= 0) {
+						removed = ledger[idx]
+						ledger.splice(idx, 1)
+						state.pending_narration = ledger
+						atomicWriteJson(statePath, state)
+					}
+					remaining = ledger.length
+				},
+				{ projectRoot: targetDir },
+			)
+
+			return ok({
+				status: 'ok',
+				command: 'task-narration-drain',
+				removed,
+				remaining,
+			})
+		}
+
 		case 'prune': {
 			// C56 A4 — retention verb. Removes `.aperant/tasks/{id}/` directories
 			// whose task row is in `state.completed_tasks[]` AND whose completion
@@ -1426,7 +1533,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 
 		default:
 			return err(
-				`Unknown task subcommand: ${subcommand}. Expected: create, list, get, close, update, move, complete-subtask, close-merged, prune`,
+				`Unknown task subcommand: ${subcommand}. Expected: create, list, get, close, update, move, complete-subtask, close-merged, narration-drain, prune`,
 			)
 	}
 }

package/src/cli/commands/tokens.mjs

@@ -10,10 +10,12 @@
  *   - state.active_tasks[id].tokens   — flat rolled-up summary (downstream).
  *
  * Subcommands:
- *   record   — append one entry from a Claude Code transcript or manual --input/--output.
- *   tally    — emit a TaskCostSummary computed via CostTracker.
- *   compare  — emit { aperant, baseline, ratio } (baseline JSON optional; C23 hook).
- *   list     — scan all .aperant/tasks/{*}/tokens.json and emit a flat sorted list.
+ *   record         — append one entry from a Claude Code transcript or manual --input/--output.
+ *   tally          — emit a TaskCostSummary computed via CostTracker.
+ *   compare        — emit { aperant, baseline, ratio } (baseline JSON optional; C23 hook).
+ *   list           — scan all .aperant/tasks/{*}/tokens.json and emit a flat sorted list.
+ *   phase-summary  — join tokens.json × task.lifecycle.* events by phase
+ *                    (roundtable 2026-05-14 R6 — phase-boundary telemetry).
  *
  * All writes go through atomicWriteJson + withFileLock (R3), state mutations
  * through createCoordinationStore.updateState (R8), and a lifecycle event is
@@ -29,6 +31,7 @@ import { dirname, join, resolve } from 'node:path'
 import { calculateCost } from '../../cost/pricing.mjs'
 import { CostTracker } from '../../cost/tracker.mjs'
 import { parseClaudeCodeTranscript } from '../../cost/transcript.mjs'
+import { readTaskEventsOverDays } from '../coordination/event-log.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { atomicWriteJson } from '../util/io.mjs'
@@ -67,6 +70,12 @@ function nowIso() {
 /**
  * Convert the on-disk JSON entry shape (snake_case + cost_usd) into the
  * canonical CostEntry shape used by CostTracker (camelCase + costUsd).
+ *
+ * R6 (roundtable 2026-05-14): `phase` is an optional per-entry tag indicating
+ * which pipeline phase (planning | executing | verifying | reviewing) the
+ * session belonged to. Carried through to enable `tokens phase-summary` to
+ * group by phase. Older entries lacking `phase` keep working — the field is
+ * additive and downstream consumers tolerate `undefined`.
  */
 function entryToCostEntry(taskId, entry) {
 	return {
@@ -82,6 +91,7 @@ function entryToCostEntry(taskId, entry) {
 		costUsd: typeof entry.cost_usd === 'number' ? entry.cost_usd : 0,
 		timestamp: entry.timestamp,
 		durationMs: entry.duration_ms || 0,
+		phase: entry.phase || null,
 	}
 }
 
@@ -162,6 +172,20 @@ function cmdRecord(targetDir, args) {
 	// DEFAULT_MODEL because there's no transcript to source it from.
 	const modelOverride = flagOf(args, '--model')
 	const providerId = flagOf(args, '--provider') || DEFAULT_PROVIDER
+	// R6 (roundtable 2026-05-14): optional --phase tags this batch of entries
+	// with the lifecycle phase they belong to. When omitted, phase-summary
+	// falls back to inferring phase from lifecycle event timestamps.
+	//
+	// SEC-001 (PR #115 review): whitelist accepted values to keep parity with
+	// --track (which also enforces a four-value allowlist). Unknown values
+	// fail closed rather than persisting arbitrary strings into tokens.json.
+	const phaseFlag = flagOf(args, '--phase')
+	const VALID_PHASES = new Set(['planning', 'executing', 'verifying', 'reviewing'])
+	if (phaseFlag !== null && !VALID_PHASES.has(phaseFlag)) {
+		throw new TokensUsageError(
+			`--phase must be one of: planning, executing, verifying, reviewing (got: ${phaseFlag})`,
+		)
+	}
 
 	if (!transcript && (inputStr === null || outputStr === null)) {
 		throw new TokensUsageError('Provide --transcript <path> OR both --input N --output N')
@@ -195,6 +219,7 @@ function cmdRecord(targetDir, args) {
 				timestamp: p.timestamp || ts,
 				source: 'transcript',
 				transcript_path: transcript,
+				...(phaseFlag ? { phase: phaseFlag } : {}),
 			})
 		}
 	} else {
@@ -222,6 +247,7 @@ function cmdRecord(targetDir, args) {
 			cost_usd: costUsd,
 			timestamp: nowIso(),
 			source: 'manual',
+			...(phaseFlag ? { phase: phaseFlag } : {}),
 		})
 	}
 
@@ -419,12 +445,135 @@ function cmdList(targetDir, args) {
 	})
 }
 
+/**
+ * Read lifecycle events for a task across today + yesterday (UTC).
+ * Returns events sorted ascending by `t`. Best-effort: missing event log
+ * directories return an empty array — phase-summary degrades gracefully
+ * when telemetry isn't enabled.
+ */
+function readTaskLifecycleEvents(targetDir, taskId) {
+	// Delegates to the shared two-day window helper in event-log.mjs so
+	// tokens.mjs and the lifecycle-event helpers cannot drift on the window
+	// strategy (PR #115 review findings QUA-001 + PRF-001).
+	const events = readTaskEventsOverDays(targetDir, taskId, 'task.lifecycle.')
+	events.sort((a, b) => Date.parse(a.t) - Date.parse(b.t))
+	return events
+}
+
+/**
+ * Infer phase for a token entry by finding the most recent lifecycle event
+ * whose timestamp <= entry timestamp. Returns null when no lifecycle event
+ * precedes the entry (e.g. entries recorded before any lifecycle transition).
+ */
+function inferPhaseForEntry(entryTime, lifecycleEvents) {
+	const entryMs = Date.parse(entryTime)
+	if (!Number.isFinite(entryMs)) return null
+	let match = null
+	for (const evt of lifecycleEvents) {
+		const evtMs = Date.parse(evt.t)
+		// LOG-002 (PR #115 review): a malformed evt.t parses to NaN. `NaN <=
+		// entryMs` is false, which would trip an `else break` and drop all
+		// subsequent valid events. Skip NaN entries instead so a single bad
+		// row can't poison phase inference.
+		if (!Number.isFinite(evtMs)) continue
+		if (evtMs <= entryMs) match = evt
+		else break
+	}
+	return match?.data?.lifecycle_phase ?? null
+}
+
+/**
+ * phase-summary — join tokens.json × task.lifecycle.* events by task_id +
+ * phase. Roundtable 2026-05-14 R6 — provides the A/B baseline needed to
+ * evaluate sequential vs sub-agents mode without per-call profiling.
+ *
+ * Each row: { phase, duration_ms, input_tokens, output_tokens, cost_usd, session_count }.
+ * Duration is summed from lifecycle event `elapsed_ms`. Tokens are summed
+ * from entries whose `phase` is set (or inferred from event timestamps when
+ * the entry has no `phase` tag).
+ */
+function cmdPhaseSummary(targetDir, args) {
+	const taskId = flagOf(args, '--task-id')
+	if (!taskId) throw new TokensUsageError('--task-id is required for tokens phase-summary')
+
+	const tokensPath = tokensFilePath(targetDir, taskId)
+	const doc = readTokensFile(tokensPath)
+	const entries = doc?.entries || []
+
+	const lifecycleEvents = readTaskLifecycleEvents(targetDir, taskId)
+
+	// Per-phase accumulator.
+	const phases = new Map()
+	function bump(phase, patch) {
+		if (!phase) return
+		if (!phases.has(phase)) {
+			phases.set(phase, {
+				phase,
+				duration_ms: 0,
+				input_tokens: 0,
+				output_tokens: 0,
+				cost_usd: 0,
+				session_count: 0,
+			})
+		}
+		const row = phases.get(phase)
+		row.duration_ms += patch.duration_ms || 0
+		row.input_tokens += patch.input_tokens || 0
+		row.output_tokens += patch.output_tokens || 0
+		row.cost_usd += patch.cost_usd || 0
+		row.session_count += patch.session_count || 0
+	}
+
+	// Sum durations from lifecycle events (elapsed_ms attributed to the phase
+	// THIS event represents — i.e. the phase that was just entered. The
+	// elapsed_ms is "time spent in the prior phase before transitioning into
+	// this one." Attribute to the prior phase to keep the model intuitive.
+	let priorPhase = null
+	for (const evt of lifecycleEvents) {
+		const elapsed = evt.data?.elapsed_ms
+		if (priorPhase && typeof elapsed === 'number') {
+			bump(priorPhase, { duration_ms: elapsed })
+		}
+		priorPhase = evt.data?.lifecycle_phase || null
+	}
+
+	// Sum tokens per phase. Prefer entry.phase when set; otherwise infer from
+	// lifecycle event timestamps.
+	for (const entry of entries) {
+		const phase = entry.phase || inferPhaseForEntry(entry.timestamp, lifecycleEvents)
+		if (!phase) continue
+		bump(phase, {
+			input_tokens: entry.input_tokens || 0,
+			output_tokens: entry.output_tokens || 0,
+			cost_usd: typeof entry.cost_usd === 'number' ? entry.cost_usd : 0,
+			session_count: 1,
+		})
+	}
+
+	const rows = Array.from(phases.values()).map((r) => ({
+		...r,
+		cost_usd: Number(r.cost_usd.toFixed(6)),
+	}))
+
+	return ok({
+		status: 'ok',
+		command: 'tokens',
+		action: 'phase-summary',
+		task_id: taskId,
+		entry_count: entries.length,
+		lifecycle_event_count: lifecycleEvents.length,
+		phases: rows,
+	})
+}
+
 /**
  * Top-level dispatcher.
  */
 export function cmdTokens(subcommand, projectDir, extraArgs = []) {
 	if (!subcommand) {
-		return err('Usage: apt-tools tokens <record|tally|compare|list> <project-dir> [flags]')
+		return err(
+			'Usage: apt-tools tokens <record|tally|compare|list|phase-summary> <project-dir> [flags]',
+		)
 	}
 	if (!projectDir) {
 		return err(`Usage: apt-tools tokens ${subcommand} <project-dir> [flags]`)
@@ -444,9 +593,11 @@ export function cmdTokens(subcommand, projectDir, extraArgs = []) {
 				return cmdCompare(targetDir, extraArgs)
 			case 'list':
 				return cmdList(targetDir, extraArgs)
+			case 'phase-summary':
+				return cmdPhaseSummary(targetDir, extraArgs)
 			default:
 				return err(
-					`Unknown tokens subcommand: ${subcommand}. Expected: record, tally, compare, list`,
+					`Unknown tokens subcommand: ${subcommand}. Expected: record, tally, compare, list, phase-summary`,
 				)
 		}
 	} catch (e) {