@aperant/framework 0.17.0 → 0.19.0

package/src/cli/commands/task.mjs

@@ -48,6 +48,319 @@ 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(
@@ -77,7 +390,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
@@ -150,293 +462,32 @@ 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(
+			const created = internalCreateTask({
+				stateRoot,
 				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, {
+				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',
@@ -462,6 +513,152 @@ 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 })
@@ -1051,9 +1248,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')
 					}