dev-orchestrator-connector 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# Dev Orchestrator Connector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The connector runs on your computer and uses your existing local Codex sign-in.
+It downloads only repositories authorized for the paired executor. The cloud
+service coordinates tasks but never hosts your source checkout.
+
+Requirements: Node.js 22.18 or newer and the official Codex CLI signed in.
+
+Pair this machine using the one-time code shown in **Executors**:
+
+```bash
+mkdir -p "$HOME/.local/share/dev-orchestrator"
+npx --yes dev-orchestrator-connector@0.1.0 pair \
+  --server https://YOUR-ORCHESTRATOR-HOST \
+  --code YOUR_ONE_USE_CODE \
+  --config "$HOME/.local/share/dev-orchestrator/connector.json"
+```
+
+An owner must bind the executor to a project in the web app. Then start it with:
+
+```bash
+npx --yes dev-orchestrator-connector@0.1.0 run \
+  --config "$HOME/.local/share/dev-orchestrator/connector.json"
+```
+
+Keep that terminal open while the executor should process tasks. Press `Ctrl+C`
+to stop it safely. The connector stores its credential and runtime data under
+`~/.local/share/dev-orchestrator` with owner-only permissions.
+
+This package contains only the local connector. It does not include the cloud
+control plane or provider credentials.

