@edgehero/pi-dispatch 0.1.0

package/src/env-allowlist.mjs

@@ -0,0 +1,198 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { findEnvKeys } from "@earendil-works/pi-ai/compat";
+import { forgeSpec } from "./forges.mjs";
+
+function configError(message) {
+	const error = new Error(message);
+	error.piDispatchConfig = true;
+	return error;
+}
+
+/**
+ * Build the EXACT environment a job container receives. Never a pass-through.
+ *
+ * `no-broad-env-into-container` is a BLOCKER, and for good reason: `ANTHROPIC_OAUTH_TOKEN`
+ * silently outranks `ANTHROPIC_API_KEY`, so one stray host variable would redirect which
+ * credential every job spends, with no error and no log line. So we forward a closed set.
+ *
+ * The provider key variable is DERIVED from pi's own table, not hardcoded. `findEnvKeys(provider,
+ * env)` returns the provider's key variable names that are actually PRESENT in `env`, in
+ * precedence order (OAuth before API key). Deriving it means:
+ *   - any of pi's ~30 providers works with no code change here;
+ *   - the list cannot drift when pi adds a provider (a hand-copied table would);
+ *   - `undefined` return === "this provider is not configured on this host" === refuse the job
+ *     BEFORE spending, rather than launch a container that will fail auth on the first call.
+ *
+ * `getApiKeyEnvVars` (the full candidate list) is intentionally NOT exported by pi; `findEnvKeys`
+ * against our own process.env is the right tool anyway, because we only ever forward keys we have.
+ */
+export function providerKeyVars(provider, hostEnv) {
+	return findEnvKeys(provider, hostEnv);
+}
+
+/**
+ * Resolve the provider credential(s) to inject, as `{ VAR_NAME: value }`.
+ *
+ * Primary source: the worker's own environment, by pi's expected variable name(s) (`findEnvKeys`).
+ * Fallback (ON by default; `PI_AUTH_FROM_PI=0` forces env-only): when the env has none, read the credential
+ * from the host's pi `auth.json`. This is a HOST-SIDE read of a host-held secret, injected via env exactly
+ * like the env path — never a credential file mounted into the container (`CONST-TOKEN-SCOPED-PER-JOB`).
+ * API-key credentials only; an OAuth/subscription login is refused (it expires, the container cannot refresh
+ * it, and it is not the credential for an unattended service). Throws a config-tagged error (pre-spend
+ * refusal) when neither source yields a credential.
+ */
+export function resolveProviderCredential({ provider, hostEnv, authFromPi = false, agentDir, readFile = readFileSync }) {
+	const envNames = providerKeyVars(provider, hostEnv);
+	if (envNames && envNames.length > 0) {
+		return Object.fromEntries(envNames.map((name) => [name, hostEnv[name]]));
+	}
+	if (authFromPi) {
+		const { name, value } = credentialFromPiAuth(provider, agentDir ?? defaultAgentDir(hostEnv), readFile);
+		return { [name]: value };
+	}
+	throw configError(`provider ${provider} has no configured credential in the worker environment`);
+}
+
+function defaultAgentDir(hostEnv) {
+	// pi's getAgentDir() default, resolved without importing the whole pi SDK into the worker.
+	return hostEnv.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+}
+
+function credentialFromPiAuth(provider, agentDir, readFile) {
+	const path = join(agentDir, "auth.json");
+	let auth;
+	try {
+		auth = JSON.parse(readFile(path, "utf8"));
+	} catch {
+		throw configError(`no credential for provider "${provider}": not in the worker environment, and no pi login at ${path} — set the key in .env, or run \`pi login\``);
+	}
+	const cred = auth?.[provider];
+	if (!cred) throw configError(`no credential for provider "${provider}": not in the worker environment, and ${path} has no "${provider}" login — set the key in .env, or run \`pi login\``);
+	if (cred.type === "oauth") {
+		throw configError(
+			`the pi login for "${provider}" is an OAuth/subscription token, which cannot power an unattended service (it expires and the container cannot refresh it). Configure an API key — with a provider-side spend limit — instead.`,
+		);
+	}
+	if (cred.type !== "api_key" || !cred.key) throw configError(`unsupported pi credential for "${provider}" in ${path} — set an API key in .env`);
+	const name = resolveEnvName(provider, cred);
+	if (!name) {
+		throw configError(`could not determine the environment variable pi expects for provider "${provider}" — set it in the worker environment manually`);
+	}
+	return { name, value: cred.key };
+}
+
+/**
+ * The env var name pi reads this provider's key from. Discovered through pi's OWN `findEnvKeys` (the
+ * oracle) rather than a hand-maintained provider→var table that would drift: try the credential's own
+ * `env` hint plus the conventional `<PROVIDER>_API_KEY`/`_KEY`, and forward the one pi recognizes.
+ */
+function resolveEnvName(provider, cred) {
+	const upper = provider.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+	const candidates = [cred.env, `${upper}_API_KEY`, `${upper}_KEY`].filter((s) => typeof s === "string" && s.length > 0);
+	const synthetic = Object.fromEntries(candidates.map((name) => [name, cred.key]));
+	const recognized = findEnvKeys(provider, synthetic);
+	return recognized?.[0] ?? null;
+}
+
+/**
+ * Assemble the container env. `hostEnv` is the worker's process.env; `job` carries the resolved
+ * config and the per-job scoped token (GitHub-backed jobs, and local cron jobs that opted in via
+ * run.github).
+ *
+ * Throws if the provider is not configured -- a deterministic misconfiguration the caller maps to
+ * a pre-spend refusal, never a launched-then-failed container.
+ *
+ * `packagePaths` is the operator-staged pi package set for THIS job: already-resolved absolute
+ * CONTAINER paths under the :ro overlay, empty for a job whose trigger opted OUT (or when nothing is staged).
+ *
+ * `allowGlobalExtensions` defaults to TRUE here, matching loadConfig's default (REQ-GLOBAL-PI-OVERLAY): a
+ * caller that says nothing gets the operator's staged setup, and only an explicit `false` withholds it.
+ */
+export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], sessionFile = null, authFromPi = false, agentDir, readFile = readFileSync }) {
+	// The provider credential(s), by pi's expected variable name(s) -- from the worker env, or (when
+	// PI_AUTH_FROM_PI is set and the env has none) host-side from pi's auth.json. Throws (config) if
+	// neither source yields one, which the processor turns into a pre-spend refusal.
+	const credEnv = resolveProviderCredential({ provider, hostEnv, authFromPi, agentDir, readFile });
+
+	const env = {
+		PI_PROVIDER: provider,
+		PI_MODEL: model,
+		PI_MAX_TURNS: String(maxTurns),
+		// The optional per-job token budget (issue #25). Absent/null => variable omitted (docker-run skips
+		// undefined), so the runner attaches a pure meter with no cap. Never an empty string.
+		PI_MAX_TOKENS: maxTokens === null || maxTokens === undefined ? undefined : String(maxTokens),
+		PI_JOB_ID: jobId,
+		// Baked into the image, but harmless to restate; kept here so the container contract is
+		// visible in one place. INT-CONTAINER-RUNTIME-CONTRACT.
+		PLAYWRIGHT_BROWSERS_PATH: "/ms-playwright",
+		PLAYWRIGHT_MCP_BROWSER: "chromium",
+		PLAYWRIGHT_MCP_SANDBOX: "false",
+		// The overlay's extensions load in the runner unless the operator opted out (REQ-GLOBAL-PI-OVERLAY).
+		// ABSENT means LOAD on both sides of the mount, so this variable is emitted ONLY to carry the explicit
+		// "0" opt-out -- the one reading a container must never have to infer. Both halves agree on the same
+		// canonical string, so the container env is legible against the operator's own .env line.
+		PI_GLOBAL_ALLOW_EXTENSIONS: allowGlobalExtensions ? undefined : "0",
+		// ":"-delimited ABSOLUTE CONTAINER paths of the operator-staged pi packages (REQ-GLOBAL-PI-OVERLAY).
+		// The caller has already applied the per-trigger opt-out, so an empty list here means "this job loads
+		// none" -- either nothing is staged, or its trigger set run.packages:false. Empty emits no -e at all,
+		// never PI_PACKAGES=. The delimiter is ":" because these are CONTAINER (POSIX) paths -- never the
+		// host's path.delimiter, which is ";" on Windows.
+		PI_PACKAGES: packagePaths.length > 0 ? packagePaths.join(":") : undefined,
+		// The persisted transcript inside the /session mount (REQ-RESUMABLE-SESSION). Emitted ONLY when
+		// this job actually has one -- absent means the runner builds pi's ephemeral in-memory session,
+		// which is every job before this feature and every job whose trigger did not arm run.resume. Never
+		// an empty string, for PI_PACKAGES' reason: an empty value is a third state neither side reads the
+		// same way, and the one reading a container must not have to infer which was meant.
+		PI_SESSION_FILE: sessionFile || undefined,
+		// Kill switch for job-time package installation, UNCONDITIONAL for every job. pi's resolver shells out
+		// to a REAL `npm install` for any npm:/git: source unless offline mode is on, and `~/.pi/agent` IS
+		// writable in the container. We emit only local paths, so nothing should reach that branch -- this
+		// makes it UNREACHABLE rather than merely unused. It is a narrowing, never a capability, which is why
+		// it is not gated on the opt-in.
+		PI_OFFLINE: "1",
+	};
+
+	// The provider credential(s), under pi's expected variable name(s), so pi's own auth resolution finds them.
+	Object.assign(env, credEnv);
+
+	// Operator-declared extra vars (PI_FORWARD_ENV), forwarded by EXACT name -- the allowlist
+	// no-broad-env-into-container prescribes, not a host pass-through. This is how a CUSTOM provider's
+	// key (one pi's findEnvKeys table does not know) reaches the container. A name whose value is unset
+	// on the host is skipped, never forwarded as empty.
+	for (const name of forwardEnv) {
+		if (hostEnv[name] !== undefined) env[name] = hostEnv[name];
+	}
+
+	// Forge-backed jobs, and local cron jobs that opted in via run.github. Other local-folder jobs have
+	// no token (CONST-TOKEN-SCOPED-PER-JOB). The mint goes into BOTH of its forge's variables because
+	// each CLI has its own preference -- gh prefers GH_TOKEN over GITHUB_TOKEN, glab prefers GITLAB_TOKEN
+	// -- and mirroring forecloses any precedence surprise inside the container.
+	//
+	// The token goes ONLY into its own forge's names. A GitLab credential exported as GITHUB_TOKEN would
+	// be sent by `gh` to github.com on the agent's first tab-complete: a working credential handed to the
+	// wrong host, which is how a scoped token stops being scoped.
+	//
+	// This assignment deliberately sits AFTER the PI_FORWARD_ENV loop so a forwarded name can never
+	// override the mint (and loadConfig refuses those names at load anyway).
+	// Absent token => absent variable, never an empty one.
+	//
+	// The forge is looked UP, never fallen back to. This was an `if gitlab / else github`, and the `else`
+	// was the whole hazard: a job of any kind the table did not name -- a new forge wired up everywhere but
+	// here, a typo that survived validation -- got its credential exported as GITHUB_TOKEN and GH_TOKEN,
+	// which is precisely the "working credential handed to the wrong host" the paragraph above describes.
+	// A local cron job that opted in via run.github has kind "local" and genuinely wants GitHub's names, so
+	// it is mapped explicitly rather than inheriting them from a default.
+	if (githubToken) {
+		const spec = forgeSpec(forgeKind === "local" ? "github" : forgeKind);
+		if (!spec) {
+			throw configError(`buildContainerEnv: no token variable names for job kind ${JSON.stringify(forgeKind)} -- add it to FORGES in worker/src/forges.mjs rather than letting it inherit another forge's`);
+		}
+		for (const name of spec.tokenVars) env[name] = githubToken;
+		const host = forgeHosts?.[forgeKind];
+		if (spec.hostVar && host) env[spec.hostVar] = host;
+	}
+
+	return env;
+}

