@dharta/cli 0.6.77

package/src/commands/deploy.ts

@@ -0,0 +1,1122 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import TOML from "@iarna/toml";
+import type { CliContext } from "../context.js";
+import { slugFromRemote, deriveSlug, validateAgentName, validateAgentSlug } from "../agent.js";
+import { findGitRoot, scanAgentFolders } from "../setup-scan.js";
+import { harnessPreflight } from "../harness-preflight.js";
+import { cliFormatRawError } from "../api-error.js";
+import { normalizeNonBlank } from "../validators.js";
+
+// `dharta deploy [slug]` deploys the ONE agent folder at/above --dir (or cwd).
+// The legacy slug argument may assert that folder's manifest identity, but it
+// can no longer redirect a deploy to a different agent or source repo.
+//
+//   git - push the repo's committed HEAD to an agent-specific ref, carrying
+//   the selected repo-relative folder as a receive-pack push option. Sibling
+//   agents are never implicit deploy targets.
+//
+//   folder - deploy by tarballing only the selected agent working tree
+//   (honoring only .gitignore) and uploading it to the publish-by-upload
+//   endpoint (Api::PublishesController). No commit, no push, so a
+//   divergent or absent git history can't block the deploy. Last-write-
+//   wins by nature - the upload becomes a new release.
+
+interface EnsureRepoResponse {
+  source_repo: { slug: string; deploy_branch: string };
+  clone_url: string;
+  created: boolean;
+}
+
+export interface GitResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+// Injectable for tests; the default shells out to `git`. `stream: true`
+// inherits stdio so push progress + sideband reach the terminal live.
+export type GitRunner = (
+  args: string[],
+  opts?: { env?: Record<string, string>; stream?: boolean },
+) => Promise<GitResult>;
+
+// Per-invocation credential helper for the push: the first empty `-c
+// credential.helper=` clears any configured helpers, then this one
+// answers with the API key read from the child process env. The key is
+// never in argv (visible in `ps`) and never persisted - deploy works
+// non-interactively even when `dharta login` couldn't install the
+// global helper.
+export const INLINE_CREDENTIAL_HELPER =
+  '!f() { echo username=karta; echo "password=$DHARTA_GIT_PASSWORD"; }; f';
+
+export interface DeployOptions {
+  dir?: string;
+  mode?: "git" | "folder";
+  reconcileSource?: boolean;
+  gitRunner?: GitRunner; // for tests
+  log?: (line: string) => void; // for tests
+  // Injectable seams for the RFC 0035 harness version pre-flight (tests).
+  fetchImpl?: typeof fetch;
+  detectLocalVersion?: (type: string) => Promise<string | null>;
+  confirm?: (question: string) => Promise<boolean>;
+  requestId?: string; // deterministic one-shot git deploy ref (tests only)
+}
+
+export interface DeployFolderResult {
+  accepted: true;
+  phase?: "publication";
+  state?: "pending";
+  agent: { id: number; slug: string; name: string };
+  release: {
+    version: number;
+    status: string;
+    harness_slug: string | null;
+    harness_version: string | null;
+  };
+}
+
+type DeployMode = "git" | "folder";
+const MAX_SOURCE_REPO_AGENT_CANDIDATES = 256;
+
+interface DeployTarget {
+  dir: string;
+  slug: string;
+  name: string;
+  deployMethod?: DeployMode;
+}
+
+export async function deploy(
+  ctx: CliContext,
+  slug?: string,
+  opts: DeployOptions = {},
+): Promise<DeployFolderResult | undefined> {
+  const explicitSlug = slug === undefined ? undefined : validateAgentSlug(slug, "agent slug");
+  const requestedDir = resolve(normalizeNonBlank(opts.dir ?? ".", "--dir"));
+  validateDeployDir(requestedDir);
+  const git = opts.gitRunner ?? defaultGitRunner;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const target = await resolveDeployTarget(requestedDir, explicitSlug, git);
+  let mode = opts.mode ?? target.deployMethod;
+  if (!mode) {
+    mode = await inferLegacyMode(target.dir, git);
+    log(
+      `No deploy_method is configured in ${join(target.dir, "dharta.toml")}; ` +
+        `inferred ${mode}. Run \`dharta setup --method ${mode}\` from that agent folder to persist it.`,
+    );
+  }
+  if (opts.reconcileSource && mode !== "git") {
+    throw new Error(
+      "--reconcile-source is only valid for git deploys. " +
+        "Remove it, or use `--mode git` to reconcile Dharta's hosted source branch.",
+    );
+  }
+
+  // RFC 0035 D7: advisory harness-version pre-flight for the selected agent. A
+  // no-op unless [harness] declares a version; throws to abort on an unsatisfiable
+  // pin or a declined local-vs-cloud gap.
+  const preflight = (d: string) =>
+    harnessPreflight({
+      dir: d,
+      baseUrl: ctx.baseUrl,
+      log,
+      fetchImpl: opts.fetchImpl,
+      detectLocalVersion: opts.detectLocalVersion,
+      confirm: opts.confirm,
+    });
+
+  if (mode === "folder") {
+    await preflight(target.dir);
+    return deployFolder(ctx, target.dir, target.slug, target.name, git, log);
+  }
+
+  // Git mode operates on the repository while carrying the exact agent subtree
+  // independently. A forced git deploy of a plain folder initializes that
+  // folder as its own repo, preserving the previous first-deploy convenience.
+  const repoRoot = findGitRoot(target.dir) ?? target.dir;
+  const agentPath = gitAgentPath(repoRoot, target.dir);
+  if (agentPath !== "." && agentPath.length > 255) {
+    throw new Error(
+      `Agent directory '${agentPath}' is ${agentPath.length} characters; ` +
+        "git deploy supports repo-relative agent paths up to 255 characters.",
+    );
+  }
+  const manifestPath = agentPath === "." ? "dharta.toml" : `${agentPath}/dharta.toml`;
+  const gitRepo = await isGitRepo(git, repoRoot);
+  let makeInitialCommit = false;
+
+  if (gitRepo) {
+    // Validate every local condition before provisioning remote state. Only
+    // changes inside this agent block its deploy; dirty siblings are not part
+    // of committed HEAD and do not make an unrelated agent unusable.
+    const status = await git([
+      "-C", repoRoot, "status", "--porcelain", "--", literalPathspec(agentPath),
+    ]);
+    if (status.code !== 0) {
+      throw new Error(`git status failed for ${target.dir}: ${gitFailure(status)}`);
+    }
+    const dirty = status.stdout.trim().length > 0;
+    const head = await git(["-C", repoRoot, "rev-parse", "--verify", "-q", "HEAD"]);
+    if (head.code === 0) {
+      if (dirty) {
+        throw new Error(
+          `Uncommitted changes in ${target.dir}. deploy ships the committed HEAD - ` +
+            `commit (or stash) first, then re-run. ` +
+            `(karta never auto-commits an existing repo's working tree.)`,
+        );
+      }
+      await requireManifestInHead(git, repoRoot, manifestPath);
+    } else {
+      // A git-inited-but-commitless repo (the setup -> deploy seam) needs its
+      // first commit. Ensure the selected manifest will actually be added;
+      // otherwise provisioning a hosted source would leave dangling state.
+      if (dirty) await rejectStagedFilesOutsideAgent(git, repoRoot, agentPath);
+      await rejectIgnoredManifest(git, repoRoot, manifestPath, "the initial commit");
+      makeInitialCommit = true;
+    }
+  } else {
+    const initialFiles = await listDeployFiles(repoRoot, git);
+    if (!initialFiles.includes(manifestPath)) {
+      throw new Error(
+        `${manifestPath} is excluded by git ignore rules and will not be present in the initial commit. ` +
+          "Unignore it, then re-run `dharta deploy`; no hosted source was provisioned.",
+      );
+    }
+  }
+
+  const sourceRepoSlug = await remoteSlug(git, repoRoot);
+  const sourceRepoBody = sourceRepoSlug
+    ? { slug: sourceRepoSlug }
+    : {
+        name: await stableRepositoryHint(git, repoRoot),
+        selected_agent_slug: target.slug,
+        agent_slugs: await configuredAgentSlugs(repoRoot, target.slug),
+      };
+  await preflight(target.dir);
+  const res = await ctx.http.request<EnsureRepoResponse>({
+    method: "POST",
+    path: "/api/source_repos",
+    body: sourceRepoBody,
+  });
+  const branch = res.source_repo.deploy_branch;
+  log(`${res.created ? "Created" : "Found"} source repo ${res.source_repo.slug}`);
+
+  if (!gitRepo) {
+    // A plain folder forced into git mode becomes a repo - say exactly
+    // what ran. (Without --mode git, a non-repo deploys as a folder.)
+    log(`${repoRoot} is not a git repo yet. Initializing one:`);
+    log(`  git init -b ${branch}`);
+    log(`  git add -A -- ${agentPath}`);
+    log(`  git commit -m "dharta deploy"`);
+    await must(git, ["-C", repoRoot, "init", "-b", branch], "git init");
+    await must(
+      git,
+      ["-C", repoRoot, "add", "-A", "--", literalPathspec(agentPath)],
+      "git add",
+    );
+    await must(git, ["-C", repoRoot, "commit", "-m", "dharta deploy"], "git commit");
+  } else if (makeInitialCommit) {
+    log(`No commits yet in ${repoRoot} - making the initial commit for ${target.slug}:`);
+    log(`  git add -A -- ${agentPath}`);
+    log(`  git commit -m "dharta deploy"`);
+    await must(
+      git,
+      ["-C", repoRoot, "add", "-A", "--", literalPathspec(agentPath)],
+      "git add",
+    );
+    await must(git, ["-C", repoRoot, "commit", "-m", "dharta deploy"], "git commit");
+  }
+
+  await ensureRemote(git, repoRoot, res.clone_url);
+
+  const requestId = deployRequestId(opts.requestId);
+  const targetRef = `refs/karta/agents/${target.slug}/requests/${requestId}`;
+  if (opts.reconcileSource) {
+    log(
+      `Reconciling Dharta's hosted ${branch} branch to local HEAD. ` +
+        "Only the hosted source branch is being rewritten; the agent request remains one-shot.",
+    );
+  }
+  log(`Pushing ${target.slug} (${agentPath}) to ${targetRef} on ${res.clone_url} ...`);
+  const pushArgs = [
+    "-C",
+    repoRoot,
+    "-c",
+    "credential.helper=",
+    "-c",
+    `credential.helper=${INLINE_CREDENTIAL_HELPER}`,
+    "push",
+    "--atomic",
+    `--push-option=dharta.agent-path=${agentPath}`,
+    "dharta",
+    `${opts.reconcileSource ? "+" : ""}HEAD:refs/heads/${branch}`,
+    `+HEAD:${targetRef}`,
+  ];
+  const pushOpts = { env: { DHARTA_GIT_PASSWORD: ctx.apiKey }, stream: true };
+  let push = await git(pushArgs, pushOpts);
+  if (push.code !== 0 && retryableAtomicRefRace(push)) {
+    log("The hosted branch changed during this push; retrying the atomic agent update once ...");
+    push = await git(pushArgs, pushOpts);
+  }
+  if (push.code !== 0) {
+    throw new Error(
+      `git push failed (exit ${push.code}). The push output above names the cause; ` +
+        "fix it and re-run `dharta deploy`. If the hosted history diverged, first run " +
+        `\`git fetch karta ${branch}\` and inspect \`git log --oneline --left-right HEAD...FETCH_HEAD\`; ` +
+        "then intentionally align only Dharta's hosted source with " +
+        "`dharta deploy --reconcile-source`. Or deploy without git using " +
+        "`dharta deploy --mode folder` (working-tree upload, last-write-wins).",
+    );
+  }
+  const pushOutput = `${push.stdout}\n${push.stderr}`;
+  if (
+    /build\s+→\s+(?:not started|FAILED|nothing (?:deployed|to deploy))/i.test(pushOutput) ||
+    /superseded by a newer push/i.test(pushOutput) ||
+    /dharta-deploy-result:\s*failed/i.test(pushOutput)
+  ) {
+    throw new Error(
+      "The git source update landed, but Dharta reported that this deployment failed. " +
+        "Fix the remote error shown above and retry the same commit with `dharta deploy`. " +
+        "To deploy the working tree instead, use `dharta deploy --mode folder`.",
+    );
+  }
+  if (/continuing in the background/i.test(pushOutput) || /dharta-deploy-result:\s*pending/i.test(pushOutput)) {
+    throw new Error(
+      "The git source update landed, but Dharta could not confirm an active release before the " +
+        "deploy timeout. Check `dharta agent show` or `dharta logs --tail`; do not assume it is live.",
+    );
+  }
+  if (!/dharta-deploy-result:\s*success/i.test(pushOutput)) {
+    throw new Error(
+      "The git source update landed, but Dharta did not return a successful deployment result. " +
+        "Review the push output and check `dharta agent show` or `dharta logs --tail`; do not assume it is live.",
+    );
+  }
+}
+
+function deployRequestId(explicit?: string): string {
+  const value = explicit ?? `${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`;
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(value)) {
+    throw new Error("Internal deploy request id must contain lowercase letters, digits, and hyphens only.");
+  }
+  return value;
+}
+
+// Transport inference used by cli.ts before it calls deploy. A configured
+// deploy_method takes precedence; legacy manifests keep the repo-shape fallback.
+export async function inferMode(
+  dir: string,
+  git: GitRunner = defaultGitRunner,
+): Promise<"git" | "folder"> {
+  const resolved = resolve(dir);
+  const agentDir = await resolveAgentDir(resolved);
+  if (agentDir) {
+    const configured = await readConfiguredDeployMethod(agentDir);
+    if (configured) return configured;
+    return inferLegacyMode(agentDir, git);
+  }
+  return inferLegacyMode(resolved, git);
+}
+
+async function resolveDeployTarget(
+  requestedDir: string,
+  explicitSlug?: string,
+  git: GitRunner = defaultGitRunner,
+): Promise<DeployTarget> {
+  const dir = await resolveAgentDir(requestedDir);
+  if (!dir) {
+    throw new Error(
+      `No dharta.toml at or above ${requestedDir} - not a harness application. ` +
+        "Run from the agent folder (or one of its subdirectories), or pass --dir.",
+    );
+  }
+
+  validateDeployRoot(dir);
+
+  const manifestPath = join(dir, "dharta.toml");
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = TOML.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+  } catch (error) {
+    throw new Error(`Could not read ${manifestPath}: ${(error as Error).message}`);
+  }
+
+  if (typeof manifest.name !== "string") {
+    throw new Error(`${manifestPath} must declare a non-blank top-level name.`);
+  }
+  const manifestName = validateAgentName(manifest.name, `${manifestPath} name`);
+  // Identity: an explicit top-level `slug` pins the agent identity so the
+  // display name can be free-form ("Chief Marketing Officer" on slug `cmo`).
+  // Without it the slug derives from the name - the original behavior, so
+  // existing manifests keep their identity.
+  if (manifest.slug !== undefined && typeof manifest.slug !== "string") {
+    throw new Error(`${manifestPath} slug must be a string when set.`);
+  }
+  const manifestSlug =
+    typeof manifest.slug === "string"
+      ? validateAgentSlug(manifest.slug, `${manifestPath} slug`)
+      : validateAgentSlug(deriveSlug(manifestName), "dharta.toml name");
+  if (explicitSlug && explicitSlug !== manifestSlug) {
+    throw new Error(
+      `Agent slug '${explicitSlug}' does not match ${manifestPath} identity ` +
+        `'${manifestSlug}' (name '${manifestName}'). The manifest identity is authoritative; ` +
+        `set a top-level slug in dharta.toml to pin it explicitly.`,
+    );
+  }
+
+  if (manifest.deploy !== undefined && typeof manifest.deploy !== "boolean") {
+    throw new Error(`${manifestPath} deploy must be true or false.`);
+  }
+  if (manifest.deploy !== true) {
+    const state = manifest.deploy === false ? "deploy = false" : "deploy is absent";
+    throw new Error(
+      `${manifestSlug} is disabled by ${manifestPath} (${state}). ` +
+        "Set deploy = true before deploying.",
+    );
+  }
+
+  await rejectOverlappingAgentRoots(dir, git);
+  const deployMethod = parseDeployMethod(manifest.deploy_method, manifestPath);
+  return { dir, slug: manifestSlug, name: manifestName, deployMethod };
+}
+
+async function resolveAgentDir(start: string): Promise<string | null> {
+  const requestedDir = resolve(start);
+  const gitRoot = findGitRoot(requestedDir);
+  const boundary = gitRoot ? resolve(gitRoot) : null;
+  let dir = requestedDir;
+  for (;;) {
+    if (existsSync(join(dir, "dharta.toml"))) return dir;
+    if (boundary && dir === boundary) break;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+
+  // A repository root is a useful compatibility entrypoint only when it has
+  // exactly one configured child agent. We never choose among several.
+  const configured = await configuredAgents(boundary as string);
+  if (requestedDir === boundary && configured.length === 1) return configured[0].dir;
+  if (configured.length > 0) {
+    const choices = configured.map((folder) => `  - ${folder.rel}`).join("\n");
+    throw new Error(
+      `${requestedDir === boundary ? "Multiple agent folders are configured in this repo." : `No agent folder contains ${requestedDir}.`} ` +
+        `Run from one agent folder or pass --dir:\n${choices}`,
+    );
+  }
+  return null;
+}
+
+async function configuredAgents(root: string) {
+  return (await scanAgentFolders(root, { isGitRepo: true }))
+    .filter((folder) => folder.configured);
+}
+
+export async function rejectOverlappingAgentRoots(agentDir: string, git: GitRunner): Promise<void> {
+  const gitRoot = findGitRoot(agentDir);
+  const ancestorManifests: string[] = [];
+  let parent = dirname(resolve(agentDir));
+  const boundary = gitRoot ? resolve(gitRoot) : undefined;
+  for (;;) {
+    if (boundary && parent !== boundary && !parent.startsWith(`${boundary}${sep}`)) break;
+    if (existsSync(join(parent, "dharta.toml"))) {
+      ancestorManifests.push(relative(parent, agentDir) || ".");
+    }
+    if ((boundary && parent === boundary) || parent === dirname(parent)) break;
+    parent = dirname(parent);
+  }
+  // Use the exact recursive file view folder packaging uses: files allowed by
+  // repository/ancestor .gitignore files. This catches deep children without
+  // following symlinked directories, and is deliberately independent of a
+  // developer's global excludes or .git/info/exclude.
+  const nested = (await listDeployFiles(agentDir, git))
+    .filter((file) => file !== "dharta.toml" && file.endsWith("/dharta.toml"));
+  if (nested.length === 0 && ancestorManifests.length === 0) return;
+
+  const paths = [
+    ...ancestorManifests.map((relPath) => `ancestor:${relPath}`),
+    ...nested.map((file) => dirname(file)),
+  ].join(", ");
+  throw new Error(
+    `${join(agentDir, "dharta.toml")} contains nested agent folder(s): ${paths}. ` +
+      "Agent folders cannot overlap; move each dharta.toml into a sibling folder before deploying.",
+  );
+}
+
+// `git commit` always commits the whole index. On an unborn branch, setup's
+// convenience commit may therefore include files a user staged for a sibling
+// agent before running deploy, even though the preceding `git add` is scoped
+// to the selected agent. Refuse that case before we touch the index. Staged
+// files inside the selected root are safe: they are part of the one initial
+// agent commit deploy is explicitly about to create.
+async function rejectStagedFilesOutsideAgent(
+  git: GitRunner,
+  repoRoot: string,
+  agentPath: string,
+): Promise<void> {
+  if (agentPath === ".") return;
+
+  const staged = await git(["-C", repoRoot, "diff", "--cached", "--name-only", "-z", "--"]);
+  if (staged.code !== 0) {
+    throw new Error(`git could not inspect staged files in ${repoRoot}: ${gitFailure(staged)}`);
+  }
+  const prefix = `${agentPath}/`;
+  const unrelated = parseNulList(staged.stdout)
+    .filter((file) => file !== agentPath && !file.startsWith(prefix));
+  if (unrelated.length === 0) return;
+
+  const listed = unrelated.slice(0, 3).map((file) => JSON.stringify(file)).join(", ");
+  const remainder = unrelated.length > 3 ? ` (and ${unrelated.length - 3} more)` : "";
+  throw new Error(
+    `Cannot make the initial commit for agent '${agentPath}': unrelated staged file(s) ` +
+      `${listed}${remainder} would also be committed. Commit or unstage those files first, then re-run; ` +
+      "Dharta left the index unchanged.",
+  );
+}
+
+async function requireManifestInHead(
+  git: GitRunner,
+  repoRoot: string,
+  manifestPath: string,
+): Promise<void> {
+  const tree = await git([
+    "-C", repoRoot, "ls-tree", "-r", "--name-only", "-z", "HEAD", "--",
+    literalPathspec(manifestPath),
+  ]);
+  if (tree.code !== 0) {
+    throw new Error(`git could not inspect committed ${manifestPath}: ${gitFailure(tree)}`);
+  }
+  if (parseNulList(tree.stdout).includes(manifestPath)) return;
+
+  await rejectIgnoredManifest(git, repoRoot, manifestPath, "HEAD");
+  throw new Error(
+    `${manifestPath} is not committed in HEAD. Add and commit the selected agent manifest, ` +
+      "then re-run `dharta deploy`; no hosted source was provisioned.",
+  );
+}
+
+async function rejectIgnoredManifest(
+  git: GitRunner,
+  repoRoot: string,
+  manifestPath: string,
+  destination: string,
+): Promise<void> {
+  // `git check-ignore` rejects the `:(literal)` pathspec magic supported by
+  // status/add/ls-tree. Run it from the selected folder against a fixed,
+  // non-magical basename instead; the repository's ancestor rules still
+  // apply, while an agent directory named e.g. `:(top)` cannot inject magic.
+  const agentDir = resolve(repoRoot, dirname(manifestPath));
+  const ignored = await git([
+    "-C", agentDir, "check-ignore", "--no-index", "--", "./dharta.toml",
+  ]);
+  if (ignored.code === 1) return;
+  if (ignored.code !== 0) {
+    throw new Error(`git could not check ignore rules for ${manifestPath}: ${gitFailure(ignored)}`);
+  }
+  if (!ignored.stdout.split(/\r?\n/).some((path) => path === "dharta.toml" || path === "./dharta.toml")) {
+    return;
+  }
+  throw new Error(
+    `${manifestPath} is excluded by .gitignore and will not be present in ${destination}. ` +
+      "Unignore it, add and commit it, then re-run `dharta deploy`; no hosted source was provisioned.",
+  );
+}
+
+async function readConfiguredDeployMethod(dir: string): Promise<DeployMode | undefined> {
+  const manifestPath = join(dir, "dharta.toml");
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = TOML.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+  } catch (error) {
+    throw new Error(`Could not read ${manifestPath}: ${(error as Error).message}`);
+  }
+  return parseDeployMethod(manifest.deploy_method, manifestPath);
+}
+
+function parseDeployMethod(value: unknown, manifestPath: string): DeployMode | undefined {
+  if (value === undefined) return undefined;
+  if (value === "git" || value === "folder") return value;
+  throw new Error(`${manifestPath} deploy_method must be "git" or "folder".`);
+}
+
+async function inferLegacyMode(dir: string, git: GitRunner): Promise<DeployMode> {
+  return (await isGitRepo(git, resolve(dir))) ? "git" : "folder";
+}
+
+function gitAgentPath(repoRoot: string, agentDir: string): string {
+  const native = relative(repoRoot, agentDir);
+  if (native === "") return ".";
+  if (native === ".." || native.startsWith(`..${sep}`) || resolve(repoRoot, native) !== resolve(agentDir)) {
+    throw new Error(`Agent directory ${agentDir} is outside git root ${repoRoot}.`);
+  }
+  const posix = native.split(sep).join("/");
+  if (
+    posix.startsWith("/") ||
+    posix.includes("\0") ||
+    posix.includes("\r") ||
+    posix.includes("\n") ||
+    posix.split("/").some((part) => part === "" || part === "." || part === "..")
+  ) {
+    throw new Error(`Agent path '${posix}' cannot be sent safely to Dharta git.`);
+  }
+  return posix;
+}
+
+// Git treats a path beginning with `:(...)` as pathspec magic and also
+// expands wildcard metacharacters elsewhere. The selected agent folder is a
+// filesystem name, never a pattern, so every Git command accepting a pathspec
+// must opt into literal matching explicitly.
+function literalPathspec(path: string): string {
+  return `:(literal)${path}`;
+}
+
+function validateDeployRoot(dir: string): void {
+  const resolved = resolve(dir);
+  if (lstatSync(resolved).isSymbolicLink()) {
+    throw new Error(
+      `Cannot deploy ${resolved}: the agent folder is a symbolic link. ` +
+        "Deploy a real, self-contained agent directory instead.",
+    );
+  }
+
+  const repoRoot = findGitRoot(resolved);
+  if (!repoRoot) return;
+
+  // Reject a symlink in any component below the repository root. Comparing
+  // canonical roots as well prevents a renamed/moved link from escaping the
+  // repository even if the lexical path still appears contained.
+  const rel = relative(resolve(repoRoot), resolved);
+  let cursor = resolve(repoRoot);
+  for (const part of rel.split(sep).filter(Boolean)) {
+    cursor = join(cursor, part);
+    if (lstatSync(cursor).isSymbolicLink()) {
+      throw new Error(
+        `Cannot deploy ${resolved}: the agent folder passes through symbolic link ${cursor}. ` +
+          "Deploy a real, self-contained directory inside the repository instead.",
+      );
+    }
+  }
+
+  const canonicalRepo = realpathSync(repoRoot);
+  const canonicalAgent = realpathSync(resolved);
+  if (!pathIsInside(canonicalRepo, canonicalAgent)) {
+    throw new Error(
+      `Cannot deploy ${resolved}: its real path is outside repository ${repoRoot}. ` +
+        "Deploy a real, self-contained directory inside the repository instead.",
+    );
+  }
+}
+
+export function validateDeployDir(dir: string): void {
+  const resolved = resolve(normalizeNonBlank(dir, "--dir"));
+  try {
+    if (!statSync(resolved).isDirectory()) {
+      throw new Error(`Cannot deploy ${resolved}: expected a directory.`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`Cannot deploy ${resolved}: directory does not exist.`);
+    }
+    throw error;
+  }
+}
+
+async function isGitRepo(git: GitRunner, dir: string): Promise<boolean> {
+  const r = await git(["-C", dir, "rev-parse", "--is-inside-work-tree"]);
+  return r.code === 0;
+}
+
+async function ensureRemote(
+  git: GitRunner,
+  dir: string,
+  url: string,
+): Promise<void> {
+  // add, or repoint if it already exists (same contract as before: re-
+  // running after a slug change must not strand the old URL).
+  const added = await git(["-C", dir, "remote", "add", "dharta", url]);
+  if (added.code !== 0) {
+    const updated = await git(["-C", dir, "remote", "set-url", "dharta", url]);
+    if (updated.code !== 0) {
+      throw new Error(
+        "Could not set the 'karta' git remote. Check `git remote -v` and add it " +
+          `yourself: git remote add dharta ${url}`,
+      );
+    }
+  }
+}
+
+async function must(
+  git: GitRunner,
+  args: string[],
+  label: string,
+): Promise<void> {
+  const r = await git(args);
+  if (r.code !== 0) throw new Error(`${label} failed: ${gitFailure(r)}`);
+}
+
+function gitFailure(r: GitResult): string {
+  return r.stderr.trim() || `exit ${r.code}`;
+}
+
+function retryableAtomicRefRace(r: GitResult): boolean {
+  return /cannot lock ref|stale info|atomic transaction failed|reference already exists/i
+    .test(`${r.stdout}\n${r.stderr}`);
+}
+
+// Mirrors Api::PublishesController's contract.
+const SLUG_FORMAT = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const MAX_TARBALL_BYTES = 200 * 1024 * 1024;
+
+// `--mode folder`: pack the working tree (honoring only .gitignore) and
+// upload it to the publish-by-upload endpoint. The HTTP response is the result.
+// A 202 is durable acceptance, not activation:
+// report it as incomplete so CI cannot mistake a recoverable background publish
+// for a live deployment.
+async function deployFolder(
+  ctx: CliContext,
+  dir: string,
+  slugCandidate: string,
+  displayName: string,
+  git: GitRunner,
+  log: (line: string) => void,
+): Promise<DeployFolderResult> {
+  const agentSlug = slugCandidate.toLowerCase();
+  if (!SLUG_FORMAT.test(agentSlug)) {
+    throw new Error(
+      `"${agentSlug}" is not a valid agent slug (lowercase letters, digits, ` +
+        `hyphens; max 63). Pass one explicitly: dharta deploy <slug> --mode folder`,
+    );
+  }
+
+  // Enumerate via git so we honor exactly repository/ancestor .gitignore files
+  // and include the working tree as-is: tracked + untracked-not-ignored.
+  // Machine-local global excludes and .git/info/exclude are intentionally not
+  // release inputs, keeping local deploys and generated CI deterministic.
+  // A folder-mode setup deliberately does not `git init`, so the helper falls
+  // back to a temporary bare git dir for truly plain folders.
+  const files = (await listDeployFiles(dir, git))
+    .filter((f) => !isAppleMetadata(f)) // drop macOS sidecar cruft (._*, .DS_Store)
+    .filter((f) => existsSync(join(dir, f))); // skip tracked-but-deleted paths
+  validateDeployFiles(dir, files);
+  if (!files.includes("dharta.toml")) {
+    throw new Error(
+      `dharta.toml is excluded by Git ignore rules and will not be included in the folder deployment. ` +
+        "Unignore it, then re-run `dharta deploy`; no release was uploaded.",
+    );
+  }
+  if (files.length === 0) {
+    throw new Error(
+      `Nothing to deploy in ${dir} - the tree is empty or everything is gitignored.`,
+    );
+  }
+
+  // Honoring only .gitignore means a .env that isn't ignored ships to the
+  // server. Don't silently exclude it (that's the chosen contract) - warn
+  // so an accidental secret upload is at least visible.
+  for (const f of files.filter((p) => /(^|\/)\.env(\.[^/]+)?$/.test(p))) {
+    log(`Warning: ${f} is not gitignored and will be uploaded - add it to .gitignore to exclude it.`);
+  }
+
+  const tarball = await packTarball(dir, files);
+  try {
+    const bytes = await readFile(tarball);
+    if (bytes.length > MAX_TARBALL_BYTES) {
+      throw new Error(
+        `Packed tarball is ${formatBytes(bytes.length)}, over the ` +
+          `${formatBytes(MAX_TARBALL_BYTES)} limit. Trim the folder ` +
+          "(a .gitignore for build output / dependencies usually does it).",
+      );
+    }
+    // No commit means no SHA; the endpoint keys releases by a hex SHA, so a
+    // content hash of the tarball is the honest identifier (stable for an
+    // unchanged tree, and 40 hex chars satisfies the server's format).
+    const commitSha = createHash("sha256").update(bytes).digest("hex").slice(0, 40);
+
+    log(`Uploading ${files.length} files (${formatBytes(bytes.length)}) as ${agentSlug} ...`);
+    log("Building + activating on the server (this can take a minute) ...");
+    const form = new FormData();
+    form.set("commit_sha", commitSha);
+    form.set("name", displayName);
+    form.set("tarball", new Blob([bytes], { type: "application/gzip" }), `${agentSlug}.tar.gz`);
+
+    const res = await ctx.http.raw(
+      `/api/agents/${encodeURIComponent(agentSlug)}/publish`,
+      { method: "POST", body: form },
+    );
+    if (!res.ok) throw await cliFormatRawError(res);
+
+    const text = await res.text();
+    let parsed: unknown = null;
+    if (text.length > 0) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    const result = parseDeployFolderResult(parsed, agentSlug);
+    const release = result.release;
+    // Echo the frozen harness so the developer sees exactly what prod will run
+    // (RFC 0035 D7). Git mode streams the same line via the build sideband.
+    const harness =
+      release.harness_slug && release.harness_version
+        ? ` on ${release.harness_slug} ${release.harness_version}`
+        : "";
+    if (res.status === 202 || result.state === "pending") {
+      log(
+        `Accepted ${agentSlug} release v${release.version}; publication is still pending${harness}.`,
+      );
+      throw new Error(
+        "Dharta retained the release but could not confirm activation before the deploy request ended. " +
+          `Check \`dharta agent show ${agentSlug}\` or \`dharta agent releases ${agentSlug}\`; ` +
+          "do not assume it is live or immediately upload the same source again.",
+      );
+    }
+    log(`Deployed ${agentSlug} release v${release.version} (${release.status})${harness}.`);
+    log(`Open it: dharta open -p ${agentSlug}   ·   Details: dharta agent show ${agentSlug}`);
+    return result;
+  } finally {
+    await rm(dirname(tarball), { recursive: true, force: true });
+  }
+}
+
+function parseDeployFolderResult(value: unknown, expectedSlug: string): DeployFolderResult {
+  const body = asRecord(value);
+  const agent = asRecord(body?.agent);
+  const release = asRecord(body?.release);
+  const phase = body?.phase;
+  const state = body?.state;
+  const harnessSlug = release?.harness_slug;
+  const harnessVersion = release?.harness_version;
+  if (
+    body?.accepted !== true ||
+    typeof agent?.id !== "number" ||
+    !Number.isInteger(agent.id) ||
+    typeof agent.slug !== "string" ||
+    agent.slug !== expectedSlug ||
+    typeof agent.name !== "string" ||
+    typeof release?.version !== "number" ||
+    !Number.isInteger(release.version) ||
+    typeof release.status !== "string" ||
+    (phase !== undefined && phase !== "publication") ||
+    (state !== undefined && state !== "pending") ||
+    (harnessSlug !== undefined && harnessSlug !== null && typeof harnessSlug !== "string") ||
+    (harnessVersion !== undefined && harnessVersion !== null && typeof harnessVersion !== "string")
+  ) {
+    throw new Error(
+      "Dharta returned an invalid folder deploy response. The release may have been created; " +
+        `check \`dharta agent show ${expectedSlug}\` before retrying.`,
+    );
+  }
+  return {
+    accepted: true,
+    ...(phase === "publication" ? { phase } : {}),
+    ...(state === "pending" ? { state } : {}),
+    agent: { id: agent.id, slug: agent.slug, name: agent.name },
+    release: {
+      version: release.version,
+      status: release.status,
+      harness_slug: typeof harnessSlug === "string" ? harnessSlug : null,
+      harness_version: typeof harnessVersion === "string" ? harnessVersion : null,
+    },
+  };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+// Read the slug from the `dharta` git remote already wired in `dir`, or
+// undefined when there is no repo / no such remote. Uses the injected
+// runner so it shares deploy's test seam.
+async function remoteSlug(git: GitRunner, dir: string): Promise<string | undefined> {
+  const r = await git(["-C", dir, "remote", "get-url", "dharta"]);
+  if (r.code !== 0) return undefined;
+  return slugFromRemote(r.stdout.trim()) ?? undefined;
+}
+
+// A fresh clone, generated CI checkout, or worktree may not have Dharta's
+// hosted remote yet. Prefer a canonical upstream identity in that case so a
+// differently named checkout does not accidentally provision a second
+// SourceRepo—and two owners with the same repo basename do not collide.
+// `origin` wins, then `upstream`, then any other non-Dharta remote; the local
+// checkout basename remains a last resort when no network remote exists.
+async function stableRepositoryHint(git: GitRunner, repoRoot: string): Promise<string> {
+  const listed = await git(["-C", repoRoot, "remote", "-v"]);
+  if (listed.code === 0) {
+    const remotes = new Map<string, string>();
+    for (const line of listed.stdout.split(/\r?\n/)) {
+      const match = line.match(/^(\S+)\s+(\S+)\s+\((fetch|push)\)$/);
+      if (!match || match[1] === "dharta") continue;
+      const [, name, url, direction] = match;
+      if (direction === "fetch" || !remotes.has(name)) remotes.set(name, url);
+    }
+    const ordered = [
+      "origin",
+      "upstream",
+      ...[...remotes.keys()].filter((name) => name !== "origin" && name !== "upstream").sort(),
+    ];
+    for (const name of ordered) {
+      const url = remotes.get(name);
+      if (!url) continue;
+      const repository = repositoryHintFromRemote(url);
+      if (repository) return repository;
+    }
+  }
+  return basename(repoRoot);
+}
+
+export function repositoryHintFromRemote(url: string): string | undefined {
+  const raw = url.trim();
+  if (!raw) return undefined;
+  let host: string | undefined;
+  let repositoryPath: string;
+
+  try {
+    const parsed = new URL(raw);
+    // A local file remote cannot provide clone-stable identity. Let the caller
+    // use its explicit local fallback instead.
+    if (parsed.protocol === "file:") return undefined;
+    host = parsed.host.toLowerCase();
+    repositoryPath = decodeURIComponent(parsed.pathname);
+  } catch {
+    // SCP-style SSH URLs (`git@github.com:org/repo.git`) are not WHATWG
+    // URLs. Normalize them to the same host/path identity as HTTPS and
+    // ssh:// clones. Plain filesystem paths are not clone-stable hints.
+    const scp = raw.match(/^(?:[^@/:]+@)?([^/:]+):(.+)$/);
+    if (!scp) return undefined;
+    host = scp[1]?.toLowerCase();
+    repositoryPath = scp[2] ?? "";
+  }
+
+  repositoryPath = repositoryPath
+    .replace(/[?#].*$/, "")
+    .replace(/^[/\\]+|[/\\]+$/g, "")
+    .replace(/\.git$/i, "")
+    .replace(/\\/g, "/");
+  if (!host || !repositoryPath) return undefined;
+
+  const identity = `${host}/${repositoryPath}`;
+  const digest = createHash("sha256").update(identity).digest("hex").slice(0, 10);
+  const readable = deriveSlug(identity.replace(/[./:@]+/g, "-"))
+    .slice(0, 52)
+    .replace(/-+$/, "") || "repo";
+  return `${readable}-${digest}`;
+}
+
+async function configuredAgentSlugs(repoRoot: string, selectedSlug: string): Promise<string[]> {
+  const folders = await scanAgentFolders(repoRoot, { isGitRepo: true });
+  const slugs = new Set<string>([selectedSlug]);
+  for (const folder of folders) {
+    if (!folder.configured || typeof folder.name !== "string" || folder.name.trim().length === 0) continue;
+    try {
+      const candidate = deriveSlug(validateAgentName(folder.name, "configured agent name"));
+      slugs.add(validateAgentSlug(candidate, "configured agent slug"));
+    } catch {
+      // A malformed sibling must not block deploying the selected agent. Its
+      // manifest will surface when that folder itself is selected.
+    }
+  }
+  const siblings = [...slugs]
+    .filter((slug) => slug !== selectedSlug)
+    .sort()
+    .slice(0, MAX_SOURCE_REPO_AGENT_CANDIDATES - 1);
+  return [selectedSlug, ...siblings];
+}
+
+// macOS sidecar cruft that `git ls-files --others` can surface on a Mac and that
+// `tar` itself injects per xattr'd file: AppleDouble resource forks (`._X`) and
+// Finder's `.DS_Store`. Never meaningful agent content - strip both so a
+// Mac-built release isn't littered with them (they would otherwise land in the
+// agent's runtime workspace AND every workspace-git clone, RFC 0043 D9).
+export function isAppleMetadata(relPath: string): boolean {
+  const base = relPath.split("/").pop() ?? relPath;
+  return base.startsWith("._") || base === ".DS_Store";
+}
+
+// Pack exactly `files` (relative to dir) into a gzip tarball in a fresh temp
+// dir. NUL-delimited file list so unusual filenames survive; shells to `tar`
+// like the parity command does for untar.
+async function packTarball(dir: string, files: string[]): Promise<string> {
+  const work = await mkdtemp(join(tmpdir(), "dharta-deploy-"));
+  try {
+    const listFile = join(work, "files.list");
+    const out = join(work, "app.tar.gz");
+    await writeFile(listFile, files.map((f) => `${f}\0`).join(""));
+    await runTar(["-czf", out, "-C", dir, "--null", "-T", listFile]);
+    return out;
+  } catch (err) {
+    await rm(work, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+async function listDeployFiles(dir: string, git: GitRunner): Promise<string[]> {
+  const trackedAndUntracked = [
+    "ls-files", "-z", "--stage", "--cached", "--others", "--exclude-per-directory=.gitignore",
+  ];
+  const listed = await git(["-C", dir, ...trackedAndUntracked]);
+  if (listed.code === 0) return parseDeployFileList(listed.stdout, dir);
+
+  const work = await mkdtemp(join(tmpdir(), "dharta-deploy-git-"));
+  const gitDir = join(work, "repo.git");
+  try {
+    const init = await git(["--git-dir", gitDir, "init", "--bare"]);
+    if (init.code !== 0) {
+      throw new Error(`git init failed for folder listing: ${gitFailure(init)}`);
+    }
+    const plain = await git(["--git-dir", gitDir, "--work-tree", dir, ...trackedAndUntracked]);
+    if (plain.code !== 0) {
+      throw new Error(`git ls-files failed for folder listing: ${gitFailure(plain)}`);
+    }
+    return parseDeployFileList(plain.stdout, dir);
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+function validateDeployFiles(dir: string, files: string[]): void {
+  const canonicalRoot = realpathSync(dir);
+  for (const file of files) {
+    const parts = file.split("/");
+    if (
+      file.length === 0 ||
+      file.includes("\0") ||
+      file.startsWith("/") ||
+      parts.some((part) => part === "" || part === "." || part === "..")
+    ) {
+      throw new Error(`Cannot package unsafe path ${JSON.stringify(file)} from ${dir}.`);
+    }
+
+    const absolute = resolve(dir, ...parts);
+    if (!pathIsInside(resolve(dir), absolute)) {
+      throw new Error(`Cannot package ${file}: it escapes agent folder ${dir}.`);
+    }
+    // Git normally reports files rather than directories. A directory here is
+    // therefore a nested repository (or a future listing regression), and
+    // passing it to tar would recursively bypass Git's ignore/index boundary.
+    if (lstatSync(absolute).isDirectory()) {
+      throw nestedRepositoryError(dir, file);
+    }
+
+    let canonical: string;
+    try {
+      canonical = realpathSync(absolute);
+    } catch (error) {
+      throw new Error(`Cannot package ${file}: ${(error as Error).message}`);
+    }
+    if (!pathIsInside(canonicalRoot, canonical)) {
+      throw new Error(
+        `Cannot package ${file}: its real path is outside agent folder ${dir}. ` +
+          "Agent folders must be self-contained.",
+      );
+    }
+  }
+}
+
+function pathIsInside(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+function parseNulList(stdout: string): string[] {
+  return stdout.split("\0").filter((f) => f.length > 0);
+}
+
+// With --stage, tracked paths carry their index mode while untracked paths are
+// still emitted as bare names. Mode 160000 is a gitlink (usually a submodule or
+// an embedded Git repository). Untracked embedded repositories are emitted as
+// a directory name ending in `/` because Git deliberately does not recurse
+// into them. Neither is a safe archive input: tar would recurse independently
+// of Git and could include the nested repository's metadata, ignored files,
+// and untracked files.
+function parseDeployFileList(stdout: string, dir: string): string[] {
+  const files = new Set<string>();
+  for (const entry of parseNulList(stdout)) {
+    const indexed = /^([0-7]{6}) [0-9a-f]+ [0-3]\t([\s\S]+)$/.exec(entry);
+    const mode = indexed?.[1];
+    const file = indexed?.[2] ?? entry;
+    if (mode === "160000" || file.endsWith("/")) {
+      throw nestedRepositoryError(dir, file);
+    }
+    files.add(file);
+  }
+  return [...files];
+}
+
+function nestedRepositoryError(dir: string, file: string): Error {
+  const display = file.replace(/\/+$/, "") || file;
+  return new Error(
+    `Cannot package ${display} from ${dir}: it is a Git submodule or nested repository. ` +
+      "An agent folder is a self-contained release boundary; vendor or materialize its contents " +
+      "into the agent folder before deploying.",
+  );
+}
+
+function runTar(args: string[]): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    // COPYFILE_DISABLE stops macOS/bsdtar from appending an AppleDouble (`._X`)
+    // member for every xattr-carrying file (e.g. com.apple.provenance) - the real
+    // source of the `._*` litter. Ignored by GNU tar, so it is a no-op on Linux/CI.
+    const proc = spawn("tar", args, {
+      stdio: ["ignore", "ignore", "pipe"],
+      env: { ...process.env, COPYFILE_DISABLE: "1" },
+    });
+    const err: Buffer[] = [];
+    proc.stderr?.on("data", (c) => err.push(c));
+    proc.on("error", () =>
+      reject(new Error("Could not run `tar` to pack the folder (is it installed?).")),
+    );
+    proc.on("close", (code) =>
+      code === 0
+        ? resolvePromise()
+        : reject(new Error(`tar exited ${code} packing the folder: ${Buffer.concat(err).toString().trim()}`)),
+    );
+  });
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB"];
+  let v = n / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(1)} ${units[i]}`;
+}
+
+export const defaultGitRunner: GitRunner = (args, opts = {}) =>
+  new Promise((resolvePromise) => {
+    const proc = spawn("git", args, {
+      env: opts.env ? { ...process.env, ...opts.env } : process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    proc.stdout?.on("data", (c: Buffer) => {
+      out.push(c);
+      if (opts.stream) process.stdout.write(c);
+    });
+    proc.stderr?.on("data", (c: Buffer) => {
+      err.push(c);
+      if (opts.stream) process.stderr.write(c);
+    });
+    proc.on("error", () =>
+      resolvePromise({ code: 127, stdout: "", stderr: "could not run git" }),
+    );
+    proc.on("close", (code) =>
+      resolvePromise({
+        code: code ?? 1,
+        stdout: Buffer.concat(out).toString(),
+        stderr: Buffer.concat(err).toString(),
+      }),
+    );
+  });