@edgehero/pi-dispatch 2.1.0 → 3.1.0

package/src/get-token.mjs

@@ -27,6 +27,7 @@ import { createAppAuth as realCreateAppAuth } from "@octokit/auth-app";
 import { Octokit as RealOctokit } from "@octokit/rest";
 import { configError } from "./config.mjs";
 import { resolveSelfId } from "./identity.mjs";
+import { octokitLogOptions } from "./octokit-log.mjs";
 import { InfraRetry } from "./processor.mjs";
 import { isDeterminateFetchFailure, isDeterminateFsCode, isTransientStatus, octokitHeaderReader } from "./transient.mjs";
 
@@ -54,14 +55,18 @@ export async function makeGitHubAuth(cfg, deps = {}) {
 		execFile = realExecFile,
 		readFile = realReadFile,
 		env = process.env,
+		// Issue #530: the caller's `(event, fields)` logger, which a GitHub client's own warnings go through. Every client
+		// here is built with `octokitLog`, so none prints Octokit's plain `GET /user - 401 ...` line into a JSON stream.
+		log,
 	} = deps;
+	const quiet = octokitLogOptions(log);
 
 	const source = cfg?.source;
 
 	if (source === "pat") {
 		const patVar = cfg.patVar ?? "GITHUB_PAT";
 		const token = requireToken(env[patVar], patVar);
-		const octokit = new Octokit({ auth: token });
+		const octokit = new Octokit({ auth: token, ...quiet });
 		const selfId = await resolveSelfId({ source: "pat", octokit });
 		const mintToken = async () => requireToken(token, patVar);
 		return { mintToken, selfId, source };
@@ -71,7 +76,7 @@ export async function makeGitHubAuth(cfg, deps = {}) {
 		const execFileAsync = promisify(execFile);
 		const ghToken = () => runGhAuthToken(execFileAsync);
 		// Resolve identity from a token minted once here; each job mints its own below.
-		const octokit = new Octokit({ auth: await ghToken() });
+		const octokit = new Octokit({ auth: await ghToken(), ...quiet });
 		const selfId = await resolveSelfId({ source: "gh", octokit });
 		const mintToken = async (job) => {
 			assertResumeAllowedOnGhSource(job, allowGhResume);
@@ -89,10 +94,16 @@ export async function makeGitHubAuth(cfg, deps = {}) {
 		// The key is either already in hand (GITHUB_APP_PRIVATE_KEY, normalised and shape-checked at config
 		// load) or on disk. loadGitHubAuth refuses both-set, so this is a fallback, never a precedence rule.
 		const privateKey = cfg.privateKey ?? (await readPem(readFile, cfg.privateKeyPath));
-		const auth = { appId: cfg.appId, privateKey, installationId: cfg.installationId };
+		// `log` rides in the auth options too: the per-job `createAppAuth` below builds no Octokit, and
+		// `@octokit/auth-app` otherwise defaults its own warnings to `console.warn`.
+		const auth = { appId: cfg.appId, privateKey, installationId: cfg.installationId, log: quiet.log };
+		// And its `request`: auth-app's default one is a bare `@octokit/request`, whose deprecation warning goes to
+		// `console`. An unauthenticated Octokit's `request` carries the quiet logger and adds no auth hook; the identity
+		// client below is not changed, since Octokit already hands its own request to its auth strategy.
+		const mintRequest = new Octokit({ ...quiet }).request;
 
 		// App-JWT client: resolveSelfId's app path reads GET /app then GET /users/{slug}[bot].
-		const octokit = new Octokit({ authStrategy: createAppAuth, auth });
+		const octokit = new Octokit({ authStrategy: createAppAuth, auth, ...quiet });
 		const selfId = await resolveSelfId({ source: "app", octokit });
 
 		const mintToken = async (job) => {
@@ -112,7 +123,7 @@ export async function makeGitHubAuth(cfg, deps = {}) {
 			const permissions = job?.permissions;
 			let minted;
 			try {
-				const appAuth = createAppAuth(auth);
+				const appAuth = createAppAuth({ ...auth, request: mintRequest });
 				minted = await appAuth({ type: "installation", repositoryNames, ...(permissions && { permissions }) });
 			} catch (error) {
 				throw classifyAppMintError(error);

package/src/git-dirty.mjs

@@ -1,4 +1,6 @@
 import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { GIT_READ_FLAGS } from "./git-hardening.mjs";
 
 /**
@@ -22,3 +24,68 @@ export function gitDirty(folder, { exec = execFileSync } = {}) {
 		return null;
 	}
 }
+
+/**
+ * Why `folder` cannot be a local job's folder, as one sentence with its fix, or null when it can (issue #524).
+ *
+ * The worker's own rule, stated here so `pi-dispatch run` refuses before anything is queued. `prepare-local.mjs`
+ * requires `.git` AT the folder (a directory, or the file a worktree or submodule has) and reads the job's
+ * instructions from HEAD. So a subfolder of a repository is refused like a plain folder, and a repository with no
+ * commit yet is refused too, as the worker's `local-folder-no-commit`. Before this the CLI skipped every check when
+ * `.git` was missing, the worker refused the job as a generic `config-refused`, and nothing said which folder or why.
+ *
+ * Only the folder's root counts, and that is the worker's requirement rather than a choice made here. When the folder
+ * has no `.git`, git itself is asked whether the folder sits inside a repository (`rev-parse --show-toplevel`,
+ * hardened), and a root is named only when git confirms one. A walk up the parents for a `.git` entry was refuted in
+ * PR #528's review: an empty `.git` directory is not a repository, and it named one anyway. Even a confirmed root is
+ * never offered as the only fix. A dotfiles repository (`git init` in the home directory, `*` ignored) contains
+ * every folder under home, so "run it on <home>" reads clean and hands the agent the whole home directory. Both
+ * options are always named, and the operator picks.
+ *
+ * `exists` and `exec` are seams; `exec` runs HARDENED for the same reason `gitDirty` does.
+ */
+export function localRepoProblem(folder, { exists = existsSync, exec = execFileSync } = {}) {
+	if (!exists(join(folder, ".git"))) {
+		const root = enclosingRepoRoot(folder, exec);
+		if (root) return `${folder} is not the root of a git repository, and a local job needs one. Run \`git init\` here and commit, or, if this folder belongs to the repository at ${root}, run it on ${root}.`;
+		return `${folder} is not a git repository. A local job needs one: run \`git init\` there and commit, then run again.`;
+	}
+	const git = (args) => exec("git", [...GIT_READ_FLAGS, "-C", folder, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+	try {
+		git(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+	} catch (error) {
+		// A missing `git` is not a missing commit, and the fix is a different one.
+		if (error?.code === "ENOENT") return "git is not installed or not on PATH, so the folder cannot be checked. Install git, then run again.";
+		// Exit 1 is also a missing commit object, a garbage branch ref or an unreadable `refs/heads` (PR #528's review,
+		// measured): "commit once" is said only for an unborn HEAD, the worker's own test (`prepare-local.mjs`).
+		if (error?.status === 1 && unbornHead(git)) return `${folder} is a git repository with no commit yet. A local job reads its instructions from HEAD: commit once, then run again.`;
+		return `${folder} is not a usable git repository: git could not read it. Check it with \`git -C ${folder} status\`, then run again.`;
+	}
+	return null;
+}
+
+/** An unborn HEAD: HEAD names no object at all, and names a branch (the worker's `unbornHead`, by the same exit codes). */
+function unbornHead(git) {
+	try {
+		git(["rev-parse", "--verify", "--quiet", "HEAD"]);
+		return false;
+	} catch (error) {
+		if (error?.status !== 1) return false;
+	}
+	try {
+		git(["symbolic-ref", "-q", "HEAD"]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** The repository git says `folder` is inside, or null when git confirms none (or cannot run). Hardened like the rest. */
+function enclosingRepoRoot(folder, exec) {
+	try {
+		const top = String(exec("git", [...GIT_READ_FLAGS, "-C", folder, "rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })).trim();
+		return top === "" ? null : top;
+	} catch {
+		return null;
+	}
+}

package/src/github-app-setup.mjs

@@ -33,14 +33,17 @@
  * defaulting to the real thing — the up.mjs convention — so the whole flow is testable offline.
  */
 import { createSign } from "node:crypto";
-import { chmodSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, 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 { ENV_WRITER_FS, updateEnvFile } from "./env-file.mjs";
 import { openBrowser as defaultOpenBrowser } from "./open-browser.mjs";
 import { defaultPrompt } from "./up.mjs";
 
+/** This command's default fs seam: its own calls, and every call the `.env` writer makes (`ENV_WRITER_FS`, issue #522). */
+export const SETUP_GITHUB_FS = { existsSync, ...ENV_WRITER_FS };
+
 const API_ROOT = "https://api.github.com";
 // GitHub rejects requests without a User-Agent, and node's fetch does not always send one.
 const USER_AGENT = "pi-dispatch-setup-github";
@@ -69,7 +72,7 @@ export async function runGithubAppSetup(argv = [], deps = {}) {
 		openBrowser = defaultOpenBrowser,
 		out = (s) => process.stdout.write(s),
 		prompt = defaultPrompt,
-		fs = { existsSync, readFileSync, writeFileSync, renameSync, statSync, chmodSync },
+		fs = SETUP_GITHUB_FS,
 		cwd = process.cwd(),
 		now = () => Date.now(),
 		codeTimeoutMs = 600000, // ~10 min for a human to click through GitHub's create-app page

package/src/github-host.mjs

@@ -25,13 +25,15 @@
 
 import { Octokit } from "@octokit/rest";
 import { configError } from "./config.mjs";
+import { octokitLogOptions } from "./octokit-log.mjs";
 import { InfraRetry } from "./processor.mjs";
 
 /**
- * Build the host surface. `octokitFor` is `(token) => new Octokit({ auth: token })`; inject a fake
- * to test offline. Returns `{ resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment }`.
+ * Build the host surface. `octokitFor` is `(token) => new Octokit({ auth: token, ...octokitLogOptions(log) })`; inject a fake
+ * to test offline. `log` is the caller's `(event, fields)` logger for the client's own warnings
+ * (`octokitLog`, issue #530). Returns `{ resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment }`.
  */
-export function makeGitHubHost({ octokitFor = (token) => new Octokit({ auth: token }) } = {}) {
+export function makeGitHubHost({ log, octokitFor = (token) => new Octokit({ auth: token, ...octokitLogOptions(log) }) } = {}) {
 	/**
 	 * Resolve the default branch and its tip SHA with FRESH API calls only -- never a webhook field.
 	 * `GET /repos/{owner}/{repo}` yields `default_branch`; `GET .../branches/{branch}` yields the tip.

package/src/host-pi.mjs

@@ -15,7 +15,7 @@
  * What it must never become. Nothing on the worker's BOOT path may import this file. It reads host paths and
  * may spawn a package manager, and neither belongs anywhere near `start.mjs`.
  *
- * Everything here MIRRORS a private detail of the pinned pi (0.99.1) rather than calling it: pi exports no
+ * Everything here MIRRORS a private detail of the pinned pi (1.0.3) rather than calling it: pi exports no
  * public answer to "where is this package installed" or "is this resource enabled", and importing the whole
  * coding-agent SDK to read two well-known paths is not worth the weight. That mirroring is a real risk --
  * pi could change the grammar and we would silently start staging something the operator turned off -- so it

package/src/identity.mjs

@@ -72,7 +72,8 @@ export async function resolveSelfId(auth) {
 		if (!isDeterminateFetchFailure(error) && status !== undefined && isTransientStatus(status, octokitHeaderReader(error), error?.message)) {
 			throw transientError(`resolveSelfId: could not reach GitHub to resolve self identity: ${error.message}`, error);
 		}
-		throw configError(`resolveSelfId: could not resolve self identity: ${error.message}`);
+		// The RequestError rides as `cause` (issue #530's review), so the failure line can name GitHub's request id.
+		throw Object.assign(configError(`resolveSelfId: could not resolve self identity: ${error.message}`), { cause: error });
 	}
 
 	if (!Number.isInteger(id)) {

package/src/image-preflight.mjs

@@ -42,10 +42,9 @@ export function resolveJobImage(job, defaultImage) {
  *   { missing: image }    -- the daemon answered and does not have it  => POLICY, refuse, do not retry
  *   { unavailable: image} -- docker itself did not answer              => INFRA, retry
  *   { forgeUnsupported }  -- present, but declares it cannot serve this job's forge => POLICY, refuse
- *   { replicaUnsupported }-- present, but does not declare replica support for a replica job => POLICY
- *   { commandUnsupported }-- present, but does not declare command support for a command job => POLICY
- *   { excludeToolsUnsupported } -- present, but does not declare exclude-tools support for a job that
- *                            carries exclusions => POLICY
+ *   { <gate.result>, declared } -- present, but does not declare a capability this job needs, one key per
+ *                            CAPABILITY_GATES row (replicaUnsupported, commandUnsupported,
+ *                            excludeToolsUnsupported, modelPolicyUnsupported, costCapUnsupported) => POLICY
  *
  * A non-zero `docker image inspect` is AMBIGUOUS -- an absent image and an unreachable daemon both exit 1 --
  * so the failure path disambiguates POSITIVELY with `docker info` rather than by matching docker's stderr.
@@ -97,26 +96,13 @@ export function makeImagePreflight({ image, spawnFn = spawn, bin = "docker" }) {
 			// asymmetry is deliberate rather than an oversight. `forges` is an EXCLUSION list, so no claim
 			// excludes nothing; `capabilities` is an INCLUSION list, so no claim includes nothing. One rule
 			// underlies both -- an image that declares nothing gets no benefit of the doubt about what it
-			// contains -- and neither costs an UNFLAGGED job anything: this branch is unreachable unless the
-			// job actually carries a replica index.
-			if (job?.replica !== undefined && !(capabilities ?? []).includes("replicas")) {
-				return { replicaUnsupported: wanted, declared: capabilities ?? [] };
-			}
-			// Same inclusion-list polarity as `replicas` directly above, and the same class of stale-image
-			// failure it guards (issue #189): a runner that predates run.command reads no PI_COMMAND, so
-			// the bare `/name args` prompt reaches the model as PROSE -- no handler runs, the agent
-			// improvises, and the queue records a clean exit 0. Unreachable for a commandless job, so the
-			// existing fleet pays nothing for it.
-			if (job?.command !== undefined && !(capabilities ?? []).includes("commands")) {
-				return { commandUnsupported: wanted, declared: capabilities ?? [] };
-			}
-			// Same inclusion-list polarity again, and here the stale-image failure is a PERMISSION quietly
-			// not enforced (issue #291): a runner that predates run.excludeTools reads no PI_EXCLUDE_TOOLS,
-			// so a "read-only" trigger's job would run with every tool the file says to remove and record a
-			// clean exit -- the silent fail-open this field exists to close. Unreachable for a job without
-			// exclusions, so the existing fleet pays nothing for it.
-			if (job?.excludeTools !== undefined && !(capabilities ?? []).includes("excludeTools")) {
-				return { excludeToolsUnsupported: wanted, declared: capabilities ?? [] };
+			// contains -- and neither costs an UNFLAGGED job anything: each gate below is unreachable unless
+			// the job actually carries the feature it guards. The gates, their order and why each exists are
+			// the CAPABILITY_GATES table; the first one this job needs and the image lacks refuses.
+			for (const gate of CAPABILITY_GATES) {
+				if (gate.needed(job) && !(capabilities ?? []).includes(gate.token)) {
+					return { [gate.result]: wanted, declared: capabilities ?? [] };
+				}
 			}
 			// `capabilities` rides the ok result for issue #341's job-user gate, which needs `anyUid` and runs after
 			// this preflight; an image that declares nothing reads as [].
@@ -127,6 +113,94 @@ export function makeImagePreflight({ image, spawnFn = spawn, bin = "docker" }) {
 	};
 }
 
+/**
+ * The image capability gates, ONE table (issues #501, #502 made it one; each row predates them). A row is a
+ * feature a job may carry and the `dev.pi-dispatch.capabilities` token an image must declare before a job
+ * carrying it runs there, because an image built before the feature silently ignores it: the runner reads no
+ * such variable and the job records a clean exit having done something else. The preflight refuses the first
+ * row whose `needed(job)` holds and whose `token` the image does not declare, before any spend.
+ *
+ *   token    the capability the image must declare
+ *   needed   whether this job carries the feature (a job that does not pays nothing for the row)
+ *   result   the key the preflight result names the image under, which the processor branches on
+ *   reason   the run record's reason for the refusal
+ *   event    the worker log event
+ *   comment  the forge comment, given the image and the `declared` phrase the processor builds; it names
+ *            the FIX rather than the label that noticed it, because an operator reading "rebuild the image"
+ *            is already where they need to be
+ *
+ * A new image-gated feature (`costCap`, `modelPolicy`) is a row here, not another branch in two files. Order
+ * is the order the branches had, so a job carrying several features is refused for the same one as before.
+ */
+export const CAPABILITY_GATES = Object.freeze([
+	// REQ-REPLICA-RUNS: an image built before it bakes a HARD_RULES.md whose rule 3 hard-codes `pi/issue-<n>`
+	// as a SYSTEM rule, which the model treats as authoritative over the user prompt naming `pi/issue-<n>-r2`.
+	// Both replicas would push to one branch: the push race the feature exists to avoid, two runs billed.
+	Object.freeze({
+		token: "replicas",
+		needed: (job) => job?.replica !== undefined,
+		result: "replicaUnsupported",
+		reason: "job-image-replicas-unsupported",
+		event: "refused_image_replicas_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare replica support (\`dev.pi-dispatch.capabilities\` ${declared}), so its baked guardrails would name the wrong branch. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// Issue #189: a runner that predates run.command reads no PI_COMMAND, so the bare `/name args` prompt
+	// reaches the model as PROSE -- no handler runs, the agent improvises, and the queue records a clean exit 0.
+	// The runner's own command-unregistered refusal does not exist on such an image, so the host refuses first.
+	Object.freeze({
+		token: "commands",
+		needed: (job) => job?.command !== undefined,
+		result: "commandUnsupported",
+		reason: "job-image-commands-unsupported",
+		event: "refused_image_commands_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare command support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would not dispatch \`run.command\`. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// Issue #291: a runner that predates run.excludeTools reads no PI_EXCLUDE_TOOLS, so a "read-only" trigger's
+	// job would run with every tool the file says to remove and record a clean exit: a PERMISSION quietly not
+	// enforced, the silent fail-open this repo brands the worst outcome available.
+	Object.freeze({
+		token: "excludeTools",
+		needed: (job) => job?.excludeTools !== undefined,
+		result: "excludeToolsUnsupported",
+		reason: "job-image-exclude-tools-unsupported",
+		event: "refused_image_exclude_tools_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare exclude-tools support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore \`run.excludeTools\` and run this trigger with every tool it says to remove. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// Issue #502: a runner that predates the model guard either ignores PI_ALLOWED_MODELS (an image older than the
+	// policy seams) or refuses it before any call as `model-policy-unenforceable`, after the budget was reserved. The
+	// first runs every model the list forbids on a clean exit, the second spends a slot to learn what the label
+	// already says. `needed` reads the EFFECTIVE list (index.mjs `effectiveJobOf`), so a deployment-wide
+	// PI_ALLOWED_MODELS is gated the same as a trigger's `run.models`.
+	Object.freeze({
+		token: "modelPolicy",
+		needed: (job) => Array.isArray(job?.models) && job.models.length > 0,
+		result: "modelPolicyUnsupported",
+		reason: "job-image-model-policy-unsupported",
+		event: "refused_image_model_policy_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare allowed-model support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner cannot hold this job to the models it may use. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// Issue #501: a runner that predates the cost guard reads no PI_MAX_COST_MICROS, so a job with a dollar cap
+	// would run UNCAPPED and record a clean exit: a money limit quietly not kept. Needed whenever the job carries
+	// a cap, 0 included (`!== null`, buildContainerEnv's rule: 0 is the tightest cap, not none). The refusal is
+	// pre-spend like every row: nothing minted, nothing cloned, no budget reserved (`budgetReserved: false`).
+	Object.freeze({
+		token: "costCap",
+		needed: (job) => job?.maxCostMicros !== null && job?.maxCostMicros !== undefined,
+		result: "costCapUnsupported",
+		reason: "job-image-cost-cap-unsupported",
+		event: "refused_image_cost_cap_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare cost-cap support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore the per-job dollar cap and run this job with no cap at all. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+]);
+
+/**
+ * The capability an image declares when its runner signs its exit line with a per-job key read from stdin, and runs
+ * under an exec-only node its job's tools cannot read (issue #545). NOT a gate: no job is refused for lacking it. The
+ * processor hands a key only to an image that declares it, and reads only a signed exit line from such an image; an
+ * image without it runs and is read exactly as before, under the #542 trust rule alone.
+ */
+export const EXIT_AUTH_CAPABILITY = "exitAuth";
+
 /**
  * Exported so the test cannot drift from the format string above. `|` because an image id is
  * `sha256:<hex>` and a version is a version, so neither can contain one -- and because a literal control

package/src/image-ref.mjs

@@ -19,3 +19,40 @@ export function imageRefProblem(image) {
 	if (/[\u0000-\u001f\u007f-\u009f]/.test(image)) return { code: "control", reason: "must not hold a control character" };
 	return null;
 }
+
+/**
+ * Whether an image reference names its registry (issue #523), by the docker reference grammar: the first path segment
+ * is a registry host only when there is a `/` after it and it holds a `.` or a `:`, or is `localhost`. Everything else
+ * (`pi-job:2.1.0`, `team/job:7`) is a short name the runtime resolves on a public registry (Docker Hub, or podman's
+ * search registries), where anyone may publish that name.
+ */
+export function registryQualified(image) {
+	const slash = image.indexOf("/");
+	if (slash < 0) return false;
+	const first = image.slice(0, slash);
+	return first.includes(".") || first.includes(":") || first === "localhost";
+}
+
+/**
+ * Whether a missing image may be offered as a pull (issue #523, review round 2): a registry-qualified name other than
+ * `localhost/...`. That prefix is qualified for the "never Docker Hub" rule, but it is podman's name for an image built
+ * on this host, with no registry behind it, so a pull of it can only fail or reach whatever listens on this host.
+ * `localhost:<port>/...` names a real registry on a port and is pullable.
+ */
+export function pullOffered(image) {
+	return registryQualified(image) && !image.startsWith("localhost/");
+}
+
+/**
+ * How to provide a missing deployment job image with `bin` (docker or podman), ONE text for `up` and doctor's fix lines
+ * (issue #523, review): the worker's default `pi-job:latest` is ghcr's latest pulled and re-tagged, since that local
+ * name has no registry behind it; a registry-qualified name is pulled as it is named; a short name is never offered as
+ * a pull, since a public registry answers for it, nor a `localhost/` name (`pullOffered`), so the text says how to
+ * provide it instead.
+ */
+export function jobImageFix(bin, image) {
+	if (image === "pi-job:latest") return `${bin} pull ghcr.io/edgehero/pi-job:latest && ${bin} tag ghcr.io/edgehero/pi-job:latest pi-job:latest`;
+	if (pullOffered(image)) return `${bin} pull ${image}`;
+	if (registryQualified(image)) return `${image} is a locally built name (localhost/ is no registry to pull from): build it on this host, or \`${bin} tag\` an image you have as ${image}`;
+	return `${image} names no registry host, so a pull would fetch whatever a public registry holds under that name: build it on this host, \`${bin} tag\` an image you have as ${image}, or set PI_JOB_IMAGE to a registry-qualified name (such as ghcr.io/edgehero/pi-job:<version>)`;
+}

package/src/import-pi.mjs

@@ -25,7 +25,7 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, lstatSync, statSync, copyFileSync, renameSync, rmSync } from "node:fs";
 import { execFile } from "node:child_process";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { FROM_HOST, PACKAGES_SUBDIR, RESOURCE_DIRS, STAGE_MANIFEST, mergeHostPackages, parsePackagesFile } from "./packages.mjs";
 import { agentDirFrom, readHostPi } from "./host-pi.mjs";
@@ -121,7 +121,9 @@ export async function runImportPi(argv = [], deps = {}) {
 	// `--host-packages` is accepted as a no-op for symmetry with `--with-extensions`.
 	const withHostPackages = withPackages && !argv.includes("--no-host-packages");
 	const from = flagValue(argv, "--from") ?? defaultFrom(env);
-	const to = flagValue(argv, "--to") ?? join(cwd, "pi-global");
+	// Absolute, always (PR #553's review): the next steps print it as the PI_GLOBAL_PI_DIR to set, and the worker
+	// refuses a relative one, since the worker and the container runtime resolve it differently.
+	const to = resolve(cwd, flagValue(argv, "--to") ?? "pi-global");
 	const packagesFile = flagValue(argv, "--packages-file") ?? env.PI_PACKAGES_FILE ?? join(cwd, "pi-packages.json");
 
 	if (!fs.existsSync(from)) {