@arcadeai/hypotenuse 0.16.1 → 0.19.0

package/dist/hypotenuse.js

@@ -343,7 +343,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@arcadeai/hypotenuse",
-  version: "0.16.1",
+  version: "0.19.0",
   description: "Hypotenuse \u2014 run coding agents on your machine for Linear agent sessions",
   type: "module",
   license: "Apache-2.0",
@@ -752,6 +752,173 @@ function isPreset(name) {
 
 // src/config/resolve.ts
 import { basename } from "path";
+function agentById(config, id) {
+  const table = config.agents[id];
+  if (table) {
+    const base = table.preset ? [...AGENT_PRESETS[table.preset].command] : table.command ?? [];
+    return {
+      id,
+      preset: table.preset ?? null,
+      command: [...base, ...table.args],
+      env: table.env,
+      maxParallel: table.max_parallel
+    };
+  }
+  if (isPreset(id)) {
+    return {
+      id,
+      preset: id,
+      command: [...AGENT_PRESETS[id].command],
+      env: {},
+      maxParallel: undefined
+    };
+  }
+  return;
+}
+function playedRoles(config) {
+  return config.runner.roles.flatMap((role) => {
+    const table = config.roles[role];
+    return table ? [[role, table]] : [];
+  });
+}
+function resolveAgents(config) {
+  const byId = new Map;
+  for (const id of Object.keys(config.agents)) {
+    const agent = agentById(config, id);
+    if (agent)
+      byId.set(id, { ...agent, roles: [] });
+  }
+  for (const [role, table] of playedRoles(config)) {
+    const known = byId.get(table.agent);
+    if (known) {
+      if (!known.roles.includes(role))
+        known.roles.push(role);
+      continue;
+    }
+    const agent = agentById(config, table.agent);
+    if (agent)
+      byId.set(table.agent, { ...agent, roles: [role] });
+  }
+  return [...byId.values()];
+}
+function repositoryName(repo, origin) {
+  if (repo.name)
+    return repo.name;
+  const source = origin ?? repo.path;
+  return basename(source.replace(/\/+$/, "")) || "repository";
+}
+
+// src/acp/presets.ts
+var SESSION_VARIABLES = new Set([
+  "HYPOTENUSE_SESSION_ID",
+  "HYPOTENUSE_LINEAR_SESSION_ID",
+  "HYPOTENUSE_ISSUE",
+  "HYPOTENUSE_ISSUE_URL",
+  "HYPOTENUSE_BRANCH",
+  "HYPOTENUSE_BASE_BRANCH",
+  "HYPOTENUSE_ROLE",
+  "HYPOTENUSE_SESSION_URL"
+]);
+function expandVariables(value, env) {
+  return value.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, bare) => env[braced ?? bare] ?? "");
+}
+function sessionVariables(assignment, branch) {
+  return {
+    HYPOTENUSE_SESSION_ID: String(assignment.agentSessionId),
+    HYPOTENUSE_LINEAR_SESSION_ID: assignment.externalSessionId,
+    HYPOTENUSE_ISSUE: assignment.issue.identifier ?? "",
+    HYPOTENUSE_ISSUE_URL: assignment.issue.url ?? "",
+    HYPOTENUSE_BRANCH: branch ?? "",
+    HYPOTENUSE_BASE_BRANCH: assignment.repository?.baseBranch ?? "",
+    HYPOTENUSE_ROLE: assignment.role,
+    HYPOTENUSE_SESSION_URL: assignment.dashboardUrl,
+    GIT_TERMINAL_PROMPT: "0"
+  };
+}
+function sessionEnvironment(daemonEnv, extra) {
+  const env = {};
+  for (const [key, value] of Object.entries(daemonEnv)) {
+    if (value === undefined)
+      continue;
+    if (key.startsWith("HYPOTENUSE_") && !SESSION_VARIABLES.has(key))
+      continue;
+    env[key] = value;
+  }
+  return Object.assign(env, extra);
+}
+function resolveAgentLaunch(config, agentId, daemonEnv, extra = {}) {
+  const agent = resolveAgents(config).find((a) => a.id === agentId);
+  if (!agent || !agent.command.length)
+    return null;
+  const table = config.agents[agentId];
+  const env = sessionEnvironment(daemonEnv, {});
+  const preset = agent.preset ? AGENT_PRESETS[agent.preset] : null;
+  if (preset && "env" in preset && preset.env)
+    Object.assign(env, preset.env);
+  if (agent.command[0] === "npx")
+    env.npm_config_yes = "true";
+  for (const [key, value] of Object.entries(agent.env))
+    env[key] = expandVariables(value, daemonEnv);
+  Object.assign(env, extra);
+  return {
+    id: agent.id,
+    preset: agent.preset,
+    command: agent.command,
+    env,
+    startupTimeoutMs: table?.startup_timeout ?? 60000,
+    authMethod: table?.auth_method ?? null
+  };
+}
+
+// src/config/loader.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname as dirname2 } from "path";
+import { parse, TomlError } from "smol-toml";
+
+// src/config/introspect.ts
+function defOf(schema) {
+  return schema._zod.def;
+}
+function unwrap(schema) {
+  let current = schema;
+  for (;; ) {
+    const def = defOf(current);
+    if (def.innerType && ["optional", "default", "prefault", "nullable", "readonly"].includes(def.type)) {
+      current = def.innerType;
+    } else if (def.type === "pipe" && def.in) {
+      current = def.in;
+    } else {
+      return current;
+    }
+  }
+}
+function schemaAt(schema, path) {
+  let current = schema;
+  for (const segment of path) {
+    if (!current)
+      return;
+    const def = defOf(unwrap(current));
+    if (def.type === "object")
+      current = def.shape?.[String(segment)];
+    else if (def.type === "record")
+      current = def.valueType;
+    else if (def.type === "array")
+      current = def.element;
+    else
+      return;
+  }
+  return current;
+}
+function objectKeys(schema) {
+  if (!schema)
+    return [];
+  const def = defOf(unwrap(schema));
+  return def.type === "object" ? Object.keys(def.shape ?? {}) : [];
+}
+
+// src/config/schema.ts
+import { cpus, hostname } from "os";
+import { z as z9 } from "zod";
 
 // ../protocol/src/capabilities.ts
 import { z as z2 } from "zod";
