@amistio/cli 0.1.2 → 0.1.3

package/dist/index.js

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { spawn as spawn3 } from "node:child_process";
-import { createHash as createHash3, randomUUID } from "node:crypto";
+import { createHash as createHash4, randomUUID as randomUUID2 } from "node:crypto";
 import { writeFile as writeFile8 } from "node:fs/promises";
-import os5 from "node:os";
-import path9 from "node:path";
+import os6 from "node:os";
+import path12 from "node:path";
 import { Command } from "commander";
 
 // ../shared/src/schemas.ts
@@ -86,9 +85,12 @@ var runnerToolNameSchema = z.enum(runnerToolNames);
 var runnerToolSelectionSchema = z.union([runnerToolNameSchema, z.literal("auto")]);
 var runnerPreferenceScopeSchema = z.enum(["account", "project"]);
 var runnerPreferenceSourceSchema = z.enum(["cli", "project", "account", "default"]);
-var runnerPreferenceStatusSchema = z.enum(["resolved", "unavailable", "modelUnsupported", "custom", "none"]);
+var runnerPreferenceStatusSchema = z.enum(["resolved", "unavailable", "modelUnsupported", "channelUnsupported", "custom", "none"]);
+var runnerInvocationChannelSchema = z.enum(["auto", "sdk", "command"]);
+var runnerEffectiveInvocationChannelSchema = z.enum(["sdk", "command"]);
 var runnerToolModelPreferenceSchema = z.object({
   tool: runnerToolSelectionSchema.optional(),
+  invocationChannel: runnerInvocationChannelSchema.optional(),
   model: z.string().trim().min(1).max(160).optional()
 });
 var runnerToolCapabilitySchema = z.object({
@@ -104,6 +106,7 @@ var runnerToolCapabilitySchema = z.object({
 });
 var repositoryLinkSourceSchema = z.enum(["web", "cli"]);
 var repositoryCloneStatusSchema = z.enum(["notCloned", "cloned", "validated", "failed"]);
+var projectStatusSchema = z.enum(["active", "archived"]);
 var baseItemSchema = z.object({
   id: z.string().min(1),
   type: itemTypeSchema,
@@ -130,7 +133,11 @@ var projectItemSchema = baseItemSchema.extend({
   projectId: z.string().min(1),
   name: z.string().min(1),
   slug: z.string().min(1),
-  description: z.string().optional()
+  description: z.string().optional(),
+  status: projectStatusSchema.default("active"),
+  archivedAt: isoDateTimeSchema.optional(),
+  archivedByUserId: z.string().min(1).optional(),
+  archiveReason: z.string().min(1).optional()
 });
 var repositoryLinkItemSchema = baseItemSchema.extend({
   type: z.literal("repositoryLink"),
@@ -229,14 +236,16 @@ var runnerHeartbeatItemSchema = baseItemSchema.extend({
   projectId: z.string().min(1),
   runnerId: z.string().min(1),
   repositoryLinkId: z.string().min(1),
-  status: z.enum(["online", "offline", "running", "blocked"]),
+  status: z.enum(["online", "offline", "running", "blocked", "removed"]),
   version: z.string().optional(),
   mode: z.enum(["foreground", "background"]).optional(),
   hostname: z.string().min(1).optional(),
   runnerName: z.string().min(1).optional(),
   capabilities: z.array(runnerToolCapabilitySchema).optional(),
   requestedTool: runnerToolSelectionSchema.optional(),
+  requestedInvocationChannel: runnerInvocationChannelSchema.optional(),
   effectiveTool: z.union([runnerToolNameSchema, z.literal("custom")]).optional(),
+  effectiveInvocationChannel: runnerEffectiveInvocationChannelSchema.optional(),
   effectiveModel: z.string().min(1).optional(),
   preferenceSource: runnerPreferenceSourceSchema.optional(),
   preferenceStatus: runnerPreferenceStatusSchema.optional(),
@@ -717,7 +726,7 @@ function runnerWaitAction(readiness, fallbackTitle) {
 }
 function getSharedRunnerReadiness(repositoryLinks, runnerHeartbeats, nowMs) {
   const repositoryLinkIds = new Set(repositoryLinks.map((link) => link.repositoryLinkId));
-  const latestHeartbeat = runnerHeartbeats.filter((heartbeat) => repositoryLinkIds.has(heartbeat.repositoryLinkId)).sort((first, second) => heartbeatTime(second) - heartbeatTime(first))[0];
+  const latestHeartbeat = runnerHeartbeats.filter((heartbeat) => repositoryLinkIds.has(heartbeat.repositoryLinkId) && heartbeat.status !== "removed").sort((first, second) => heartbeatTime(second) - heartbeatTime(first))[0];
   const repositoryLink = latestHeartbeat ? repositoryLinks.find((link) => link.repositoryLinkId === latestHeartbeat.repositoryLinkId) ?? repositoryLinks[0] : repositoryLinks[0];
   if (!latestHeartbeat) {
     return { ready: false, reason: "runnerMissing", ...repositoryLink ? { repositoryLink } : {} };
@@ -992,6 +1001,22 @@ var ApiClient = class {
       }
     );
   }
+  async importPairingSession(input) {
+    return this.request(
+      "pairing-sessions",
+      z3.object({
+        accountId: z3.string().min(1),
+        projectId: z3.string().min(1),
+        repositoryLink: repositoryLinkItemSchema,
+        repositoryLinkAction: z3.enum(["created", "reused"]),
+        token: z3.string().min(1)
+      }),
+      {
+        method: "PATCH",
+        body: JSON.stringify(input)
+      }
+    );
+  }
   async claimWork(projectId, runnerId, repositoryLinkId, leaseSeconds = 300) {
     return this.request(
       `/projects/${projectId}/work-items/claim`,
@@ -1066,6 +1091,7 @@ var ApiClient = class {
         project: runnerSettingsItemSchema.optional(),
         effective: z3.object({
           tool: runnerToolSelectionSchema,
+          invocationChannel: runnerInvocationChannelSchema,
           model: z3.string().optional(),
           source: runnerPreferenceSourceSchema
         })
@@ -1141,7 +1167,7 @@ var ApiClient = class {
       ...init,
       headers: {
         "content-type": "application/json",
-        "x-amistio-account-id": this.options.accountId,
+        ...this.options.accountId ? { "x-amistio-account-id": this.options.accountId } : {},
         ...this.options.token ? { authorization: `Bearer ${this.options.token}` } : {}
       }
     });
@@ -1178,8 +1204,8 @@ var toolSessionMutationSchema = z3.object({
 });
 function resolveApiUrl(apiUrl, urlPath) {
   const base = apiUrl.endsWith("/") ? apiUrl.slice(0, -1) : apiUrl;
-  const path10 = urlPath.startsWith("/") ? urlPath : `/${urlPath}`;
-  return new URL(`${base}${path10}`);
+  const path13 = urlPath.startsWith("/") ? urlPath : `/${urlPath}`;
+  return new URL(`${base}${path13}`);
 }
 
 // src/orchestrator.ts
@@ -1375,6 +1401,7 @@ async function runLocalTool(options) {
       prompt: options.prompt,
       promptFilePath,
       tool: options.tool ?? "auto",
+      invocationChannel: options.invocationChannel ?? "auto",
       ...options.model ? { model: options.model } : {}
     };
     if (options.toolCommand) {
@@ -1407,6 +1434,7 @@ async function createToolRunPreview(options) {
     prompt: options.prompt,
     promptFilePath,
     tool: options.tool ?? "auto",
+    invocationChannel: options.invocationChannel ?? "auto",
     ...options.model ? { model: options.model } : {}
   };
   if (options.toolCommand) {
@@ -1443,25 +1471,32 @@ async function createToolRunner(options) {
   if (tool === "none") {
     throw new Error("No local tool selected. Use --tool auto, a supported tool name, or --tool-command.");
   }
-  const adapter = tool === "auto" ? await selectFirstAvailableAdapter(Boolean(options.model)) : await selectRequestedAdapter(tool);
+  const adapter = tool === "auto" ? await selectFirstAvailableAdapter(Boolean(options.model), options.invocationChannel) : await selectRequestedAdapter(tool, options.invocationChannel);
   if (options.model && !adapter.supportsModelSelection) {
     throw new Error(`Model selection is not supported by ${adapter.name}. Remove --model or choose a model-aware adapter.`);
   }
-  if (adapter.runWithSdk && await isSdkAvailable(adapter)) {
+  if (options.invocationChannel !== "command" && adapter.runWithSdk && await isSdkAvailable(adapter)) {
     return {
       toolName: adapter.name,
       kind: "sdk",
       displayCommand: adapter.sdkDisplayCommand ?? `${adapter.name} SDK`,
-      adapter
+      adapter,
+      allowCommandFallback: options.invocationChannel === "auto"
     };
   }
-  if (adapter.buildInvocation && adapter.executable && await commandExists(adapter.executable)) {
+  if (options.invocationChannel !== "sdk" && adapter.buildInvocation && adapter.executable && await commandExists(adapter.executable)) {
     return {
       toolName: adapter.name,
       kind: "command",
       invocation: adapter.buildInvocation(options)
     };
   }
+  if (options.invocationChannel === "sdk") {
+    throw new Error(`The ${adapter.name} SDK was not found. Select Auto or Command invocation, install the SDK/runtime, or pass --tool-command locally.`);
+  }
+  if (options.invocationChannel === "command") {
+    throw new Error(`The ${adapter.name} executable was not found. Select Auto or SDK invocation, install the command, or pass --tool-command locally.`);
+  }
   throw new Error(`The ${adapter.name} SDK or executable was not found. Install the SDK/runtime or pass --tool-command.`);
 }
 async function executeToolRunner(runner2, input) {
@@ -1471,7 +1506,7 @@ async function executeToolRunner(runner2, input) {
   try {
     return await runner2.adapter.runWithSdk(input);
   } catch (error) {
-    if (runner2.adapter.buildInvocation && runner2.adapter.executable && await commandExists(runner2.adapter.executable)) {
+    if (runner2.allowCommandFallback && runner2.adapter.buildInvocation && runner2.adapter.executable && await commandExists(runner2.adapter.executable)) {
       const fallback = runner2.adapter.buildInvocation(input);
       const result = await executeToolInvocation(fallback, input.rootDir, input.streamOutput);
       const sdkFailure = `SDK execution for ${runner2.adapter.name} failed, fell back to ${fallback.displayCommand}: ${errorMessage(error)}`;
@@ -1490,34 +1525,53 @@ function normalizeToolRequest(value) {
   }
   throw new Error(`Unsupported local tool: ${value}. Supported tools: auto, none, ${localToolNames.join(", ")}.`);
 }
-async function selectFirstAvailableAdapter(requiresModelSelection = false) {
+async function selectFirstAvailableAdapter(requiresModelSelection = false, invocationChannel = "auto") {
   for (const adapter of localToolAdapters) {
     if (requiresModelSelection && !adapter.supportsModelSelection) {
       continue;
     }
     const sdkAvailable = await isSdkAvailable(adapter);
     const commandAvailable = adapter.executable ? await commandExists(adapter.executable) : false;
-    if (sdkAvailable || commandAvailable) {
+    if (supportsRequestedInvocationChannel({ sdkAvailable, commandAvailable }, invocationChannel)) {
       return adapter;
     }
   }
+  if (invocationChannel !== "auto") {
+    throw new Error(`No installed local AI tool supports ${invocationChannel} invocation${requiresModelSelection ? " with model selection" : ""}. Select Auto or install a compatible tool.`);
+  }
   throw new Error(
     requiresModelSelection ? "No installed local AI tool supports model selection. Remove --model or choose a model-aware adapter." : `No supported local AI tool was found. Install one of ${localToolNames.join(", ")} or pass --tool-command "your-tool --prompt-file {promptFile}".`
   );
 }
-async function selectRequestedAdapter(tool) {
+async function selectRequestedAdapter(tool, invocationChannel = "auto") {
   const adapter = localToolAdapters.find((candidate) => candidate.name === tool);
   if (!adapter) {
     throw new Error(`Unsupported local tool: ${tool}.`);
   }
-  if (await isSdkAvailable(adapter)) {
+  const sdkAvailable = await isSdkAvailable(adapter);
+  const commandAvailable = adapter.executable ? await commandExists(adapter.executable) : false;
+  if (!supportsRequestedInvocationChannel({ sdkAvailable, commandAvailable }, invocationChannel)) {
+    if (invocationChannel === "sdk") {
+      throw new Error(`The ${tool} SDK was not found. Select Auto or Command invocation, install it, or pass --tool-command locally.`);
+    }
+    if (invocationChannel === "command") {
+      throw new Error(`The ${tool} executable was not found. Select Auto or SDK invocation, install it, or pass --tool-command locally.`);
+    }
+    throw new Error(`The ${tool} SDK or executable was not found. Install it or pass --tool-command.`);
+  }
+  if (invocationChannel !== "command" && sdkAvailable) {
     return adapter;
   }
-  if (adapter.executable && await commandExists(adapter.executable)) {
+  if (invocationChannel !== "sdk" && commandAvailable) {
     return adapter;
   }
   throw new Error(`The ${tool} SDK or executable was not found. Install it or pass --tool-command.`);
 }
+function supportsRequestedInvocationChannel(capability, invocationChannel) {
+  if (invocationChannel === "auto") return capability.sdkAvailable || capability.commandAvailable;
+  if (invocationChannel === "sdk") return capability.sdkAvailable;
+  return capability.commandAvailable;
+}
 async function isSdkAvailable(adapter) {
   if (!adapter.sdkPackageName || !adapter.runWithSdk) {
     return false;
@@ -2484,12 +2538,782 @@ function watchStateKey(action) {
   return [action.kind, action.message, action.workItemId, action.documentId, action.runnerId].filter(Boolean).join(":");
 }
 
+// src/importer.ts
+import { execFile as execFile2 } from "node:child_process";
+import { createHash as createHash3 } from "node:crypto";
+import { readdir as readdir4, readFile as readFile6, stat as stat4 } from "node:fs/promises";
+import path9 from "node:path";
+import { promisify as promisify2 } from "node:util";
+var execFileAsync2 = promisify2(execFile2);
+var defaultMaxFileKb = 256;
+var controlPlaneRoots = ["architecture", "context", "decisions", "features", "memory", "plans", "prompts", "workflows"];
+var excludedDirectoryNames = /* @__PURE__ */ new Set([".git", "node_modules", ".pnpm-store", ".next", "dist", "build", "coverage", ".cache", "cache", "tmp", "temp", "vendor"]);
+var excludedFileNames = /* @__PURE__ */ new Set(["context/amistio-project.md"]);
+var generatedPathSegments = /* @__PURE__ */ new Set(["generated", "__generated__", "vendor", "vendors"]);
+var documentFolderByType = {
+  architecture: "architecture",
+  context: "context",
+  decision: "decisions",
+  feature: "features",
+  memory: "memory",
+  plan: "plans",
+  prompt: "prompts/shared",
+  workflow: "workflows"
+};
+async function inspectLocalRepository(rootDir, defaultBranch) {
+  const requestedRoot = path9.resolve(rootDir);
+  const root = await runGit2(["-C", requestedRoot, "rev-parse", "--show-toplevel"]).catch(() => requestedRoot);
+  const detectedBranch = await runGit2(["-C", root, "symbolic-ref", "--quiet", "--short", "HEAD"]).catch(() => defaultBranch);
+  const originUrl = await runGit2(["-C", root, "remote", "get-url", "origin"]).catch(() => void 0);
+  const parsedCloneUrl = originUrl ? parseOptionalOriginCloneUrl(originUrl) : void 0;
+  const repoName = (parsedCloneUrl?.repoName ?? path9.basename(root)) || "repository";
+  const fingerprintSeed = parsedCloneUrl ? `origin:${parsedCloneUrl.normalizedKey}` : `repo:${repoName}:${detectedBranch || defaultBranch}`;
+  return {
+    rootDir: root,
+    repoName,
+    defaultBranch: detectedBranch || defaultBranch,
+    repoFingerprint: `import_${hashText(fingerprintSeed, 24)}`,
+    ...parsedCloneUrl ? { parsedCloneUrl } : {},
+    ...!parsedCloneUrl && originUrl ? { originRemoteWarning: "Origin remote is not a supported hosted HTTPS or SSH clone URL, so no clone URL will be stored." } : {}
+  };
+}
+async function scanLegacyDocuments(options) {
+  const rootDir = path9.resolve(options.rootDir);
+  const maxBytes = (options.maxFileKb ?? defaultMaxFileKb) * 1024;
+  const skipped = [];
+  const candidates = [];
+  const usedDestinationPaths = /* @__PURE__ */ new Set();
+  const repoPaths = (await listRepositoryPaths(rootDir)).sort((first, second) => first.localeCompare(second));
+  for (const repoPath of repoPaths) {
+    if (!matchesIncludeExclude(repoPath, options.include, options.exclude)) {
+      skipped.push({ repoPath, reason: "excluded" });
+      continue;
+    }
+    if (!isMarkdownDocument(repoPath)) {
+      skipped.push({ repoPath, reason: "notMarkdown" });
+      continue;
+    }
+    if (isExcludedRepoPath(repoPath)) {
+      skipped.push({ repoPath, reason: "excluded" });
+      continue;
+    }
+    const fullPath = path9.join(rootDir, ...repoPath.split("/"));
+    const fileStat = await stat4(fullPath).catch(() => void 0);
+    if (!fileStat?.isFile()) {
+      skipped.push({ repoPath, reason: "unreadable" });
+      continue;
+    }
+    if (fileStat.size > maxBytes) {
+      skipped.push({ repoPath, reason: "tooLarge" });
+      continue;
+    }
+    const content = await readFile6(fullPath, "utf8").catch(() => void 0);
+    if (content === void 0) {
+      skipped.push({ repoPath, reason: "unreadable" });
+      continue;
+    }
+    if (isAmistioManagedMarkdown(content)) {
+      skipped.push({ repoPath, reason: "alreadyManaged" });
+      continue;
+    }
+    const documentType = classifyLegacyDocument(repoPath, content);
+    const destinationPath = uniqueDestinationPath(canonicalImportPath(repoPath, documentType), repoPath, usedDestinationPaths);
+    candidates.push({
+      sourcePath: repoPath,
+      repoPath: destinationPath,
+      documentType,
+      title: inferTitle2(content, repoPath),
+      content,
+      contentHash: sha256ContentHash(content)
+    });
+  }
+  return { candidates, skipped };
+}
+function buildImportedBrainDocuments(options) {
+  const importedAt = options.importedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const existingById = new Map((options.existingDocuments ?? []).map((document) => [document.documentId, document]));
+  return options.candidates.map((candidate) => {
+    const documentId = stableImportDocumentId(options.accountId, options.projectId, options.repositoryLinkId, candidate.sourcePath);
+    const existing = existingById.get(documentId);
+    const revision = existing ? existing.contentHash === candidate.contentHash ? existing.revision : existing.revision + 1 : 0;
+    return {
+      id: documentId,
+      type: "brainDocument",
+      schemaVersion: 1,
+      accountId: options.accountId,
+      projectId: options.projectId,
+      documentId,
+      documentType: candidate.documentType,
+      title: candidate.title,
+      status: "reviewing",
+      repoPath: candidate.repoPath,
+      content: candidate.content,
+      contentHash: candidate.contentHash,
+      frontmatter: {
+        ...existing?.frontmatter ?? {},
+        legacySourcePath: candidate.sourcePath,
+        importedByCommand: "amistio import",
+        importedAt,
+        importedSourceHash: candidate.contentHash
+      },
+      revision,
+      source: "repo",
+      syncState: "dirtyInRepo",
+      createdAt: existing?.createdAt ?? importedAt,
+      updatedAt: importedAt,
+      ...existing?.approvedRevision !== void 0 ? { approvedRevision: existing.approvedRevision } : {}
+    };
+  });
+}
+function importSkipCounts(skipped) {
+  return {
+    notMarkdown: skipped.filter((item) => item.reason === "notMarkdown").length,
+    excluded: skipped.filter((item) => item.reason === "excluded").length,
+    tooLarge: skipped.filter((item) => item.reason === "tooLarge").length,
+    alreadyManaged: skipped.filter((item) => item.reason === "alreadyManaged").length,
+    unreadable: skipped.filter((item) => item.reason === "unreadable").length
+  };
+}
+function parseOptionalOriginCloneUrl(originUrl) {
+  try {
+    return parseRepositoryCloneUrl(originUrl);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.toLowerCase().includes("credential") || message.toLowerCase().includes("password")) {
+      throw new Error("Repository origin remote contains embedded credentials. Remove credentials from the remote URL before importing.");
+    }
+    return void 0;
+  }
+}
+async function listRepositoryPaths(rootDir) {
+  const gitFiles = await runGit2(["-C", rootDir, "ls-files", "--cached", "--others", "--exclude-standard"]).catch(() => void 0);
+  if (gitFiles !== void 0) {
+    return gitFiles.split("\n").map((line) => normalizeRepoPath2(line)).filter((line) => line.length > 0);
+  }
+  const files = [];
+  await walkRepository(rootDir, rootDir, files);
+  return files;
+}
+async function walkRepository(rootDir, directory, files) {
+  const entries = await readdir4(directory, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    const fullPath = path9.join(directory, entry.name);
+    const repoPath = normalizeRepoPath2(path9.relative(rootDir, fullPath));
+    if (entry.isDirectory()) {
+      if (!excludedDirectoryNames.has(entry.name)) {
+        await walkRepository(rootDir, fullPath, files);
+      }
+    } else if (entry.isFile() && !isExcludedRepoPath(repoPath)) {
+      files.push(repoPath);
+    }
+  }
+}
+function matchesIncludeExclude(repoPath, include, exclude) {
+  if (include?.length && !include.some((pattern) => wildcardMatch(pattern, repoPath))) {
+    return false;
+  }
+  if (exclude?.some((pattern) => wildcardMatch(pattern, repoPath))) {
+    return false;
+  }
+  return true;
+}
+function wildcardMatch(pattern, repoPath) {
+  const normalizedPattern = normalizeRepoPath2(pattern);
+  const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "::DOUBLE_STAR_SLASH::").replace(/\*\*/g, "::DOUBLE_STAR::").replace(/\?/g, "[^/]").replace(/\*/g, "[^/]*").replace(/::DOUBLE_STAR_SLASH::/g, "(?:.*/)?").replace(/::DOUBLE_STAR::/g, ".*");
+  return new RegExp(`^${escaped}$`).test(repoPath);
+}
+function isMarkdownDocument(repoPath) {
+  return /\.(md|mdx)$/i.test(repoPath);
+}
+function isExcludedRepoPath(repoPath) {
+  if (excludedFileNames.has(repoPath)) return true;
+  const segments = repoPath.split("/");
+  if (segments.some((segment) => excludedDirectoryNames.has(segment) || generatedPathSegments.has(segment))) return true;
+  const basename = segments[segments.length - 1]?.toLowerCase() ?? "";
+  return basename.startsWith(".env") || basename.includes("secret") || basename.includes("token") || basename.includes("credential") || basename.endsWith(".lock");
+}
+function isAmistioManagedMarkdown(content) {
+  const frontmatter = parseFrontmatter(content);
+  return typeof frontmatter.amistioDocumentId === "string" && frontmatter.amistioDocumentId.trim().length > 0;
+}
+function classifyLegacyDocument(repoPath, content) {
+  const haystack = `${repoPath} ${inferTitle2(content, repoPath)}`.toLowerCase();
+  if (/\b(prompt|prompts|instruction|instructions|copilot|agent|skill)\b/.test(haystack)) return "prompt";
+  if (/\b(adr|decision|decisions|rfc)\b/.test(haystack)) return "decision";
+  if (/\b(architecture|architectural|design|system|technical|tech-spec)\b/.test(haystack)) return "architecture";
+  if (/\b(feature|features|spec|requirements|prd|story|stories)\b/.test(haystack)) return "feature";
+  if (/\b(memory|memories|lesson|lessons|mistake|mistakes|learning|retro|retrospective)\b/.test(haystack)) return "memory";
+  if (/\b(plan|plans|roadmap|milestone|todo|task|tasks)\b/.test(haystack)) return "plan";
+  if (/\b(workflow|workflows|runbook|playbook|process|procedure|ops)\b/.test(haystack)) return "workflow";
+  return "context";
+}
+function canonicalImportPath(sourcePath, documentType) {
+  if (isControlPlanePath2(sourcePath)) {
+    return sourcePath;
+  }
+  const baseSlug = slugFromPath(sourcePath);
+  return `${documentFolderByType[documentType]}/imported/${baseSlug}.md`;
+}
+function uniqueDestinationPath(basePath, sourcePath, usedPaths) {
+  if (!usedPaths.has(basePath)) {
+    usedPaths.add(basePath);
+    return basePath;
+  }
+  const extension = path9.posix.extname(basePath) || ".md";
+  const directory = path9.posix.dirname(basePath);
+  const basename = path9.posix.basename(basePath, extension);
+  const uniquePath = `${directory}/${basename}-${hashText(sourcePath, 8)}${extension}`;
+  usedPaths.add(uniquePath);
+  return uniquePath;
+}
+function isControlPlanePath2(repoPath) {
+  const [firstSegment] = repoPath.split("/");
+  return Boolean(firstSegment && controlPlaneRoots.includes(firstSegment));
+}
+function inferTitle2(content, repoPath) {
+  const body = stripFrontmatter(content);
+  const heading = body.split("\n").find((line) => /^#\s+/.test(line))?.replace(/^#\s+/, "").trim();
+  if (heading) return heading;
+  const basename = path9.posix.basename(repoPath, path9.posix.extname(repoPath)).replace(/[-_]+/g, " ").trim();
+  return titleCase(basename || "Imported Document");
+}
+function stripFrontmatter(content) {
+  if (!content.startsWith("---\n")) return content;
+  const end = content.indexOf("\n---", 4);
+  if (end === -1) return content;
+  const closingLineEnd = content.indexOf("\n", end + 4);
+  return closingLineEnd === -1 ? "" : content.slice(closingLineEnd + 1);
+}
+function slugFromPath(repoPath) {
+  const withoutExtension = repoPath.replace(/\.(md|mdx)$/i, "");
+  const slug = withoutExtension.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 90);
+  return slug || "imported-document";
+}
+function titleCase(value) {
+  return value.replace(/\b\w/g, (match) => match.toUpperCase());
+}
+function stableImportDocumentId(accountId, projectId, repositoryLinkId, sourcePath) {
+  return `doc_import_${hashText(`${accountId}\0${projectId}\0${repositoryLinkId}\0${sourcePath}`, 24)}`;
+}
+function hashText(value, length) {
+  return createHash3("sha256").update(value).digest("hex").slice(0, length);
+}
+function normalizeRepoPath2(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+async function runGit2(args) {
+  const { stdout } = await execFileAsync2("git", args, { maxBuffer: 10 * 1024 * 1024 });
+  return stdout.trim();
+}
+
+// src/runner-actions.ts
+import { spawn as spawn3 } from "node:child_process";
+import path10 from "node:path";
+function buildBackgroundRunnerArgs(options) {
+  const args = [
+    "run",
+    "--watch",
+    "--api-url",
+    options.apiUrl,
+    "--runner-id",
+    options.runnerId,
+    "--root",
+    path10.resolve(options.root),
+    "--session",
+    options.session,
+    "--interval-seconds",
+    String(options.intervalSeconds)
+  ];
+  if (options.tool) {
+    args.push("--tool", options.tool);
+  }
+  if (options.invocationChannel) {
+    args.push("--invocation-channel", options.invocationChannel);
+  }
+  if (options.toolCommand) {
+    args.push("--tool-command", options.toolCommand);
+  }
+  if (options.model) {
+    args.push("--model", options.model);
+  }
+  if (options.maxIterations !== void 0) {
+    args.push("--max-iterations", String(options.maxIterations));
+  }
+  if (!options.stream) {
+    args.push("--no-stream");
+  }
+  return args;
+}
+async function runOfficialCliUpdate() {
+  const result = await runOfficialUpdateProcess("npm", ["install", "-g", "@amistio/cli"], 12e4);
+  if (result.exitCode === 0) {
+    return { succeeded: true, message: "Official Amistio CLI update command completed." };
+  }
+  return { succeeded: false, message: "Official Amistio CLI update command failed.", error: result.output || `npm exited with code ${result.exitCode}.` };
+}
+function runOfficialUpdateProcess(command, args, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn3(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let output = "";
+    const updateTimeout = setTimeout(() => {
+      output += "Timed out while running official CLI update.\n";
+      child.kill("SIGTERM");
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => {
+      output += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += chunk.toString("utf8");
+    });
+    child.on("error", (error) => {
+      clearTimeout(updateTimeout);
+      resolve({ exitCode: 1, output: error.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(updateTimeout);
+      resolve({ exitCode: code ?? 1, output: truncateProcessOutput(output) });
+    });
+  });
+}
+function truncateProcessOutput(value) {
+  const trimmed = value.trim();
+  return trimmed.length > 1200 ? `${trimmed.slice(0, 1200)}...` : trimmed;
+}
+
+// src/runner-tui.ts
+import { randomUUID } from "node:crypto";
+import { readFile as readFile7 } from "node:fs/promises";
+import os5 from "node:os";
+import path11 from "node:path";
+import * as readline from "node:readline";
+async function runRunnerTui(options) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  if (!input.isTTY || !output.isTTY) {
+    output.write(`${runnerTuiNonInteractiveMessage()}
+`);
+    return;
+  }
+  let selectedIndex = 0;
+  let message;
+  let state = await loadRunnerTuiState(options);
+  const render = async () => {
+    state = await loadRunnerTuiState(options);
+    selectedIndex = clampSelectedIndex(state, selectedIndex);
+    output.write(`\x1B[?25l\x1B[2J\x1B[H${renderRunnerTuiScreen(state, selectedIndex, { columns: output.columns, rows: output.rows, ...message ? { message } : {} })}`);
+  };
+  readline.emitKeypressEvents(input);
+  input.setRawMode?.(true);
+  input.resume();
+  await render();
+  await new Promise((resolve) => {
+    let busy = false;
+    const keypressHandler = (character, key) => {
+      if (busy) return;
+      busy = true;
+      void handleRunnerTuiKey({ character, input, key, output, options, selectedIndex, state }).then(async (result) => {
+        if (result.quit) {
+          teardownRunnerTui(input, output, keypressHandler);
+          resolve();
+          return;
+        }
+        selectedIndex = result.selectedIndex;
+        message = result.message;
+        await render();
+      }).catch(async (error) => {
+        message = error instanceof Error ? error.message : String(error);
+        await render();
+      }).finally(() => {
+        busy = false;
+      });
+    };
+    input.on("keypress", keypressHandler);
+  });
+}
+async function loadRunnerTuiState(options) {
+  const resolvedRoot = path11.resolve(options.root);
+  const metadata = await readProjectLink(resolvedRoot);
+  const credentialStore = options.credentialStore ?? new LocalCredentialStore();
+  if (!metadata) {
+    return createRunnerTuiState({ root: resolvedRoot, apiUrl: options.apiUrl, remoteEnabled: options.remote, credentialPresent: false, remoteError: "Repository is not paired. Run `amistio pair` or `amistio import <code>` first." });
+  }
+  const token = await credentialStore.get(credentialKey(metadata.amistioAccountId, metadata.amistioProjectId, metadata.repositoryLinkId));
+  const localRecords = await listRunnerDaemonMetadata({
+    accountId: metadata.amistioAccountId,
+    projectId: metadata.amistioProjectId,
+    repositoryLinkId: metadata.repositoryLinkId,
+    ...options.runnerId ? { runnerId: options.runnerId } : {}
+  }, options.metadataDir);
+  if (!options.remote) {
+    return createRunnerTuiState({ root: resolvedRoot, apiUrl: options.apiUrl, remoteEnabled: false, credentialPresent: Boolean(token), metadata, localRecords });
+  }
+  if (!token) {
+    return createRunnerTuiState({ root: resolvedRoot, apiUrl: options.apiUrl, remoteEnabled: true, credentialPresent: false, metadata, localRecords, remoteError: "Remote runner state was not loaded because this checkout has no local runner credential." });
+  }
+  const client = new ApiClient({ apiUrl: options.apiUrl, accountId: metadata.amistioAccountId, token });
+  try {
+    const [{ runners }, preferences] = await Promise.all([
+      client.listRunners(metadata.amistioProjectId),
+      client.getRunnerPreferences(metadata.amistioProjectId).catch(() => void 0)
+    ]);
+    const projectRunners = runners.filter((runner2) => runner2.repositoryLinkId === metadata.repositoryLinkId).filter((runner2) => !options.runnerId || runner2.runnerId === options.runnerId);
+    const commandGroups = await Promise.all(projectRunners.map((runner2) => client.listRunnerCommands(metadata.amistioProjectId, runner2.runnerId, runner2.repositoryLinkId).then((result) => result.commands).catch(() => [])));
+    return createRunnerTuiState({
+      root: resolvedRoot,
+      apiUrl: options.apiUrl,
+      remoteEnabled: true,
+      credentialPresent: true,
+      metadata,
+      localRecords,
+      remoteRunners: projectRunners,
+      remoteCommands: commandGroups.flat(),
+      ...preferences ? { preferences } : {}
+    });
+  } catch (error) {
+    return createRunnerTuiState({ root: resolvedRoot, apiUrl: options.apiUrl, remoteEnabled: true, credentialPresent: true, metadata, localRecords, remoteError: error instanceof Error ? error.message : String(error) });
+  }
+}
+function createRunnerTuiState(input) {
+  const localRecords = input.localRecords ?? [];
+  const remoteRunners = input.remoteRunners ?? [];
+  const remoteCommands = input.remoteCommands ?? [];
+  const runnersByKey = /* @__PURE__ */ new Map();
+  for (const record of localRecords) {
+    const runnerKey = runnerKeyFor(record.runnerId, record.repositoryLinkId);
+    runnersByKey.set(runnerKey, {
+      runnerId: record.runnerId,
+      repositoryLinkId: record.repositoryLinkId,
+      source: "local",
+      local: {
+        metadata: record,
+        runtimeStatus: runnerDaemonRuntimeStatus(record),
+        uptime: runnerDaemonRuntimeStatus(record) === "running" ? runnerDaemonUptime(record, input.nowMs) : "not running"
+      }
+    });
+  }
+  for (const heartbeat of remoteRunners) {
+    const runnerKey = runnerKeyFor(heartbeat.runnerId, heartbeat.repositoryLinkId);
+    const existing = runnersByKey.get(runnerKey);
+    const latestCommand = latestRunnerCommand(remoteCommands, heartbeat.runnerId, heartbeat.repositoryLinkId);
+    if (existing) {
+      runnersByKey.set(runnerKey, { ...existing, heartbeat, ...latestCommand ? { latestCommand } : {} });
+    } else {
+      runnersByKey.set(runnerKey, { runnerId: heartbeat.runnerId, repositoryLinkId: heartbeat.repositoryLinkId, source: "remote", heartbeat, ...latestCommand ? { latestCommand } : {} });
+    }
+  }
+  const runners = [...runnersByKey.values()].sort((first, second) => {
+    if (first.source !== second.source) return first.source === "local" ? -1 : 1;
+    return first.runnerId.localeCompare(second.runnerId);
+  });
+  return {
+    root: path11.resolve(input.root),
+    apiUrl: input.apiUrl,
+    paired: Boolean(input.metadata),
+    credentialPresent: input.credentialPresent,
+    remoteEnabled: input.remoteEnabled,
+    runners,
+    localRunnerCount: localRecords.length,
+    remoteRunnerCount: remoteRunners.length,
+    ...input.metadata ? { metadata: input.metadata } : {},
+    ...input.preferences ? { preferences: input.preferences } : {},
+    ...input.remoteError ? { remoteError: input.remoteError } : {}
+  };
+}
+function renderRunnerTuiScreen(state, selectedIndex = 0, options = {}) {
+  const columns = Math.max(40, options.columns ?? 100);
+  const rows = Math.max(8, options.rows ?? 32);
+  const selectedRunner = state.runners[clampSelectedIndex(state, selectedIndex)];
+  const lines = [];
+  lines.push("Amistio Runner UI");
+  lines.push(`Project: ${state.metadata?.amistioProjectId ?? "unpaired"}  Repository link: ${state.metadata?.repositoryLinkId ?? "none"}`);
+  lines.push(`API: ${state.apiUrl}`);
+  lines.push(`Root: ${state.root}`);
+  lines.push(`Credential: ${state.credentialPresent ? "available" : "missing"}  Remote: ${state.remoteEnabled ? state.remoteError ? "warning" : "enabled" : "local only"}`);
+  if (state.remoteError) lines.push(`Remote: ${state.remoteError}`);
+  lines.push(`Preferences: ${formatPreferenceSummary(state.preferences)}`);
+  lines.push("");
+  lines.push(`Runners (${state.localRunnerCount} local, ${state.remoteRunnerCount} remote heartbeat${state.remoteRunnerCount === 1 ? "" : "s"})`);
+  if (!state.runners.length) {
+    lines.push("  No runner records found. Press s to start a background runner, or run `amistio run --background`.");
+  }
+  state.runners.forEach((runner2, index) => {
+    const marker = index === clampSelectedIndex(state, selectedIndex) ? ">" : " ";
+    lines.push(`${marker} ${formatRunnerListLine(runner2)}`);
+  });
+  lines.push("");
+  lines.push("Details");
+  if (selectedRunner) {
+    lines.push(...formatRunnerDetails(selectedRunner));
+  } else {
+    lines.push("  No runner selected.");
+  }
+  lines.push("");
+  lines.push("Preference Editing");
+  lines.push("  Account/project runner preferences are read-only here until a user-authenticated CLI path exists.");
+  const availability = runnerTuiActionAvailability(state, selectedIndex);
+  lines.push(`Actions: r refresh | s start${availability.start ? "" : " (needs credential)"} | x stop | b restart | u update CLI | d local remove | l logs | q quit`);
+  if (options.message) {
+    lines.push("");
+    lines.push("Status");
+    lines.push(...options.message.split("\n").map((line) => `  ${line}`));
+  }
+  return `${lines.slice(0, rows).map((line) => fitLine(line, columns)).join("\n")}
+`;
+}
+function runnerTuiActionAvailability(state, selectedIndex = 0) {
+  const selectedRunner = state.runners[clampSelectedIndex(state, selectedIndex)];
+  return {
+    start: state.paired && state.credentialPresent,
+    stop: Boolean(selectedRunner?.local),
+    restart: Boolean(selectedRunner?.local),
+    update: state.paired,
+    localRemove: state.paired && state.credentialPresent,
+    logs: Boolean(selectedRunner?.local?.metadata.logPath)
+  };
+}
+function runnerTuiNonInteractiveMessage() {
+  return "Terminal UI requires an interactive TTY. Use `amistio runner status` for status or `amistio run --background` to start a background runner.";
+}
+async function handleRunnerTuiKey({ character, input, key, options, output, selectedIndex, state }) {
+  if (key.ctrl && key.name === "c" || character === "q") return { quit: true, selectedIndex };
+  if (key.name === "up") return { selectedIndex: Math.max(0, selectedIndex - 1) };
+  if (key.name === "down") return { selectedIndex: Math.min(Math.max(0, state.runners.length - 1), selectedIndex + 1) };
+  if (character === "r") return { selectedIndex, message: "Refreshed runner state." };
+  if (character === "s") return { selectedIndex, message: await promptAndStartRunner(state, options, input, output) };
+  if (character === "x") return { selectedIndex, message: await stopSelectedRunner(state, selectedIndex, options) };
+  if (character === "b") return { selectedIndex, message: await restartSelectedRunner(state, selectedIndex, options) };
+  if (character === "u") return { selectedIndex, message: await confirmAndUpdateCli(input, output) };
+  if (character === "d") return { selectedIndex, message: await confirmAndRemoveLocalCredential(state, options, input, output) };
+  if (character === "l") return { selectedIndex, message: await readSelectedRunnerLog(state, selectedIndex) };
+  return { selectedIndex, message: "Unknown key. Use r, s, x, b, u, d, l, or q." };
+}
+async function promptAndStartRunner(state, options, input, output) {
+  const context = await loadRunnerTuiContext(state, options);
+  if (!context.token) {
+    return "Cannot start a background runner because this checkout has no local runner credential.";
+  }
+  const startOptions = await promptForStartRunnerOptions(input, output, options);
+  const metadata = await startRunnerDaemon({
+    accountId: context.metadata.amistioAccountId,
+    projectId: context.metadata.amistioProjectId,
+    repositoryLinkId: context.metadata.repositoryLinkId,
+    runnerId: startOptions.runnerId,
+    rootDir: path11.resolve(options.root),
+    apiUrl: options.apiUrl,
+    args: buildBackgroundRunnerArgs({
+      apiUrl: options.apiUrl,
+      runnerId: startOptions.runnerId,
+      root: options.root,
+      ...startOptions.tool ? { tool: startOptions.tool } : {},
+      ...startOptions.invocationChannel ? { invocationChannel: startOptions.invocationChannel } : {},
+      ...startOptions.model ? { model: startOptions.model } : {},
+      session: startOptions.session,
+      intervalSeconds: startOptions.intervalSeconds,
+      stream: startOptions.stream
+    }),
+    ...options.metadataDir ? { metadataDir: options.metadataDir } : {}
+  });
+  return `Started background runner ${metadata.runnerId} with PID ${metadata.pid}.${metadata.logPath ? `
+Log: ${metadata.logPath}` : ""}`;
+}
+async function promptForStartRunnerOptions(input, output, options) {
+  const runnerId = (await promptLine(input, output, `Runner ID [${options.runnerId ?? "new"}]: `)).trim() || options.runnerId || `runner_${randomUUID()}`;
+  const tool = parseOptionalTool(await promptLine(input, output, "AI tool / SDK [remote preference; auto, none, opencode, claude, codex, copilot, gemini, aider, cursor-agent]: "));
+  const invocationChannel = parseOptionalInvocationChannel(await promptLine(input, output, "Invocation channel [remote preference; auto, sdk, command]: "));
+  const model = optionalTrim(await promptLine(input, output, "Model [provider default]: "));
+  const sessionInput = optionalTrim(await promptLine(input, output, "Session policy [auto]: ")) ?? "auto";
+  const session = sessionPolicySchema.parse(sessionInput);
+  const intervalInput = optionalTrim(await promptLine(input, output, `Polling interval seconds [${options.intervalSeconds}]: `));
+  const intervalSeconds = intervalInput ? parsePositiveInteger(intervalInput) : options.intervalSeconds;
+  const streamInput = optionalTrim(await promptLine(input, output, "Stream output from background runner? [Y/n]: "));
+  const stream = !streamInput || streamInput.toLowerCase() === "y" || streamInput.toLowerCase() === "yes";
+  return { runnerId, ...tool ? { tool } : {}, ...invocationChannel ? { invocationChannel } : {}, ...model ? { model } : {}, session, intervalSeconds, stream };
+}
+async function stopSelectedRunner(state, selectedIndex, options) {
+  const selectedRunner = state.runners[clampSelectedIndex(state, selectedIndex)];
+  if (!selectedRunner?.local) return "Select a local background runner to stop.";
+  const stopResult = await stopRunnerDaemonProcess(selectedRunner.local.metadata);
+  await markRunnerDaemonStopped(selectedRunner.local.metadata, options.metadataDir);
+  const context = await loadRunnerTuiContext(state, options).catch(() => void 0);
+  if (context?.token) {
+    await context.client.sendRunnerHeartbeat(context.metadata.amistioProjectId, selectedRunner.runnerId, selectedRunner.repositoryLinkId, "offline", { version: "0.1.3", mode: "background", hostname: os5.hostname() }).catch(() => void 0);
+  }
+  return stopResult === "stopped" ? `Stopped background runner ${selectedRunner.runnerId}.` : `Marked background runner ${selectedRunner.runnerId} stopped; process was not running.`;
+}
+async function restartSelectedRunner(state, selectedIndex, options) {
+  const selectedRunner = state.runners[clampSelectedIndex(state, selectedIndex)];
+  if (!selectedRunner?.local) return "Select a local background runner to restart.";
+  await stopRunnerDaemonProcess(selectedRunner.local.metadata).catch(() => "not-running");
+  await markRunnerDaemonStopped(selectedRunner.local.metadata, options.metadataDir);
+  const replacement = await restartRunnerDaemonProcess(
+    selectedRunner.local.metadata,
+    buildBackgroundRunnerArgs({ apiUrl: selectedRunner.local.metadata.apiUrl, runnerId: selectedRunner.runnerId, root: selectedRunner.local.metadata.rootDir, session: "auto", intervalSeconds: options.intervalSeconds, stream: true }),
+    { ...options.metadataDir ? { metadataDir: options.metadataDir } : {} }
+  );
+  return `Restarted background runner ${replacement.runnerId} with PID ${replacement.pid}.`;
+}
+async function confirmAndUpdateCli(input, output) {
+  const confirmation = await promptLine(input, output, "Run the official Amistio CLI update now? Type update to continue: ");
+  if (confirmation.trim() !== "update") return "Update cancelled.";
+  const result = await runOfficialCliUpdate();
+  return result.succeeded ? result.message : `${result.message}${result.error ? `
+${result.error}` : ""}`;
+}
+async function confirmAndRemoveLocalCredential(state, options, input, output) {
+  const context = await loadRunnerTuiContext(state, options);
+  if (!context.token) return "No local runner credential is stored for this paired repository.";
+  const confirmation = await promptLine(input, output, "Remove this machine's runner credential? This does not delete source files, local checkouts, hosted repositories, project records, or team data. Type remove local to continue: ");
+  if (confirmation.trim() !== "remove local") return "Local remove cancelled.";
+  const localRunners = state.runners.filter((runner2) => runner2.local);
+  for (const runner2 of localRunners) {
+    await stopRunnerDaemonProcess(runner2.local.metadata).catch(() => "not-running");
+    await markRunnerDaemonStopped(runner2.local.metadata, options.metadataDir).catch(() => void 0);
+    await context.client.sendRunnerHeartbeat(context.metadata.amistioProjectId, runner2.runnerId, runner2.repositoryLinkId, "offline", { version: "0.1.3", mode: "background", hostname: os5.hostname() }).catch(() => void 0);
+  }
+  await context.credentialStore.delete(credentialKey(context.metadata.amistioAccountId, context.metadata.amistioProjectId, context.metadata.repositoryLinkId));
+  return `Removed this machine's local runner credential for ${context.metadata.repositoryLinkId}. Source files, hosted repositories, project records, and team data were not deleted.`;
+}
+async function readSelectedRunnerLog(state, selectedIndex) {
+  const selectedRunner = state.runners[clampSelectedIndex(state, selectedIndex)];
+  const logPath = selectedRunner?.local?.metadata.logPath;
+  if (!logPath) return "Selected runner has no local log path.";
+  try {
+    const content = await readFile7(logPath, "utf8");
+    const excerpt = content.trim().slice(-3e3);
+    return excerpt ? `Log: ${logPath}
+${excerpt}` : `Log: ${logPath}
+No log output yet.`;
+  } catch (error) {
+    return `Could not read ${logPath}: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+async function loadRunnerTuiContext(state, options) {
+  if (!state.metadata) {
+    throw new Error("Repository is not paired. Run `amistio pair` or `amistio import <code>` first.");
+  }
+  const credentialStore = options.credentialStore ?? new LocalCredentialStore();
+  const token = await credentialStore.get(credentialKey(state.metadata.amistioAccountId, state.metadata.amistioProjectId, state.metadata.repositoryLinkId));
+  return {
+    metadata: state.metadata,
+    credentialStore,
+    ...token ? { token } : {},
+    client: new ApiClient({ apiUrl: options.apiUrl, accountId: state.metadata.amistioAccountId, ...token ? { token } : {} })
+  };
+}
+function formatRunnerListLine(runner2) {
+  const local = runner2.local ? `local ${runner2.local.metadata.status}/${runner2.local.runtimeStatus} pid ${runner2.local.metadata.pid}` : "remote-only";
+  const heartbeat = runner2.heartbeat ? `heartbeat ${runner2.heartbeat.status}${runner2.heartbeat.mode ? ` ${runner2.heartbeat.mode}` : ""} ${runner2.heartbeat.lastSeenAt}` : "no heartbeat";
+  return `${runner2.runnerId} | ${local} | ${heartbeat}`;
+}
+function formatRunnerDetails(runner2) {
+  const lines = [];
+  lines.push(`  Runner ID: ${runner2.runnerId}`);
+  lines.push(`  Repository link: ${runner2.repositoryLinkId}`);
+  if (runner2.local) {
+    lines.push(`  Local process: ${runner2.local.runtimeStatus}, PID ${runner2.local.metadata.pid}, uptime ${runner2.local.uptime}`);
+    lines.push(`  Local root: ${runner2.local.metadata.rootDir}`);
+    lines.push(`  Host: ${runner2.local.metadata.hostname}`);
+    if (runner2.local.metadata.logPath) lines.push(`  Log: ${runner2.local.metadata.logPath}`);
+  } else {
+    lines.push("  Local process: not on this machine");
+  }
+  if (runner2.heartbeat) {
+    const effectiveTool = runner2.heartbeat.effectiveTool ?? runner2.heartbeat.requestedTool ?? "unknown";
+    const requestedTool = runner2.heartbeat.requestedTool ?? "auto";
+    const channel = runner2.heartbeat.effectiveInvocationChannel ?? runner2.heartbeat.requestedInvocationChannel ?? "auto";
+    lines.push(`  Last heartbeat: ${runner2.heartbeat.status} at ${runner2.heartbeat.lastSeenAt}${runner2.heartbeat.version ? ` (${runner2.heartbeat.version})` : ""}`);
+    lines.push(`  Tool: ${requestedTool}${effectiveTool !== requestedTool ? ` -> ${effectiveTool}` : ""}`);
+    lines.push(`  Channel: ${channel}`);
+    lines.push(`  Model: ${runner2.heartbeat.effectiveModel ?? "provider default"}`);
+    lines.push(`  Preference: ${runner2.heartbeat.preferenceSource ?? "default"} / ${runner2.heartbeat.preferenceStatus ?? "pending"}`);
+    if (runner2.heartbeat.preferenceMessage) lines.push(`  Warning: ${runner2.heartbeat.preferenceMessage}`);
+    lines.push(`  Capabilities: ${formatCapabilities(runner2.heartbeat)}`);
+  } else {
+    lines.push("  Last heartbeat: not loaded");
+  }
+  if (runner2.latestCommand) {
+    lines.push(`  Latest command: ${runner2.latestCommand.commandKind} ${runner2.latestCommand.status}${runner2.latestCommand.message ? ` - ${runner2.latestCommand.message}` : ""}`);
+  } else {
+    lines.push("  Latest command: none loaded");
+  }
+  return lines;
+}
+function formatCapabilities(runner2) {
+  const availableCapabilities = runner2.capabilities?.filter((capability) => capability.available) ?? [];
+  if (!availableCapabilities.length) return "unknown";
+  return availableCapabilities.map((capability) => `${capability.name} (${capability.sdkAvailable && capability.commandAvailable ? "sdk+command" : capability.sdkAvailable ? "sdk" : capability.commandAvailable ? "command" : capability.execution})`).join(", ");
+}
+function formatPreferenceSummary(preferences) {
+  if (!preferences) return "not loaded";
+  const effective = preferences.effective;
+  return `${effective.source}: ${effective.tool} / ${effective.invocationChannel} / ${effective.model ?? "provider default"}${formatSettingsSuffix(preferences.project, "project")}${formatSettingsSuffix(preferences.account, "account")}`;
+}
+function formatSettingsSuffix(settings, label) {
+  if (!settings) return "";
+  const preference = settings.preferences;
+  return `; ${label} ${preference.tool ?? "unset"}/${preference.invocationChannel ?? "unset"}/${preference.model ?? "provider default"}`;
+}
+function latestRunnerCommand(commands, runnerId, repositoryLinkId) {
+  return commands.filter((command) => command.runnerId === runnerId && command.repositoryLinkId === repositoryLinkId).sort((first, second) => Date.parse(second.createdAt) - Date.parse(first.createdAt))[0];
+}
+function runnerKeyFor(runnerId, repositoryLinkId) {
+  return `${repositoryLinkId}:${runnerId}`;
+}
+function clampSelectedIndex(state, selectedIndex) {
+  if (!state.runners.length) return 0;
+  return Math.max(0, Math.min(state.runners.length - 1, selectedIndex));
+}
+function fitLine(line, columns) {
+  if (line.length <= columns) return line;
+  return `${line.slice(0, Math.max(0, columns - 3))}...`;
+}
+function parseOptionalTool(value) {
+  const trimmed = optionalTrim(value);
+  if (!trimmed) return void 0;
+  if (trimmed === "auto" || trimmed === "none" || runnerToolNames.includes(trimmed)) {
+    return trimmed;
+  }
+  throw new Error(`Expected auto, none, ${runnerToolNames.join(", ")}; received ${trimmed}.`);
+}
+function parseOptionalInvocationChannel(value) {
+  const trimmed = optionalTrim(value);
+  if (!trimmed) return void 0;
+  return runnerInvocationChannelSchema.parse(trimmed);
+}
+function parsePositiveInteger(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Expected a positive integer, received ${value}.`);
+  }
+  return parsed;
+}
+function optionalTrim(value) {
+  const trimmed = value.trim();
+  return trimmed ? trimmed : void 0;
+}
+function promptLine(input, output, question) {
+  input.setRawMode?.(false);
+  return new Promise((resolve) => {
+    const prompt = readline.createInterface({ input, output });
+    prompt.question(question, (answer) => {
+      prompt.close();
+      input.setRawMode?.(true);
+      resolve(answer);
+    });
+  });
+}
+function teardownRunnerTui(input, output, keypressHandler) {
+  input.setRawMode?.(false);
+  input.off("keypress", keypressHandler);
+  output.write("\x1B[?25h\n");
+}
+
 // src/index.ts
 var program = new Command();
 var defaultRoot = process.env.INIT_CWD ?? process.cwd();
 var apiUrlOptionDescription = `Amistio API URL override (or ${AMISTIO_API_URL_ENV})`;
-program.name("amistio").description("Amistio project brain CLI").version("0.1.2");
-var CLI_VERSION = "0.1.2";
+program.name("amistio").description("Amistio project brain CLI").version("0.1.3");
+var CLI_VERSION = "0.1.3";
 program.command("init").description("Create Amistio control-plane folders for a new project").option("--root <path>", "Repository root", defaultRoot).action(async (options) => {
   const created = await initControlPlane(options.root);
   console.log(created.length ? `Created ${created.length} control-plane folders.` : "Control-plane folders already exist.");
@@ -2530,8 +3354,76 @@ program.command("bootstrap").description("Clone a linked repository locally, pre
   console.log(`Wrote non-secret project metadata to ${filePath}.`);
   console.log(`Next: cd ${formatShellArg(checkout.targetDir)} && amistio run${formatApiUrlFlag(options.apiUrl)} --watch`);
 });
+program.command("import").description("Pair an existing checkout and import legacy Markdown docs for review").argument("[code]", "Short-lived pairing code from the Amistio app").option("--pairing-code <code>", "Short-lived pairing code from the Amistio app").option("--root <path>", "Repository root", defaultRoot).option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--default-branch <branch>", "Default branch fallback", "main").option("--include <glob>", "Only import files matching a repo-relative glob", collectRepeatedOption, []).option("--exclude <glob>", "Exclude files matching a repo-relative glob", collectRepeatedOption, []).option("--max-file-kb <kb>", "Maximum Markdown file size to import", parsePositiveInteger2, 256).option("--dry-run", "Inspect and print import candidates without consuming the code or uploading documents").action(async (code, options) => {
+  const pairingCode = (options.pairingCode ?? code)?.trim();
+  if (!pairingCode) {
+    throw new Error("Provide a pairing code as `amistio import <code>` or with `--pairing-code <code>`.");
+  }
+  const repository = await inspectLocalRepository(options.root, options.defaultBranch);
+  const scan = await scanLegacyDocuments({
+    rootDir: repository.rootDir,
+    include: options.include,
+    exclude: options.exclude,
+    maxFileKb: options.maxFileKb
+  });
+  const skipCounts = importSkipCounts(scan.skipped);
+  console.log(`Repository: ${repository.repoName}`);
+  console.log(`Root: ${repository.rootDir}`);
+  console.log(`Default branch: ${repository.defaultBranch}`);
+  if (repository.originRemoteWarning) {
+    console.log(repository.originRemoteWarning);
+  }
+  console.log(`Import candidates: ${scan.candidates.length}`);
+  console.log(formatImportSkipSummary(skipCounts));
+  for (const candidate of scan.candidates.slice(0, 12)) {
+    console.log(`- ${candidate.sourcePath} -> ${candidate.repoPath} (${candidate.documentType})`);
+  }
+  if (scan.candidates.length > 12) {
+    console.log(`...and ${scan.candidates.length - 12} more.`);
+  }
+  if (options.dryRun) {
+    console.log("Dry run complete. No pairing code was consumed and no files or Amistio records were written.");
+    return;
+  }
+  const parsedCloneUrl = repository.parsedCloneUrl;
+  const pairing = await new ApiClient({ apiUrl: options.apiUrl }).importPairingSession({
+    pairingCode,
+    repoName: repository.repoName,
+    repoFingerprint: repository.repoFingerprint,
+    defaultBranch: repository.defaultBranch,
+    ...parsedCloneUrl ? { cloneUrl: parsedCloneUrl.cloneUrl } : {},
+    ...parsedCloneUrl?.provider ? { provider: parsedCloneUrl.provider } : {},
+    ...parsedCloneUrl?.repoOwner ? { repoOwner: parsedCloneUrl.repoOwner } : {},
+    ...parsedCloneUrl?.repoFullName ? { repoFullName: parsedCloneUrl.repoFullName } : {}
+  });
+  await initControlPlane(repository.rootDir);
+  const metadataFilePath = await writeProjectLink(repository.rootDir, {
+    amistioAccountId: pairing.accountId,
+    amistioProjectId: pairing.projectId,
+    repositoryLinkId: pairing.repositoryLink.repositoryLinkId,
+    defaultBranch: repository.defaultBranch,
+    lastSyncedRevision: 0
+  });
+  await new LocalCredentialStore().set(credentialKey(pairing.accountId, pairing.projectId, pairing.repositoryLink.repositoryLinkId), pairing.token);
+  const authenticatedClient = new ApiClient({ apiUrl: options.apiUrl, accountId: pairing.accountId, token: pairing.token });
+  const { documents: existingDocuments } = await authenticatedClient.listBrainDocuments(pairing.projectId);
+  const documents = buildImportedBrainDocuments({
+    accountId: pairing.accountId,
+    projectId: pairing.projectId,
+    repositoryLinkId: pairing.repositoryLink.repositoryLinkId,
+    candidates: scan.candidates,
+    existingDocuments
+  });
+  if (documents.length) {
+    await authenticatedClient.pushBrainDocuments(pairing.projectId, documents);
+  }
+  console.log(`Pairing confirmed for ${pairing.repositoryLink.repoName}; repository link ${pairing.repositoryLinkAction}.`);
+  console.log(`Wrote non-secret project metadata to ${metadataFilePath}.`);
+  console.log(`Imported ${documents.length} legacy document${documents.length === 1 ? "" : "s"} for review.`);
+  console.log(`Next: amistio sync status${formatApiUrlFlag(options.apiUrl)}`);
+});
 program.command("pair").description("Pair this repository with an Amistio web project").requiredOption("--account <accountId>", "Amistio account ID").requiredOption("--project <projectId>", "Amistio project ID").option("--repository-link <repositoryLinkId>", "Existing repository link ID").option("--default-branch <branch>", "Default branch", "main").option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--pairing-code <code>", "Short-lived pairing code from the Amistio app").option("--token <token>", "Runner/device credential to store outside the repository").option("--root <path>", "Repository root", defaultRoot).action(async (options, command) => {
-  let repositoryLinkId = options.repositoryLink ?? `repo_${randomUUID()}`;
+  let repositoryLinkId = options.repositoryLink ?? `repo_${randomUUID2()}`;
   let credential = options.token;
   if (options.pairingCode) {
     const pairing = await new ApiClient({
@@ -2691,7 +3583,7 @@ program.command("tools").description("List local AI coding tools that the Amisti
   }
   console.log("custom - pass --tool-command to use any other local runner command.");
 });
-program.command("orchestrate").description("Update the Amistio control plane through a user-installed local AI tool").argument("[goal...]", "Goal or next-step instruction for the orchestration pass").option("--root <path>", "Repository root", defaultRoot).option("--tool <name>", "Local tool to use: auto, none, opencode, claude, codex, copilot, gemini, aider, cursor-agent", "auto").option("--model <model>", "Model to request when the selected local tool supports model selection").option("--tool-command <command>", "Custom local command. Use {promptFile} and {root} placeholders when supported").option("--session <policy>", "Tool session policy: auto, new, continue:<toolSessionId>, or none", "auto").option("--prompt-out <path>", "Write the generated orchestration prompt to a file before running").option("--dry-run", "Print the generated orchestration prompt without running a tool").option("--no-stream", "Capture local tool output instead of streaming it").action(async (goalParts, options) => {
+program.command("orchestrate").description("Update the Amistio control plane through a user-installed local AI tool").argument("[goal...]", "Goal or next-step instruction for the orchestration pass").option("--root <path>", "Repository root", defaultRoot).option("--tool <name>", "Local tool to use: auto, none, opencode, claude, codex, copilot, gemini, aider, cursor-agent", "auto").option("--invocation-channel <channel>", "Local invocation channel: auto, sdk, or command", parseInvocationChannel, "auto").option("--model <model>", "Model to request when the selected local tool supports model selection").option("--tool-command <command>", "Custom local command. Use {promptFile} and {root} placeholders when supported").option("--session <policy>", "Tool session policy: auto, new, continue:<toolSessionId>, or none", "auto").option("--prompt-out <path>", "Write the generated orchestration prompt to a file before running").option("--dry-run", "Print the generated orchestration prompt without running a tool").option("--no-stream", "Capture local tool output instead of streaming it").action(async (goalParts, options) => {
   const goal = goalParts?.join(" ").trim() || "Review the current repository state and update the Amistio control plane with the next useful orchestration steps.";
   const prompt = await createOrchestrationPrompt({ rootDir: options.root, goal });
   if (options.promptOut) {
@@ -2703,16 +3595,17 @@ program.command("orchestrate").description("Update the Amistio control plane thr
     return;
   }
   const sessionPolicy = normalizeSessionPolicy(options.session);
-  const preview = await createToolRunPreview({ rootDir: options.root, prompt, tool: options.tool, ...options.toolCommand ? { toolCommand: options.toolCommand } : {}, ...options.model ? { model: options.model } : {} });
+  const preview = await createToolRunPreview({ rootDir: options.root, prompt, tool: options.tool, invocationChannel: options.invocationChannel, ...options.toolCommand ? { toolCommand: options.toolCommand } : {}, ...options.model ? { model: options.model } : {} });
   console.log(`Running ${preview.toolName}: ${preview.displayCommand}`);
   const result = await runLocalTool({
     rootDir: options.root,
     prompt,
     tool: options.tool,
+    invocationChannel: options.invocationChannel,
     ...options.toolCommand ? { toolCommand: options.toolCommand } : {},
     ...options.model ? { model: options.model } : {},
     streamOutput: options.stream,
-    ...sessionPolicy === "none" ? {} : { session: { toolSessionId: `local_orchestration_${randomUUID()}`, policy: sessionPolicy, decision: localSessionDecision(sessionPolicy) } }
+    ...sessionPolicy === "none" ? {} : { session: { toolSessionId: `local_orchestration_${randomUUID2()}`, policy: sessionPolicy, decision: localSessionDecision(sessionPolicy) } }
   });
   if (!options.stream && result.stdout.trim()) {
     console.log(result.stdout.trim());
@@ -2724,7 +3617,7 @@ program.command("orchestrate").description("Update the Amistio control plane thr
     process.exitCode = result.exitCode;
   }
 });
-program.command("run").description("Claim and run approved Amistio work locally").option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--runner-id <runnerId>", "Stable runner ID", `runner_${randomUUID()}`).option("--root <path>", "Repository root", defaultRoot).option("--tool <name>", "Local tool to use: auto, none, opencode, claude, codex, copilot, gemini, aider, cursor-agent").option("--model <model>", "Model to request when the selected local tool supports model selection").option("--tool-command <command>", "Custom local command. Use {promptFile} and {root} placeholders when supported").option("--session <policy>", "Tool session policy: auto, new, continue:<toolSessionId>, or none", "auto").option("--dry-run", "Claim work and print the generated execution prompt without running a tool").option("--watch", "Keep polling for approved work until stopped").option("--background", "Start a detached background runner that watches for approved work").option("--interval-seconds <seconds>", "Polling interval for --watch", parsePositiveInteger, 10).option("--max-iterations <count>", "Stop watch mode after this many polling attempts", parsePositiveInteger).option("--no-stream", "Capture local tool output instead of streaming it").action(async (options, command) => {
+program.command("run").description("Claim and run approved Amistio work locally").option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--runner-id <runnerId>", "Stable runner ID", `runner_${randomUUID2()}`).option("--root <path>", "Repository root", defaultRoot).option("--tool <name>", "Local tool to use: auto, none, opencode, claude, codex, copilot, gemini, aider, cursor-agent").option("--invocation-channel <channel>", "Local invocation channel: auto, sdk, or command", parseInvocationChannel).option("--model <model>", "Model to request when the selected local tool supports model selection").option("--tool-command <command>", "Custom local command. Use {promptFile} and {root} placeholders when supported").option("--session <policy>", "Tool session policy: auto, new, continue:<toolSessionId>, or none", "auto").option("--dry-run", "Claim work and print the generated execution prompt without running a tool").option("--watch", "Keep polling for approved work until stopped").option("--background", "Start a detached background runner that watches for approved work").option("--interval-seconds <seconds>", "Polling interval for --watch", parsePositiveInteger2, 10).option("--max-iterations <count>", "Stop watch mode after this many polling attempts", parsePositiveInteger2).option("--no-stream", "Capture local tool output instead of streaming it").action(async (options, command) => {
   const context = await loadPairedApiContext(options.root, options.apiUrl);
   if (!context) {
     console.log("Repository is not paired. Run `amistio pair` first.");
@@ -2746,7 +3639,7 @@ program.command("run").description("Claim and run approved Amistio work locally"
       projectId: context.metadata.amistioProjectId,
       repositoryLinkId: context.metadata.repositoryLinkId,
       runnerId: options.runnerId,
-      rootDir: path9.resolve(options.root),
+      rootDir: path12.resolve(options.root),
       apiUrl: options.apiUrl,
       args: buildBackgroundRunnerArgs(options)
     });
@@ -2773,6 +3666,7 @@ program.command("run").description("Claim and run approved Amistio work locally"
       root: options.root,
       sessionPolicy: normalizeSessionPolicy(options.session),
       ...command.getOptionValueSource("tool") === "cli" && options.tool ? { explicitTool: options.tool } : {},
+      ...command.getOptionValueSource("invocationChannel") === "cli" && options.invocationChannel ? { explicitInvocationChannel: options.invocationChannel } : {},
       ...command.getOptionValueSource("model") === "cli" && options.model ? { explicitModel: options.model } : {},
       ...options.toolCommand ? { toolCommand: options.toolCommand } : {},
       dryRun: Boolean(options.dryRun),
@@ -2812,6 +3706,9 @@ program.command("run").description("Claim and run approved Amistio work locally"
   }
 });
 var runner = program.command("runner").description("Manage local Amistio runner processes");
+runner.command("ui").alias("tui").description("Open an interactive terminal UI for local runner management").option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--root <path>", "Repository root", defaultRoot).option("--runner-id <runnerId>", "Select or prefill a runner ID").option("--interval-seconds <seconds>", "Default polling interval for started background runners", parsePositiveInteger2, 10).option("--no-remote", "Skip remote API calls and show local runner state only").action(async (options) => {
+  await runRunnerTui(options);
+});
 runner.command("status").description("Show background runner status for the paired repository").option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--root <path>", "Repository root", defaultRoot).option("--runner-id <runnerId>", "Limit status to one runner ID").action(async (options) => {
   const context = await loadPairedApiContext(options.root, options.apiUrl);
   if (!context) {
@@ -2892,6 +3789,7 @@ async function runNextWorkItem({
   sessionPolicy,
   stream,
   explicitModel,
+  explicitInvocationChannel,
   explicitTool,
   toolCommand,
   commandContext,
@@ -2900,6 +3798,7 @@ async function runNextWorkItem({
   const toolConfig = await resolveRunnerToolConfig({
     apiClient,
     projectId,
+    ...explicitInvocationChannel ? { explicitInvocationChannel } : {},
     ...explicitModel ? { explicitModel } : {},
     ...explicitTool ? { explicitTool } : {},
     ...toolCommand ? { toolCommand } : {}
@@ -2932,7 +3831,7 @@ async function runNextWorkItem({
     await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "online", runnerHeartbeatMetadata(toolConfig));
     return { status: "preview", exitCode: 0 };
   }
-  const preview = await createToolRunPreview({ rootDir: root, prompt, tool: toolConfig.tool, ...toolCommand ? { toolCommand } : {}, ...toolConfig.model ? { model: toolConfig.model } : {} });
+  const preview = await createToolRunPreview({ rootDir: root, prompt, tool: toolConfig.tool, invocationChannel: toolConfig.requestedInvocationChannel ?? "auto", ...toolCommand ? { toolCommand } : {}, ...toolConfig.model ? { model: toolConfig.model } : {} });
   const sessionContext = await prepareToolSession({
     apiClient,
     projectId,
@@ -2953,6 +3852,7 @@ async function runNextWorkItem({
     rootDir: root,
     prompt,
     tool: toolConfig.tool,
+    invocationChannel: toolConfig.requestedInvocationChannel ?? "auto",
     ...toolCommand ? { toolCommand } : {},
     ...toolConfig.model ? { model: toolConfig.model } : {},
     streamOutput: stream,
@@ -3012,7 +3912,7 @@ async function runNextWorkItem({
     projectId,
     result.workItem.workItemId,
     finalStatus,
-    `run_${result.workItem.workItemId}_${randomUUID()}`,
+    `run_${result.workItem.workItemId}_${randomUUID2()}`,
     runnerId,
     {
       tool: preview.toolName,
@@ -3058,7 +3958,7 @@ async function updateRunnerCommandStatus(apiClient, context, command, status, me
     runnerId: context.runnerId,
     repositoryLinkId: context.repositoryLinkId,
     status,
-    idempotencyKey: `runner_command_${command.commandId}_${status}_${randomUUID()}`,
+    idempotencyKey: `runner_command_${command.commandId}_${status}_${randomUUID2()}`,
     message,
     ...error ? { error } : {}
   });
@@ -3088,37 +3988,6 @@ async function restartCurrentRunner(context) {
     return { succeeded: false, message: "Background restart failed.", error: errorMessage2(error) };
   }
 }
-async function runOfficialCliUpdate() {
-  const result = await runOfficialUpdateProcess("npm", ["install", "-g", "@amistio/cli"], 12e4);
-  if (result.exitCode === 0) {
-    return { succeeded: true, message: "Official Amistio CLI update command completed." };
-  }
-  return { succeeded: false, message: "Official Amistio CLI update command failed.", error: result.output || `npm exited with code ${result.exitCode}.` };
-}
-function runOfficialUpdateProcess(command, args, timeoutMs) {
-  return new Promise((resolve) => {
-    const child = spawn3(command, args, { stdio: ["ignore", "pipe", "pipe"] });
-    let output = "";
-    const timer = setTimeout(() => {
-      output += "Timed out while running official CLI update.\n";
-      child.kill("SIGTERM");
-    }, timeoutMs);
-    child.stdout?.on("data", (chunk) => {
-      output += chunk.toString("utf8");
-    });
-    child.stderr?.on("data", (chunk) => {
-      output += chunk.toString("utf8");
-    });
-    child.on("error", (error) => {
-      clearTimeout(timer);
-      resolve({ exitCode: 1, output: error.message });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      resolve({ exitCode: code ?? 1, output: truncateLogExcerpt(output) });
-    });
-  });
-}
 function runnerCommandLabel(commandKind) {
   if (commandKind === "update") return "update";
   if (commandKind === "restart") return "restart";
@@ -3174,7 +4043,7 @@ ${toolResult.stderr}`);
     const result = await apiClient.submitBrainGenerationResult(projectId, workItem.workItemId, {
       status: "completed",
       runnerId,
-      idempotencyKey: `generation_${workItem.workItemId}_${randomUUID()}`,
+      idempotencyKey: `generation_${workItem.workItemId}_${randomUUID2()}`,
       artifacts,
       tool: toolName,
       durationMs,
@@ -3188,7 +4057,7 @@ ${toolResult.stderr}`);
   await apiClient.submitBrainGenerationResult(projectId, workItem.workItemId, {
     status: "failed",
     runnerId,
-    idempotencyKey: `generation_${workItem.workItemId}_${randomUUID()}`,
+    idempotencyKey: `generation_${workItem.workItemId}_${randomUUID2()}`,
     tool: toolName,
     durationMs,
     ...sessionTelemetry,
@@ -3304,7 +4173,7 @@ async function prepareToolSession({
     });
     return { ...selection, toolSession: toolSession2 };
   }
-  const toolSessionId = `tool_session_${randomUUID()}`;
+  const toolSessionId = `tool_session_${randomUUID2()}`;
   const { toolSession } = await apiClient.createToolSession(projectId, {
     toolSessionId,
     repositoryLinkId,
@@ -3386,18 +4255,30 @@ function truncateLogExcerpt(value) {
   const trimmed = value.trim();
   return trimmed.length > 1200 ? `${trimmed.slice(0, 1200)}...` : trimmed;
 }
-function parsePositiveInteger(value) {
+function collectRepeatedOption(value, previous) {
+  return [...previous, value];
+}
+function formatImportSkipSummary(counts) {
+  return `Skipped: ${counts.excluded} excluded, ${counts.tooLarge} too large, ${counts.alreadyManaged} already managed, ${counts.unreadable} unreadable, ${counts.notMarkdown} non-Markdown.`;
+}
+function parsePositiveInteger2(value) {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed <= 0) {
     throw new Error(`Expected a positive integer, received ${value}.`);
   }
   return parsed;
 }
+function parseInvocationChannel(value) {
+  if (value === "auto" || value === "sdk" || value === "command") {
+    return value;
+  }
+  throw new Error(`Expected invocation channel auto, sdk, or command; received ${value}.`);
+}
 function inferRepoName(root) {
-  return path9.basename(path9.resolve(root)) || "repository";
+  return path12.basename(path12.resolve(root)) || "repository";
 }
 function createRepoFingerprint(accountId, projectId, repositoryLinkId) {
-  return createHash3("sha256").update(`${accountId}:${projectId}:${repositoryLinkId}`).digest("hex");
+  return createHash4("sha256").update(`${accountId}:${projectId}:${repositoryLinkId}`).digest("hex");
 }
 function defaultApiUrl() {
   const envApiUrl = process.env[AMISTIO_API_URL_ENV]?.trim();
@@ -3412,7 +4293,7 @@ function formatApiUrlFlag(apiUrl) {
 function formatShellArg(value) {
   return /^[A-Za-z0-9_./:@-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
 }
-async function resolveRunnerToolConfig({ apiClient, explicitModel, explicitTool, projectId, toolCommand }) {
+async function resolveRunnerToolConfig({ apiClient, explicitInvocationChannel, explicitModel, explicitTool, projectId, toolCommand }) {
   const capabilities = toRunnerToolCapabilities(await detectLocalTools());
   if (toolCommand) {
     return {
@@ -3422,6 +4303,8 @@ async function resolveRunnerToolConfig({ apiClient, explicitModel, explicitTool,
       source: "cli",
       status: "custom",
       effectiveTool: "custom",
+      requestedInvocationChannel: explicitInvocationChannel ?? "command",
+      effectiveInvocationChannel: "command",
       ...explicitTool && explicitTool !== "none" && explicitTool !== "auto" && isLocalToolName(explicitTool) ? { requestedTool: explicitTool } : explicitTool === "auto" ? { requestedTool: "auto" } : {},
       ...explicitModel ? { model: explicitModel } : {},
       message: "Using local custom tool command."
@@ -3429,43 +4312,51 @@ async function resolveRunnerToolConfig({ apiClient, explicitModel, explicitTool,
   }
   if (explicitTool === "none") {
     if (explicitModel) {
-      return unavailableToolConfig({ capabilities, source: "cli", status: "modelUnsupported", message: "--model cannot be used with --tool none.", tool: "none", model: explicitModel });
+      return unavailableToolConfig({ capabilities, source: "cli", status: "modelUnsupported", message: "--model cannot be used with --tool none.", tool: "none", requestedInvocationChannel: explicitInvocationChannel ?? "auto", model: explicitModel });
     }
-    return { ready: true, tool: "none", capabilities, source: "cli", status: "none", message: "No local tool selected." };
+    return { ready: true, tool: "none", capabilities, source: "cli", status: "none", requestedInvocationChannel: explicitInvocationChannel ?? "auto", message: "No local tool selected." };
   }
   if (explicitTool && explicitTool !== "auto" && !isLocalToolName(explicitTool)) {
-    return unavailableToolConfig({ capabilities, source: "cli", status: "unavailable", message: `Unsupported local tool: ${explicitTool}.`, tool: explicitTool, ...explicitModel ? { model: explicitModel } : {} });
+    return unavailableToolConfig({ capabilities, source: "cli", status: "unavailable", message: `Unsupported local tool: ${explicitTool}.`, tool: explicitTool, requestedInvocationChannel: explicitInvocationChannel ?? "auto", ...explicitModel ? { model: explicitModel } : {} });
   }
-  const remotePreference = explicitTool || explicitModel ? void 0 : await apiClient.getRunnerPreferences(projectId).then((response) => response.effective).catch(() => void 0);
+  const remotePreference = await apiClient.getRunnerPreferences(projectId).then((response) => response.effective).catch(() => void 0);
   const requestedTool = explicitTool ?? remotePreference?.tool ?? "auto";
+  const requestedInvocationChannel = explicitInvocationChannel ?? remotePreference?.invocationChannel ?? "auto";
   const model = explicitModel ?? remotePreference?.model;
-  const source = explicitTool || explicitModel ? "cli" : remotePreference?.source ?? "default";
-  return resolveRequestedTool({ capabilities, requestedTool, source, ...model ? { model } : {} });
+  const source = explicitTool || explicitInvocationChannel || explicitModel ? "cli" : remotePreference?.source ?? "default";
+  return resolveRequestedTool({ capabilities, requestedInvocationChannel, requestedTool, source, ...model ? { model } : {} });
 }
-function resolveRequestedTool({ capabilities, model, requestedTool, source }) {
+function resolveRequestedTool({ capabilities, model, requestedInvocationChannel, requestedTool, source }) {
   if (requestedTool === "auto") {
-    const candidate = capabilities.find((capability2) => capability2.available && (!model || capability2.supportsModelSelection));
+    const candidate = capabilities.find((capability2) => capability2.available && capabilitySupportsInvocationChannel(capability2, requestedInvocationChannel) && (!model || capability2.supportsModelSelection));
     if (!candidate) {
+      const anyAvailable = capabilities.some((capability2) => capability2.available);
+      const anyChannelAvailable = capabilities.some((capability2) => capability2.available && capabilitySupportsInvocationChannel(capability2, requestedInvocationChannel));
+      const status = !anyAvailable ? "unavailable" : requestedInvocationChannel !== "auto" && !anyChannelAvailable ? "channelUnsupported" : model ? "modelUnsupported" : "unavailable";
       return unavailableToolConfig({
         capabilities,
         source,
-        status: model ? "modelUnsupported" : "unavailable",
+        status,
         requestedTool,
+        requestedInvocationChannel,
         tool: "auto",
         ...model ? { model } : {},
-        message: model ? "No installed local tool can honor the selected model." : "No supported local AI tool is installed."
+        message: status === "channelUnsupported" ? `No installed local AI tool can honor ${requestedInvocationChannel} invocation.` : model ? "No installed local tool can honor the selected model." : "No supported local AI tool is installed."
       });
     }
-    return { ready: true, tool: "auto", capabilities, source, status: "resolved", requestedTool, effectiveTool: candidate.name, ...model ? { model } : {} };
+    return { ready: true, tool: "auto", capabilities, source, status: "resolved", requestedTool, requestedInvocationChannel, effectiveTool: candidate.name, effectiveInvocationChannel: effectiveInvocationChannel(candidate, requestedInvocationChannel), ...model ? { model } : {} };
   }
   const capability = capabilities.find((candidate) => candidate.name === requestedTool);
   if (!capability?.available) {
-    return unavailableToolConfig({ capabilities, source, status: "unavailable", requestedTool, tool: requestedTool, ...model ? { model } : {}, message: `${requestedTool} is selected but is not available on this runner.` });
+    return unavailableToolConfig({ capabilities, source, status: "unavailable", requestedTool, requestedInvocationChannel, tool: requestedTool, ...model ? { model } : {}, message: `${requestedTool} is selected but is not available on this runner.` });
+  }
+  if (!capabilitySupportsInvocationChannel(capability, requestedInvocationChannel)) {
+    return unavailableToolConfig({ capabilities, source, status: "channelUnsupported", requestedTool, requestedInvocationChannel, effectiveTool: requestedTool, tool: requestedTool, ...model ? { model } : {}, message: `${requestedTool} is available but does not support ${requestedInvocationChannel} invocation on this runner.` });
   }
   if (model && !capability.supportsModelSelection) {
-    return unavailableToolConfig({ capabilities, source, status: "modelUnsupported", requestedTool, effectiveTool: requestedTool, tool: requestedTool, model, message: `${requestedTool} is available but does not support Amistio model selection yet.` });
+    return unavailableToolConfig({ capabilities, source, status: "modelUnsupported", requestedTool, requestedInvocationChannel, effectiveTool: requestedTool, effectiveInvocationChannel: effectiveInvocationChannel(capability, requestedInvocationChannel), tool: requestedTool, model, message: `${requestedTool} is available but does not support Amistio model selection yet.` });
   }
-  return { ready: true, tool: requestedTool, capabilities, source, status: "resolved", requestedTool, effectiveTool: requestedTool, ...model ? { model } : {} };
+  return { ready: true, tool: requestedTool, capabilities, source, status: "resolved", requestedTool, requestedInvocationChannel, effectiveTool: requestedTool, effectiveInvocationChannel: effectiveInvocationChannel(capability, requestedInvocationChannel), ...model ? { model } : {} };
 }
 function unavailableToolConfig(input) {
   return {
@@ -3476,10 +4367,21 @@ function unavailableToolConfig(input) {
     status: input.status,
     message: input.message,
     ...input.requestedTool ? { requestedTool: input.requestedTool } : {},
+    ...input.requestedInvocationChannel ? { requestedInvocationChannel: input.requestedInvocationChannel } : {},
     ...input.effectiveTool ? { effectiveTool: input.effectiveTool } : {},
+    ...input.effectiveInvocationChannel ? { effectiveInvocationChannel: input.effectiveInvocationChannel } : {},
     ...input.model ? { model: input.model } : {}
   };
 }
+function capabilitySupportsInvocationChannel(capability, channel) {
+  if (channel === "auto") return capability.available;
+  if (channel === "sdk") return capability.sdkAvailable;
+  return capability.commandAvailable;
+}
+function effectiveInvocationChannel(capability, channel) {
+  if (channel === "sdk" || channel === "command") return channel;
+  return capability.sdkAvailable ? "sdk" : "command";
+}
 function toRunnerToolCapabilities(tools) {
   return tools.map((tool) => ({
     name: tool.name,
@@ -3493,46 +4395,16 @@ function toRunnerToolCapabilities(tools) {
     supportsModelSelection: tool.supportsModelSelection
   }));
 }
-function buildBackgroundRunnerArgs(options) {
-  const args = [
-    "run",
-    "--watch",
-    "--api-url",
-    options.apiUrl,
-    "--runner-id",
-    options.runnerId,
-    "--root",
-    path9.resolve(options.root),
-    "--session",
-    options.session,
-    "--interval-seconds",
-    String(options.intervalSeconds)
-  ];
-  if (options.tool) {
-    args.push("--tool", options.tool);
-  }
-  if (options.toolCommand) {
-    args.push("--tool-command", options.toolCommand);
-  }
-  if (options.model) {
-    args.push("--model", options.model);
-  }
-  if (options.maxIterations !== void 0) {
-    args.push("--max-iterations", String(options.maxIterations));
-  }
-  if (!options.stream) {
-    args.push("--no-stream");
-  }
-  return args;
-}
 function runnerHeartbeatMetadata(toolConfig, mode = currentRunnerMode()) {
   return {
     version: CLI_VERSION,
     mode,
-    hostname: os5.hostname(),
+    hostname: os6.hostname(),
     ...toolConfig?.capabilities ? { capabilities: toolConfig.capabilities } : {},
     ...toolConfig?.requestedTool ? { requestedTool: toolConfig.requestedTool } : {},
+    ...toolConfig?.requestedInvocationChannel ? { requestedInvocationChannel: toolConfig.requestedInvocationChannel } : {},
     ...toolConfig?.effectiveTool ? { effectiveTool: toolConfig.effectiveTool } : {},
+    ...toolConfig?.effectiveInvocationChannel ? { effectiveInvocationChannel: toolConfig.effectiveInvocationChannel } : {},
     ...toolConfig?.model ? { effectiveModel: toolConfig.model } : {},
     ...toolConfig?.source ? { preferenceSource: toolConfig.source } : {},
     ...toolConfig?.status ? { preferenceStatus: toolConfig.status } : {},