Phase 2: local-folder jobs work end-to-end (the zero-GitHub path)

This project mostly runs locally on people's own machines/servers, and the local-folder
job kind is the zero-setup path: point pi at a folder, run a flow. It needs NO GitHub App,
no webhook, no scoped token -- only a provider API key. The processor already skips minting
and branch-checks for kind:local; this makes the path real.

prepare-local.mjs: for a local folder that is a git repo, resolve HEAD and materialise .pi/
from it through the SAME symlink/submodule-safe git path as GitHub jobs -- so instructions
come from a committed ref (read-only) while work happens on the working tree bind-mounted at
/workspace, edited in place. The task text is data, written to /job/prompt.md. A non-git
folder is a clear config error (v1 requires one), not a crash. Tested against a real local
git repo including a hostile symlink object: it is rejected locally exactly as for GitHub.

Verified END TO END against the real image, with no GitHub anything: prepared a real local
git folder, mounted it as /workspace and the job dir as /job:ro, launched the real pi image.
The runner read /job/prompt.md, found the model claude-sonnet-4-5 in the registry, and
stopped at "no configured auth" (exit 2) -- exactly the boundary a provider key crosses. The
whole local plumbing works; only the operator's API key is missing.

Fixed a real mount bug the e2e exposed: buildDockerRunArgs mounted only the .pi/ subdir at
/job/pi, so /job/prompt.md was invisible and every job would have died with "missing job
input". It now mounts the WHOLE job dir at /job:ro (prompt.md AND pi/), matching
INT-CONTAINER-JOB-INPUTS. The unit test was masking this by only asserting the pi mount --
the running container is what caught it, again.

Recalibration: I had framed a GitHub App as the blocker for Phase 2. It is not -- it gates
only the GitHub job kind. The local path is fully buildable and verifiable now, and is the
primary experience for a self-hosted OSS user. The GitHub token-minting and
branch-protection pieces still want an App to verify rather than guess, but they are one of
two paths, not the critical one.

Author: edgehero

worker/src/docker-run.mjs

