Deliver agent prompts reliably at launch

package.json

@@ -8,7 +8,7 @@
     "build:css": "tailwindcss -i ./src/tailwind.css -o ./public/styles.css --minify",
     "check": "tsc --noEmit && vitest run && npm run test:e2e && wrangler deploy --dry-run",
     "test": "vitest run",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts && vitest run --config vitest.agent-e2e.config.ts",
     "deploy": "wrangler deploy"
   },
   "dependencies": {
@@ -24,6 +24,7 @@
     "@cloudflare/workers-types": "^5.20260910.1",
     "@tailwindcss/cli": "^4.1.14",
     "@types/mustache": "^4.2.6",
+    "@types/node": "^26.5.1",
     "tailwindcss": "^4.1.14",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",

src/exe-herdr-backend.ts

@@ -8,7 +8,7 @@ export class ExeHerdrBackend implements ExecutionBackend {
   constructor(private readonly connection: ExeConnection) {}
 
   async launch(request: LaunchRequest) {
-    const command = await exec(this.connection, launchAgentCommand(request.agentName, this.connection, request.workspaceName, request.runPath, request.lease));
+    const command = await exec(this.connection, launchAgentCommand(request.agentName, this.connection, request.workspaceName, request.runPath, request.lease, request.prompt));
     return { handle: { backend: this.kind, agentName: request.agentName }, command };
   }
 

src/exe.ts

@@ -41,47 +41,60 @@ export function shellAtom(value: string): string {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 
-export function launchAgentCommand(agentName: string, connection: ExeConnection, workspaceName: string, runPath: string, lease: string): string {
+export function launchAgentCommand(agentName: string, connection: ExeConnection, workspaceName: string, runPath: string, lease: string, prompt: string): string {
   const name = agentName;
   const herdr = herdrBinary(connection);
+  const promptDirectory = `/tmp/factorize-prompts/${agentName}`;
+  const promptPath = `${promptDirectory}/prompt.md`;
+  const launchInstruction = `Read and follow the complete task instructions in ${promptPath}`;
   return [
     herdrPrefix(connection),
     `cd ${shellAtom(connection.cwd)}`,
     `mkdir -p ${shellAtom(`${connection.cwd.replace(/\/$/, "")}/.factorize-runs`)}`,
     `if [ ! -e ${shellAtom(runPath)} ]; then mkdir ${shellAtom(runPath)}; fi`,
     `test -d ${shellAtom(runPath)}`,
     `if [ -e ${shellAtom(`${runPath}/.factorize-lease`)} ]; then test "$(cat ${shellAtom(`${runPath}/.factorize-lease`)})" = ${shellAtom(lease)}; else printf '%s' ${shellAtom(lease)} > ${shellAtom(`${runPath}/.factorize-lease`)}; fi`,
+    `mkdir -p ${shellAtom(promptDirectory)}`,
+    `chmod 700 ${shellAtom(promptDirectory)}`,
+    `printf '%s' ${shellAtom(base64(prompt))} | base64 -d > ${shellAtom(promptPath)}`,
+    `chmod 600 ${shellAtom(promptPath)}`,
     `workspaces=$(${herdr} workspace list)`,
     `workspace_id=$(printf '%s' "$workspaces" | jq -r --arg label ${shellAtom(workspaceName)} '.result.workspaces[]? | select(.label == $label) | .workspace_id' | head -n1)`,
     `if [ -z "$workspace_id" ]; then created=$(${herdr} workspace create --cwd ${shellAtom(runPath)} --label ${shellAtom(workspaceName)} --no-focus) && workspace_id=$(printf '%s' "$created" | jq -er '.result.workspace.workspace_id') && tab_id=$(printf '%s' "$created" | jq -er '.result.tab.tab_id') && pane=$(printf '%s' "$created" | jq -er '.result.root_pane.pane_id') && ${herdr} tab rename "$tab_id" ${shellAtom(name)} >/dev/null; else tabs=$(${herdr} tab list --workspace "$workspace_id") && tab_id=$(printf '%s' "$tabs" | jq -r --arg label ${shellAtom(name)} '.result.tabs[]? | select(.label == $label) | .tab_id' | head -n1); if [ -z "$tab_id" ]; then created=$(${herdr} tab create --workspace "$workspace_id" --cwd ${shellAtom(runPath)} --label ${shellAtom(name)} --no-focus) && tab_id=$(printf '%s' "$created" | jq -er '.result.tab.tab_id') && pane=$(printf '%s' "$created" | jq -er '.result.root_pane.pane_id'); else panes=$(${herdr} pane list --workspace "$workspace_id") && pane=$(printf '%s' "$panes" | jq -r --arg tab "$tab_id" '.result.panes[]? | select(.tab_id == $tab) | .pane_id' | head -n1); test -n "$pane"; extras=$(printf '%s' "$panes" | jq -r --arg tab "$tab_id" --arg keep "$pane" '.result.panes[]? | select(.tab_id == $tab and .pane_id != $keep) | .pane_id'); for extra in $extras; do ${herdr} pane close "$extra" >/dev/null; done; fi; fi`,
     `existing=$(${herdr} agent get ${shellAtom(name)} 2>/dev/null || true)`,
-    `if [ -n "$existing" ]; then printf '%s\\n' "$existing"; else ${herdr} agent start ${shellAtom(name)} --kind ${shellAtom(connection.agentKind)} --pane "$pane"${agentCommand(connection)} && ${herdr} agent get ${shellAtom(name)}; fi`,
+    `if [ -n "$existing" ]; then printf '%s\\n' "$existing"; else ${herdr} agent start ${shellAtom(name)} --kind ${shellAtom(connection.agentKind)} --pane "$pane"${agentCommand(connection, launchInstruction, runPath)} && ${herdr} agent get ${shellAtom(name)}; fi`,
   ].join(" && ");
 }
 
 export function promptAgentCommand(connection: ExeConnection, agentName: string, prompt: string): string {
   const encodedPrompt = base64(prompt), herdr = herdrBinary(connection);
-  return `${herdrPrefix(connection)} && prompt=$(printf '%s' ${shellAtom(encodedPrompt)} | base64 -d) && ${herdr} agent prompt ${shellAtom(agentName)} "$prompt"`;
+  const name = shellAtom(agentName);
+  return [
+    herdrPrefix(connection),
+    `${herdr} agent wait ${name} --until idle --until done --timeout 15000 >/dev/null`,
+    `prompt=$(printf '%s' ${shellAtom(encodedPrompt)} | base64 -d)`,
+    `${herdr} agent prompt ${name} "$prompt" --wait --until working --until blocked --timeout 7000`,
+  ].join(" && ");
 }
 
 /** Compatibility helper used by recovery paths; prompt delivery is never skipped. */
 export function startAgentCommand(agentName: string, connection: ExeConnection, prompt: string, workspaceName: string, runPath: string, lease: string): string {
-  return `${launchAgentCommand(agentName, connection, workspaceName, runPath, lease)} && ${promptAgentCommand(connection, agentName, prompt)}`;
+  return launchAgentCommand(agentName, connection, workspaceName, runPath, lease, prompt);
 }
 
 export function agentListCommand(connection: ExeConnection): string { return `${herdrPrefix(connection)} && ${herdrBinary(connection)} agent list`; }
 export function paneGetCommand(connection: ExeConnection, paneId: string): string { return `${herdrPrefix(connection)} && ${herdrBinary(connection)} pane get ${shellAtom(paneId)}`; }
 export function paneProcessInfoCommand(connection: ExeConnection, paneId: string): string { return `${herdrPrefix(connection)} && ${herdrBinary(connection)} pane process-info --pane ${shellAtom(paneId)}`; }
 export function validateWorktreeLeaseCommand(connection: ExeConnection, runPath: string, lease: string): string { return `${herdrPrefix(connection)} && test -d ${shellAtom(runPath)} && test "$(cat ${shellAtom(`${runPath}/.factorize-lease`)})" = ${shellAtom(lease)}`; }
 export function renameAgentCommand(connection: ExeConnection, currentName: string, expectedName: string): string { return `${herdrPrefix(connection)} && ${herdrBinary(connection)} agent rename ${shellAtom(currentName)} ${shellAtom(expectedName)} && ${herdrBinary(connection)} agent get ${shellAtom(expectedName)}`; }
-export function startAgentInPaneCommand(agentName: string, connection: ExeConnection, paneId: string, cwd = connection.cwd): string { return `${herdrPrefix(connection)} && cd ${shellAtom(cwd)} && ${herdrBinary(connection)} agent start ${shellAtom(agentName)} --kind ${shellAtom(connection.agentKind)} --pane ${shellAtom(paneId)}${agentCommand(connection)} && ${herdrBinary(connection)} agent get ${shellAtom(agentName)}`; }
+export function startAgentInPaneCommand(agentName: string, connection: ExeConnection, paneId: string, cwd = connection.cwd): string { return `${herdrPrefix(connection)} && cd ${shellAtom(cwd)} && ${herdrBinary(connection)} agent start ${shellAtom(agentName)} --kind ${shellAtom(connection.agentKind)} --pane ${shellAtom(paneId)}${agentCommand(connection, undefined, cwd)} && ${herdrBinary(connection)} agent get ${shellAtom(agentName)}`; }
 
 /** Stop only the foreground process group observed in the exact persisted pane.
  * Every signal is preceded by a fresh identity read, preventing stale-PID races. */
 export function replaceForegroundCommand(agentName: string, connection: ExeConnection, paneId: string, cwd = connection.cwd): string {
   const herdr = herdrBinary(connection), pane = shellAtom(paneId);
   const fields = `jq -er --arg pane ${pane} --arg cwd ${shellAtom(cwd)} '[.result.pane_id // .pane_id // .result.pane.pane_id, .result.foreground.pid // .result.pid // .pid, .result.foreground.process_group // .result.foreground.pgid // .result.process_group // .result.pgid // .pgid, .result.foreground.cwd // .result.cwd // .cwd] | select(.[0] == $pane and .[1] > 1 and .[2] > 1 and .[3] == $cwd) | @tsv'`;
-  return [herdrPrefix(connection), `first=$(${herdr} pane process-info --pane ${pane} | ${fields})`, `first_pid=$(printf '%s' "$first" | cut -f2)`, `first_pgid=$(printf '%s' "$first" | cut -f3)`, `kill -INT -- "-$first_pgid"`, `i=0; while [ "$i" -lt 10 ] && kill -0 -- "-$first_pgid" 2>/dev/null; do i=$((i+1)); sleep 1; done`, `if kill -0 -- "-$first_pgid" 2>/dev/null; then second=$(${herdr} pane process-info --pane ${pane} | ${fields}) && second_pid=$(printf '%s' "$second" | cut -f2) && second_pgid=$(printf '%s' "$second" | cut -f3) && [ "$second_pid" = "$first_pid" ] && [ "$second_pgid" = "$first_pgid" ] && kill -TERM -- "-$first_pgid"; fi`, `i=0; while [ "$i" -lt 10 ] && kill -0 -- "-$first_pgid" 2>/dev/null; do i=$((i+1)); sleep 1; done`, `! kill -0 -- "-$first_pgid" 2>/dev/null`, `cd ${shellAtom(cwd)}`, `${herdr} agent start ${shellAtom(agentName)} --kind ${shellAtom(connection.agentKind)} --pane ${pane}${agentCommand(connection)}`, `${herdr} agent get ${shellAtom(agentName)}`].join(" && ");
+  return [herdrPrefix(connection), `first=$(${herdr} pane process-info --pane ${pane} | ${fields})`, `first_pid=$(printf '%s' "$first" | cut -f2)`, `first_pgid=$(printf '%s' "$first" | cut -f3)`, `kill -INT -- "-$first_pgid"`, `i=0; while [ "$i" -lt 10 ] && kill -0 -- "-$first_pgid" 2>/dev/null; do i=$((i+1)); sleep 1; done`, `if kill -0 -- "-$first_pgid" 2>/dev/null; then second=$(${herdr} pane process-info --pane ${pane} | ${fields}) && second_pid=$(printf '%s' "$second" | cut -f2) && second_pgid=$(printf '%s' "$second" | cut -f3) && [ "$second_pid" = "$first_pid" ] && [ "$second_pgid" = "$first_pgid" ] && kill -TERM -- "-$first_pgid"; fi`, `i=0; while [ "$i" -lt 10 ] && kill -0 -- "-$first_pgid" 2>/dev/null; do i=$((i+1)); sleep 1; done`, `! kill -0 -- "-$first_pgid" 2>/dev/null`, `cd ${shellAtom(cwd)}`, `${herdr} agent start ${shellAtom(agentName)} --kind ${shellAtom(connection.agentKind)} --pane ${pane}${agentCommand(connection, undefined, cwd)}`, `${herdr} agent get ${shellAtom(agentName)}`].join(" && ");
 }
 
 export function agentStatusCommand(connection: ExeConnection, agentName: string): string {
@@ -128,9 +141,12 @@ function herdrBinary(connection: ExeConnection): string {
 }
 
 /** Herdr owns the executable; it forwards these arguments after `--` to it. */
-function agentCommand(connection: ExeConnection): string {
+function agentCommand(connection: ExeConnection, prompt?: string, cwd?: string): string {
   const command = connection.agentCommand?.trim() || defaultAgentCommand(connection.agentKind);
-  return command ? ` -- ${shellWords(command).map(shellAtom).join(" ")}` : "";
+  const args = command ? shellWords(command).map(shellAtom) : [];
+  if (connection.agentKind === "codex" && cwd) args.push("--dangerously-bypass-hook-trust", "-c", shellAtom(`projects.${JSON.stringify(cwd)}.trust_level="trusted"`));
+  if (prompt !== undefined) args.push("--", shellAtom(prompt));
+  return args.length ? ` -- ${args.join(" ")}` : "";
 }
 
 export function defaultAgentCommand(agentKind: string): string {

src/execution.ts

@@ -14,6 +14,7 @@ export interface LaunchRequest {
   workspaceName: string;
   runPath: string;
   lease: string;
+  prompt: string;
 }
 
 export interface RunHandle {

src/tenant.ts

@@ -591,7 +591,9 @@ export class Tenant extends DurableObject<Env> {
     this.ctx.storage.sql.exec("UPDATE runs SET herdr_server_namespace='default',worktree_path=?,ownership_lease=?,ownership_generation=ownership_generation+1,agent_session_generation=1,updated_at=? WHERE id=?", worktreePath, lease, now(), run.id);
     if (String(run.provider || "linear") === "linear") await this.safeLinearComment(String(run.issue_id), `Factorize started **${connection.agentKind}** on ${connection.vmName} in Herdr workspace \`${workspaceName}\` for this issue.`);
     const backend = new ExeHerdrBackend(connection);
-    const launched = await backend.launch({ runId: String(run.id), agentName: String(run.agent_name), workspaceName, runPath: worktreePath, lease });
+    const prompt = await decrypt(String(run.prompt), this.env.CREDENTIAL_ENCRYPTION_KEY);
+    this.ctx.storage.sql.exec("UPDATE runs SET prompt_delivery_state='submitting',updated_at=? WHERE id=?", now(), run.id);
+    const launched = await backend.launch({ runId: String(run.id), agentName: String(run.agent_name), workspaceName, runPath: worktreePath, lease, prompt });
     const result = launched.command;
     const execRequest = await encrypt(result.requestBody, this.env.CREDENTIAL_ENCRYPTION_KEY);
     const execResponse = await encrypt(result.body, this.env.CREDENTIAL_ENCRYPTION_KEY);
@@ -605,15 +607,8 @@ export class Tenant extends DurableObject<Env> {
     }
     const identity = parseAgent(verification.body);
     if (!identity) return this.beginRecovery(run, pipe, connection, "agent start succeeded but its structured identity was inconsistent");
-    this.persistIdentity(run.id, identity, "starting");
-    const prompt = await decrypt(String(run.prompt), this.env.CREDENTIAL_ENCRYPTION_KEY);
-    this.ctx.storage.sql.exec("UPDATE runs SET prompt_delivery_state='submitting',updated_at=? WHERE id=?", now(), run.id);
-    const delivery = await backend.deliverPrompt(launched.handle, prompt);
-    const deliveryRequest = await encrypt(delivery.command.requestBody, this.env.CREDENTIAL_ENCRYPTION_KEY);
-    const deliveryResponse = await encrypt(delivery.command.body, this.env.CREDENTIAL_ENCRYPTION_KEY);
-    this.ctx.storage.sql.exec("UPDATE runs SET prompt_delivery_state=?,prompt_delivery_request=?,prompt_delivery_response=?,prompt_delivery_status=?,prompt_delivery_exit_code=?,prompt_accepted=?,updated_at=? WHERE id=?", delivery.state, deliveryRequest, deliveryResponse, delivery.command.status, delivery.command.exitCode, delivery.state === "accepted" ? 1 : 0, now(), run.id);
-    this.commandActivity(run.id, "initial prompt delivery", delivery.command);
-    if (delivery.state !== "accepted") return this.finishRun(run, "failed", `Harness launched, but prompt delivery was ${delivery.state} (exe.dev HTTP ${delivery.command.status}, VM exit ${delivery.command.exitCode ?? "not reported"}).`);
+    this.ctx.storage.sql.exec("UPDATE runs SET prompt_delivery_state='accepted',prompt_delivery_request=?,prompt_delivery_response=?,prompt_delivery_status=?,prompt_delivery_exit_code=?,prompt_accepted=1,updated_at=? WHERE id=?", execRequest, execResponse, result.status, result.exitCode, now(), run.id);
+    this.activity(run.id, "prompt_delivered_at_launch", "The initial prompt was passed as a positional harness argument in the successful Herdr launch command.");
     this.persistIdentity(run.id, identity, "running");
   }
 

test/agent-launch.e2e.test.ts

@@ -0,0 +1,50 @@
+import { chmod, mkdtemp, mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+import { describe, expect, it } from "vitest";
+import { launchAgentCommand, type ExeConnection } from "../src/exe";
+
+const runFile = promisify(execFile);
+const fixture = resolve(dirname(fileURLToPath(import.meta.url)), "fixtures/fake-herdr.sh");
+const jsonLines = (output: string) => output.trim().split("\n").map(line => JSON.parse(line));
+
+describe("agent launch and prompt delivery", () => {
+  it("delivers the exact prompt as part of the fake agent launch", async () => {
+    const root = await mkdtemp(`${tmpdir()}/factorize-agent-e2e-`);
+    try {
+      const repository = resolve(root, "repo");
+      const runPath = resolve(repository, ".factorize-runs/run-e2e");
+      const stateDir = resolve(root, "fake-herdr-state");
+      const promptDirectory = "/tmp/factorize-prompts/run-e2e";
+      await mkdir(repository, { recursive: true });
+      await chmod(fixture, 0o755);
+
+      const connection: ExeConnection = {
+        vmName: "unused",
+        apiToken: "unused",
+        agentKind: "codex",
+        cwd: repository,
+        herdrCommand: fixture,
+      };
+      const environment = {
+        ...process.env,
+        FAKE_HERDR_STATE_DIR: stateDir,
+        FAKE_HERDR_RUN_PATH: runPath,
+      };
+
+      const prompt = "Fix the launch race.\n\nConfirm readiness before starting.";
+      const launched = await runFile("bash", ["-c", launchAgentCommand("run-e2e", connection, "flow-e2e", runPath, "lease-e2e", prompt)], { env: environment });
+      expect(jsonLines(launched.stdout).at(-1)?.result.agent).toMatchObject({ name: "run-e2e", agent_status: "working", interactive_ready: true });
+      await expect(readFile(resolve(promptDirectory, "prompt.md"), "utf8")).resolves.toBe(prompt);
+      await expect(readFile(resolve(stateDir, "launch-instruction"), "utf8")).resolves.toBe(`Read and follow the complete task instructions in ${promptDirectory}/prompt.md`);
+      await expect(readFile(resolve(stateDir, "status"), "utf8")).resolves.toBe("working");
+      await expect(readFile(resolve(stateDir, "events"), "utf8")).resolves.toBe("workspace list\nworkspace create\ntab rename\nagent get\nagent start\nagent get\n");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+      await rm("/tmp/factorize-prompts/run-e2e", { recursive: true, force: true });
+    }
+  });
+});