package/src/env-file.mjs

@@ -0,0 +1,153 @@
+/**
+ * Single-key edits to a dotenv-style file, in two disciplines.
+ *
+ * `setEnvKeyIfEmpty` exists for `pi-dispatch up`, which fills WEBHOOK_SECRET into a scaffolded .env
+ * without asking the operator to hand-run `openssl rand -hex 32`. It is init's contract applied to a
+ * single key instead of a whole file: init never overwrites an existing file, and this never
+ * overwrites an existing VALUE — a key the operator already set is sacrosanct, because a tool that
+ * "helpfully" rotates a live webhook secret breaks every configured forge hook at once, silently.
+ *
+ * `setEnvKey` is the CONSENTED-overwrite sibling, added for `pi-dispatch setup github` (issue #81),
+ * whose whole point is replacing values like GITHUB_AUTH_SOURCE=gh with the App credentials the
+ * operator just minted and approved line-by-line. The consent lives at the CALLER, never here.
+ *
+ * Both return the input text UNCHANGED (byte-identical, same object) when there is nothing to do, so
+ * callers can compare identity to know nothing happened.
+ *
+ * Deliberately dependency-free (node:fs only, and only in the thin wrapper): it must stay importable
+ * from any future setup command without dragging worker config or queue deps along.
+ */
+import { chmodSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+
+/**
+ * Pure transform over .env TEXT: set `key` to `value` only where nothing is set yet.
+ *
+ *   - `KEY=` (empty value, whitespace-only counts)      → that line becomes `KEY=value`, in place
+ *   - no set line, but a commented `# KEY=…` line       → the comment becomes `KEY=value`, in place
+ *   - no KEY line at all                                → `KEY=value` appended at the end
+ *   - `KEY=something` (any non-empty value, anywhere)   → text returned UNCHANGED
+ *
+ * Every other byte is preserved: lines are only ever replaced whole, CRLF endings survive on the
+ * replaced line, and the untouched remainder is never re-serialized. Ambiguity resolves to "do not
+ * touch" — a value like `KEY= # tbd` trims to a non-empty string and therefore counts as set, because
+ * the cost of wrongly leaving a key alone (operator sets it by hand) is a fraction of the cost of
+ * wrongly overwriting one.
+ */
+export function setEnvKeyIfEmpty(text, key, value) {
+	const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const setRe = new RegExp(`^\\s*${escaped}\\s*=(.*)$`);
+	const commentRe = new RegExp(`^\\s*#\\s*${escaped}\\s*=`);
+
+	const lines = text.split("\n");
+	// Replace a line wholesale, keeping a CRLF file's trailing \r so the file stays one convention.
+	const replaceLine = (i) => {
+		lines[i] = `${key}=${value}${lines[i].endsWith("\r") ? "\r" : ""}`;
+		return lines.join("\n");
+	};
+
+	// Pass 1: set lines. ANY non-empty value anywhere means the key is set — return the input text
+	// itself (not a copy) so callers can detect "unchanged" by identity. Otherwise remember the FIRST
+	// empty set line; a later commented duplicate must not win over it.
+	let firstEmpty = -1;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].endsWith("\r") ? lines[i].slice(0, -1) : lines[i];
+		const m = line.match(setRe);
+		if (!m) continue;
+		if (m[1].trim() !== "") return text;
+		if (firstEmpty === -1) firstEmpty = i;
+	}
+	if (firstEmpty !== -1) return replaceLine(firstEmpty);
+
+	// Pass 2: a commented-out `# KEY=` line (only reachable when no set line exists at all).
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].endsWith("\r") ? lines[i].slice(0, -1) : lines[i];
+		if (commentRe.test(line)) return replaceLine(i);
+	}
+
+	// Pass 3: no trace of the key — append at the end, on its own line.
+	const base = text === "" || text.endsWith("\n") ? text : `${text}\n`;
+	return `${base}${key}=${value}\n`;
+}
+
+/**
+ * Pure transform over .env TEXT: set `key` to `value`, REPLACING whatever is there. The overwrite
+ * sibling of `setEnvKeyIfEmpty`, with the same line mechanics and the same first-match position rules:
+ *
+ *   - a set line `KEY=anything` (empty or not, whitespace tolerated)  → becomes `KEY=value`, in place;
+ *     the FIRST set line wins over later duplicates and over any commented line
+ *   - no set line, but a commented `# KEY=…` line                     → the comment becomes `KEY=value`
+ *   - no KEY line at all                                              → `KEY=value` appended at the end
+ *   - the first set line is already exactly `KEY=value`               → text returned UNCHANGED
+ *     (the input string object itself, so callers detect the no-op by identity, like the sibling)
+ *
+ * THE CONFIRM GATE LIVES AT THE CALLER. This function is mechanical and will happily replace a live
+ * credential; the wizard that calls it shows the exact lines it is about to write and collects an
+ * explicit y/N first (github-app-setup.mjs). Nothing in here asks, because a transform that sometimes
+ * prompts is untestable and a prompt that sometimes doesn't fire is not a gate. Every other byte is
+ * preserved exactly as in the sibling: whole-line replacement only, CRLF survives on the replaced
+ * line, the untouched remainder is never re-serialized. A matched line with stray whitespace
+ * (`KEY = old`) is normalised to canonical `KEY=value` — it is being rewritten anyway.
+ */
+export function setEnvKey(text, key, value) {
+	const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const setRe = new RegExp(`^\\s*${escaped}\\s*=`);
+	const commentRe = new RegExp(`^\\s*#\\s*${escaped}\\s*=`);
+
+	const lines = text.split("\n");
+	const replaceLine = (i) => {
+		lines[i] = `${key}=${value}${lines[i].endsWith("\r") ? "\r" : ""}`;
+		return lines.join("\n");
+	};
+
+	// Pass 1: the FIRST set line, whatever its value — this is the overwrite discipline. Already
+	// exactly `KEY=value` (modulo the CRLF tail) → the input object back, so the wrapper skips the write.
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].endsWith("\r") ? lines[i].slice(0, -1) : lines[i];
+		if (!setRe.test(line)) continue;
+		if (line === `${key}=${value}`) return text;
+		return replaceLine(i);
+	}
+
+	// Pass 2: a commented-out `# KEY=` line (only reachable when no set line exists at all).
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].endsWith("\r") ? lines[i].slice(0, -1) : lines[i];
+		if (commentRe.test(line)) return replaceLine(i);
+	}
+
+	// Pass 3: no trace of the key — append at the end, on its own line.
+	const base = text === "" || text.endsWith("\n") ? text : `${text}\n`;
+	return `${base}${key}=${value}\n`;
+}
+
+/**
+ * Read → transform → write back ATOMICALLY (tmp + rename, the same shape as the admin's
+ * writeTriggers), so a watcher or a concurrent reader never sees a half-written .env. When the
+ * transform is a no-op the file is not touched at all — no tmp, no rename, no mtime churn — and
+ * `{ changed: false }` is returned so callers can say so.
+ *
+ * `overwrite` picks the transform: false (the default, and the only behaviour that existed before
+ * issue #81) applies `setEnvKeyIfEmpty`'s never-clobber discipline; true applies `setEnvKey`, for
+ * callers that have already shown the operator the exact line and collected consent — the gate is
+ * theirs, this wrapper stays mechanical either way.
+ *
+ * Mode: a .env at 0o600 (an operator who locked their secrets down) stays 0o600 — chmod on the tmp
+ * BEFORE the rename, so no window exists where the secret-bearing file is wider than it was. Any
+ * other mode is left to the platform default; this helper preserves a hardening choice, it does not
+ * impose one.
+ */
+export function updateEnvFile(path, key, value, deps = {}) {
+	const { fs = { readFileSync, writeFileSync, renameSync, statSync, chmodSync }, overwrite = false } = deps;
+	const text = fs.readFileSync(path, "utf8");
+	const next = (overwrite ? setEnvKey : setEnvKeyIfEmpty)(text, key, value);
+	if (next === text) return { changed: false };
+	const tmp = `${path}.tmp`;
+	fs.writeFileSync(tmp, next);
+	try {
+		if ((fs.statSync(path).mode & 0o777) === 0o600) fs.chmodSync(tmp, 0o600);
+	} catch {
+		// The file vanished between read and write, or the fs cannot stat: leave the tmp's default
+		// mode rather than failing an edit that is otherwise sound.
+	}
+	fs.renameSync(tmp, path);
+	return { changed: true };
+}

