@fitlab-ai/agent-infra 0.11.15 → 0.12.1

package/lib/task/resolve-ref.ts

@@ -3,12 +3,15 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { normalizeShortIdInput, resolveShortIdReadOnly } from './short-id.ts';
 import { parseTaskFrontmatter } from './frontmatter.ts';
+import { resolveProjectTaskWorkspaceRoot } from './workspace-root.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 // Flat-structured workspace dirs that hold tasks under `{dir}/{taskId}/task.md`.
 // Note: `archive` uses a three-level YYYY/MM/DD layout and is handled separately.
 const FLAT_WORKSPACE_DIRS = ['active', 'blocked', 'completed'] as const;
 
+function taskRoot(repoRoot: string): string { return resolveProjectTaskWorkspaceRoot(repoRoot); }
+
 type ResolveRefResult =
   | {
       ok: true;
@@ -80,12 +83,12 @@ function listSortedNumeric(dir: string, width: number): string[] {
     .reverse();
 }
 
-function findInArchive(repoRoot: string, taskId: string): string | null {
-  // archive-tasks stores local material at .agents/workspace/archive/YYYY/MM/DD/{taskId}/local/task.md
+function findInArchive(workspaceRoot: string, taskId: string): string | null {
+  // archive-tasks stores local material at the project task workspace archive/YYYY/MM/DD/{taskId}/local/task.md
   // where YYYY/MM/DD comes from completed_at (or updated_at fallback) — NOT from
   // the task id's creation date. So we cannot derive the path from taskId alone;
   // walk the bounded YYYY/MM/DD tree instead. Newest-first to favor recent archives.
-  const archiveDir = path.join(repoRoot, '.agents', 'workspace', 'archive');
+  const archiveDir = path.join(workspaceRoot, 'archive');
   for (const year of listSortedNumeric(archiveDir, 4)) {
     const yearDir = path.join(archiveDir, year);
     for (const month of listSortedNumeric(yearDir, 2)) {
@@ -100,14 +103,14 @@ function findInArchive(repoRoot: string, taskId: string): string | null {
 }
 
 function findTaskMd(
-  repoRoot: string,
+  workspaceRoot: string,
   taskId: string
 ): { taskMdPath: string; state: TaskWorkspaceState } | null {
   for (const sub of FLAT_WORKSPACE_DIRS) {
-    const candidate = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
+    const candidate = path.join(workspaceRoot, sub, taskId, 'task.md');
     if (fs.existsSync(candidate)) return { taskMdPath: candidate, state: sub };
   }
-  const archived = findInArchive(repoRoot, taskId);
+  const archived = findInArchive(workspaceRoot, taskId);
   return archived ? { taskMdPath: archived, state: 'archive' } : null;
 }
 
@@ -119,8 +122,9 @@ function findTaskMd(
  */
 function enumerateTaskDirs(repoRoot: string): { taskId: string; taskDir: string }[] {
   const out: { taskId: string; taskDir: string }[] = [];
+  const workspaceRoot = taskRoot(repoRoot);
   for (const sub of FLAT_WORKSPACE_DIRS) {
-    const base = path.join(repoRoot, '.agents', 'workspace', sub);
+    const base = path.join(workspaceRoot, sub);
     if (!fs.existsSync(base)) continue;
     for (const entry of fs.readdirSync(base).sort()) {
       if (!TASK_ID_RE.test(entry)) continue;
@@ -139,6 +143,7 @@ function enumerateTaskDirs(repoRoot: string): { taskId: string; taskDir: string
  */
 function enumerateAllTaskDirs(repoRoot: string): { taskId: string; taskDir: string; state: TaskWorkspaceState }[] {
   const out: { taskId: string; taskDir: string; state: TaskWorkspaceState }[] = [];
+  const workspaceRoot = taskRoot(repoRoot);
   const seen = new Map<string, string>();
   const add = (taskId: string, taskDir: string, state: TaskWorkspaceState) => {
     if (!TASK_ID_RE.test(taskId)) return;
@@ -155,12 +160,12 @@ function enumerateAllTaskDirs(repoRoot: string): { taskId: string; taskDir: stri
   };
 
   for (const state of FLAT_WORKSPACE_DIRS) {
-    const base = path.join(repoRoot, '.agents', 'workspace', state);
+    const base = path.join(workspaceRoot, state);
     if (!fs.existsSync(base)) continue;
     for (const taskId of fs.readdirSync(base).sort()) add(taskId, path.join(base, taskId), state);
   }
 
-  const archive = path.join(repoRoot, '.agents', 'workspace', 'archive');
+  const archive = path.join(workspaceRoot, 'archive');
   for (const year of listSortedNumeric(archive, 4).reverse()) {
     const yearDir = path.join(archive, year);
     for (const month of listSortedNumeric(yearDir, 2).reverse()) {
@@ -178,8 +183,9 @@ function locateHotTaskDirs(
   repoRoot: string,
   taskId: string
 ): { taskId: string; taskDir: string; taskMdPath: string; state: Exclude<TaskWorkspaceState, 'archive'> }[] {
+  const workspaceRoot = taskRoot(repoRoot);
   return FLAT_WORKSPACE_DIRS.flatMap((state) => {
-    const taskDir = path.join(repoRoot, '.agents', 'workspace', state, taskId);
+    const taskDir = path.join(workspaceRoot, state, taskId);
     const taskMdPath = path.join(taskDir, 'task.md');
     return fs.existsSync(taskMdPath) ? [{ taskId, taskDir, taskMdPath, state }] : [];
   });
@@ -244,7 +250,7 @@ function resolveTaskRef(arg: string, options: ResolveTaskRefOptions = {}): Resol
     }
     taskId = shortResult.taskId;
   }
-  const located = findTaskMd(repoRoot, taskId);
+  const located = findTaskMd(taskRoot(repoRoot), taskId);
   if (!located) {
     return {
       ok: false,
@@ -300,7 +306,7 @@ function resolveTaskContext(
     };
   }
 
-  const activeDir = path.join(repoRoot, '.agents', 'workspace', 'active');
+  const activeDir = path.join(taskRoot(repoRoot), 'active');
   const matches: { taskId: string; taskDir: string; taskMdPath: string }[] = [];
   if (fs.existsSync(activeDir)) {
     for (const entry of fs.readdirSync(activeDir).sort()) {

package/lib/task/review-finalization.ts

@@ -10,7 +10,6 @@ import { finalizeReviewSummaryContent } from './review-artifacts.ts';
 import { inspectDecisionDetailDuplicates } from './decision-details.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { validateLifecycleExecution } from './lifecycle-execution.ts';
-import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import type { ResolveTaskRefErrorCode } from './resolve-ref.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
 import { validateQualificationAudit } from './qualification-audit.ts';
@@ -69,7 +68,6 @@ type ReviewFileSystem = {
 type ReviewFinalizationOptions = {
   repoRoot?: string;
   fileSystem?: Partial<ReviewFileSystem>;
-  lockAlreadyHeld?: boolean;
 };
 
 const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code' }> = {
@@ -123,7 +121,7 @@ function preflightFailed(
 }
 
 /** Validate the current review draft before any finding-ledger write. */
-function preflightReviewSummaryUnlocked(
+function preflightReviewSummary(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewPreflightResult {
@@ -178,30 +176,9 @@ function preflightReviewSummaryUnlocked(
   };
 }
 
-function preflightReviewSummary(
-  request: ReviewFinalizationRequest,
-  options: ReviewFinalizationOptions = {}
-): ReviewPreflightResult {
-  if (request.dryRun || options.lockAlreadyHeld) return preflightReviewSummaryUnlocked(request, options);
-  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
-  if (!resolved.ok) return preflightReviewSummaryUnlocked(request, options);
-  try {
-    return withTaskExecutionLock(
-      resolved.repoRoot,
-      resolved.taskId,
-      'task-review.preflight',
-      () => preflightReviewSummaryUnlocked(request, { ...options, lockAlreadyHeld: true })
-    );
-  } catch (error) {
-    if (!(error instanceof TaskExecutionLockError)) throw error;
-    return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
-  }
-}
-
 type ReviewSummaryCandidatePreparation = Readonly<{
   result: ReviewFinalizationResult;
   content: string;
-  lockAlreadyHeld?: boolean;
 }>;
 
 /** Prepare domain validation, summary bytes and provenance before any publication. */
@@ -279,7 +256,6 @@ function prepareReviewSummaryCandidate(
       operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
       error: null
     },
-    lockAlreadyHeld: options.lockAlreadyHeld
   };
 }
 
@@ -303,7 +279,7 @@ function replaceCurrentArtifactAtomically(file: string, content: string): void {
   }
 }
 
-function finalizeReviewSummaryUnlocked(
+function finalizeReviewSummary(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewFinalizationResult {
@@ -340,32 +316,6 @@ function finalizeReviewSummaryUnlocked(
   }
 }
 
-function finalizeReviewSummary(
-  request: ReviewFinalizationRequest,
-  options: ReviewFinalizationOptions = {}
-): ReviewFinalizationResult {
-  const effectiveOptions = options;
-  if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, effectiveOptions);
-  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
-  if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, effectiveOptions);
-  try {
-    return withTaskExecutionLock(
-      resolved.repoRoot,
-      resolved.taskId,
-      'task-review.finalize-summary',
-      () => finalizeReviewSummaryUnlocked(request, { ...effectiveOptions, lockAlreadyHeld: true })
-    );
-  } catch (error) {
-    if (!(error instanceof TaskExecutionLockError)) throw error;
-    return failed(
-      request,
-      'REVIEW_PROVENANCE_INVALID',
-      `${error.code}: ${error.message}`,
-      resolved.taskId
-    );
-  }
-}
-
 export { finalizeReviewSummary, preflightReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 export type {
   ReviewFinalizationError,

package/lib/task/review-identity.ts

@@ -45,7 +45,9 @@ export function inspectReviewIdentity(taskDir: string, reportContent: string, re
   }
   try {
     const metadata = parseTypedTaskFrontmatter(fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8'));
-    const taskRepositoryRoot = git(taskDir, ['rev-parse', '--show-toplevel']);
+    const taskRepositoryRoot = repositoryRoot
+      ? fs.realpathSync.native(repositoryRoot)
+      : git(taskDir, ['rev-parse', '--show-toplevel']);
     const branch = String(metadata.branch ?? '').trim();
     const gitRoot = branch ? resolveBranchWorktree(taskRepositoryRoot, branch) : taskRepositoryRoot;
     if (!gitRoot) return result('indeterminate', `Task branch '${branch}' is not checked out in a registered worktree`, reviewedHead);

package/lib/task/short-id.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
+import { resolveProjectTaskWorkspaceRoot } from './workspace-root.ts';
 
 const REGISTRY_NAME = '.short-ids.json';
 const LOCK_NAME = '.short-ids.json.lock';
@@ -85,7 +86,7 @@ function resolveShortIdReadOnly(
   }
 
   const key = normalized.value;
-  const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+  const registryPath = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', REGISTRY_NAME);
   if (!fs.existsSync(registryPath)) {
     return shortIdFailure(
       'SHORT_ID_REGISTRY_NOT_FOUND',
@@ -164,8 +165,9 @@ function resolveShortIdReadOnly(
       : `short id '${key}' not found in task short-id registry.`;
     return shortIdFailure('SHORT_ID_NOT_FOUND', message);
   }
-  const activeTask = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
-  const completedTask = path.join(repoRoot, '.agents', 'workspace', 'completed', taskId, 'task.md');
+  const workspaceRoot = resolveProjectTaskWorkspaceRoot(repoRoot);
+  const activeTask = path.join(workspaceRoot, 'active', taskId, 'task.md');
+  const completedTask = path.join(workspaceRoot, 'completed', taskId, 'task.md');
   let isValidCompletedTask = false;
   try {
     const task = parseTypedTaskFrontmatter(fs.readFileSync(completedTask, 'utf8'));
@@ -300,7 +302,7 @@ function mutateShortIdRegistry(
   taskId: string,
   requested: ShortIdMutationEffect
 ): ShortIdMutationResult {
-  const activeDir = path.join(repoRoot, '.agents', 'workspace', 'active');
+  const activeDir = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active');
   return mutateShortIdRegistryAt(activeDir, configuredShortIdLength(repoRoot), taskId, requested);
 }
 
@@ -369,7 +371,7 @@ function mutateShortIdRegistryAt(
 }
 
 function releaseStaleShortIdRegistry(repoRoot: string, taskId: string): ShortIdMutationResult {
-  const activeDir = path.join(repoRoot, '.agents', 'workspace', 'active');
+  const activeDir = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active');
   return mutateShortIdRegistryAt(
     activeDir,
     configuredShortIdLength(repoRoot),
@@ -433,7 +435,7 @@ function executeShortIdCommand(request: ShortIdCommandRequest): ShortIdCommandRe
 }
 
 function readRegistry(repoRoot: string): RegistrySchema | null {
-  const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+  const registryPath = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', REGISTRY_NAME);
   if (!fs.existsSync(registryPath)) return null;
   try {
     const raw = fs.readFileSync(registryPath, 'utf8');
@@ -446,7 +448,7 @@ function readRegistry(repoRoot: string): RegistrySchema | null {
 }
 
 function readBranchFromTaskMd(repoRoot: string, taskId: string): string | null {
-  const taskMdPath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
+  const taskMdPath = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', taskId, 'task.md');
   if (!fs.existsSync(taskMdPath)) return null;
   const content = fs.readFileSync(taskMdPath, 'utf8');
   const m = content.match(/^branch:\s*(.+)$/m);
@@ -468,7 +470,7 @@ function inspectShortIdRegistry(
   repoRoot: string,
   shortIdLength = configuredShortIdLength(repoRoot)
 ): ShortIdRegistryInspection {
-  const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+  const registryPath = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', REGISTRY_NAME);
   if (!fs.existsSync(registryPath)) {
     return {
       status: 'missing',

package/lib/task/verification-engine.ts

@@ -69,9 +69,7 @@ const DEFAULT_REQUIRED_FIELDS = [
 ];
 
 const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?$/;
-// Start markers (action suffixed with ` [started]`) are excluded from the
-// "latest action" / freshness computation so a step's in-flight marker never
-// satisfies a skill's expected_action_pattern; the matching done entry does.
+// Started rows do not represent completed lifecycle actions.
 const ACTIVITY_LOG_STARTED_RE = /\s*\[started\]\s*$/;
 const BRANCH_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
@@ -358,16 +356,10 @@ function checkTaskMeta({ taskDir, config, repositoryRoot, skillName, artifactFil
   if (expectedStep && metadata.current_step !== expectedStep) {
     let validLifecycleArtifact = false;
     if (currentTask) {
-      const activityConfig = loadVerificationConfig(repositoryRoot, skillName).checks?.["activity-log"];
       const { section, invalidEntries } = inspectActivityLog(task.content);
-      if (activityConfig && section && invalidEntries.length === 0) {
-        let latestAction = "";
-        for (const entry of section.entries) {
-          if (!ACTIVITY_LOG_STARTED_RE.test(entry.step)) latestAction = entry.step;
-        }
+      if (section && invalidEntries.length === 0) {
         validLifecycleArtifact = checkArtifactLifecycleActivityLog(
-          taskDir, artifactFile, skillName,
-          activityConfig, task, section.entries, latestAction
+          taskDir, artifactFile, skillName, task, section.entries
         )?.status === "pass";
       }
     }
@@ -725,16 +717,16 @@ function checkImplementationInput({ taskDir, artifactFile }: any): any {
   return passResult("implementation-input", `${actionDecision} matches Activity Log, report, and task table`);
 }
 
-const ARTIFACT_ACTIVITY_STAGES: Readonly<Record<string, { family: string; event: string }>> = {
-  "analyze-task": { family: "analysis", event: "analyze.completed" },
-  "plan-task": { family: "plan", event: "plan.completed" },
-  "review-analysis": { family: "review-analysis", event: "review-analysis.completed" },
-  "review-plan": { family: "review-plan", event: "review-plan.completed" },
-  "code-task": { family: "code", event: "code.completed" },
-  "review-code": { family: "review-code", event: "review-code.completed" }
+const ARTIFACT_ACTIVITY_STAGES: Readonly<Record<string, { family: string; event: string; action: string }>> = {
+  "analyze-task": { family: "analysis", event: "analyze.completed", action: "Analyze Task" },
+  "plan-task": { family: "plan", event: "plan.completed", action: "Plan Task" },
+  "review-analysis": { family: "review-analysis", event: "review-analysis.completed", action: "Review Analysis" },
+  "review-plan": { family: "review-plan", event: "review-plan.completed", action: "Review Plan" },
+  "code-task": { family: "code", event: "code.completed", action: "Code Task" },
+  "review-code": { family: "review-code", event: "review-code.completed", action: "Review Code" }
 };
 
-function checkArtifactLifecycleActivityLog(taskDir: string, artifactFile: string | undefined, skillName: string, config: any, task: any, entries: any[], latestAction: string): any {
+function checkArtifactLifecycleActivityLog(taskDir: string, artifactFile: string | undefined, skillName: string, task: any, entries: any[]): any {
   const stage = ARTIFACT_ACTIVITY_STAGES[skillName];
   if (!stage) return null;
   const inventory = inspectArtifactDirectory(taskDir, stage.family as any);
@@ -772,25 +764,19 @@ function checkArtifactLifecycleActivityLog(taskDir: string, artifactFile: string
     }
   }
 
-  const expectedAction = new RegExp(config.expected_action_pattern);
+  const roundActionPattern = new RegExp(`^${stage.action} \\(Round ${identity.round}(?:, [^)]+)?\\)$`);
   const roundAction = entries.find((entry) => {
-    if (ACTIVITY_LOG_STARTED_RE.test(entry.step)) return false;
-    if (!expectedAction.test(entry.step)) return false;
-    expectedAction.lastIndex = 0;
-    const actionRound = /\(Round (\d+)/.exec(entry.step)?.[1];
-    return actionRound === String(identity.round) && entry.note.includes(`→ ${output}`);
+    return !ACTIVITY_LOG_STARTED_RE.test(entry.step)
+      && roundActionPattern.test(entry.step)
+      && entry.note.includes(`→ ${output}`);
   });
   if (!roundAction) {
     return failResult("activity-log", `No completed Activity Log row records '${output}' for ${skillName} Round ${identity.round}`);
   }
-  if (skillName === "plan-task" && /^(?:Human Decision|Decision)\b/.test(latestAction)
-    && expectedAction.test(latestAction)) {
-    return passResult("activity-log", `Plan completion '${output}' is current; latest action '${latestAction}' is a human decision`);
-  }
   return passResult("activity-log", `Current ${stage.family} completion '${output}' is valid for Round ${identity.round}`);
 }
 
-function checkActivityLog({ taskDir, config, skillName, artifactFile }: any): any {
+function checkActivityLog({ taskDir, skillName, artifactFile }: any): any {
   const task = loadTask(taskDir);
   if (!task.ok) {
     return failResult("activity-log", task.message);
@@ -802,44 +788,16 @@ function checkActivityLog({ taskDir, config, skillName, artifactFile }: any): an
   const entries = section.entries;
   if (entries.length === 0) return failResult("activity-log", "Activity Log has no entries");
 
-  let latestAction = "";
-  let latestTimestamp = "";
-  const doneActions: string[] = [];
-
   for (const entry of entries) {
     if (!entry.note.trim()) return failResult("activity-log", "Activity Log entry note is required");
-    const { time: timestamp, step: action } = entry;
-    // A `[started]` marker is not a terminal action: keep latestAction/latestTimestamp
-    // on the most recent done entry so expected_action_pattern sees it.
-    if (!ACTIVITY_LOG_STARTED_RE.test(action)) {
-      latestTimestamp = timestamp;
-      latestAction = action;
-      doneActions.push(action);
-    }
   }
 
   const artifactLifecycleResult = checkArtifactLifecycleActivityLog(
-    taskDir, artifactFile, skillName, config, task, entries, latestAction
+    taskDir, artifactFile, skillName, task, entries
   );
   if (artifactLifecycleResult) return artifactLifecycleResult;
 
-  if (config.expected_action_pattern && !new RegExp(config.expected_action_pattern).test(latestAction)) {
-    const expected = new RegExp(config.expected_action_pattern);
-    let index = doneActions.length - 1;
-    while (index >= 0 && doneActions[index] === 'Commit' && !expected.test(doneActions[index]!)) index -= 1;
-    if (index >= 0 && expected.test(doneActions[index]!)) {
-      latestAction = doneActions[index]!;
-    }
-  }
-
-  if (config.expected_action_pattern && !new RegExp(config.expected_action_pattern).test(latestAction)) {
-    return failResult(
-      "activity-log",
-      `Latest action '${latestAction}' does not match '${config.expected_action_pattern}'`
-    );
-  }
-
-  return passResult("activity-log", `Latest entry '${latestAction}' at ${latestTimestamp}`);
+  return passResult("activity-log", "Activity Log is valid");
 }
 
 function checkCompletionChecklist({ taskDir, config }: any): any {
@@ -1042,9 +1000,9 @@ async function checkPostReviewCommit({ taskDir, config, repositoryRoot }: any):
 
   let gitRoot;
   try {
-    gitRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+    gitRoot = execFileSync("git", ["-C", repositoryRoot, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
   } catch {
-    return blockedResult("post-review-commit", "git unavailable or task directory is not inside a git repository");
+    return blockedResult("post-review-commit", "git unavailable or repository root is not inside a git repository");
   }
 
   const task = loadTask(taskDir);

package/lib/task/workspace-root.ts

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { isSandbox } from '../sandbox/environment.ts';
+
+export type ExecutionBoundary = 'host' | 'container';
+
+/**
+ * Resolve the physical task-workspace boundary from the verified process
+ * execution context. Sandbox mode (task-bound / branch-only) does not affect
+ * the task workspace mount location.
+ */
+export function resolveTaskWorkspaceExecutionBoundary(
+  env: NodeJS.ProcessEnv = process.env
+): ExecutionBoundary {
+  if (env.AGENT_INFRA_SANDBOX !== '1') return 'host';
+  const statusMountPath = env.AGENT_INFRA_CONTROL_STATUS_DIR;
+  if (!statusMountPath || !isSandbox(env, { statusMountPath })) {
+    throw new Error('task workspace boundary requires a verified sandbox execution context');
+  }
+  return 'container';
+}
+
+export interface TaskWorkspaceLayout {
+  projectKey: string;
+  boundary: ExecutionBoundary;
+  root: string;
+  active: string;
+  blocked: string;
+  completed: string;
+  archive: string;
+  shortIds: string;
+}
+
+export function resolveTaskWorkspaceLayout(input: {
+  project: string;
+  boundary: ExecutionBoundary;
+  home?: string;
+}): TaskWorkspaceLayout {
+  const { project, boundary } = input;
+  if (!project || project === '.' || project === '..' || /[\\/\u0000-\u001f\u007f]/u.test(project)) {
+    throw new TypeError('project must be a safe single path segment');
+  }
+  let root: string;
+  if (boundary === 'container') {
+    root = '/task-workspace';
+  } else if (boundary === 'host') {
+    if (!input.home) throw new TypeError('home is required for host task workspace resolution');
+    if (!path.isAbsolute(input.home)) throw new TypeError('home must be an absolute path for host task workspace resolution');
+    root = path.join(input.home, '.agent-infra', 'task-workspaces', project);
+  } else {
+    throw new TypeError(`unsupported task workspace boundary: ${String(boundary)}`);
+  }
+  return {
+    projectKey: project,
+    boundary,
+    root,
+    active: path.join(root, 'active'),
+    blocked: path.join(root, 'blocked'),
+    completed: path.join(root, 'completed'),
+    archive: path.join(root, 'archive'),
+    shortIds: path.join(root, 'active', '.short-ids.json')
+  };
+}
+
+export function resolveProjectTaskWorkspaceLayout(
+  repoRoot: string,
+  boundary: ExecutionBoundary = resolveTaskWorkspaceExecutionBoundary()
+): TaskWorkspaceLayout {
+  const configPath = path.join(repoRoot, '.agents', '.airc.json');
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8')) as { project?: unknown };
+  if (typeof config.project !== 'string') throw new TypeError(`project is missing from ${configPath}`);
+  return resolveTaskWorkspaceLayout({ project: config.project, boundary, home: process.env.HOME || os.homedir() });
+}
+
+export function resolveProjectTaskWorkspaceRoot(repoRoot: string): string {
+  return resolveProjectTaskWorkspaceLayout(repoRoot).root;
+}

package/lib/task/workspace-snapshot.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { resolveProjectTaskWorkspaceRoot } from './workspace-root.ts';
 
 function git(repoRoot: string, indexFile: string | null, args: string[]): string {
   const env = indexFile ? { ...process.env, GIT_INDEX_FILE: indexFile } : process.env;
@@ -55,7 +56,7 @@ function captureWorktreeTree(repoRoot: string, forcedPath: string | null): strin
 }
 
 function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFileFingerprint[] {
-  const activeRoot = path.join(stateRoot, '.agents', 'workspace', 'active');
+  const activeRoot = path.join(resolveProjectTaskWorkspaceRoot(stateRoot), 'active');
   const roots = taskId ? [path.join(activeRoot, taskId)] : [activeRoot];
   const records: TaskFileFingerprint[] = [];
   const visit = (absolute: string, relative: string): void => {
@@ -67,7 +68,7 @@ function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFil
       return;
     }
     if (!stat.isFile() && !stat.isSymbolicLink()) return;
-    if (/^\.agents\/workspace\/(?:active|blocked|completed)\/TASK-[0-9]{8}-[0-9]{6}\/\.runtime\/orchestration\.json$/u.test(relative)) return;
+    if (/^task-workspace\/(?:active|blocked|completed)\/TASK-[0-9]{8}-[0-9]{6}\/\.runtime\/orchestration\.json$/u.test(relative)) return;
     const content = stat.isSymbolicLink()
       ? Buffer.from(fs.readlinkSync(absolute))
       : fs.readFileSync(absolute);
@@ -80,7 +81,7 @@ function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFil
   };
   for (const root of roots) {
     if (!fs.existsSync(root)) continue;
-    const relative = path.posix.join('.agents/workspace/active', path.relative(activeRoot, root).split(path.sep).join('/'));
+    const relative = path.posix.join('task-workspace/active', path.relative(activeRoot, root).split(path.sep).join('/'));
     visit(root, relative.replace(/\/$/, ''));
   }
   return records.sort((left, right) => left.path.localeCompare(right.path));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.15",
+  "version": "0.12.1",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/QUICKSTART.en.md

@@ -53,16 +53,23 @@ Built-in templates take priority over external templates. Later external templat
 
 ## Creating Your First Task
 
+Resolve the host task root once for these examples:
+
+```bash
+TASK_WORKSPACE_ROOT=$(agent-infra-internal task-workspace resolve --boundary host | node -e 'let input="";process.stdin.setEncoding("utf8");process.stdin.on("data",chunk=>input+=chunk);process.stdin.on("end",()=>process.stdout.write(JSON.parse(input).root));')
+```
+
 1. Copy the task template to the active workspace:
 
 ```bash
-cp .agents/templates/task.md .agents/workspace/active/task-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md"
 ```
 
 2. Fill in the task metadata:
 
 ```yaml
-id: task-001
+id: TASK-20260101-120000
 type: feature          # feature | bugfix | refactor | docs | review
 status: open           # open | in-progress | review | blocked | completed
 assigned_to: claude    # claude | codex | antigravity | opencode | human
@@ -92,7 +99,7 @@ Claude Code excels at codebase exploration and understanding complex relationshi
 agy
 
 # Example prompt:
-# "Based on the analysis in .agents/workspace/active/task-001.md,
+# "Based on the analysis in $TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md,
 #  create a technical design. Define interfaces and outline the approach."
 ```
 
@@ -103,7 +110,7 @@ agy
 codex
 
 # Example prompt:
-# "Implement the changes described in .agents/workspace/active/task-001.md.
+# "Implement the changes described in $TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md.
 #  Follow the design section. Create a new branch for this work."
 ```
 
@@ -130,7 +137,8 @@ claude
 
 ```bash
 # Quick bug fix workflow
-cp .agents/templates/task.md .agents/workspace/active/bugfix-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md"
 # Edit the task, then:
 # 1. Use Claude Code to analyze
 # 2. Use Codex/OpenCode to fix
@@ -144,7 +152,8 @@ cp .agents/templates/task.md .agents/workspace/active/bugfix-001.md
 3. **Report**: Generate review report from template.
 
 ```bash
-cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120001"
+cp .agents/templates/review-report.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120001/review-report.md"
 # Use Claude Code to fill in the review
 ```
 
@@ -156,7 +165,8 @@ cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 4. **Verify** (Claude Code): Ensure no regressions, run tests.
 
 ```bash
-cp .agents/templates/task.md .agents/workspace/active/refactor-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120002"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120002/task.md"
 # Follow the refactoring workflow in .agents/workflows/refactoring.yaml
 ```
 
@@ -165,7 +175,8 @@ cp .agents/templates/task.md .agents/workspace/active/refactor-001.md
 When switching between AI tools, create a handoff document:
 
 ```bash
-cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120003"
+cp .agents/templates/handoff.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120003/handoff.md"
 ```
 
 Fill in: