@indigoai-us/hq-cli 5.291.0 → 5.292.0

package/dist/commands/core-jobs-native.js

@@ -3,11 +3,14 @@ import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import { JSON_SCHEMA, load, loadAll } from "js-yaml";
 import { matchingSecretPatterns } from "../lib/core-utils/secret-patterns.js";
+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";
 const SCHEDULE_PARSE_ASSET = "core/scripts/jobs-schedule-parse.sh";
 const VALIDATE_ASSET = "core/scripts/jobs-validate.sh";
+const RECONCILE_ASSET = "core/scripts/outpost-jobs-reconcile.sh";
 const SCHEDULE_PARSE_USAGE = 'usage: jobs-schedule-parse.sh [--tz IANA] "<nl or cron schedule>"\n';
 const VALIDATE_USAGE = "usage: jobs-validate.sh <file-or-dir> [file-or-dir...]\n";
 const CRON_RE = /^(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)$/;
@@ -579,6 +582,704 @@ export function validateJobs(args) {
     }
     return 0;
 }
+const RECONCILE_USAGE = `outpost-jobs-reconcile.sh — registry YAML → systemd user timers (US-004).
+
+Reads personal/jobs/*.yaml and companies/*/jobs/*.yaml from the box HQ tree,
+validates each with jobs-validate.sh, and materializes disposable units:
+  ~/.config/systemd/user/hq-job-{id}.service
+  ~/.config/systemd/user/hq-job-{id}.timer
+with Persistent=true and RandomizedDelaySec. Timers are armed only when
+hq-pro jobs status readiness=ready (box cache from probe ingest, or live
+GET when available). Disabled/deleted jobs have units removed.
+
+Company-scoped jobs materialize only when job.owner matches this Outpost's
+owner identity (creator's box only in v1).
+
+Usage:
+  core/scripts/outpost-jobs-reconcile.sh [options]
+  core/scripts/outpost-jobs-reconcile.sh --after-sync   # post-sync entrypoint
+
+Options:
+  --hq-root DIR       HQ tree root (default: HQ_ROOT or repo root above core/)
+  --dry-run           Write units to unit dir / print plan; skip systemctl
+  --no-probe          Do not probe non-ready jobs
+  --probe-only        Probe non-ready jobs then exit (no unit changes)
+  --ensure-hook       Install personal/hooks/Stop/90-outpost-jobs-reconcile.sh
+  --after-sync        Alias for default reconcile + probe path (sync Stop hook)
+  -h, --help
+
+Env / overrides (tests):
+  HQ_ROOT, HOME, HQ_JOB_UNIT_DIR, HQ_JOB_SYSTEMCTL, HQ_JOB_STATUS_CACHE_DIR
+  HQ_JOB_OWNER_EMAIL, HQ_JOB_OWNER_UID, OUTPOST_USER_ID, OUTPOST_ID
+  HQ_JOB_RANDOMIZE_SEC (default 60), HQ_JOB_RECONCILE_STATE
+  HQ_PRO_API_URL / HQ_API_URL / HQ_VAULT_API_URL, HQ_ACCESS_TOKEN (optional GET)
+
+Exit: 0 success; 1 partial failures; 2 usage/config.
+`;
+function commandResult(command, args) {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        status: result.status ?? (result.error ? 127 : 1),
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+function isExecutable(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function findExecutable(command, searchPath) {
+    if (path.isAbsolute(command) || command.includes(path.sep)) {
+        return isExecutable(command) ? command : undefined;
+    }
+    for (const directory of searchPath.split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = path.join(directory, command);
+        if (isExecutable(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function shellText(value) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+function parseIdentityAssignments(contents) {
+    const values = [];
+    for (const line of contents.split(/\r?\n/)) {
+        const assignment = /^\s*(?:export\s+)?(OUTPOST_USER_ID|OUTPOST_OWNER_EMAIL|OWNER_EMAIL)\s*=\s*(.*?)\s*$/.exec(line);
+        if (!assignment)
+            continue;
+        let value = assignment[2] ?? "";
+        if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) {
+            value = value.slice(1, -1);
+        }
+        else {
+            value = value.replace(/\s+#.*$/, "");
+        }
+        values.push(value);
+    }
+    return values;
+}
+function identityFileTokens(options) {
+    if (process.env.HQ_JOB_SKIP_SYSTEM_IDENTITY === "1")
+        return [];
+    const filename = "/etc/outpost/codex-identity.env";
+    try {
+        const contents = options.identityFileReader
+            ? options.identityFileReader(filename)
+            : fs.readFileSync(filename, "utf8");
+        return contents ? parseIdentityAssignments(contents) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function resolveBoxOwners(options) {
+    const owners = [];
+    const add = (value) => {
+        if (!value || value === "null" || owners.includes(value))
+            return;
+        owners.push(value);
+    };
+    add(process.env.HQ_JOB_OWNER_EMAIL);
+    add(process.env.HQ_JOB_OWNER_UID);
+    add(process.env.OUTPOST_USER_ID);
+    const searchPath = process.env.PATH ?? "";
+    if (findExecutable("hq", searchPath)) {
+        const run = options.commandRunner ?? commandResult;
+        let result = run("hq", ["whoami", "--json"]);
+        if (result.status !== 0)
+            result = run("hq", ["whoami"]);
+        const who = result.stdout;
+        if (who) {
+            let parsed;
+            try {
+                parsed = JSON.parse(who);
+            }
+            catch {
+                parsed = undefined;
+            }
+            let email = "";
+            if (parsed && typeof parsed === "object") {
+                const record = parsed;
+                const user = record.user && typeof record.user === "object"
+                    ? record.user
+                    : undefined;
+                email = shellText(record.email ?? user?.email);
+                add(email);
+                add(shellText(record.personUid ?? record.person_uid ?? record.uid));
+            }
+            if (!email) {
+                const humanEmail = /.*Email:\s*(.*)/i.exec(who)?.[1]
+                    ?? /.*email\s*[:=]\s*(.*)/i.exec(who)?.[1];
+                if (humanEmail)
+                    add(humanEmail.replace(/\s/g, ""));
+            }
+        }
+    }
+    for (const value of identityFileTokens(options))
+        add(value);
+    return owners;
+}
+function ownerMatches(jobOwner, owners) {
+    if (!jobOwner)
+        return false;
+    return owners.some((owner) => owner === jobOwner
+        || (owner.includes("@") && owner.toLowerCase() === jobOwner.toLowerCase()));
+}
+function compareReconcilePaths(left, right) {
+    return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}
+function addYamlFilesAtDepth(directory, maxDepth) {
+    const result = [];
+    const walk = (current, depth) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const file = path.join(current, entry.name);
+            if (entry.isFile() && depth <= maxDepth && /\.(yaml|yml)$/.test(entry.name)) {
+                result.push(file);
+            }
+            else if (entry.isDirectory() && depth < maxDepth) {
+                walk(file, depth + 1);
+            }
+        }
+    };
+    walk(directory, 1);
+    return result;
+}
+function collectReconcileJobs(root) {
+    const files = addYamlFilesAtDepth(path.join(root, "personal", "jobs"), 1);
+    const companies = path.join(root, "companies");
+    let companyEntries = [];
+    try {
+        companyEntries = fs.readdirSync(companies, { withFileTypes: true });
+    }
+    catch { /* A missing companies tree is empty. */ }
+    for (const company of companyEntries) {
+        if (!company.isDirectory())
+            continue;
+        files.push(...addYamlFilesAtDepth(path.join(companies, company.name, "jobs"), 1));
+    }
+    return files
+        .filter((file) => !file.includes(".conflict-") && !file.includes(`${path.sep}.conflicts${path.sep}`))
+        .sort(compareReconcilePaths);
+}
+function readJobValue(file) {
+    try {
+        const parsed = parseJobFile(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function reconcileJobIsValid(file) {
+    const errors = [];
+    try {
+        validateJob(file, parseJobFile(fs.readFileSync(file, "utf8")), [], (_path, _field, message) => errors.push(message));
+        return errors.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function parseData(contents) {
+    return load(contents, { schema: JSON_SCHEMA, json: true });
+}
+function recordOf(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function writeReadinessCache(cacheDir, id, readiness, source, options) {
+    const filename = path.join(cacheDir, `${id}.json`);
+    const updatedAt = (options.now?.() ?? new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+    fs.writeFileSync(filename, serializeJqJson({ job_id: id, readiness, updated_at: updatedAt, source }, "compact"));
+    try {
+        fs.chmodSync(filename, 0o600);
+    }
+    catch { /* The shell ignores chmod failure. */ }
+}
+function cachedReadiness(cacheDir, home, id) {
+    try {
+        const record = recordOf(parseData(fs.readFileSync(path.join(cacheDir, `${id}.json`), "utf8")));
+        const value = record?.readiness;
+        if (value !== undefined && value !== null && value !== false)
+            return shellText(value);
+        if (value === false)
+            return "unknown";
+    }
+    catch { /* The shell falls through to the probe marker. */ }
+    try {
+        const marker = JSON.parse(fs.readFileSync(path.join(home, ".hq", "jobs", "probes", id, "last-attempt.json"), "utf8"));
+        const reported = marker.reported_readiness;
+        if (reported !== undefined && reported !== null && reported !== false && reported !== "")
+            return shellText(reported);
+    }
+    catch { /* No successful prior probe marker. */ }
+    return "unknown";
+}
+async function liveReadiness(id, cacheDir, options) {
+    if (process.env.HQ_JOB_DISABLE_LIVE_READINESS === "1")
+        return undefined;
+    const token = process.env.HQ_ACCESS_TOKEN;
+    if (!token)
+        return undefined;
+    const api = process.env.HQ_PRO_API_URL || process.env.HQ_API_URL || process.env.HQ_VAULT_API_URL || "https://hqapi.hq.computer";
+    const url = `${api.replace(/\/$/, "")}/outpost/jobs/status/${id}`;
+    try {
+        const response = await (options.fetcher ?? fetch)(url, {
+            method: "GET",
+            headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok)
+            return undefined;
+        const body = recordOf(await response.json());
+        const status = recordOf(body?.status);
+        const readiness = status?.readiness !== undefined && status.readiness !== null && status.readiness !== false
+            ? status.readiness
+            : body?.readiness;
+        if (readiness === undefined || readiness === null || readiness === false || readiness === "")
+            return undefined;
+        const result = shellText(readiness);
+        writeReadinessCache(cacheDir, id, result, "api-get", options);
+        return result;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function jobReadiness(id, cacheDir, home, options) {
+    return await liveReadiness(id, cacheDir, options) ?? cachedReadiness(cacheDir, home, id);
+}
+function probeValue(output, field) {
+    try {
+        const record = recordOf(JSON.parse(output));
+        const value = record?.[field];
+        return value === undefined || value === null ? "" : shellText(value);
+    }
+    catch {
+        return "";
+    }
+}
+function cronDowNumber(value) {
+    const names = { "0": "Sun", "1": "Mon", "2": "Tue", "3": "Wed", "4": "Thu", "5": "Fri", "6": "Sat", "7": "Sun" };
+    return names[value];
+}
+function cronDowTokenToSystemd(token) {
+    if (/^[0-7]+-[0-7]+$/.test(token)) {
+        const [from, to] = token.split("-");
+        const start = cronDowNumber(from ?? "");
+        const end = cronDowNumber(to ?? "");
+        return start && end ? `${start}..${end}` : undefined;
+    }
+    const lower = token.toLowerCase();
+    const names = {
+        sun: "Sun", "0": "Sun", "7": "Sun", mon: "Mon", "1": "Mon",
+        tue: "Tue", "2": "Tue", wed: "Wed", "3": "Wed", thu: "Thu", "4": "Thu",
+        fri: "Fri", "5": "Fri", sat: "Sat", "6": "Sat", "mon..fri": "Mon..Fri", "1-5": "Mon..Fri",
+    };
+    return names[lower];
+}
+function cronDowToSystemd(field) {
+    if (field === "*" || field === "*/1")
+        return "";
+    const mapped = [];
+    for (const part of field.split(/[\s,]+/)) {
+        const value = cronDowTokenToSystemd(part);
+        if (!value)
+            return undefined;
+        mapped.push(value);
+    }
+    return mapped.join(",");
+}
+function padCronField(value) {
+    return value.length === 1 ? `0${value}` : value;
+}
+function cronTimeField(field) {
+    if (field === "*")
+        return "";
+    if (field.includes("/"))
+        return `*/${field.slice(field.indexOf("/") + 1)}`;
+    if (field.includes("-"))
+        return field;
+    return /^\d+$/.test(field) ? padCronField(field) : field;
+}
+function cronToOnCalendar(fields) {
+    const [minute = "", hour = "", dom = "", month = "", dow = ""] = fields;
+    const dowValue = cronDowToSystemd(dow) ?? "";
+    const monthValue = month === "*" ? "*" : padCronField(month);
+    const dayValue = dom === "*" ? "*" : padCronField(dom);
+    const date = `*-${monthValue}-${dayValue}`;
+    const minuteValue = cronTimeField(minute) || "00";
+    const hourValue = cronTimeField(hour) || "*";
+    let time;
+    if (hourValue === "*")
+        time = `*:${minuteValue}:00`;
+    else if (hourValue.includes("/"))
+        time = `0/${hourValue.slice(hourValue.indexOf("/") + 1)}:${minuteValue}:00`;
+    else
+        time = `${hourValue}:${minuteValue}:00`;
+    return dowValue ? `${dowValue} ${date} ${time}` : `${date} ${time}`;
+}
+function normalizeServicePath(value) {
+    const entries = [];
+    for (const entry of value.split(":")) {
+        if (entry.startsWith("/") && !entries.includes(entry))
+            entries.push(entry);
+    }
+    return entries.join(":");
+}
+function servicePathValue() {
+    let servicePath = normalizeServicePath(process.env.PATH || "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin");
+    const hq = findExecutable("hq", servicePath);
+    if (hq) {
+        let binDirectory = "";
+        try {
+            binDirectory = fs.realpathSync(path.dirname(hq));
+        }
+        catch { /* `pwd -P` failed in the shell equivalent. */ }
+        if (binDirectory && !servicePath.split(":").includes(binDirectory))
+            servicePath = [binDirectory, servicePath].filter(Boolean).join(":");
+    }
+    return servicePath;
+}
+function systemdQuote(value) {
+    return `"${value.replace(/%/g, "%%").replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
+}
+function serviceUnit(root, runner, id) {
+    const pathValue = systemdQuote(`PATH=${servicePathValue()}`);
+    return `# Generated by outpost-jobs-reconcile.sh — disposable derived state. Do not edit.\n[Unit]\nDescription=HQ Outpost scheduled job: ${id}\nDocumentation=file://${root}/core/knowledge/public/hq-core/outpost-jobs-spec.md\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=oneshot\nEnvironment=HQ_ROOT=${root}\nEnvironment=${pathValue}\nExecStart=${runner} --hq-root ${root} --job-id ${id}\nNice=10\n\n[Install]\nWantedBy=default.target\n`;
+}
+function timerUnit(id, onCalendar, randomize, root) {
+    return `# Generated by outpost-jobs-reconcile.sh — disposable derived state. Do not edit.\n[Unit]\nDescription=HQ Outpost scheduled job timer: ${id}\nDocumentation=file://${root}/core/knowledge/public/hq-core/outpost-jobs-spec.md\n\n[Timer]\nOnCalendar=${onCalendar}\nPersistent=true\nRandomizedDelaySec=${randomize}\nUnit=hq-job-${id}.service\n\n[Install]\nWantedBy=timers.target\n`;
+}
+function systemctlResult(args, dryRun, command, options) {
+    if (dryRun) {
+        process.stderr.write(`outpost-jobs-reconcile: dry-run systemctl --user ${args.join(" ")}\n`);
+        return { status: 0, stdout: "", stderr: "" };
+    }
+    if (command === ":" || command === "true")
+        return { status: 0, stdout: "", stderr: "" };
+    if (!options.schedulerRunner && !findExecutable(command, process.env.PATH ?? "")) {
+        process.stderr.write(`outpost-jobs-reconcile: systemctl not available — units written but not enabled (${args.join(" ")})\n`);
+        return { status: 0, stdout: "", stderr: "" };
+    }
+    if (process.env.HQ_JOB_TEST_SCHEDULER_STUB === "1" && !options.schedulerRunner) {
+        return { status: 127, stdout: "", stderr: "scheduler stub was requested but no injected runner was supplied" };
+    }
+    try {
+        const runner = options.schedulerRunner ?? commandResult;
+        return runner(command, ["--user", ...args]);
+    }
+    catch (error) {
+        return { status: 127, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+    }
+}
+function installSyncHook(root) {
+    const directory = path.join(root, "personal", "hooks", "Stop");
+    const filename = path.join(directory, "90-outpost-jobs-reconcile.sh");
+    fs.mkdirSync(directory, { recursive: true });
+    const contents = [
+        "#!/usr/bin/env bash",
+        "# Auto-installed by outpost-jobs-reconcile.sh --ensure-hook (US-004).",
+        "# hq-sync-runner executes personal/hooks/Stop/* after each sync cycle.",
+        "set -u",
+        'HQ_ROOT="${OUTPOST_HQ_ROOT:-${HQ_ROOT:-/home/ec2-user/hq}}"',
+        'RECONCILE="$HQ_ROOT/core/scripts/outpost-jobs-reconcile.sh"',
+        'if [ -x "$RECONCILE" ] || [ -f "$RECONCILE" ]; then',
+        '  bash "$RECONCILE" --hq-root "$HQ_ROOT" --after-sync >>"${HOME}/.hq/jobs/reconcile/after-sync.log" 2>&1 || true',
+        "fi",
+        "",
+    ].join("\n");
+    fs.writeFileSync(filename, contents);
+    fs.chmodSync(filename, 0o755);
+    process.stderr.write(`outpost-jobs-reconcile: installed sync Stop hook: ${filename}\n`);
+}
+function disableRemoveUnits(id, unitDir, command, dryRun, options) {
+    for (const args of [["disable", "--now", `hq-job-${id}.timer`], ["stop", `hq-job-${id}.service`]]) {
+        const result = systemctlResult(args, dryRun, command, options);
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+    }
+    fs.rmSync(path.join(unitDir, `hq-job-${id}.service`), { force: true });
+    fs.rmSync(path.join(unitDir, `hq-job-${id}.timer`), { force: true });
+}
+function jobEnabled(job) {
+    return job.enabled === undefined ? "true" : shellText(job.enabled);
+}
+function isCompanyJobPath(file) {
+    return file.split(path.sep).join("/").includes("/companies/");
+}
+function reconcileDie(message) {
+    process.stderr.write(`outpost-jobs-reconcile: ${message}\n`);
+    return 2;
+}
+export async function runReconcile(argv, rootArg, options = {}) {
+    let root = rootArg ?? process.env.HQ_ROOT ?? "";
+    let dryRun = false;
+    let noProbe = false;
+    let probeOnly = false;
+    let ensureHook = false;
+    const args = [...argv];
+    for (let index = 0; index < args.length;) {
+        const arg = args[index];
+        if (arg === "--hq-root") {
+            const value = args[index + 1] ?? "";
+            if (!value)
+                return reconcileDie("--hq-root requires a directory");
+            root = value;
+            index += 2;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+            index += 1;
+        }
+        else if (arg === "--no-probe") {
+            noProbe = true;
+            index += 1;
+        }
+        else if (arg === "--probe-only") {
+            probeOnly = true;
+            index += 1;
+        }
+        else if (arg === "--ensure-hook") {
+            ensureHook = true;
+            index += 1;
+        }
+        else if (arg === "--after-sync") {
+            index += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write(`${RECONCILE_USAGE}\n`);
+            return 0;
+        }
+        else if (arg?.startsWith("-")) {
+            return reconcileDie(`unknown option: ${arg}`);
+        }
+        else if (arg !== undefined) {
+            return reconcileDie(`unexpected argument: ${arg}`);
+        }
+    }
+    if (!root)
+        root = resolveLiveRoot();
+    const validator = path.join(root, "core", "scripts", "jobs-validate.sh");
+    const runner = path.join(root, "core", "scripts", "hq-job-run.sh");
+    const probe = path.join(root, "core", "scripts", "hq-job-probe.sh");
+    if (!fs.existsSync(validator))
+        return reconcileDie("missing jobs-validate.sh");
+    if (!fs.existsSync(runner))
+        return reconcileDie("missing hq-job-run.sh");
+    if (!fs.existsSync(probe))
+        return reconcileDie("missing hq-job-probe.sh");
+    const home = process.env.HOME ?? "";
+    const unitDir = process.env.HQ_JOB_UNIT_DIR || path.join(home, ".config", "systemd", "user");
+    const cacheDir = process.env.HQ_JOB_STATUS_CACHE_DIR || path.join(home, ".hq", "jobs", "status-cache");
+    const stateDir = process.env.HQ_JOB_RECONCILE_STATE || path.join(home, ".hq", "jobs", "reconcile");
+    const systemctl = process.env.HQ_JOB_SYSTEMCTL || "systemctl";
+    const randomize = process.env.HQ_JOB_RANDOMIZE_SEC || "60";
+    for (const directory of [unitDir, cacheDir, stateDir])
+        fs.mkdirSync(directory, { recursive: true });
+    const log = (message) => {
+        process.stderr.write(`outpost-jobs-reconcile: ${message}\n`);
+    };
+    const commandRunner = options.commandRunner ?? commandResult;
+    const owners = resolveBoxOwners(options);
+    let errors = 0;
+    let armed = 0;
+    let skipped = 0;
+    let removed = 0;
+    let probed = 0;
+    const desired = new Set();
+    if (ensureHook)
+        installSyncHook(root);
+    if (!noProbe) {
+        for (const file of collectReconcileJobs(root)) {
+            if (!reconcileJobIsValid(file))
+                continue;
+            const job = readJobValue(file);
+            const id = shellText(job.id);
+            if (!id)
+                continue;
+            if (isCompanyJobPath(file) && !ownerMatches(shellText(job.owner), owners))
+                continue;
+            const readiness = await jobReadiness(id, cacheDir, home, options);
+            if (readiness === "ready")
+                continue;
+            log(`probe ${id} (cached readiness=${readiness})`);
+            const result = commandRunner("bash", [probe, "--hq-root", root, file]);
+            probed += 1;
+            const probeReadiness = probeValue(result.stdout, "readiness");
+            if (probeReadiness) {
+                const ingest = probeValue(result.stdout, "ingest");
+                if (ingest === "ok" || ingest === "dry_run")
+                    writeReadinessCache(cacheDir, id, probeReadiness, "probe", options);
+                else if (probeReadiness === "blocked")
+                    writeReadinessCache(cacheDir, id, "blocked", "probe-local", options);
+            }
+            if (result.status >= 2 && result.status !== 3)
+                errors += 1;
+        }
+    }
+    if (probeOnly) {
+        log(`probe-only done (probed=${probed} errors=${errors})`);
+        return errors === 0 ? 0 : 1;
+    }
+    for (const file of collectReconcileJobs(root)) {
+        const job = readJobValue(file);
+        const idHint = shellText(job.id);
+        const timezone = shellText(job.timezone);
+        if (timezone && !/^[A-Za-z0-9/_+-]+$/.test(timezone)) {
+            log(`skip ${idHint || "unknown"} — invalid timezone contains unsafe characters`);
+            errors += 1;
+            continue;
+        }
+        if (!reconcileJobIsValid(file)) {
+            log(`skip invalid job YAML: ${file}`);
+            errors += 1;
+            continue;
+        }
+        const id = idHint;
+        const name = shellText(job.name);
+        const owner = shellText(job.owner);
+        const schedule = shellText(job.schedule);
+        const companyJob = isCompanyJobPath(file);
+        const timerPath = path.join(unitDir, `hq-job-${id}.timer`);
+        const servicePath = path.join(unitDir, `hq-job-${id}.service`);
+        if (companyJob && !ownerMatches(owner, owners)) {
+            log(`skip company job ${id} — owner '${owner}' does not match this Outpost`);
+            skipped += 1;
+            if (fs.existsSync(timerPath)) {
+                disableRemoveUnits(id, unitDir, systemctl, dryRun, options);
+                removed += 1;
+            }
+            continue;
+        }
+        const enabled = jobEnabled(job);
+        if (enabled === "false" || enabled === "False" || enabled === "0") {
+            log(`remove units for disabled job ${id}`);
+            if (fs.existsSync(timerPath) || fs.existsSync(servicePath)) {
+                disableRemoveUnits(id, unitDir, systemctl, dryRun, options);
+                removed += 1;
+            }
+            continue;
+        }
+        const readiness = await jobReadiness(id, cacheDir, home, options);
+        if (readiness !== "ready") {
+            log(`skip arming ${id} — readiness=${readiness} (need ready)`);
+            skipped += 1;
+            if (fs.existsSync(timerPath)) {
+                disableRemoveUnits(id, unitDir, systemctl, dryRun, options);
+                removed += 1;
+                log(`stopped timer for non-ready job ${id}`);
+            }
+            continue;
+        }
+        const cron = schedule.trim().split(/\s+/);
+        if (cron.length !== 5) {
+            log(`skip ${id} — schedule not 5-field cron: ${schedule}`);
+            errors += 1;
+            continue;
+        }
+        let onCalendar = cronToOnCalendar(cron);
+        if (timezone && !` ${onCalendar} `.includes(` ${timezone} `))
+            onCalendar = `${onCalendar} ${timezone}`;
+        desired.add(id);
+        const service = serviceUnit(root, runner, id);
+        const timer = timerUnit(id, onCalendar, randomize, root);
+        const unchanged = fs.existsSync(servicePath) && fs.existsSync(timerPath)
+            && fs.readFileSync(servicePath, "utf8") === service
+            && fs.readFileSync(timerPath, "utf8") === timer;
+        if (unchanged) {
+            log(`noop ${id} — units unchanged (${name})`);
+            const reload = systemctlResult(["daemon-reload"], dryRun, systemctl, options);
+            if (reload.stdout)
+                process.stdout.write(reload.stdout);
+            if (reload.stderr)
+                process.stderr.write(reload.stderr);
+            const enabledResult = systemctlResult(["enable", "--now", `hq-job-${id}.timer`], dryRun, systemctl, options);
+            const output = `${enabledResult.stdout}${enabledResult.stderr}`.replace(/\n+$/, "");
+            if (enabledResult.status !== 0) {
+                log(`systemctl enable timer failed for job ${id} exit=${enabledResult.status}: ${output || "no error message"}`);
+                skipped += 1;
+                errors += 1;
+            }
+            else {
+                if (output)
+                    process.stderr.write(`${output}\n`);
+                armed += 1;
+            }
+            continue;
+        }
+        fs.writeFileSync(servicePath, service);
+        fs.writeFileSync(timerPath, timer);
+        const reload = systemctlResult(["daemon-reload"], dryRun, systemctl, options);
+        if (reload.stdout)
+            process.stdout.write(reload.stdout);
+        if (reload.stderr)
+            process.stderr.write(reload.stderr);
+        const enabledResult = systemctlResult(["enable", "--now", `hq-job-${id}.timer`], dryRun, systemctl, options);
+        const output = `${enabledResult.stdout}${enabledResult.stderr}`.replace(/\n+$/, "");
+        if (enabledResult.status === 0) {
+            if (output)
+                process.stderr.write(`${output}\n`);
+            if (!dryRun)
+                log(`armed ${id} OnCalendar=${onCalendar} readiness=ready`);
+            armed += 1;
+        }
+        else {
+            log(`systemctl enable timer failed for job ${id} exit=${enabledResult.status}: ${output || "no error message"}`);
+            skipped += 1;
+            errors += 1;
+        }
+    }
+    let unitNames = [];
+    try {
+        unitNames = fs.readdirSync(unitDir);
+    }
+    catch { /* The shell's unmatched glob is ignored. */ }
+    for (const unitName of unitNames) {
+        const match = /^hq-job-(.+)\.timer$/.exec(unitName);
+        if (!match)
+            continue;
+        const id = match[1];
+        if (desired.has(id))
+            continue;
+        log(`remove orphaned units for deleted/unarmed job ${id}`);
+        disableRemoveUnits(id, unitDir, systemctl, dryRun, options);
+        removed += 1;
+    }
+    const timestamp = (options.now?.() ?? new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+    fs.writeFileSync(path.join(stateDir, "last-reconcile.json"), serializeJqJson({
+        armed, skipped, removed, probed, errors, dry_run: dryRun, at: timestamp,
+    }, "compact"));
+    log(`done armed=${armed} skipped=${skipped} removed=${removed} probed=${probed} errors=${errors}`);
+    return errors === 0 ? 0 : 1;
+}
 export function registerCoreJobsNativeCommand(core) {
     const jobs = core.command("jobs").description("Scheduled jobs helpers");
     const register = (name, asset, summary, run) => {
@@ -590,13 +1291,18 @@ export function registerCoreJobsNativeCommand(core) {
             .argument("[args...]", "Arguments passed to the scaffold helper")
             .action(async (args, _options, current) => {
             const argv = rawArgumentsForCommand(current, args);
+            const groupHqRoot = core.opts().hqRoot;
             if (!await coreNativeJobsEnabled()) {
-                const result = runBundledScript({ asset, args: argv, cwd: process.cwd() });
+                const hqRoot = asset === RECONCILE_ASSET && !argv.includes("--hq-root")
+                    && !argv.includes("--help") && !argv.includes("-h")
+                    ? resolveLiveRoot({ hqRoot: groupHqRoot })
+                    : undefined;
+                const result = runBundledScript({ asset, args: argv, cwd: process.cwd(), ...(hqRoot ? { hqRoot } : {}) });
                 if (result.code !== 0)
                     process.exit(result.code);
                 return;
             }
-            const result = run(argv);
+            const result = await run(argv, groupHqRoot ?? process.env.HQ_ROOT);
             if (result !== 0)
                 process.exit(result);
         });
@@ -604,6 +1310,7 @@ export function registerCoreJobsNativeCommand(core) {
     };
     register("schedule-parse", SCHEDULE_PARSE_ASSET, "Resolve natural-language or raw cron schedules", runScheduleParse);
     register("validate", VALIDATE_ASSET, "Validate scheduled-job YAML files", validateJobs);
+    register("reconcile", RECONCILE_ASSET, "Materialize scheduled jobs on this outpost", runReconcile);
 }
 export function rawArgumentsForCommand(command, fallback, raw = process.argv) {
     const names = [];