@aperant/framework 0.17.0 → 0.19.0

package/dist/cli/commands/task.mjs

@@ -38,6 +38,277 @@ import { atomicWriteJson } from '../util/io.mjs';
 import { err, exitWith, ok } from '../util/result.mjs';
 import { resolveMainRepoRoot } from '../util/state-paths.mjs';
 import { cmdCiWatch } from './ci-watch.mjs';
+/**
+ * Resolve the effective autonomy for a `task create` / `task ensure`
+ * invocation (ID-04). Layered fallback mirroring
+ * worktree.mjs:resolveCreateAutonomy — a `--autonomy <n>` flag wins; else the
+ * project config's `autonomy.default`; else 1 (the conservative
+ * confirm-by-default level). A non-numeric / out-of-range flag or config value
+ * is ignored. This kills the hardcoded-1 footgun: a caller that omits
+ * --autonomy now inherits config.autonomy.default instead of silently
+ * forwarding 1 to the worktree hook (which would spuriously trip the
+ * non-default-base deferral).
+ * @param {Map<string, string>} flags
+ * @param {Record<string, unknown>} config already-loaded merged project config
+ * @returns {number}
+ */
+export function resolveEffectiveAutonomy(flags, config) {
+    const raw = flags.get('autonomy');
+    if (raw !== undefined && raw !== null && raw !== '') {
+        const n = Number.parseInt(String(raw), 10);
+        if (Number.isFinite(n) && n >= 0 && n <= 3)
+            return n;
+    }
+    const def = config?.autonomy?.default;
+    if (typeof def === 'number' && Number.isFinite(def) && def >= 0 && def <= 3)
+        return def;
+    return 1;
+}
+/**
+ * Shared create-new allocation routine for `task create` and `task ensure`
+ * (ID-02). Owns the explicit-id safety checks, the withFileLock critical
+ * section (collision disambiguation + taskDir mkdir + task-record write +
+ * worktree hook), and the post-lock side effects (index regen + team status +
+ * task.created event + re-read of the created record).
+ *
+ * When `ensureKey` is set (the idempotent `task ensure --intent create-new`
+ * path, ID-03), the lock first scans active_tasks for a record already
+ * carrying that ensure_key (or the deterministic id with a matching
+ * track+scope) and, on a hit, RETURNS the existing record + worktree WITHOUT
+ * creating a second task/worktree (reused:true) — short-circuiting the
+ * collision disambiguator. On a miss it creates and stamps ensure_key.
+ *
+ * @returns {{ error?: any, taskId?: string, taskDir?: string, createdTask?: any, reused?: boolean }}
+ */
+function internalCreateTask(ctx) {
+    const { stateRoot, statePath, targetDir, store, config, description, track, autonomy, executionMode, scope, milestoneId, phaseIdForRoadmap, roadmapRefUrl, dependsOn, explicitIdRaw, assignedTo, ensureKey, } = ctx;
+    const SAFE_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+    if (explicitIdRaw && !SAFE_ID_PATTERN.test(explicitIdRaw)) {
+        return {
+            error: err('[apt-tools] Invalid task id: must match /^[A-Za-z0-9._-]+$/', 1, {
+                command: 'task-create',
+            }),
+        };
+    }
+    // Secondary guard: the resolved task directory must stay inside the tasks
+    // base (SAFE_ID_PATTERN allows '.'/'..').
+    if (explicitIdRaw) {
+        const tasksBase = resolve(join(stateRoot, '.aperant', 'tasks'));
+        const candidateDir = resolve(getTaskDir(stateRoot, explicitIdRaw));
+        if (!candidateDir.startsWith(`${tasksBase}/`) && candidateDir !== tasksBase) {
+            return {
+                error: err('[apt-tools] Invalid task id: path escapes the tasks directory', 1, {
+                    command: 'task-create',
+                }),
+            };
+        }
+    }
+    let taskId;
+    let taskDir;
+    let collisionOverflowErr = null;
+    let reused = false;
+    withFileLock(statePath, () => {
+        const raw = readFileSync(statePath, 'utf-8').trim();
+        const state = raw ? JSON.parse(raw) : {};
+        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 = {};
+        // ID-03 — idempotent reuse for `task ensure --intent create-new`. A
+        // record already carrying this ensure_key (or the deterministic id with
+        // a matching track+scope) short-circuits the collision disambiguator and
+        // returns the existing task + worktree.
+        if (ensureKey) {
+            const candidateId = explicitIdRaw || generateTaskId(description, config);
+            const existing = Object.values(state.active_tasks).find((t) => t &&
+                (t.ensure_key === ensureKey ||
+                    (t.id === candidateId &&
+                        (t.track || 'STANDARD') === track &&
+                        (t.scope || 'project') === scope)));
+            if (existing) {
+                taskId = existing.id;
+                taskDir = getTaskDir(stateRoot, taskId);
+                reused = true;
+                return;
+            }
+        }
+        // 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(stateRoot, 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;
+                }
+                candidate = `${base}-${counter}`;
+                counter++;
+            }
+            taskId = candidate;
+        }
+        taskDir = getTaskDir(stateRoot, taskId);
+        mkdirSync(taskDir, { recursive: true });
+        for (const subdir of ['events', 'locks']) {
+            mkdirSync(join(taskDir, subdir), { recursive: true });
+        }
+        const outputs = resolveDefaultOutputs({
+            id: taskId,
+            scope,
+            milestone_id: milestoneId,
+            phase_id: phaseIdForRoadmap,
+        });
+        state.active_tasks[taskId] = {
+            id: taskId,
+            description,
+            track,
+            autonomy,
+            ...(executionMode ? { execution_mode: executionMode } : {}),
+            // ID-03 — stamp the ensure_key so a re-run can short-circuit.
+            ...(ensureKey ? { ensure_key: ensureKey } : {}),
+            scope,
+            milestone_id: milestoneId,
+            phase_id: phaseIdForRoadmap,
+            roadmap_ref_url: roadmapRefUrl,
+            depends_on: dependsOn,
+            outputs,
+            assigned_to: assignedTo ?? null,
+            lifecycle_phase: 'planning',
+            history: [],
+            created_at: new Date().toISOString(),
+            progress: { subtasks_total: 0, subtasks_completed: 0, current_subtask: null },
+        };
+        // ── Task-level worktree hook ──────────────────────────────
+        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);
+                }
+                // ID-04 — forward the EFFECTIVE autonomy (already resolved from
+                // config.autonomy.default) so a non-default from_branch:current base
+                // does not spuriously trip the worktree.mjs autonomy<=1 deferral.
+                wtArgs.push('--autonomy', String(autonomy));
+                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);
+                    if (wtOut.status === 'requires_input' || wtOut.reason === 'non_default_base') {
+                        state.active_tasks[taskId].worktree_warning =
+                            `worktree deferred: non-default base — re-run worktree create with explicit --from (base would be '${wtOut.base_branch}', default '${wtOut.default_branch}')`;
+                        state.last_activity = new Date().toISOString();
+                        atomicWriteJson(statePath, state);
+                        return;
+                    }
+                    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;
+                    }
+                    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;
+                        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: stateRoot });
+    if (collisionOverflowErr)
+        return { error: collisionOverflowErr };
+    // Post-lock side-effects only run for a genuinely NEW task — a reused
+    // ensure hit must not re-emit task.created or re-register team status.
+    if (!reused) {
+        regenerateTaskIndex(stateRoot);
+        updateTeamMember(targetDir);
+        store.upsertTeamStatus(taskId, {
+            description,
+            lifecycle_phase: 'planning',
+            scope,
+        });
+        store.appendEvent({
+            op: 'task.created',
+            task: taskId,
+            data: {
+                description,
+                track,
+                scope,
+                milestone_id: milestoneId,
+                phase_id: phaseIdForRoadmap,
+            },
+        });
+    }
+    let createdTask = null;
+    if (existsSync(statePath)) {
+        try {
+            const s = JSON.parse(readFileSync(statePath, 'utf-8'));
+            createdTask = s.active_tasks?.[taskId] || null;
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return { taskId, taskDir, createdTask, reused };
+}
 export function cmdTask(subcommand, projectDir, extraArgs) {
     if (!subcommand)
         return err('Usage: apt-tools task <create|list|get|close|update|move|complete-subtask|narration-drain|prune> <project-dir> [flags]');
@@ -63,7 +334,6 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
             if (!description)
                 return err('Required: --description "task description"');
             const track = flags.get('track') || 'STANDARD';
-            const autonomy = parseInt(flags.get('autonomy') ?? '1', 10);
             // C21 — first-class execution_mode field. Accepts the same values as
             // the router's `--execution-mode` flag (validation lives in
             // task/execution-mode.mjs — single source of truth). Unset is allowed
@@ -134,273 +404,33 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
             catch {
                 config = {};
             }
-            // 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._-]+$/;
+            // ID-04 — resolve effective autonomy from the loaded config AFTER it is
+            // available: --autonomy flag → config.autonomy.default → 1. Replaces the
+            // former hardcoded `?? '1'` so a caller omitting --autonomy inherits the
+            // project default instead of silently forwarding 1 to the worktree hook.
+            const autonomy = resolveEffectiveAutonomy(flags, config);
             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(stateRoot, '.aperant', 'tasks'));
-                const candidateDir = resolve(getTaskDir(stateRoot, 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(stateRoot, 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;
-                        }
-                        candidate = `${base}-${counter}`;
-                        counter++;
-                    }
-                    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(stateRoot, 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,
-                    // FRAMEWORK-BUG-033 defect 2 — durable task→agent ownership.
-                    // Defaults to null at create time; fan-out workers (or the
-                    // `task update --assigned-to <agent-id>` path) populate it
-                    // when they claim the task. Persists across short-lived CLI
-                    // invocations unlike team-status/{agentId}.json (pid-keyed).
-                    assigned_to: flags.has('assigned-to') ? flags.get('assigned-to') : null,
-                    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);
-                        }
-                        // state-fork-fix ID-09b: forward the task's effective autonomy
-                        // so `worktree create` can pick the 0-1 confirm vs. 2-3 log
-                        // branch for a non-default `from_branch: current` base.
-                        wtArgs.push('--autonomy', String(autonomy));
-                        // 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-fork-fix ID-09b: a requires_input non-default-base
-                            // return (autonomy <= 1) is NOT a created worktree — degrade
-                            // it to a worktree_warning so task-create still SUCCEEDS
-                            // (task created, worktree deferred) instead of recording a
-                            // bogus undefined worktree_path. The operator re-runs
-                            // `worktree create` with an explicit --from.
-                            if (wtOut.status === 'requires_input' || wtOut.reason === 'non_default_base') {
-                                state.active_tasks[taskId].worktree_warning =
-                                    `worktree deferred: non-default base — re-run worktree create with explicit --from (base would be '${wtOut.base_branch}', default '${wtOut.default_branch}')`;
-                                state.last_activity = new Date().toISOString();
-                                atomicWriteJson(statePath, state);
-                                return;
-                            }
-                            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();
-                        }
-                    }
-                    catch (e) {
-                        state.active_tasks[taskId].worktree_warning = `worktree hook error: ${e.message}`;
-                    }
-                }
-                state.last_activity = new Date().toISOString();
-                atomicWriteJson(statePath, state);
-            }, { projectRoot: stateRoot });
-            if (collisionOverflowErr)
-                return collisionOverflowErr;
-            regenerateTaskIndex(stateRoot);
-            // Team collaboration: register user + add to active board
-            updateTeamMember(targetDir);
-            store.upsertTeamStatus(taskId, {
+            const created = internalCreateTask({
+                stateRoot,
+                statePath,
+                targetDir,
+                store,
+                config,
                 description,
-                lifecycle_phase: 'planning',
+                track,
+                autonomy,
+                executionMode,
                 scope,
+                milestoneId,
+                phaseIdForRoadmap,
+                roadmapRefUrl,
+                dependsOn,
+                explicitIdRaw,
+                assignedTo: flags.has('assigned-to') ? flags.get('assigned-to') : null,
             });
-            // R10 — forensic trail: emit task.created to the append-only
-            // JSONL log so operators can reconstruct history even when
-            // ephemeral state.json / team-status have been rotated.
-            store.appendEvent({
-                op: 'task.created',
-                task: taskId,
-                data: {
-                    description,
-                    track,
-                    scope,
-                    milestone_id: milestoneId,
-                    phase_id: phaseIdForRoadmap,
-                },
-            });
-            // Re-read task record so we can surface the worktree block to the
-            // router skill without duplicating state.
-            let createdTask = null;
-            if (existsSync(statePath)) {
-                try {
-                    const s = JSON.parse(readFileSync(statePath, 'utf-8'));
-                    createdTask = s.active_tasks?.[taskId] || null;
-                }
-                catch {
-                    /* best-effort */
-                }
-            }
+            if (created.error)
+                return created.error;
+            const { taskId, taskDir, createdTask } = created;
             const createOut = {
                 status: 'ok',
                 command: 'task-create',
@@ -425,6 +455,144 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
             }
             return ok(createOut);
         }
+        case 'ensure': {
+            // ID-02 — deterministic, idempotent allocator invoked by the /apt
+            // dispatch layer. The host emits a single schema-bounded
+            // allocation_intent bit; this command provisions (or no-ops)
+            // deterministically so worktree creation never depends on LLM prose.
+            const intent = flags.get('intent');
+            const VALID_INTENTS = ['create-new', 'require-existing', 'self-managed', 'none'];
+            if (!intent || !VALID_INTENTS.includes(intent)) {
+                return err(`Required: --intent <${VALID_INTENTS.join('|')}>`, 1, { command: 'task-ensure' });
+            }
+            // none / self-managed — allocate nothing.
+            if (intent === 'none' || intent === 'self-managed') {
+                return ok({
+                    status: 'ok',
+                    command: 'task-ensure',
+                    intent,
+                    allocated: false,
+                    reason: intent === 'none'
+                        ? 'allocation_intent=none — brainstorm/investigation/status/help allocates no task or worktree'
+                        : 'allocation_intent=self-managed — the skill owns its own task/worktree lifecycle',
+                });
+            }
+            // require-existing — resolve the active task; NEVER create one.
+            if (intent === 'require-existing') {
+                if (!existsSync(statePath)) {
+                    return ok({
+                        status: 'requires_input',
+                        command: 'task-ensure',
+                        intent,
+                        allocated: false,
+                        reason: 'no active tasks — require-existing cannot mint a new task',
+                    });
+                }
+                const state = JSON.parse(readFileSync(statePath, 'utf-8'));
+                const active = state.active_tasks && typeof state.active_tasks === 'object'
+                    ? Object.values(state.active_tasks)
+                    : [];
+                if (active.length === 1) {
+                    const task = active[0];
+                    const ensureOut = {
+                        status: 'ok',
+                        command: 'task-ensure',
+                        intent,
+                        allocated: false,
+                        reused: true,
+                        task_id: task.id,
+                        task_dir: getTaskDir(stateRoot, task.id),
+                        description: task.description,
+                        track: task.track,
+                    };
+                    if (task.worktree_path) {
+                        ensureOut.worktree = {
+                            worktree_path: task.worktree_path,
+                            branch: task.branch,
+                            base_branch: task.base_branch,
+                            remote_tracking: !!task.remote_tracking,
+                        };
+                    }
+                    return ok(ensureOut);
+                }
+                return ok({
+                    status: 'requires_input',
+                    command: 'task-ensure',
+                    intent,
+                    allocated: false,
+                    reason: active.length === 0
+                        ? 'no active tasks — require-existing cannot mint a new task'
+                        : `${active.length} active tasks — disambiguate before require-existing can resolve`,
+                });
+            }
+            // create-new — idempotent allocation via the shared helper (ID-03/ID-04).
+            const description = flags.get('description') || flags.get('desc');
+            if (!description)
+                return err('Required: --description "task description"');
+            const track = flags.get('track') || 'STANDARD';
+            const scope = (flags.get('scope') || 'project').trim() || 'project';
+            let config;
+            try {
+                config = loadMergedProjectConfig(targetDir) ?? {};
+            }
+            catch {
+                config = {};
+            }
+            // ID-04 — resolve effective autonomy BEFORE forwarding to the worktree
+            // hook so a non-default from_branch base does not spuriously defer.
+            const autonomy = resolveEffectiveAutonomy(flags, config);
+            // ID-03 — ensure-key keyed on normalized description + scope + intent.
+            const normalizedDescription = description.trim().toLowerCase().replace(/\s+/g, ' ');
+            const ensureKey = `${normalizedDescription}|${scope}|create-new`;
+            const allocated = internalCreateTask({
+                stateRoot,
+                statePath,
+                targetDir,
+                store,
+                config,
+                description,
+                track,
+                autonomy,
+                executionMode: null,
+                scope,
+                milestoneId: null,
+                phaseIdForRoadmap: null,
+                roadmapRefUrl: null,
+                dependsOn: [],
+                explicitIdRaw: flags.get('id'),
+                assignedTo: flags.has('assigned-to') ? flags.get('assigned-to') : null,
+                ensureKey,
+            });
+            if (allocated.error)
+                return allocated.error;
+            const ensureOut = {
+                status: 'ok',
+                command: 'task-ensure',
+                intent,
+                allocated: true,
+                reused: !!allocated.reused,
+                task_id: allocated.taskId,
+                task_dir: allocated.taskDir,
+                description,
+                track,
+                autonomy,
+            };
+            const t = allocated.createdTask;
+            if (t?.worktree_path) {
+                ensureOut.worktree = {
+                    worktree_path: t.worktree_path,
+                    branch: t.branch,
+                    base_branch: t.base_branch,
+                    remote_tracking: !!t.remote_tracking,
+                };
+                if (t.push_warning)
+                    ensureOut.worktree.push_warning = t.push_warning;
+            }
+            if (t?.worktree_warning) {
+                ensureOut.worktree_warning = t.worktree_warning;
+            }
+            return ok(ensureOut);
+        }
         case 'list': {
             if (!existsSync(statePath)) {
                 return ok({ status: 'ok', command: 'task-list', tasks: [], count: 0 });
@@ -960,9 +1128,9 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
                 }
                 // FRAMEWORK-BUG-033 defect 2 — durable task→agent ownership.
                 // Mutable owner field; fan-out workers write
-                // `fanout-${batch}-${task}` on claim, conductor reads to
+                // `fanout-${batch}-${task}` on claim, showrunner reads to
                 // resolve crash recovery (which worker owned T1 when the
-                // conductor died?).
+                // showrunner died?).
                 if (flags.has('assigned-to')) {
                     task.assigned_to = flags.get('assigned-to');
                 }