harnery 0.31.6 → 0.33.0

package/src/commands/claude-desktop.ts

@@ -1,12 +1,16 @@
 import type { Command } from "commander";
-import type { EmitContext } from "../commander.ts";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { monorepoRoot } from "../core/agents/index.ts";
 import {
   applyMirror,
+  applyTidy,
   type DesktopAccount,
   findDesktopDataDirs,
   listAccounts,
   planMirror,
+  planTidy,
   readCliAccount,
+  readDesktopLifecycleIndex,
 } from "../lib/claude-desktop.ts";
 
 /**
@@ -24,12 +28,14 @@ import {
  * desktop app picks the copies up, and opening one resumes with full
  * history.
  */
-export function registerClaudeDesktopCommand(program: Command, emit: EmitContext): void {
+export function registerClaudeDesktopCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
   const cmd = program
     .command("claude-desktop")
-    .description(
-      "Claude desktop-app session index: list accounts/sessions, mirror sessions across accounts",
-    )
+    .description("Claude desktop-app session index: list, mirror, and archive completed sessions")
     .action(() => {
       const dirs = requireDataDirs(emit, undefined);
       for (const dir of dirs) {
@@ -184,6 +190,101 @@ export function registerClaudeDesktopCommand(program: Command, emit: EmitContext
         }
       },
     );
+
+  cmd
+    .command("tidy")
+    .description(
+      "Archive desktop sidebar entries whose mapped Harnery lifecycle is done. " +
+        "Dry-run by default; --yes applies atomic entry updates.",
+    )
+    .option("--data-dir <path>", "Explicit desktop-app data directory")
+    .option(
+      "--account <uuid-prefix>",
+      "Only entries under accounts matching this UUID prefix (repeatable)",
+      collect,
+      [] as string[],
+    )
+    .option(
+      "--include-legacy-prefix",
+      "Also archive unmatched historical entries whose title starts with [DONE]",
+    )
+    .option("--yes", "Apply the archive plan (default is dry-run)")
+    .action(
+      async (opts: {
+        dataDir?: string;
+        account: string[];
+        includeLegacyPrefix?: boolean;
+        yes?: boolean;
+      }) => {
+        const dirs = requireDataDirs(emit, opts.dataDir);
+        const coordRoot =
+          context?.resolveCoordRoot?.() ?? context?.repoRoot ?? monorepoRoot() ?? process.cwd();
+        const lifecycle = await readDesktopLifecycleIndex(coordRoot);
+
+        for (const dir of dirs) {
+          const plan = planTidy(listAccounts(dir), lifecycle, {
+            accounts: opts.account,
+            includeLegacyPrefix: opts.includeLegacyPrefix,
+          });
+          const planned = plan.actions.map((action) => ({
+            account_uuid: action.entry.accountUuid,
+            cli_session_id: action.entry.cliSessionId,
+            title: action.entry.title,
+            source: action.source,
+            lifecycle_updated_at: action.lifecycle?.updatedAt ?? null,
+            file: action.entry.file,
+          }));
+          const skipped = plan.skipped
+            .map((skip) => ({
+              account_uuid: skip.entry.accountUuid,
+              cli_session_id: skip.entry.cliSessionId,
+              title: skip.entry.title,
+              reason: skip.reason,
+              lifecycle: skip.lifecycle?.state ?? null,
+            }))
+            .filter((skip) => skip.reason !== "already_archived");
+          const skippedByReason = Object.fromEntries(
+            [
+              "already_archived",
+              "blocked_title",
+              "lifecycle_active",
+              "lifecycle_blocked",
+              "unmatched",
+            ].map((reason) => [
+              reason,
+              plan.skipped.filter((skip) => skip.reason === reason).length,
+            ]),
+          );
+
+          if (!opts.yes) {
+            emit.data({
+              data_dir: dir,
+              dry_run: true,
+              planned,
+              skipped,
+              skipped_by_reason: skippedByReason,
+              hint: plan.actions.length > 0 ? "re-run with --yes to archive" : "nothing to archive",
+            });
+            continue;
+          }
+
+          const result = applyTidy(plan);
+          emit.data({
+            data_dir: dir,
+            dry_run: false,
+            archived: result.archived,
+            already_archived: result.alreadyArchived,
+            planned,
+            skipped,
+            skipped_by_reason: skippedByReason,
+            hint:
+              result.archived > 0
+                ? "fully quit the Claude desktop app (tray icon, not the X) and relaunch to refresh the sidebar"
+                : "nothing to archive",
+          });
+        }
+      },
+    );
 }
 
 function collect(value: string, previous: string[]): string[] {

package/src/commands/deinit.ts

@@ -34,8 +34,10 @@ import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { DEFAULT_BIN_NAME } from "../core/config.ts";
 import { ADAPTER_SPECS, type AdapterId } from "../core/hooks/adapter/events.ts";
+import type { SettingsFile } from "../core/hooks/adapter/wiring.ts";
 import { removeInstructions } from "../lib/instructions/apply.ts";
-import { type SettingsFile, unwireHooks } from "./init.ts";
+import { removeGitHooks } from "../lib/instructions/git-hooks.ts";
+import { unwireHooks } from "./init.ts";
 
 interface DeinitOpts {
   adapter: string;
@@ -138,6 +140,10 @@ export function registerDeinitCommand(program: Command, emit: EmitContext, binNa
       const removed = removeInstructions(projectRoot, { adapter, dryRun });
       actions.push(...removed.actions, ...removed.warnings.map((w) => `! ${w}`));
 
+      // ── 1c. git-hook managed regions ───────────────────────────────────────
+      const gitHooks = removeGitHooks(projectRoot, { dryRun });
+      actions.push(...gitHooks.actions, ...gitHooks.warnings.map((w) => `! ${w}`));
+
       // ── 2. coord root (opt-in; destructive) ────────────────────────────────
       if (purgeState) {
         if (!coordExists) {

package/src/commands/docs.ts

@@ -6,6 +6,7 @@ import {
   runFrontmatterMigration,
 } from "../lib/docs-frontmatter-migrate.ts";
 import { initDocsContext as initDocsIndex, runIndex } from "../lib/docs-index.ts";
+import { initDocsContext as initDocsLinks, runLinks } from "../lib/docs-links.ts";
 import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.ts";
 import { readDocsMetadata, readDocsMetadataKey } from "../lib/docs-meta.ts";
 import {
@@ -27,6 +28,7 @@ function ensureContext(context: HarneryProgramContext | undefined): void {
     extraExcludedPrefixes: context.extraDocsExcludedPrefixes,
     docsRootAllowlist: context.docsRootAllowlist,
   });
+  initDocsLinks({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
   initDocsSweep(opts);
 }
 
@@ -115,6 +117,34 @@ export function registerDocsCommand(
       }
     });
 
+  docs
+    .command("links")
+    .description("Check internal Markdown link targets and heading fragments")
+    .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .option("--no-fragments", "Check target existence only; skip heading-fragment validation")
+    .option("--strict", "Report findings in archive/audit/changelog docs as errors, not warnings")
+    .option("--check-escapes", "Also flag links that resolve outside their own repo root")
+    .option("--fail", "Exit non-zero when errors are found (advisory by default)")
+    .option("--format <type>", "Output format: human, json", "human")
+    .action(
+      async (opts: {
+        repo?: string;
+        fragments?: boolean;
+        strict?: boolean;
+        checkEscapes?: boolean;
+        fail?: boolean;
+        format: string;
+      }) => {
+        try {
+          ensureContext(context);
+          await handleLinks(opts);
+        } catch (err: unknown) {
+          const msg = err instanceof Error ? err.message : String(err);
+          emit.error({ code: "docs_error", message: msg });
+        }
+      },
+    );
+
   docs
     .command("sweep")
     .description(
@@ -232,6 +262,32 @@ async function handleLint(opts: { fast?: boolean; repo?: string; format: string
   if (errors.length > 0) emit.setExitCode(1);
 }
 
+// --- `harn docs links` ---
+
+/**
+ * Advisory by default: a clean exit code even with findings, because turning
+ * link health into a gate is an enforcement policy decision for the host, not
+ * something this command should assume. `--fail` is the opt-in for CI or a hook.
+ */
+async function handleLinks(opts: {
+  repo?: string;
+  fragments?: boolean;
+  strict?: boolean;
+  checkEscapes?: boolean;
+  fail?: boolean;
+  format: string;
+}): Promise<void> {
+  if (opts.format === "json") emit.config({ format: "json" });
+  const report = await runLinks({
+    repo: opts.repo,
+    noFragments: opts.fragments === false,
+    strict: opts.strict,
+    checkEscapes: opts.checkEscapes,
+  });
+  emit.data({ ...report, advisory: !opts.fail });
+  if (opts.fail && report.error_count > 0) emit.setExitCode(1);
+}
+
 // --- `harn docs sweep` ---
 
 async function handleSweep(opts: { repo?: string; format: string }): Promise<void> {

package/src/commands/doctor.ts

@@ -19,7 +19,16 @@ import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { BUILTIN_ADAPTER_IDS } from "../core/adapters/index.ts";
 import { resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
-import { loadAdapterWiring } from "../core/hooks/adapter/wiring.ts";
+import { ADAPTER_SPECS, type AdapterId } from "../core/hooks/adapter/events.ts";
+import { loadAdapterWiring, summarizeAdapterWiring } from "../core/hooks/adapter/wiring.ts";
+import {
+  type CodexHookAuthorizationResult,
+  probeCodexHookAuthorization,
+} from "../core/hooks/codex-authorization.ts";
+import {
+  type CodexWslBridgeStatus,
+  inspectCodexWslBridge,
+} from "../core/hooks/codex-wsl-bridge.ts";
 import {
   ADAPTER_BINARIES,
   ADAPTER_INSTALL_HINTS,
@@ -27,11 +36,12 @@ import {
 } from "../core/workflow/adapters.ts";
 import { probeBilling } from "../core/workflow/billing.ts";
 import type { AdapterName } from "../core/workflow/types.ts";
+import { checkGitHooks, gitHooksInstalled } from "../lib/instructions/git-hooks.ts";
 import { findRg, installRg, managedRgPath, rgInstallSupported } from "../lib/tools/ripgrep.ts";
 
 type Severity = "ok" | "warn" | "fail";
 
-interface Check {
+export interface Check {
   name: string;
   severity: Severity;
   detail: string;
@@ -63,7 +73,7 @@ export function registerDoctorCommand(program: Command, emit: EmitContext): void
           emit.text(`ripgrep install failed: ${(err as Error).message}\n`);
         }
       }
-      const checks = runChecks();
+      const checks = await runChecks();
       const requiredFailed = checks.some((c) => c.severity === "fail");
 
       if (opts.json) {
@@ -96,15 +106,26 @@ export function registerDoctorCommand(program: Command, emit: EmitContext): void
     });
 }
 
-export function runChecks(): Check[] {
+export async function runChecks(): Promise<Check[]> {
+  const codexWslStatus = inspectCodexWslBridge();
+  const codexWslBridge = checkCodexWslBridge(codexWslStatus);
+  // Probe the adapter CLIs before the hook check runs, not in output order:
+  // an unwired adapter only matters if its CLI is actually installed, and
+  // probing once here keeps that join to one spawn per CLI.
+  const workflow = BUILTIN_ADAPTER_IDS.map((id) => ({ id, ...checkWorkflowAdapter(id) }));
+  const installed = workflow.filter((w) => w.installed).map((w) => w.id as AdapterId);
+  const codexAuthorization = await checkCodexHookAuthorization(installed, codexWslStatus);
   return [
     checkNode(),
     checkGit(),
     checkBun(),
     checkRipgrep(),
     checkHarneryDir(),
-    checkAdapterHooks(),
-    ...BUILTIN_ADAPTER_IDS.map(checkWorkflowAdapter),
+    checkAdapterHooks(installed),
+    ...(codexAuthorization ? [codexAuthorization] : []),
+    checkGitHookRegions(),
+    ...(codexWslBridge ? [codexWslBridge] : []),
+    ...workflow.map((w) => w.check),
     checkRestic(),
     checkRclone(),
     checkPlaywright(),
@@ -112,6 +133,91 @@ export function runChecks(): Check[] {
   ];
 }
 
+function checkGitHookRegions(): Check {
+  const root = findCoordProjectRoot();
+  if (!root) {
+    return { name: "git hooks", severity: "ok", detail: "n/a (no .harnery/ above cwd)" };
+  }
+  try {
+    if (!gitHooksInstalled(root)) {
+      const bin = resolveBinName(root);
+      return {
+        name: "git hooks",
+        severity: "warn",
+        detail:
+          `not installed - commits are not guarded against peer-claim conflicts and ` +
+          `claims never auto-release on commit/checkout; run \`${bin} init\` to install`,
+      };
+    }
+    const { status, issues } = checkGitHooks(root);
+    if (status === "fresh") {
+      return { name: "git hooks", severity: "ok", detail: "managed regions current" };
+    }
+    return { name: "git hooks", severity: "warn", detail: issues.join("; ") };
+  } catch (err) {
+    return {
+      name: "git hooks",
+      severity: "warn",
+      detail: `check failed: ${(err as Error).message}`,
+    };
+  }
+}
+
+function checkCodexWslBridge(status: CodexWslBridgeStatus | null): Check | null {
+  if (!status) return null;
+  return {
+    name: "codex:WSL bridge",
+    severity: status.ok ? "ok" : "warn",
+    detail: status.detail,
+    hint: status.ok
+      ? undefined
+      : "forward CODEX_THREAD_ID through WSLENV in the Codex shell environment policy, then start a fresh task",
+  };
+}
+
+export function codexAuthorizationCheck(result: CodexHookAuthorizationResult): Check {
+  const reviewHint =
+    "terminal UI: run `/hooks`; Codex Desktop: open Settings > Hooks; after approval, start a fresh task";
+  if (result.status === "runnable") {
+    return { name: "codex:hook authorization", severity: "ok", detail: result.detail };
+  }
+  if (result.status === "review_required" || result.status === "disabled") {
+    return {
+      name: "codex:hook authorization",
+      severity: "warn",
+      detail: result.detail,
+      hint: reviewHint,
+    };
+  }
+  return {
+    name: "codex:hook authorization",
+    severity: "warn",
+    detail: `authorization unverified: ${result.detail}`,
+    hint: reviewHint,
+  };
+}
+
+async function checkCodexHookAuthorization(
+  installedAdapters: AdapterId[],
+  codexWslStatus: CodexWslBridgeStatus | null,
+): Promise<Check | null> {
+  const root = findCoordProjectRoot();
+  if (!root || !summarizeAdapterWiring(root).wired.includes("codex")) return null;
+
+  if (codexWslStatus) {
+    return {
+      name: "codex:hook authorization",
+      severity: "warn",
+      detail:
+        "unverified from WSL; the Windows-native Codex runtime owns this workspace's trust state",
+      hint: "run the host's Windows bridge doctor, or open Codex Desktop Settings > Hooks; start a fresh task after approval",
+    };
+  }
+  if (!installedAdapters.includes("codex")) return null;
+
+  return codexAuthorizationCheck(await probeCodexHookAuthorization({ cwd: root }));
+}
+
 function checkRipgrep(): Check {
   const found = findRg();
   if (found) {
@@ -157,26 +263,35 @@ function whichVersion(bin: string, args: string[] = ["--version"]): { ok: boolea
  * One workflow spawn target: is the adapter CLI installed, and how will its
  * headless children bill (subscription login vs API key — see billing.ts)?
  * Missing is a warn, not a fail: workflows degrade to the adapters you have.
+ *
+ * Reports `installed` alongside the check so `checkAdapterHooks` can reuse the
+ * probe instead of spawning every adapter CLI a second time.
  */
-function checkWorkflowAdapter(adapter: AdapterName): Check {
+function checkWorkflowAdapter(adapter: AdapterName): { check: Check; installed: boolean } {
   const bin = ADAPTER_BINARIES[adapter];
   const name = `workflow:${adapter}`;
   const r = whichVersion(bin);
   if (!r.ok) {
     return {
-      name,
-      severity: "warn",
-      detail: `${bin} missing (workflow --adapter ${adapter} unavailable)`,
-      hint: `${ADAPTER_INSTALL_HINTS[adapter]}  then: ${ADAPTER_LOGIN_HINTS[adapter]}`,
+      check: {
+        name,
+        severity: "warn",
+        detail: `${bin} missing (workflow --adapter ${adapter} unavailable)`,
+        hint: `${ADAPTER_INSTALL_HINTS[adapter]}  then: ${ADAPTER_LOGIN_HINTS[adapter]}`,
+      },
+      installed: false,
     };
   }
   const probe = probeBilling(adapter);
   if (probe.login === "absent" && !probe.apiKeyPresent) {
     return {
-      name,
-      severity: "warn",
-      detail: `${r.out} — installed, but no stored login or API key detected`,
-      hint: ADAPTER_LOGIN_HINTS[adapter],
+      check: {
+        name,
+        severity: "warn",
+        detail: `${r.out} — installed, but no stored login or API key detected`,
+        hint: ADAPTER_LOGIN_HINTS[adapter],
+      },
+      installed: true,
     };
   }
   const billing =
@@ -185,7 +300,7 @@ function checkWorkflowAdapter(adapter: AdapterName): Check {
         ? "billing: subscription"
         : "billing: subscription (login unverifiable, CLI is the authority)"
       : `billing: ${probe.mode} (${probe.apiKeySource})`;
-  return { name, severity: "ok", detail: `${r.out} — ${billing}` };
+  return { check: { name, severity: "ok", detail: `${r.out} — ${billing}` }, installed: true };
 }
 
 function checkNode(): Check {
@@ -331,13 +446,22 @@ function checkHarneryDir(): Check {
  * loadAdapterWiring — so a bare settings file never false-warns. The remedy is
  * always the same: re-run `<bin> init` (idempotent, additive).
  */
-function checkAdapterHooks(): Check {
+function checkAdapterHooks(installedAdapters: AdapterId[] = []): Check {
   const root = findCoordProjectRoot();
   if (!root) {
     return { name: "adapter hooks", severity: "ok", detail: "n/a (no .harnery/ above cwd)" };
   }
   const drift = loadAdapterWiring(root);
-  if (drift.length === 0) {
+  // A adapter with zero harnery hooks is only worth flagging when the project
+  // plainly uses harnery hooks (something else is wired) AND that adapter's CLI
+  // is installed. Both conditions matter: the first keeps a project that has
+  // never run init quiet, the second keeps a project that simply doesn't have
+  // Codex quiet. What's left is the case that reads as healthy but isn't — an
+  // agent can start a session through that adapter and register nothing.
+  const summary = summarizeAdapterWiring(root);
+  const unwired =
+    summary.wired.length > 0 ? summary.unwired.filter((id) => installedAdapters.includes(id)) : [];
+  if (drift.length === 0 && unwired.length === 0) {
     return { name: "adapter hooks", severity: "ok", detail: "wired + current" };
   }
   const bin = resolveBinName(root);
@@ -356,12 +480,22 @@ function checkAdapterHooks(): Check {
     }
     return `${d.settingsFile}: ${bits.join("; ")}`;
   });
+  for (const id of unwired) {
+    parts.push(`${ADAPTER_SPECS[id].settingsFile}: ${id} CLI installed, no harnery hooks wired`);
+  }
   const needsManualRepair = drift.some(
     (d) => d.parseError || d.invalidTopLevelKeys.length > 0 || d.invalidEventKeys.length > 0,
   );
-  const hint = needsManualRepair
-    ? `repair the invalid adapter settings, then run \`${bin} init\` to migrate harnery hooks`
-    : `run \`${bin} init\` to migrate the hook set (idempotent)`;
+  const wireHints = unwired.map((id) => `\`${bin} init --adapter ${id}\``);
+  let hint: string;
+  if (needsManualRepair) {
+    hint = `repair the invalid adapter settings, then run \`${bin} init\` to migrate harnery hooks`;
+  } else if (drift.length > 0) {
+    hint = `run \`${bin} init\` to migrate the hook set (idempotent)`;
+    if (wireHints.length > 0) hint += `; ${wireHints.join(" and ")} to wire the rest`;
+  } else {
+    hint = `run ${wireHints.join(" and ")} (idempotent, additive)`;
+  }
   return { name: "adapter hooks", severity: "warn", detail: parts.join("  |  "), hint };
 }
 

package/src/commands/init.ts

@@ -36,12 +36,9 @@ import {
   applyInstructions,
   checkInstructions,
 } from "../lib/instructions/apply.ts";
+import { applyGitHooks, checkGitHooks } from "../lib/instructions/git-hooks.ts";
 import { HostAddendumError } from "../lib/instructions/host-addendum.ts";
 
-// Re-exported for back-compat: callers (deinit, tests) import these names
-// from init.ts. The definitions now live in core/hooks/adapter/wiring.ts.
-export type { HookGroup, SettingsFile };
-
 // This file is src/commands/init.ts → harnery package root is two levels up.
 const HARNERY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
@@ -85,15 +82,19 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
       // ── --check: read-only drift report on the block + skills ──────────────
       if (opts.check === true) {
         const { status, issues } = checkInstructions(projectRoot, { binName: bin, adapter });
+        const gitHooks = checkGitHooks(projectRoot);
+        if (gitHooks.status !== "fresh") issues.push(...gitHooks.issues);
+        const merged =
+          status === "error" ? "error" : gitHooks.status !== "fresh" ? "drift" : status;
         const head =
-          status === "fresh"
-            ? "harn init --check: instructions + skills are current"
-            : status === "drift"
+          merged === "fresh"
+            ? "harn init --check: instructions + skills + git hooks are current"
+            : merged === "drift"
               ? "harn init --check: drift found (re-run `init` to refresh)"
               : "harn init --check: error";
         const lines = issues.length ? `\n${issues.map((i) => `  ✗ ${i}`).join("\n")}` : "";
         emit.text(`${head}${lines}`);
-        emit.setExitCode(status === "fresh" ? 0 : status === "drift" ? 2 : 1);
+        emit.setExitCode(merged === "fresh" ? 0 : merged === "drift" ? 2 : 1);
         return;
       }
 
@@ -174,6 +175,8 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
             `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`,
         );
       }
+      const authorizationReview = codexHookReviewAction(adapter);
+      if (authorizationReview) actions.push(authorizationReview);
 
       // ── 3. agent-facing instructions block + skills ────────────────────────
       // A misconfigured host addendum aborts here rather than half-writing: the
@@ -190,10 +193,26 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
       }
       actions.push(...applied.actions);
 
-      emit.text(render(projectRoot, dryRun, actions, applied.warnings));
+      // ── 4. git-hook managed regions ────────────────────────────────────────
+      // Same lifecycle contract as the instructions block: the coordination
+      // content of the consumer's git hooks is machine-owned and versioned;
+      // everything else in those files belongs to the host.
+      const gitHooks = applyGitHooks(projectRoot, { dryRun });
+      actions.push(...gitHooks.actions);
+
+      emit.text(render(projectRoot, dryRun, actions, [...applied.warnings, ...gitHooks.warnings]));
     });
 }
 
+export function codexHookReviewAction(adapter: AdapterId): string | null {
+  if (adapter !== "codex") return null;
+  return (
+    "! Codex authorizes hook commands separately. Before starting work, review them in " +
+    "the terminal UI with `/hooks` or in Codex Desktop under Settings > Hooks. " +
+    "After approval, start a fresh task so SessionStart can run."
+  );
+}
+
 /**
  * Merge agent-hook entries into a adapter settings object in place, idempotently.
  * Preserves every existing hook; rewrites events already wired to