nolo-cli 0.1.26 → 0.1.29

package/agentRunCommand.ts

@@ -1,23 +1,25 @@
 import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
 import { runAgentTurn, type RunAgentTurnResult } from "./client/agentRun";
-import type { AgentRuntimeHostAdapter, AgentRuntimeRequestedMode } from "./agentRuntimeLocal";
-import { existsSync, readFileSync } from "node:fs";
-import { extname, resolve } from "node:path";
-import { parseSkillDocProtocol, type WorkflowReferenceConfig } from "./ai/skills/skillDocProtocol";
-import { resolveCliAgentKeyInput } from "./agentAliases";
+import type { AgentRuntimeHostAdapter } from "./agentRuntimeLocal";
 import {
-  ensureWorkspacePackageLinks,
-  formatPreparedTaskWorktree,
   prepareTaskWorktree,
-  type PreparedTaskWorktree,
+  ensureWorkspacePackageLinks,
 } from "./client/taskWorktree";
-import type { TaskRunPromptContext } from "./client/taskRunPrompt";
-
-type EnvLike = Record<string, string | undefined>;
-
-type OutputLike = {
-  write(chunk: string): unknown;
-};
+import {
+  formatLocalRunSummary,
+  inspectLocalRunWorkspace,
+  prepareLocalRunWorkspace,
+  type EnvLike,
+  type OutputLike,
+} from "./agentRunLocalWorkspace";
+import {
+  normalizeCliImageInput,
+  parseAgentRunArgs,
+  prependWorkflowReferencePrompt,
+  resolveWorkflowReference,
+  type ParsedAgentRunArgs,
+  type ResolvedWorkflowReference,
+} from "./agentRunParsing";
 
 type AgentRunCommandDeps = {
   env?: EnvLike;
@@ -31,325 +33,15 @@ type AgentRunCommandDeps = {
   resolveWorkflowReference?: typeof resolveWorkflowReference;
 };
 
-type LocalRunWorkspaceInspection = {
-  cwd: string;
-  clean: boolean;
-  status: string;
-  commit?: {
-    hash: string;
-    subject: string;
-  };
-};
-
-type ParseAgentRunArgsOptions = {
-  readTextFile?: (path: string) => string;
-};
-
-type ParsedAgentRunArgs = {
-  agentKey: string;
-  message: string;
-  imageUrls: string[];
-  allowShell: boolean;
-  runtimeMode?: AgentRuntimeRequestedMode;
-  continueDialogId?: string;
-  spaceId?: string;
-  category?: string;
-  inheritedFromDialogKey?: string;
-  parentDialogId?: string;
-  background: boolean;
-  noStream: boolean;
-  noDefaultTestRoot: boolean;
-  cwd?: string;
-  maxToolRounds?: number;
-  timeoutMs?: number;
-  traceTools: boolean;
-  useTaskWorktree: boolean;
-  taskRunContext?: TaskRunPromptContext;
-  workflowRef?: string;
+// Compatibility shim for publish/runtime consumers that still import parser helpers from
+// the command module. New code should import these from agentRunParsing directly.
+export {
+  normalizeCliImageInput,
+  parseAgentRunArgs,
+  prependWorkflowReferencePrompt,
+  resolveWorkflowReference,
 };
 
-type ResolvedWorkflowReference = {
-  ref: string;
-  content: string;
-  config?: Partial<WorkflowReferenceConfig>;
-};
-
-const DEFAULT_TEST_ROOT_DIALOG_ID = "01KN6V3MVEQA4Q1PNKVM2W7YY8";
-const DEFAULT_TEST_ROOT_DIALOG_KEY = `dialog-b2e06f801f-${DEFAULT_TEST_ROOT_DIALOG_ID}`;
-const DEFAULT_TEST_DIALOG_CATEGORY_ID = "test-dialogs";
-
-function readFlagValue(args: string[], flag: string) {
-  const index = args.indexOf(flag);
-  if (index < 0) return undefined;
-  return args[index + 1];
-}
-
-function readRepeatedFlagValues(args: string[], flag: string) {
-  const values: string[] = [];
-  for (let index = 0; index < args.length; index += 1) {
-    if (args[index] === flag && args[index + 1]) {
-      values.push(args[index + 1]);
-      index += 1;
-    }
-  }
-  return values;
-}
-
-function runtimeModeFromArgs(args: string[]): AgentRuntimeRequestedMode | undefined {
-  if (args.includes("--local")) return "local";
-  if (args.includes("--server")) return "server";
-  if (args.includes("--auto")) return "auto";
-  return undefined;
-}
-
-function parseNonNegativeInteger(value: string | undefined) {
-  if (!value) return undefined;
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed < 0) return undefined;
-  return Math.floor(parsed);
-}
-
-function parsePositiveInteger(value: string | undefined) {
-  if (!value) return undefined;
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
-  return Math.floor(parsed);
-}
-
-function positionalArgs(args: string[]) {
-  const values: string[] = [];
-  const valuelessFlags = new Set([
-    "--local",
-    "--server",
-    "--auto",
-    "--dangerously-allow-shell",
-    "--worktree-task",
-    "--trace-tools",
-    "--bg",
-    "--no-stream",
-    "--debug",
-    "--no-default-test-root",
-  ]);
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (valuelessFlags.has(arg)) continue;
-    if (arg.startsWith("--")) {
-      index += 1;
-      continue;
-    }
-    values.push(arg);
-  }
-  return values;
-}
-
-export function parseAgentRunArgs(
-  args: string[],
-  options: ParseAgentRunArgsOptions = {}
-): ParsedAgentRunArgs | null {
-  const agentKey = readFlagValue(args, "--agent") ?? positionalArgs(args)[0];
-  const explicitMsg = readFlagValue(args, "--msg");
-  const msgFile = readFlagValue(args, "--msg-file");
-  const fileMessage = msgFile
-    ? (options.readTextFile ?? ((path: string) => readFileSync(path, "utf8")))(msgFile)
-    : undefined;
-  const rawMessage = explicitMsg ?? fileMessage ?? positionalArgs(args).slice(1).join(" ");
-  if (!agentKey || !rawMessage.trim()) return null;
-  const message = rawMessage.trim();
-  const runtimeMode = runtimeModeFromArgs(args);
-  const continueDialogId = readFlagValue(args, "--continue") ?? readFlagValue(args, "--dialog");
-  const spaceId = readFlagValue(args, "--space");
-  const category = readFlagValue(args, "--category");
-  const inheritedFromDialog = readFlagValue(args, "--inherit-from-dialog");
-  const noDefaultTestRoot = args.includes("--no-default-test-root");
-  const cwd = readFlagValue(args, "--cwd");
-  const maxToolRounds = parseNonNegativeInteger(
-    readFlagValue(args, "--max-tool-rounds") ?? readFlagValue(args, "--rounds")
-  );
-  const timeoutMs = parsePositiveInteger(readFlagValue(args, "--timeout-ms"));
-  const inheritedRef = inheritedFromDialog
-    ? parseDialogReference(inheritedFromDialog)
-    : !continueDialogId && !noDefaultTestRoot
-      ? {
-          dialogKey: DEFAULT_TEST_ROOT_DIALOG_KEY,
-          dialogId: DEFAULT_TEST_ROOT_DIALOG_ID,
-        }
-      : undefined;
-  const imageUrls = [
-    ...readRepeatedFlagValues(args, "--image"),
-    ...readRepeatedFlagValues(args, "--image-url"),
-  ];
-  const useTaskWorktree = args.includes("--worktree-task");
-  const workflowRef = readFlagValue(args, "--workflow");
-  const taskRowDbKey = readFlagValue(args, "--task-row-dbkey");
-  const artifactIds = readFlagValue(args, "--artifact-ids")
-    ?.split(",")
-    .map((item) => item.trim())
-    .filter(Boolean);
-  return {
-    agentKey: resolveCliAgentKeyInput(agentKey),
-    message,
-    imageUrls,
-    allowShell: args.includes("--dangerously-allow-shell"),
-    traceTools: args.includes("--trace-tools"),
-    useTaskWorktree,
-    ...(workflowRef ? { workflowRef } : {}),
-    ...(taskRowDbKey
-      ? {
-          taskRunContext: {
-            rowDbKey: taskRowDbKey,
-            ...(readFlagValue(args, "--task-run-id") ? { taskRunId: readFlagValue(args, "--task-run-id") } : {}),
-            ...(readFlagValue(args, "--work-item-id") ? { workItemId: readFlagValue(args, "--work-item-id") } : {}),
-            ...(artifactIds?.length ? { artifactIds } : {}),
-          },
-        }
-      : {}),
-    ...(runtimeMode ? { runtimeMode } : useTaskWorktree ? { runtimeMode: "local" as const } : {}),
-    background: args.includes("--bg"),
-    noStream: args.includes("--no-stream"),
-    noDefaultTestRoot,
-    ...(continueDialogId ? { continueDialogId } : {}),
-    ...(!continueDialogId && spaceId ? { spaceId } : {}),
-    ...(category ? { category } : !continueDialogId && !noDefaultTestRoot ? { category: DEFAULT_TEST_DIALOG_CATEGORY_ID } : {}),
-    ...(inheritedRef?.dialogKey ? { inheritedFromDialogKey: inheritedRef.dialogKey } : {}),
-    ...(inheritedRef?.dialogId ? { parentDialogId: inheritedRef.dialogId } : {}),
-    ...(cwd ? { cwd } : {}),
-    ...(typeof maxToolRounds === "number" ? { maxToolRounds } : {}),
-    ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
-  };
-}
-
-function workflowRefToCandidatePath(cwd: string, ref: string) {
-  const normalized = ref.trim();
-  if (!normalized) return "";
-  if (normalized.endsWith(".md") || normalized.includes("/") || normalized.includes("\\")) {
-    const directPath = resolve(cwd, normalized);
-    if (existsSync(directPath)) return directPath;
-  }
-  const fileName = normalized.replace(/[^a-zA-Z0-9\u4e00-\u9fa5]+/g, "-").replace(/^-+|-+$/g, "");
-  return resolve(cwd, "docs", "workflows", `${fileName}.md`);
-}
-
-export async function resolveWorkflowReference(ref: string, cwd = process.cwd()): Promise<ResolvedWorkflowReference> {
-  const path = workflowRefToCandidatePath(cwd, ref);
-  if (!path || !existsSync(path)) {
-    throw new Error(`Workflow reference not found: ${ref}`);
-  }
-  const markdown = readFileSync(path, "utf8");
-  const parsed = parseSkillDocProtocol(markdown);
-  return {
-    ref,
-    content: parsed.content,
-    ...(parsed.meta?.workflowConfig ? { config: parsed.meta.workflowConfig } : {}),
-  };
-}
-
-export function prependWorkflowReferencePrompt(message: string, workflow?: ResolvedWorkflowReference): string {
-  if (!workflow) return message;
-  const config = workflow.config;
-  return [
-    "AI-native workflow reference:",
-    "- This reference is guidance for the agent, not a central workflow engine.",
-    `- ref: ${workflow.ref}`,
-    ...(config?.id ? [`- id: ${config.id}`] : []),
-    ...(config?.name ? [`- name: ${config.name}`] : []),
-    ...(config?.defaultAgent ? [`- suggested defaultAgent: ${config.defaultAgent}`] : []),
-    ...(config?.inputs?.length ? [`- inputs: ${config.inputs.join(", ")}`] : []),
-    ...(config?.recommendedTools?.length ? [`- recommendedTools: ${config.recommendedTools.join(", ")}`] : []),
-    ...(config?.requiredTools?.length ? [`- requiredTools: ${config.requiredTools.join(", ")}`] : []),
-    ...(config?.requiredOutputs?.length ? [`- requiredOutputs: ${config.requiredOutputs.join(", ")}`] : []),
-    ...(config?.gates?.length ? [`- gates: ${config.gates.join(", ")}`] : []),
-    ...(config?.contextStrategy ? [`- contextStrategy: ${config.contextStrategy}`] : []),
-    ...(config?.failureProtocol ? [`- failureProtocol: ${config.failureProtocol}`] : []),
-    "",
-    "Reference body:",
-    workflow.content,
-    "",
-    "User task:",
-    message,
-  ].join("\n");
-}
-
-function parseDialogReference(rawInput: string) {
-  const normalized = rawInput.trim();
-  if (normalized.startsWith("dialog-")) {
-    const parts = normalized.split("-");
-    return {
-      dialogKey: normalized,
-      dialogId: parts.at(-1) ?? normalized,
-    };
-  }
-  const dialogMatch = normalized.match(/dialog-([a-zA-Z0-9]+)-([a-zA-Z0-9]+)/);
-  if (dialogMatch) {
-    return {
-      dialogKey: `dialog-${dialogMatch[1]}-${dialogMatch[2]}`,
-      dialogId: dialogMatch[2],
-    };
-  }
-  return {
-    dialogId: normalized,
-  };
-}
-
-function mimeTypeForPath(path: string) {
-  switch (extname(path).toLowerCase()) {
-    case ".jpg":
-    case ".jpeg":
-      return "image/jpeg";
-    case ".webp":
-      return "image/webp";
-    case ".gif":
-      return "image/gif";
-    default:
-      return "image/png";
-  }
-}
-
-export function normalizeCliImageInput(input: string) {
-  if (/^(https?:|data:|file:)/i.test(input)) return input;
-  const absolutePath = resolve(input);
-  if (!existsSync(absolutePath)) return input;
-  const base64 = readFileSync(absolutePath).toString("base64");
-  return `data:${mimeTypeForPath(absolutePath)};base64,${base64}`;
-}
-
-async function runGitForLocalSummary(args: {
-  cwd: string;
-  gitArgs: string[];
-}) {
-  const proc = Bun.spawn(["git", ...args.gitArgs], {
-    cwd: args.cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  if (exitCode !== 0) {
-    throw new Error((stderr || stdout || `git ${args.gitArgs.join(" ")} failed`).trim());
-  }
-  return stdout.trim();
-}
-
-async function inspectLocalRunWorkspace(cwd: string): Promise<LocalRunWorkspaceInspection> {
-  const status = await runGitForLocalSummary({
-    cwd,
-    gitArgs: ["status", "--short"],
-  });
-  const rawCommit = await runGitForLocalSummary({
-    cwd,
-    gitArgs: ["log", "-1", "--format=%h%x00%s"],
-  }).catch(() => "");
-  const [hash, subject] = rawCommit.split("\0");
-  return {
-    cwd,
-    clean: status.trim() === "",
-    status,
-    ...(hash ? { commit: { hash, subject: subject ?? "" } } : {}),
-  };
-}
-
 function shouldPrintLocalRunSummary(args: {
   parsed: ParsedAgentRunArgs;
   localRuntimeCwd?: string;
@@ -357,46 +49,10 @@ function shouldPrintLocalRunSummary(args: {
   return Boolean(args.localRuntimeCwd && args.parsed.runtimeMode === "local");
 }
 
-function formatLocalRunSummary(args: {
-  dialogId?: string;
-  inspection: LocalRunWorkspaceInspection;
-}) {
-  return [
-    "",
-    "[nolo] local run summary",
-    `workspace: ${args.inspection.cwd}`,
-    ...(args.dialogId ? [`dialog: ${args.dialogId}`] : []),
-    ...(args.inspection.commit
-      ? [`commit: ${args.inspection.commit.hash} ${args.inspection.commit.subject}`]
-      : []),
-    `dirty: ${args.inspection.clean ? "clean" : "dirty"}`,
-    ...(!args.inspection.clean && args.inspection.status.trim()
-      ? [`status:\n${args.inspection.status.trim()}`]
-      : []),
-    "",
-  ].join("\n");
-}
-
 function resolveServerUrl(env: EnvLike) {
   return (env.NOLO_SERVER || env.BASE_URL || DEFAULT_NOLO_SERVER_URL).replace(/\/+$/, "");
 }
 
-function shouldPrepareTaskWorktree(parsed: ParsedAgentRunArgs) {
-  return !parsed.cwd && (parsed.useTaskWorktree || parsed.allowShell);
-}
-
-function buildTaskWorktreeEnv(args: {
-  env: EnvLike;
-  worktreePath?: string;
-  allowShell: boolean;
-}) {
-  return {
-    ...args.env,
-    ...(args.allowShell ? { NOLO_LOCAL_SHELL_MODE: "worktree" } : {}),
-    ...(args.worktreePath ? { NOLO_LOCAL_WORKTREE: args.worktreePath } : {}),
-  };
-}
-
 function writeUsage(output: OutputLike) {
   output.write(
     "Usage: nolo agent run <agent> <message> [--local|--server|--auto] [--continue <dialogId>] [--cwd <path>] [--max-tool-rounds <n>]\n" +
@@ -425,48 +81,17 @@ export async function runAgentRunCommand(args: string[], deps: AgentRunCommandDe
       return 1;
     }
   }
-  let localRuntimeCwd = parsed.cwd;
-  if (shouldPrepareTaskWorktree(parsed)) {
-    try {
-      const preparedWorktree = await (deps.prepareTaskWorktree ?? prepareTaskWorktree)({
-        agentKey: parsed.agentKey,
-        env,
-      });
-      localRuntimeCwd = preparedWorktree.path;
-      output.write(formatPreparedTaskWorktree(preparedWorktree));
-    } catch (error) {
-      output.write(
-        "[nolo] Could not prepare a local task worktree.\n" +
-          "Run from inside a git repository, or set NOLO_LOCAL_WORKTREE to an existing isolated checkout.\n" +
-          `Reason: ${error instanceof Error ? error.message : String(error)}\n`
-      );
-      return 1;
-    }
-  }
-  const shouldBindLocalWorkspace =
-    !!localRuntimeCwd &&
-    (parsed.runtimeMode === "local" || parsed.allowShell || parsed.useTaskWorktree);
-  if (shouldBindLocalWorkspace) {
-    try {
-      await (deps.ensureWorkspacePackageLinks ?? ensureWorkspacePackageLinks)(
-        localRuntimeCwd!
-      );
-    } catch (error) {
-      output.write(
-        "[nolo] Dependency preflight failed for local task worktree.\n" +
-          "The worktree may have node_modules entries that point outside the task checkout, or paths that cannot be repaired safely.\n" +
-          `Reason: ${error instanceof Error ? error.message : String(error)}\n`
-      );
-      return 1;
-    }
-  }
-  const runEnv = shouldBindLocalWorkspace
-    ? buildTaskWorktreeEnv({
-        env,
-        worktreePath: localRuntimeCwd,
-        allowShell: parsed.allowShell,
-      })
-    : env;
+  const localWorkspace = await prepareLocalRunWorkspace({
+    parsed,
+    env,
+    output,
+    ...(deps.prepareTaskWorktree ? { prepareTaskWorktree: deps.prepareTaskWorktree } : {}),
+    ...(deps.ensureWorkspacePackageLinks
+      ? { ensureWorkspacePackageLinks: deps.ensureWorkspacePackageLinks }
+      : {}),
+  });
+  if (!localWorkspace.ok) return localWorkspace.exitCode;
+  const { localRuntimeCwd, runEnv } = localWorkspace;
   const result: RunAgentTurnResult = await runner({
     agentName: parsed.agentKey,
     agentKey: parsed.agentKey,

package/agentRunLocalWorkspace.ts

@@ -0,0 +1,182 @@
+import { formatPreparedTaskWorktree, prepareTaskWorktree, ensureWorkspacePackageLinks } from "./client/taskWorktree";
+import type { PreparedTaskWorktree } from "./client/taskWorktree";
+
+export type EnvLike = Record<string, string | undefined>;
+
+export type OutputLike = {
+  write(chunk: string): unknown;
+};
+
+export type LocalRunWorkspaceInspection = {
+  cwd: string;
+  clean: boolean;
+  status: string;
+  commit?: {
+    hash: string;
+    subject: string;
+  };
+};
+
+export type LocalWorkspaceRunArgs = {
+  agentKey: string;
+  runtimeMode?: "local" | "server" | "auto";
+  allowShell: boolean;
+  useTaskWorktree: boolean;
+  cwd?: string;
+};
+
+type InspectLocalRunWorkspaceDeps = {
+  runGitForLocalSummary?: typeof runGitForLocalSummary;
+};
+
+type PrepareLocalRunWorkspaceDeps = {
+  parsed: LocalWorkspaceRunArgs;
+  env: EnvLike;
+  output: OutputLike;
+  prepareTaskWorktree?: typeof prepareTaskWorktree;
+  ensureWorkspacePackageLinks?: typeof ensureWorkspacePackageLinks;
+};
+
+export async function runGitForLocalSummary(args: {
+  cwd: string;
+  gitArgs: string[];
+}) {
+  const proc = Bun.spawn(["git", ...args.gitArgs], {
+    cwd: args.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error((stderr || stdout || `git ${args.gitArgs.join(" ")} failed`).trim());
+  }
+  return stdout.trim();
+}
+
+export async function inspectLocalRunWorkspace(
+  cwd: string,
+  deps: InspectLocalRunWorkspaceDeps = {}
+): Promise<LocalRunWorkspaceInspection> {
+  const runGit = deps.runGitForLocalSummary ?? runGitForLocalSummary;
+  const status = await runGit({
+    cwd,
+    gitArgs: ["status", "--short"],
+  });
+  const rawCommit = await runGit({
+    cwd,
+    gitArgs: ["log", "-1", "--format=%h%x00%s"],
+  }).catch(() => "");
+  const [hash, subject] = rawCommit.split("\0");
+  return {
+    cwd,
+    clean: status.trim() === "",
+    status,
+    ...(hash ? { commit: { hash, subject: subject ?? "" } } : {}),
+  };
+}
+
+export function formatLocalRunSummary(args: {
+  dialogId?: string;
+  inspection: LocalRunWorkspaceInspection;
+}) {
+  return [
+    "",
+    "[nolo] local run summary",
+    `workspace: ${args.inspection.cwd}`,
+    ...(args.dialogId ? [`dialog: ${args.dialogId}`] : []),
+    ...(args.inspection.commit
+      ? [`commit: ${args.inspection.commit.hash} ${args.inspection.commit.subject}`]
+      : []),
+    `dirty: ${args.inspection.clean ? "clean" : "dirty"}`,
+    ...(!args.inspection.clean && args.inspection.status.trim()
+      ? [`status:\n${args.inspection.status.trim()}`]
+      : []),
+    "",
+  ].join("\n");
+}
+
+function shouldPrepareTaskWorktree(parsed: LocalWorkspaceRunArgs) {
+  return !parsed.cwd && (parsed.useTaskWorktree || parsed.allowShell);
+}
+
+function buildTaskWorktreeEnv(args: {
+  env: EnvLike;
+  worktreePath?: string;
+  allowShell: boolean;
+}) {
+  return {
+    ...args.env,
+    ...(args.allowShell ? { NOLO_LOCAL_SHELL_MODE: "worktree" } : {}),
+    ...(args.worktreePath ? { NOLO_LOCAL_WORKTREE: args.worktreePath } : {}),
+  };
+}
+
+function shouldBindLocalWorkspace(args: {
+  parsed: LocalWorkspaceRunArgs;
+  localRuntimeCwd?: string;
+}) {
+  return Boolean(
+    args.localRuntimeCwd &&
+      (args.parsed.runtimeMode === "local" || args.parsed.allowShell || args.parsed.useTaskWorktree)
+  );
+}
+
+export async function prepareLocalRunWorkspace(
+  args: PrepareLocalRunWorkspaceDeps
+): Promise<
+  | {
+      ok: true;
+      localRuntimeCwd?: string;
+      runEnv: EnvLike;
+    }
+  | {
+      ok: false;
+      exitCode: 1;
+    }
+> {
+  let localRuntimeCwd = args.parsed.cwd;
+  if (shouldPrepareTaskWorktree(args.parsed)) {
+    try {
+      const preparedWorktree: PreparedTaskWorktree = await (args.prepareTaskWorktree ?? prepareTaskWorktree)({
+        agentKey: args.parsed.agentKey,
+        env: args.env,
+      });
+      localRuntimeCwd = preparedWorktree.path;
+      args.output.write(formatPreparedTaskWorktree(preparedWorktree));
+    } catch (error) {
+      args.output.write(
+        "[nolo] Could not prepare a local task worktree.\n" +
+          "Run from inside a git repository, or set NOLO_LOCAL_WORKTREE to an existing isolated checkout.\n" +
+          `Reason: ${error instanceof Error ? error.message : String(error)}\n`
+      );
+      return { ok: false, exitCode: 1 };
+    }
+  }
+  if (shouldBindLocalWorkspace({ parsed: args.parsed, localRuntimeCwd })) {
+    try {
+      await (args.ensureWorkspacePackageLinks ?? ensureWorkspacePackageLinks)(localRuntimeCwd!);
+    } catch (error) {
+      args.output.write(
+        "[nolo] Dependency preflight failed for local task worktree.\n" +
+          "The worktree may have node_modules entries that point outside the task checkout, or paths that cannot be repaired safely.\n" +
+          `Reason: ${error instanceof Error ? error.message : String(error)}\n`
+      );
+      return { ok: false, exitCode: 1 };
+    }
+  }
+  return {
+    ok: true,
+    ...(localRuntimeCwd ? { localRuntimeCwd } : {}),
+    runEnv: shouldBindLocalWorkspace({ parsed: args.parsed, localRuntimeCwd })
+      ? buildTaskWorktreeEnv({
+          env: args.env,
+          worktreePath: localRuntimeCwd,
+          allowShell: args.parsed.allowShell,
+        })
+      : args.env,
+  };
+}