package/bin/dev-orchestrator-connector.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const cli = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
+const child = spawn(process.execPath, ["--experimental-strip-types", cli, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+child.on("error", (error) => {
+  console.error(`Could not start the connector: ${error.message}`);
+  process.exitCode = 1;
+});
+
+child.on("exit", (code, signal) => {
+  process.exitCode = code ?? (signal ? 1 : 0);
+});

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "dev-orchestrator-connector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Run a customer-owned local Codex executor for Dev Orchestrator.",
+  "type": "module",
+  "bin": {
+    "dev-orchestrator-connector": "bin/dev-orchestrator-connector.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": { "node": ">=22.18.0" },
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "check": "tsc --noEmit",
+    "start": "node --experimental-strip-types src/cli.ts"
+  },
+  "devDependencies": { "@types/node": "22.18.8", "typescript": "5.9.3" }
+}

package/src/activity.ts

@@ -0,0 +1,33 @@
+export type ActivityStage =
+  | "agent_started"
+  | "working"
+  | "editing"
+  | "validating"
+  | "checks_passed";
+
+const validationCommand = /\b(test|tests|spec|lint|format|typecheck|type-check|check|build|compile)\b/i;
+
+export function activityForNotification(message: any): ActivityStage | undefined {
+  if (!message || typeof message !== "object" || !message.params) return undefined;
+
+  if (message.method === "turn/started") return "agent_started";
+
+  const item = message.params.item;
+  if (message.method === "item/started") {
+    if (item?.type === "fileChange") return "editing";
+    if (item?.type === "commandExecution") {
+      return validationCommand.test(String(item.command ?? "")) ? "validating" : "working";
+    }
+  }
+
+  if (
+    message.method === "item/completed" &&
+    item?.type === "commandExecution" &&
+    validationCommand.test(String(item.command ?? "")) &&
+    item.exitCode === 0
+  ) {
+    return "checks_passed";
+  }
+
+  return undefined;
+}

package/src/api.ts

@@ -0,0 +1,23 @@
+import { serverURL } from "./config.ts";
+export class APIError extends Error {
+  readonly status: number;
+  readonly code: string;
+  constructor(status: number, code: string) { super(`Control plane request failed (${status}: ${code}).`); this.status=status; this.code=code; }
+}
+
+export class API {
+  readonly origin: string;
+  readonly token: string | undefined;
+  constructor(origin: string, token?: string) { this.origin=serverURL(origin); this.token=token; }
+  async post(path: string, data: unknown): Promise<any> {
+    if (!/^\/[a-z/-]+$/.test(path)) throw new Error("Invalid control-plane route.");
+    const response = await fetch(this.origin + "/api/v1" + path, {
+      method: "POST", redirect: "error", signal: AbortSignal.timeout(15_000),
+      headers: { "content-type":"application/json", ...(this.token ? {authorization:`Bearer ${this.token}`} : {}) },
+      body: JSON.stringify(data)
+    });
+    const body = await response.json() as Record<string,unknown>;
+    if (!response.ok) throw new APIError(response.status, typeof body.error === "string" && /^[a-z_]+$/.test(body.error) ? body.error : "request_failed");
+    return path === "/enroll" ? body : body.data;
+  }
+}

package/src/cli.ts

@@ -0,0 +1,55 @@
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { mkdir, open, unlink } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { API } from "./api.ts";
+import { loadConfig, saveConfig, serverURL } from "./config.ts";
+import { CodexSession } from "./codex.ts";
+import { runLoop } from "./worker.ts";
+
+export async function main(args:string[]):Promise<void> {
+  const [action,...rest]=args;
+  if(!action || action==="help" || action==="--help") {
+    console.log("Dev Orchestrator connector\n\npair --server URL --code CODE --config /absolute/config.json\nstatus --config FILE\nrun --config FILE\n\nProjects and repository access are managed in the web app. This connector uses your official local Codex login and never modifies global provider/Git configuration.");return;
+  }
+  const opts:Record<string,string>={};
+  for(let i=0;i<rest.length;i+=2){if(!/^--[a-z-]+$/.test(rest[i]) || !rest[i+1])throw new Error("Options require --name value pairs.");opts[rest[i].slice(2)]=rest[i+1];}
+  if(!opts.config || !opts.config.startsWith("/"))throw new Error("Provide an absolute --config path.");
+  const file=opts.config;
+  if(action==="pair") {
+    // Do not consume a one-use code if a pairing already exists.
+    const reservation=await open(file+".pairing","wx",0o600).catch(()=>{throw new Error("Configuration directory must exist and no pairing may already be in progress.");});
+    try {
+      try {await loadConfig(file);throw new Error("This configuration is already paired.");}
+      catch(error){if((error as NodeJS.ErrnoException).code!=="ENOENT")throw error;}
+      const server=serverURL(opts.server);
+      const result=await new API(server).post("/enroll",{code:opts.code,name:opts.name??hostname()});
+      if(typeof result.token!=="string")throw new Error("Invalid enrollment response.");
+      await saveConfig(file,{version:2,server,token:result.token},true);
+      console.log("Paired. Ask the owner to bind a project and install its repository in the web app.");
+    } finally {await reservation.close();await unlink(file+".pairing");}
+    return;
+  }
+  const config=await loadConfig(file);
+  if(action==="allow") {
+    console.log("The local allow command is no longer needed. Bind this executor to the project and configure its GitHub App repository access in the web app.");return;
+  }
+  if(action==="status") {
+    const session=CodexSession.start(config.codexBinary??"codex",dirname(file));
+    try {await session.initialize();console.log(JSON.stringify({codex_authenticated:await session.authenticated(),server:config.server}));}
+    finally{session.stop();}return;
+  }
+  if(action!=="run")throw new Error("Unknown command. Use help.");
+  const root=join(dirname(file),"runtime");await mkdir(root,{recursive:true,mode:0o700});
+  const lock=join(root,"connector.lock");
+  const fd=await open(lock,"wx",0o600).catch(()=>{throw new Error("Connector lock exists. Confirm no connector is running before removing that exact lock file.");});
+  await fd.writeFile(String(process.pid));
+  const controller=new AbortController();
+  const stop=()=>controller.abort();process.once("SIGINT",stop);process.once("SIGTERM",stop);
+  try {console.log("Connector running. Press Ctrl+C to stop; interrupted work is preserved.");await runLoop(config,root,controller.signal);}
+  finally {controller.abort();process.off("SIGINT",stop);process.off("SIGTERM",stop);await fd.close();await unlink(lock);}
+}
+
+if(process.argv[1] && import.meta.url===pathToFileURL(process.argv[1]).href) {
+  main(process.argv.slice(2)).catch(error=>{console.error(error instanceof Error?error.message:"Connector operation failed.");process.exitCode=1;});
+}

package/src/codex.ts

@@ -0,0 +1,160 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { createHash } from "node:crypto";
+import { stopProcess } from "./process.ts";
+import { activityForNotification, type ActivityStage } from "./activity.ts";
+
+type Pending={resolve:(value:any)=>void;reject:(reason:Error)=>void;timer:NodeJS.Timeout};
+
+export class RepeatedFailureError extends Error {
+  readonly fingerprint: string;
+  constructor(fingerprint:string){super("Codex repeated the same failed command three times.");this.fingerprint=fingerprint;}
+}
+export class CodexBlockedError extends Error {}
+
+export class CodexSession {
+  readonly child: ChildProcessWithoutNullStreams;
+  readonly events=new EventEmitter();
+  private pending=new Map<number,Pending>();
+  private id=0;
+  private buffer="";
+  private failed:Error|null=null;
+  private commandFailures=new Map<string,number>();
+
+  constructor(child:ChildProcessWithoutNullStreams) {
+    this.child=child;
+    child.stderr.resume();
+    child.stdin.on("error",()=>this.fail(new Error("Codex transport closed.")));
+    child.stdout.on("data",chunk=>this.consume(chunk.toString()));
+    child.on("error",()=>this.fail(new Error("Codex could not start. Check the locally installed CLI.")));
+    child.on("close",()=>this.fail(new Error("Codex process stopped before completion.")));
+  }
+
+  static start(binary:string,workspace:string):CodexSession {
+    // Keep provider-owned local login, but never forward API/Git tokens into the agent.
+    const allowed=["PATH","HOME","USER","LOGNAME","SHELL","TMPDIR","LANG","LC_ALL","CODEX_HOME","HTTP_PROXY","HTTPS_PROXY","ALL_PROXY","NO_PROXY"];
+    const env=Object.fromEntries(allowed.filter(key=>process.env[key]!==undefined).map(key=>[key,process.env[key]]));
+    const args=["app-server","--listen","stdio://",
+      "-c",'permissions.dev-orchestrator.extends=":workspace"',
+      "-c",'permissions.dev-orchestrator.filesystem={":workspace_roots"={"."="write",".git"="write",".agents"="write",".codex"="read",".aws"="read"}}',
+      "-c","permissions.dev-orchestrator.network.enabled=false"];
+    return new CodexSession(spawn(binary,args,{cwd:workspace,env,detached:true,stdio:["pipe","pipe","pipe"]}));
+  }
+
+  async initialize():Promise<void> {
+    await this.request("initialize",{clientInfo:{name:"dev_orchestrator",title:"Dev Orchestrator",version:"0.1.0"},capabilities:{experimentalApi:true}});
+    this.send({method:"initialized",params:{}});
+  }
+  async authenticated():Promise<boolean> {
+    const result=await this.request("account/read",{refreshToken:false});
+    return result.account?.type==="chatgpt";
+  }
+
+  async run(workspace:string,prompt:string,model:string|undefined,signal?:AbortSignal,onProgress?:(stage:ActivityStage)=>Promise<void>):Promise<void> {
+    const thread=await this.request("thread/start",{cwd:workspace,approvalPolicy:"never",permissions:"dev-orchestrator",...(model?{model}:{})});
+    const threadId=thread.thread?.id;
+    if(!threadId)throw new Error("Codex returned no task thread.");
+    let onNotification:(message:any)=>void;
+    let onFailure:(error:Error)=>void;
+    let abort:()=>void;
+    let outcome:string|undefined;
+    let lastStage:ActivityStage|undefined;
+    let progressQueue=Promise.resolve();
+    let progressFailure:Error|undefined;
+    const completed=new Promise<void>((resolve,reject)=>{
+      onNotification=(message)=>{
+        if(message.params?.threadId===threadId) {
+          const stage=activityForNotification(message);
+          if(stage && stage!==lastStage) {
+            lastStage=stage;
+            progressQueue=progressQueue.then(()=>onProgress?.(stage));
+            void progressQueue.catch(error=>{
+              progressFailure=error instanceof Error?error:new Error("Progress delivery failed.");
+              this.fail(progressFailure);
+            });
+          }
+        }
+        if(message.method==="item/completed" && message.params?.threadId===threadId && message.params.item?.type==="agentMessage") {
+          try {const result=JSON.parse(message.params.item.text);if(["completed","blocked"].includes(result?.outcome))outcome=result.outcome;}catch{/* Wait for a valid structured final answer. */}
+        }
+        if(message.method==="turn/completed" && message.params?.threadId===threadId) {
+          if(outcome==="blocked")reject(new CodexBlockedError("Essential context is missing; the task is blocked."));
+          else if(message.params.turn?.status==="completed" && outcome==="completed")resolve();
+          else reject(new Error("Codex turn did not complete."));
+        }
+      };
+      onFailure=reject;
+      abort=()=>{this.stop();reject(new Error("Task stopped before lease expiration."));};
+      this.events.on("notification",onNotification);
+      this.events.once("failure",onFailure);
+      signal?.addEventListener("abort",abort,{once:true});
+      if(signal?.aborted)abort();
+    });
+    // Attach a rejection handler before turn/start to cover an early process exit.
+    completed.catch(()=>{});
+    try {
+      await this.request("turn/start",{threadId,cwd:workspace,approvalPolicy:"never",permissions:"dev-orchestrator",input:[{type:"text",text:prompt}],outputSchema:{type:"object",properties:{outcome:{type:"string",enum:["completed","blocked"]}},required:["outcome"],additionalProperties:false}});
+      await completed;
+      await progressQueue;
+      if(progressFailure)throw progressFailure;
+    } finally {
+      this.events.off("notification",onNotification!);this.events.off("failure",onFailure!);
+      signal?.removeEventListener("abort",abort!);
+    }
+  }
+
+  stop():void {stopProcess(this.child);this.fail(new Error("Codex stopped."));}
+
+  private request(method:string,params:unknown):Promise<any> {
+    if(this.failed)return Promise.reject(this.failed);
+    return new Promise((resolve,reject)=>{
+      const id=++this.id;
+      const timer=setTimeout(()=>{this.pending.delete(id);reject(new Error("Codex request timed out."));this.stop();},30_000);
+      this.pending.set(id,{resolve,reject,timer});this.send({id,method,params});
+    });
+  }
+  private send(message:unknown):void {if(!this.child.stdin.destroyed)this.child.stdin.write(JSON.stringify(message)+"\n");}
+  private consume(chunk:string):void {
+    this.buffer+=chunk;
+    if(this.buffer.length>1_048_576){this.fail(new Error("Codex message exceeded the size limit."));this.stop();return;}
+    let newline:number;
+    while((newline=this.buffer.indexOf("\n"))>=0) {
+      const line=this.buffer.slice(0,newline);this.buffer=this.buffer.slice(newline+1);
+      if(!line.trim())continue;
+      let message:any;
+      try{message=JSON.parse(line);}catch{this.fail(new Error("Invalid Codex protocol response."));this.stop();return;}
+      if(!message || typeof message!=="object" || Array.isArray(message)){this.fail(new Error("Invalid Codex protocol response."));this.stop();return;}
+      if(message.method==="item/completed") {
+        const item=message.params?.item;
+        if(item?.type==="commandExecution" && (typeof item.exitCode==="number" && item.exitCode!==0 || item.status==="failed")) {
+          const command=String(item.command??"");
+          const wrapped=command.trim().match(/^(?:\/[^\s]+\/)?(?:bash|zsh|sh)\s+-lc\s+(['"])([\s\S]*)\1$/);
+          const probe=(wrapped?.[2]??command).trim();
+          const unquoted=probe.replace(/"[^"\n]*"|'[^'\n]*'/g,"");
+          const expectedMiss=item.exitCode===1 && /^(?:rg|grep|test|\[)(?:\s|$)/.test(probe) && !/[;&|]/.test(unquoted);
+          if(!expectedMiss) {
+            const detail=(command+":"+String(item.exitCode)+":"+String(item.aggregatedOutput??"")).replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi,"<id>").replace(/\b\d+(?:\.\d+)?\s*(?:ms|s|seconds)\b/g,"<duration>");
+            const fingerprint=createHash("sha256").update(detail).digest("hex");
+            const count=(this.commandFailures.get(fingerprint)??0)+1;this.commandFailures.set(fingerprint,count);
+            if(count>=3){this.fail(new RepeatedFailureError(fingerprint));this.stop();return;}
+          }
+        }
+      }
+      if(message.method && message.id!==undefined) {
+        // The connector never auto-approves a broader permission or user-input request.
+        this.send({id:message.id,error:{code:-32000,message:"Required context or permission is unavailable; task blocked."}});
+        this.fail(new Error("Codex needs context or unsupported permissions."));this.stop();return;
+      }
+      if(message.id!==undefined) {
+        const pending=this.pending.get(message.id);
+        if(pending){clearTimeout(pending.timer);this.pending.delete(message.id);message.error?pending.reject(new Error("Codex rejected the configured request or sandbox.")):pending.resolve(message.result);}
+      } else if(message.method)this.events.emit("notification",message);
+    }
+  }
+  private fail(error:Error):void {
+    if(this.failed)return;
+    this.failed=error;
+    for(const pending of this.pending.values()){clearTimeout(pending.timer);pending.reject(error);}this.pending.clear();
+    this.events.emit("failure",error);
+  }
+}

package/src/config.ts

@@ -0,0 +1,46 @@
+import { lstat, readFile, mkdir, open, rename, unlink } from "node:fs/promises";
+import { dirname, isAbsolute } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { Config } from "./types.ts";
+
+export function serverURL(value: string): string {
+  const url = new URL(value);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) || url.username || url.password || url.search || url.hash || url.pathname !== "/") throw new Error("Use an HTTPS server origin (loopback HTTP is allowed for development).");
+  return url.origin;
+}
+
+export async function loadConfig(path: string): Promise<Config> {
+  if (!isAbsolute(path)) throw new Error("Configuration path must be absolute.");
+  const info = await lstat(path);
+  if (!info.isFile() || info.isSymbolicLink() || (info.mode & 0o077) !== 0) throw new Error("Configuration must be a regular owner-only file (chmod 600).");
+  const config = JSON.parse(await readFile(path,"utf8"));
+  if (![1,2].includes(config.version) || typeof config.token !== "string" || !config.token) throw new Error("Invalid connector configuration.");
+  const server = serverURL(config.server);
+  if (config.version === 1) {
+    if (!Array.isArray(config.mappings)) throw new Error("Invalid connector configuration.");
+    console.warn("Legacy connector configuration detected. Local project mappings are ignored; bind projects in the web app.");
+  } else if ("mappings" in config) {
+    throw new Error("Invalid connector configuration.");
+  }
+  return {version:2,server,token:config.token,...(typeof config.codexBinary === "string"?{codexBinary:config.codexBinary}:{})};
+}
+
+export async function saveConfig(path: string, config: Config, exclusive = false): Promise<void> {
+  if (!isAbsolute(path)) throw new Error("Configuration path must be absolute.");
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  if (!exclusive) {
+    try { await loadConfig(path); } catch (e) { if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e; }
+  }
+  if (exclusive) {
+    const file = await open(path,"wx",0o600);
+    try { await file.writeFile(JSON.stringify(config,null,2)); await file.sync(); } finally { await file.close(); }
+  } else {
+    const temporary = path + ".tmp-" + randomUUID();
+    const file = await open(temporary,"wx",0o600);
+    try {
+      await file.writeFile(JSON.stringify(config,null,2)); await file.sync();
+      await file.close(); await rename(temporary,path);
+    } catch (error) { await file.close().catch(()=>{}); await unlink(temporary).catch(()=>{}); throw error; }
+  }
+}

package/src/git-credential.ts

@@ -0,0 +1,29 @@
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { GitHubCredential } from "./types.ts";
+import { cleanGitEnv } from "./process.ts";
+
+export function validateGitHubCredential(value: unknown): asserts value is GitHubCredential {
+  if (!value || typeof value !== "object") throw new Error("GitHub authorization is unavailable.");
+  const credential=value as Partial<GitHubCredential>;
+  if (typeof credential.token!=="string" || !/^[A-Za-z0-9_-]+$/.test(credential.token) ||
+      typeof credential.expires_at!=="string" || !Number.isFinite(Date.parse(credential.expires_at)) || Date.parse(credential.expires_at)<=Date.now() ||
+      typeof credential.author_name!=="string" || !credential.author_name || credential.author_name.length>200 || /[\r\n]/.test(credential.author_name) ||
+      typeof credential.author_email!=="string" || !credential.author_email || credential.author_email.length>254 || /[\r\n]/.test(credential.author_email)) {
+    throw new Error("GitHub authorization is invalid or expired.");
+  }
+}
+
+export async function withGitHubCredential<T>(root:string, credential:GitHubCredential, operation:(env:NodeJS.ProcessEnv)=>Promise<T>):Promise<T> {
+  validateGitHubCredential(credential);
+  const directory=await mkdtemp(join(root,".github-auth-"));
+  try {
+    await chmod(directory,0o700);
+    const helper=join(directory,"askpass");
+    const script=`#!/bin/sh\ncase "$1" in\n  *sername*) printf '%s\\n' 'x-access-token' ;;\n  *assword*) printf '%s\\n' '${credential.token}' ;;\n  *) exit 1 ;;\nesac\n`;
+    await writeFile(helper,script,{encoding:"utf8",mode:0o700,flag:"wx"});
+    return await operation({...cleanGitEnv(),GIT_ASKPASS:helper,SSH_ASKPASS:helper,GIT_TERMINAL_PROMPT:"0"});
+  } finally {
+    await rm(directory,{recursive:true,force:true});
+  }
+}

package/src/journal.ts

@@ -0,0 +1,36 @@
+import { mkdir, open, readFile, rename, unlink, lstat } from "node:fs/promises";
+import { join, isAbsolute } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { JournalState } from "./types.ts";
+
+export class Journal {
+  readonly root: string;
+  constructor(root: string) {
+    if (!isAbsolute(root)) throw new Error("Journal directory must be absolute.");
+    this.root = root;
+  }
+  async load(): Promise<JournalState | null> {
+    try {
+      const path = join(this.root,"active.json");
+      const stat = await lstat(path);
+      if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077)) throw new Error("Unsafe journal file.");
+      const state = JSON.parse(await readFile(path,"utf8"));
+      if (!state.lease?.id || !Number.isInteger(state.sequence)) throw new Error("Corrupt journal; manual recovery is required.");
+      return state;
+    } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+  }
+  async save(state: JournalState): Promise<void> {
+    await mkdir(this.root,{recursive:true,mode:0o700});
+    const info = await lstat(this.root);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Unsafe journal directory.");
+    const temp = join(this.root,".journal-" + randomUUID());
+    const file = await open(temp,"wx",0o600);
+    try {
+      await file.writeFile(JSON.stringify(state)); await file.sync(); await file.close();
+      await rename(temp,join(this.root,"active.json"));
+    } catch (error) { await file.close().catch(()=>{}); await unlink(temp).catch(()=>{}); throw error; }
+  }
+  async clear(): Promise<void> {
+    await unlink(join(this.root,"active.json")).catch((e: NodeJS.ErrnoException) => { if (e.code !== "ENOENT") throw e; });
+  }
+}

