@aperant/framework 0.6.4 → 0.6.6

package/dist/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()
@@ -13,7 +13,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';
@@ -34,11 +35,12 @@ 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]');
+        return err('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]');
+        return err(`Usage: apt-tools task ${subcommand} <project-dir> [flags]`);
     const targetDir = resolve(projectDir);
     const statePath = join(targetDir, '.aperant', 'state.json');
     const flags = parseFlags(extraArgs);
@@ -115,151 +117,216 @@ 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',
+                });
             }
-            // 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;
+            // 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',
+                    });
+                }
+            }
+            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,
-                    });
-                    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);
+                    taskId = candidate;
+                }
+                // 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-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;
-                                }
+                            if (wtOut.push_warning) {
+                                state.active_tasks[taskId].push_warning = wtOut.push_warning;
                             }
-                            else {
-                                state.active_tasks[taskId].worktree_warning =
-                                    'worktree create failed: ' +
-                                        (createRes.stderr || createRes.stdout || 'unknown')
-                                            .toString()
-                                            .trim()
-                                            .split('\n')
-                                            .pop();
+                            // 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;
                             }
                         }
-                        catch (e) {
-                            state.active_tasks[taskId].worktree_warning = 'worktree hook error: ' + e.message;
+                        else {
+                            state.active_tasks[taskId].worktree_warning =
+                                'worktree create failed: ' +
+                                    (createRes.stderr || createRes.stdout || 'unknown')
+                                        .toString()
+                                        .trim()
+                                        .split('\n')
+                                        .pop();
                         }
                     }
-                    state.last_activity = new Date().toISOString();
-                    atomicWriteJson(statePath, state);
-                }, { projectRoot: targetDir });
-            }
+                    catch (e) {
+                        state.active_tasks[taskId].worktree_warning = `worktree hook error: ${e.message}`;
+                    }
+                }
+                state.last_activity = new Date().toISOString();
+                atomicWriteJson(statePath, state);
+            }, { projectRoot: targetDir });
+            if (collisionOverflowErr)
+                return collisionOverflowErr;
             regenerateTaskIndex(targetDir);
             // Team collaboration: register user + add to active board
             updateTeamMember(targetDir);
@@ -416,6 +483,11 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
             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');
             // withFileLock callback can produce either an error envelope (early
@@ -472,11 +544,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
                 // don't have to pick up orphaned diffs. Never fails task close.
@@ -653,6 +728,22 @@ 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.
@@ -664,6 +755,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`
@@ -710,6 +802,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') {
@@ -743,6 +841,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
                             },
                         });
                     }
+                    prUrlForCiWatch = url;
                 }
                 if (flags.has('subtasks-total'))
                     task.progress.subtasks_total = parseInt(flags.get('subtasks-total'), 10);
@@ -797,6 +896,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);
                 // Team collaboration: sync active board with updated state
                 updateTeamMember(targetDir);
@@ -812,6 +914,12 @@ 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 });
             return updateError ?? updateResult;
@@ -1126,7 +1234,7 @@ 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', [
+                const closeArgs = [
                     resolve(import.meta.dirname ?? '.', '..', '..', '..', 'bin', 'apt-tools.mjs'),
                     'task',
                     'close',
@@ -1135,7 +1243,18 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
                     id,
                     '--verdict',
                     closeVerdict,
-                ], { cwd: targetDir, encoding: 'utf-8', env: { ...process.env } });
+                ];
+                // 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,
@@ -1185,6 +1304,33 @@ 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({
                 status: 'ok',
@@ -1195,6 +1341,44 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
                 errors,
             });
         }
+        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
@@ -1219,7 +1403,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
             const pruned = [];
             const skipped = [];
             for (const row of state.completed_tasks || []) {
-                if (!row || !row.id)
+                if (!row?.id)
                     continue;
                 const rowScope = row.scope || 'project';
                 if (scopeFilter && rowScope !== scopeFilter) {
@@ -1290,8 +1474,72 @@ 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`);
+            return err(`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