loreli 1.0.0 → 2.0.0

package/packages/tmux/src/index.js

@@ -1,8 +1,19 @@
 import { execFile as execFileCb, execFileSync } from 'node:child_process';
+import { writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
 import { promisify } from 'node:util';
 
 const execFile = promisify(execFileCb);
 
+/**
+ * Pattern for safe tmux session names — alphanumeric, hyphens, and underscores only.
+ * Prevents shell injection and tmux command-line metacharacter issues.
+ * @type {RegExp}
+ */
+const SAFE_SESSION_NAME = /^[a-zA-Z0-9_-]+$/;
+
 /**
  * Clean, modern, ESM Node.js wrapper for tmux with pane-level control.
  *
@@ -85,6 +96,9 @@ export class Tmux {
    * @throws {Error} When a session with the same name already exists.
    */
   async create(name, opts = {}) {
+    if (!SAFE_SESSION_NAME.test(name))
+      throw new Error(`Invalid session name "${name}": must match ${SAFE_SESSION_NAME}`);
+
     if (await this.has(name)) {
       throw new Error(`Session "${name}" already exists`);
     }
@@ -98,7 +112,13 @@ export class Tmux {
       args.push('-P', '-F', '#{pane_id}');
       if (opts.cwd) args.push('-c', opts.cwd);
       args.push(opts.command);
-      const paneId = await this.#exec(args);
+      let paneId;
+      try {
+        paneId = await this.#exec(args);
+      } catch (err) {
+        try { await this.#exec(['kill-session', '-t', name]); } catch { /* best-effort */ }
+        throw err;
+      }
       this.#sessions.add(name);
       return paneId;
     }
@@ -295,24 +315,49 @@ export class Tmux {
     return this.#exec(args);
   }
 
+  /**
+   * Maximum length for direct send-keys. Longer text uses load-buffer
+   * to avoid terminal truncation.
+   * @type {number}
+   */
+  static SEND_MAX = 200;
+
   /**
    * Send text to a pane followed by Enter.
    *
+   * Clears any partial input first with C-u, then delivers the text.
+   * For short single-line text, uses `send-keys -l` (literal mode) so
+   * strings like "Enter" or "Space" are not interpreted as key names.
+   * For long or multiline text, writes to a temp file and uses
+   * `load-buffer` / `paste-buffer` to avoid terminal truncation.
+   *
    * Text and Enter are sent as separate operations with a brief delay.
-   * TUI applications (Claude Code, Cursor Agent) run in raw TTY mode
-   * and process keystrokes via an async event loop. When send-keys
-   * delivers text + Enter in a single call, both arrive in one PTY
-   * read buffer. The TUI's event loop processes them in a single tick,
-   * causing Enter to be consumed by the text rendering pipeline instead
-   * of triggering "submit". Splitting into two calls guarantees Enter
-   * arrives in a separate stdin data event.
+   * TUI applications process keystrokes asynchronously — splitting
+   * guarantees Enter arrives in a separate stdin data event.
    *
    * @param {string} target - Pane ID or session:window.pane target.
    * @param {string} text - The text to send.
    * @returns {Promise<void>}
    */
   async send(target, text) {
-    await this.#exec(['send-keys', '-t', target, text]);
+    await this.#exec(['send-keys', '-t', target, 'C-u']);
+
+    if (text.includes('\n') || text.length > Tmux.SEND_MAX) {
+      const id = randomUUID().slice(0, 8);
+      const bufName = `loreli-${id}`;
+      const tmpPath = join(tmpdir(), `loreli-send-${id}.txt`);
+      writeFileSync(tmpPath, text, { encoding: 'utf-8', mode: 0o600 });
+      try {
+        await this.#exec(['load-buffer', '-b', bufName, tmpPath]);
+        await this.#exec(['paste-buffer', '-b', bufName, '-t', target, '-d']);
+      } finally {
+        try { unlinkSync(tmpPath); } catch { /* may already be removed */ }
+        try { await this.#exec(['delete-buffer', '-b', bufName]); } catch { /* may already be deleted */ }
+      }
+    } else {
+      await this.#exec(['send-keys', '-l', '-t', target, text]);
+    }
+
     await new Promise(function settle(r) { setTimeout(r, 200); });
     await this.#exec(['send-keys', '-t', target, 'Enter']);
   }
@@ -342,9 +387,13 @@ export class Tmux {
    * @returns {Promise<string>} The captured pane content.
    */
   async capture(target, lines = 500) {
-    return this.#exec([
-      'capture-pane', '-p', '-J', '-t', target, '-S', `-${lines}`
-    ]);
+    try {
+      return await this.#exec([
+        'capture-pane', '-p', '-J', '-t', target, '-S', `-${lines}`
+      ]);
+    } catch {
+      return '';
+    }
   }
 
   /**

package/packages/workflow/README.md

@@ -104,9 +104,9 @@ Create and spawn a new agent via the orchestrator's factory. Convenience wrapper
 
 #### `workflow.custom(opts?)` → Promise\<string\>
 
-Load the project-specific custom prompt from the `prompts.{role}` config key (e.g. `prompts.action`, `prompts.reviewer`, `prompts.planner`, `prompts.risk`). By default, resolves this workflow's `static role`; pass `opts.role` to resolve another role during cross-role rendering. Reads each role-specific file once from the target repo via the hub and caches it on the instance. Returns an empty string when:
+Load the project-specific custom prompt from the `workflows.{role}.prompt` config key (e.g. `workflows.action.prompt`, `workflows.reviewer.prompt`, `workflows.planner.prompt`, `workflows.risk.prompt`). By default, resolves this workflow's `static role`; pass `opts.role` to resolve another role during cross-role rendering. Reads each role-specific file once from the target repo via the hub and caches it on the instance. Returns an empty string when:
 
-- `prompts.{role}` is not configured for this workflow's role
+- `workflows.{role}.prompt` is not configured for this workflow's role
 - The hub is unavailable (e.g. unit tests)
 - The repo is not set on the orchestrator
 - The file cannot be read (missing or inaccessible)
@@ -115,13 +115,13 @@ Rendering never fails due to a missing custom prompt — this method degrades si
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `opts.role` | `string` | Optional role override for `prompts.{role}` lookup |
+| `opts.role` | `string` | Optional role override for `workflows.{role}.prompt` lookup |
 
 **Returns**: `Promise<string>` — Custom prompt text, or empty string.
 
 #### `workflow.render(vars)` → Promise\<string\>
 
-Load and render this workflow's prompt template with Mustache variables. Automatically prepends the shared autonomous-mode preamble and any per-role custom prompt from `prompts.{role}` (see [Autonomous Preamble](#autonomous-preamble) and [Custom Prompt Extensions](#custom-prompt-extensions) below).
+Load and render this workflow's prompt template with Mustache variables. Automatically prepends the shared autonomous-mode preamble and any per-role custom prompt from `workflows.{role}.prompt` (see [Autonomous Preamble](#autonomous-preamble) and [Custom Prompt Extensions](#custom-prompt-extensions) below).
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -137,7 +137,7 @@ Load and render an arbitrary Mustache template. Used for cross-role rendering (e
 |-----------|------|-------------|
 | `path` | `string` | Absolute path to a `.md` template file |
 | `vars` | `object` | Template variables |
-| `opts.role` | `string` | Optional role override for custom prompt lookup. When set, resolves `prompts.{opts.role}` instead of this workflow's `static role` |
+| `opts.role` | `string` | Optional role override for custom prompt lookup. When set, resolves `workflows.{opts.role}.prompt` instead of this workflow's `static role` |
 
 **Returns**: `Promise<string>` — Rendered prompt text with preamble and custom prompt prepended.
 
@@ -274,24 +274,28 @@ The preamble is loaded once and cached for the lifetime of the process.
 
 ## Custom Prompt Extensions
 
-Projects can inject per-role custom instructions into agent prompts by setting `prompts.{role}` in `loreli.yml`. Each key maps to a workflow role and the value is a file path relative to the repository root.
+Projects can inject per-role custom instructions into agent prompts by setting `workflows.{role}.prompt` in `loreli.yml`. Each role maps to a workflow and the value is a file path relative to the repository root.
 
 ```yaml
 # loreli.yml
-prompts:
-  action: .loreli/action.md
-  reviewer: .loreli/review.md
-  planner: .loreli/planner.md
-  risk: .loreli/risk.md
+workflows:
+  action:
+    prompt: .loreli/action.md
+  reviewer:
+    prompt: .loreli/review.md
+  planner:
+    prompt: .loreli/planner.md
+  risk:
+    prompt: .loreli/risk.md
 ```
 
-When configured, `render()` and `renderFrom()` resolve `prompts.{this.constructor.role}` from config, read the file from the target repo via the hub, and insert its content between the autonomous preamble and the role-specific template:
+When configured, `render()` and `renderFrom()` resolve `workflows.{role}.prompt` from config, read the file from the target repo via the hub, and insert its content between the autonomous preamble and the role-specific template:
 
 1. **Autonomous preamble** (`prompts/preamble.md`) — always present
-2. **Custom prompt** (`prompts.{role}`) — when configured for the current role
+2. **Custom prompt** (`workflows.{role}.prompt`) — when configured for the current role
 3. **Role template** (action/planner/reviewer `.md` file)
 
-Each role resolves independently — an action workflow only reads `prompts.action`, a reviewer only reads `prompts.reviewer`. Roles without a configured prompt file are unaffected.
+Each role resolves independently — an action workflow only reads `workflows.action.prompt`, a reviewer only reads `workflows.reviewer.prompt`. Roles without a configured prompt file are unaffected.
 
 The file is read once on the first `render()` call and cached on the `Workflow` instance for the remainder of the session. If the file is missing or unreadable, rendering continues normally — agents are never blocked by a missing custom prompt.
 

package/packages/workflow/prompts/preamble.md

@@ -0,0 +1,14 @@
+<autonomous>
+
+You are running autonomously in a headless tmux pane with no human operator. There is no user to respond to questions.
+
+- **Never ask** clarifying questions, present multiple-choice options, or wait for user input.
+- **Never invoke** interactive skills (brainstorming, design reviews, or anything that requires human approval gates).
+- **Always proceed** with your best judgment. When multiple approaches exist, pick the most reasonable default and document your reasoning.
+- If a skill or workflow would normally require user confirmation, skip it entirely and proceed directly to your task.
+- Before planning or coding, explicitly check whether `AGENTS.md` exists at the repository root. If it exists, read it and treat it as normative repository policy for this task.
+- `AGENTS.md` policy takes precedence over generic defaults for repository-specific behavior. Follow it without waiting for confirmation.
+
+Violations of these rules will permanently stall your session.
+
+</autonomous>

package/packages/workflow/src/index.js

@@ -3,6 +3,9 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Mustache from 'mustache';
 import { mark, has, parse } from 'loreli/marker';
+import { Tmux } from 'loreli/tmux';
+import { classify } from 'loreli/classify';
+import { logger } from 'loreli/log';
 
 export { responder } from './proof-of-life.js';
 
@@ -16,10 +19,25 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  * @type {string}
  */
 const PREAMBLE = join(__dirname, '..', 'prompts', 'preamble.md');
+const log = logger('workflow');
 
 /** @type {string|null} Cached preamble text — loaded once, reused. */
 let _preamble = null;
 
+/**
+ * Maximum backend-diagnose checks after prompt dispatch.
+ *
+ * @type {number}
+ */
+const DISPATCH_NUDGE_CHECKS = 48;
+
+/**
+ * Delay between post-dispatch diagnose checks.
+ *
+ * @type {number}
+ */
+const DISPATCH_NUDGE_INTERVAL = 5000;
+
 /**
  * Load the shared preamble, caching after the first read.
  *
@@ -30,6 +48,100 @@ async function preamble() {
   return _preamble;
 }
 
+/**
+ * Wait for the specified duration.
+ *
+ * @param {number} ms - Milliseconds to sleep.
+ * @returns {Promise<void>}
+ */
+async function sleep(ms) {
+  await new Promise(function onTimer(resolve) {
+    const handle = setTimeout(resolve, ms);
+    handle?.unref?.();
+  });
+}
+
+/**
+ * Normalize remedy values into tmux key sequences.
+ *
+ * Classifier output may provide remedy as a single space-delimited string,
+ * while backend fallback diagnosers usually return string arrays.
+ *
+ * @param {string|string[]|null|undefined} remedy - Remedy value from diagnosis.
+ * @returns {string[]} Keys to send through tmux.
+ */
+function keys(remedy) {
+  if (Array.isArray(remedy)) {
+    const list = remedy.filter(Boolean);
+    if (list.length > 0) return list;
+    return ['Enter'];
+  }
+
+  if (typeof remedy === 'string') {
+    const list = remedy.split(/\s+/).filter(Boolean);
+    if (list.length > 0) return list;
+    return ['Enter'];
+  }
+
+  return ['Enter'];
+}
+
+/**
+ * Return whether a diagnosis category requires immediate remediation.
+ *
+ * @param {string|undefined} category - Diagnosis category.
+ * @returns {boolean} True when remediation should be applied immediately.
+ */
+function actionable(category) {
+  return category === 'option_dialog'
+    || category === 'waiting_for_input'
+    || category === 'fatal'
+    || category === 'dead';
+}
+
+/**
+ * Run pane classification through loreli/classify.
+ *
+ * This is best-effort: classification errors should not block dispatch
+ * nudging because backend regex diagnosis can still recover option dialogs.
+ *
+ * @param {object} orchestrator - Orchestrator instance containing config/backends.
+ * @param {object} agent - Agent metadata.
+ * @param {string} pane - Captured pane output.
+ * @returns {Promise<object|null>} Classifier diagnosis, or null when unavailable/failed.
+ */
+async function diagnose(orchestrator, agent, pane) {
+  const backends = orchestrator?.backendRegistry;
+  if (!backends?.oneshot) return null;
+
+  try {
+    const result = await classify('pane-state', pane, {
+      backends,
+      config: orchestrator?.cfg,
+      vars: { model: agent.model, backend: agent.backend, role: agent.role }
+    });
+
+    if (result?.category === 'option_dialog') {
+      log.info(
+        `dispatch nudge classify: ${agent.identity?.name ?? 'unknown'} ${agent.backend} `
+        + `${result.category} — ${result.reasoning}`
+      );
+    }
+
+    return result;
+  } catch (err) {
+    log.debug(`dispatch nudge classify failed for ${agent.identity?.name ?? 'unknown'}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Swallow background nudge errors.
+ *
+ * @returns {void}
+ */
+function ignoreNudgeError() {}
+
 /**
  * Abstract base class for role-specific workflow packages.
  *
@@ -138,22 +250,21 @@ export class Workflow {
   /**
    * Load the project-specific custom prompt for this workflow's role.
    *
-   * Resolves `prompts.{role}` from config (e.g. `prompts.action`,
-   * `prompts.reviewer`, `prompts.planner`), reads the file once from
-   * the target repo via the hub, and caches the result on this
-   * instance. Returns an empty string when the config key is unset,
-   * the hub is unavailable, or the file cannot be read — prompt
-   * rendering never fails due to a missing custom prompt.
+   * Resolves `workflows.{role}.prompt` from config, reads the file
+   * once from the target repo via the hub, and caches the result on
+   * this instance. Returns an empty string when the config key is
+   * unset, the hub is unavailable, or the file cannot be read —
+   * prompt rendering never fails due to a missing custom prompt.
    *
    * @param {object} [opts] - Options.
-   * @param {string} [opts.role] - Role to resolve `prompts.{role}` for.
+   * @param {string} [opts.role] - Role to resolve prompt for.
    * @returns {Promise<string>} Custom prompt text, or empty string.
    */
   async custom(opts = {}) {
     const role = opts.role ?? this.constructor.role;
     if (this._custom.has(role)) return this._custom.get(role) ?? '';
 
-    const path = this.orchestrator.cfg?.get?.(`prompts.${role}`);
+    const path = this.orchestrator.cfg?.get?.(`workflows.${role}.prompt`);
     if (!path || !this.hub?.read || !this.orchestrator.repo) {
       this._custom.set(role, null);
       return '';
@@ -175,8 +286,8 @@ export class Workflow {
    * Automatically injects the workflow's `role` into the template
    * variables so subclasses don't need to pass it explicitly.
    * Prepends the shared autonomous-mode preamble and any project-
-   * specific custom prompt from `prompts.{role}` so every agent
-   * prompt carries the headless operation directive and project rules.
+   * specific custom prompt from `workflows.{role}.prompt` so every
+   * agent prompt carries the headless operation directive and project rules.
    *
    * @param {object} vars - Mustache template variables.
    * @returns {Promise<string>} Rendered prompt text.
@@ -198,12 +309,12 @@ export class Workflow {
    * Used for cross-role rendering where one workflow needs another
    * role's prompt (e.g. review rendering the action prompt for forward).
    * Prepends the shared autonomous-mode preamble and any project-
-   * specific custom prompt from `prompts.{role}`.
+   * specific custom prompt from `workflows.{role}.prompt`.
    *
    * @param {string} path - Absolute path to a .md template file.
    * @param {object} vars - Mustache template variables.
    * @param {object} [opts] - Options.
-   * @param {string} [opts.role] - Role to resolve `prompts.{role}` for.
+   * @param {string} [opts.role] - Role to resolve prompt for.
    * @returns {Promise<string>} Rendered prompt text.
    */
   async renderFrom(path, vars, opts = {}) {
@@ -253,6 +364,74 @@ export class Workflow {
   async dispatch(agent, vars) {
     const prompt = await this.render(vars);
     await agent.send(prompt);
+    this.nudge(agent).catch(ignoreNudgeError);
+  }
+
+  /**
+   * Nudge known CLI option dialogs after prompt dispatch.
+   *
+   * Some backends surface interactive confirmation dialogs seconds
+   * after a prompt is submitted (for example MCP tool approvals).
+   * This helper polls pane output and applies backend-provided
+   * dialog remedies so workflows remain unattended.
+   *
+   * @param {object} agent - Target agent with backend/pane metadata.
+   * @returns {Promise<void>}
+   */
+  async nudge(agent) {
+    if (!agent?.backend || !agent?.paneId || !agent?.capture) return;
+
+    const registry = this.orchestrator?.backendRegistry;
+    if (!registry?.diagnose) return;
+
+    for (let i = 0; i < DISPATCH_NUDGE_CHECKS; i++) {
+      if (agent.state === 'dormant') return;
+
+      let pane;
+      try {
+        pane = await agent.capture(this.orchestrator?.cfg?.get?.('classify.maxLines') ?? 100);
+      } catch {
+        return;
+      }
+
+      const llm = await diagnose(this.orchestrator, agent, pane);
+      const fallback = registry.diagnose(agent.backend, pane);
+
+      let result = llm;
+      if (!result?.category && fallback?.category) {
+        result = fallback;
+        log.info(
+          `dispatch nudge fallback diagnose: ${agent.identity?.name ?? 'unknown'} ${agent.backend} `
+          + `${fallback.category} — ${fallback.reasoning}`
+        );
+      } else if (actionable(fallback?.category) && !actionable(result?.category)) {
+        result = fallback;
+        log.info(
+          `dispatch nudge fallback override: ${agent.identity?.name ?? 'unknown'} ${agent.backend} `
+          + `${fallback.category} over ${llm?.category ?? 'unknown'} — ${fallback.reasoning}`
+        );
+      }
+
+      if (result?.category === 'option_dialog') {
+        const seq = keys(result.remedy);
+        log.info(`dispatch nudge: ${agent.identity?.name ?? 'unknown'} ${agent.backend} option_dialog — sending ${seq.join('+')}`);
+        try {
+          const tmux = new Tmux();
+          await tmux.keys(agent.paneId, ...seq);
+        } catch {
+          log.debug(`dispatch nudge: keys failed for ${agent.identity?.name ?? 'unknown'}`);
+          return;
+        }
+        this.orchestrator.activity?.(agent.identity?.name);
+
+        if (i < DISPATCH_NUDGE_CHECKS - 1)
+          await sleep(DISPATCH_NUDGE_INTERVAL);
+        continue;
+      }
+
+      if (i < DISPATCH_NUDGE_CHECKS - 1)
+        await sleep(DISPATCH_NUDGE_INTERVAL);
+    }
   }
 
   // ── Proof of Life ───────────────────────────────────

package/packages/workspace/README.md

@@ -18,11 +18,11 @@ This package prepares agent directories, scaffolds local MCP configs and safety
 
 #### `codexToml(context?)` → `string`
 
-Generate Codex TOML config content with optional agent context env keys.
+Generate Codex TOML config content with `env_vars = ["GITHUB_TOKEN"]` forwarding and optional agent context env keys.
 
 #### `mcpJson(context?, opts?)` → `string`
 
-Generate JSON MCP config content with optional agent context, token reference (`tokenRef`), and env file path (`envFile`).
+Generate JSON MCP config content with optional agent context, token reference (`tokenRef`), and env file path (`envFile`). Cursor scaffolding keeps both interpolation and envFile fallback for token propagation.
 
 ### Security/Hook Generators
 

package/packages/workspace/src/index.js

@@ -4,7 +4,45 @@ import { homedir } from 'node:os';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
-const run = promisify(execFile);
+const exec = promisify(execFile);
+
+/**
+ * Timeout for git network operations (fetch, clone, push) in ms.
+ * Prevents hung network connections from blocking the orchestrator.
+ * @type {number}
+ */
+const GIT_TIMEOUT = 30_000;
+
+/**
+ * Run a child process with an optional timeout.
+ *
+ * @param {string} cmd - Command to execute.
+ * @param {string[]} args - Arguments.
+ * @param {object} [opts] - execFile options.
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+function run(cmd, args, opts = {}) {
+  return exec(cmd, args, opts);
+}
+
+/**
+ * Pattern for safe path segments — alphanumeric, hyphens, and underscores only.
+ * Prevents path traversal, tmux injection, and shell metacharacter issues.
+ * @type {RegExp}
+ */
+const SAFE_NAME = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Validate that a name is safe for use in file paths and tmux session IDs.
+ *
+ * @param {string} value - The name to validate.
+ * @param {string} label - Human-readable label for error messages.
+ * @throws {Error} When the value contains unsafe characters.
+ */
+function assertSafe(value, label) {
+  if (!SAFE_NAME.test(value))
+    throw new Error(`Invalid ${label} "${value}": must match ${SAFE_NAME}`);
+}
 
 /**
  * Default root directory for agent workspaces.
@@ -38,7 +76,13 @@ export const MCP_JSON = JSON.stringify({
  * MCP config for TOML-based CLI tools (Codex).
  * @type {string}
  */
-export const CODEX_TOML = '[mcp_servers.loreli]\ncommand = "npx"\nargs = ["loreli", "mcp"]\n';
+export const CODEX_TOML = [
+  '[mcp_servers.loreli]',
+  'command = "npx"',
+  'args = ["loreli", "mcp"]',
+  'env_vars = ["GITHUB_TOKEN"]',
+  ''
+].join('\n');
 
 /**
  * Build Codex TOML config, optionally injecting agent context env vars.
@@ -50,13 +94,10 @@ export const CODEX_TOML = '[mcp_servers.loreli]\ncommand = "npx"\nargs = ["lorel
  * @returns {string} TOML string for .codex/config.toml.
  */
 export function codexToml(context) {
-  let toml = '[mcp_servers.loreli]\ncommand = "npx"\nargs = ["loreli", "mcp"]\n';
+  let toml = CODEX_TOML;
   if (context?.session) {
     toml += `\n[mcp_servers.loreli.env]\nLORELI_SESSION = "${context.session}"\nLORELI_AGENT = "${context.agent}"\nLORELI_REPO = "${context.repo}"\n`;
     if (context.home) toml += `LORELI_HOME = "${context.home}"\n`;
-    // Codex env_vars whitelists parent process env vars for forwarding
-    // to the MCP subprocess — no literal secret in the file.
-    toml += 'env_vars = ["GITHUB_TOKEN"]\n';
   }
   return toml;
 }
@@ -314,12 +355,19 @@ export async function mirror(url, opts = {}) {
     authUrl = parsed.toString();
   }
 
+  const gitEnv = { env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, timeout: GIT_TIMEOUT };
+
+  let exists = false;
   try {
     await access(dir);
-    await run('git', ['-C', dir, 'fetch', '--prune'], { env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
-  } catch {
+    exists = true;
+  } catch { /* directory doesn't exist */ }
+
+  if (exists) {
+    await run('git', ['-C', dir, 'fetch', '--prune'], gitEnv);
+  } else {
     await mkdir(reposDir, { recursive: true });
-    await run('git', ['clone', '--bare', authUrl, dir], { env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+    await run('git', ['clone', '--bare', authUrl, dir], gitEnv);
   }
 
   return dir;
@@ -337,6 +385,7 @@ export async function mirror(url, opts = {}) {
  * @returns {string} Absolute path to the agent's workspace.
  */
 export function pathFor(name, root = DEFAULT_ROOT) {
+  assertSafe(name, 'agent name');
   return join(root, `loreli-${name}`);
 }
 
@@ -359,10 +408,10 @@ export function pathFor(name, root = DEFAULT_ROOT) {
  *   - Cursor IDE:  `${env:GITHUB_TOKEN}`
  *   The file only contains a reference — never the literal secret.
  * @param {string} [opts.envFile] - Path to a `.env` file that the
- *   MCP host loads at spawn time. Used for cursor-agent which does
- *   not support `${env:NAME}` interpolation. The secret lives in
- *   the referenced file (inside `.git/`, unstageable), not in the
- *   JSON config itself.
+ *   MCP host loads at spawn time. Used as a fallback for Cursor
+ *   startup paths where interpolation may not be available. The
+ *   secret lives in the referenced file (inside `.git/`,
+ *   unstageable), not in the JSON config itself.
  * @returns {string} JSON string for .mcp.json files.
  */
 export function mcpJson(context, { tokenRef, envFile } = {}) {
@@ -432,7 +481,9 @@ function legacyDescriptors(context) {
     {
       configs: [{
         path: '.cursor/mcp.json',
-        content: mcpJson(context, context ? { envFile: '.git/loreli.env' } : {}),
+        content: mcpJson(context, context ? {
+          envFile: '.git/loreli.env'
+        } : {}),
         marker: 'loreli',
         format: 'json'
       }],
@@ -669,7 +720,7 @@ export async function create(repo, branch, name, root = DEFAULT_ROOT, context, d
   const cloneArgs = ['clone', '--single-branch'];
   if (branch && branch !== 'HEAD') cloneArgs.push('--branch', branch);
   cloneArgs.push(repo, cwd);
-  await run('git', cloneArgs);
+  await run('git', cloneArgs, { timeout: GIT_TIMEOUT });
 
   // Create a named branch for the agent. A named branch lets agents
   // commit and push without extra setup — no "HEAD (no branch)" state.
@@ -871,7 +922,7 @@ export async function reset(cwd, name, issue, base = 'main', opts = {}) {
   // tracked branch. When merge.base differs (e.g. 'loreli'), the ref
   // won't exist locally without an explicit refspec.
   await run('git', ['-C', cwd, 'fetch', 'origin',
-    `+refs/heads/${base}:refs/remotes/origin/${base}`]);
+    `+refs/heads/${base}:refs/remotes/origin/${base}`], { timeout: GIT_TIMEOUT });
 
   // Discard any uncommitted changes from the previous run
   await run('git', ['-C', cwd, 'checkout', '--', '.']);
@@ -915,7 +966,7 @@ export async function reset(cwd, name, issue, base = 'main', opts = {}) {
 export async function checkout(cwd, branch, base = 'main', opts = {}) {
   await run('git', ['-C', cwd, 'fetch', 'origin',
     `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
-    `+refs/heads/${base}:refs/remotes/origin/${base}`]);
+    `+refs/heads/${base}:refs/remotes/origin/${base}`], { timeout: GIT_TIMEOUT });
   await run('git', ['-C', cwd, 'checkout', '--', '.']);
   try { await run('git', ['-C', cwd, 'clean', '-fd']); } catch { /* ok */ }
   await cleanScaffolding(cwd);
@@ -1018,7 +1069,7 @@ export async function commitAndPush(cwd, message) {
   // The caller decides whether push failure is fatal.
   let pushed = false;
   try {
-    await run('git', ['-C', cwd, 'push', '-u', 'origin', 'HEAD']);
+    await run('git', ['-C', cwd, 'push', '-u', 'origin', 'HEAD'], { timeout: GIT_TIMEOUT });
     pushed = true;
   } catch { /* push failure is non-fatal — caller may retry */ }