package/src/process.ts

@@ -0,0 +1,40 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+export const cleanGitEnv = (): NodeJS.ProcessEnv => ({
+  PATH: process.env.PATH, HOME: process.env.HOME,
+  LANG: "C", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null",
+  GIT_TERMINAL_PROMPT: "0", GIT_NO_REPLACE_OBJECTS: "1"
+});
+
+export async function readAuthor(source:string,env:NodeJS.ProcessEnv={PATH:process.env.PATH,HOME:process.env.HOME,XDG_CONFIG_HOME:process.env.XDG_CONFIG_HOME,GIT_CONFIG_NOSYSTEM:"1"}):Promise<{name:string;email:string}> {
+  // Reading these two values does not execute hooks or credential helpers.
+  const name=(await command("git",["-C",source,"config","--get","user.name"],{env})).output;
+  const email=(await command("git",["-C",source,"config","--get","user.email"],{env})).output;
+  if(!name || name.length>200 || !email || email.length>254 || /[\r\n]/.test(name+email))throw new Error("Configure a Git author on the customer host before running tasks.");
+  return {name,email};
+}
+
+export function stopProcess(child: ChildProcess): void {
+  if (!child.pid || child.exitCode !== null) return;
+  try { process.kill(-child.pid,"SIGKILL"); } catch { child.kill("SIGKILL"); }
+}
+
+export async function command(binary: string, args: string[], opts: { cwd?: string; env?: NodeJS.ProcessEnv; signal?: AbortSignal; timeout?: number; allowExitOne?: boolean } = {}): Promise<{ output: string; code: number }> {
+  return new Promise((resolve,reject)=>{
+    const child=spawn(binary,args,{cwd:opts.cwd,env:opts.env ?? cleanGitEnv(),detached:true,stdio:["ignore","pipe","ignore"]});
+    let output="",settled=false;
+    const fail=()=>{if(!settled){settled=true;stopProcess(child);reject(new Error("Local command failed."));}};
+    const timer=setTimeout(fail,opts.timeout ?? 30_000);
+    const abort=()=>fail();
+    opts.signal?.addEventListener("abort",abort,{once:true});
+    if(opts.signal?.aborted) fail();
+    child.stdout.on("data",chunk=>{output+=chunk.toString();if(output.length>1_048_576)fail();});
+    child.on("error",fail);
+    child.on("close",code=>{
+      clearTimeout(timer);opts.signal?.removeEventListener("abort",abort);
+      if(settled)return;settled=true;
+      if(code===0 || (code===1 && opts.allowExitOne))resolve({output:output.trim(),code:code!});
+      else reject(new Error("Local command failed."));
+    });
+  });
+}

