@aperant/framework 0.13.0 → 0.16.0

package/src/cli/commands/worktree.mjs

@@ -10,12 +10,14 @@
 import { execFileSync, execSync, spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { getTaskIsolationConfig } from '../config/load.mjs'
+import { getTaskIsolationConfig, loadProjectConfig } from '../config/load.mjs'
+import { materializeProjectEnvCli } from '../git/materialize-env.mjs'
 import { detectWorktree } from '../git/worktree-detect.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { resolveAptToolsBin } from '../util/bin-path.mjs'
 import { getSharedLockDir } from '../util/project.mjs'
 import { err, ok, UsageError } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 /**
  * Sentinel error class for helper-level usage failures inside cmdWorktree.
@@ -28,6 +30,98 @@ class WorktreeUsageError extends UsageError {
 	}
 }
 
+/**
+ * Resolve the effective autonomy for a `worktree create` invocation (ID-09b).
+ * Layered fallback: a `--autonomy <n>` flag (forwarded by the task.mjs auto-hook)
+ * wins; else the project config's `autonomy.default`; else 1 (the conservative
+ * confirm-by-default level). A non-numeric / out-of-range flag is ignored.
+ * @param {Map<string, string>} flags
+ * @param {string} targetDir
+ * @returns {number}
+ */
+function resolveCreateAutonomy(flags, targetDir) {
+	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
+	}
+	try {
+		const cfg = loadProjectConfig(targetDir)
+		const def = cfg?.autonomy?.default
+		if (Number.isFinite(def) && def >= 0 && def <= 3) return def
+	} catch {
+		/* config unreadable — fall through to the conservative default */
+	}
+	return 1
+}
+
+/**
+ * Resolve the current branch name (or 'HEAD' on detached/failure).
+ * @param {string} cwd
+ * @returns {string}
+ */
+function currentBranchName(cwd) {
+	try {
+		return execSync('git rev-parse --abbrev-ref HEAD', { cwd, encoding: 'utf-8' }).trim() || 'HEAD'
+	} catch {
+		return 'HEAD'
+	}
+}
+
+/**
+ * Main-detection chain — local refs only, no network (ID-02). Returns the
+ * detected default branch (e.g. `origin/main`, `main`, `master`) or null when
+ * the repo has no main/master ref anywhere. Extracted so the `current`-branch
+ * surfacing (ID-09b) can compare against the same detected default the
+ * `from_branch: main` path uses.
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function detectDefaultBranch(cwd) {
+	const candidates = ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master']
+	for (const ref of candidates) {
+		try {
+			const out = execSync(`git rev-parse --verify ${ref}`, {
+				cwd,
+				encoding: 'utf-8',
+				stdio: ['ignore', 'pipe', 'pipe'],
+			}).trim()
+			if (out) {
+				// origin/HEAD is a symref — resolve it to e.g. `origin/main`
+				// so the base branch we hand to `git worktree add` is usable.
+				if (ref === 'origin/HEAD') {
+					try {
+						const sym = execSync('git symbolic-ref refs/remotes/origin/HEAD', {
+							cwd,
+							encoding: 'utf-8',
+							stdio: ['ignore', 'pipe', 'pipe'],
+						}).trim()
+						return sym.replace(/^refs\/remotes\//, '') || ref
+					} catch {
+						return ref
+					}
+				}
+				return ref
+			}
+		} catch {
+			// Ref doesn't exist — try the next one.
+		}
+	}
+	return null
+}
+
+/**
+ * Normalize a detected default branch to its bare branch name for comparison
+ * with the current branch (e.g. `origin/main` → `main`). The current branch is
+ * always a local bare name, so strip a single leading remote segment.
+ * @param {string|null} ref
+ * @returns {string|null}
+ */
+function bareBranchName(ref) {
+	if (!ref) return null
+	return ref.replace(/^origin\//, '')
+}
+
 export function cmdDetectWorktree(projectDir) {
 	if (!projectDir) return err('Usage: apt-tools detect-worktree <project-dir>')
 	const wt = detectWorktree(projectDir)
@@ -42,9 +136,9 @@ export function cmdDetectWorktree(projectDir) {
 	})
 }
 