package/src/exit-code.mjs

@@ -0,0 +1,32 @@
+/**
+ * INT-RUNNER-EXIT-CODE-PROTOCOL, worker side.
+ *
+ * The container's exit code is the ONLY channel telling "the agent ran and concluded something"
+ * from "the container died". The worker turns that into BullMQ's throw-vs-return, which IS
+ * CONST-RETRY-INFRA-ONLY: a thrown processor is retried, a returned one is not.
+ */
+export const EXIT_COMPLETED = 0; // agent ran, INCLUDING "I cannot fix this" -- a determinate success
+export const EXIT_INFRA = 1; // container died, network, provider 5xx/429 -- the only retryable class
+export const EXIT_POLICY = 2; // budget/turn cap/config -- a determinate refusal, never retried
+
+/**
+ * Decide whether the processor should RETURN (BullMQ records success, no retry) or THROW (BullMQ
+ * retries per `attempts`). Returns `{ retry }`; the caller returns on false and throws on true.
+ *
+ * Only exit 1 is retryable. 0 and 2 are both determinate outcomes -- the agent's verdict (or our
+ * own budget refusal) is the product, not a failure to paper over by paying for it again. An
+ * unknown code is treated as infra: a runner that exits with something we do not recognise is a
+ * runner we cannot reason about, and retrying-then-alerting beats silently accepting it as done.
+ */
+export function decideRetry(exitCode) {
+	switch (exitCode) {
+		case EXIT_COMPLETED:
+			return { retry: false, outcome: "completed" };
+		case EXIT_POLICY:
+			return { retry: false, outcome: "policy" };
+		case EXIT_INFRA:
+			return { retry: true, outcome: "infra" };
+		default:
+			return { retry: true, outcome: `unknown-exit-${exitCode}` };
+	}
+}