package/src/publisher.ts

@@ -0,0 +1,152 @@
+import { mkdtemp, readFile, writeFile, rm, realpath, lstat, access, mkdir } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { command, cleanGitEnv } from "./process.ts";
+import { withGitHubCredential, validateGitHubCredential } from "./git-credential.ts";
+import type { GitHubCredential } from "./types.ts";
+import { validBranch, validRepository } from "./workspace.ts";
+
+export type PublicationContext={workspace:string;repository:string;baseBranch:string;branch:string;baseline:string};
+type Dependencies={runCommand?:typeof command;apiFetch?:typeof fetch;remoteURL?:(repository:string)=>string};
+const validSHA=(sha:string)=>/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(sha);
+
+export class Publisher {
+  readonly context:PublicationContext;
+  private readonly runCommand:typeof command;
+  private readonly apiFetch:typeof fetch;
+  private readonly remoteURL:(repository:string)=>string;
+
+  constructor(context:PublicationContext,dependencies:Dependencies={}) {
+    if(!validRepository(context.repository) || !validBranch(context.branch) || !validBranch(context.baseBranch) || context.branch===context.baseBranch || !context.branch.startsWith("task/") || !validSHA(context.baseline))throw new Error("Invalid publication context.");
+    this.context=context;
+    this.runCommand=dependencies.runCommand??command;
+    this.apiFetch=dependencies.apiFetch??fetch;
+    this.remoteURL=dependencies.remoteURL??(repository=>`https://github.com/${repository}.git`);
+  }
+
+  async status(signal?:AbortSignal):Promise<{changed:boolean;commit:string}> {
+    return this.trusted(async(git,sha)=>{
+      const uncommitted=await git(["diff","--no-ext-diff","--no-textconv","--quiet",sha,"--"],true);
+      const untracked=await git(["ls-files","--others","--exclude-standard"]);
+      if(uncommitted.code!==0 || untracked.output)throw new Error("Uncommitted changes remain. Codex must commit the task before publication.");
+      const diff=await git(["diff","--no-ext-diff","--no-textconv","--quiet",this.context.baseline,sha,"--"],true);
+      return {changed:diff.code===1,commit:sha};
+    },signal);
+  }
+
+  async publish(title:string,body:string,credential:GitHubCredential,signal?:AbortSignal):Promise<Record<string,string>> {
+    if(!title.trim() || title.length>240 || body.length>64_000)throw new Error("Invalid PR metadata.");
+    validateGitHubCredential(credential);
+    const status=await this.status(signal);
+    if(!status.changed)throw new Error("No committed changes to publish.");
+    return this.trusted(async(git,sha,temp,objects)=>{
+      await withGitHubCredential(temp,credential,env=>git(["push","--no-verify",this.remoteURL(this.context.repository),`${sha}:refs/heads/${this.context.branch}`],false,{...env,GIT_OBJECT_DIRECTORY:objects}));
+      let pr=await this.findOpenPullRequest(credential,signal);
+      if(!pr) {
+        const [owner]=this.context.repository.split("/");
+        const created=await this.githubRequest("POST",`/repos/${this.context.repository}/pulls`,credential,{
+          title,
+          head:`${owner}:${this.context.branch}`,
+          base:this.context.baseBranch,
+          body,
+          draft:false
+        },signal);
+        if(created.status===422)pr=await this.findOpenPullRequest(credential,signal);
+        else if(created.ok)pr=created.body;
+        else throw new Error("GitHub could not create a pull request for this branch.");
+      }
+      if(!this.matchesPullRequest(pr,sha))throw new Error("GitHub pull request does not match the task commit.");
+      return {repository:this.context.repository,branch:this.context.branch,base_branch:this.context.baseBranch,commit:sha,pr_url:pr.html_url};
+    },signal);
+  }
+
+  private async findOpenPullRequest(credential:GitHubCredential,signal?:AbortSignal):Promise<any|undefined> {
+    const [owner]=this.context.repository.split("/");
+    const query=new URLSearchParams({state:"open",head:`${owner}:${this.context.branch}`,per_page:"100"});
+    const response=await this.githubRequest("GET",`/repos/${this.context.repository}/pulls?${query}`,credential,undefined,signal);
+    if(!response.ok || !Array.isArray(response.body))throw new Error("GitHub pull request lookup failed.");
+    const sameBranch=response.body.filter((pr:any)=>pr?.head?.ref===this.context.branch && pr?.head?.repo?.full_name===this.context.repository);
+    const exact=sameBranch.find((pr:any)=>pr?.base?.ref===this.context.baseBranch && pr?.base?.repo?.full_name===this.context.repository);
+    if(sameBranch.length && !exact)throw new Error("An open pull request exists for this task branch with a different base repository or branch.");
+    return exact;
+  }
+
+  private matchesPullRequest(pr:any,sha:string):boolean {
+    const escaped=this.context.repository.replace(/[.*+?^${}()|[\]\\]/g,"\\$&");
+    return pr?.state==="open" && pr?.head?.sha===sha && pr?.head?.ref===this.context.branch &&
+      pr?.head?.repo?.full_name===this.context.repository && pr?.base?.ref===this.context.baseBranch &&
+      pr?.base?.repo?.full_name===this.context.repository &&
+      new RegExp(`^https://github\\.com/${escaped}/pull/[0-9]+$`).test(pr?.html_url??"");
+  }
+
+  private async githubRequest(method:"GET"|"POST",path:string,credential:GitHubCredential,body?:Record<string,string|boolean>,signal?:AbortSignal):Promise<{ok:boolean;status:number;body:any}> {
+    const timeout=AbortSignal.timeout(15_000);
+    const requestSignal=signal?AbortSignal.any([signal,timeout]):timeout;
+    let response:Response;
+    try {
+      response=await this.apiFetch("https://api.github.com"+path,{
+        method,redirect:"error",signal:requestSignal,
+        headers:{authorization:`Bearer ${credential.token}`,accept:"application/vnd.github+json","x-github-api-version":"2022-11-28","content-type":"application/json","user-agent":"dev-orchestrator"},
+        ...(body?{body:JSON.stringify(body)}:{})
+      });
+    } catch {throw new Error("GitHub pull request service is temporarily unavailable.");}
+    let payload:any;
+    try {payload=await response.json();} catch {throw new Error("GitHub returned an invalid pull request response.");}
+    return {ok:response.ok,status:response.status,body:payload};
+  }
+
+  private async trusted<T>(fn:(git:(args:string[],allowExitOne?:boolean,commandEnv?:NodeJS.ProcessEnv)=>Promise<{output:string;code:number}>,sha:string,temp:string,objects:string)=>Promise<T>,signal?:AbortSignal):Promise<T> {
+    const workspace=await realpath(this.context.workspace);
+    const pointer=join(workspace,".git");
+    const stat=await lstat(pointer);
+    if(stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile()))throw new Error("Publication needs valid Git metadata.");
+    let gitDir:string;
+    let commonDir:string;
+    if(stat.isDirectory()) {
+      gitDir=workspace+sep+".git";
+      commonDir=gitDir;
+    } else {
+      const content=await readFile(pointer,"utf8");
+      const match=content.match(/^gitdir: (.+)\r?\n?$/);
+      if(!match)throw new Error("Publication needs valid Git worktree metadata.");
+      gitDir=await realpath(resolve(workspace,match[1]));
+      commonDir=await realpath(join(gitDir,"..",".."));
+      const worktrees=await realpath(join(commonDir,"worktrees"));
+      if(!gitDir.startsWith(worktrees+sep) || gitDir.slice(worktrees.length+1).includes(sep))throw new Error("Publication worktree metadata escaped its repository.");
+    }
+    const objects=await realpath(join(commonDir,"objects"));
+    if(!objects.startsWith(commonDir+sep))throw new Error("Publication needs an internal Git object directory.");
+    for(const forbidden of ["info/alternates","info/http-alternates"]) {
+      try {await access(join(objects,forbidden));throw new Error("External Git object stores are not supported.");}
+      catch(error) {if((error as NodeJS.ErrnoException).code!=="ENOENT")throw error;}
+    }
+    const head=await readFile(join(gitDir,"HEAD"),"utf8");
+    if(head.trim()!==`ref: refs/heads/${this.context.branch}`)throw new Error("Task branch changed unexpectedly.");
+    const ref=join(commonDir,"refs","heads",this.context.branch);
+    const resolved=await realpath(ref);
+    if(!resolved.startsWith(commonDir+sep))throw new Error("Unsafe Git reference.");
+    const sha=(await readFile(ref,"utf8")).trim();
+    if(!validSHA(sha))throw new Error("Invalid task commit.");
+    const temporary=await mkdtemp(join(tmpdir(),"dev-orchestrator-publish-"));
+    try {
+      const bare=join(temporary,"repo.git");
+      await this.runCommand("git",["init","--bare","--template=",bare],{signal});
+      await mkdir(join(bare,"info"),{mode:0o700});
+      const excludes=join(commonDir,"info","exclude");
+      const excludesInfo=await lstat(excludes).catch(error=>{if((error as NodeJS.ErrnoException).code==="ENOENT")return undefined;throw error;});
+      if(excludesInfo) {
+        if(!excludesInfo.isFile() || excludesInfo.isSymbolicLink() || excludesInfo.size>1_048_576)throw new Error("Unsafe Git exclude metadata.");
+        await writeFile(join(bare,"info","exclude"),await readFile(excludes,"utf8"),{mode:0o600});
+      }
+      try {
+        const shallow=await readFile(join(commonDir,"shallow"),"utf8");
+        if(!shallow.trim().split("\n").every(validSHA))throw new Error("Invalid shallow boundary.");
+        await writeFile(join(bare,"shallow"),shallow,{mode:0o600});
+      } catch(error) {if((error as NodeJS.ErrnoException).code!=="ENOENT")throw error;}
+      const env={...cleanGitEnv(),GIT_OBJECT_DIRECTORY:objects};
+      const git=(args:string[],allowExitOne=false,commandEnv:NodeJS.ProcessEnv=env)=>this.runCommand("git",["--git-dir",bare,"--work-tree",workspace,"-c","core.bare=false","-c","core.hooksPath=/dev/null",...args],{cwd:temporary,env:commandEnv,signal,allowExitOne});
+      await git(["read-tree",sha]);
+      return await fn(git,sha,temporary,objects);
+    } finally {await rm(temporary,{recursive:true,force:true});}
+  }
+}

