@indigoai-us/hq-cli 5.89.1 → 5.90.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [5.90.0]
+
+### Changed
+
+- Six bundled `hq core` utility scripts (detect-stale-core-policy-mirror,
+  hq-status-summary, ontology-readme-drift, resize-screenshot,
+  token-usage-report, worktree) now run as native, tested TypeScript instead of
+  bundled shell assets, proven equivalent by a shell-vs-native differential
+  suite. Command surfaces are unchanged, the scaffold files still ship, and
+  the commands no longer depend on bundled scaffold assets being present.
+  (#321)
+
+## [5.89.2]
+
+### Fixed
+
+- The `hq core checkpoint` maintenance sibling no longer loses queued payloads.
+  Both drain paths read `pending.jsonl` and then truncated it, so a checkpoint
+  queued between the read and the truncate was discarded unread and never
+  enriched. The queue is now claimed atomically by renaming it into the run
+  directory, leaving producers a fresh queue and keeping the claimed file as an
+  audit and crash-recovery trail; the sibling prompt claims by `mv` in a loop
+  rather than truncating in place. (#317)
+
 ## [5.89.1]
 
 ### Fixed

package/dist/commands/core-checkpoint.d.ts

@@ -11,7 +11,7 @@ import { Command } from "commander";
  * Kept in TypeScript rather than in a bundled asset: it is an instruction to
  * a locally-installed agent, not a scaffold script that should be packaged.
  */
-export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint sibling \u2014 a background maintenance agent for this\nHQ install. Your parent session's state is in <payloadPath>. Work\nquietly and do not ask questions; if something is ambiguous, record it in the\nreport instead of guessing.\n\n1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)\n   both for session context and to extract additional reusable learnings/insights\n   the parent did not pass explicitly. Never quote secrets\n   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists\n   under this HQ root, read it and follow it wherever it goes beyond these instructions;\n   the write bounds below always win over the skill text.\n2. Upgrade the thread file named in the payload IN PLACE: verify/repair its\n   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and\n   git.knowledge_repos by scanning core/knowledge/public/*,\n   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge\n   for symlinks or directories containing .git, recording dirty repositories\n   as {\"<name>\": {\"commit\": \"<short>\", \"dirty\": true}}. Fill worker,\n   next_steps, and insights; set type to \"checkpoint\"; then rename the file to\n   drop -auto- from its filename. Use the renamed path in every reference you\n   write afterwards.\n3. For every explicit or transcript-derived learning that is a reusable rule,\n   distill a non-duplicate policy file under personal/policies/ or, only when\n   the payload names a company and the rule is company-specific,\n   companies/<company>/policies/, following\n   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or\n   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md\n   when present, otherwise workspace/insights/. Durable facts (not rules) may\n   go under personal/knowledge/ or companies/<company>/knowledge/ only.\n4. Close an active session journal fail-soft with\n   bash .claude/skills/_shared/journal.sh close \"<project_dir>\" \"<one-line synthesis>\".\n   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with\n   id, created_at, summary, files, and next_steps for backward compatibility.\n5. Update workspace/threads/recent.md and regenerate\n   workspace/threads/INDEX.md. For each company whose knowledge path appears\n   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under\n   core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation\n   is allowed for those companies, but knowledge/policy content writes remain\n   restricted to the payload's named company.\n6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;\n   skip silently on any failure. Hook or automation improvements go ONLY under\n   personal/hooks/ as proposals.\n7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.\n8. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), and what you skipped and why. If\n   workspace/checkpoints/sibling/pending.jsonl is non-empty when you finish,\n   process those payloads with this same flow, then truncate the file.\n";
+export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint sibling \u2014 a background maintenance agent for this\nHQ install. Your parent session's state is in <payloadPath>. Work\nquietly and do not ask questions; if something is ambiguous, record it in the\nreport instead of guessing.\n\n1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)\n   both for session context and to extract additional reusable learnings/insights\n   the parent did not pass explicitly. Never quote secrets\n   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists\n   under this HQ root, read it and follow it wherever it goes beyond these instructions;\n   the write bounds below always win over the skill text.\n2. Upgrade the thread file named in the payload IN PLACE: verify/repair its\n   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and\n   git.knowledge_repos by scanning core/knowledge/public/*,\n   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge\n   for symlinks or directories containing .git, recording dirty repositories\n   as {\"<name>\": {\"commit\": \"<short>\", \"dirty\": true}}. Fill worker,\n   next_steps, and insights; set type to \"checkpoint\"; then rename the file to\n   drop -auto- from its filename. Use the renamed path in every reference you\n   write afterwards.\n3. For every explicit or transcript-derived learning that is a reusable rule,\n   distill a non-duplicate policy file under personal/policies/ or, only when\n   the payload names a company and the rule is company-specific,\n   companies/<company>/policies/, following\n   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or\n   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md\n   when present, otherwise workspace/insights/. Durable facts (not rules) may\n   go under personal/knowledge/ or companies/<company>/knowledge/ only.\n4. Close an active session journal fail-soft with\n   bash .claude/skills/_shared/journal.sh close \"<project_dir>\" \"<one-line synthesis>\".\n   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with\n   id, created_at, summary, files, and next_steps for backward compatibility.\n5. Update workspace/threads/recent.md and regenerate\n   workspace/threads/INDEX.md. For each company whose knowledge path appears\n   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under\n   core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation\n   is allowed for those companies, but knowledge/policy content writes remain\n   restricted to the payload's named company.\n6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;\n   skip silently on any failure. Hook or automation improvements go ONLY under\n   personal/hooks/ as proposals.\n7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.\n8. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), and what you skipped and why. Then drain the queue: while\n   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim\n   it atomically by renaming it aside \u2014\n   mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl\n   (N counting up from 2) \u2014 and process the claimed payloads with this same\n   flow. Repeat until a claim finds nothing left, then update the report.\n   NEVER read the queue and truncate it in place: a payload appended between\n   your read and the truncate is lost, and its checkpoint is never enriched.\n";
 export declare function renderSiblingPrompt(runDir: string, payloadPath: string): string;
 /** Attach the native checkpoint command to the hidden `hq core` group. */
 export declare function registerCoreCheckpointCommand(core: Command): void;

package/dist/commands/core-checkpoint.js

@@ -78,9 +78,14 @@ report instead of guessing.
    personal/hooks/ as proposals.
 7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.
 8. Write <runDir>/report.md — full prose: what you read, what you changed