package/src/flow-gate.mjs

@@ -0,0 +1,82 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+
+/**
+ * Read a flow's AI-trigger opt-in from the git OBJECT STORE at a pinned commit.
+ *
+ * A flow is AI-triggerable only if `.pi/skills/<flow>/SKILL.md` at `sha` carries `ai-trigger: allow`
+ * in its YAML frontmatter. `sha` is a REQUIRED input captured BEFORE the in-container agent runs, so
+ * it is agent-uninfluenceable: an agent cannot self-authorize by committing its own `SKILL.md`,
+ * because any `allow` it writes lands in a commit later than the pinned `sha` and is never consulted.
+ * This module therefore resolves NO ref — no HEAD, no rev-parse, no ref primitive of any kind — the
+ * caller supplies the SHA. (DES-AI-TRIGGER-FLOW-GATE, INT-OUTBOX-CONTRACT.)
+ *
+ * The read is object-store-only, mirroring materialize.mjs's blob-only discipline: enumerate the one
+ * exact path with `git ls-tree` at `sha`, require a single regular blob (type `blob`, mode `100644`
+ * — rejecting a 120000 symlink or 160000 gitlink), then `git cat-file blob <oid>`. The working tree
+ * is never read, so a frontmatter symlinked at a token file cannot escape the tree.
+ *
+ * Fail-closed everywhere — only an exact `ai-trigger: allow` yields `allow`:
+ *   - missing/empty `sha`                         -> deny  (never falls back to HEAD)
+ *   - `flow` failing the skill charset            -> deny  (never interpolated; traversal choke)
+ *   - SKILL.md absent at that path/sha            -> no-skill
+ *   - entry present but non-blob / wrong mode     -> deny
+ *   - unparseable / absent `---` frontmatter      -> deny
+ *   - `ai-trigger` key absent                     -> deny
+ *   - `ai-trigger` present but not exactly `allow`-> deny
+ *   - git error / bad sha / binary failure        -> deny  (caught; this function never throws)
+ */
+
+// The skill name charset: lowercase kebab/underscore, 1-64 chars, no dots (so no "..") and no
+// slashes. Mirrors materialize.mjs SKILL_NAME_RE (not exported there) — keep in sync. Validating
+// `flow` against it BEFORE building any path is the traversal choke point: a bad name is denied,
+// never interpolated into a git path.
+const SKILL_NAME_RE = /^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$/;
+
+export async function readFlowGate({ folder, flow, sha, git = defaultGit }) {
+	// `sha` is REQUIRED and never defaulted: a missing SHA fails closed rather than resolving HEAD,
+	// which would let a self-authored commit open the gate. See DES-AI-TRIGGER-FLOW-GATE.
+	if (typeof sha !== "string" || sha.trim() === "") return { gate: "deny" };
+	// Charset-guard `flow` BEFORE it reaches any git path (traversal choke point).
+	if (typeof flow !== "string" || !SKILL_NAME_RE.test(flow)) return { gate: "deny" };
+
+	const path = `.pi/skills/${flow}/SKILL.md`;
+	try {
+		const lsTreeZ = await git(folder, ["ls-tree", "-z", sha, path]);
+		const record = lsTreeZ.split("\0").find((r) => r);
+		if (!record) return { gate: "no-skill" }; // valid sha, path absent at that commit
+		// "<mode> <type> <oid>\t<path>"
+		const tab = record.indexOf("\t");
+		if (tab === -1) return { gate: "deny" };
+		const [mode, type, oid] = record.slice(0, tab).split(/\s+/);
+		if (mode !== "100644" || type !== "blob") return { gate: "deny" }; // symlink/gitlink/exec
+		const content = await git(folder, ["cat-file", "blob", oid], { raw: true });
+		return { gate: aiTriggerAllows(content) ? "allow" : "deny" };
+	} catch {
+		// bad sha, git failure, binary error: fail closed, never crash the producer/collector.
+		return { gate: "deny" };
+	}
+}
+
+// Custom: no YAML parser in worker deps; a single ai-trigger boolean does not justify js-yaml.
+// Strict leading-frontmatter scan: strip a BOM, normalise CRLF, isolate the leading `---`..`---`
+// block, and require an exact `ai-trigger: allow` line (an optional surrounding double quote).
+function aiTriggerAllows(buf) {
+	const text = buf.toString("utf8").replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+	const block = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(text);
+	if (!block) return false; // no parseable frontmatter -> deny
+	return /^ai-trigger:\s*("?)allow\1\s*$/m.test(block[1]);
+}
+
+async function defaultGit(gitDir, args, { raw = false } = {}) {
+	// hardening flags mirror materialize.mjs defaultGit — keep in sync. No hooks, no fsmonitor, no
+	// pager, so a hostile repo config cannot run code or corrupt output during a read.
+	const hardened = ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "--no-pager", "-C", gitDir, ...args];
+	const { stdout } = await exec("git", hardened, {
+		encoding: raw ? "buffer" : "utf8",
+		maxBuffer: 16 * 1024 * 1024,
+	});
+	return stdout;
+}

