@indigoai-us/hq-cli 5.306.0 → 5.307.0

package/dist/commands/core-audit-log-native.js

@@ -0,0 +1,257 @@
+/** In-process implementation of core/scripts/audit-log.sh. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { serializeJqJson } from "../lib/core-utils/jq-json-serializer.js";
+import { resolveLiveRoot } from "../utils/hq-roots.js";
+import { bundledShellUnboundValue, registerNativeUtility, utilityError } from "./core-native-utilities.js";
+export const AUDIT_LOG_ASSET = "core/scripts/audit-log.sh";
+export const AUDIT_LOG_HELP = `audit-log.sh — HQ audit log utility
+
+SUBCOMMANDS:
+  append    Write one JSONL record to the audit log
+  query     Filter and display records
+  summary   Show aggregated table (project | worker | status)
+
+APPEND FLAGS (--event and --project are required):
+  --timestamp    ISO8601 (auto-filled if omitted)
+  --event        task_started | phase_completed | task_completed | task_failed |
+                 project_started | project_completed |
+                 story_dispatched | story_completed | story_failed |
+                 pipeline_started | pipeline_completed | pipeline_paused |
+                 pipeline_failed | project_pr_created | project_reviewed |
+                 project_merged | project_deployed | project_canary_pass |
+                 project_canary_fail | gate_requested | gate_resolved
+  --company      Company slug (e.g. {company})
+  --project      Project slug (e.g. hq-observability)
+  --story-id     Story ID (e.g. US-001)
+  --worker       Worker name (e.g. backend-dev)
+  --model        Model name (e.g. sonnet)
+  --action       Short description of what happened
+  --files        Comma-separated file paths touched
+  --result       success | fail | skipped
+  --duration-ms  Wall-clock time in milliseconds (integer)
+  --error        Error message if result=fail
+  --session-id   Claude session/thread ID
+
+QUERY FLAGS:
+  --project      Filter by project slug
+  --company      Filter by company slug
+  --worker       Filter by worker name
+  --since        Filter by timestamp >= YYYY-MM-DD (or full ISO8601)
+  --event        Filter by event type
+
+EXAMPLES:
+  # Append a task_started event
+  core/scripts/audit-log.sh append \\
+    --event task_started \\
+    --project hq-observability \\
+    --company {company} \\
+    --story-id US-001 \\
+    --worker backend-dev \\
+    --model sonnet
+
+  # Query all failures for a project
+  core/scripts/audit-log.sh query --project hq-observability --event task_failed
+
+  # Query since a date
+  core/scripts/audit-log.sh query --since 2026-03-01
+
+  # Show summary table
+  core/scripts/audit-log.sh summary
+
+LOG FILE:
+  workspace/metrics/audit-log.jsonl
+`;
+const EVENTS = "task_started phase_completed task_completed task_failed project_started project_completed story_dispatched story_completed story_failed pipeline_started pipeline_completed pipeline_paused pipeline_failed project_pr_created project_reviewed project_merged project_deployed project_canary_pass project_canary_fail gate_requested gate_resolved";
+const RESULTS = "success fail skipped";
+const APPEND_FLAGS = {
+    "--timestamp": "timestamp", "--event": "event", "--company": "company", "--project": "project",
+    "--story-id": "story_id", "--worker": "worker", "--model": "model", "--action": "action",
+    "--files": "files_touched", "--result": "result", "--duration-ms": "duration_ms", "--error": "error", "--session-id": "session_id",
+};
+const QUERY_FLAGS = {
+    "--project": "project", "--company": "company", "--worker": "worker", "--since": "timestamp", "--event": "event",
+};
+const APPEND_SHELL_LINES = {
+    "--timestamp": 76, "--event": 77, "--company": 78, "--project": 79, "--story-id": 80,
+    "--worker": 81, "--model": 82, "--action": 83, "--files": 84, "--result": 85,
+    "--duration-ms": 86, "--error": 87, "--session-id": 88,
+};
+const QUERY_SHELL_LINES = {
+    "--project": 171, "--company": 172, "--worker": 173, "--since": 174, "--event": 175,
+};
+const OMIT_EMPTY_FIELDS = ["company", "story_id", "worker", "model", "action", "result", "duration_ms", "error", "session_id"];
+function parseFlags(args, allowed) {
+    const values = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const key = args[i];
+        if (!Object.hasOwn(allowed, key))
+            return { error: `ERROR: Unknown flag: ${key}` };
+        if (i + 1 >= args.length)
+            return { missingValue: key };
+        values[allowed[key]] = args[i + 1];
+        i += 1;
+    }
+    return { values };
+}
+function logPath(root) {
+    return path.join(root, "workspace/metrics/audit-log.jsonl");
+}
+function append(args, deps) {
+    const parsed = parseFlags(args, APPEND_FLAGS);
+    if (!parsed.values)
+        return parsed.missingValue
+            ? bundledShellUnboundValue(AUDIT_LOG_ASSET, APPEND_SHELL_LINES[parsed.missingValue])
+            : utilityError(parsed.error ?? "ERROR: invalid arguments");
+    const values = parsed.values;
+    const event = values.event ?? "";
+    const project = values.project ?? "";
+    if (!event)
+        return utilityError("ERROR: Missing required field: --event");
+    if (!project)
+        return utilityError("ERROR: Missing required field: --project");
+    if (!` ${EVENTS} `.includes(` ${event} `))
+        return utilityError(`ERROR: Invalid event '${event}'. Must be one of: ${EVENTS}`);
+    if (values.result && !` ${RESULTS} `.includes(` ${values.result} `))
+        return utilityError(`ERROR: Invalid result '${values.result}'. Must be one of: ${RESULTS}`);
+    if (values.duration_ms && !/^\d+$/.test(values.duration_ms))
+        return utilityError("ERROR: --duration-ms must be a non-negative integer");
+    const timestamp = values.timestamp || deps.now().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const files = values.files_touched ? values.files_touched.split(",") : [];
+    const entry = {
+        timestamp,
+        event,
+        company: values.company || null,
+        project,
+        story_id: values.story_id || null,
+        worker: values.worker || null,
+        model: values.model || null,
+        action: values.action || null,
+        files_touched: files,
+        result: values.result || null,
+        duration_ms: values.duration_ms ? Number(values.duration_ms) : null,
+        error: values.error || null,
+        session_id: values.session_id || null,
+    };
+    for (const key of OMIT_EMPTY_FIELDS) {
+        if (entry[key] === null)
+            delete entry[key];
+    }
+    if (files.length === 0)
+        delete entry.files_touched;
+    const target = logPath(deps.root);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.appendFileSync(target, serializeJqJson(entry, "compact"), { encoding: "utf8", mode: 0o666 });
+    return { code: 0, stdout: `Appended to ${target}\n`, stderr: "" };
+}
+function readEntries(file) {
+    return fs.readFileSync(file, "utf8").split(/\r?\n/).filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line));
+}
+function query(args, deps) {
+    const parsed = parseFlags(args, QUERY_FLAGS);
+    if (!parsed.values)
+        return parsed.missingValue
+            ? bundledShellUnboundValue(AUDIT_LOG_ASSET, QUERY_SHELL_LINES[parsed.missingValue])
+            : utilityError(parsed.error ?? "ERROR: invalid arguments");
+    const file = logPath(deps.root);
+    if (!fs.existsSync(file))
+        return { code: 0, stdout: "", stderr: `No audit log found at ${file}\n` };
+    let entries;
+    try {
+        entries = readEntries(file);
+    }
+    catch {
+        return { code: 4, stdout: "", stderr: "" };
+    }
+    const filters = Object.fromEntries(Object.entries(parsed.values).filter(([, value]) => value !== ""));
+    const rows = entries.filter((entry) => Object.entries(filters).every(([key, value]) => {
+        if (key === "timestamp")
+            return String(entry.timestamp ?? "") >= value;
+        return entry[key] === value;
+    }));
+    return { code: 0, stdout: serializeJqJson(rows, "pretty"), stderr: `--- ${rows.length} record(s) matched ---\n` };
+}
+function pad(value, width) {
+    return String(value ?? "").padEnd(width, " ");
+}
+function right(value, width) {
+    return String(value ?? "").padStart(width, " ");
+}
+function printProject(project, stories, phases, failures, skipped, last) {
+    return `${pad(project, 40)}  ${right(stories, 8)}  ${right(phases, 8)}  ${right(failures, 8)}  ${right(skipped, 8)}  ${pad(last, 26)}\n`;
+}
+function printWorker(worker, tasks, failures, rate) {
+    return `${pad(worker, 30)}  ${right(tasks, 8)}  ${right(failures, 8)}  ${pad(rate, 10)}\n`;
+}
+function isTask(entry) { return entry.event === "task_completed" || entry.event === "task_failed"; }
+function isFailure(entry) { return entry.result === "fail" || entry.event === "task_failed"; }
+function summary(_args, deps) {
+    const file = logPath(deps.root);
+    if (!fs.existsSync(file))
+        return { code: 0, stdout: "", stderr: `No audit log found at ${file}\n` };
+    let contents;
+    let entries;
+    try {
+        contents = fs.readFileSync(file, "utf8");
+        entries = readEntries(file);
+    }
+    catch {
+        return { code: 4, stdout: "", stderr: "" };
+    }
+    const lineCount = (contents.match(/\n/g) ?? []).length;
+    if (lineCount === 0)
+        return { code: 0, stdout: "Audit log is empty — no records to summarize.\n", stderr: "" };
+    const projects = new Map();
+    const workers = new Map();
+    for (const entry of entries) {
+        const project = String(entry.project ?? "null");
+        projects.set(project, [...(projects.get(project) ?? []), entry]);
+        if (entry.worker !== undefined && entry.worker !== null) {
+            const worker = String(entry.worker);
+            workers.set(worker, [...(workers.get(worker) ?? []), entry]);
+        }
+    }
+    let out = "\n=== Audit Log Summary ===\n\n--- By Project ---\n";
+    out += printProject("PROJECT", "STORIES", "PHASES", "FAILURES", "SKIPPED", "LAST_ACTIVITY");
+    out += printProject("-".repeat(40), "--------", "--------", "--------", "--------", "-".repeat(26));
+    for (const project of [...projects.keys()].sort()) {
+        const rows = projects.get(project);
+        const sorted = [...rows].sort((a, b) => String(a.timestamp ?? "").localeCompare(String(b.timestamp ?? "")));
+        out += printProject(project === "null" ? "unknown" : project, rows.filter(isTask).length, rows.filter((row) => row.event === "phase_completed").length, rows.filter(isFailure).length, rows.filter((row) => row.result === "skipped").length, String(sorted.at(-1)?.timestamp ?? "-"));
+    }
+    out += "\n--- By Worker ---\n";
+    out += printWorker("WORKER", "TASKS", "FAILURES", "SUCCESS_RATE");
+    out += printWorker("-".repeat(30), "--------", "--------", "----------");
+    for (const worker of [...workers.keys()].sort()) {
+        const rows = workers.get(worker);
+        const tasks = rows.filter(isTask).length;
+        const failures = rows.filter(isFailure).length;
+        const rate = tasks > 0 ? `${Math.floor(((tasks - failures) / tasks * 100) + 0.5)}%` : "n/a";
+        out += printWorker(worker, tasks, failures, rate);
+    }
+    const totalTasks = entries.filter(isTask).length;
+    const totalFailures = entries.filter(isFailure).length;
+    out += `\n--- Totals ---\n  Total events:   ${lineCount}\n  Total tasks:    ${totalTasks}\n  Total failures: ${totalFailures}\n\n`;
+    return { code: 0, stdout: out, stderr: "" };
+}
+export function runAuditLog(args, deps) {
+    const [subcommand = "help", ...rest] = args;
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h")
+        return { code: 0, stdout: AUDIT_LOG_HELP, stderr: "" };
+    if (subcommand === "append")
+        return append(rest, deps);
+    if (subcommand === "query")
+        return query(rest, deps);
+    if (subcommand === "summary")
+        return summary(rest, deps);
+    return utilityError(`ERROR: Unknown subcommand '${subcommand}'. Use: append | query | summary | help`);
+}
+export function registerCoreAuditLogNative(core) {
+    registerNativeUtility(core, {
+        name: "audit-log", asset: AUDIT_LOG_ASSET, root: "live", summary: "Append, query, or summarize the HQ audit log",
+        resolveRoot: (_cwd, hqRoot) => resolveLiveRoot({ hqRoot }),
+        run: (args, context) => runAuditLog(args, context),
+    });
+}
+//# sourceMappingURL=core-audit-log-native.js.map

package/dist/commands/core-git-pack-extension-check-native.d.ts

@@ -0,0 +1,22 @@
+import * as fs from "node:fs";
+import type { Command } from "commander";
+import { type UtilityOutput } from "./core-native-utilities.js";
+export declare const GIT_PACK_EXTENSION_CHECK_ASSET = "core/scripts/git-pack-extension-check.sh";
+export declare const GIT_PACK_EXTENSION_CHECK_HELP: string;
+export type GitResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type GitPackDependencies = {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    runGit?: (args: string[], cwd: string) => GitResult;
+    renameFile?: (source: string, destination: string) => void;
+};
+type PackHeaderReader = Pick<typeof fs, "openSync" | "readSync" | "closeSync">;
+export declare function readPackHeaderHex(file: string, reader?: PackHeaderReader): string;
+export declare function runGitPackExtensionCheck(args: string[], deps: GitPackDependencies): UtilityOutput;
+export declare function registerCoreGitPackExtensionCheckNative(core: Command): void;
+export {};
+//# sourceMappingURL=core-git-pack-extension-check-native.d.ts.map

package/dist/commands/core-git-pack-extension-check-native.js

@@ -0,0 +1,190 @@
+/** In-process pack scan/repair for core/scripts/git-pack-extension-check.sh. */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { registerNativeUtility, utilityError } from "./core-native-utilities.js";
+export const GIT_PACK_EXTENSION_CHECK_ASSET = "core/scripts/git-pack-extension-check.sh";
+export const GIT_PACK_EXTENSION_CHECK_HELP = `# hq-core: public
+# git-pack-extension-check.sh — find pack files that have lost their extension.
+#
+# A git packfile set is three files sharing one basename:
+#
+#   pack-<sha>.pack   the objects           (magic "PACK")
+#   pack-<sha>.idx    the index into them   (magic "\\377tOc")
+#   pack-<sha>.rev    reverse index         (magic "RIDX")
+#
+# Git pairs them BY EXTENSION. Strip the extension off any one of them and git
+# stops seeing the set entirely: the objects are still on disk, byte for byte,
+# but they become unreachable. The repo then fails in a way that reads like
+# catastrophic history loss rather than a filename problem:
+#
+#   fatal: unable to read tree (<sha>)
+#   error: bad tree object HEAD
+#   error: refs/heads/<branch>: invalid sha1 pointer <sha>
+#
+# \`git fsck\` reports the objects as missing and \`git gc\` cannot help, because
+# nothing is actually corrupt — the bytes are intact and the repair is a
+# rename. That mismatch between how it presents and what it is makes this
+# failure expensive to diagnose from the error text alone, which is why this
+# check exists as a deterministic probe.
+#
+# Git never writes an extensionless \`pack-*\` file, so finding one is
+# unambiguous. Observed in the wild on a macOS HQ root where a folder-level
+# sync/backup agent had been walking the tree; the mechanism that drops the
+# extension is not established.
+#
+# Usage:
+#   git-pack-extension-check.sh [--root <path>] [--fix] [--quiet]
+#
+#   --root <path>   Repository to check (default: current directory).
+#   --fix           Rename each orphan back to the extension its magic bytes
+#                   prove it should carry. Without this the script only
+#                   reports.
+#   --quiet         Suppress the healthy-case line; findings still print.
+#
+# Exit codes:
+#   0  healthy, or every orphan was repaired under --fix
+#   1  usage error, or the root is not a git repository
+#   2  orphans found and left in place (report-only, or unrepairable)
+#
+# The repair is a rename and nothing else. It never deletes, never rewrites
+# file contents, never touches refs or the index, and refuses to overwrite an
+# existing target. A file whose magic bytes are not a known pack signature is
+# reported and left alone — this script will not guess.
+
+set -uo pipefail
+`.replace(/^# ?/gm, "");
+function defaultGit(args, cwd, env) {
+    const result = spawnSync("git", args, { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    if (result.error)
+        return { code: 127, stdout: "", stderr: result.error.message };
+    return { code: result.status ?? 128, stdout: String(result.stdout ?? ""), stderr: String(result.stderr ?? "") };
+}
+export function readPackHeaderHex(file, reader = fs) {
+    let fd;
+    try {
+        fd = reader.openSync(file, "r");
+        const header = Buffer.alloc(4);
+        const bytesRead = reader.readSync(fd, header, 0, header.length, 0);
+        return header.subarray(0, bytesRead).toString("hex");
+    }
+    catch {
+        return "";
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                reader.closeSync(fd);
+            }
+            catch { /* preserve the old unreadable-header result */ }
+        }
+    }
+}
+export function runGitPackExtensionCheck(args, deps) {
+    let root = ".";
+    let emptyRoot = false;
+    let fix = false;
+    let quiet = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--root") {
+            if (i + 1 >= args.length)
+                return utilityError("git-pack-extension-check: --root needs a path");
+            root = args[++i];
+            emptyRoot = root.length === 0;
+        }
+        else if (arg === "--fix")
+            fix = true;
+        else if (arg === "--quiet")
+            quiet = true;
+        else if (arg === "-h" || arg === "--help")
+            return { code: 0, stdout: GIT_PACK_EXTENSION_CHECK_HELP, stderr: "" };
+        else
+            return utilityError(`git-pack-extension-check: unknown argument '${arg}'`);
+    }
+    if (emptyRoot)
+        return utilityError("git-pack-extension-check: not a directory: ");
+    const rootPath = path.resolve(deps.cwd, root);
+    try {
+        if (!fs.statSync(rootPath).isDirectory())
+            throw new Error("not a directory");
+    }
+    catch {
+        return utilityError(`git-pack-extension-check: not a directory: ${root}`);
+    }
+    const git = deps.runGit ?? ((gitArgs, cwd) => defaultGit(gitArgs, cwd, deps.env ?? process.env));
+    const renameFile = deps.renameFile ?? ((source, destination) => fs.renameSync(source, destination));
+    const shellOutput = (value) => value.replace(/(?:\r?\n)+$/, "");
+    let common = shellOutput(git(["-C", root, "rev-parse", "--path-format=absolute", "--git-common-dir"], deps.cwd).stdout);
+    if (!common) {
+        common = shellOutput(git(["-C", root, "rev-parse", "--git-common-dir"], deps.cwd).stdout);
+        if (!common)
+            return utilityError(`git-pack-extension-check: not a git repository: ${root}`);
+        if (!path.isAbsolute(common))
+            common = path.resolve(rootPath, common);
+    }
+    const packDir = path.join(common, "objects/pack");
+    let names;
+    try {
+        names = fs.readdirSync(packDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.startsWith("pack-") && !entry.name.includes(".")).map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && error.code !== "ENOTDIR")
+            throw error;
+        return { code: 0, stdout: quiet ? "" : "git-pack-extension-check: no pack directory, nothing to check\n", stderr: "" };
+    }
+    let found = 0;
+    let repaired = 0;
+    let unrepaired = 0;
+    let stdout = "";
+    let stderr = "";
+    for (const name of names) {
+        const orphan = path.join(packDir, name);
+        const hex = readPackHeaderHex(orphan);
+        const ext = hex === "5041434b" ? "pack" : hex === "ff744f63" ? "idx" : hex === "52494458" ? "rev" : "";
+        found += 1;
+        if (!ext) {
+            stderr += `git-pack-extension-check: FOUND ${name} — extensionless, but its magic bytes (${hex || "empty"}) are not a pack/idx/rev signature; leaving it alone\n`;
+            unrepaired += 1;
+            continue;
+        }
+        const target = `${orphan}.${ext}`;
+        if (fs.existsSync(target)) {
+            stderr += `git-pack-extension-check: FOUND ${name} — should be ${name}.${ext}, but that file already exists; resolve by hand\n`;
+            unrepaired += 1;
+            continue;
+        }
+        if (!fix) {
+            stderr += `git-pack-extension-check: FOUND ${name} — lost its .${ext} extension; git cannot see this pack set. Re-run with --fix to rename it.\n`;
+            unrepaired += 1;
+            continue;
+        }
+        try {
+            // Rename works on filesystems that do not support hard links.
+            renameFile(orphan, target);
+            stdout += `git-pack-extension-check: REPAIRED ${name} -> ${name}.${ext}\n`;
+            repaired += 1;
+        }
+        catch {
+            stderr += `git-pack-extension-check: FAILED to rename ${name} -> ${name}.${ext}\n`;
+            unrepaired += 1;
+        }
+    }
+    if (found === 0)
+        return { code: 0, stdout: quiet ? "" : `git-pack-extension-check: ok — no extensionless pack files in ${packDir}\n`, stderr: "" };
+    if (unrepaired > 0)
+        return { code: 2, stdout, stderr: `${stderr}git-pack-extension-check: ${found} orphan(s), ${repaired} repaired, ${unrepaired} still broken\n` };
+    return { code: 0, stdout: `${stdout}git-pack-extension-check: ${repaired} pack file(s) repaired — re-run 'git fsck' to confirm\n`, stderr: "" };
+}
+export function registerCoreGitPackExtensionCheckNative(core) {
+    registerNativeUtility(core, {
+        name: "git-pack-extension-check", asset: GIT_PACK_EXTENSION_CHECK_ASSET, root: "cwd", summary: "Find or repair extensionless Git pack files",
+        resolveRoot: (cwd) => cwd,
+        run: (args, context) => runGitPackExtensionCheck(args, {
+            cwd: context.cwd,
+            env: context.env,
+            runGit: (gitArgs, cwd) => defaultGit(gitArgs, cwd, context.env),
+        }),
+    });
+}
+//# sourceMappingURL=core-git-pack-extension-check-native.js.map