-   (paths), and what you skipped and why. If
-   workspace/checkpoints/sibling/pending.jsonl is non-empty when you finish,
-   process those payloads with this same flow, then truncate the file.
+   (paths), and what you skipped and why. Then drain the queue: while
+   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim
+   it atomically by renaming it aside —
+   mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl
+   (N counting up from 2) — and process the claimed payloads with this same
+   flow. Repeat until a claim finds nothing left, then update the report.
+   NEVER read the queue and truncate it in place: a payload appended between
+   your read and the truncate is lost, and its checkpoint is never enriched.
 `;
 export function renderSiblingPrompt(runDir, payloadPath) {
     return SIBLING_PROMPT_TEMPLATE
@@ -457,26 +462,43 @@ function appendPending(pendingPath, payload) {
         .filter((line) => line.trim());
     if (lines.length <= MAX_PENDING_PAYLOADS)
         return lines.length;
+    // Best-effort trim: this rewrite can race a concurrent append, but it only
+    // runs once the queue is already over cap, where newest-wins is the point.
     const kept = lines.slice(-MAX_PENDING_PAYLOADS);
     fs.writeFileSync(pendingPath, `${kept.join("\n")}\n`);
     return kept.length;
 }
-function drainPending(pendingPath) {
-    if (!fs.existsSync(pendingPath))
-        return [];
+/**
+ * Take ownership of the queued payloads by renaming the queue aside.
+ *
+ * The queue must never be claimed by read-then-truncate: a payload appended
+ * between the read and the truncate is discarded unread, and the checkpoint it
+ * describes is never enriched. Renaming is atomic, so this run receives exactly
+ * the file that existed at the moment of the claim while concurrent callers go
+ * on appending to a fresh queue. The claimed file is left in the run directory
+ * as an audit trail and as a recovery point if this sibling dies.
+ */
+function claimPending(pendingPath, claimPath) {
+    try {
+        fs.renameSync(pendingPath, claimPath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return [];
+        throw error;
+    }
     const entries = [];
-    for (const line of fs.readFileSync(pendingPath, "utf8").split("\n")) {
+    for (const line of fs.readFileSync(claimPath, "utf8").split("\n")) {
         if (!line.trim())
             continue;
         try {
             entries.push(JSON.parse(line));
         }
         catch {
-            // A partial line must not prevent a future sibling from processing the
-            // valid queued payloads around it.
+            // A partial line must not prevent this run from processing the valid
+            // queued payloads around it.
         }
     }
-    fs.writeFileSync(pendingPath, "");
     return entries;
 }
 function startSibling(liveRoot, input, threadPath, backend) {
@@ -494,7 +516,7 @@ function startSibling(liveRoot, input, threadPath, backend) {
     }
     const runDir = path.join(siblingRoot, `${formatTimestamp(new Date())}-${summarySlug(input.summary ?? "checkpoint")}`);
     fs.mkdirSync(runDir, { recursive: true });
-    payload.pending_payloads = drainPending(pendingPath);
+    payload.pending_payloads = claimPending(pendingPath, path.join(runDir, "pending-claimed.jsonl"));
     const payloadPath = path.join(runDir, "payload.json");
     fs.writeFileSync(payloadPath, `${JSON.stringify(payload, null, 2)}\n`);
     const prompt = renderSiblingPrompt(runDir, payloadPath);

package/dist/commands/core.d.ts

@@ -85,6 +85,21 @@ export type WorkerSubcommand = ScaffoldAsset & {
 export type NativeScaffoldCommand = ScaffoldAsset & {
     name: string;
 };
+type NativeUtilityCommand = {
+    name: string;
+    root: ScaffoldRoot;
+    summary: string;
+    run: (args: string[], context: {
+        cwd: string;
+        hqRoot?: string;
+    }) => number;
+};
+/**
+ * These commands are now native implementations. Their retained shell assets
+ * are deliberately claimed in SCAFFOLD_ONLY_ASSETS: loose HQ trees still ship
+ * them for legacy callers, but `hq core` never dispatches through them again.
+ */
+export declare const NATIVE_UTILITY_COMMANDS: NativeUtilityCommand[];
 export declare const NATIVE_SCAFFOLD_COMMANDS: NativeScaffoldCommand[];
 /**
  * The `hq core worker <name>` subgroup — worker-scoped skill maintenance.

package/dist/commands/core.js

@@ -35,6 +35,25 @@ import { runBundledScript } from "../utils/run-bundled-script.js";
 import { renderIndexTarget } from "../lib/index-render/index.js";
 import { generateWorkersRegistry } from "../lib/workers-registry/index.js";
 import { scanPackages } from "../lib/scan-packages/index.js";
+import { detectStaleCorePolicyMirror } from "../lib/core-utils/detect-stale-core-policy-mirror.js";
+import { summarizeHqStatus } from "../lib/core-utils/hq-status-summary.js";
+import { ontologyReadmeDrift } from "../lib/core-utils/ontology-readme-drift.js";
+import { resizeScreenshot } from "../lib/core-utils/resize-screenshot.js";
+import { tokenUsageReport } from "../lib/core-utils/token-usage-report.js";
+import { createWorktree } from "../lib/core-utils/worktree.js";
+/**
+ * These commands are now native implementations. Their retained shell assets
+ * are deliberately claimed in SCAFFOLD_ONLY_ASSETS: loose HQ trees still ship
+ * them for legacy callers, but `hq core` never dispatches through them again.
+ */
+export const NATIVE_UTILITY_COMMANDS = [
+    { name: "detect-stale-core-policy-mirror", root: "live", summary: "Find (and prune) stale personal-policy mirrors in core", run: (args, context) => detectStaleCorePolicyMirror(args, { root: context.hqRoot }) },
+    { name: "hq-status-summary", root: "cwd", summary: "Summarize working-tree status across the HQ tree", run: (args, context) => summarizeHqStatus(args, { cwd: context.cwd, root: context.hqRoot }) },
+    { name: "ontology-readme-drift", root: "live", summary: "Check a company's ontology README for drift", run: (args, context) => ontologyReadmeDrift(args, { root: context.hqRoot }) },
+    { name: "resize-screenshot", root: "cwd", summary: "Downscale a screenshot for context efficiency", run: (args) => resizeScreenshot(args) },
+    { name: "token-usage-report", root: "cwd", summary: "Report session token usage", run: (args) => tokenUsageReport(args) },
+    { name: "worktree", root: "live", summary: "Create a git worktree under workspace/worktrees/", run: (args, context) => createWorktree(args, { cwd: context.cwd, hqRoot: context.hqRoot }) },
+];
 export const NATIVE_SCAFFOLD_COMMANDS = [
     {
         name: "generate-workers-registry",
@@ -158,12 +177,6 @@ export const SCAFFOLD_COMMANDS = [
         root: "cwd",
         summary: "One-shot: mirror threads into company workspaces",
     },
-    {
-        name: "detect-stale-core-policy-mirror",
-        asset: "core/scripts/detect-stale-core-policy-mirror.sh",
-        root: "live",
-        summary: "Find (and prune) stale personal-policy mirrors in core",
-    },
     {
         name: "qmd-reindex-after-sync",
         asset: "core/scripts/qmd-reindex-after-sync.sh",
@@ -177,36 +190,6 @@ export const SCAFFOLD_COMMANDS = [
         root: "live",
         summary: "Install/inspect the Codex skill bridge",
     },
-    {
-        name: "hq-status-summary",
-        asset: "core/scripts/hq-status-summary.sh",
-        root: "cwd",
-        summary: "Summarize working-tree status across the HQ tree",
-    },
-    {
-        name: "ontology-readme-drift",
-        asset: "core/scripts/ontology-readme-drift.sh",
-        root: "live",
-        summary: "Check a company's ontology README for drift",
-    },
-    {
-        name: "resize-screenshot",
-        asset: "core/scripts/resize-screenshot.sh",
-        root: "cwd",
-        summary: "Downscale a screenshot for context efficiency",
-    },
-    {
-        name: "token-usage-report",
-        asset: "core/scripts/token-usage-report.sh",
-        root: "cwd",
-        summary: "Report session token usage",
-    },
-    {
-        name: "worktree",
-        asset: "core/scripts/worktree.sh",
-        root: "live",
-        summary: "Create a git worktree under workspace/worktrees/",
-    },
 ];
 /**
  * Bundled solely for HQ-root scaffolds, which still need these as loose files.
@@ -214,6 +197,12 @@ export const SCAFFOLD_COMMANDS = [
  * direct `hq core` command.
  */
 export const SCAFFOLD_ONLY_ASSETS = [
+    { asset: "core/scripts/detect-stale-core-policy-mirror.sh", root: "live", summary: "Scaffold-only native utility companion" },
+    { asset: "core/scripts/hq-status-summary.sh", root: "cwd", summary: "Scaffold-only native utility companion" },
+    { asset: "core/scripts/ontology-readme-drift.sh", root: "live", summary: "Scaffold-only native utility companion" },
+    { asset: "core/scripts/resize-screenshot.sh", root: "cwd", summary: "Scaffold-only native utility companion" },
+    { asset: "core/scripts/token-usage-report.sh", root: "cwd", summary: "Scaffold-only native utility companion" },
+    { asset: "core/scripts/worktree.sh", root: "live", summary: "Scaffold-only native utility companion" },
     {
         asset: "core/scripts/rebuild-all-indexes.sh",
         root: "cwd",
@@ -348,6 +337,23 @@ export function registerCoreCommands(program) {
                 process.exit(result.status);
         });
     }
+    for (const entry of NATIVE_UTILITY_COMMANDS) {
+        core
+            .command(entry.name)
+            .description(entry.summary)
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .helpOption(false)
+            .argument("[args...]", "arguments accepted for shell ABI compatibility")
+            .action((args = [], _opts, cmd) => {
+            const scope = core.opts();
+            const operands = cmd.args.length > 0 ? cmd.args : args;
+            const { cwd, hqRoot } = resolveEntryRoot(entry, scope);
+            const code = entry.run(operands, { cwd, hqRoot });
+            if (code !== 0)
+                process.exit(code);
+        });
+    }
     // `hq core worker <name>` — a nested subgroup for worker-scoped skill
     // maintenance. Nested (rather than flat `hq core worker-<name>`) so the two
     // related operations read as one family.

package/dist/lib/core-utils/common.d.ts

@@ -0,0 +1,14 @@
+export type Write = (text: string) => void;
+export interface UtilityIo {
+    stdout?: Write;
+    stderr?: Write;
+}
+export declare function ioFor(io?: UtilityIo): Required<UtilityIo>;
+export declare function line(write: Write, value: string): void;
+export declare function command(command: string, args: string[], cwd?: string): {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function exists(pathname: string): boolean;
+//# sourceMappingURL=common.d.ts.map

package/dist/lib/core-utils/common.js

@@ -0,0 +1,26 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+export function ioFor(io = {}) {
+    return {
+        stdout: io.stdout ?? ((text) => process.stdout.write(text)),
+        stderr: io.stderr ?? ((text) => process.stderr.write(text)),
+    };
+}
+export function line(write, value) {
+    write(`${value}\n`);
+}
+export function command(command, args, cwd) {
+    const result = spawnSync(command, args, { cwd, encoding: "utf8" });
+    if (result.error)
+        throw result.error;
+    return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+export function exists(pathname) {
+    try {
+        return Boolean(fs.lstatSync(pathname));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=common.js.map

package/dist/lib/core-utils/detect-stale-core-policy-mirror.d.ts

@@ -0,0 +1,7 @@
+import { type UtilityIo } from "./common.js";
+export type CorePolicyMirrorOptions = UtilityIo & {
+    root?: string;
+};
+/** Find stale personal-policy mirror files, retaining the shell command's modes and exit ABI. */
+export declare function detectStaleCorePolicyMirror(args?: string[], options?: CorePolicyMirrorOptions): number;
+//# sourceMappingURL=detect-stale-core-policy-mirror.d.ts.map

package/dist/lib/core-utils/detect-stale-core-policy-mirror.js

@@ -0,0 +1,101 @@
+/** Native implementation of core/scripts/detect-stale-core-policy-mirror.sh. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ioFor, line } from "./common.js";
+function namesIn(directory) {
+    try {
+        return fs.readdirSync(directory).filter((name) => name.endsWith(".md")).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Find stale personal-policy mirror files, retaining the shell command's modes and exit ABI. */
+export function detectStaleCorePolicyMirror(args = [], options = {}) {
+    const { stdout, stderr } = ioFor(options);
+    const arg = args[0] ?? "";
+    const mode = arg === "" ? "report" : arg === "--json" ? "json" : arg === "--check" ? "check" : arg === "--prune-identical" ? "prune" : arg === "-h" || arg === "--help" ? "help" : "invalid";
+    if (mode === "invalid") {
+        line(stderr, `detect-stale-core-policy-mirror: unknown argument: ${arg}`);
+        line(stderr, "usage: detect-stale-core-policy-mirror.sh [--json|--check|--prune-identical]");
+        return 2;
+    }
+    if (mode === "help") {
+        stdout("# detect-stale-core-policy-mirror.sh — find leftover core/policies/ copies of a\n# personal/policies/ twin from before the personal→core policy mirror was\n# retired.\n#\n# Background: HQ used to symlink personal/policies/<slug>.md into\n# core/policies/<slug>.md at reindex time. That mirror is retired — the policy\n# trigger hook (.claude/hooks/inject-policy-on-trigger.sh) now reads\n# personal/policies/ DIRECTLY, ahead of core/policies/, and dedups by policy id.\n# But an install upgraded across the retirement can still carry stale REGULAR\n# FILE copies of personal policies inside core/policies/. Those copies are\n# release-owned scaffold: /update-hq will not refresh them from personal/, and a\n# copy that is missing the when:/on: trigger frontmatter its personal twin has\n# gained (via migrate-policy-triggers.sh) can shadow or diverge from the live\n# rule in confusing ways.\n#\n# This tool classifies every core/policies twin of a personal policy:\n#   identical  — byte-identical to the personal twin: an orphaned mirror copy,\n#                behavior-neutral to remove (the personal twin still loads, and\n#                /update-hq restores any genuinely release-shipped file).\n#   symlink    — a leftover personal→core mirror symlink: resolves back to\n#                personal, so also a behavior-neutral orphan.\n#   diverged   — content differs from the personal twin. DRIFT CAN RUN EITHER\n#                DIRECTION (the core copy may be the newer, genericized one).\n#                These are NEVER pruned — a human must classify each.\n#\n# Modes:\n#   (default)          human-readable report; always exit 0.\n#   --json             machine-readable JSON array; exit 0.\n#   --check            exit 0 if no twins, 1 if any twin exists (advisory gate).\n#   --prune-identical  remove ONLY identical + leftover-symlink orphans; never\n#                      touch diverged; print each action; exit 0.\n#\n# It never writes to personal/, never syncs personal→core, and never removes a\n# core/policies file that has no personal twin (release-shipped policies are\n# left untouched by construction).\n");
+        return 0;
+    }
+    const root = options.root ?? process.env.HQ_ROOT ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+    const personal = path.join(root, "personal/policies");
+    const core = path.join(root, "core/policies");
+    const mirrors = [];
+    for (const policy of namesIn(personal)) {
+        if (policy === "example-policy.md" || policy === "README.md")
+            continue;
+        const personalFile = path.join(personal, policy);
+        const coreFile = path.join(core, policy);
+        let coreStat;
+        try {
+            coreStat = fs.lstatSync(coreFile);
+        }
+        catch {
+            continue;
+        }
+        let status;
+        if (coreStat.isSymbolicLink())
+            status = "symlink";
+        else
+            status = fs.readFileSync(personalFile).equals(fs.readFileSync(coreFile)) ? "identical" : "diverged";
+        mirrors.push({ policy, status, core_path: `core/policies/${policy}`, personal_path: `personal/policies/${policy}` });
+    }
+    const orphaned = mirrors.filter((item) => item.status !== "diverged");
+    const diverged = mirrors.filter((item) => item.status === "diverged");
+    if (mode === "json") {
+        line(stdout, JSON.stringify(mirrors));
+        return 0;
+    }
+    if (mode === "check") {
+        if (!mirrors.length) {
+            line(stdout, "detect-stale-core-policy-mirror: clean (no core/policies twins of a personal policy)");
+            return 0;
+        }
+        line(stderr, `detect-stale-core-policy-mirror: ${mirrors.length} twin(s) found — ${orphaned.length} prunable orphan(s), ${diverged.length} diverged (need human classification)`);
+        return 1;
+    }
+    if (mode === "prune") {
+        if (!mirrors.length) {
+            line(stdout, "detect-stale-core-policy-mirror: nothing to prune (no twins)");
+            return 0;
+        }
+        for (const item of mirrors) {
+            if (item.status === "diverged")
+                line(stdout, `SKIPPED (diverged, needs human classification): ${item.core_path}`);
+            else {
+                fs.unlinkSync(path.join(root, item.core_path));
+                line(stdout, `pruned  (${item.status}): ${item.core_path}`);
+            }
+        }
+        line(stdout, `detect-stale-core-policy-mirror: pruned ${orphaned.length} orphan(s); left ${diverged.length} diverged twin(s) for review.`);
+        return 0;
+    }
+    if (!mirrors.length) {
+        line(stdout, "detect-stale-core-policy-mirror: clean — no core/policies copies shadow a personal twin.");
+        return 0;
+    }
+    line(stdout, `Stale personal→core policy mirror copies in core/policies/ (${mirrors.length} twin(s)):`);
+    line(stdout, "");
+    if (orphaned.length) {
+        line(stdout, "Orphaned mirror copies (behavior-neutral — remove with --prune-identical):");
+        for (const item of orphaned)
+            line(stdout, `  ${item.status.padEnd(10)} ${item.core_path}`);
+        line(stdout, "");
+    }
+    if (diverged.length) {
+        line(stdout, "Diverged copies (DRIFT MAY RUN EITHER DIRECTION — classify by hand, do NOT blind-sync):");
+        for (const item of diverged)
+            line(stdout, `  diverged   ${item.core_path}   (diff: git diff --no-index ${item.personal_path} ${item.core_path})`);
+        line(stdout, "");
+    }
+    line(stdout, `Summary: ${orphaned.length} orphan(s), ${diverged.length} diverged.`);
+    return 0;
+}
+//# sourceMappingURL=detect-stale-core-policy-mirror.js.map

package/dist/lib/core-utils/hq-status-summary.d.ts

@@ -0,0 +1,9 @@
+import { type UtilityIo } from "./common.js";
+type HqStatusOptions = UtilityIo & {
+    cwd?: string;
+    root?: string;
+};
+/** Classify porcelain status records using the same path-prefix and baseline rules as the shell utility. */
+export declare function summarizeHqStatus(args?: string[], options?: HqStatusOptions): number;
+export {};
+//# sourceMappingURL=hq-status-summary.d.ts.map

package/dist/lib/core-utils/hq-status-summary.js

@@ -0,0 +1,96 @@
+/** Native implementation of core/scripts/hq-status-summary.sh. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { command, ioFor, line } from "./common.js";
+function jsonPaths(value) { try {
+    const input = JSON.parse(value);
+    return Array.isArray(input) ? input.flatMap((entry) => typeof entry === "string" ? [entry] : entry && typeof entry === "object" && typeof entry.path === "string" ? [entry.path] : []) : [];
+}
+catch {
+    return [];
+} }
+function matchesBaseline(pathname, pattern) { const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*"); return new RegExp(`^${escaped}$`).test(pathname); }
+function statusRoot(cwd, root) { if (root)
+    return root; if (process.env.HQ_ROOT)
+    return process.env.HQ_ROOT; const result = command("git", ["rev-parse", "--show-toplevel"], cwd); return result.status === 0 ? result.stdout.trim() : cwd; }
+/** Classify porcelain status records using the same path-prefix and baseline rules as the shell utility. */
+export function summarizeHqStatus(args = [], options = {}) {
+    const { stdout, stderr } = ioFor(options);
+    const cwd = options.cwd ?? process.cwd();
+    let porcelainFile = "", sessionJson = "[]", sessionFile = "", format = "json";
+    for (let index = 0; index < args.length;) {
+        const arg = args[index];
+        if (arg === "--porcelain-file") {
+            porcelainFile = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--session-files-json") {
+            sessionJson = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--session-files-file") {
+            sessionFile = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--json") {
+            format = "json";
+            index++;
+        }
+        else if (arg === "--text") {
+            format = "text";
+            index++;
+        }
+        else {
+            line(stderr, `Unknown arg: ${arg}`);
+            return 2;
+        }
+    }
+    if (sessionFile && !fs.existsSync(sessionFile)) {
+        line(stderr, `hq-status-summary: --session-files-file not found: ${sessionFile}`);
+        return 3;
+    }
+    const root = statusRoot(cwd, options.root);
+    const sessions = sessionFile ? jsonPaths(fs.readFileSync(sessionFile, "utf8")) : jsonPaths(sessionJson);
+    let patterns = ["companies/*", "workspace/*", "repos/*", "core/settings/*", ".hq/*"];
+    const baseline = path.join(root, "workspace/baseline/hq-local-baseline.json");
+    if (fs.existsSync(baseline)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(baseline, "utf8"));
+            patterns = (parsed.categories ?? []).flatMap((category) => (category.patterns ?? []).filter((item) => typeof item === "string"));
+        }
+        catch {
+            patterns = [];
+        }
+    }
+    const source = porcelainFile ? fs.readFileSync(path.resolve(cwd, porcelainFile), "utf8") : command("git", ["status", "--porcelain", "--ignored"], root).stdout;
+    const lists = { tracked_changes: [], session_touched_untracked: [], baseline_untracked: [], unrelated_untracked: [], ignored: [] };
+    for (const item of source.split(/\r?\n/)) {
+        if (!item)
+            continue;
+        const code = item.slice(0, 2);
+        let pathname = item.slice(3);
+        if (pathname.includes(" -> "))
+            pathname = pathname.slice(pathname.lastIndexOf(" -> ") + 4);
+        if (code === "!!")
+            lists.ignored.push(pathname);
+        else if (code === "??") {
+            if (sessions.some((candidate) => pathname === candidate || pathname.startsWith(`${candidate}/`) || candidate.startsWith(`${pathname}/`)))
+                lists.session_touched_untracked.push(pathname);
+            else if (patterns.some((pattern) => matchesBaseline(pathname, pattern)))
+                lists.baseline_untracked.push(pathname);
+            else
+                lists.unrelated_untracked.push(pathname);
+        }
+        else
+            lists.tracked_changes.push(pathname);
+    }
+    if (format === "text") {
+        for (const [key, values] of Object.entries(lists))
+            line(stdout, `${key === "session_touched_untracked" ? "session_untracked" : key}=${values.length}`);
+        return 0;
+    }
+    const output = { counts: { tracked_changes: lists.tracked_changes.length, session_touched_untracked: lists.session_touched_untracked.length, baseline_untracked: lists.baseline_untracked.length, unrelated_untracked: lists.unrelated_untracked.length, ignored: lists.ignored.length, baseline_noise: lists.baseline_untracked.length + lists.unrelated_untracked.length }, files: lists };
+    line(stdout, JSON.stringify(output, null, 2));
+    return 0;
+}
+//# sourceMappingURL=hq-status-summary.js.map

package/dist/lib/core-utils/ontology-readme-drift.d.ts

@@ -0,0 +1,7 @@
+import { type UtilityIo } from "./common.js";
+export type OntologyReadmeDriftOptions = UtilityIo & {
+    root?: string;
+};
+/** Compare the first README team table with ontology canonical names and aliases. */
+export declare function ontologyReadmeDrift(args?: string[], options?: OntologyReadmeDriftOptions): number;
+//# sourceMappingURL=ontology-readme-drift.d.ts.map

package/dist/lib/core-utils/ontology-readme-drift.js

@@ -0,0 +1,135 @@
+/** Native implementation of core/scripts/ontology-readme-drift.sh. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ioFor, line } from "./common.js";
+const usage = "USAGE: ontology-readme-drift.sh <company-slug> [--root <HQ_ROOT>]";
+const trim = (value) => value.trim();
+const unquote = (value) => { const trimmed = trim(value); return (trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'")) ? trimmed.slice(1, -1) : trimmed; };
+function teamNames(readme) {
+    const results = [];
+    let team = false, table = false, rows = 0;
+    for (const raw of fs.readFileSync(readme, "utf8").split(/\r?\n/)) {
+        if (/^##\s+Team\s*$/.test(raw)) {
+            team = true;
+            continue;
+        }
+        if (team && /^##\s+/.test(raw))
+            break;
+        if (!team)
+            continue;
+        if (/^\s*\|/.test(raw)) {
+            table = true;
+            rows++;
+            if (rows <= 2)
+                continue;
+            const name = trim((raw.replace(/^\s*/, "").split("|")[2] ?? "").replace(/<!--[^>]*-->/g, ""));
+            if (name)
+                results.push(name);
+            continue;
+        }
+        if (table)
+            break;
+    }
+    return results;
+}
+function personNames(person) {
+    const out = [];
+    let markers = 0, frontmatter = false, aliases = false;
+    for (const raw of fs.readFileSync(person, "utf8").split(/\r?\n/)) {
+        if (/^---\s*$/.test(raw)) {
+            markers++;
+            if (markers === 1) {
+                frontmatter = true;
+                continue;
+            }
+            if (markers === 2)
+                break;
+        }
+        if (!frontmatter)
+            continue;
+        if (/^\s*aliases:\s*$/.test(raw)) {
+            aliases = true;
+            continue;
+        }
+        if (aliases && /^\s*-\s*/.test(raw)) {
+            const value = unquote(raw.replace(/^\s*-\s*/, ""));
+            if (value)
+                out.push(value);
+            continue;
+        }
+        if (aliases && !/^\s*(?:$|#)/.test(raw))
+            aliases = false;
+        if (/^\s*canonical_name\s*:/.test(raw)) {
+            const value = unquote(raw.replace(/^\s*canonical_name\s*:\s*/, ""));
+            if (value)
+                out.push(value);
+        }
+    }
+    return out;
+}
+function normalize(name) { return name.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, "").replace(/\s+/g, " ").trim(); }
+function matches(a, b) { if (a === b)
+    return true; if (!a || !b)
+    return false; const at = a.split(" "), bt = b.split(" "); const [smaller, larger] = at.length < bt.length || at.length === bt.length && a.length <= b.length ? [at, bt] : [bt, at]; return smaller.every((token) => larger.includes(token)); }
+/** Compare the first README team table with ontology canonical names and aliases. */
+export function ontologyReadmeDrift(args = [], options = {}) {
+    const { stdout, stderr } = ioFor(options);
+    let slug = "", rootArg = "";
+    for (let index = 0; index < args.length;) {
+        const arg = args[index];
+        if (arg === "--root") {
+            if (index + 1 >= args.length) {
+                line(stderr, usage);
+                return 2;
+            }
+            rootArg = args[index + 1];
+            index += 2;
+        }
+        else if (arg.startsWith("-") || slug) {
+            line(stderr, usage);
+            return 2;
+        }
+        else {
+            slug = arg;
+            index++;
+        }
+    }
+    if (!slug) {
+        line(stderr, usage);
+        return 2;
+    }
+    const root = rootArg || options.root || process.env.HQ_ROOT || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const readme = path.join(root, "companies", slug, "README.md");
+    const persons = path.join(root, "companies", slug, "ontology/entities/person");
+    if (!fs.existsSync(readme)) {
+        line(stderr, `ERROR: README missing: companies/${slug}/README.md`);
+        return 2;
+    }
+    if (!fs.existsSync(persons) || !fs.statSync(persons).isDirectory()) {
+        line(stderr, `ERROR: ontology person directory missing: companies/${slug}/ontology/entities/person`);
+        return 2;
+    }
+    const files = fs.readdirSync(persons).filter((name) => name.endsWith(".md") && fs.statSync(path.join(persons, name)).isFile());
+    if (!files.length) {
+        line(stderr, `ERROR: ontology person directory is empty: companies/${slug}/ontology/entities/person`);
+        return 2;
+    }
+    const ontology = files.flatMap((name) => personNames(path.join(persons, name))).map(normalize).filter(Boolean);
+    if (!ontology.length) {
+        line(stderr, `ERROR: ontology person directory has no canonical_name or aliases to compare: companies/${slug}/ontology/entities/person`);
+        return 2;
+    }
+    let drift = 0;
+    for (const name of teamNames(readme)) {
+        const normalized = normalize(name);
+        if (normalized && !ontology.some((candidate) => matches(normalized, candidate))) {
+            line(stdout, `DRIFT: "${name}" in companies/${slug} README team table has no matching active ontology person entity (possibly departed or misspelled)`);
+            drift++;
+        }
+    }
+    if (!drift)
+        line(stdout, `ontology-readme-drift(${slug}): no drift`);
+    line(stdout, `ontology-readme-drift(${slug}): ${drift} drift(s)`);
+    return drift ? 1 : 0;
+}
+//# sourceMappingURL=ontology-readme-drift.js.map

package/dist/lib/core-utils/resize-screenshot.d.ts

@@ -0,0 +1,10 @@
+import { type UtilityIo } from "./common.js";
+export interface ResizeScreenshotOptions extends UtilityIo {
+    run?: (binary: string, args: string[]) => {
+        status: number;
+        stdout: string;
+    };
+}
+/** Resize a screenshot through the legacy sips/magick codec boundary. */
+export declare function resizeScreenshot(args?: string[], options?: ResizeScreenshotOptions): number;
+//# sourceMappingURL=resize-screenshot.d.ts.map

package/dist/lib/core-utils/resize-screenshot.js

@@ -0,0 +1,50 @@
+/** Native implementation of core/scripts/resize-screenshot.sh. */
+import * as fs from "node:fs";
+import { command, ioFor, line } from "./common.js";
+const MAX_DIM = 1800;
+/** Resize a screenshot through the legacy sips/magick codec boundary. */
+export function resizeScreenshot(args = [], options = {}) {
+    const { stdout, stderr } = ioFor(options);
+    const file = args[0] ?? "";
+    if (!file || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+        line(stderr, `resize-screenshot: file not found: ${file}`);
+        return 1;
+    }
+    const run = options.run ?? ((binary, commandArgs) => command(binary, commandArgs));
+    // The original always queries sips before checking the fallback. Preserve that
+    // ABI; magick is only a resize fallback, not a metadata reader.
+    let width = "", height = "";
+    try {
+        width = run("sips", ["-g", "pixelWidth", file]).stdout.split(/\r?\n/).find((entry) => entry.includes("pixelWidth"))?.trim().split(/\s+/)[1] ?? "";
+        height = run("sips", ["-g", "pixelHeight", file]).stdout.split(/\r?\n/).find((entry) => entry.includes("pixelHeight"))?.trim().split(/\s+/)[1] ?? "";
+    }
+    catch { /* missing sips intentionally maps to legacy dimension error */ }
+    const w = Number.parseInt(width, 10), h = Number.parseInt(height, 10);
+    if (!width || !height || Number.isNaN(w) || Number.isNaN(h)) {
+        line(stderr, "resize-screenshot: cannot read dimensions");
+        return 2;
+    }
+    if (w <= MAX_DIM && h <= MAX_DIM) {
+        line(stdout, `resize-screenshot: ${w}x${h} — within bounds, skipping`);
+        return 0;
+    }
+    const [newW, newH] = w >= h ? [MAX_DIM, Math.trunc(h * MAX_DIM / w)] : [Math.trunc(w * MAX_DIM / h), MAX_DIM];
+    line(stdout, `resize-screenshot: ${w}x${h} → ${newW}x${newH} (${file})`);
+    try {
+        const sips = run("sips", ["--resampleHeightWidth", String(newH), String(newW), file, "--out", file]);
+        if (sips.status !== 0) {
+            const magick = run("magick", [file, "-resize", `${MAX_DIM}x${MAX_DIM}>`, file]);
+            if (magick.status !== 0) {
+                line(stderr, "resize-screenshot: no image tool available (sips/magick)");
+                return 2;
+            }
+        }
+    }
+    catch {
+        line(stderr, "resize-screenshot: no image tool available (sips/magick)");
+        return 2;
+    }
+    line(stdout, "resize-screenshot: done");
+    return 0;
+}
+//# sourceMappingURL=resize-screenshot.js.map

package/dist/lib/core-utils/token-usage-report.d.ts

@@ -0,0 +1,8 @@
+import { type UtilityIo } from "./common.js";
+export type TokenUsageReportOptions = UtilityIo & {
+    projectDir?: string;
+    now?: Date;
+};
+/** Print token usage totals from Claude session JSONL files. */
+export declare function tokenUsageReport(args?: string[], options?: TokenUsageReportOptions): number;
+//# sourceMappingURL=token-usage-report.d.ts.map

package/dist/lib/core-utils/token-usage-report.js

@@ -0,0 +1,196 @@
+/** Native implementation of core/scripts/token-usage-report.sh. */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { ioFor, line } from "./common.js";
+const format = (value) => value.toLocaleString("en-US");
+const dayOf = (date) => date.toISOString().slice(0, 10);
+const parseJsonl = (file) => fs.readFileSync(file, "utf8").split(/\r?\n/).flatMap((raw) => { try {
+    return [JSON.parse(raw)];
+}
+catch {
+    return [];
+} });
+const listJsonl = (dir) => { try {
+    return fs.readdirSync(dir).filter((name) => name.endsWith(".jsonl")).sort();
+}
+catch {
+    return [];
+} };
+const readNumber = (value) => typeof value === "number" ? value : 0;
+function firstUser(record) { const content = record.message?.content; if (typeof content === "string")
+    return content.slice(0, 120); if (Array.isArray(content) && content.length) {
+    const first = content[0];
+    if (first && typeof first === "object" && typeof first.text === "string")
+        return first.text.slice(0, 120);
+} return ""; }
+function comparison(projectDir, before, after, minHours, json, stdout) {
+    const parseRange = (range) => range.split(":").map((value) => new Date(`${value}T00:00:00Z`));
+    const [bStart, bEnd] = parseRange(before), [aStart, aEnd] = parseRange(after);
+    const collect = (start, end) => listJsonl(projectDir).flatMap((name) => {
+        const rows = parseJsonl(path.join(projectDir, name));
+        let cr = 0, first, last;
+        for (const row of rows) {
+            cr += readNumber(row.message?.usage?.cache_read_input_tokens);
+            if (row.timestamp) {
+                if (!first)
+                    first = row.timestamp;
+                last = row.timestamp;
+            }
+        }
+        if (!first || !last)
+            return [];
+        const firstDate = new Date(first), lastDate = new Date(last), day = new Date(`${first.slice(0, 10)}T00:00:00Z`);
+        if (Number.isNaN(firstDate.getTime()) || Number.isNaN(lastDate.getTime()) || day < start || day > end)
+            return [];
+        const hours = Math.max((lastDate.getTime() - firstDate.getTime()) / 3_600_000, 0.01);
+        if (hours < minHours)
+            return [];
+        return [{ sid: name.replace(/\.jsonl$/, "").slice(0, 8), hours: Math.round(hours * 10) / 10, cr, cr_per_hour: Math.trunc(cr / hours) }];
+    });
+    const bRows = collect(bStart, bEnd), aRows = collect(aStart, aEnd);
+    const median = (rows) => { if (!rows.length)
+        return 0; const values = rows.map((row) => row.cr_per_hour).sort((a, b) => a - b); const mid = Math.floor(values.length / 2); return Math.trunc(values.length % 2 ? values[mid] : (values[mid - 1] + values[mid]) / 2); };
+    const bMed = median(bRows), aMed = median(aRows), delta = bMed ? (bMed - aMed) / bMed * 100 : 0;
+    if (json) {
+        line(stdout, JSON.stringify({ before: { window: before, sessions: bRows.length, median_cr_per_hour: bMed, rows: bRows }, after: { window: after, sessions: aRows.length, median_cr_per_hour: aMed, rows: aRows }, delta_pct: Math.round(delta * 10) / 10 }, null, 2));
+        return;
+    }
+    line(stdout, "");
+    line(stdout, `Cache_read/hour comparison (min ${minHours}h session duration)`);
+    line(stdout, "");
+    line(stdout, `  BEFORE  ${before}  — ${bRows.length} sessions`);
+    for (const row of bRows)
+        line(stdout, `    ${row.sid}  ${row.hours.toFixed(1).padStart(5)}h  cr_per_hour=${format(row.cr_per_hour).padStart(12)}`);
+    line(stdout, `    median: ${format(bMed)}/h`);
+    line(stdout, `\n  AFTER   ${after}   — ${aRows.length} sessions`);
+    for (const row of aRows)
+        line(stdout, `    ${row.sid}  ${row.hours.toFixed(1).padStart(5)}h  cr_per_hour=${format(row.cr_per_hour).padStart(12)}`);
+    line(stdout, `    median: ${format(aMed)}/h`);
+    const verdict = delta > 0 ? "IMPROVED" : delta < 0 ? "WORSE" : "unchanged";
+    line(stdout, `\n  Δ:  ${delta >= 0 ? "+" : ""}${delta.toFixed(1)}%  (${verdict})`);
+}
+/** Print token usage totals from Claude session JSONL files. */
+export function tokenUsageReport(args = [], options = {}) {
+    const { stdout, stderr } = ioFor(options);
+    let lastDays = 7, since = "", json = false, before = "", after = "", minHours = 0;
+    for (let index = 0; index < args.length;) {
+        const arg = args[index];
+        if (arg === "--last") {
+            lastDays = Number.parseInt(args[index + 1] ?? "", 10);
+            index += 2;
+        }
+        else if (arg === "--since") {
+            since = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--json") {
+            json = true;
+            index++;
+        }
+        else if (arg === "--compare-windows")
+            index++;
+        else if (arg === "--before") {
+            before = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--after") {
+            after = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--min-hours") {
+            minHours = Number.parseFloat(args[index + 1] ?? "");
+            index += 2;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            stdout("token-usage-report.sh — Daily effective-token totals + top burners from Claude Code session JSONLs.\nUsage:\n  scripts/token-usage-report.sh                # last 7 days, table\n  scripts/token-usage-report.sh --last 14      # last 14 days\n  scripts/token-usage-report.sh --since 2026-05-01\n  scripts/token-usage-report.sh --json         # machine-readable\nEffective tokens weighting (matches weekly rate-limit volume):\n  input + 5×output + 1.25×cache_creation + 0.1×cache_read\n--- Compare-windows mode (US-011) ---\nFormat: --before YYYY-MM-DD:YYYY-MM-DD --after YYYY-MM-DD:YYYY-MM-DD\n");
+            return 0;
+        }
+        else {
+            line(stderr, `Unknown arg: ${arg}`);
+            return 1;
+        }
+    }
+    // Preserve the bundled shell asset's historical parameter-expansion parsing:
+    // the `}` in `{your-name}` terminates `${CLAUDE_PROJECTS_DIR:-…}` early, so
+    // its literal `-Documents-HQ}` suffix remains even when the environment
+    // variable is set. `projectDir` is the explicit native test/integration seam.
+    const projectDir = options.projectDir ?? `${process.env.CLAUDE_PROJECTS_DIR ?? path.join(os.homedir(), ".claude/projects/-Users-{your-name")}-Documents-HQ}`;
+    if (before && after) {
+        comparison(projectDir, before, after, minHours, json, stdout);
+        return 0;
+    }
+    if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
+        line(stderr, `Project dir not found: ${projectDir}`);
+        return 1;
+    }
+    const now = options.now ?? new Date();
+    const cutoff = since || dayOf(new Date(now.getTime() - (lastDays - 1) * 86_400_000));
+    const days = new Map(), sessions = new Map();
+    for (const name of listJsonl(projectDir)) {
+        const file = path.join(projectDir, name);
+        const stat = fs.statSync(file);
+        const mtime = dayOf(stat.mtime);
+        if (mtime < cutoff)
+            continue;
+        let inp = 0, out = 0, cc = 0, cr = 0, firstTs = "", lastTs = "", first = "";
+        for (const record of parseJsonl(file)) {
+            const usage = record.message?.usage;
+            inp += readNumber(usage?.input_tokens);
+            out += readNumber(usage?.output_tokens);
+            cc += readNumber(usage?.cache_creation_input_tokens);
+            cr += readNumber(usage?.cache_read_input_tokens);
+            if (record.timestamp) {
+                if (!firstTs)
+                    firstTs = record.timestamp;
+                lastTs = record.timestamp;
+            }
+            if (!first && record.type === "user")
+                first = firstUser(record);
+        }
+        const sid = name.replace(/\.jsonl$/, "");
+        const subagents = (() => { try {
+            return fs.readdirSync(path.join(projectDir, sid, "subagents")).filter((entry) => entry.endsWith(".jsonl")).length;
+        }
+        catch {
+            return 0;
+        } })();
+        const day = (firstTs || lastTs || "").slice(0, 10) || mtime;
+        if (day < cutoff)
+            continue;
+        const current = days.get(day) ?? { sessions: new Set(), inp: 0, out: 0, cc: 0, cr: 0 };
+        current.sessions.add(sid);
+        current.inp += inp;
+        current.out += out;
+        current.cc += cc;
+        current.cr += cr;
+        days.set(day, current);
+        sessions.set(sid, { day, inp, out, cc, cr, eff: Math.trunc(inp + 5 * out + 1.25 * cc + .1 * cr), subagents, first_user: first.replaceAll("\n", " ") });
+    }
+    const sorted = [...days.keys()].sort();
+    const dayRows = sorted.map((day) => { const value = days.get(day); return { date: day, sessions: value.sessions.size, input: value.inp, output: value.out, cache_create: value.cc, cache_read: value.cr, effective: Math.trunc(value.inp + 5 * value.out + 1.25 * value.cc + .1 * value.cr) }; });
+    const recent = sorted.at(-1);
+    const top = recent ? [...sessions.values()].filter((session) => session.day === recent).sort((a, b) => b.eff - a.eff).slice(0, 3) : [];
+    if (json) {
+        line(stdout, JSON.stringify({ days: dayRows, top_sessions_recent_day: top }, null, 2));
+        return 0;
+    }
+    line(stdout, `\nToken usage (last ${sorted.length} day(s), cutoff ${cutoff})`);
+    line(stdout, "  Effective = input + 5×output + 1.25×cache_create + 0.1×cache_read\n");
+    line(stdout, `  ${"date".padEnd(12)} ${"sessions".padStart(8)} ${"output".padStart(12)} ${"cache_read".padStart(14)} ${"effective".padStart(14)}`);
+    line(stdout, `  ${"-".repeat(12)} ${"-".repeat(8)} ${"-".repeat(12)} ${"-".repeat(14)} ${"-".repeat(14)}`);
+    let total = 0;
+    for (const row of dayRows) {
+        total += row.effective;
+        line(stdout, `  ${row.date.padEnd(12)} ${String(row.sessions).padStart(8)} ${format(row.output).padStart(12)} ${format(row.cache_read).padStart(14)} ${format(row.effective).padStart(14)}`);
+    }
+    line(stdout, `\n  total effective: ${format(total)}`);
+    if (recent && top.length) {
+        line(stdout, `\nTop sessions on ${recent}:`);
+        for (const row of top)
+            line(stdout, `  ${[...sessions.entries()].find(([, value]) => value === row)?.[0].slice(0, 8)}  eff=${format(row.eff).padStart(11)}  subagents=${String(row.subagents).padStart(3)}  ${row.first_user.slice(0, 80)}`);
+    }
+    line(stdout, "");
+    return 0;
+}
+//# sourceMappingURL=token-usage-report.js.map

package/dist/lib/core-utils/worktree.d.ts

@@ -0,0 +1,13 @@
+import { type UtilityIo } from "./common.js";
+export type WorktreeOptions = UtilityIo & {
+    cwd?: string;
+    hqRoot?: string;
+    run?: (args: string[], cwd?: string) => {
+        status: number;
+        stdout: string;
+        stderr: string;
+    };
+};
+/** Create an isolated branch worktree at the exact location established by the legacy shell tool. */
+export declare function createWorktree(args?: string[], options?: WorktreeOptions): number;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/lib/core-utils/worktree.js

@@ -0,0 +1,113 @@
+/** Native implementation of core/scripts/worktree.sh. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { command, ioFor, line } from "./common.js";
+function git(options, args, cwd) { return (options.run ?? ((commandArgs, workingDirectory) => command("git", commandArgs, workingDirectory)))(args, cwd); }
+function emit(result, stdout, stderr) { if (result.stdout)
+    stdout(result.stdout); if (result.stderr)
+    stderr(result.stderr); }
+/** Create an isolated branch worktree at the exact location established by the legacy shell tool. */
+export function createWorktree(args = [], options = {}) {
+    const { stdout, stderr } = ioFor(options);
+    const cwd = options.cwd ?? process.cwd();
+    let name = "", source = "", branch = "", base = "", noPull = false;
+    const usage = (status = 0) => { stdout("# Create a git worktree under {HQ_ROOT}/workspace/worktrees/{repo}/{name}/ on a\n# fresh branch pointing at origin/{default-branch}. The source repo's working\n# tree and local branch refs are left untouched.\n#\n# Usage:\n#   worktree.sh --name <slug> [--source <repo-path>] [--branch <new-branch>]\n#               [--base <branch-or-ref>] [--no-pull]\n"); return status; };
+    for (let index = 0; index < args.length;) {
+        const arg = args[index];
+        if (arg === "--name") {
+            name = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--source") {
+            source = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--branch") {
+            branch = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--base") {
+            base = args[index + 1] ?? "";
+            index += 2;
+        }
+        else if (arg === "--no-pull") {
+            noPull = true;
+            index++;
+        }
+        else if (arg === "-h" || arg === "--help")
+            return usage();
+        else {
+            line(stderr, `unknown arg: ${arg}`);
+            return usage(2);
+        }
+    }
+    const die = (message) => { line(stderr, `ERROR: ${message}`); return 1; };
+    if (!name)
+        return die("--name is required (kebab-case slug, e.g. 'fix-login-bug')");
+    if (name.includes("/") || name.includes(" "))
+        return die(`invalid --name '${name}': no slashes or spaces; use kebab-case`);
+    if (!source) {
+        const result = git(options, ["rev-parse", "--show-toplevel"], cwd);
+        if (result.status === 0)
+            source = result.stdout.trim();
+    }
+    if (!source)
+        return die("not inside a git repo and --source not given");
+    if (!fs.existsSync(path.join(source, ".git")))
+        return die(`${source} is not a git repo`);
+    source = fs.realpathSync(source);
+    const repo = path.basename(source);
+    let hqRoot = process.env.HQ_HOME || options.hqRoot || process.env.HQ_ROOT || "";
+    if (!hqRoot)
+        hqRoot = path.resolve(cwd, "../..");
+    if (!fs.existsSync(path.join(hqRoot, "workspace")))
+        return die(`HQ_ROOT=${hqRoot} has no workspace/ directory`);
+    const hasOrigin = git(options, ["-C", source, "remote", "get-url", "origin"]).status === 0;
+    if (!base) {
+        if (hasOrigin) {
+            const remoteHead = git(options, ["-C", source, "symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+            if (remoteHead.status === 0)
+                base = remoteHead.stdout.trim().replace(/^origin\//, "");
+        }
+        if (!base) {
+            if (git(options, ["-C", source, "show-ref", "--verify", "--quiet", "refs/heads/main"]).status === 0)
+                base = "main";
+            else if (git(options, ["-C", source, "show-ref", "--verify", "--quiet", "refs/heads/master"]).status === 0)
+                base = "master";
+            else
+                return die("cannot determine default branch; pass --base <branch>");
+        }
+    }
+    if (!noPull && hasOrigin) {
+        line(stdout, `→ fetching origin/${base} in ${source}`);
+        const result = git(options, ["-C", source, "fetch", "origin", base]);
+        emit(result, stdout, stderr);
+        if (result.status !== 0)
+            return die(`git fetch origin ${base} failed; rerun with --no-pull to skip, or fix network/auth`);
+    }
+    else if (!noPull)
+        line(stdout, `⚠ no 'origin' remote on ${source} — skipping fetch, basing off local ${base}`);
+    branch ||= `wt/${name}`;
+    let baseRef = base;
+    if (hasOrigin && git(options, ["-C", source, "rev-parse", "--verify", "--quiet", `origin/${base}`]).status === 0)
+        baseRef = `origin/${base}`;
+    const parent = path.join(hqRoot, "workspace/worktrees", repo), target = path.join(parent, name);
+    if (fs.existsSync(target))
+        return die(`${target} already exists. Pick a different --name, or remove it first:\n  git -C ${source} worktree remove ${target}`);
+    if (git(options, ["-C", source, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]).status === 0)
+        return die(`branch '${branch}' already exists in ${source}. Pass --branch <other-name>, or delete:\n  git -C ${source} branch -D ${branch}`);
+    fs.mkdirSync(parent, { recursive: true });
+    line(stdout, `→ creating worktree ${target} on branch ${branch} from ${baseRef}`);
+    const added = git(options, ["-C", source, "worktree", "add", target, "-b", branch, baseRef]);
+    emit(added, stdout, stderr);
+    if (added.status !== 0)
+        return added.status;
+    // Shell captures this command substitution, so its stdout is intentionally
+    // not forwarded to the caller.
+    const sha = git(options, ["-C", target, "rev-parse", "--short", "HEAD"]);
+    if (sha.status !== 0)
+        return sha.status;
+    stdout(`\n✓ worktree ready\n  path:   ${target}\n  branch: ${branch}\n  base:   ${baseRef} (${sha.stdout.trim()})\n  source: ${source}\n\nMain checkout untouched — working tree, local '${base}' ref, and stash are unchanged.\n\nCleanup when done:\n  git -C ${source} worktree remove ${target}\n  git -C ${source} branch -D ${branch}   # optional, drops the branch ref\n`);
+    return 0;
+}
+//# sourceMappingURL=worktree.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.89.1",
+  "version": "5.90.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {