@amistio/cli 0.1.2 → 0.1.4

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 } from "node:crypto";
 import { writeFile as writeFile8 } from "node:fs/promises";
 import os5 from "node:os";
-import path9 from "node:path";
+import path11 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 path12 = urlPath.startsWith("/") ? urlPath : `/${urlPath}`;
+  return new URL(`${base}${path12}`);
 }
 
 // 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,354 @@ 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/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.4");
+var CLI_VERSION = "0.1.4";
 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,6 +2926,74 @@ 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", parsePositiveInteger, 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 credential = options.token;
@@ -2691,7 +3155,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,12 +3167,13 @@ 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,
@@ -2724,7 +3189,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_${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("--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", 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) => {
   const context = await loadPairedApiContext(options.root, options.apiUrl);
   if (!context) {
     console.log("Repository is not paired. Run `amistio pair` first.");
@@ -2746,7 +3211,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: path11.resolve(options.root),
       apiUrl: options.apiUrl,
       args: buildBackgroundRunnerArgs(options)
     });
@@ -2773,6 +3238,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),
@@ -2892,6 +3358,7 @@ async function runNextWorkItem({
   sessionPolicy,
   stream,
   explicitModel,
+  explicitInvocationChannel,
   explicitTool,
   toolCommand,
   commandContext,
@@ -2900,6 +3367,7 @@ async function runNextWorkItem({
   const toolConfig = await resolveRunnerToolConfig({
     apiClient,
     projectId,
+    ...explicitInvocationChannel ? { explicitInvocationChannel } : {},
     ...explicitModel ? { explicitModel } : {},
     ...explicitTool ? { explicitTool } : {},
     ...toolCommand ? { toolCommand } : {}
@@ -2932,7 +3400,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 +3421,7 @@ async function runNextWorkItem({
     rootDir: root,
     prompt,
     tool: toolConfig.tool,
+    invocationChannel: toolConfig.requestedInvocationChannel ?? "auto",
     ...toolCommand ? { toolCommand } : {},
     ...toolConfig.model ? { model: toolConfig.model } : {},
     streamOutput: stream,
@@ -3088,37 +3557,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";
@@ -3386,6 +3824,12 @@ function truncateLogExcerpt(value) {
   const trimmed = value.trim();
   return trimmed.length > 1200 ? `${trimmed.slice(0, 1200)}...` : trimmed;
 }
+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 parsePositiveInteger(value) {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed <= 0) {
@@ -3393,11 +3837,17 @@ function parsePositiveInteger(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 path11.basename(path11.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 +3862,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 +3872,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 +3881,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 +3936,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,38 +3964,6 @@ 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,
@@ -3532,7 +3971,9 @@ function runnerHeartbeatMetadata(toolConfig, mode = currentRunnerMode()) {
     hostname: os5.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 } : {},