@edgehero/pi-dispatch 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
   "keywords": [
@@ -44,6 +44,8 @@
     "./config": "./src/config.mjs",
     "./exit-code": "./src/exit-code.mjs",
     "./flow-gate": "./src/flow-gate.mjs",
+    "./materialize": "./src/materialize.mjs",
+    "./open-browser": "./src/open-browser.mjs",
     "./git-dirty": "./src/git-dirty.mjs",
     "./queue": "./src/queue.mjs",
     "./connection": "./src/connection.mjs",

package/src/config.mjs

@@ -15,6 +15,13 @@ export function configError(message) {
 	return error;
 }
 
+// The chain caps' DEFAULTS, exported (issue #54) so the admin's read-model can state them without a
+// second literal to drift and without calling loadConfig, whose GitHub-auth validation throws on
+// problems unrelated to a path read (the documented reason resolvePaths never calls it). The env
+// OVERRIDES stay right here in loadConfig; only the defaults are shared.
+export const CHAIN_DEPTH_MAX_DEFAULT = 1; // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
+export const CHAIN_MAX_PER_JOB_DEFAULT = 2; // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
+
 function boundedInt(env, name, fallback, min, want) {
 	const raw = env[name];
 	if (raw === undefined || raw === "") {
@@ -191,8 +198,8 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// A bound on how large a transcript may be before it stops being resumed. Not disk hygiene: an
 		// oversized transcript is a prefill an operator never sized PI_MAX_TOKENS for.
 		sessionMaxBytes: nonNegativeInt(env, "PI_SESSION_MAX_BYTES", 8 * 1024 * 1024), // 0 = no cap
-		chainDepthMax: nonNegativeInt(env, "PI_CHAIN_DEPTH_MAX", 1), // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
-		chainMaxPerJob: nonNegativeInt(env, "PI_CHAIN_MAX_PER_JOB", 2), // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
+		chainDepthMax: nonNegativeInt(env, "PI_CHAIN_DEPTH_MAX", CHAIN_DEPTH_MAX_DEFAULT), // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
+		chainMaxPerJob: nonNegativeInt(env, "PI_CHAIN_MAX_PER_JOB", CHAIN_MAX_PER_JOB_DEFAULT), // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
 		dispatchRunPerHour: nonNegativeInt(env, "PI_DISPATCH_RUN_PER_HOUR", 3), // DES-ADMIN-VIA-PI-EXTENSION; 0 = disable dispatch_run
 		dispatchRunRoots: delimitedList(env.PI_DISPATCH_RUN_ROOTS), // DES-AI-TRIGGER-FLOW-GATE: default [] fails closed — no folder passes, dispatch_run refuses everything
 		github: { ...loadGitHubAuth(env, fileExists), allowGhResume: env.PI_SESSIONS_ALLOW_GH_SOURCE === "1" },
@@ -262,6 +269,16 @@ export function defaultLogsDir() {
 	return `${process.env.TMPDIR ?? process.env.TEMP ?? "/tmp"}/pi-dispatch/logs`.replace(/\\/g, "/");
 }
 
+export function defaultGraphDir(env = process.env) {
+	// Under the OS temp dir by default, beside logs/ and jobs/ -- the admin's graph HTML artifact
+	// (issue #54) is host-side display output on the defaultLogsDir doctrine, and deliberately NOT
+	// inside logsDir: INT-RUN-HISTORY-FILE-CONTRACT names that directory's filename shape, and a
+	// stray .html beside the sidecars would widen a contract for a file that is not a record.
+	// Overridable with PI_GRAPH_DIR; exported so the admin resolves the same default without
+	// loadConfig, like defaultSandboxDir above.
+	return `${env.TMPDIR ?? env.TEMP ?? "/tmp"}/pi-dispatch/graph`.replace(/\\/g, "/");
+}
+
 export function defaultSettingsFile() {
 	// Under the OS temp dir by default. Holds the runtime-tunable settings overlay shared with the admin
 	// extension (INT-CONFIG-OVERLAY-CONTRACT); a worker-owned path that never enters the container env

package/src/flow-gate.mjs

@@ -64,7 +64,9 @@ export async function readFlowGate({ folder, flow, sha, git = defaultGit }) {
 // 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) {
+// Exported (issue #54) so the admin's skill enumeration answers "chainable?" with THIS scanner and
+// not a keep-in-sync copy -- the SKILL_NAME_RE lesson one export up, applied to the frontmatter test.
+export 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

package/src/github-app-setup.mjs

@@ -32,13 +32,13 @@
  * Everything side-effecting is injected (fetch, the listener, the browser opener, prompt, fs, clock),
  * defaulting to the real thing — the up.mjs convention — so the whole flow is testable offline.
  */
-import { spawn as nodeSpawn } from "node:child_process";
 import { createSign } from "node:crypto";
 import { chmodSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { updateEnvFile } from "./env-file.mjs";
+import { openBrowser as defaultOpenBrowser } from "./open-browser.mjs";
 import { defaultPrompt } from "./up.mjs";
 
 const API_ROOT = "https://api.github.com";
@@ -503,20 +503,6 @@ async function defaultListen(pageFor) {
 	};
 }
 
-/**
- * Best-effort platform browser opener. ALWAYS paired with the URL printed to the terminal — a
- * headless or SSH'd operator has no opener that works, and the printed URL pasted into any browser
- * (on the right machine, or through the port-forward the wizard suggests) is the real contract; the
- * spawn is only a convenience on top. Failures are swallowed for the same reason.
- */
-function defaultOpenBrowser(url) {
-	const [cmd, args] =
-		process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
-	try {
-		const child = nodeSpawn(cmd, args, { stdio: "ignore", detached: true });
-		child.on("error", () => {});
-		child.unref();
-	} catch {
-		// No opener on this host — the printed URL carries the flow.
-	}
-}
+// The best-effort platform opener moved to its own module (issue #54) so the admin's graph export
+// shares this one reviewed argv table instead of hand-copying it; the print-the-URL-first doctrine
+// lives in its docstring and is unchanged here.

package/src/open-browser.mjs

@@ -0,0 +1,24 @@
+import { spawn as nodeSpawn } from "node:child_process";
+
+/**
+ * Best-effort platform browser opener. ALWAYS paired with the URL printed to the terminal -- a
+ * headless or SSH'd operator has no opener that works, and the printed URL pasted into any browser
+ * (on the right machine, or through the port-forward the caller suggests) is the real contract; the
+ * spawn is only a convenience on top. Failures are swallowed for the same reason.
+ *
+ * One module on purpose (issue #54): the GitHub App wizard and the admin's graph export both open a
+ * browser, and two hand-copies of platform-opener argv is exactly the drift class the repo's mirror
+ * tests exist to prevent. `spawn` and `platform` are injectable so the argv table is testable
+ * without launching anything.
+ */
+export function openBrowser(url, { spawn = nodeSpawn, platform = process.platform } = {}) {
+	const [cmd, args] =
+		platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+	try {
+		const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+		child.on("error", () => {});
+		child.unref();
+	} catch {
+		// No opener on this host -- the printed URL carries the flow.
+	}
+}

package/src/run-history.mjs

@@ -295,6 +295,19 @@ export function buildRecord({ job, result, error, startedAt, endedAt }) {
 		// deliberately not stored, for the reason `session` states one group below.
 		replica: data.replica ?? null,
 		replicas: data.replicas ?? null,
+		// Trigger attribution (INT-RUN-HISTORY-FILE-CONTRACT, issue #54): additive and nullable, explicit
+		// literals beside the replica fields whose admissibility argument they reuse, no spread. Both read
+		// the receiver's harness-computed `matched` from this job's own `job.data.trigger`: `index` is the
+		// raw triggers-array position of the entry that fired (cron entries counted) and `type` that entry's
+		// `on.type` -- an INTEGER and a FIXED ENUM ("label" | "comment" | "pull_request"), nothing
+		// attacker-chosen. The third `matched` key (`label`/`phrase`/`action`) is DELIBERATELY absent:
+		// a label that satisfied an `any` predicate is collaborator-applied payload text, and `type`
+		// already names the route. Cron jobs carry `trigger: { id, pattern }` with no `matched`, so both
+		// stay null there on purpose -- a cron run's attribution is already exact via its
+		// `repeat:<id>:<millis>` jobId (see makeFindPreviousRun), and that join also works retroactively
+		// over the whole retention window, which a new record field cannot.
+		triggerIndex: data.trigger?.matched?.index ?? null,
+		triggerType: data.trigger?.matched?.type ?? null,
 		// Session telemetry (INT-RUN-HISTORY-FILE-CONTRACT): additive, nullable, an explicit literal, no
 		// spread. `{ resumed, reason, bytes }` -- a boolean, a fixed enum and an integer. THE KEY AND THE
 		// BRANCH NAME ARE DELIBERATELY ABSENT: this record's PII-free-by-construction property rests on it