@@ -1886,175 +2053,6 @@ var WorkAssignment = z8.looseObject({
 var ClaimResponse = z8.looseObject({
   assignment: WorkAssignment.nullable()
 });
-// src/config/resolve.ts
-function agentById(config, id) {
-  const table = config.agents[id];
-  if (table) {
-    const base = table.preset ? [...AGENT_PRESETS[table.preset].command] : table.command ?? [];
-    return {
-      id,
-      preset: table.preset ?? null,
-      command: [...base, ...table.args],
-      env: table.env,
-      maxParallel: table.max_parallel
-    };
-  }
-  if (isPreset(id)) {
-    return {
-      id,
-      preset: id,
-      command: [...AGENT_PRESETS[id].command],
-      env: {},
-      maxParallel: undefined
-    };
-  }
-  return;
-}
-function playedRoles(config) {
-  return config.runner.roles.flatMap((role) => {
-    const table = config.roles[role];
-    return table ? [[role, table]] : [];
-  });
-}
-function resolveAgents(config) {
-  const byId = new Map;
-  for (const id of Object.keys(config.agents)) {
-    const agent = agentById(config, id);
-    if (agent)
-      byId.set(id, { ...agent, roles: [] });
-  }
-  for (const [role, table] of playedRoles(config)) {
-    const known = byId.get(table.agent);
-    if (known) {
-      if (!known.roles.includes(role))
-        known.roles.push(role);
-      continue;
-    }
-    const agent = agentById(config, table.agent);
-    if (agent)
-      byId.set(table.agent, { ...agent, roles: [role] });
-  }
-  return [...byId.values()];
-}
-function repositoryName(repo) {
-  if (repo.name)
-    return repo.name;
-  const source = repo.remote ? normalizeRemote(repo.remote) : repo.path;
-  return basename(source.replace(/\/+$/, "")) || "repository";
-}
-
-// src/acp/presets.ts
-var SESSION_VARIABLES = new Set([
-  "HYPOTENUSE_SESSION_ID",
-  "HYPOTENUSE_LINEAR_SESSION_ID",
-  "HYPOTENUSE_ISSUE",
-  "HYPOTENUSE_ISSUE_URL",
-  "HYPOTENUSE_BRANCH",
-  "HYPOTENUSE_BASE_BRANCH",
-  "HYPOTENUSE_ROLE",
-  "HYPOTENUSE_SESSION_URL"
-]);
-function expandVariables(value, env) {
-  return value.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, bare) => env[braced ?? bare] ?? "");
-}
-function sessionVariables(assignment, branch) {
-  return {
-    HYPOTENUSE_SESSION_ID: String(assignment.agentSessionId),
-    HYPOTENUSE_LINEAR_SESSION_ID: assignment.externalSessionId,
-    HYPOTENUSE_ISSUE: assignment.issue.identifier ?? "",
-    HYPOTENUSE_ISSUE_URL: assignment.issue.url ?? "",
-    HYPOTENUSE_BRANCH: branch ?? "",
-    HYPOTENUSE_BASE_BRANCH: assignment.repository?.baseBranch ?? "",
-    HYPOTENUSE_ROLE: assignment.role,
-    HYPOTENUSE_SESSION_URL: assignment.dashboardUrl,
-    GIT_TERMINAL_PROMPT: "0"
-  };
-}
-function sessionEnvironment(daemonEnv, extra) {
-  const env = {};
-  for (const [key, value] of Object.entries(daemonEnv)) {
-    if (value === undefined)
-      continue;
-    if (key.startsWith("HYPOTENUSE_") && !SESSION_VARIABLES.has(key))
-      continue;
-    env[key] = value;
-  }
-  return Object.assign(env, extra);
-}
-function resolveAgentLaunch(config, agentId, daemonEnv, extra = {}) {
-  const agent = resolveAgents(config).find((a) => a.id === agentId);
-  if (!agent || !agent.command.length)
-    return null;
-  const table = config.agents[agentId];
-  const env = sessionEnvironment(daemonEnv, {});
-  const preset = agent.preset ? AGENT_PRESETS[agent.preset] : null;
-  if (preset && "env" in preset && preset.env)
-    Object.assign(env, preset.env);
-  if (agent.command[0] === "npx")
-    env.npm_config_yes = "true";
-  for (const [key, value] of Object.entries(agent.env))
-    env[key] = expandVariables(value, daemonEnv);
-  Object.assign(env, extra);
-  return {
-    id: agent.id,
-    preset: agent.preset,
-    command: agent.command,
-    env,
-    startupTimeoutMs: table?.startup_timeout ?? 60000,
-    authMethod: table?.auth_method ?? null
-  };
-}
-
-// src/config/loader.ts
-import { existsSync, readFileSync } from "fs";
-import { dirname as dirname2 } from "path";
-import { parse, TomlError } from "smol-toml";
-
-// src/config/introspect.ts
-function defOf(schema) {
-  return schema._zod.def;
-}
-function unwrap(schema) {
-  let current = schema;
-  for (;; ) {
-    const def = defOf(current);
-    if (def.innerType && ["optional", "default", "prefault", "nullable", "readonly"].includes(def.type)) {
-      current = def.innerType;
-    } else if (def.type === "pipe" && def.in) {
-      current = def.in;
-    } else {
-      return current;
-    }
-  }
-}
-function schemaAt(schema, path) {
-  let current = schema;
-  for (const segment of path) {
-    if (!current)
-      return;
-    const def = defOf(unwrap(current));
-    if (def.type === "object")
-      current = def.shape?.[String(segment)];
-    else if (def.type === "record")
-      current = def.valueType;
-    else if (def.type === "array")
-      current = def.element;
-    else
-      return;
-  }
-  return current;
-}
-function objectKeys(schema) {
-  if (!schema)
-    return [];
-  const def = defOf(unwrap(schema));
-  return def.type === "object" ? Object.keys(def.shape ?? {}) : [];
-}
-
-// src/config/schema.ts
-import { cpus, hostname } from "os";
-import { z as z9 } from "zod";
-
 // src/config/durations.ts
 var DURATION_UNITS = {
   ms: 1,
@@ -2137,6 +2135,9 @@ function expandPath(raw, baseDir, env = process.env) {
   value = value.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, bare) => env[braced ?? bare] ?? "");
   return isAbsolute(value) ? resolve(value) : resolve(baseDir, value);
 }
