@indigoai-us/hq-cli 5.89.2 → 5.91.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [5.91.0]
+
+### Changed
+
+- The `hq core checkpoint` maintenance sibling now curates the policy and
+  knowledge stores instead of only appending to them. It searches the existing
+  policies first and then amends, supersedes, merges or creates, and corrects a
+  stale durable fact in place rather than shadowing it with a contradictory
+  copy. Deletion is bounded: only as part of a merge or supersede, only inside
+  the policy directories the sibling could already write, never a HARD-marked
+  policy (those are flagged in the report for a human), and never a file it has
+  not read. Every amendment, supersession, merge and deletion must be named in
+  the run report with its reason. (#320)
+
+## [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

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. 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 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   FIRST search the existing policies for one the learning refines, contradicts\n   or duplicates. Then take exactly one of these actions and name it in the\n   report \u2014 the policy set is curated, not append-only:\n   - AMEND an existing policy in place when the learning sharpens it, narrows\n     its scope, or adds a case, and the rule as written is still correct.\n   - SUPERSEDE it when the learning contradicts it: rewrite the rule to what is\n     now true and record inside the file what changed and why.\n   - MERGE near-duplicates into the single best-named file, then delete the\n     files you merged away.\n   - CREATE a new policy only when no existing policy covers the rule.\n   Follow core/knowledge/public/hq-core/policies-spec.md. Write under\n   personal/policies/ or, only when the payload names a company and the rule is\n   company-specific, companies/<company>/policies/.\n   DELETION BOUNDS: delete a policy only as the MERGE or SUPERSEDE step above,\n   only inside those two directories, and never one whose body marks it HARD \u2014\n   if a hard policy now looks wrong, leave it untouched and flag it in the\n   report for a human to decide. Never delete a file you have not read.\n   Apply the same curation to durable facts (not rules) under\n   personal/knowledge/ or companies/<company>/knowledge/: correct a stale fact\n   in place rather than appending a second, contradictory copy of it.\n   Store up to two explicit or transcript-derived insights per\n   core/knowledge/public/hq-core/insights-spec.md when present, otherwise\n   workspace/insights/.\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. List every policy or knowledge file\n   you amended, superseded, merged or deleted with the reason, so a human can\n   audit and reverse it; a deletion you do not name in the report is a defect.\n   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

@@ -56,13 +56,29 @@ report instead of guessing.
    drop -auto- from its filename. Use the renamed path in every reference you
    write afterwards.
 3. For every explicit or transcript-derived learning that is a reusable rule,
-   distill a non-duplicate policy file under personal/policies/ or, only when
-   the payload names a company and the rule is company-specific,
-   companies/<company>/policies/, following
-   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or
-   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md
-   when present, otherwise workspace/insights/. Durable facts (not rules) may
-   go under personal/knowledge/ or companies/<company>/knowledge/ only.
+   FIRST search the existing policies for one the learning refines, contradicts
+   or duplicates. Then take exactly one of these actions and name it in the
+   report — the policy set is curated, not append-only:
+   - AMEND an existing policy in place when the learning sharpens it, narrows
+     its scope, or adds a case, and the rule as written is still correct.
+   - SUPERSEDE it when the learning contradicts it: rewrite the rule to what is
+     now true and record inside the file what changed and why.
+   - MERGE near-duplicates into the single best-named file, then delete the
+     files you merged away.
+   - CREATE a new policy only when no existing policy covers the rule.
+   Follow core/knowledge/public/hq-core/policies-spec.md. Write under
+   personal/policies/ or, only when the payload names a company and the rule is
+   company-specific, companies/<company>/policies/.
+   DELETION BOUNDS: delete a policy only as the MERGE or SUPERSEDE step above,
+   only inside those two directories, and never one whose body marks it HARD —
+   if a hard policy now looks wrong, leave it untouched and flag it in the
+   report for a human to decide. Never delete a file you have not read.
+   Apply the same curation to durable facts (not rules) under
+   personal/knowledge/ or companies/<company>/knowledge/: correct a stale fact
+   in place rather than appending a second, contradictory copy of it.
+   Store up to two explicit or transcript-derived insights per
+   core/knowledge/public/hq-core/insights-spec.md when present, otherwise
+   workspace/insights/.
 4. Close an active session journal fail-soft with
    bash .claude/skills/_shared/journal.sh close "<project_dir>" "<one-line synthesis>".
    Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with
@@ -78,7 +94,10 @@ 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. Then drain the queue: while
+   (paths), and what you skipped and why. List every policy or knowledge file
+   you amended, superseded, merged or deleted with the reason, so a human can
+   audit and reverse it; a deletion you do not name in the report is a defect.
+   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

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.2",
+  "version": "5.91.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -29,7 +29,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "^6.14.45",
+    "@indigoai-us/hq-cloud": "^6.14.47",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "1.0.7",