-export function cmdWorktree(subcommand, projectDir, extraArgs) {
+export async function cmdWorktree(subcommand, projectDir, extraArgs) {
 	if (!subcommand || !projectDir) {
-		return err('Usage: apt-tools worktree <create|remove|list> <dir> [options]')
+		return err('Usage: apt-tools worktree <create|remove|list|sync-env> <dir> [options]')
 	}
 
 	const targetDir = resolve(projectDir)
@@ -56,13 +150,23 @@ export function cmdWorktree(subcommand, projectDir, extraArgs) {
 	try {
 		switch (subcommand) {
 			case 'create':
-				return doCreate(subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANCH_PATTERN)
+				return await doCreate(
+					subcommand,
+					targetDir,
+					extraArgs,
+					SAFE_ID_PATTERN,
+					SAFE_BRANCH_PATTERN,
+				)
 			case 'remove':
 				return doRemove(subcommand, targetDir, extraArgs, SAFE_ID_PATTERN)
 			case 'list':
 				return doList(targetDir)
+			case 'sync-env':
+				return await doSyncEnv(targetDir, extraArgs, SAFE_ID_PATTERN)
 			default:
-				return err('Unknown worktree subcommand: ' + subcommand + '. Use create, remove, or list.')
+				return err(
+					'Unknown worktree subcommand: ' + subcommand + '. Use create, remove, list, or sync-env.',
+				)
 		}
 	} catch (e) {
 		if (e instanceof WorktreeUsageError) return err(e.message)
@@ -70,7 +174,7 @@ export function cmdWorktree(subcommand, projectDir, extraArgs) {
 	}
 }
 
-function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANCH_PATTERN) {
+async function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANCH_PATTERN) {
 	const flags = parseFlags(extraArgs)
 	const subtaskId = flags.get('subtask')
 	const taskId = flags.get('task')
@@ -88,13 +192,21 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 			throw new WorktreeUsageError('Invalid task ID: must match [a-zA-Z0-9_-]. Got: ' + taskId)
 		}
 
+		// state-fork-fix ID-09a: ANCHOR AT MAIN. Task-mode worktree creation can
+		// now run from inside a worktree (the sub-agent / dropped-cd model) — it
+		// retargets to the main repo instead of hard-erroring. The worktree path,
+		// the mkdirSync parent, the `git worktree add` cwd, AND the scope state-read
+		// ALL resolve off this one anchorRoot so they can never drift.
+		const anchorRoot = resolveMainRepoRoot(targetDir)
+
 		// C28 — scope propagation into worktree path. If --scope is not
 		// passed, look it up from state.json so external callers keep
-		// working without knowing the scope.
+		// working without knowing the scope. Reads off anchorRoot (the main
+		// board), since an empty worktree board would mis-resolve the scope.
 		let taskScope = flags.get('scope')
 		if (!taskScope) {
 			try {
-				const sp = join(targetDir, '.aperant', 'state.json')
+				const sp = join(anchorRoot, '.aperant', 'state.json')
 				if (existsSync(sp)) {
 					const st = JSON.parse(readFileSync(sp, 'utf-8'))
 					taskScope = st?.active_tasks?.[taskId]?.scope || 'project'
@@ -121,69 +233,59 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 		}
 
 		// Resolve base branch: --from beats config beats default chain.
+		// state-fork-fix ID-09b: default to the repo DEFAULT branch and make a
+		// surprising non-default current base EXPLICIT. The discriminator is
+		// "did the user ask for `current` on THIS invocation (--from) vs. did it
+		// fall through from a `from_branch: current` config default?".
 		const fromFlag = flags.get('from')
 		const fromPref = fromFlag || isolation.from_branch || 'main'
+		// Resolve against the anchored MAIN repo (ID-09a) so the detected default
+		// + current branch are read from the same repo the worktree is added to.
 		let baseBranch = fromPref
+		let baseBranchSource = null
+		let baseBranchNote = null
 		if (fromPref === 'current' || fromPref === 'HEAD') {
-			// Explicit opt-in to chaining onto the user's current branch (AC8).
-			try {
-				baseBranch =
-					execSync('git rev-parse --abbrev-ref HEAD', {
-						cwd: targetDir,
-						encoding: 'utf-8',
-					}).trim() || 'HEAD'
-			} catch {
-				baseBranch = 'HEAD'
-			}
-		} else if (fromPref === 'main') {
-			// Main-detection chain — local refs only, no network (per ID-02).
-			const candidates = ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master']
-			let resolved = null
-			for (const ref of candidates) {
-				try {
-					const out = execSync(`git rev-parse --verify ${ref}`, {
-						cwd: targetDir,
-						encoding: 'utf-8',
-						stdio: ['ignore', 'pipe', 'pipe'],
-					}).trim()
-					if (out) {
-						// origin/HEAD is a symref — resolve it to e.g. `origin/main`
-						// so the base branch we hand to `git worktree add` is usable.
-						if (ref === 'origin/HEAD') {
-							try {
-								const sym = execSync('git symbolic-ref refs/remotes/origin/HEAD', {
-									cwd: targetDir,
-									encoding: 'utf-8',
-									stdio: ['ignore', 'pipe', 'pipe'],
-								}).trim()
-								resolved = sym.replace(/^refs\/remotes\//, '') || ref
-							} catch {
-								resolved = ref
-							}
-						} else {
-							resolved = ref
-						}
-						break
-					}
-				} catch {
-					// Ref doesn't exist — try the next one.
+			// `current` = the INVOKING context's branch (the worktree/cwd you are
+			// on), NOT the main repo's — that is the branch the user would
+			// silently stack onto. Worktrees share refs, so this branch is still
+			// resolvable from anchorRoot when `git worktree add` runs.
+			const cur = currentBranchName(targetDir)
+			baseBranch = cur
+			const detectedDefault = bareBranchName(detectDefaultBranch(anchorRoot))
+			const isNonDefault = !!detectedDefault && cur !== detectedDefault && cur !== 'HEAD'
+			// EXPLICIT --from current/HEAD is intentional stacking → silent (AC13).
+			// A from_branch:'current' CONFIG default resolving to a non-default
+			// branch is the SURPRISING case that surfaces autonomy-aware.
+			const explicitCurrent = !!fromFlag
+			if (isNonDefault && !explicitCurrent) {
+				const autonomy = resolveCreateAutonomy(flags, targetDir)
+				if (autonomy <= 1) {
+					// Fail closed asking (C50/0.6.1 requires_input non-TTY contract):
+					// do NOT create until the caller re-invokes with explicit --from.
+					return ok({
+						status: 'requires_input',
+						command: 'worktree-create',
+						reason: 'non_default_base',
+						task_id: taskId,
+						scope: taskScope,
+						base_branch: cur,
+						default_branch: detectedDefault,
+						prompt: `base = ${cur} — fork from ${detectedDefault} instead? [${detectedDefault}/current]`,
+					})
 				}
+				// autonomy 2-3 — proceed, but LOG the chosen non-default base.
+				baseBranchSource = 'current-non-default'
+				baseBranchNote = `base branch '${cur}' is not the repo default '${detectedDefault}' (from_branch: current config default) — proceeding at autonomy ${autonomy}`
 			}
+		} else if (fromPref === 'main') {
+			const resolved = detectDefaultBranch(anchorRoot)
 			if (resolved) {
 				baseBranch = resolved
 			} else {
 				// Degenerate repo (no main/master ref anywhere). Fall back to
 				// current HEAD so users in detached or greenfield repos still
 				// get a working worktree instead of a hard error.
-				try {
-					baseBranch =
-						execSync('git rev-parse --abbrev-ref HEAD', {
-							cwd: targetDir,
-							encoding: 'utf-8',
-						}).trim() || 'HEAD'
-				} catch {
-					baseBranch = 'HEAD'
-				}
+				baseBranch = currentBranchName(anchorRoot)
 			}
 		}
 		// Any other explicit fromPref value (e.g. `origin/main`, `feature/foo`,
@@ -194,17 +296,12 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 			)
 		}
 
-		// Nested-worktree guard — same rule as subtask mode.
-		const wt = detectWorktree(targetDir)
-		if (wt.is_worktree) {
-			throw new WorktreeUsageError(
-				'Cannot create worktree: already inside a worktree at ' +
-					wt.worktree_root +
-					'. Nested worktrees are not supported.',
-			)
-		}
-
-		const worktreePath = join(targetDir, '.aperant', 'worktrees', taskScope, taskId)
+		// state-fork-fix ID-09a: NO nested-worktree hard-error in task mode. The
+		// task worktree is always created as a SIBLING under the MAIN repo's
+		// .aperant/worktrees/<scope>/<id> — invoking from inside a worktree (or a
+		// subdir) retargets to main instead of refusing. (The legacy subtask-mode
+		// path below keeps its nested-worktree refusal — back-compat only.)
+		const worktreePath = join(anchorRoot, '.aperant', 'worktrees', taskScope, taskId)
 		if (existsSync(worktreePath)) {
 			throw new WorktreeUsageError(
 				'Worktree already exists at ' +
@@ -214,11 +311,11 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 			)
 		}
 
-		mkdirSync(join(targetDir, '.aperant', 'worktrees', taskScope), { recursive: true })
+		mkdirSync(join(anchorRoot, '.aperant', 'worktrees', taskScope), { recursive: true })
 
 		try {
 			execFileSync('git', ['worktree', 'add', worktreePath, '-b', taskBranch, baseBranch], {
-				cwd: targetDir,
+				cwd: anchorRoot,
 				encoding: 'utf-8',
 				stdio: 'pipe',
 			})
@@ -226,6 +323,22 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 			throw new WorktreeUsageError('Failed to create worktree: ' + (e.stderr || e.message).trim())
 		}
 
+		// Materialize the project's stored env blobs into the fresh worktree
+		// (#354) — best-effort, traversal-guarded inside the helper, never aborts
+		// worktree creation. Surfaced on the envelope as `env_materialized`.
+		let envMaterialized = null
+		try {
+			envMaterialized = await materializeProjectEnvCli(
+				worktreePath,
+				targetDir,
+				flags.get('project-id'),
+			)
+		} catch {
+			// Defense in depth: the helper already swallows errors, but if it ever
+			// rejects we still must not fail the create.
+			envMaterialized = null
+		}
+
 		// Best-effort push: honor --push flag or config.push_on_create.
 		// Never abort on failure — users may have no network / no remote.
 		const shouldPush = pushOptIn || isolation.push_on_create === true
@@ -259,10 +372,16 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 				// resolution (env override → process.argv[1] → monorepo →
 				// consumer-install → $PATH). This file no longer reads
 				// process.argv[1] directly.
+				// state-fork-fix ID-09a: pass anchorRoot (NOT raw targetDir) as the
+				// project-dir. With the nested-worktree guard removed, doCreate can
+				// run from inside a worktree, and worktree-install writes EPHEMERAL
+				// tasks/<id>/install/ logs + a stubbed $HOME + a detached --finalize
+				// re-spawn off its project-dir — anchoring at main keeps those off the
+				// forked worktree board, consistent with the main-anchored worktreePath.
 				const wtInstallArgs = [
-					resolveAptToolsBin(targetDir),
+					resolveAptToolsBin(anchorRoot),
 					'worktree-install',
-					targetDir,
+					anchorRoot,
 					'--task',
 					taskId,
 					'--worktree',
@@ -334,6 +453,11 @@ function doCreate(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN, SAFE_BRANC
 		}
 		if (installBlock) createOut.install = installBlock
 		if (installWarning) createOut.install_warning = installWarning
+		if (envMaterialized) createOut.env_materialized = envMaterialized
+		// ID-09b: when proceeding with a non-default current base at autonomy 2-3,
+		// LOG the chosen base on the success envelope.
+		if (baseBranchSource) createOut.base_branch_source = baseBranchSource
+		if (baseBranchNote) createOut.base_branch_note = baseBranchNote
 		return ok(createOut)
 	}
 
@@ -414,10 +538,14 @@ function doRemove(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN) {
 		// C28 — resolve scope for {scope}/{task-id} path. Accept --scope,
 		// else read state.json, else fall back to scanning the worktree
 		// dir (handles orphaned worktrees whose task record is gone).
+		// state-fork-fix: anchor at main, matching doCreate (ID-09a).
+		const anchorRoot = resolveMainRepoRoot(targetDir)
+
 		let taskScope = flags.get('scope') || null
 		if (!taskScope) {
 			try {
-				const sp = join(targetDir, '.aperant', 'state.json')
+				// state-fork-fix: ephemeral scope read resolves to the main board.
+				const sp = join(anchorRoot, '.aperant', 'state.json')
 				if (existsSync(sp)) {
 					const st = JSON.parse(readFileSync(sp, 'utf-8'))
 					taskScope = st?.active_tasks?.[taskId]?.scope || null
@@ -429,7 +557,7 @@ function doRemove(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN) {
 		if (!taskScope) {
 			// Scan scope subdirs for a match.
 			try {
-				const root = join(targetDir, '.aperant', 'worktrees')
+				const root = join(anchorRoot, '.aperant', 'worktrees')
 				if (existsSync(root)) {
 					for (const entry of readdirSync(root, { withFileTypes: true })) {
 						if (entry.isDirectory() && existsSync(join(root, entry.name, taskId))) {
@@ -443,12 +571,15 @@ function doRemove(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN) {
 			}
 		}
 		taskScope = taskScope || 'project'
+		if (!SAFE_ID_PATTERN.test(taskScope)) {
+			throw new WorktreeUsageError('Invalid scope: must match [a-zA-Z0-9_-]. Got: ' + taskScope)
+		}
 
-		const worktreePath = join(targetDir, '.aperant', 'worktrees', taskScope, taskId)
+		const worktreePath = join(anchorRoot, '.aperant', 'worktrees', taskScope, taskId)
 		const args = ['worktree', 'remove', worktreePath]
 		if (force) args.push('--force')
 		try {
-			execFileSync('git', args, { cwd: targetDir, encoding: 'utf-8', stdio: 'pipe' })
+			execFileSync('git', args, { cwd: anchorRoot, encoding: 'utf-8', stdio: 'pipe' })
 		} catch (e) {
 			throw new WorktreeUsageError('Failed to remove worktree: ' + (e.stderr || e.message).trim())
 		}
@@ -458,7 +589,7 @@ function doRemove(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN) {
 			const taskBranch = `${isolation.branch_prefix || 'apt'}/${taskId}`
 			try {
 				execFileSync('git', ['branch', '-D', taskBranch], {
-					cwd: targetDir,
+					cwd: anchorRoot,
 					encoding: 'utf-8',
 					stdio: 'pipe',
 				})
@@ -507,10 +638,12 @@ function doRemove(_subcommand, targetDir, extraArgs, SAFE_ID_PATTERN) {
 }
 
 function doList(targetDir) {
+	// state-fork-fix: anchor at main so the prefix and git output share the same root.
+	const anchorRoot = resolveMainRepoRoot(targetDir)
 	let rawOutput
 	try {
 		rawOutput = execSync('git worktree list --porcelain', {
-			cwd: targetDir,
+			cwd: anchorRoot,
 			encoding: 'utf-8',
 			stdio: 'pipe',
 		})
@@ -520,7 +653,7 @@ function doList(targetDir) {
 
 	// Parse porcelain output — each worktree block separated by blank line
 	const worktrees = []
-	const aperantPrefix = join(targetDir, '.aperant', 'worktrees')
+	const aperantPrefix = join(anchorRoot, '.aperant', 'worktrees')
 	const blocks = rawOutput.trim().split('\n\n')
 	for (const block of blocks) {
 		const lines = block.trim().split('\n')
@@ -562,3 +695,87 @@ function doList(targetDir) {
 		worktrees: worktrees,
 	})
 }
+
+/**
+ * `apt-tools worktree sync-env <dir> --task <id> [--scope <scope>] [--project-id <id>]`
+ *
+ * Re-materialize the project's stored env blobs into an existing task worktree
+ * (ID-07). The store is the source of truth — sync-env OVERWRITES the worktree
+ * files; there is no two-way merge. Used for long-lived worktrees that drifted
+ * after the source env changed in the store.
+ */
+async function doSyncEnv(targetDir, extraArgs, SAFE_ID_PATTERN) {
+	const flags = parseFlags(extraArgs)
+	const taskId = flags.get('task')
+	if (!taskId) {
+		throw new WorktreeUsageError(
+			'Usage: apt-tools worktree sync-env <dir> --task <id> [--scope <scope>] [--project-id <id>]',
+		)
+	}
+	if (!SAFE_ID_PATTERN.test(taskId)) {
+		throw new WorktreeUsageError('Invalid task ID: must match [a-zA-Z0-9_-]. Got: ' + taskId)
+	}
+
+	// state-fork-fix: anchor at main, matching doCreate (ID-09a).
+	const anchorRoot = resolveMainRepoRoot(targetDir)
+
+	// Resolve scope the same way doRemove does: --scope, else state.json, else
+	// scan the worktrees dir for a matching task subdir.
+	let taskScope = flags.get('scope') || null
+	if (!taskScope) {
+		try {
+			// state-fork-fix: ephemeral scope read resolves to the main board.
+			const sp = join(anchorRoot, '.aperant', 'state.json')
+			if (existsSync(sp)) {
+				const st = JSON.parse(readFileSync(sp, 'utf-8'))
+				taskScope = st?.active_tasks?.[taskId]?.scope || null
+			}
+		} catch {
+			/* ignore */
+		}
+	}
+	if (!taskScope) {
+		try {
+			const root = join(anchorRoot, '.aperant', 'worktrees')
+			if (existsSync(root)) {
+				for (const entry of readdirSync(root, { withFileTypes: true })) {
+					if (entry.isDirectory() && existsSync(join(root, entry.name, taskId))) {
+						taskScope = entry.name
+						break
+					}
+				}
+			}
+		} catch {
+			/* ignore */
+		}
+	}
+	taskScope = (taskScope || 'project').trim() || 'project'
+	// Validate scope BEFORE it is joined into the worktree path (mirrors
+	// doCreate). An unvalidated scope (e.g. `--scope ../../etc`) would let the
+	// resolved worktree root escape `.aperant/worktrees/`, and sync-env writes
+	// secret env blobs into that root — so reject anything outside [a-zA-Z0-9_-].
+	if (!SAFE_ID_PATTERN.test(taskScope)) {
+		throw new WorktreeUsageError('Invalid scope: must match [a-zA-Z0-9_-]. Got: ' + taskScope)
+	}
+
+	const worktreePath = join(anchorRoot, '.aperant', 'worktrees', taskScope, taskId)
+	if (!existsSync(worktreePath)) {
+		throw new WorktreeUsageError(
+			'Worktree not found at ' +
+				worktreePath +
+				'. Create it first with: apt-tools worktree create <dir> --task ' +
+				taskId,
+		)
+	}
+
+	const result = await materializeProjectEnvCli(worktreePath, targetDir, flags.get('project-id'))
+
+	return ok({
+		status: 'ok',
+		command: 'worktree-sync-env',
+		task_id: taskId,
+		scope: taskScope,
+		worktree_path: worktreePath,
+		env_materialized: result,
+	})
+}

package/src/cli/config/post-merge-sweep.mjs

@@ -37,6 +37,7 @@ import { spawn } from 'node:child_process'
 import { closeSync, existsSync, openSync, readFileSync, statSync, writeSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 /**
  * Hot-path commands whose stderr feeds back into LLM-facing routers /
@@ -82,7 +83,7 @@ function getCooldownMs() {
  * @internal
  */
 export function readShippedCandidates(projectRoot) {
-	const statePath = join(projectRoot, '.aperant', 'state.json')
+	const statePath = join(resolveMainRepoRoot(projectRoot), '.aperant', 'state.json')
 	if (!existsSync(statePath)) return null
 	let state
 	try {
@@ -110,7 +111,7 @@ export function readShippedCandidates(projectRoot) {
  * @internal
  */
 export function readPendingNarrationCount(projectRoot) {
-	const statePath = join(projectRoot, '.aperant', 'state.json')
+	const statePath = join(resolveMainRepoRoot(projectRoot), '.aperant', 'state.json')
 	if (!existsSync(statePath)) return 0
 	try {
 		const state = JSON.parse(readFileSync(statePath, 'utf-8'))

package/src/cli/config/share-policy.mjs

@@ -23,7 +23,9 @@
  *     visibility: 'solo' | 'team' | 'oss',   // preset (unused after resolution
  *                                            //  except for diagnostics)
  *     roadmap:   boolean,                    // .aperant/roadmap/** *.json
- *     tasks:     boolean,                    // .aperant/tasks/ *\/ **
+ *     tasks:     boolean,                    // .aperant/tasks/ *\/ ** AND
+ *                                            //  .aperant/quick/ *\/ ** (quick is
+ *                                            //  a task track, shares this toggle)
  *     team:      { roster: boolean },        // .aperant/team.json
  *     decisions: boolean,                    // .aperant/decisions/ *.md
  *     digests:   boolean                     // .aperant/digests/ *.md (resolved
@@ -263,8 +265,11 @@ export function buildPolicyIgnoreMatcher(policy) {
 			return { ignored: true, class: 'ephemeral', reason: 'ephemeral' }
 		}
 
-		// Derived — always ignored (two-way write = drift).
-		if (rest === 'tasks/INDEX.md' || rest === 'decisions/INDEX.md') {
+		// Derived — always ignored (two-way write = drift). `quick/INDEX.md` is
+		// the QUICK-task analogue of `tasks/INDEX.md`: a regenerated markdown
+		// index whose visibility follows share.tasks via the per-record rule
+		// below, so the index itself is never tracked.
+		if (rest === 'tasks/INDEX.md' || rest === 'decisions/INDEX.md' || rest === 'quick/INDEX.md') {
 			return { ignored: true, class: 'derived', reason: 'derived' }
 		}
 		if (/^roadmap\/.*ROADMAP\.md$/.test(rest)) {
@@ -311,6 +316,14 @@ export function buildPolicyIgnoreMatcher(policy) {
 				? { ignored: false, class: 'shared-source', reason: null }
 				: { ignored: true, class: 'shared-source', reason: 'share.tasks=false' }
 		}
+		// QUICK-task records (quick/<task-id>/TASK.md, task.json, evidence/**)
+		// follow share.tasks — quick is a task track, not a separate share class.
+		// `quick/INDEX.md` is handled above as derived.
+		if (/^quick\/[^/]+\/.+/.test(rest)) {
+			return policy.tasks
+				? { ignored: false, class: 'shared-source', reason: null }
+				: { ignored: true, class: 'shared-source', reason: 'share.tasks=false' }
+		}
 
 		// Everything else under .aperant/ falls through to ignored (deny by
 		// default) — matches the template's leading `*` rule. Classed as