package/dist/commands/core-native-utilities-flag.d.ts

@@ -0,0 +1,4 @@
+/** Default-off rollout gate for native operator utility commands. */
+export declare const CORE_NATIVE_UTILITIES_FLAG = "core-native-utilities";
+export declare function coreNativeUtilitiesEnabled(): Promise<boolean>;
+//# sourceMappingURL=core-native-utilities-flag.d.ts.map

package/dist/commands/core-native-utilities-flag.js

@@ -0,0 +1,7 @@
+/** Default-off rollout gate for native operator utility commands. */
+export const CORE_NATIVE_UTILITIES_FLAG = "core-native-utilities";
+export async function coreNativeUtilitiesEnabled() {
+    const { resolveProcessFlagGate } = await import("../lib/flag-registry.js");
+    return resolveProcessFlagGate(CORE_NATIVE_UTILITIES_FLAG, { fallback: false }, () => false);
+}
+//# sourceMappingURL=core-native-utilities-flag.js.map

package/dist/commands/core-native-utilities.d.ts

@@ -0,0 +1,28 @@
+/** Shared dispatch for the default-off Wave 5 operator utilities. */
+import type { Command } from "commander";
+import { type CoreCommandRoot } from "./core-command-catalog.js";
+export type UtilityOutput = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type UtilityContext = {
+    root: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    now: () => Date;
+};
+export type NativeUtilityDefinition = {
+    name: string;
+    asset: string;
+    root: CoreCommandRoot;
+    summary: string;
+    resolveRoot: (cwd: string, hqRoot?: string) => string;
+    run: (args: string[], context: UtilityContext) => UtilityOutput;
+};
+/** Register one raw-argv command and retain the original shell as rollback. */
+export declare function registerNativeUtility(core: Command, definition: NativeUtilityDefinition): void;
+export declare function utilityError(message: string, code?: number): UtilityOutput;
+/** Preserve Bash's set -u diagnostic for a missing positional option value. */
+export declare function bundledShellUnboundValue(asset: string, line: number): UtilityOutput;
+//# sourceMappingURL=core-native-utilities.d.ts.map

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

