@dharta/cli 0.6.77

package/src/commands/setup.ts

@@ -0,0 +1,1176 @@
+import { constants, existsSync, promises as fs, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import * as path from "node:path";
+import { findGitRoot, scanAgentFolders, renderTable, describeFolder, type AgentFolder } from "../setup-scan.js";
+import { renderManifest, patchManifest, type DeployMethod } from "../manifest.js";
+import { deriveSlug, validateAgentName } from "../agent.js";
+import { defaultGitRunner, rejectOverlappingAgentRoots, type GitRunner } from "./deploy.js";
+import { closestChoice, normalizeNonBlank } from "../validators.js";
+import { DEFAULT_CREATE_HARNESS, hasAgentMarker } from "../harnesses.js";
+
+// `dharta setup [path]` (RFC 0024 DEP-4): the one front door. It scans the
+// repo for agent folders, lets you pick one, and writes its (self-
+// documenting) dharta.toml - name, deploy gate, deployment transport.
+//
+// Destination-agnostic by construction: setup writes LOCAL config only and
+// never contacts a Dharta environment. The selected transport is persisted on
+// the agent itself as deploy_method, so the same folder behaves consistently
+// from a laptop or git push. GitHub Actions is separate automation, not a
+// third transport; its generated least-privilege workflow pins the transport
+// selected when setup renders it.
+
+export type Method = DeployMethod;
+export type CiProvider = "github";
+
+export interface SetupOptions {
+  cwd?: string;
+  name?: string;
+  enable?: boolean;
+  disable?: boolean;
+  method?: string;
+  ci?: string;
+  yes?: boolean;
+  // seams (tests / cli wiring)
+  ask?: (question: string) => Promise<string>;
+  gitRunner?: GitRunner;
+  log?: (line: string) => void;
+}
+
+export interface SetupResult {
+  folder: string; // configured folder, relative to the scan root
+  name: string;
+  deploy: boolean;
+  method: Method;
+  ci?: CiProvider;
+  manifestPath: string; // absolute
+  scaffolded: boolean; // true when dharta.toml was newly created (vs patched)
+  workflowScaffolded: boolean; // true when --ci github wrote this agent's workflow
+  gitInitialized: boolean;
+}
+
+const METHODS: Method[] = ["git", "folder"];
+const METHOD_INPUTS = [...METHODS, "github"] as const;
+const CI_PROVIDERS: CiProvider[] = ["github"];
+const MANAGED_WORKFLOW_MARKER = "# Dharta managed workflow. Generated by dharta setup (format v1).";
+const CLI_VERSION = (
+  JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version: string }
+).version;
+
+export async function setup(pathArg: string | undefined, opts: SetupOptions = {}): Promise<SetupResult> {
+  const cwd = path.resolve(opts.cwd ?? ".");
+  const git = opts.gitRunner ?? defaultGitRunner;
+  const log = opts.log ?? ((line: string) => console.error(line));
+  const ask = opts.yes ? undefined : opts.ask;
+  const pathInput = pathArg === undefined ? undefined : normalizeNonBlank(pathArg, "path");
+  const parsedMethod = parseMethod(opts.method); // validate configuration up front
+  const forcedMethod = parsedMethod.method;
+  const ci = parseCi(opts.ci) ?? parsedMethod.ci;
+  if (opts.enable && opts.disable) throw new Error("Use either --enable or --disable, not both.");
+  if (opts.name !== undefined) validateAgentName(opts.name, "--name");
+  // Resolve and validate an explicit target before setup can initialize git or
+  // write anything. Besides avoiding a stray .git on typos, this establishes a
+  // lexical + realpath boundary that a symlink cannot redirect later writes
+  // through.
+  let gitRoot = findGitRoot(cwd);
+  await validateExplicitSetupPath(cwd, pathInput, gitRoot ?? cwd);
+  if (parsedMethod.legacyGithub) {
+    log(
+      "Compatibility: --method github now means --method folder plus --ci github. " +
+        "Prefer the two explicit options in scripts.",
+    );
+  }
+
+  // --- 1. git context (needed by git transport and GitHub automation) -----
+  const containingPlainAgent = !gitRoot && !pathInput ? nearestAgentMarkerDir(cwd) : undefined;
+  const localSetupRoot = containingPlainAgent ?? cwd;
+  let gitInitialized = false;
+  const existingMethod = !gitRoot && !forcedMethod
+    ? await inferExistingMethodWithoutGit(localSetupRoot, pathInput)
+    : undefined;
+  const needsGit = ci === "github" || (forcedMethod ?? existingMethod) !== "folder";
+  if (!gitRoot && needsGit) {
+    const rel = relLabel(localSetupRoot);
+    const create = ask
+      ? yesNoCancel(await ask(`No git here. Create git in ${rel} ? [Yes] / [no] / [cancel]  `))
+      : "yes"; // non-interactive default takes the [Yes] (or pass --method folder)
+    if (create === "cancel") throw new Error("setup canceled.");
+    if (create === "no" && ci === "github") {
+      throw new Error("--ci github requires a git repo. Initialize git, then run setup again.");
+    }
+    if (create === "yes") {
+      await run(git, ["-C", localSetupRoot, "init", "-b", "main"], "git init");
+      gitRoot = localSetupRoot;
+      gitInitialized = true;
+      log(`Initialized a git repo in ${rel}.`);
+    }
+  }
+  const scanRoot = gitRoot ?? containingPlainAgent ?? cwd;
+  const hasGit = !!gitRoot;
+
+  // --- 2. scan for agent folders -----------------------------------------
+  const folders = await scanAgentFolders(scanRoot, { isGitRepo: hasGit });
+  const shared: Shared = { cwd, git, hasGit, scanRoot, gitInitialized, forcedMethod, ci, ask, log };
+
+  // The nearest containing agent always wins, even if it is deep or ignored
+  // and therefore absent from the repo-wide discovery list. Setup from inside
+  // an agent must never fall through to a sibling selection.
+  if (!pathInput) {
+    const containingDir = nearestAgentMarkerDir(cwd, gitRoot ?? undefined);
+    if (containingDir) {
+      const target = folders.find((folder) => folder.dir === containingDir) ??
+        await describeFolder(containingDir, path.relative(scanRoot, containingDir));
+      requireAgent(target, pathInput);
+      return configureAgent(target, shared, opts);
+    }
+  }
+
+  // --- 3. interactive + several agents: select exactly one ----------------
+  // Setup is agent-scoped, just like deploy. Standing inside an agent selects
+  // it immediately. At an ambiguous repo root, show one menu and configure the
+  // single choice; configuring siblings requires explicit repeat invocations.
+  if (ask && !pathInput && folders.length >= 2) {
+    const target = await pickOneAgent(folders, shared);
+    if (!target) return snapshotResult(folders[0], shared);
+    return configureAgent(target, shared, opts);
+  }
+
+  // --- single agent / explicit path / non-interactive --------------------
+  if (ask && folders.length > 0) {
+    log("");
+    log(renderTable(folders));
+    log("");
+  }
+  const target = await pickFolder(pathInput, folders, scanRoot, cwd, ask);
+  requireAgent(target, pathInput);
+  return configureAgent(target, shared, opts);
+}
+
+function nearestAgentMarkerDir(start: string, boundary?: string): string | undefined {
+  let dir = path.resolve(start);
+  const stop = boundary === undefined ? undefined : path.resolve(boundary);
+  for (;;) {
+    if (hasAgentMarker(dir)) return dir;
+    if (stop && dir === stop) return undefined;
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+// Everything one setup invocation shares across the agent(s) it configures: the
+// git context (resolved once) and the IO seams.
+interface Shared {
+  cwd: string;
+  git: GitRunner;
+  hasGit: boolean;
+  scanRoot: string;
+  gitInitialized: boolean;
+  forcedMethod?: Method; // --method, if passed
+  ci?: CiProvider; // --ci, if passed
+  ask?: (question: string) => Promise<string>;
+  log: (line: string) => void;
+}
+
+// setup configures an EXISTING agent; scaffolding a brand-new folder is
+// `dharta create`'s job (RFC 0024). A folder with no harness or karta marker
+// has no agent to configure - send them to create.
+function requireAgent(target: AgentFolder, pathArg: string | undefined): void {
+  if (hasAgentMarker(target.dir)) return;
+  const here = target.rel === "." ? "this folder" : target.rel;
+  throw new Error(
+    `No agent to configure in ${here}. Create one first with \`dharta create${pathArg ? ` ${pathArg}` : ""}\`.`,
+  );
+}
+
+// Configure ONE agent: name, deploy gate, delivery method, then write the
+// self-documenting dharta.toml and apply the method action.
+async function configureAgent(target: AgentFolder, s: Shared, opts: SetupOptions): Promise<SetupResult> {
+  const { cwd, hasGit, scanRoot, gitInitialized, ask, log } = s;
+
+  // Discovery is read-only and may encounter paths supplied by the working
+  // tree. Re-establish the selected agent boundary before prompts or writes so
+  // an explicit or discovered symlink can never become a write target.
+  await validateSelectedAgentRoot(scanRoot, target.dir, target.rel);
+
+  const defaultName = target.name ?? deriveSlug(path.basename(target.dir));
+  const name = validateAgentName(opts.name === undefined
+    ? ((ask ? (await ask(`Agent name [${defaultName}]:  `)).trim() : "") || defaultName)
+    : opts.name, "agent name");
+
+  // Default to the EXISTING gate so re-running setup on an enabled agent does
+  // not silently disable it; a brand-new agent has deployEnabled = false, so
+  // D6's fail-safe default still holds.
+  let deploy: boolean;
+  if (opts.enable) deploy = true;
+  else if (opts.disable) deploy = false;
+  else if (ask) {
+    const defaultDeploy = target.configured ? target.deployEnabled : false;
+    const hint = defaultDeploy ? "Y/n" : "y/N";
+    deploy = yesNo(await ask(`Enable deploy for this agent? [${hint}]  `), defaultDeploy);
+  }
+  else deploy = target.deployEnabled;
+
+  // An explicit option changes the transport; otherwise preserve the method
+  // already configured for this agent. Only an unconfigured agent falls back
+  // to the repo-shaped default / interactive choice.
+  let method = s.forcedMethod ?? target.deployMethod;
+  if (!method) method = ask ? await askMethod(ask, hasGit) : hasGit ? "git" : "folder";
+  if (!hasGit) method = "folder"; // folder is forced without a git repo
+
+  // Enforce the same one-manifest-per-release-root invariant as deploy before
+  // either local artifact is written. A parent and child dharta.toml would make
+  // ownership of the child's files ambiguous regardless of transport or CI.
+  await rejectOverlappingAgentRoots(target.dir, s.git);
+  await rejectDuplicateAgentSlug(scanRoot, target.dir, name, hasGit);
+
+  const workflow = s.ci === "github"
+    ? githubWorkflowTarget(
+        scanRoot,
+        target.dir,
+        name,
+        method,
+        await currentGitBranch(s.git, scanRoot),
+      )
+    : undefined;
+  let workflowState: WorkflowState | undefined;
+  if (workflow) {
+    if (!hasGit) throw new Error("--ci github requires a git repo.");
+    await validateWorkflowTarget(workflow);
+    workflowState = await existingWorkflowState(workflow, log);
+    if (workflowState !== "custom") {
+      await rejectGitignoredSetupFile(s.git, scanRoot, workflow.dest, workflow.rel);
+    }
+  }
+
+  const manifestPath = path.join(target.dir, "dharta.toml");
+  await validateSafeWriteTarget(target.dir, manifestPath, "dharta.toml", false);
+  if (hasGit) {
+    await rejectGitignoredSetupFile(s.git, scanRoot, manifestPath, path.relative(scanRoot, manifestPath));
+  }
+  const existingManifest = await lstatIfPresent(manifestPath);
+  const scaffolded = existingManifest === undefined;
+  if (existingManifest) {
+    const patched = patchManifest(await fs.readFile(manifestPath, "utf8"), {
+      name,
+      deploy,
+      deployMethod: method,
+    });
+    await safeAtomicWriteFile(target.dir, manifestPath, "dharta.toml", patched);
+  } else {
+    await safeAtomicWriteFile(
+      target.dir,
+      manifestPath,
+      "dharta.toml",
+      renderManifest({
+        name,
+        deploy,
+        deployMethod: method,
+        harness: target.harnessType ?? DEFAULT_CREATE_HARNESS,
+      }),
+    );
+  }
+  log(
+    `${scaffolded ? "Wrote" : "Updated"} ${path.relative(cwd, manifestPath) || "dharta.toml"} ` +
+      `(name = ${name}, deploy = ${deploy}, deploy_method = ${method}).`,
+  );
+
+  applyMethod(method, { deploy, log });
+  const workflowScaffolded = workflow
+    ? await scaffoldGithubWorkflow(workflow, workflowState as WorkflowState, log)
+    : false;
+
+  return {
+    folder: target.rel,
+    name,
+    deploy,
+    method,
+    ci: s.ci,
+    manifestPath,
+    scaffolded,
+    workflowScaffolded,
+    gitInitialized,
+  };
+}
+
+async function pickOneAgent(initial: AgentFolder[], s: Shared): Promise<AgentFolder | null> {
+  const { scanRoot, hasGit, ask, log } = s;
+  const view = await Promise.all(initial.map((folder) => describeFolder(folder.dir, folder.rel)));
+  log("");
+  log(`Agents in ${hasGit ? "this repo" : "this folder"} (${scanRoot}):`);
+  log("");
+  log(renderMenu(view, null));
+  log("");
+  return selectAgent(ask as (q: string) => Promise<string>, view, log);
+}
+
+// The agent folder the user is standing in: an exact cwd match, else the
+// deepest agent that contains cwd. null when cwd is outside every agent.
+function currentAgentDir(folders: AgentFolder[], cwd: string): string | null {
+  const containing = folders
+    .filter((f) => f.dir === cwd || cwd.startsWith(f.dir + path.sep))
+    .sort((a, b) => b.dir.length - a.dir.length);
+  return containing[0]?.dir ?? null;
+}
+
+// Numbered agent menu: the current folder is prefixed [current], and a final
+// `q` row cancels this invocation.
+function renderMenu(folders: AgentFolder[], currentDir: string | null): string {
+  const headers = ["#", "AGENT FOLDER", "NAME", "HARNESS", "CONFIGURED", "DEPLOY", "METHOD"];
+  const rows = folders.map((f, i) => [
+    String(i + 1),
+    `${f.dir === currentDir ? "[current] " : ""}${f.rel === "." ? "./ (repo root)" : `./${f.rel}`}`,
+    f.name ?? "-",
+    f.harnessType ?? "-",
+    f.configured ? "yes" : "no",
+    f.configured ? (f.deployEnabled ? "enabled" : "disabled") : "-",
+    f.deployMethod ?? "-",
+  ]);
+  const quit = ["q", "quit", "", "", "", "", ""];
+  const widths = headers.map((_, i) => Math.max(...[headers, ...rows, quit].map((r) => r[i].length)));
+  const fmt = (cols: string[]) => cols.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+  return [fmt(headers), ...rows.map(fmt), fmt(quit)].join("\n");
+}
+
+// Read one menu choice: a number, or 'q' to quit. An empty answer quits because
+// an ambiguous repository root has no safe implicit agent selection.
+async function selectAgent(
+  ask: (q: string) => Promise<string>,
+  folders: AgentFolder[],
+  log: (line: string) => void,
+): Promise<AgentFolder | null> {
+  for (;;) {
+    const choice = (await ask("Select one agent to set up, or q to quit [q]:  ")).trim().toLowerCase() || "q";
+    if (choice === "q" || choice === "quit") return null;
+    const n = Number(choice);
+    if (Number.isInteger(n) && n >= 1 && n <= folders.length) return folders[n - 1];
+    log(`Enter a number 1-${folders.length}, or q to quit.`);
+  }
+}
+
+// A read-only SetupResult for "quit before configuring anything" - only used to
+// satisfy the return type; the interactive caller never reads it.
+function snapshotResult(f: AgentFolder, s: Shared): SetupResult {
+  return {
+    folder: f.rel,
+    name: f.name ?? deriveSlug(path.basename(f.dir)),
+    deploy: f.deployEnabled,
+    method: f.deployMethod ?? (s.hasGit ? "git" : "folder"),
+    ci: s.ci,
+    manifestPath: path.join(f.dir, "dharta.toml"),
+    scaffolded: false,
+    workflowScaffolded: false,
+    gitInitialized: s.gitInitialized,
+  };
+}
+
+interface ParsedMethodInput {
+  method?: Method;
+  ci?: CiProvider;
+  legacyGithub: boolean;
+}
+
+function parseMethod(raw: string | undefined): ParsedMethodInput {
+  if (raw === undefined) return { legacyGithub: false };
+  const normalized = normalizeNonBlank(raw, "--method");
+  // Backward compatibility for the old three-way transport switch. GitHub is
+  // automation, and the workflow it historically generated used folder
+  // upload, so preserve that behavior while making the two decisions explicit.
+  if (normalized === "github") {
+    return { method: "folder", ci: "github", legacyGithub: true };
+  }
+  if (!METHODS.includes(normalized as Method)) {
+    const suggestion = closestChoice(normalized, METHOD_INPUTS);
+    throw new Error(
+      `Unknown --method '${normalized}'. Use git or folder.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  }
+  return { method: normalized as Method, legacyGithub: false };
+}
+
+function parseCi(raw: string | undefined): CiProvider | undefined {
+  if (raw === undefined) return undefined;
+  const normalized = normalizeNonBlank(raw, "--ci");
+  if (!CI_PROVIDERS.includes(normalized as CiProvider)) {
+    const suggestion = closestChoice(normalized, CI_PROVIDERS);
+    throw new Error(
+      `Unknown --ci '${normalized}'. Use github.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  }
+  return normalized as CiProvider;
+}
+
+// Before setup decides whether to initialize git, honor a persisted folder
+// method for the obvious single-agent / explicit-path cases. This prevents a
+// routine setup re-run from changing a plain-folder project's repo shape.
+async function inferExistingMethodWithoutGit(
+  cwd: string,
+  pathArg: string | undefined,
+): Promise<Method | undefined> {
+  if (pathArg) {
+    return (await describeFolder(path.resolve(cwd, pathArg), pathArg)).deployMethod;
+  }
+  const folders = await scanAgentFolders(cwd, { isGitRepo: false });
+  if (folders.length === 1) return folders[0].deployMethod;
+  if (folders.length > 1 && folders.every((folder) => folder.deployMethod === "folder")) {
+    return "folder";
+  }
+  return undefined;
+}
+
+async function validateExplicitSetupPath(
+  cwd: string,
+  pathArg: string | undefined,
+  boundary: string,
+): Promise<void> {
+  if (!pathArg) return;
+  const target = path.resolve(cwd, pathArg);
+  try {
+    await validateExistingDirectoryTree(boundary, target, `Cannot set up ${pathArg}`);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      throw new Error(
+        `Cannot set up ${pathArg}: that directory does not exist. ` +
+          `Create an agent first with \`dharta create ${pathArg}\`.`,
+      );
+    }
+    if (code === "ENOTDIR") {
+      throw new Error(`Cannot set up ${pathArg}: a parent path is not a directory.`);
+    }
+    throw error;
+  }
+  if (!hasAgentMarker(target)) {
+    throw new Error(
+      `Cannot set up ${pathArg}: no agent was found there. ` +
+        `Create one first with \`dharta create ${pathArg}\`.`,
+    );
+  }
+}
+
+async function validateSelectedAgentRoot(scanRoot: string, agentDir: string, rel: string): Promise<void> {
+  const label = rel === "." ? "selected agent root" : `selected agent root '${rel}'`;
+  await validateExistingDirectoryTree(scanRoot, agentDir, `Cannot use ${label}`);
+}
+
+// Resolve the agent folder: an explicit path, the sole candidate, an
+// interactive pick, or (non-interactive + ambiguous) a loud error.
+async function pickFolder(
+  pathArg: string | undefined,
+  folders: AgentFolder[],
+  scanRoot: string,
+  cwd: string,
+  ask: ((q: string) => Promise<string>) | undefined,
+): Promise<AgentFolder> {
+  if (pathArg) {
+    const requested = path.resolve(cwd, pathArg);
+    const [scanRootReal, requestedReal] = await Promise.all([fs.realpath(scanRoot), fs.realpath(requested)]);
+    const realRelative = containedRelativePath(scanRootReal, requestedReal);
+    // Use the scan root's spelling for all later reads/writes. This preserves
+    // harmless platform aliases such as macOS /var -> /private/var while
+    // removing any caller-supplied symlink component from the writable path.
+    const dir = realRelative === undefined ? requested : path.resolve(scanRoot, realRelative);
+    const match = folders.find((f) => f.dir === dir);
+    if (match) return match;
+    // Not surfaced by the scan (deep / untracked): describe it directly so an
+    // existing dharta.toml's name + deploy are read, not silently reset to the
+    // folder slug - which would rename the agent and change its deploy slug.
+    return describeFolder(dir, path.relative(scanRoot, dir));
+  }
+  const current = currentAgentDir(folders, cwd);
+  if (current) return folders.find((folder) => folder.dir === current) as AgentFolder;
+  if (folders.length === 1) return folders[0];
+  if (folders.length === 0) {
+    // No marker folder found - configure the scan root itself.
+    return { dir: scanRoot, rel: ".", configured: false, deployEnabled: false };
+  }
+  if (!ask) {
+    throw new Error(
+      "Multiple agent folders here. Pass a [path] to pick one, e.g. `dharta setup ./support-bot`.",
+    );
+  }
+  const answer = (await ask("Configure which folder? (path)  ")).trim();
+  const dir = path.resolve(scanRoot, answer);
+  const match = folders.find((f) => f.dir === dir || f.rel === answer);
+  if (!match) throw new Error(`No agent folder matching '${answer}'.`);
+  return match;
+}
+
+async function askMethod(ask: (q: string) => Promise<string>, hasGit: boolean): Promise<Method> {
+  const def: Method = hasGit ? "git" : "folder";
+  const a = (await ask(`Deploy method - git (push) / folder (upload) [${def}]:  `)).trim().toLowerCase();
+  return METHODS.includes(a as Method) ? (a as Method) : def;
+}
+
+function applyMethod(
+  method: Method,
+  o: { deploy: boolean; log: (l: string) => void },
+): void {
+  const deployHint = o.deploy ? "`dharta deploy`" : "enable it (deploy = true), then `dharta deploy`";
+  switch (method) {
+    case "git":
+      // The hosted repo + the `dharta` remote are provisioned at deploy time
+      // (dharta deploy self-provisions), keeping setup destination-agnostic.
+      o.log(
+        `Method: git. Deploy with ${deployHint} - it provisions the hosted repo and wires the 'karta' remote on first run. ` +
+          "After that, 'dharta deploy' remains the agent-scoped path. A direct deploy-branch push (for example, 'git push dharta main') is a compatibility shortcut only for repos with one enabled agent.",
+      );
+      return;
+    case "folder":
+      o.log(`Method: folder. Deploy with ${deployHint} - it uploads only this agent folder as a tarball.`);
+      return;
+  }
+}
+
+interface GithubWorkflowTarget {
+  repoRoot: string;
+  slug: string;
+  method: Method;
+  branch: string;
+  secretName: string;
+  agentDir: string; // POSIX-style path relative to the checkout root
+  rel: string;
+  dest: string;
+}
+
+function githubWorkflowTarget(
+  repoRoot: string,
+  agentDirectory: string,
+  name: string,
+  method: Method,
+  branch: string,
+): GithubWorkflowTarget {
+  const relative = path.relative(repoRoot, agentDirectory);
+  if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`)) {
+    throw new Error("--ci github requires the agent folder to be inside the git repo.");
+  }
+  const agentDir = relative === "" ? "." : relative.split(path.sep).join("/");
+  if (agentDir.includes("${{")) {
+    throw new Error(
+      "--ci github cannot generate a safe workflow for an agent path containing '${{'. " +
+        "Rename the folder, then run setup again.",
+    );
+  }
+  const slug = deriveSlug(name);
+  const rel = `.github/workflows/dharta-${slug}.yml`;
+  const secretName = `DHARTA_API_KEY_${slug.replaceAll("-", "_").toUpperCase()}`;
+  return { repoRoot, slug, method, branch, secretName, agentDir, rel, dest: path.join(repoRoot, rel) };
+}
+
+async function currentGitBranch(git: GitRunner, repoRoot: string): Promise<string> {
+  const result = await git(["-C", repoRoot, "symbolic-ref", "--quiet", "--short", "HEAD"]);
+  const branch = result.stdout.trim();
+  if (result.code !== 0 || branch.length === 0 || branch.match(/[\0\r\n]/)) {
+    throw new Error(
+      "--ci github needs a checked-out branch so setup can generate the correct push trigger. " +
+        "Check out the deploy branch, then run setup again.",
+    );
+  }
+  if (branch.includes("${{")) {
+    throw new Error(
+      "--ci github cannot generate a safe workflow for a branch containing '${{'. " +
+        "Check out a different deploy branch, then run setup again.",
+    );
+  }
+  return branch;
+}
+
+async function rejectDuplicateAgentSlug(
+  scanRoot: string,
+  targetDir: string,
+  name: string,
+  isGitRepo: boolean,
+): Promise<void> {
+  const slug = deriveSlug(name);
+  const folders = isGitRepo
+    ? await scanAgentFolders(scanRoot, { isGitRepo: true })
+    : await recursiveConfiguredFolders(scanRoot);
+  const conflict = folders.find(
+    (folder) => path.resolve(folder.dir) !== path.resolve(targetDir) &&
+      folder.name !== undefined && deriveSlug(folder.name) === slug,
+  );
+  if (!conflict) return;
+
+  throw new Error(
+    `Agent name '${name}' resolves to slug '${slug}', already used by ${conflict.rel}. ` +
+      "Choose unique agent names before setup; Dharta deploy identity is the derived slug.",
+  );
+}
+
+async function recursiveConfiguredFolders(root: string): Promise<AgentFolder[]> {
+  const folders: AgentFolder[] = [];
+  const walk = async (dir: string): Promise<void> => {
+    if (existsSync(path.join(dir, "dharta.toml"))) {
+      folders.push(await describeFolder(dir, path.relative(root, dir) || "."));
+    }
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      await walk(path.join(dir, entry.name));
+    }
+  };
+  await walk(path.resolve(root));
+  return folders;
+}
+
+// GitHub is an automation layer, not a third persisted transport. Each agent
+// owns one path-filtered workflow and one named secret, so changing support
+// cannot trigger billing and concurrent runs for the same agent stay ordered.
+// The job pins the method rendered by setup so its checkout, concurrency, and
+// credential scope cannot drift from the actual command. Setup does not mint
+// credentials; it explains the scope required by that method.
+async function scaffoldGithubWorkflow(
+  target: GithubWorkflowTarget,
+  state: WorkflowState,
+  log: (l: string) => void,
+): Promise<boolean> {
+  if (state === "custom") return false;
+
+  await safeAtomicWriteFile(
+    target.repoRoot,
+    target.dest,
+    target.rel,
+    renderDeployWorkflow(target),
+  );
+  log(`CI: github. ${state === "generated" ? "Updated" : "Wrote"} ${target.rel} for ${target.agentDir}.`);
+  log(
+    `  This workflow is pinned to --mode ${target.method}. To change methods, rerun setup with ` +
+      "--ci github and rotate the agent's CI secret for the new scope.",
+  );
+  const scope = target.method === "folder" ? "releases:write" : "source_repos:write";
+  log(`  To let CI deploy, add a ${scope} key as the ${target.secretName} repo secret:`);
+  log(`    dharta keys create ci-${target.slug} --scope ${scope}`);
+  log("    (requires an active key with keys:write; dashboard creation also works)");
+  log(`    gh secret set ${target.secretName}  # or add it in repo Settings > Secrets`);
+  log("  Then push a change to this agent folder, or run the workflow manually.");
+  return true;
+}
+
+async function validateWorkflowTarget(target: GithubWorkflowTarget): Promise<void> {
+  // `target.dest` is always repo/.github/workflows/file. Derive the workflow
+  // directory without trusting a caller-supplied relative path.
+  const workflowsDir = path.dirname(target.dest);
+
+  await validateSafeWriteTarget(target.repoRoot, target.dest, target.rel, false);
+  await rejectLegacyRepoWorkflow(workflowsDir, target.dest);
+  await rejectConflictingGeneratedWorkflow(workflowsDir, target);
+}
+
+async function rejectConflictingGeneratedWorkflow(
+  workflowsDir: string,
+  target: GithubWorkflowTarget,
+): Promise<void> {
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await fs.readdir(workflowsDir, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+
+  const agentMarker = `# Agent directory: ${JSON.stringify(target.agentDir)}.`;
+  const unpinnedCommand = `dharta deploy --dir ${shellQuote(target.agentDir)}`;
+  for (const entry of entries) {
+    if (!entry.isFile() || !(entry.name.endsWith(".yml") || entry.name.endsWith(".yaml"))) continue;
+    const dest = path.join(workflowsDir, entry.name);
+    const content = await fs.readFile(dest, "utf8");
+    if (!isManagedWorkflow(content)) continue;
+
+    const deploysTarget = content.includes(agentMarker) || content.includes(unpinnedCommand);
+    if (path.resolve(dest) === path.resolve(target.dest) && !deploysTarget) {
+      throw new Error(
+        `${target.rel} is a generated workflow for a different agent folder. ` +
+          `Agent slug '${target.slug}' is already in use; choose unique dharta.toml names before setup.`,
+      );
+    }
+    if (path.resolve(dest) !== path.resolve(target.dest) && deploysTarget) {
+      const rel = `.github/workflows/${entry.name}`;
+      throw new Error(
+        `${rel} already deploys ${target.agentDir}. Remove or rename that generated workflow ` +
+          "before changing this agent's name, or both workflows could deploy the same folder.",
+      );
+    }
+  }
+}
+
+async function rejectLegacyRepoWorkflow(workflowsDir: string, targetDest: string): Promise<void> {
+  const rel = ".github/workflows/dharta-deploy.yml";
+  const dest = path.join(workflowsDir, "dharta-deploy.yml");
+  let content: string;
+  try {
+    content = await fs.readFile(dest, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT" ||
+        (error as NodeJS.ErrnoException).code === "EISDIR") return;
+    throw error;
+  }
+
+  const generatedLegacy = content.includes("# Deploy this repo's Dharta agents on every push (RFC 0024).") &&
+    content.includes("DHARTA_API_KEY: ${{ secrets.DHARTA_API_KEY }}") &&
+    content.includes("run: dharta deploy --mode folder");
+  if (generatedLegacy) {
+    throw new Error(
+      `${rel} is Dharta's legacy repo-wide deploy workflow and can duplicate or fan out deploys. ` +
+        `Remove it, then rerun setup to create one path-scoped workflow per agent. No files were changed.`,
+    );
+  }
+  if (!isManagedWorkflow(content) && path.resolve(dest) !== path.resolve(targetDest)) {
+    throw new Error(
+      `${rel} already exists but is not a current per-agent Dharta workflow. ` +
+        "Inspect, remove, or rename it before enabling per-agent CI; setup left every file unchanged.",
+    );
+  }
+}
+
+type WorkflowState = "missing" | "generated" | "custom";
+
+async function existingWorkflowState(
+  target: GithubWorkflowTarget,
+  log: (l: string) => void,
+): Promise<WorkflowState> {
+  const { dest, rel } = target;
+  try {
+    const stat = await fs.lstat(dest);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Cannot write ${rel}: the workflow file is a symbolic link.`);
+    }
+    if (stat.isDirectory()) {
+      throw new Error(`Cannot write ${rel}: expected a file, got a directory.`);
+    }
+    const content = await fs.readFile(dest, "utf8");
+    if (isManagedWorkflow(content)) return "generated";
+    log(
+      `CI: github requested, but ${rel} is a custom workflow. Left it unchanged; ` +
+        "CI was not configured. Verify and maintain that workflow yourself.",
+    );
+    return "custom";
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
+    throw error;
+  }
+}
+
+function isManagedWorkflow(content: string): boolean {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] === MANAGED_WORKFLOW_MARKER) {
+    return /^# Deploy only the [a-z0-9-]+ Dharta agent\.$/.test(lines[1] ?? "") &&
+      /^# Agent directory: ".*"\.$/.test(lines[2] ?? "");
+  }
+
+  // Compatibility for the per-agent workflow format emitted immediately
+  // before the explicit ownership marker existed. Its exact first two lines,
+  // pinned-method comment, and deploy command form a narrow signature; a
+  // custom workflow that merely mentions the old generator phrase is not
+  // adopted or overwritten.
+  return /^# Deploy only the [a-z0-9-]+ Dharta agent\. Generated by dharta setup\.$/.test(lines[0] ?? "") &&
+    /^# Agent directory: ".*"\.$/.test(lines[1] ?? "") &&
+    content.includes("# The command is pinned to the ") &&
+    /dharta deploy --mode (git|folder) --dir /.test(content);
+}
+
+interface SafeWriteTarget {
+  rootReal: string;
+  existing?: import("node:fs").Stats;
+}
+
+// Validate an existing directory without following any repo-relative symlink.
+// We deliberately start at the setup/repo boundary instead of walking system
+// ancestors: platform paths such as /var may themselves be legitimate OS
+// links, while every component controlled by the working tree must be real.
+async function validateExistingDirectoryTree(root: string, target: string, label: string): Promise<void> {
+  const absoluteRoot = path.resolve(root);
+  const absoluteTarget = path.resolve(target);
+  const rootStat = await fs.lstat(absoluteRoot);
+  if (rootStat.isSymbolicLink()) {
+    throw new Error(
+      `${label}: '.' is a symbolic link. ` +
+        "Dharta setup does not follow links when selecting an agent folder.",
+    );
+  }
+  if (!rootStat.isDirectory()) throw new Error(`${label}: a parent path is not a directory.`);
+
+  // Check the caller-visible leaf before realpath so a selected agent symlink
+  // is rejected even when it resolves back inside the repo.
+  const targetLeaf = await fs.lstat(absoluteTarget);
+  if (targetLeaf.isSymbolicLink()) {
+    throw new Error(
+      `${label}: '${path.basename(absoluteTarget)}' is a symbolic link. ` +
+        "Dharta setup does not follow links when selecting an agent folder.",
+    );
+  }
+  if (!targetLeaf.isDirectory()) throw new Error(`${label}: expected a directory, got a file.`);
+
+  const [rootReal, targetReal] = await Promise.all([fs.realpath(absoluteRoot), fs.realpath(absoluteTarget)]);
+  const realRelative = containedRelativePath(rootReal, targetReal);
+  if (realRelative === undefined) {
+    throw new Error(`${label}: the resolved path escapes the current setup root.`);
+  }
+
+  // Prefer the caller-visible path when it is lexically below the boundary so
+  // repo-controlled intermediate symlinks are observable. macOS commonly
+  // exposes the same safe temp directory through /var and /private/var; when
+  // those lexical aliases differ, walk the already-contained canonical path.
+  const lexicalRelative = containedRelativePath(absoluteRoot, absoluteTarget);
+  const walkRoot = lexicalRelative === undefined ? rootReal : absoluteRoot;
+  const relativeTarget = lexicalRelative ?? realRelative;
+  const components = relativeTarget === "" ? [] : relativeTarget.split(path.sep);
+  let current = walkRoot;
+  for (const component of components) {
+    current = path.join(current, component);
+    const stat = await fs.lstat(current);
+    const display = path.relative(walkRoot, current) || ".";
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `${label}: '${display}' is a symbolic link. ` +
+          "Dharta setup does not follow links when selecting an agent folder.",
+      );
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`${label}: a parent path is not a directory.`);
+    }
+  }
+}
+
+// Validate (and optionally create) every parent below a trusted root. lstat is
+// intentional: stat/readFile/writeFile would follow a final symlink. A realpath
+// containment check provides a second invariant for platforms with links in
+// unusual directory layouts.
+async function validateSafeWriteTarget(
+  root: string,
+  destination: string,
+  label: string,
+  createParents: boolean,
+): Promise<SafeWriteTarget> {
+  const absoluteRoot = path.resolve(root);
+  const absoluteDestination = path.resolve(destination);
+  const relativeDestination = containedRelativePath(absoluteRoot, absoluteDestination);
+  if (relativeDestination === undefined || relativeDestination === "") {
+    throw new Error(`Cannot write ${label}: destination is outside its intended root.`);
+  }
+
+  await validateExistingDirectoryTree(absoluteRoot, absoluteRoot, `Cannot write ${label}`);
+  const rootReal = await fs.realpath(absoluteRoot);
+  const parent = path.dirname(absoluteDestination);
+  const relativeParent = path.relative(absoluteRoot, parent);
+  const components = relativeParent === "" ? [] : relativeParent.split(path.sep);
+  let current = absoluteRoot;
+  let parentMissing = false;
+
+  for (const component of components) {
+    current = path.join(current, component);
+    let stat: import("node:fs").Stats;
+    try {
+      stat = await fs.lstat(current);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      if (!createParents) {
+        parentMissing = true;
+        break;
+      }
+      try {
+        await fs.mkdir(current);
+      } catch (mkdirError) {
+        if ((mkdirError as NodeJS.ErrnoException).code !== "EEXIST") throw mkdirError;
+      }
+      stat = await fs.lstat(current);
+    }
+
+    const display = path.relative(absoluteRoot, current) || ".";
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `Cannot write ${label}: parent '${display}' is a symbolic link. ` +
+          "Dharta setup refuses to follow links for generated files.",
+      );
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`Cannot write ${label}: a parent path is not a directory.`);
+    }
+    const currentReal = await fs.realpath(current);
+    if (containedRelativePath(rootReal, currentReal) === undefined) {
+      throw new Error(`Cannot write ${label}: parent '${display}' resolves outside its intended root.`);
+    }
+  }
+
+  if (parentMissing) return { rootReal };
+
+  let existing: import("node:fs").Stats | undefined;
+  try {
+    existing = await fs.lstat(absoluteDestination);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { rootReal };
+    if (code === "ENOTDIR") {
+      throw new Error(`Cannot write ${label}: a parent path is not a directory.`);
+    }
+    throw error;
+  }
+  if (existing.isSymbolicLink()) {
+    throw new Error(
+      `Cannot write ${label}: the destination is a symbolic link. ` +
+        "Dharta setup refuses to follow links for generated files.",
+    );
+  }
+  if (existing.isDirectory()) throw new Error(`Cannot write ${label}: expected a file, got a directory.`);
+  if (!existing.isFile()) throw new Error(`Cannot write ${label}: expected a regular file.`);
+  const destinationReal = await fs.realpath(absoluteDestination);
+  if (containedRelativePath(rootReal, destinationReal) === undefined) {
+    throw new Error(`Cannot write ${label}: destination resolves outside its intended root.`);
+  }
+  return { rootReal, existing };
+}
+
+// Write through a fresh same-directory file and atomically replace the final
+// path. O_NOFOLLOW protects the temporary leaf; lstat rejects a linked final
+// leaf; rename replaces rather than dereferences a link introduced after the
+// check. This also avoids leaving half a manifest/workflow on interruption.
+async function safeAtomicWriteFile(
+  root: string,
+  destination: string,
+  label: string,
+  content: string,
+): Promise<void> {
+  const prepared = await validateSafeWriteTarget(root, destination, label, true);
+  const parent = path.dirname(destination);
+  const temporary = path.join(
+    parent,
+    `.${path.basename(destination)}.karta-${process.pid}-${randomBytes(12).toString("hex")}.tmp`,
+  );
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+  const flags = constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow;
+  const finalMode = prepared.existing ? prepared.existing.mode & 0o777 : 0o644;
+  let handle: import("node:fs/promises").FileHandle | undefined;
+  let renamed = false;
+
+  try {
+    handle = await fs.open(temporary, flags, 0o600);
+    const opened = await handle.stat();
+    const temporaryReal = await fs.realpath(temporary);
+    if (containedRelativePath(prepared.rootReal, temporaryReal) === undefined) {
+      throw new Error(`Cannot write ${label}: temporary file escaped its intended root.`);
+    }
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+    await handle.chmod(finalMode);
+    await handle.close();
+    handle = undefined;
+
+    // Re-check after writing, immediately before the atomic replacement. The
+    // inode comparison ensures the lexical temporary path still names the file
+    // descriptor we created rather than a swapped link/file.
+    await validateSafeWriteTarget(root, destination, label, true);
+    const tempStat = await fs.lstat(temporary);
+    if (
+      !tempStat.isFile() || tempStat.isSymbolicLink() ||
+      tempStat.dev !== opened.dev || tempStat.ino !== opened.ino
+    ) {
+      throw new Error(`Cannot write ${label}: temporary file changed during setup.`);
+    }
+    const checkedTemporaryReal = await fs.realpath(temporary);
+    if (containedRelativePath(prepared.rootReal, checkedTemporaryReal) === undefined) {
+      throw new Error(`Cannot write ${label}: temporary file escaped its intended root.`);
+    }
+
+    await fs.rename(temporary, destination);
+    renamed = true;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith(`Cannot write ${label}:`)) throw error;
+    throw new Error(`Cannot write ${label}: ${(error as Error).message}`);
+  } finally {
+    await handle?.close().catch(() => {});
+    if (!renamed) await fs.unlink(temporary).catch(() => {});
+  }
+}
+
+async function lstatIfPresent(file: string): Promise<import("node:fs").Stats | undefined> {
+  try {
+    return await fs.lstat(file);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function containedRelativePath(root: string, candidate: string): string | undefined {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`)) {
+    return undefined;
+  }
+  return relative;
+}
+
+async function rejectGitignoredSetupFile(
+  git: GitRunner,
+  repoRoot: string,
+  destination: string,
+  label: string,
+): Promise<void> {
+  const relative = containedRelativePath(repoRoot, destination);
+  if (relative === undefined || relative === "") {
+    throw new Error(`Cannot check ${label}: path is outside the git repo.`);
+  }
+  const gitPath = relative.split(path.sep).join("/");
+  // Do not pass --no-index: an already tracked generated file remains part of
+  // the repo even if a later ignore rule matches it. New/untracked generated
+  // files are the ones setup must reject as impossible to push.
+  const result = await git(["-C", repoRoot, "check-ignore", "-q", "--", gitPath]);
+  if (result.code === 1) return;
+  if (result.code !== 0) {
+    throw new Error(
+      `git could not check ignore rules for ${gitPath}: ${result.stderr.trim() || `exit ${result.code}`}`,
+    );
+  }
+  throw new Error(
+    `Cannot configure ${label}: ${gitPath} is excluded by .gitignore. ` +
+      "Unignore it, then rerun setup; Dharta did not write the generated file or report it ready to push.",
+  );
+}
+
+function renderDeployWorkflow(target: GithubWorkflowTarget): string {
+  const pushPaths = githubPushPaths(target);
+  const scope = target.method === "folder" ? "releases:write" : "source_repos:write";
+  const reconcileSource = target.method === "git" ? " --reconcile-source" : "";
+  const command =
+    `dharta deploy --mode ${target.method}${reconcileSource} --dir ${shellQuote(target.agentDir)}`;
+  const concurrency = target.method === "git"
+    ? "dharta-git-deploy-${{ github.repository }}"
+    : `dharta-deploy-${target.slug}`;
+  return [
+    MANAGED_WORKFLOW_MARKER,
+    `# Deploy only the ${target.slug} Dharta agent.`,
+    `# Agent directory: ${JSON.stringify(target.agentDir)}.`,
+    "#",
+    `# Authentication comes from this agent's ${target.secretName} repo secret.`,
+    `# The command is pinned to the ${target.method} method used to render this workflow.`,
+    ...(target.method === "git" ? [
+      "# --reconcile-source is safe here only because the branch-tip guard below rejects stale runs.",
+    ] : []),
+    "# To change deploy_method, update dharta.toml by rerunning setup, regenerate this workflow,",
+    "# and rotate the secret so its operation scope matches the new method:",
+    `# rerun: dharta setup ${shellQuote(target.agentDir)} --ci github`,
+    "#",
+    "# Required repo secret:",
+    `#   ${target.secretName}   a dh_live_... key with \`${scope}\`:`,
+    `#                   dharta keys create ci-${target.slug} --scope ${scope}`,
+    "#                   (requires an active key with keys:write; dashboard creation also works)",
+    "# Optional repo variable:",
+    "#   DHARTA_BASE_URL  control-plane URL (defaults to https://dharta.ai).",
+    "",
+    `name: Deploy ${target.slug} to Dharta`,
+    "",
+    "on:",
+    "  push:",
+    `    branches: [${JSON.stringify(githubLiteralPath(target.branch))}]`,
+    "    paths:",
+    ...pushPaths.map((triggerPath) => `      - ${JSON.stringify(triggerPath)}`),
+    "  workflow_dispatch:",
+    "",
+    "permissions:",
+    "  contents: read",
+    "",
+    "concurrency:",
+    `  group: ${concurrency}`,
+    "  queue: max",
+    "  cancel-in-progress: false",
+    "",
+    "jobs:",
+    "  deploy:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    ...(target.method === "git" ? [ "        with:", "          fetch-depth: 0" ] : []),
+    "      - uses: actions/setup-node@v4",
+    '        with:',
+    '          node-version: "20"',
+    "      - name: Install Dharta CLI",
+    `        run: npm install --global @dharta/cli@${CLI_VERSION}`,
+    "      - name: Check current branch tip",
+    "        id: freshness",
+    "        env:",
+    `          DHARTA_DEPLOY_BRANCH: ${JSON.stringify(target.branch)}`,
+    "        run: |",
+    "          git fetch --no-tags --force origin \"refs/heads/${DHARTA_DEPLOY_BRANCH}:refs/remotes/origin/dharta-deploy-tip\"",
+    "          tip=\"$(git rev-parse refs/remotes/origin/dharta-deploy-tip)\"",
+    "          if [ \"$GITHUB_SHA\" = \"$tip\" ]; then",
+    "            echo \"deploy=true\" >> \"$GITHUB_OUTPUT\"",
+    "          else",
+    `            echo "Skipping stale ${target.method} deploy: workflow SHA $GITHUB_SHA is not current branch tip $tip."`,
+    "            echo \"deploy=false\" >> \"$GITHUB_OUTPUT\"",
+    "          fi",
+    "      - name: Deploy",
+    "        if: steps.freshness.outputs.deploy == 'true'",
+    "        env:",
+    `          DHARTA_API_KEY: \${{ secrets.${target.secretName} }}`,
+    "          DHARTA_BASE_URL: ${{ vars.DHARTA_BASE_URL || 'https://dharta.ai' }}",
+    `        run: ${JSON.stringify(command)}`,
+    "",
+  ].join("\n");
+}
+
+function githubPushPaths(target: GithubWorkflowTarget): string[] {
+  // A root agent's `**` covers its own .gitignore and generated workflow.
+  if (target.agentDir === ".") return ["**"];
+
+  const paths = new Set<string>([`${githubLiteralPath(target.agentDir)}/**`]);
+  const parts = target.agentDir.split("/");
+
+  // Folder packaging applies ignore rules from the checkout root through the
+  // selected folder. Include every *potential* ancestor .gitignore, even when
+  // it does not exist yet, so adding one cannot silently change the package
+  // without triggering CI. The selected folder's own .gitignore is already
+  // covered by the subtree glob, hence the strict `< parts.length` bound.
+  for (let depth = 0; depth < parts.length; depth += 1) {
+    const prefix = parts.slice(0, depth).join("/");
+    const ignorePath = prefix ? `${prefix}/.gitignore` : ".gitignore";
+    paths.add(githubLiteralPath(ignorePath));
+  }
+
+  // Ordinarily a generated-workflow edit should trigger its deploy. Avoid a
+  // duplicate when an unusually placed agent subtree already covers it.
+  if (!target.rel.startsWith(`${target.agentDir}/`)) {
+    paths.add(githubLiteralPath(target.rel));
+  }
+  return [...paths];
+}
+
+function githubLiteralPath(value: string): string {
+  // GitHub `paths` values are glob patterns even when YAML-quoted. Escape
+  // metacharacters that are legal in git directory names so a literal agent
+  // path cannot broaden, negate, or otherwise change its workflow trigger.
+  return value.replace(/[\\*?+!\[\]]/g, "\\$&");
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function relLabel(dir: string): string {
+  const rel = path.relative(process.cwd(), dir);
+  return rel === "" ? "./" : `./${rel}`;
+}
+
+// (ensureRemote lives on the deploy command; setup stays destination-
+// agnostic and lets `dharta deploy` provision + wire the remote.)
+
+function yesNo(answer: string, fallback: boolean): boolean {
+  const a = answer.trim().toLowerCase();
+  if (a === "") return fallback;
+  return a === "y" || a === "yes";
+}
+
+function yesNoCancel(answer: string): "yes" | "no" | "cancel" {
+  const a = answer.trim().toLowerCase();
+  if (a === "n" || a === "no") return "no";
+  if (a === "c" || a === "cancel") return "cancel";
+  return "yes"; // empty (the [Yes] default) or y/yes
+}
+
+async function run(git: GitRunner, args: string[], label: string): Promise<void> {
+  const r = await git(args);
+  if (r.code !== 0) throw new Error(`${label} failed: ${r.stderr.trim() || `exit ${r.code}`}`);
+}