+function isRemoteSource(source) {
+  return /^https?:\/\//i.test(source.trim());
+}
 function tildify(path, env = process.env) {
   const home = homeOf(env);
   return path === home ? "~" : path.startsWith(`${home}/`) ? `~/${path.slice(home.length + 1)}` : path;
@@ -2201,6 +2202,9 @@ function machineContext(baseDir, env = process.env) {
 }
 function buildConfigSchema(ctx) {
   const path = () => z9.string().trim().min(1).transform((value) => expandPath(value, ctx.baseDir, ctx.env));
+  const source = () => z9.string().trim().min(1).refine((value) => !isRemoteSource(value) || URL.canParse(value), {
+    message: "expected a path or an http(s) URL"
+  }).transform((value) => isRemoteSource(value) ? value : expandPath(value, ctx.baseDir, ctx.env));
   const duration = () => z9.string().regex(DURATION_PATTERN, "expected a duration such as 45s, 10m, 2h, or 7d").transform(parseDuration);
   const size = () => z9.string().regex(SIZE_PATTERN, "expected a size such as 500MB or 2GB").transform(parseSize);
   const parallel = () => z9.number().int().min(1).max(32);
@@ -2223,7 +2227,8 @@ function buildConfigSchema(ctx) {
   const role = (fallbackPolicy) => z9.strictObject({
     agent: z9.string().trim().min(1).describe("An [agents.<id>] id or a preset name"),
     prompt: z9.string().min(1).optional().describe("The role's entry prompt template, inline"),
-    prompt_file: path().optional().describe("A Markdown prompt template file"),
+    prompt_file: source().optional().describe("A Markdown prompt template file, or a URL of instructions the agent reads with its own tools"),
+    docs: z9.array(source()).default([]).describe("Documents added to the role's instructions: a file's text is included, a URL is linked for the agent to read with its own tools"),
     permission_policy: permissionPolicy(fallbackPolicy),
     max_parallel: parallel().optional().describe("Jobs of this role at once"),
     mode: z9.string().trim().min(1).optional().describe("The ACP session mode to select"),
@@ -2245,7 +2250,6 @@ function buildConfigSchema(ctx) {
   const repository = z9.strictObject({
     name: z9.string().trim().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "letters, digits, `.`, `_`, `-`").max(64).optional().describe("Unique; used in worktree paths"),
     path: path().describe("An existing git clone"),
-    remote: z9.string().trim().min(1).optional().describe("The repository's remote; must match origin"),
     base_branch: z9.string().trim().min(1).optional().describe("The branch worktrees start from"),
     setup: strings().default([]).describe("Shell commands run in each new worktree"),
     setup_timeout: duration().prefault("10m").describe("Per setup command"),
@@ -2585,11 +2589,11 @@ function originHead(machine, path) {
   return result.code === 0 && ref.startsWith("origin/") ? ref.slice("origin/".length) : null;
 }
 function resolveRepository(machine, repo) {
-  const remote = repo.remote ? normalizeRemote(repo.remote) : originOf(machine, repo.path);
+  const remote = originOf(machine, repo.path);
   if (!remote)
     return null;
   return {
-    name: repositoryName({ ...repo, remote }),
+    name: repositoryName(repo, remote),
     remote,
     baseBranch: repo.base_branch ?? originHead(machine, repo.path) ?? "main",
     path: repo.path
@@ -3133,35 +3137,7 @@ function validateReferences(config) {
       hint: 'the default denies edit, delete, move, and execute: { default = "allow", edit = "deny", delete = "deny", move = "deny", execute = "deny" }'
     });
   }
-  const names = new Map;
-  const remotes = new Map;
   config.repositories.forEach((repo, index) => {
-    const name = repositoryName(repo);
-    if (!repo.name && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name)) {
-      errors.push({
-        path: `repositories[${index}]`,
-        message: `"${name}" is not a usable repository name (letters, digits, \`.\`, \`_\`, \`-\`); set name`
-      });
-    }
-    const firstName = names.get(name);
-    if (firstName !== undefined) {
-      errors.push({
-        path: `repositories[${index}].name`,
-        message: `"${name}" is already repositories[${firstName}]`
-      });
-    } else
-      names.set(name, index);
-    if (repo.remote) {
-      const remote = normalizeRemote(repo.remote);
-      const first = remotes.get(remote);
-      if (first !== undefined) {
-        errors.push({
-          path: `repositories[${index}].remote`,
-          message: `${remote} is already repositories[${first}]`
-        });
-      } else
-        remotes.set(remote, index);
-    }
     if (repo.cleanup === "ttl" && config.sessions.cleanup_ttl === undefined) {
       errors.push({
         path: `repositories[${index}].cleanup`,
@@ -3252,6 +3228,8 @@ function validateMachine(config, machine, options = {}) {
       message: `git ${version.join(".")} is older than ${MIN_GIT_VERSION.join(".")}`
     });
   }
+  const origins = new Map;
+  const names = new Map;
   config.repositories.forEach((repo, index) => {
     const at = `repositories[${index}]`;
     if (!machine.isDirectory(repo.path)) {
@@ -3278,21 +3256,37 @@ function validateMachine(config, machine, options = {}) {
       return;
     }
     const origin = originOf(machine, repo.path);
-    const configured = repo.remote ? normalizeRemote(repo.remote) : null;
     if (!origin) {
       errors.push({
-        path: `${at}.remote`,
+        path: `${at}.path`,
         message: `${home(repo.path)} has no origin remote`
       });
       return;
     }
-    if (configured && origin !== configured) {
+    const first = origins.get(origin);
+    if (first !== undefined) {
       errors.push({
-        path: `${at}.remote`,
-        message: `origin is ${origin}, config says ${configured}`
+        path: `${at}.path`,
+        message: `${home(repo.path)} is another clone of ${origin}, already repositories[${first}]`
       });
       return;
     }
+    origins.set(origin, index);
+    const name = repositoryName(repo, origin);
+    if (!repo.name && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name)) {
+      errors.push({
+        path: `${at}`,
+        message: `"${name}" (from origin ${origin}) is not a usable repository name (letters, digits, \`.\`, \`_\`, \`-\`); set name`
+      });
+    }
+    const firstName = names.get(name);
+    if (firstName !== undefined) {
+      errors.push({
+        path: `${at}.name`,
+        message: `"${name}" is already repositories[${firstName}]${repo.name ? "" : ` (from origin ${origin}); set name`}`
+      });
+    } else
+      names.set(name, index);
     const base = repo.base_branch ?? originHead(machine, repo.path) ?? "main";
     if (!options.offline) {
       const heads = machine.git(["ls-remote", "--heads", "origin", base], repo.path);
@@ -3315,7 +3309,7 @@ function validateMachine(config, machine, options = {}) {
   ]) {
     if (!table)
       continue;
-    if (table.prompt_file !== undefined) {
+    if (table.prompt_file !== undefined && !isRemoteSource(table.prompt_file)) {
       const text = machine.readFile(table.prompt_file);
       if (text === null) {
         errors.push({
@@ -3326,6 +3320,14 @@ function validateMachine(config, machine, options = {}) {
         checkTemplate(`roles.${role}.prompt_file`, text, errors);
       }
     }
+    table.docs.forEach((doc, index) => {
+      if (isRemoteSource(doc) || machine.readFile(doc) !== null)
+        return;
+      errors.push({
+        path: `roles.${role}.docs[${index}]`,
+        message: `${home(doc)} cannot be read`
+      });
+    });
     table.extra_mcp_servers.forEach((server, index) => {
       const at = `roles.${role}.extra_mcp_servers[${index}]`;
       for (const [key, name] of [
@@ -4619,7 +4621,7 @@ function coAuthorEnvironment(env, hooksDir, coAuthor) {
 
 // src/worktree/manager.ts
 import { existsSync as existsSync10, mkdirSync as mkdirSync5, statSync as statSync4 } from "fs";
-import { join as join6 } from "path";
+import { isAbsolute as isAbsolute5, join as join6, relative as relative4, resolve as resolve2 } from "path";
 
 // src/worktree/branch.ts
 var SLUG_MAX = 40;
@@ -5172,6 +5174,10 @@ ${stderrTail(fetched)}
           return { row: previous, reused: true };
         }
         request.output(`not reusing ${previous.path}: HEAD is ${head.stdout.trim() || "unreadable"}, not ${previous.branch}`);
+      } else {
+        const orphan = await this.ownOrphan(request, repository);
+        if (orphan)
+          return { row: orphan, reused: true };
       }
       if (!this.diskStatus(request.config).enough) {
         if (!cleaned)
@@ -5222,6 +5228,45 @@ ${stderrTail(fetched)}
       return { row: created, reused: false };
     });
   }
+  async ownOrphan(request, repository) {
+    const id = request.assignment.agentSessionId;
+    const root = resolve2(request.config.sessions.worktree_root);
+    const list = await this.git(["worktree", "list", "--porcelain"], {
+      cwd: repository.path
+    });
+    if (list.code !== 0)
+      return null;
+    for (const block of list.stdout.split(`
+
+`)) {
+      const path = /^worktree (.+)$/m.exec(block)?.[1];
+      const branch = /^branch refs\/heads\/(.+)$/m.exec(block)?.[1];
+      if (!path || !branch || !existsSync10(path))
+        continue;
+      const rel = relative4(root, path);
+      if (rel === "" || rel.startsWith("..") || isAbsolute5(rel))
+        continue;
+      if (await this.branchOwner(repository.path, branch) !== id)
+        continue;
+      const known = this.state.worktreeAt(path);
+      if (known && (known.state === "removed" || known.agentSessionId !== id))
+        continue;
+      const row = known ?? this.state.insertWorktree({
+        kind: "worktree",
+        repository: repository.name,
+        repoPath: repository.path,
+        path,
+        branch,
+        baseBranch: repository.baseBranch,
+        agentSessionId: id
+      });
+      this.state.updateWorktree(row.id, { state: "active", touch: true });
+      this.state.linkWorktree(id, row.id);
+      request.output(`reusing ${path} on ${branch}: a previous daemon made it but did not record it`);
+      return this.state.worktree(row.id) ?? row;
+    }
+    return null;
+  }
   reusable(agentSessionId) {
     const session = this.state.session(agentSessionId);
     const row = session?.worktreeId ? this.state.worktree(session.worktreeId) : null;
@@ -5567,7 +5612,7 @@ import {
   rmSync as rmSync4,
   writeFileSync as writeFileSync4
 } from "fs";
-import { basename as basename2, dirname as dirname7, isAbsolute as isAbsolute5, join as join7, resolve as resolve2, sep } from "path";
+import { basename as basename2, dirname as dirname7, isAbsolute as isAbsolute6, join as join7, resolve as resolve3, sep } from "path";
 
 class OutsideWorktree extends Error {
   path;
@@ -5626,7 +5671,7 @@ class ConfinedFs {
     const root = this.roots[0];
     if (!root)
       throw new OutsideWorktree(path);
-    return isAbsolute5(path) ? resolve2(path) : resolve2(root, path);
+    return isAbsolute6(path) ? resolve3(path) : resolve3(root, path);
   }
   read(path, line, limit) {
     const real = this.resolveExisting(path);
@@ -5920,7 +5965,7 @@ function callText(call) {
 }
 
 // src/acp/mcp-servers.ts
-import { isAbsolute as isAbsolute6 } from "path";
+import { isAbsolute as isAbsolute7 } from "path";
 var HYPOTENUSE_SERVER_NAME = "hypotenuse";
 var VARIABLE = /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g;
 
@@ -5970,7 +6015,7 @@ function turnMcpServers(role, caps, env, hypotenuse) {
       const [command, ...args] = s.command;
       servers.push({
         name: s.name,
-        command: isAbsolute6(command) ? command : Bun.which(command, { PATH: env.PATH ?? "" }) ?? command,
+        command: isAbsolute7(command) ? command : Bun.which(command, { PATH: env.PATH ?? "" }) ?? command,
         args,
         env: pairs(s.name, s.env, env)
       });
@@ -6209,6 +6254,26 @@ function fenceFor(text) {
   const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((m) => m[0].length));
   return "`".repeat(Math.max(3, longest + 1));
 }
+function remoteInstructions(url) {
+  return `Your instructions for this role are the document at ${url}. Read it with your tools before doing anything else, and follow it. If you cannot read it, say so in your response and stop.`;
+}
+function roleDocsSection(docs) {
+  if (docs.length === 0)
+    return "";
+  const links = docs.filter((d) => d.text === null).map((d) => d.source);
+  const files = docs.filter((d) => d.text !== null);
+  return [
+    "These documents are part of your instructions: they say how this team works. Where one disagrees with the instructions above about your tools or what you never do, the instructions above win.",
+    links.length ? `Read each of these with your tools before you begin. If one cannot be read, say so in your response.
+${links.map((l) => `- ${l}`).join(`
+`)}` : null,
+    ...files.map((d) => `<doc source=${attr(d.source)}>
+${(d.text ?? "").trim()}
+</doc>`)
+  ].filter(Boolean).join(`
+
+`);
+}
 function reviewSection(review) {
   const issue = review.childIssueIdentifier ?? "the dispatched issue";
   const body = [
@@ -6315,7 +6380,8 @@ ${g.body.trim()}
 `);
   const text = [
     section("hypotenuse", `You are working as the ${assignment.role} agent for ${who}${creator ? ` on behalf of ${creator}` : ""}, in a Linear agent session. You are an AI agent; never claim to be a person. What you say at the end of your turn is posted to the session as your response.${dispatchedBy(assignment)}`),
-    section("role-instructions", renderTemplate(template, values, onUnknown)),
+    section("role-instructions", ctx.templateUrl ? remoteInstructions(ctx.templateUrl) : renderTemplate(template, values, onUnknown)),
+    section("role-docs", roleDocsSection(ctx.docs ?? [])),
     section("linear-context", assignment.promptContext),
     section("guidance", guidance),
     section("conversation", conversation(assignment)),
@@ -6908,11 +6974,29 @@ class Turn {
     const conn = this.conn;
     const sessionId = this.acpSessionId;
     let templateText = null;
-    if (this.role?.prompt_file) {
-      try {
-        templateText = readFileSync7(this.role.prompt_file, "utf8");
-      } catch (error) {
-        throw new TurnFailure(`Runner ${ctx.runnerName} cannot read its ${ctx.assignment.role} prompt file: ${errorMessage(error)}`);
+    let templateUrl = null;
+    const docs = [];
+    if (!this.resumed) {
+      const promptFile = this.role?.prompt_file;
+      if (promptFile && isRemoteSource(promptFile))
+        templateUrl = promptFile;
+      else if (promptFile) {
+        try {
+          templateText = readFileSync7(promptFile, "utf8");
+        } catch (error) {
+          throw new TurnFailure(`Runner ${ctx.runnerName} cannot read its ${ctx.assignment.role} prompt file: ${errorMessage(error)}`);
+        }
+      }
+      for (const doc of this.role?.docs ?? []) {
+        if (isRemoteSource(doc)) {
+          docs.push({ source: doc, text: null });
+          continue;
+        }
+        try {
+          docs.push({ source: tildify(doc), text: readFileSync7(doc, "utf8") });
+        } catch (error) {
+          throw new TurnFailure(`Runner ${ctx.runnerName} cannot read a ${ctx.assignment.role} doc: ${errorMessage(error)}`);
+        }
       }
     }
     const blocks = buildPrompt(ctx.assignment, this.role, {
@@ -6922,6 +7006,8 @@ class Turn {
       runnerName: ctx.runnerName,
       resumed: this.resumed,
       templateText,
+      templateUrl,
+      docs,
       readOnly: this.workspace?.mode === "readonly"
     }, (name) => ctx.log.warn(`the prompt template uses an unknown variable {{${name}}}; it rendered empty`));
     this.promptStartedAt = this.now();
@@ -6976,11 +7062,10 @@ class Turn {
     return stop === "end_turn" ? this.result("completed") : this.result("failed", `stopReason: ${stop}`);
   }
   repositoryName() {
+    if (this.workspace?.repository)
+      return this.workspace.repository.name;
     const remote = this.ctx.assignment.repository?.remote;
-    if (!remote)
-      return null;
-    const repo = this.ctx.config.repositories.find((r) => r.remote && r.remote.includes(remote));
-    return repo ? repositoryName(repo) : remote.split("/").pop() ?? null;
+    return remote ? remote.split("/").pop() ?? null : null;
   }
   async stopped() {
     const reason = this.endReason ?? "stop";
@@ -7946,7 +8031,7 @@ class StateDb {
 
 // src/daemon/supervisor.ts
 import { hostname as hostname3 } from "os";
-import { isAbsolute as isAbsolute7 } from "path";
+import { isAbsolute as isAbsolute8 } from "path";
 
 // src/telemetry/collector.ts
 var SCOPE = { name: "hypotenuse.daemon", version: package_default.version };
@@ -8514,7 +8599,7 @@ function resolvedConfigSecrets(config, env) {
 
 // src/worktree/cleanup.ts
 import { existsSync as existsSync15, readdirSync, rmSync as rmSync7 } from "fs";
-import { join as join9, relative as relative4, resolve as resolve3 } from "path";
+import { join as join9, relative as relative5, resolve as resolve4 } from "path";
 
 // src/worktree/merge-state.ts
 var MERGE_STATE_TTL_MS = 10 * 60000;
@@ -8677,7 +8762,7 @@ class WorktreeCleaner {
     return result.stdout.trim() !== "";
   }
   async adopt() {
-    const root = resolve3(this.config().sessions.worktree_root);
+    const root = resolve4(this.config().sessions.worktree_root);
     const known = new Set(this.state.worktrees({ live: true }).map((w) => w.path));
     let adopted = 0;
     for (const repo of this.options.repositories?.() ?? []) {
@@ -8693,7 +8778,7 @@ class WorktreeCleaner {
         const branch = /^branch refs\/heads\/(.+)$/m.exec(block)?.[1];
         if (!path || !branch || known.has(path))
           continue;
-        const rel = relative4(root, path);
+        const rel = relative5(root, path);
         if (rel.startsWith("..") || rel === "")
           continue;
         const session = await this.git(["config", "--worktree", "--get", "hypotenuse.session"], { cwd: path });
@@ -10452,7 +10537,7 @@ function changedKeys(a, b, prefix = "") {
   return JSON.stringify(a) === JSON.stringify(b) ? [] : [prefix];
 }
 function resolveCommand(command, env) {
-  if (isAbsolute7(command))
+  if (isAbsolute8(command))
     return command;
   return Bun.which(command, { PATH: env.PATH ?? "" }) ?? command;
 }
@@ -11455,11 +11540,12 @@ function registerCheckUpdateCommand(program) {
 // src/commands/config.ts
 import { existsSync as existsSync18, mkdirSync as mkdirSync11, writeFileSync as writeFileSync6 } from "fs";
 import { hostname as hostname5 } from "os";
-import { dirname as dirname11, resolve as resolve4 } from "path";
+import { dirname as dirname11, resolve as resolve5 } from "path";
 
 // src/config/template.toml
 var template_default = `#:schema https://www.hypotenuse.cloud/schemas/config-v1.json
-# The hypotenuse daemon's config. Every key: https://www.hypotenuse.cloud/docs/config
+# The hypotenuse daemon's config. Only what has no default is set; the rest is read from git and
+# your sign-in. Every key: https://www.hypotenuse.cloud/docs/config
 # Check it with \`hypotenuse config validate\`; apply edits with \`hypotenuse daemon reload\`.
 config_version = 1
 
@@ -11476,8 +11562,9 @@ roles = ["manager", "worker"]    # drop "manager" to only implement issues
 # teams = ["ENG"]                # only these Linear teams (empty: every team)
 # labels = ["frontend"]          # an issue needs one of these labels
 
-[agents.{{agent}}]
-preset = "{{agent}}"
+# Only to change how an agent is launched; a role can name a preset directly.
+# [agents.{{agent}}]
+# preset = "{{agent}}"
 # max_parallel = 2               # jobs using this agent at once
 
 [roles.worker]
@@ -11500,7 +11587,7 @@ agent = "{{agent}}"
 # keepalive_interval = "10m"     # must stay under Linear's 30m stale window
 
 [log]
-level = "info"
+# level = "info"
 `;
 
 // src/commands/config.ts
@@ -11515,41 +11602,31 @@ function detectPreset(machine) {
   }
   return "claude";
 }
-function repositoryBlocks(machine, paths, env) {
+function repositoryBlocks(paths, env) {
+  const overrides = [
+    '# base_branch = "develop"           # default: the branch origin/HEAD names',
+    '# setup = ["bun install --frozen-lockfile"]'
+  ];
   if (paths.length === 0) {
     return [
-      "# One table per repository this runner works in (`config init --repo <path>` fills these in):",
+      "# One table per git clone this runner works in (`config init --repo <path>` fills these in):",
       "# [[repositories]]",
-      '# name = "web"',
       '# path = "~/code/web"',
-      '# remote = "github.com/acme/web"',
-      '# base_branch = "main"',
-      '# setup = ["bun install --frozen-lockfile"]'
+      ...overrides
     ].join(`
 `);
   }
-  return paths.map((path) => {
-    const remote = originOf(machine, path);
-    const name = repositoryName({
-      path,
-      remote: remote ?? undefined
-    });
-    const base = originHead(machine, path) ?? "main";
-    return [
-      "[[repositories]]",
-      `name = ${JSON.stringify(name)}`,
-      `path = ${JSON.stringify(tildify(path, env))}`,
-      remote ? `remote = ${JSON.stringify(remote)}` : "# remote = (no origin remote found)",
-      `base_branch = ${JSON.stringify(base)}`,
-      "# setup = []"
-    ].join(`
-`);
-  }).join(`
+  return paths.map((path) => [
+    "[[repositories]]",
+    `path = ${JSON.stringify(tildify(path, env))}`,
+    ...overrides
+  ].join(`
+`)).join(`
 
 `);
 }
 function renderTemplate2(input) {
-  return template_default.replaceAll("{{server}}", input.server ? `url = ${JSON.stringify(input.server)}` : '# url = "https://api.hypotenuse.cloud"').replaceAll("{{hostname}}", hostname5().replace(/\.local$/i, "")).replaceAll("{{jobs}}", String(defaultMaxParallelJobs(input.cpus))).replaceAll("{{agent}}", input.agent).replaceAll("{{repositories}}", input.repositories);
+  return template_default.replaceAll("{{server}}", `# url = ${JSON.stringify(input.server ?? "https://api.hypotenuse.cloud")}   # default: where this machine's runner is registered`).replaceAll("{{hostname}}", hostname5().replace(/\.local$/i, "")).replaceAll("{{jobs}}", String(defaultMaxParallelJobs(input.cpus))).replaceAll("{{agent}}", input.agent).replaceAll("{{repositories}}", input.repositories);
 }
 async function validateFile(ctx, options) {
   const path = ctx.configPath;
@@ -11624,10 +11701,10 @@ function registerConfigCommands(program) {
       const text = renderTemplate2({
         server,
         agent: detectPreset(machine),
-        repositories: repositoryBlocks(machine, repos, ctx.env),
+        repositories: repositoryBlocks(repos, ctx.env),
         cpus: navigator.hardwareConcurrency || 1
       });
-      mkdirSync11(dirname11(resolve4(path)), { recursive: true, mode: 448 });
+      mkdirSync11(dirname11(resolve5(path)), { recursive: true, mode: 448 });
       writeFileSync6(path, text);
       if (!ctx.json)
         console.log(`Wrote ${tildify(path, ctx.env)}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcadeai/hypotenuse",
-  "version": "0.16.1",
+  "version": "0.19.0",
   "description": "Hypotenuse — run coding agents on your machine for Linear agent sessions",
   "type": "module",
   "license": "Apache-2.0",