package/src/repository.ts

@@ -0,0 +1,261 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { command } from "./process.ts";
+import { withGitHubCredential } from "./git-credential.ts";
+import type { GitHubCredential, Lease } from "./types.ts";
+import { validBranch, validRepository } from "./workspace.ts";
+
+type Marker={run:string;lifecycle:number;project:string;repository:string;base_branch:string;baseline:string;branch:string};
+type Options={remoteURL?:(repository:string)=>string;runCommand?:typeof command};
+const validId=(value:unknown):value is string=>typeof value==="string" && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(value);
+const validSHA=(value:unknown):value is string=>typeof value==="string" && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+
+async function ensureDirectory(path:string):Promise<string> {
+  await mkdir(path,{recursive:true,mode:0o700});
+  const info=await lstat(path);
+  const canonical=await realpath(path);
+  if(!info.isDirectory() || info.isSymbolicLink() || canonical!==resolve(path))throw new Error("Managed repository storage must be a canonical directory without symlinks.");
+  await chmod(path,0o700);
+  return canonical;
+}
+
+async function acquireLock(path:string):Promise<()=>Promise<void>> {
+  const deadline=Date.now()+30_000;
+  while(Date.now()<deadline) {
+    try {
+      const file=await open(path,"wx",0o600);
+      await file.writeFile(String(process.pid));await file.sync();await file.close();
+      return async()=>{await unlink(path).catch(error=>{if((error as NodeJS.ErrnoException).code!=="ENOENT")throw error;});};
+    } catch(error) {
+      const code=(error as NodeJS.ErrnoException).code;
+      if(code!=="EEXIST")throw error;
+      const info=await lstat(path).catch(()=>undefined);
+      if(info?.isSymbolicLink() || (info && !info.isFile()))throw new Error("Unsafe repository cache lock.");
+      const value=info?await readFile(path,"utf8").catch(()=>""):"";
+      const pid=Number(value.trim());
+      if(Number.isInteger(pid) && pid>0 && pid!==process.pid) {
+        try {process.kill(pid,0);} catch(e) {
+          if((e as NodeJS.ErrnoException).code==="ESRCH") {await unlink(path).catch(()=>{});continue;}
+        }
+      }
+      await new Promise(resolve=>setTimeout(resolve,100));
+    }
+  }
+  throw new Error("Repository cache is busy. Retry after the active repository operation finishes.");
+}
+
+async function worktreeGitDirectory(workspace:string,cache:string):Promise<string> {
+  const pointer=join(workspace,".git");
+  const info=await lstat(pointer);
+  if(!info.isFile() || info.isSymbolicLink())throw new Error("Task worktree Git pointer is invalid.");
+  const contents=await readFile(pointer,"utf8");
+  const match=contents.match(/^gitdir: (.+)\r?\n?$/);
+  if(!match)throw new Error("Task worktree Git pointer is invalid.");
+  const gitdir=await realpath(resolve(workspace,match[1]));
+  const worktrees=await realpath(join(cache,"worktrees"));
+  if(!gitdir.startsWith(worktrees+sep) || relative(worktrees,gitdir).split(sep).length!==1)throw new Error("Task worktree metadata escaped its managed repository.");
+  const gitInfo=await lstat(gitdir);
+  if(!gitInfo.isDirectory() || gitInfo.isSymbolicLink())throw new Error("Task worktree metadata is invalid.");
+  return gitdir;
+}
+
+async function readMarker(workspace:string,cache:string):Promise<Marker> {
+  const gitdir=await worktreeGitDirectory(workspace,cache);
+  const path=join(gitdir,"orchestrator.json");
+  const info=await lstat(path);
+  if(!info.isFile() || info.isSymbolicLink() || (info.mode&0o077)!==0)throw new Error("Task worktree marker is unsafe.");
+  const marker=JSON.parse(await readFile(path,"utf8")) as Marker;
+  if(!validId(marker.run) || !validId(marker.project) || !Number.isInteger(marker.lifecycle) || marker.lifecycle<1 || !validRepository(marker.repository) || !validBranch(marker.base_branch) || !validBranch(marker.branch) || !validSHA(marker.baseline))throw new Error("Task worktree marker is invalid.");
+  return marker;
+}
+
+async function workspaceCache(workspace:string):Promise<string> {
+  const pointer=await readFile(join(workspace,".git"),"utf8");
+  const match=pointer.match(/^gitdir: (.+)\r?\n?$/);
+  if(!match)throw new Error("Task worktree Git pointer is invalid.");
+  const gitdir=await realpath(resolve(workspace,match[1]));
+  return realpath(join(gitdir,"..",".."));
+}
+
+export class RepositoryWorkspace {
+  private readonly remoteURL:(repository:string)=>string;
+  private readonly runCommand:typeof command;
+
+  constructor(options:Options={}) {
+    this.remoteURL=options.remoteURL??(repository=>`https://github.com/${repository}.git`);
+    this.runCommand=options.runCommand??command;
+  }
+
+  async prepare(root:string,lease:Lease,credential:GitHubCredential):Promise<{path:string;branch:string;baseline:string}> {
+    const projectId=lease.project_id;
+    const repository=lease.snapshot?.repository;
+    const baseBranch=lease.snapshot?.base_branch;
+    if(!isAbsolute(root) || !validId(lease.id) || !validId(projectId) || !Number.isInteger(lease.lifecycle) || lease.lifecycle<1 || !validRepository(repository) || !validBranch(baseBranch))throw new Error("Task repository snapshot is invalid.");
+    const dataRoot=await ensureDirectory(root);
+    const repositories=await ensureDirectory(join(dataRoot,"repositories"));
+    const workspaces=await ensureDirectory(join(dataRoot,"workspaces"));
+    const cacheKey=createHash("sha256").update(repository).digest("hex").slice(0,16);
+    const cache=join(repositories,`${projectId}-${cacheKey}`);
+    const workspace=join(workspaces,`${lease.id}-${lease.lifecycle}`);
+    const branch=`task/${lease.id}`;
+    const remote=this.remoteURL(repository);
+    const release=await acquireLock(cache+".lock");
+    try {
+      return await withGitHubCredential(dataRoot,credential,async env=>{
+        const git=(args:string[],cwd?:string)=>this.runCommand("git",args,{cwd,env,timeout:120_000});
+        let cacheInfo=await lstat(cache).catch(error=>{if((error as NodeJS.ErrnoException).code==="ENOENT")return undefined;throw error;});
+        if(cacheInfo) {
+          if(!cacheInfo.isDirectory() || cacheInfo.isSymbolicLink() || await realpath(cache)!==cache)throw new Error("Managed repository cache is unsafe.");
+          if((await git(["--git-dir",cache,"rev-parse","--is-bare-repository"])).output!=="true")throw new Error("Managed repository cache is invalid.");
+          const existing=(await git(["--git-dir",cache,"remote","get-url","origin"])).output;
+          if(existing!==remote)throw new Error("Managed repository cache does not match the selected repository.");
+        } else {
+          await git(["-c","core.hooksPath=/dev/null","clone","--bare","--template=","--",remote,cache]);
+          cacheInfo=await lstat(cache);
+          if(!cacheInfo.isDirectory() || cacheInfo.isSymbolicLink())throw new Error("Repository checkout did not create a safe cache.");
+          await chmod(cache,0o700);
+        }
+        await git(["--git-dir",cache,"-c","core.hooksPath=/dev/null","fetch","--prune","origin",`+refs/heads/${baseBranch}:refs/remotes/origin/${baseBranch}`]);
+        const baseline=(await git(["--git-dir",cache,"rev-parse",`refs/remotes/origin/${baseBranch}^{commit}`])).output;
+        if(!validSHA(baseline))throw new Error("Selected base branch does not resolve to a commit.");
+
+        const existingWorkspace=await lstat(workspace).catch(error=>{if((error as NodeJS.ErrnoException).code==="ENOENT")return undefined;throw error;});
+        if(existingWorkspace) {
+          if(!existingWorkspace.isDirectory() || existingWorkspace.isSymbolicLink() || await realpath(workspace)!==workspace)throw new Error("Existing task worktree is unsafe.");
+          const marker=await readMarker(workspace,cache);
+          if(marker.run!==lease.id || marker.lifecycle!==lease.lifecycle || marker.project!==projectId || marker.repository!==repository || marker.base_branch!==baseBranch || marker.branch!==branch || !validSHA(marker.baseline))throw new Error("Existing task worktree identity does not match this lease.");
+          return {path:workspace,branch,baseline:marker.baseline};
+        }
+
+        await git(["--git-dir",cache,"worktree","add","--force","--detach",workspace,baseline]);
+        await git(["-C",workspace,"-c","core.hooksPath=/dev/null","switch","-C",branch,"--ignore-other-worktrees",baseline]);
+        await git(["-C",workspace,"config","user.name",credential.author_name]);
+        await git(["-C",workspace,"config","user.email",credential.author_email]);
+        await git(["-C",workspace,"config","core.hooksPath","/dev/null"]);
+        const gitdir=await worktreeGitDirectory(workspace,cache);
+        await writeFile(join(gitdir,"orchestrator.json"),JSON.stringify({run:lease.id,lifecycle:lease.lifecycle,project:projectId,repository,base_branch:baseBranch,baseline,branch} satisfies Marker),{mode:0o600,flag:"wx"});
+        return {path:workspace,branch,baseline};
+      });
+    } catch(error) {
+      throw error instanceof Error && /Task repository|Managed repository|Selected base|Existing task|Task worktree/.test(error.message)
+        ? error
+        : new Error("Repository setup failed. Check GitHub App access, repository selection, base branch, and local storage.",{cause:error});
+    } finally {
+      await release();
+    }
+  }
+
+  async writeProjectInstructions(workspace:string,instructions:unknown):Promise<string|undefined> {
+    if(typeof instructions!=="string" || Buffer.byteLength(instructions,"utf8")>32_000)throw new Error("Project instructions snapshot is invalid.");
+    const canonical=await realpath(workspace);
+    if(!isAbsolute(workspace) || canonical!==resolve(workspace))throw new Error("Task worktree path must be canonical.");
+    const pointer=await readFile(join(canonical,".git"),"utf8");
+    const match=pointer.match(/^gitdir: (.+)\r?\n?$/);
+    if(!match)throw new Error("Task worktree Git pointer is invalid.");
+    const gitdir=await realpath(resolve(canonical,match[1]));
+    const cache=dirname(dirname(gitdir));
+    const marker=await readMarker(canonical,cache);
+    const target=join(canonical,`.dev-orchestrator-instructions-${marker.run}-${marker.lifecycle}.md`);
+    const release=await acquireLock(cache+".lock");
+    try {
+      const existing=await lstat(target).catch(error=>{if((error as NodeJS.ErrnoException).code==="ENOENT")return undefined;throw error;});
+      if(existing?.isSymbolicLink() || (existing && !existing.isFile()))throw new Error("Project instructions target is unsafe.");
+      if(instructions==="") {
+        if(existing)await unlink(target);
+        return undefined;
+      }
+      if(existing) {
+        if(await readFile(target,"utf8")!==instructions)throw new Error("Project instructions target already exists with different content.");
+        return target;
+      }
+      const excludeDirPath=join(cache,"info");
+      await mkdir(excludeDirPath,{recursive:true,mode:0o700});
+      const excludeDir=await realpath(excludeDirPath);
+      if(!excludeDir.startsWith(cache+sep))throw new Error("Worktree ignore metadata escaped its Git directory.");
+      const excludeDirInfo=await lstat(excludeDirPath);
+      if(!excludeDirInfo.isDirectory() || excludeDirInfo.isSymbolicLink())throw new Error("Worktree ignore metadata is unsafe.");
+      const excludePath=join(excludeDir,"exclude");
+      await writeFile(excludePath,"",{encoding:"utf8",mode:0o600,flag:"wx"}).catch(error=>{
+        if((error as NodeJS.ErrnoException).code!=="EEXIST")throw error;
+      });
+      const excludeInfo=await lstat(excludePath);
+      if(!excludeInfo.isFile() || excludeInfo.isSymbolicLink())throw new Error("Worktree ignore metadata is unsafe.");
+      const exclude=await readFile(excludePath,"utf8");
+      const rule=`/${basename(target)}`;
+      if(!exclude.split(/\r?\n/).includes(rule)) {
+        const excludeTemp=join(excludeDir,`.exclude-${randomUUID()}`);
+        try {
+          await writeFile(excludeTemp,exclude+(exclude.endsWith("\n")||exclude===""?"":"\n")+rule+"\n",{encoding:"utf8",mode:0o600,flag:"wx"});
+          await rename(excludeTemp,excludePath);
+        } catch(error) {
+          await unlink(excludeTemp).catch(()=>{});
+          throw error;
+        }
+      }
+      const temporary=join(canonical,`.instructions-${randomUUID()}`);
+      try {
+        await writeFile(temporary,instructions,{encoding:"utf8",mode:0o600,flag:"wx"});
+        await chmod(temporary,0o600);
+        await rename(temporary,target);
+        return target;
+      } catch(error) {
+        await unlink(temporary).catch(()=>{});
+        throw error;
+      }
+    } finally {await release();}
+  }
+
+  async markTerminal(workspace:string,outcome:"success"|"failure"):Promise<void> {
+    const canonical=await realpath(workspace);
+    if(!isAbsolute(workspace) || canonical!==resolve(workspace))throw new Error("Task worktree path must be canonical.");
+    const cache=await workspaceCache(canonical);
+    const gitdir=await worktreeGitDirectory(canonical,cache);
+    await readMarker(canonical,cache);
+    const terminalPath=join(gitdir,"terminal.json");
+    const existing=await lstat(terminalPath).catch(error=>{if((error as NodeJS.ErrnoException).code==="ENOENT")return undefined;throw error;});
+    if(existing) {
+      if(!existing.isFile() || existing.isSymbolicLink() || (existing.mode&0o077)!==0)throw new Error("Task terminal marker is unsafe.");
+      const previous=JSON.parse(await readFile(terminalPath,"utf8")) as {outcome?:unknown};
+      if(previous.outcome!==outcome)throw new Error("Task terminal outcome changed unexpectedly.");
+      return;
+    }
+    await writeFile(terminalPath,JSON.stringify({outcome,recorded_at:Date.now()}),{mode:0o600,flag:"wx"});
+  }
+
+  async cleanupExpired(root:string,protectedWorkspace?:string,now=Date.now()):Promise<number> {
+    const canonicalRoot=await ensureDirectory(root);
+    const workspacesRoot=join(canonicalRoot,"workspaces");
+    const entries=await readdir(workspacesRoot,{withFileTypes:true}).catch(error=>{
+      if((error as NodeJS.ErrnoException).code==="ENOENT")return [];
+      throw error;
+    });
+    let removed=0;
+    for(const entry of entries) {
+      if(!entry.isDirectory() || entry.isSymbolicLink())continue;
+      const workspace=join(workspacesRoot,entry.name);
+      if(workspace===protectedWorkspace)continue;
+      try {
+        if(await realpath(workspace)!==workspace)continue;
+        const cache=await workspaceCache(workspace);
+        const marker=await readMarker(workspace,cache);
+        if(entry.name!==`${marker.run}-${marker.lifecycle}`)continue;
+        const terminalPath=join(await worktreeGitDirectory(workspace,cache),"terminal.json");
+        const terminalInfo=await lstat(terminalPath);
+        if(!terminalInfo.isFile() || terminalInfo.isSymbolicLink() || (terminalInfo.mode&0o077)!==0)continue;
+        const terminal=JSON.parse(await readFile(terminalPath,"utf8")) as {outcome?:unknown;recorded_at?:unknown};
+        if(!["success","failure"].includes(String(terminal.outcome)) || typeof terminal.recorded_at!=="number")continue;
+        const retention=terminal.outcome==="success"?24*60*60_000:7*24*60*60_000;
+        if(now-terminal.recorded_at<retention)continue;
+        if(await realpath(cache)!==cache)continue;
+        const release=await acquireLock(cache+".lock");
+        try {
+          await this.runCommand("git",["--git-dir",cache,"-c","core.hooksPath=/dev/null","worktree","remove","--force",workspace],{env:{PATH:process.env.PATH,HOME:process.env.HOME,GIT_CONFIG_NOSYSTEM:"1",GIT_CONFIG_GLOBAL:"/dev/null"},timeout:30_000});
+          await rm(workspace,{recursive:true,force:true});
+          removed++;
+        } finally {await release();}
+      } catch { /* Unknown or unsafe worktrees are retained for manual recovery. */ }
+    }
+    return removed;
+  }
+}