package/src/forgejo-auth.mjs

@@ -0,0 +1,77 @@
+/**
+ * Forgejo/Gitea authentication for the worker: the counterpart of get-token.mjs and gitlab-auth.mjs,
+ * yielding the identical `{ mintToken, selfId, source }` shape so nothing downstream branches on which
+ * forge a job belongs to.
+ *
+ * CONST-TOKEN-SCOPED-PER-JOB, stated honestly. Forgejo has no App, no installation token, and no per-job
+ * mint. What it does have -- and this is the interesting part -- is a REPO-SCOPED access token, which
+ * GitLab's project token also gives but GitHub's classic PAT does not. So Forgejo and Azure DevOps fail
+ * OPPOSITE halves of this constraint, and it is worth being precise about which:
+ *
+ *   - repo-scoped         YES, and better than GitLab's. A "specific repositories" token reaches only the
+ *                         repositories the operator selected.
+ *   - minimally-permissioned  YES, and this is the good news: such a token may carry ONLY
+ *                         `read:repository`, `write:repository`, `read:issue` and `write:issue`. There is
+ *                         no all-or-nothing `api` scope to fall back to, as there is on GitLab.
+ *   - host-held           YES; it lives in the worker's env and reaches a container only as an env value.
+ *   - env-injected        YES; never written to /workspace, .git/config, argv, or a log.
+ *   - not merge-capable   YES in practice; branch protection is the barrier and no merge API is called.
+ *   - short-lived         NO. The operator mints it by hand. Forgejo offers no installation-token
+ *                         equivalent, so there is no path to a bounded expiry at all.
+ *
+ * That last row is the whole exception, and it is the one the constitution names as the blast-radius
+ * bound -- "a when, not an if" for an agent induced to exfiltrate its environment. It is inherited from
+ * the accepted `gh`/`pat` gap rather than being a new class, but unlike GitHub there is no stronger path
+ * to prefer, so the docs must say so where an operator chooses.
+ *
+ * The narrow scope has one consequence that is NOT cosmetic: a repo-scoped token cannot call `GET /user`,
+ * so the bot-loop guard's identity has to come from `FORGEJO_BOT_ID` instead. See forgejo-identity.mjs --
+ * and note that an unresolved identity throws here rather than degrading, because a receiver that cannot
+ * recognise its own comments turns them into more paid jobs.
+ *
+ * All side-effecting collaborators are INJECTED, so the module is testable offline with no Forgejo.
+ */
+
+import { configError } from "./config.mjs";
+import { resolveForgejoSelfId } from "./forgejo-identity.mjs";
+
+/**
+ * Build the auth surface for `cfg = { source, apiUrl, tokenVar, botId }`.
+ *
+ * Fails CLOSED at construction: an empty token or an unresolvable identity throws before returning, so a
+ * misconfigured worker refuses to boot rather than running jobs it cannot report on.
+ */
+export async function makeForgejoAuth(cfg, deps = {}) {
+	const { env = process.env, fetchFn = fetch } = deps;
+	const source = cfg?.source;
+	if (source !== "pat") {
+		// `app` is the value most likely to arrive here, from an operator copying the GitHub block. It is
+		// refused by name rather than ignored, because an App is not merely unconfigured on Forgejo -- it
+		// does not exist, and a worker that quietly fell back to `pat` would hide that.
+		throw configError(`makeForgejoAuth: unknown or missing source: ${JSON.stringify(source)} (only "pat" is supported -- Forgejo has no App or installation-token equivalent)`);
+	}
+
+	const tokenVar = cfg.tokenVar ?? "FORGEJO_TOKEN";
+	const token = requireToken(env[tokenVar], tokenVar);
+	const selfId = await resolveForgejoSelfId({ apiUrl: cfg.apiUrl, token, botId: cfg.botId ?? null, fetchFn });
+
+	// Ignores the job by design: one operator-supplied token serves every repository this deployment
+	// services, exactly as the gitlab and github `pat` sources do. The parameter exists so the shape matches.
+	const mintToken = async () => requireToken(token, tokenVar);
+	return { mintToken, selfId, source };
+}
+
+/**
+ * The money-hole invariant, mirrored from get-token.mjs: return a trimmed non-empty token, or throw.
+ *
+ * An empty credential would reach env-allowlist's truthiness check as falsy, the token would be OMITTED
+ * from the container env entirely, and the job would run anonymously -- a silent, paid, useless run rather
+ * than an error.
+ */
+function requireToken(raw, what) {
+	const token = typeof raw === "string" ? raw.trim() : "";
+	if (token === "") {
+		throw configError(`${what} is empty or unset; refusing to hand a job an empty Forgejo credential`);
+	}
+	return token;
+}