@@ -0,0 +1,52 @@
+import * as path from "node:path";
+import { coreNativeUtilitiesEnabled } from "./core-native-utilities-flag.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
+import { runBundledScript } from "../utils/run-bundled-script.js";
+import { packageRoot } from "../utils/hq-roots.js";
+/** Register one raw-argv command and retain the original shell as rollback. */
+export function registerNativeUtility(core, definition) {
+    const command = core.command(definition.name)
+        .description(definition.summary)
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .helpOption(false)
+        .argument("[args...]")
+        .action(async (args = [], _options, cmd) => {
+        const cwd = process.cwd();
+        const groupRoot = core.opts().hqRoot;
+        const operands = cmd.args.length > 0 ? cmd.args : args;
+        const root = definition.resolveRoot(cwd, groupRoot);
+        const nativeEnabled = await coreNativeUtilitiesEnabled();
+        if (process.env.HQ_CM_W5_EXPECT_NATIVE === "1" && !nativeEnabled) {
+            throw new Error(`core-native-utilities dispatch gate is disabled for ${definition.name}`);
+        }
+        if (!nativeEnabled) {
+            const result = runBundledScript({
+                asset: definition.asset,
+                args: operands,
+                cwd: definition.root === "live" ? root : cwd,
+                hqRoot: root,
+            });
+            if (result.code !== 0)
+                process.exitCode = result.code;
+            return;
+        }
+        const result = definition.run(operands, { root, cwd, env: process.env, now: () => new Date() });
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        if (result.code !== 0)
+            process.exitCode = result.code;
+    });
+    describeCoreCommand(command, { execution: "native", asset: definition.asset, root: definition.root });
+}
+export function utilityError(message, code = 1) {
+    return { code, stdout: "", stderr: `${message}\n` };
+}
+/** Preserve Bash's set -u diagnostic for a missing positional option value. */
+export function bundledShellUnboundValue(asset, line) {
+    const script = path.join(packageRoot(), "assets/scaffold", asset);
+    return { code: 1, stdout: "", stderr: `${script}: line ${line}: $2: unbound variable\n` };
+}
+//# sourceMappingURL=core-native-utilities.js.map

