@aperant/framework 0.6.4 → 0.6.6

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()
@@ -14,7 +14,8 @@
 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 { getTaskIsolationConfig, loadProjectConfig } 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'
@@ -39,13 +40,14 @@ import { parseDuration } from '../util/duration.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { atomicWriteJson } from '../util/io.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { cmdCiWatch } from './ci-watch.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]')
+	if (!projectDir) return err(`Usage: apt-tools task ${subcommand} <project-dir> [flags]`)
 
 	const targetDir = resolve(projectDir)
 	const statePath = join(targetDir, '.aperant', 'state.json')
@@ -128,166 +130,233 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			// Load config for date format preference
 			const configPath = join(targetDir, '.aperant', 'config.json')
 			const config = existsSync(configPath) ? JSON.parse(readFileSync(configPath, 'utf-8')) : {}
-			const taskId = flags.get('id') || generateTaskId(description, config)
-
-			// Create task directory
-			const taskDir = getTaskDir(targetDir, taskId)
-			mkdirSync(taskDir, { recursive: true })
-			for (const subdir of ['events', 'locks']) {
-				mkdirSync(join(taskDir, subdir), { recursive: true })
+			// User-supplied --id bypasses the collision guard (caller owns the
+			// uniqueness contract). Generated ids run through a numeric-counter
+			// disambiguator that appends -2, -3, … when the candidate already
+			// exists in state or on disk. Bounded at 100 iterations as a
+			// defensive ceiling; same-day same-slug collisions are vanishingly
+			// rare so the loop should almost always terminate on the first try.
+			//
+			// BUG-2 fix: the candidate-selection scan, taskDir mkdir, and
+			// state.active_tasks write MUST all happen inside a single
+			// withFileLock critical section. Two concurrent task create calls
+			// in the multi-agent environment can otherwise both compute the
+			// same candidate against the same pre-lock snapshot of state and
+			// race into a duplicate-id write that silently overwrites the
+			// first task's record.
+			const SAFE_ID_PATTERN = /^[A-Za-z0-9._-]+$/
+			const explicitIdRaw = flags.get('id')
+			if (explicitIdRaw && !SAFE_ID_PATTERN.test(explicitIdRaw)) {
+				return err('[apt-tools] Invalid task id: must match /^[A-Za-z0-9._-]+$/', 1, {
+					command: 'task-create',
+				})
+			}
+			// Secondary guard: ensure the resolved task directory stays inside the
+			// tasks base. The SAFE_ID_PATTERN above blocks `/` and most traversal
+			// but allows `.` and `..` as valid characters. A lone `..` id would
+			// escape via getTaskDir's join: `tasks/..` resolves to `.aperant/`.
+			if (explicitIdRaw) {
+				const tasksBase = resolve(join(targetDir, '.aperant', 'tasks'))
+				const candidateDir = resolve(getTaskDir(targetDir, explicitIdRaw))
+				if (!candidateDir.startsWith(`${tasksBase}/`) && candidateDir !== tasksBase) {
+					return err('[apt-tools] Invalid task id: path escapes the tasks directory', 1, {
+						command: 'task-create',
+					})
+				}
 			}
 
-			// Register in state.json
-			if (existsSync(statePath)) {
-				withFileLock(
-					statePath,
-					() => {
-						const state = JSON.parse(readFileSync(statePath, 'utf-8'))
-
-						// Migrate: if old format (active_task singular), convert
-						if (state.active_task !== undefined && state.active_tasks === undefined) {
-							state.active_tasks = {}
-							if (state.active_task) {
-								const oldId = state.active_task.id || 'legacy-task'
-								state.active_tasks[oldId] = state.active_task
+			let taskId
+			let taskDir
+			let collisionOverflowErr = null
+
+			withFileLock(
+				statePath,
+				() => {
+					// Read state under the lock so the collision scan, taskDir
+					// mkdir, and state.active_tasks write all observe the same
+					// snapshot. withFileLock seeds an empty file if statePath
+					// doesn't exist, so the JSON.parse fallback handles the
+					// first-ever task create cleanly.
+					const raw = readFileSync(statePath, 'utf-8').trim()
+					const state = raw ? JSON.parse(raw) : {}
+
+					// Migrate: if old format (active_task singular), convert
+					if (state.active_task !== undefined && state.active_tasks === undefined) {
+						state.active_tasks = {}
+						if (state.active_task) {
+							const oldId = state.active_task.id || 'legacy-task'
+							state.active_tasks[oldId] = state.active_task
+						}
+						delete state.active_task
+					}
+					if (!state.active_tasks) state.active_tasks = {}
+
+					// Resolve taskId against the locked-in state snapshot.
+					if (explicitIdRaw) {
+						taskId = explicitIdRaw
+					} else {
+						const base = generateTaskId(description, config)
+						const activeIds = Object.keys(state.active_tasks)
+						const completedIds = Array.isArray(state.completed_tasks)
+							? state.completed_tasks.map((row) => row?.id).filter(Boolean)
+							: []
+						const known = new Set([...activeIds, ...completedIds])
+						const isTaken = (candidate) =>
+							known.has(candidate) || existsSync(getTaskDir(targetDir, candidate))
+						let candidate = base
+						let counter = 2
+						while (isTaken(candidate)) {
+							if (counter > 100) {
+								collisionOverflowErr = err(
+									`task create: collision counter exceeded 100 for base id "${base}" — manual --id required`,
+								)
+								return
 							}
-							delete state.active_task
+							candidate = `${base}-${counter}`
+							counter++
 						}
-						if (!state.active_tasks) state.active_tasks = {}
-
-						// Task-record lifecycle phase (NOT roadmap phase, NOT workflow phase).
-						// C28 D-02/D-03/D-08: scope + linkage + dependency-graph fields.
-						// R11 — resolve the outputs allowlist now so it is pinned at
-						// task creation time. If the planner edits the task record
-						// later (e.g. narrows the allowlist), it overwrites this.
-						const outputs = resolveDefaultOutputs({
-							id: taskId,
-							scope,
-							milestone_id: milestoneId,
-							phase_id: phaseIdForRoadmap,
-						})
+						taskId = candidate
+					}
 
-						state.active_tasks[taskId] = {
-							id: taskId,
-							description,
-							track,
-							autonomy,
-							// C21 — execution_mode is omitted entirely when unset so legacy
-							// readers (apt-plan SKILL.md 9a) continue to see `undefined`
-							// rather than `null` and fall through to the autonomy heuristic.
-							...(executionMode ? { execution_mode: executionMode } : {}),
-							scope,
-							milestone_id: milestoneId,
-							phase_id: phaseIdForRoadmap,
-							roadmap_ref_url: roadmapRefUrl,
-							depends_on: dependsOn,
-							outputs,
-							lifecycle_phase: 'planning',
-							history: [],
-							created_at: new Date().toISOString(),
-							progress: { subtasks_total: 0, subtasks_completed: 0, current_subtask: null },
-						}
+					// Create task directory under the lock so a concurrent
+					// run can't observe (and then re-pick) a half-created id.
+					taskDir = getTaskDir(targetDir, taskId)
+					mkdirSync(taskDir, { recursive: true })
+					for (const subdir of ['events', 'locks']) {
+						mkdirSync(join(taskDir, subdir), { recursive: true })
+					}
 
-						// ── Task-level worktree hook ──────────────────────────────
-						// When task_isolation.worktree_per_task is enabled AND we're
-						// not already inside a worktree AND the host supports them,
-						// fork a branch + worktree and record its location on the
-						// task record. Any failure is downgraded to a warning so
-						// task-create never aborts.
-						const isolation = getTaskIsolationConfig(targetDir)
-						const host = detectHost()
-						if (
-							isolation.worktree_per_task === true &&
-							host.capabilities.worktrees === true &&
-							!detectWorktree(targetDir).is_worktree
-						) {
-							try {
-								const wtArgs = ['--task', taskId, '--scope', scope]
-								if (isolation.push_on_create) wtArgs.push('--push')
-								if (isolation.from_branch && isolation.from_branch !== 'current') {
-									wtArgs.push('--from', isolation.from_branch)
+					// Task-record lifecycle phase (NOT roadmap phase, NOT workflow phase).
+					// C28 D-02/D-03/D-08: scope + linkage + dependency-graph fields.
+					// R11 — resolve the outputs allowlist now so it is pinned at
+					// task creation time. If the planner edits the task record
+					// later (e.g. narrows the allowlist), it overwrites this.
+					const outputs = resolveDefaultOutputs({
+						id: taskId,
+						scope,
+						milestone_id: milestoneId,
+						phase_id: phaseIdForRoadmap,
+					})
+
+					state.active_tasks[taskId] = {
+						id: taskId,
+						description,
+						track,
+						autonomy,
+						// C21 — execution_mode is omitted entirely when unset so legacy
+						// readers (apt-plan SKILL.md 9a) continue to see `undefined`
+						// rather than `null` and fall through to the autonomy heuristic.
+						...(executionMode ? { execution_mode: executionMode } : {}),
+						scope,
+						milestone_id: milestoneId,
+						phase_id: phaseIdForRoadmap,
+						roadmap_ref_url: roadmapRefUrl,
+						depends_on: dependsOn,
+						outputs,
+						lifecycle_phase: 'planning',
+						history: [],
+						created_at: new Date().toISOString(),
+						progress: { subtasks_total: 0, subtasks_completed: 0, current_subtask: null },
+					}
+
+					// ── Task-level worktree hook ──────────────────────────────
+					// When task_isolation.worktree_per_task is enabled AND we're
+					// not already inside a worktree AND the host supports them,
+					// fork a branch + worktree and record its location on the
+					// task record. Any failure is downgraded to a warning so
+					// task-create never aborts.
+					const isolation = getTaskIsolationConfig(targetDir)
+					const host = detectHost()
+					if (
+						isolation.worktree_per_task === true &&
+						host.capabilities.worktrees === true &&
+						!detectWorktree(targetDir).is_worktree
+					) {
+						try {
+							const wtArgs = ['--task', taskId, '--scope', scope]
+							if (isolation.push_on_create) wtArgs.push('--push')
+							if (isolation.from_branch && isolation.from_branch !== 'current') {
+								wtArgs.push('--from', isolation.from_branch)
+							}
+							// Invoke inline so we capture the structured payload
+							// without shelling back out. We cheat by calling the
+							// worktree creator directly as a subprocess to keep
+							// its output discipline intact, then parse its JSON.
+							//
+							// D-03 — single source of truth for the apt-tools binary
+							// path (replaces the legacy process.argv[1] heuristic).
+							const aptToolsBin = resolveAptToolsBin(targetDir)
+							const createRes = spawnSync(
+								process.execPath,
+								[aptToolsBin, 'worktree', 'create', targetDir, ...wtArgs],
+								{ encoding: 'utf-8' },
+							)
+							if (createRes.status === 0 && createRes.stdout) {
+								const wtOut = JSON.parse(createRes.stdout)
+								state.active_tasks[taskId].worktree_path = wtOut.worktree_path
+								state.active_tasks[taskId].branch = wtOut.branch
+								state.active_tasks[taskId].base_branch = wtOut.base_branch
+								state.active_tasks[taskId].remote_tracking = !!wtOut.remote_tracking
+								if (wtOut.scope) {
+									state.active_tasks[taskId].worktree_scope = wtOut.scope
 								}
-								// Invoke inline so we capture the structured payload
-								// without shelling back out. We cheat by calling the
-								// worktree creator directly as a subprocess to keep
-								// its output discipline intact, then parse its JSON.
-								//
-								// D-03 — single source of truth for the apt-tools binary
-								// path (replaces the legacy process.argv[1] heuristic).
-								const aptToolsBin = resolveAptToolsBin(targetDir)
-								const createRes = spawnSync(
-									process.execPath,
-									[aptToolsBin, 'worktree', 'create', targetDir, ...wtArgs],
-									{ encoding: 'utf-8' },
-								)
-								if (createRes.status === 0 && createRes.stdout) {
-									const wtOut = JSON.parse(createRes.stdout)
-									state.active_tasks[taskId].worktree_path = wtOut.worktree_path
-									state.active_tasks[taskId].branch = wtOut.branch
-									state.active_tasks[taskId].base_branch = wtOut.base_branch
-									state.active_tasks[taskId].remote_tracking = !!wtOut.remote_tracking
-									if (wtOut.scope) {
-										state.active_tasks[taskId].worktree_scope = wtOut.scope
-									}
-									if (wtOut.push_warning) {
-										state.active_tasks[taskId].push_warning = wtOut.push_warning
-									}
-									// C54 — merge install_* fields surfaced by the
-									// worktree-install hook in worktree.mjs. These fields are
-									// absent on pre-C54 default-config paths, so readers that
-									// don't know about install_* continue to work unchanged.
-									if (wtOut.install && typeof wtOut.install === 'object') {
-										const inst = wtOut.install
-										if (inst.install_status)
-											state.active_tasks[taskId].install_status = inst.install_status
-										if (inst.install_log_path)
-											state.active_tasks[taskId].install_log_path = inst.install_log_path
-										if (inst.install_pid !== undefined && inst.install_pid !== null)
-											state.active_tasks[taskId].install_pid = inst.install_pid
-										if (Array.isArray(inst.install_ecosystems))
-											state.active_tasks[taskId].install_ecosystems = inst.install_ecosystems
-										if (inst.install_started_at)
-											state.active_tasks[taskId].install_started_at = inst.install_started_at
-										if (inst.install_finished_at)
-											state.active_tasks[taskId].install_finished_at = inst.install_finished_at
-										if (inst.install_warning)
-											state.active_tasks[taskId].install_warning = inst.install_warning
-										// C54 review: persist the per-ecosystem breakdown and
-										// pre-spawn scanner rejections. worktree-install already
-										// wrote these directly via updateState; forwarding them
-										// through the stdout merge keeps the exposed fields
-										// consistent with the install envelope.
-										if (
-											inst.install_per_ecosystem &&
-											typeof inst.install_per_ecosystem === 'object'
-										)
-											state.active_tasks[taskId].install_per_ecosystem = inst.install_per_ecosystem
-										if (Array.isArray(inst.install_rejections))
-											state.active_tasks[taskId].install_rejections = inst.install_rejections
-									}
-									if (wtOut.install_warning && !state.active_tasks[taskId].install_warning) {
-										state.active_tasks[taskId].install_warning = wtOut.install_warning
-									}
-								} else {
-									state.active_tasks[taskId].worktree_warning =
-										'worktree create failed: ' +
-										(createRes.stderr || createRes.stdout || 'unknown')
-											.toString()
-											.trim()
-											.split('\n')
-											.pop()
+								if (wtOut.push_warning) {
+									state.active_tasks[taskId].push_warning = wtOut.push_warning
 								}
-							} catch (e) {
-								state.active_tasks[taskId].worktree_warning = 'worktree hook error: ' + e.message
+								// C54 — merge install_* fields surfaced by the
+								// worktree-install hook in worktree.mjs. These fields are
+								// absent on pre-C54 default-config paths, so readers that
+								// don't know about install_* continue to work unchanged.
+								if (wtOut.install && typeof wtOut.install === 'object') {
+									const inst = wtOut.install
+									if (inst.install_status)
+										state.active_tasks[taskId].install_status = inst.install_status
+									if (inst.install_log_path)
+										state.active_tasks[taskId].install_log_path = inst.install_log_path
+									if (inst.install_pid !== undefined && inst.install_pid !== null)
+										state.active_tasks[taskId].install_pid = inst.install_pid
+									if (Array.isArray(inst.install_ecosystems))
+										state.active_tasks[taskId].install_ecosystems = inst.install_ecosystems
+									if (inst.install_started_at)
+										state.active_tasks[taskId].install_started_at = inst.install_started_at
+									if (inst.install_finished_at)
+										state.active_tasks[taskId].install_finished_at = inst.install_finished_at
+									if (inst.install_warning)
+										state.active_tasks[taskId].install_warning = inst.install_warning
+									// C54 review: persist the per-ecosystem breakdown and
+									// pre-spawn scanner rejections. worktree-install already
+									// wrote these directly via updateState; forwarding them
+									// through the stdout merge keeps the exposed fields
+									// consistent with the install envelope.
+									if (inst.install_per_ecosystem && typeof inst.install_per_ecosystem === 'object')
+										state.active_tasks[taskId].install_per_ecosystem = inst.install_per_ecosystem
+									if (Array.isArray(inst.install_rejections))
+										state.active_tasks[taskId].install_rejections = inst.install_rejections
+								}
+								if (wtOut.install_warning && !state.active_tasks[taskId].install_warning) {
+									state.active_tasks[taskId].install_warning = wtOut.install_warning
+								}
+							} else {
+								state.active_tasks[taskId].worktree_warning =
+									'worktree create failed: ' +
+									(createRes.stderr || createRes.stdout || 'unknown')
+										.toString()
+										.trim()
+										.split('\n')
+										.pop()
 							}
+						} catch (e) {
+							state.active_tasks[taskId].worktree_warning = `worktree hook error: ${e.message}`
 						}
+					}
 
-						state.last_activity = new Date().toISOString()
-						atomicWriteJson(statePath, state)
-					},
-					{ projectRoot: targetDir },
-				)
-			}
+					state.last_activity = new Date().toISOString()
+					atomicWriteJson(statePath, state)
+				},
+				{ projectRoot: targetDir },
+			)
+
+			if (collisionOverflowErr) return collisionOverflowErr
 
 			regenerateTaskIndex(targetDir)
 
@@ -457,6 +526,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 +595,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 +798,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 +824,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`
@@ -786,6 +879,12 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					// This collapses the two-call apt:ship contract into a single
 					// load-bearing call so orchestrators can't drop the lifecycle
 					// transition. Idempotent / no-op on any other phase.
+					let ciWatchResult = {
+						ci_watch_armed: false,
+						ci_watch_skip_reason: null,
+						ci_watch: null,
+					}
+					let prUrlForCiWatch = null
 					if (flags.has('pr-url')) {
 						const url = flags.get('pr-url')
 						if (!url || typeof url !== 'string') {
@@ -821,6 +920,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 								},
 							})
 						}
+						prUrlForCiWatch = url
 					}
 					if (flags.has('subtasks-total'))
 						task.progress.subtasks_total = parseInt(flags.get('subtasks-total'), 10)
@@ -881,6 +981,9 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 
 					state.last_activity = new Date().toISOString()
 					atomicWriteJson(statePath, state)
+					if (prUrlForCiWatch) {
+						ciWatchResult = armCiWatchAfterPrUrl(targetDir, task, prUrlForCiWatch)
+					}
 
 					regenerateTaskIndex(targetDir)
 
@@ -899,6 +1002,11 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 
 					const updateOut = { status: 'ok', command: 'task-update', task_id: taskId, task }
 					if (lifecycleTransition) updateOut.transition = lifecycleTransition
+					if (flags.has('pr-url')) {
+						updateOut.ci_watch_armed = ciWatchResult.ci_watch_armed
+						updateOut.ci_watch_skip_reason = ciWatchResult.ci_watch_skip_reason
+						if (ciWatchResult.ci_watch) updateOut.ci_watch = ciWatchResult.ci_watch
+					}
 					updateResult = ok(updateOut)
 				},
 				{ projectRoot: targetDir },
@@ -1253,20 +1361,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 +1432,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 +1474,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
@@ -1354,7 +1544,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			const skipped = []
 
 			for (const row of state.completed_tasks || []) {
-				if (!row || !row.id) continue
+				if (!row?.id) continue
 				const rowScope = row.scope || 'project'
 				if (scopeFilter && rowScope !== scopeFilter) {
 					skipped.push({ id: row.id, reason: 'scope-mismatch' })
@@ -1426,11 +1616,81 @@ 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`,
 			)
 	}
 }
 
+function armCiWatchAfterPrUrl(targetDir, task, prUrl) {
+	const pr = extractPrNumber(prUrl)
+	if (!pr) {
+		return {
+			ci_watch_armed: false,
+			ci_watch_skip_reason: 'invalid-pr-url',
+			ci_watch: null,
+		}
+	}
+
+	const host = detectHost()
+	const defaultMode = host.capabilities?.cron ? 'auto' : 'never'
+	const config = loadProjectConfig(targetDir)
+	const configuredMode = config?.ci_watch?.after_ship || defaultMode
+	const mode = configuredMode === 'ask' && Number(task.autonomy) === 3 ? 'auto' : configuredMode
+
+	if (mode === 'never') {
+		return {
+			ci_watch_armed: false,
+			ci_watch_skip_reason: 'disabled',
+			ci_watch: null,
+		}
+	}
+
+	if (mode === 'ask') {
+		return {
+			ci_watch_armed: false,
+			ci_watch_skip_reason: 'ask-deferred',
+			ci_watch: null,
+		}
+	}
+
+	if (mode !== 'auto') {
+		return {
+			ci_watch_armed: false,
+			ci_watch_skip_reason: `invalid-config:${mode}`,
+			ci_watch: null,
+		}
+	}
+
+	const result = cmdCiWatch('start', targetDir, [
+		'--pr',
+		String(pr),
+		'--task-id',
+		task.id,
+		'--host',
+		host.cli || 'unknown',
+	])
+	const envelope = result?.envelope || {}
+	if (envelope.status === 'ok') {
+		return {
+			ci_watch_armed: true,
+			ci_watch_skip_reason: null,
+			ci_watch: envelope,
+		}
+	}
+	if (envelope.status === 'busy' && envelope.reason === 'already-armed') {
+		return {
+			ci_watch_armed: true,
+			ci_watch_skip_reason: 'already-armed',
+			ci_watch: envelope,
+		}
+	}
+	return {
+		ci_watch_armed: false,
+		ci_watch_skip_reason: envelope.reason || 'start-failed',
+		ci_watch: envelope,
+	}
+}
+
 /**
  * Extract a PR number from a GitHub URL like https://github.com/owner/repo/pull/123
  * or a short form like `owner/repo#123`. Returns null if not parseable.