@@ -24,7 +24,7 @@ export const ISOLATION_FLAGS = [
  *
  * @param image      pinned job image tag/digest
  * @param env        the closed env map from buildContainerEnv -- passed as explicit -e NAME=VALUE
- * @param jobPiDir   host path to the materialised .pi/ (mounted /job/pi:ro)
+ * @param jobDir     host path to the /job inputs dir (contains prompt.md and pi/); mounted /job:ro
  * @param workspace  host path to the fresh clone / local folder (mounted /workspace:rw)
  * @param name       container name (for `docker stop` at the timeout)
  * @param memory     e.g. "4g"; cpus e.g. "2"
@@ -33,7 +33,7 @@ export const ISOLATION_FLAGS = [
 export function buildDockerRunArgs({
 	image,
 	env,
-	jobPiDir,
+	jobDir,
 	workspace,
 	name,
 	memory = "4g",
@@ -54,9 +54,9 @@ export function buildDockerRunArgs({
 		args.push("-e", `${k}=${v}`);
 	}
 
-	// /job is read-only (INT-CONTAINER-JOB-INPUTS): the agent cannot rewrite its own instructions.
-	// /workspace is the only writable mount.
-	if (jobPiDir) args.push("-v", `${jobPiDir}:/job/pi:ro`);
+	// The WHOLE /job dir is read-only (INT-CONTAINER-JOB-INPUTS): it holds prompt.md and pi/, and
+	// the agent cannot rewrite any of it. /workspace is the only writable mount.
+	if (jobDir) args.push("-v", `${jobDir}:/job:ro`);
 	args.push("-v", `${workspace}:/workspace`);
 
 	args.push(image);

worker/src/prepare-local.mjs

@@ -0,0 +1,53 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { materializePiDir } from "./materialize.mjs";
+
+const exec = promisify(execFile);
+
+/**
+ * Prepare a LOCAL-FOLDER job. This is the zero-GitHub path: no token, no clone, no PR. The folder
+ * on the operator's own machine becomes /workspace (bind-mounted read-write), edited in place.
+ *
+ * For v1 the folder must be a git repository, which buys two things for free: a stable ref (HEAD)
+ * to read instructions from, and git's object model, so `.pi/` materialises through the same
+ * symlink/submodule-safe path as GitHub jobs (materializePiDir). Instructions come from HEAD
+ * (committed, reviewed); work happens on the working tree in /workspace. A non-git folder is a
+ * documented v1 limitation -- `git init` it first.
+ *
+ * The task text is DATA (CONST-ISSUE-TEXT-IS-DATA): it goes into /job/prompt.md, never the
+ * instructions. The operator supplies it from the panel.
+ */
+export async function prepareLocalWorkspace({ folder, task, jobDir, git = defaultGit }) {
+	if (!existsSync(folder)) {
+		const error = new Error(`local folder does not exist: ${folder}`);
+		error.piDispatchConfig = true;
+		throw error;
+	}
+	if (!existsSync(join(folder, ".git"))) {
+		const error = new Error(`local folder is not a git repository (v1 requires one): ${folder}`);
+		error.piDispatchConfig = true;
+		throw error;
+	}
+
+	const sha = (await git(folder, ["rev-parse", "HEAD"])).trim();
+
+	mkdirSync(jobDir, { recursive: true });
+	// Instructions from HEAD, via the symlink-safe git materialiser, into /job/pi (mounted :ro).
+	const written = await materializePiDir({ gitDir: folder, sha, destDir: jobDir });
+
+	// The task the operator asked for. Plain data below the instructions.
+	writeFileSync(join(jobDir, "prompt.md"), String(task ?? ""), { mode: 0o444 });
+
+	// The folder itself is /workspace (rw). No clone: local jobs edit in place.
+	return { workspace: folder, jobDir, sha, materialised: written };
+}
+
+async function defaultGit(gitDir, args) {
+	const { stdout } = await exec("git", ["-c", "core.hooksPath=/dev/null", "--no-pager", "-C", gitDir, ...args], {
+		encoding: "utf8",
+		maxBuffer: 16 * 1024 * 1024,
+	});
+	return stdout;
+}

worker/test/docker-run.test.mjs

@@ -5,7 +5,7 @@ import { buildDockerRunArgs, ISOLATION_FLAGS } from "../src/docker-run.mjs";
 const base = {
 	image: "pi-job:pinned",
 	env: { PI_PROVIDER: "anthropic", ANTHROPIC_API_KEY: "sk-real" },
-	jobPiDir: "/srv/jobs/abc/pi",
+	jobDir: "/srv/jobs/abc/job",
 	workspace: "/srv/jobs/abc/workspace",
 	name: "pi-job-abc",
 };
@@ -23,7 +23,7 @@ test("carries every isolation flag -- these ARE the boundary", () => {
 
 test("/job is read-only, /workspace is writable", () => {
 	const args = buildDockerRunArgs(base);
-	assert.ok(args.includes("/srv/jobs/abc/pi:/job/pi:ro"), "/job/pi must be :ro");
+	assert.ok(args.includes("/srv/jobs/abc/job:/job:ro"), "the whole /job must be :ro");
 	assert.ok(args.includes("/srv/jobs/abc/workspace:/workspace"), "/workspace must be writable");
 	assert.ok(!args.some((a) => a.includes("/workspace:ro")), "/workspace must not be read-only");
 });

worker/test/prepare-local.test.mjs

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { prepareLocalWorkspace } from "../src/prepare-local.mjs";
+
+function git(dir, args) {
+	return execFileSync("git", ["-C", dir, ...args], {
+		encoding: "utf8",
+		env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" },
+	});
+}
+
+/** A local git repo with a .pi/ persona and skill, plus a working-tree file to "edit". */
+function localRepo() {
+	const dir = mkdtempSync(join(tmpdir(), "pi-local-"));
+	git(dir, ["init", "-q"]);
+	git(dir, ["config", "core.autocrlf", "false"]);
+	const blob = (c) => execFileSync("git", ["-C", dir, "hash-object", "-w", "--stdin"], { input: c, encoding: "utf8" }).trim();
+	git(dir, ["update-index", "--add", "--cacheinfo", `100644,${blob("LOCAL-PERSONA-SENTINEL")},.pi/APPEND_SYSTEM.md`]);
+	git(dir, [
+		"update-index",
+		"--add",
+		"--cacheinfo",
+		`100644,${blob("---\nname: tidy\ndescription: tidy up\n---\nsteps\n")},.pi/skills/tidy/SKILL.md`,
+	]);
+	// a hostile symlink object, to prove the local path is as safe as the GitHub path
+	git(dir, ["update-index", "--add", "--cacheinfo", `120000,${blob("/etc/passwd")},.pi/EVIL.md`]);
+	git(dir, ["commit", "-qm", "x"]);
+	return dir;
+}
+
+test("prepares a local git folder: materialises .pi/ from HEAD, writes the task, folder is /workspace", async () => {
+	const folder = localRepo();
+	const jobDir = mkdtempSync(join(tmpdir(), "pi-job-"));
+	const result = await prepareLocalWorkspace({ folder, task: "please tidy the imports", jobDir });
+
+	assert.equal(result.workspace, folder, "the folder itself is the workspace (edited in place)");
+	assert.equal(readFileSync(join(jobDir, "prompt.md"), "utf8"), "please tidy the imports");
+	assert.equal(readFileSync(join(jobDir, "pi/APPEND_SYSTEM.md"), "utf8"), "LOCAL-PERSONA-SENTINEL");
+	assert.ok(result.materialised.includes("pi/skills/tidy/SKILL.md"));
+	// the symlink is NOT materialised -- the local path inherits the git materialiser's safety
+	assert.ok(!result.materialised.some((p) => p.includes("EVIL")), "a hostile symlink must not materialise locally either");
+});
+
+test("no GitHub anything: a local job needs no token, no repo, no network", async () => {
+	// This test passing at all -- with no octokit, no token, no clone URL -- IS the assertion.
+	const folder = localRepo();
+	const jobDir = mkdtempSync(join(tmpdir(), "pi-job-"));
+	const result = await prepareLocalWorkspace({ folder, task: "x", jobDir });
+	assert.ok(result.sha.match(/^[0-9a-f]{40}$/), "resolved HEAD locally, offline");
+});
+
+test("a non-git folder is a clear config error, not a crash", async () => {
+	const plain = mkdtempSync(join(tmpdir(), "pi-plain-"));
+	await assert.rejects(
+		() => prepareLocalWorkspace({ folder: plain, task: "x", jobDir: mkdtempSync(join(tmpdir(), "j-")) }),
+		(e) => e.piDispatchConfig === true && /not a git repository/.test(e.message),
+	);
+});
+
+test("a missing folder is a clear config error", async () => {
+	await assert.rejects(
+		() => prepareLocalWorkspace({ folder: "/does/not/exist/anywhere", task: "x", jobDir: "/tmp/x" }),
+		(e) => e.piDispatchConfig === true,
+	);
+});