package/dist/commands/core-pin-native.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+import { type UtilityOutput } from "./core-native-utilities.js";
+export declare const PIN_ASSET = "core/scripts/hq-pin.sh";
+export declare const PIN_HELP = "# hq-pin.sh \u2014 anchor the current session to one goal (the \"pin\").\n#\n# A pin is the message, goal, or target the session keeps working toward\n# across loops, wakeups, compactions, and hand-offs. It is stored per session\n# and re-read at every checkpoint so the session cannot drift.\n#\n# Usage:\n#   core/scripts/hq-pin.sh set  \"<goal>\" [--done \"<criterion>\"]... [--owner <name>] [--channel <dm-channel>]\n#   core/scripts/hq-pin.sh show                # print the pin (goal, done criteria, owner, channel, set-at)\n#   core/scripts/hq-pin.sh check               # print a one-line reminder for loop ticks; exit 3 if no pin\n#   core/scripts/hq-pin.sh note \"<progress>\"   # append a dated progress line under the pin\n#   core/scripts/hq-pin.sh clear               # remove the pin (the goal is met or withdrawn)\n#\n# Storage: workspace/sessions/<sid>/pin.md plus `pin: <goal>` in the session's\n";
+export type PinDependencies = {
+    root: string;
+    env: NodeJS.ProcessEnv;
+    now: () => Date;
+    tmpDir?: string;
+};
+export declare function resolvePinSessionId(root: string, env: NodeJS.ProcessEnv): string;
+export declare function runPin(args: string[], deps: PinDependencies): UtilityOutput;
+export declare function registerCorePinNative(core: Command): void;
+//# sourceMappingURL=core-pin-native.d.ts.map