@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/core-job-probe-native.js

@@ -0,0 +1,564 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { load, JSON_SCHEMA } from "js-yaml";
+import { serializeJqJson } from "../lib/core-utils/jq-json-serializer.js";
+import { resolveLiveRoot } from "../utils/hq-roots.js";
+import { runBundledScript } from "../utils/run-bundled-script.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
+import { coreNativeJobsEnabled } from "./core-native-jobs-flag.js";
+export const JOB_PROBE_ASSET = "core/scripts/hq-job-probe.sh";
+export const JOB_PROBE_USAGE = [
+    "hq-job-probe.sh — Outpost requirements probe → hq-pro jobs status (US-008).", "",
+    "On the Outpost, deterministically checks a job's requirements checklist and",
+    "POSTs readiness to POST /outpost/internal/jobs-status. Never rewrites job YAML.", "",
+    "Usage:", "  core/scripts/hq-job-probe.sh [options] <job.yaml|job-id>",
+    "  core/scripts/hq-job-probe.sh [options] --all", "", "Options:",
+    "  --hq-root DIR     HQ tree root (default: HQ_ROOT or repo root above core/)",
+    "  --dry-run         Run checks + print JSON; skip ingest", "  --no-ingest       Alias of --dry-run",
+    "  --json            Force JSON on stdout (default)", "  -h, --help        Show this help", "",
+    "Checks (per requirements / job fields):",
+    "  - runtime CLI auth: claude → ~/.claude/.credentials.json; codex → ~/.codex/auth.json",
+    "  - requirements.secrets[] visible via `hq secrets list` (names only; never values)",
+    "  - optional cwd exists (HQ-root-relative or absolute)",
+    "  - company path present when requirements.company / company scope set", "",
+    "Ingest auth (box identity — same trust model as disk-status / relay-status):",
+    "  Header: x-outpost-instance-token",
+    "  Body:   userId + jobId + kind=probe + readiness + probed_at + next_actions + checks",
+    "  Identity from (first match):",
+    "    1. OUTPOST_USER_ID + OUTPOST_INSTANCE_TOKEN (+ optional OUTPOST_ID)",
+    "    2. /etc/outpost/codex-identity.env (OUTPOST_USER_ID / OUTPOST_INSTANCE_TOKEN)",
+    "    3. USER_ID= / INSTANCE_TOKEN= / OUTPOST_ID= lines in /usr/local/bin/outpost-runner.sh",
+    "  API base: HQ_PRO_API_URL → HQ_API_URL → HQ_VAULT_API_URL → https://hqapi.hq.computer", "",
+    "StatusIngestError (unreachable / 5xx / retryable body):",
+    "  Bounded backoff retries; writes ~/.hq/jobs/probes/{id}/last-attempt.json;",
+    "  never reports readiness=ready solely because ingest failed; surfaces",
+    "  next_action \"status ingest failed — retry probe\".", "", "Env (tests / overrides):",
+    "  HQ_ROOT, HOME, HQ_PRO_API_URL, OUTPOST_USER_ID, OUTPOST_INSTANCE_TOKEN, OUTPOST_ID",
+    "  HQ_JOB_PROBE_CLAUDE_CRED, HQ_JOB_PROBE_CODEX_AUTH",
+    "  HQ_JOB_PROBE_STATE_DIR, HQ_JOB_PROBE_MAX_ATTEMPTS, HQ_JOB_PROBE_BACKOFF_BASE_SEC",
+    "  HQ_JOB_PROBE_SLEEP (set to \":\" to no-op sleep), HQ_JOB_PROBE_NOW (ISO timestamp)",
+    "  HQ_JOB_PROBE_CURL (curl binary override), HQ_JOB_PROBE_RUNNER (outpost-runner path)", "",
+    "Exit: 0 ready+ingested (or dry-run ready); 1 blocked; 2 usage/config; 3 StatusIngestError", "",
+    "set -euo pipefail", "",
+].join("\n");
+class Fatal extends Error {
+    code;
+    prefix;
+    rawStderr;
+    constructor(message, code = 2, prefix = "hq-job-probe", rawStderr = "") {
+        super(message);
+        this.code = code;
+        this.prefix = prefix;
+        this.rawStderr = rawStderr;
+    }
+}
+const compact = (x) => serializeJqJson(x, "compact").trimEnd();
+const statSize = (f) => { try {
+    return fs.statSync(f).size;
+}
+catch {
+    return undefined;
+} };
+const isFile = (f) => { try {
+    return fs.statSync(f).isFile();
+}
+catch {
+    return false;
+} };
+const isDirectory = (f) => { try {
+    return fs.statSync(f).isDirectory();
+}
+catch {
+    return false;
+} };
+const realpath = (f) => { try {
+    return fs.realpathSync(f);
+}
+catch {
+    return undefined;
+} };
+function writeState(file, body) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${body}\n`, { mode: 0o600 }); try {
+    fs.chmodSync(file, 0o600);
+}
+catch { /* legacy chmod is best-effort */ } }
+function hasCommand(name, env) {
+    for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        try {
+            const f = path.join(dir, name);
+            fs.accessSync(f, fs.constants.X_OK);
+            if (fs.statSync(f).isFile())
+                return true;
+        }
+        catch { /* search remaining PATH */ }
+    }
+    return false;
+}
+function listSecrets(company) {
+    // Keep the `hq secrets list` subprocess: no in-process API produces the same names-only table.
+    const args = company ? ["secrets", "list", "--company", company] : ["secrets", "list", "--personal"];
+    const r = spawnSync("hq", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return Promise.resolve({ code: r.status ?? (r.error ? 127 : 1), stdout: r.stdout ?? "" });
+}
+export function defaultProbeDeps(root, env = process.env) {
+    const stubs = env.HQ_JOB_TEST_STUB === "1";
+    return { root, home: env.HOME || os.homedir(), env, now: () => new Date(),
+        sleep: async (s) => { if (env.HQ_JOB_PROBE_SLEEP === ":" || env.HQ_JOB_PROBE_SLEEP === "true")
+            return; await new Promise((resolve) => setTimeout(resolve, Math.max(0, s * 1000))); },
+        statSize, isFile, isDirectory, realpath, readText: (f) => fs.readFileSync(f, "utf8"), writeState,
+        writeStderr: (line) => process.stderr.write(line),
+        listSecrets: stubs ? async () => { throw new Error("HQ_JOB_TEST_STUB blocked real hq secrets list"); } : listSecrets,
+        commandExists: (name) => hasCommand(name, env),
+        fetcher: stubs ? async () => { throw new Error("HQ_JOB_TEST_STUB blocked real network fetch"); } : (url, init) => fetch(url, init) };
+}
+const isoNow = (d) => d.env.HQ_JOB_PROBE_NOW || d.now().toISOString().replace(/\.\d{3}Z$/, "Z");
+const obj = (x) => x && typeof x === "object" && !Array.isArray(x) ? x : {};
+function yaml(file, d) { return obj(load(d.readText(file), { schema: JSON_SCHEMA })); }
+function nested(x, ...keys) { let v = x; for (const k of keys)
+    v = obj(v)[k]; return v; }
+function scalar(x) { return x == null ? "" : typeof x === "string" ? x : typeof x === "object" ? JSON.stringify(x) : String(x); }
+function allFiles(root) {
+    const files = [];
+    const walk = (dir, jobsOnly, companiesRoot) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const f = path.join(dir, e.name);
+            if (e.isDirectory())
+                walk(f, jobsOnly, companiesRoot);
+            else if (e.isFile() && /\.ya?ml$/.test(e.name)
+                && (!jobsOnly || (companiesRoot ? path.relative(companiesRoot, f).split(path.sep).includes("jobs") : true)))
+                files.push(f);
+        }
+    };
+    walk(path.join(root, "personal", "jobs"), false);
+    const companiesRoot = path.join(root, "companies");
+    walk(companiesRoot, true, companiesRoot);
+    return files.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+}
+function legacyYamlParseDiagnostics(file, d) {
+    // The shell evaluates each field with yq before checking the now-empty id;
+    // preserve the six parser diagnostics it emits on malformed input.
+    const expressions = [".id // \"\"", ".name // \"\"", ".runtime // \"\"", ".requirements.runtime // \"\"", ".requirements.company // \"\"", ".requirements.cwd // .cwd // \"\""];
+    return expressions.map((expression) => spawnSync("yq", ["-r", expression, file], {
+        cwd: d.root, env: d.env, encoding: "utf8",
+    }).stderr ?? "").join("");
+}
+function findById(id, d) {
+    let found;
+    for (const file of allFiles(d.root)) {
+        let job;
+        try {
+            job = yaml(file, d);
+        }
+        catch {
+            continue;
+        }
+        if (scalar(job.id) !== id)
+            continue;
+        if (found)
+            throw new Fatal(`duplicate job id '${id}' in registry: ${found} and ${file}`);
+        found = file;
+    }
+    return found;
+}
+function secretNames(output) {
+    let foundHeader = false;
+    const names = [];
+    for (const line of output.split(/\r?\n/)) {
+        if (/^NAME(?:\s|$)/.test(line)) {
+            foundHeader = true;
+            continue;
+        }
+        if (!foundHeader || /^\s*$/.test(line) || /^Secrets /.test(line))
+            continue;
+        const name = line.trim().split(/\s+/)[0] ?? "";
+        if (/^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/.test(name))
+            names.push(name);
+    }
+    return names;
+}
+function parseAssignments(body, allowed) {
+    const values = {};
+    for (const line of body.split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Z_]+)=(?:"([^"]*)"|'([^']*)'|([^#\s]*))\s*$/.exec(line);
+        if (m && allowed.includes(m[1]))
+            values[m[1]] = m[2] ?? m[3] ?? m[4] ?? "";
+    }
+    return values;
+}
+function resolveIdentity(d) {
+    let user = d.env.OUTPOST_USER_ID || "", token = d.env.OUTPOST_INSTANCE_TOKEN || "", outpost = d.env.OUTPOST_ID || "";
+    if (user && token)
+        return { user, token, outpost };
+    const identityFile = "/etc/outpost/codex-identity.env";
+    if (d.isFile(identityFile)) {
+        try {
+            const assignments = parseAssignments(d.readText(identityFile), ["OUTPOST_USER_ID", "OUTPOST_INSTANCE_TOKEN", "OUTPOST_ID"]);
+            // A sourced assignment replaces only its own field; an explicit empty value still clears it.
+            if (Object.hasOwn(assignments, "OUTPOST_USER_ID"))
+                user = assignments.OUTPOST_USER_ID;
+            if (Object.hasOwn(assignments, "OUTPOST_INSTANCE_TOKEN"))
+                token = assignments.OUTPOST_INSTANCE_TOKEN;
+            if (Object.hasOwn(assignments, "OUTPOST_ID"))
+                outpost = assignments.OUTPOST_ID;
+            if (user && token)
+                return { user, token, outpost };
+        }
+        catch { /* continue to runner with the environment values */ }
+    }
+    const runner = d.env.HQ_JOB_PROBE_RUNNER || "/usr/local/bin/outpost-runner.sh";
+    if (d.isFile(runner)) {
+        try {
+            const body = d.readText(runner), get = (k) => new RegExp(`^${k}="(.*)"$`, "m").exec(body)?.[1] ?? "";
+            if (!user)
+                user = get("USER_ID");
+            if (!token)
+                token = get("INSTANCE_TOKEN");
+            if (!outpost)
+                outpost = get("OUTPOST_ID");
+        }
+        catch { /* legacy sed is best-effort */ }
+    }
+    if (user && token)
+        return { user, token, outpost };
+    return undefined;
+}
+function auth(runtime, d) {
+    if (runtime !== "claude" && runtime !== "codex")
+        return "unknown_runtime";
+    if (!d.commandExists(runtime))
+        return "no_cli";
+    const file = runtime === "claude" ? d.env.HQ_JOB_PROBE_CLAUDE_CRED || path.join(d.home, ".claude/.credentials.json") : d.env.HQ_JOB_PROBE_CODEX_AUTH || path.join(d.home, ".codex/auth.json");
+    return (d.statSize(file) ?? 0) > 0 ? "ok" : "missing";
+}
+function writeAttempt(d, id, data) { d.writeState(path.join(d.env.HQ_JOB_PROBE_STATE_DIR || path.join(d.home, ".hq/jobs/probes"), id, "last-attempt.json"), compact(data)); }
+function writeCache(d, id, readiness, source) { d.writeState(path.join(d.env.HQ_JOB_STATUS_CACHE_DIR || path.join(d.home, ".hq/jobs/status-cache"), `${id}.json`), compact({ job_id: id, readiness, updated_at: isoNow(d), source })); }
+function resolveCwd(root, cwd, d) {
+    const canon = d.realpath(root) ?? path.resolve(root), candidate = path.resolve(root, cwd), file = d.realpath(candidate) ?? candidate;
+    return { file, allowed: file === canon || file.startsWith(`${canon}${path.sep}`) };
+}
+async function post(payload, token, d) {
+    const env = d.env, max = Number.parseInt(env.HQ_JOB_PROBE_MAX_ATTEMPTS || "3", 10), backoff = Number.parseInt(env.HQ_JOB_PROBE_BACKOFF_BASE_SEC || "1", 10);
+    const base = (env.HQ_PRO_API_URL || env.HQ_API_URL || env.HQ_VAULT_API_URL || "https://hqapi.hq.computer").replace(/\/$/, ""), bytes = compact(payload);
+    let http = 0, body = "", retryable = false;
+    for (let attempt = 1; attempt <= max; attempt += 1) {
+        try {
+            const abort = new AbortController(), timer = setTimeout(() => abort.abort(), 20_000);
+            let response;
+            try {
+                response = await d.fetcher(`${base}/outpost/internal/jobs-status`, { method: "POST", redirect: "manual", headers: { "content-type": "application/json", "x-outpost-instance-token": token }, body: bytes, signal: abort.signal });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            http = response.status;
+            body = await response.text();
+        }
+        catch (e) {
+            const timedOut = e instanceof Error && e.name === "AbortError";
+            http = 0;
+            body = compact({ error: true, code: "StatusIngestError", step: "lookup", message: `curl failed rc=${timedOut ? 28 : 7} (API unreachable)`, retryable: true });
+        }
+        if (http >= 200 && http < 300)
+            return { http, body, retryable: false };
+        let res = {};
+        try {
+            res = obj(JSON.parse(body));
+        }
+        catch { /* invalid body is not retryable unless http says so */ }
+        retryable = http === 0 || http >= 500 || res.retryable === true || (res.code === "StatusIngestError" && ["persist", "lookup", "config"].includes(String(res.step)));
+        if (!retryable || attempt >= max)
+            break;
+        d.writeStderr(`hq-job-probe: ingest attempt ${attempt}/${max} failed (http=${http}); backoff ${backoff * (2 ** (attempt - 1))}s\n`);
+        await d.sleep(backoff * (2 ** (attempt - 1)));
+    }
+    return { http, body, retryable };
+}
+async function probeFile(file, dry, d) {
+    if (!d.isFile(file))
+        throw new Fatal(`job file not found: ${file}`);
+    let job;
+    try {
+        job = yaml(file, d);
+    }
+    catch (e) {
+        const rawStderr = legacyYamlParseDiagnostics(file, d);
+        if (rawStderr)
+            throw new Fatal(`job missing id: ${file}`, 2, "hq-job-probe", rawStderr);
+        throw new Fatal(`invalid job YAML: ${file}${e instanceof Error ? `: ${e.message}` : ""}`);
+    }
+    const id = scalar(job.id), name = scalar(job.name), runtime = scalar(nested(job, "requirements", "runtime")) || scalar(job.runtime);
+    const company = scalar(nested(job, "requirements", "company")), cwd = scalar(nested(job, "requirements", "cwd") ?? job.cwd);
+    if (!id)
+        throw new Fatal(`job missing id: ${file}`);
+    if (!runtime)
+        throw new Fatal(`job missing runtime: ${file}`);
+    const at = isoNow(d), actions = [], authState = auth(runtime, d);
+    let blocked = false;
+    if (authState === "no_cli") {
+        blocked = true;
+        actions.push(`install ${runtime} CLI on Outpost and re-login`);
+    }
+    else if (authState === "missing") {
+        blocked = true;
+        actions.push(`device re-login for ${runtime} on Outpost (cached credentials missing)`);
+    }
+    else if (authState !== "ok") {
+        blocked = true;
+        actions.push(`unsupported runtime '${runtime}' — fix job requirements.runtime`);
+    }
+    const listed = await d.listSecrets(company || undefined), missing = [];
+    let secretState = "ok";
+    if (listed.code !== 0) {
+        blocked = true;
+        secretState = "list_failed";
+        actions.push(company ? `hq secrets list --company ${company} failed on Outpost — check hq login / vault access` : "hq secrets list --personal failed on Outpost — check hq login / vault access");
+    }
+    else {
+        const names = new Set(secretNames(listed.stdout)), required = nested(job, "requirements", "secrets");
+        for (const v of Array.isArray(required) ? required : []) {
+            const n = scalar(v);
+            if (n && n !== "null" && !names.has(n))
+                missing.push(n);
+        }
+        if (missing.length) {
+            blocked = true;
+            secretState = "missing";
+            for (const n of missing)
+                actions.push(`hq secrets share ${n} (grant Outpost owner visibility; names only — never paste values)`);
+        }
+    }
+    let cwdState = "ok";
+    if (!cwd || cwd === "null")
+        cwdState = "skipped";
+    else if (cwd.startsWith("/")) {
+        blocked = true;
+        cwdState = "invalid";
+        actions.push("fix cwd to HQ-root-relative path (absolute not allowed)");
+    }
+    else if (cwd.split("/").includes("..")) {
+        blocked = true;
+        cwdState = "invalid";
+        actions.push("fix cwd — remove '..' path components");
+    }
+    else {
+        const target = resolveCwd(d.root, cwd, d);
+        if (!target.allowed) {
+            blocked = true;
+            cwdState = "invalid";
+            actions.push("fix cwd — must resolve under HQ root");
+        }
+        else if (!d.isDirectory(target.file)) {
+            blocked = true;
+            cwdState = "missing";
+            actions.push(`create cwd on Outpost HQ tree: ${cwd}`);
+        }
+    }
+    let companyState = "ok";
+    if (company && company !== "null" && !d.isDirectory(path.join(d.root, "companies", company))) {
+        companyState = "missing";
+        blocked = true;
+    }
+    else if (!company || company === "null")
+        companyState = "skipped";
+    const readiness = blocked ? "blocked" : "ready", actionsUnique = [...new Set(actions)];
+    const checks = { runtime, auth: authState, secrets: { status: secretState, missing }, cwd: cwdState, company: companyState === "skipped" ? { status: companyState } : { status: companyState, slug: company } };
+    const payload = { userId: d.env.OUTPOST_USER_ID || "", jobId: id, kind: "probe", readiness, probed_at: at, event_id: `probe-${at}-${id}`, next_actions: actionsUnique, checks };
+    let ingest, http = 0, finalReadiness = readiness, finalActions = actionsUnique, ingestFailed = false;
+    if (dry) {
+        ingest = "dry_run";
+        writeCache(d, id, readiness, "probe-dry-run");
+    }
+    else {
+        const authIdentity = resolveIdentity(d);
+        if (!authIdentity) {
+            ingestFailed = true;
+            ingest = "StatusIngestError";
+            finalReadiness = "unknown";
+            finalActions = [...actionsUnique, "status ingest failed — retry probe"];
+            writeAttempt(d, id, { job_id: id, probed_at: at, local_readiness: readiness, ingest: { ok: false, code: "StatusIngestError", step: "config", message: "missing Outpost identity (OUTPOST_USER_ID / OUTPOST_INSTANCE_TOKEN)", retryable: true }, reported_readiness: null, next_actions: finalActions, checks });
+        }
+        else {
+            const body = { ...payload, userId: authIdentity.user, ...(authIdentity.outpost ? { outpostId: authIdentity.outpost } : {}) }, res = await post(body, authIdentity.token, d);
+            http = res.http;
+            if (http >= 200 && http < 300) {
+                ingest = "ok";
+                writeAttempt(d, id, { job_id: id, probed_at: at, local_readiness: readiness, ingest: { ok: true, http }, reported_readiness: readiness, next_actions: actionsUnique, checks });
+                writeCache(d, id, readiness, "probe-ingest");
+            }
+            else {
+                ingestFailed = true;
+                ingest = "StatusIngestError";
+                finalReadiness = "unknown";
+                finalActions = [...actionsUnique, "status ingest failed — retry probe"];
+                let response;
+                try {
+                    response = JSON.parse(res.body);
+                }
+                catch {
+                    response = { raw: res.body };
+                }
+                writeAttempt(d, id, { job_id: id, probed_at: at, local_readiness: readiness, ingest: { ok: false, code: "StatusIngestError", http, retryable: res.retryable, body: response }, reported_readiness: null, next_actions: finalActions, checks });
+            }
+        }
+    }
+    return { code: ingestFailed ? 3 : blocked ? 1 : 0, value: { job_id: id, name, job_file: file, readiness: finalReadiness, probed_at: at, ingest, http, dry_run: dry, checks, next_actions: finalActions } };
+}
+function parseArgs(argv) {
+    const a = [...argv];
+    let root, dry = false, all = false, target = "";
+    while (a.length) {
+        const x = a[0];
+        if (x === "--hq-root") {
+            root = a[1] ?? "";
+            if (!root)
+                throw new Fatal("--hq-root requires a directory");
+            a.splice(0, 2);
+        }
+        else if (x === "--dry-run" || x === "--no-ingest") {
+            dry = true;
+            a.shift();
+        }
+        else if (x === "--all") {
+            all = true;
+            a.shift();
+        }
+        else if (x === "--json")
+            a.shift();
+        else if (x === "-h" || x === "--help")
+            return { help: true, dry, all, target };
+        else if (x === "--") {
+            a.shift();
+            break;
+        }
+        else if (x.startsWith("-"))
+            throw new Fatal(`unknown option: ${x}`);
+        else {
+            if (target)
+                throw new Fatal(`unexpected argument: ${x}`);
+            target = x;
+            a.shift();
+        }
+    }
+    return { root, dry, all, target };
+}
+export async function runJobProbe(argv, injected) {
+    let opts;
+    try {
+        opts = parseArgs(argv);
+    }
+    catch (x) {
+        const e = x instanceof Fatal ? x : new Fatal(String(x));
+        return { code: e.code, stdout: "", stderr: `${e.prefix}: ${e.message}\n` };
+    }
+    if (opts.help)
+        return { code: 0, stdout: JOB_PROBE_USAGE, stderr: "" };
+    const root = opts.root || injected?.root || process.env.HQ_ROOT || process.cwd();
+    const d = injected ? { ...injected, root } : defaultProbeDeps(root), output = [];
+    const failure = (x) => { const e = x instanceof Fatal ? x : new Fatal(String(x)); return { code: e.code, stdout: output.map((s) => `${s}\n`).join(""), stderr: `${e.rawStderr}${e.prefix}: ${e.message}\n` }; };
+    if (opts.all) {
+        if (opts.target)
+            return { code: 2, stdout: "", stderr: "hq-job-probe: --all does not take a job argument\n" };
+        const files = allFiles(root);
+        if (!files.length)
+            return { code: 2, stdout: "", stderr: `hq-job-probe: no job YAML found under personal/jobs or companies/*/jobs in ${root}\n` };
+        let code = 0;
+        try {
+            for (const f of files) {
+                const r = await probeFile(f, opts.dry, d);
+                output.push(compact(r.value));
+                code = Math.max(code, r.code);
+            }
+        }
+        catch (x) {
+            return failure(x);
+        }
+        return { code, stdout: output.map((s) => `${s}\n`).join(""), stderr: "" };
+    }
+    if (!opts.target)
+        return { code: 2, stdout: "", stderr: "hq-job-probe: usage: hq-job-probe.sh [--dry-run] <job.yaml|job-id> | --all\n" };
+    let file;
+    if (d.isFile(opts.target))
+        file = opts.target;
+    else if (d.isFile(path.join(root, opts.target)))
+        file = path.join(root, opts.target);
+    else {
+        try {
+            file = findById(opts.target, d);
+        }
+        catch (x) {
+            // The shell's duplicate-ID die runs inside process substitution; its caller
+            // then emits the ordinary not-found error after the process substitution
+            // closes. Preserve both stderr lines for byte parity.
+            if (x instanceof Fatal && x.message.startsWith("duplicate job id '")) {
+                return { code: x.code, stdout: "", stderr: `${x.prefix}: ${x.message}\n${x.prefix}: job id not found in registry: ${opts.target}\n` };
+            }
+            return failure(x);
+        }
+        if (!file)
+            return { code: 2, stdout: "", stderr: `hq-job-probe: job id not found in registry: ${opts.target}\n` };
+    }
+    try {
+        const r = await probeFile(file, opts.dry, d);
+        return { code: r.code, stdout: `${compact(r.value)}\n`, stderr: "" };
+    }
+    catch (x) {
+        return failure(x);
+    }
+}
+function rawArgs(command, fallback) { let cursor = 0, start = -1; for (const n of ["core", "job", "probe"]) {
+    const i = process.argv.indexOf(n, cursor);
+    if (i < 0)
+        return command.args.length ? command.args : fallback;
+    cursor = i + 1;
+    start = cursor;
+} return start < 0 ? fallback : process.argv.slice(start); }
+function registrationRootOptions(argv) {
+    let help = false, hasRoot = false, root;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--")
+            break;
+        if (arg === "-h" || arg === "--help")
+            help = true;
+        if (arg === "--hq-root") {
+            hasRoot = true;
+            root = argv[index + 1];
+            index += 1;
+        }
+    }
+    return { help, hasRoot, root };
+}
+export function registerCoreJobProbeCommand(job) {
+    const command = job.command("probe").description("Check scheduled-job requirements and report readiness").helpOption(false).allowUnknownOption().allowExcessArguments(true).argument("[args...]")
+        .action(async (args = [], _options, current) => {
+        const argv = rawArgs(current, args), core = job.parent, forwarded = registrationRootOptions(argv);
+        const root = !forwarded.help && (!forwarded.hasRoot || Boolean(forwarded.root))
+            ? resolveLiveRoot({ hqRoot: forwarded.hasRoot ? forwarded.root : core.opts().hqRoot })
+            : undefined;
+        if (!await coreNativeJobsEnabled()) {
+            const r = runBundledScript({ asset: JOB_PROBE_ASSET, args: argv, cwd: process.cwd(), ...(root ? { hqRoot: root } : {}) });
+            if (r.code)
+                process.exit(r.code);
+            return;
+        }
+        const r = await runJobProbe(argv, defaultProbeDeps(root ?? (process.env.HQ_ROOT || process.cwd())));
+        if (r.stdout)
+            process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+        if (r.stderr)
+            process.stderr.write(r.stderr);
+        if (r.code)
+            process.exit(r.code);
+    });
+    describeCoreCommand(command, { execution: "native", root: "live" });
+}
+//# sourceMappingURL=core-job-probe-native.js.map

package/dist/commands/core-job-remediate-native.d.ts

@@ -0,0 +1,26 @@
+/** Native TypeScript port of hq-job-remediate.sh. */
+import { Command } from "commander";
+type Environment = Record<string, string | undefined>;
+export type JobRemediateRunOptions = {
+    cwd: string;
+    env: Environment;
+    logPath: string;
+};
+export type JobRemediateDependencies = {
+    env: Environment;
+    cwd: string;
+    /** Guard seam: this command must never inspect credential file contents. */
+    readFile: (file: string) => string;
+    commandExists: (command: string) => boolean;
+    run: (command: string, args: string[], options: JobRemediateRunOptions) => number;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+};
+export declare function defaultJobRemediateDependencies(env?: Environment, cwd?: string): JobRemediateDependencies;
+export declare function runJobRemediate(argv: string[], options?: {
+    hqRoot?: string;
+    dependencies?: Partial<JobRemediateDependencies>;
+}): number;
+export declare function registerCoreJobRemediateNativeCommand(group: Command, core: Command): void;
+export {};
+//# sourceMappingURL=core-job-remediate-native.d.ts.map