package/src/types.ts

@@ -0,0 +1,6 @@
+export type Config = { version: 2; server: string; token: string; codexBinary?: string };
+export type TokenPurpose = "checkout" | "publish";
+export type GitHubCredential = { token: string; expires_at: string; author_name: string; author_email: string };
+export type Lease = { id: string; generation: number; lifecycle: number; project_id?: string; title?: string; prompt?: string; source_key?: string; snapshot?: Record<string, unknown>; expires_in_ms?: number; sequence?: number };
+export type RunEvent = { sequence: number; kind: string; data: Record<string, unknown> };
+export type JournalState = { lease: Lease; sequence: number; pending_event?: RunEvent; workspace?: string; baseline?: string };

package/src/worker.ts

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { dirname } from "node:path";
+import { Journal } from "./journal.ts";
+import { API, APIError } from "./api.ts";
+import { CodexSession, RepeatedFailureError, CodexBlockedError } from "./codex.ts";
+import { RepositoryWorkspace } from "./repository.ts";
+import { Publisher, type PublicationContext } from "./publisher.ts";
+import type { Config, JournalState } from "./types.ts";
+
+type Transport={post:(path:string,payload:unknown)=>Promise<any>};
+type ExecutionDependencies={dataRoot?:string;repositories?:RepositoryWorkspace;publisherFactory?:(context:PublicationContext)=>Publisher};
+
+export async function emitDurably(api:Transport,journal:Journal,state:JournalState,kind:string,data:Record<string,unknown>):Promise<any> {
+  if(state.pending_event)throw new Error("A previous event still needs acknowledgement.");
+  state.sequence++;
+  state.pending_event={sequence:state.sequence,kind,data};
+  await journal.save(state);
+  const result=await api.post("/executor/events",{lease:state.lease,event:state.pending_event});
+  delete state.pending_event;
+  await journal.save(state);
+  return result;
+}
+
+export async function recover(api:Transport,journal:Journal,repositories?:RepositoryWorkspace,dataRoot?:string):Promise<void> {
+  const state=await journal.load();
+  if(!state)return;
+  const result=await api.post("/executor/reconcile",{lease:state.lease,journal:{pending_event:state.pending_event??null}});
+  let terminalState=result.state;
+  if(result.action==="replay" && state.pending_event) {
+    const kind=state.pending_event.kind;
+    const acknowledgement=await api.post("/executor/events",{lease:state.lease,event:state.pending_event});
+    if(["succeeded","blocked","failed","cancelled"].includes(acknowledgement?.state))terminalState=acknowledgement.state;
+    if(["started","progress"].includes(kind))terminalState=(await api.post("/executor/reconcile",{lease:state.lease,journal:{pending_event:null}})).state;
+  } else if(result.action!=="acknowledge")throw new Error("Task reconciliation needs operator attention.");
+  if(state.workspace && repositories && dataRoot && ["succeeded","blocked","failed","cancelled"].includes(terminalState)) {
+    await repositories.markTerminal(state.workspace,terminalState==="succeeded"?"success":"failure");
+  }
+  await journal.clear();
+}
+
+export async function runLoop(config:Config,root:string,signal:AbortSignal):Promise<void> {
+  const api=new API(config.server,config.token);
+  const journal=new Journal(root);
+  const repositories=new RepositoryWorkspace();
+  await recover(api,journal,repositories,dirname(root));
+  const health=CodexSession.start(config.codexBinary??"codex",root);
+  let authenticated=false;
+  try {await health.initialize();authenticated=await health.authenticated();}finally{health.stop();}
+  await api.post("/executor/heartbeat",{protocol:1,codex_authenticated:authenticated,platform:process.platform});
+  if(!authenticated)throw new Error("Sign in to the official Codex CLI with your own ChatGPT account before starting this connector.");
+  while(!signal.aborted) {
+    try {
+      await recover(api,journal,repositories,dirname(root));
+      await api.post("/executor/heartbeat",{protocol:1,codex_authenticated:true,platform:process.platform});
+      const claimStarted=performance.now();
+      const lease=await api.post("/executor/claim",{});
+      if(lease)await execute(config,api,journal,{lease,sequence:lease.sequence??0},claimStarted,signal,{dataRoot:dirname(root)});
+    } catch(error) {
+      if(signal.aborted)break;
+      if(error instanceof APIError && error.status===401)throw new Error("Executor access was revoked. Pair again with an authorized owner.");
+      console.error("Control-plane operation interrupted. Preserved task state; reconnecting without rerunning unacknowledged work.");
+    }
+    await new Promise(resolve=>setTimeout(resolve,5_000));
+  }
+}
+
+export async function execute(config:Config,api:Transport,journal:Journal,state:JournalState,claimStarted:number,signal:AbortSignal,dependencies:ExecutionDependencies={}):Promise<void> {
+  const controller=new AbortController();
+  let session:CodexSession|undefined;
+  let phase="github_installation_required";
+  let deadline=claimStarted+Math.min(state.lease.expires_in_ms??90_000,90_000)-5_000;
+  const abort=()=>{controller.abort();session?.stop();};
+  let workspacePath:string|undefined;
+  signal.addEventListener("abort",abort,{once:true});
+  const safety=setInterval(()=>{if(performance.now()>=deadline)abort();},250);
+  const renewal=setInterval(async()=>{
+    const started=performance.now();
+    try {
+      const result=await api.post("/executor/renew",state.lease);
+      if(!controller.signal.aborted)deadline=started+Math.min(result.expires_in_ms,90_000)-5_000;
+    } catch(error) {
+      if(error instanceof APIError && [401,409].includes(error.status))abort();
+      // A transport failure does not extend the last acknowledged deadline.
+    }
+  },20_000);
+  const timeBudget=setTimeout(abort,20*60_000);
+  try {
+    await journal.save(state);
+    await emitDurably(api,journal,state,"started",{});
+    await emitDurably(api,journal,state,"progress",{stage:"repository_preparing"});
+    const dataRoot=dependencies.dataRoot??dirname(journal.root);
+    const repositories=dependencies.repositories??new RepositoryWorkspace();
+    await repositories.cleanupExpired(dataRoot);
+    const credential=await api.post("/executor/github-token",{lease:state.lease,purpose:"checkout"});
+    phase="workspace_setup_failed";
+    const workspace=await repositories.prepare(dataRoot,state.lease,credential);
+    workspacePath=workspace.path;
+    const snapshot=state.lease.snapshot??{};
+    const instructionsPath=await repositories.writeProjectInstructions(workspace.path,snapshot.instructions??"");
+    state.workspace=workspace.path;state.baseline=workspace.baseline;await journal.save(state);
+    if(controller.signal.aborted)throw new Error("Lease ended.");
+    await emitDurably(api,journal,state,"progress",{stage:"workspace_ready"});
+    phase="authentication_required";
+    session=CodexSession.start(config.codexBinary??"codex",workspace.path);
+    await session.initialize();
+    if(!await session.authenticated())throw new Error("Local account is not signed in.");
+    phase="execution_failed";
+    const prompt=[
+      "Implement this development task end to end in this isolated checkout.",
+      "Read and respect the repository's AGENTS.md and project-scoped skills. Do not change global skills or configuration.",
+      "Validate changes and create a Conventional Commit on the existing issue branch. Do not push, create a PR, merge, or deploy: the trusted connector handles publication after your turn.",
+      "Do not invent external access or credentials. If essential context is missing, report a real blocker. Network access is disabled in this evaluation sandbox.",
+      instructionsPath
+        ? "Project instructions: read and follow the file at "+instructionsPath+" before making changes."
+        : "Project instructions:\n"+String(snapshot.instructions??""),
+      "Task: "+String(state.lease.title??""),String(state.lease.prompt??"")
+    ].join("\n\n");
+    await session.run(
+      workspace.path,
+      prompt,
+      typeof snapshot.model==="string"?snapshot.model:undefined,
+      controller.signal,
+      stage=>emitDurably(api,journal,state,"progress",{stage})
+    );
+    session.stop();session=undefined;
+    phase="publication_failed";
+    await api.post("/executor/renew",state.lease);
+    const publicationContext={workspace:workspace.path,repository:String(snapshot.repository??""),baseBranch:String(snapshot.base_branch??""),branch:workspace.branch,baseline:workspace.baseline};
+    const publisher=dependencies.publisherFactory?.(publicationContext)??new Publisher(publicationContext);
+    const status=await publisher.status(controller.signal);
+    if(status.changed) {
+      await emitDurably(api,journal,state,"progress",{stage:"publishing"});
+      const publishCredential=await api.post("/executor/github-token",{lease:state.lease,purpose:"publish"});
+      const result=await publisher.publish(state.lease.title??"Development task",`## Summary\n\nCompleted by the customer-owned local executor.\n\n## Validation\n\nReview the committed changes and repository checks before merging.\n\nRun: ${state.lease.id}`,publishCredential,controller.signal);
+      if(controller.signal.aborted)throw new Error("Lease ended.");
+      await emitDurably(api,journal,state,"progress",{stage:"pr_verifying"});
+      const acknowledgement=await emitDurably(api,journal,state,"candidate",result);
+      if(acknowledgement?.state==="succeeded")await repositories.markTerminal(workspace.path,"success").catch(()=>{});
+    } else {
+      const acknowledgement=await emitDurably(api,journal,state,"no_changes",{});
+      if(acknowledgement?.state==="succeeded")await repositories.markTerminal(workspace.path,"success").catch(()=>{});
+    }
+    await journal.clear();
+  } catch(error) {
+    session?.stop();
+    if(controller.signal.aborted || state.pending_event)throw error;
+    if(error instanceof APIError && ["github_installation_required","github_permission_denied","base_branch_missing","github_unavailable","local_policy_denied"].includes(error.code))phase=error.code;
+    else if(error instanceof APIError && error.code==="provider_authentication")phase="github_permission_denied";
+    else if(error instanceof APIError && ["provider_rejected","provider_rate_limit","provider_unavailable"].includes(error.code))phase="github_unavailable";
+    else if(error instanceof Error && /Selected base branch does not resolve to a commit/i.test(error.message))phase="base_branch_missing";
+    else if(error instanceof Error && /Repository setup failed|worktree|managed repository cache|Task repository snapshot/i.test(error.message))phase="workspace_setup_failed";
+    if(error instanceof CodexBlockedError)phase="missing_context";
+    const fingerprint=error instanceof RepeatedFailureError?error.fingerprint:createHash("sha256").update(phase+":"+(error instanceof Error?error.message:"unknown")).digest("hex");
+    const kind=["authentication_required","local_policy_denied","github_installation_required","github_permission_denied","base_branch_missing","missing_context","workspace_setup_failed"].includes(phase)?"blocked":"failure";
+    const acknowledgement=await emitDurably(api,journal,state,kind,{category:phase,fingerprint,occurrences:error instanceof RepeatedFailureError?3:1});
+    if(workspacePath && ["blocked","cancelled","failed"].includes(acknowledgement?.state)) {
+      await (dependencies.repositories??new RepositoryWorkspace()).markTerminal(workspacePath,"failure").catch(()=>{});
+    }
+    await journal.clear();
+  } finally {
+    clearInterval(safety);clearInterval(renewal);clearTimeout(timeBudget);
+    signal.removeEventListener("abort",abort);session?.stop();
+  }
+}

package/src/workspace.ts

@@ -0,0 +1,2 @@
+export const validBranch=(value:unknown):value is string=>typeof value==="string" && value.length<=200 && /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value) && !value.includes("..") && !value.includes("//") && value.split("/").every(part=>part && !part.startsWith(".") && !part.endsWith(".") && !part.endsWith(".lock"));
+export const validRepository=(value:unknown):value is string=>typeof value==="string" && value.length<=200 && /^[A-Za-z0-9][A-Za-z0-9_-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes("..") && !value.endsWith(".git");