harnery 0.38.0 → 0.40.0

package/src/lib/browser/thumbnail-association.ts

@@ -0,0 +1,190 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  openSync,
+  readSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import path from "node:path";
+
+const MAX_HTML = 2 * 1024 * 1024;
+const MAX_PNG = 32 * 1024 * 1024;
+export interface CaptureFingerprint {
+  version: string;
+  sha256: string;
+}
+export interface CaptureThumbnailAssociation {
+  schema_version: 2;
+  producer: "browser-standalone-capture";
+  source: CaptureFingerprint & { path: string };
+  preview: CaptureFingerprint & { path: string };
+}
+function version(fd: number): string {
+  const s = fstatSync(fd);
+  return `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`;
+}
+function fingerprint(filename: string, maxBytes: number): CaptureFingerprint | null {
+  const canonical = realpathSync(filename);
+  const before = statSync(canonical);
+  if (!before.isFile() || before.size > maxBytes) return null;
+  const fd = openSync(canonical, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) return null;
+    const initial = version(fd);
+    const hash = createHash("sha256");
+    const bytes = Buffer.alloc(64 * 1024);
+    let offset = 0;
+    while (offset < before.size) {
+      const count = readSync(fd, bytes, 0, Math.min(bytes.length, before.size - offset), offset);
+      if (!count) return null;
+      hash.update(bytes.subarray(0, count));
+      offset += count;
+    }
+    if (version(fd) !== initial || realpathSync(filename) !== canonical) return null;
+    return { version: initial, sha256: hash.digest("hex") };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Take immediately after the screenshot writer completes, before asynchronous
+ * HTML serialization. A later writer cannot silently substitute its PNG. */
+export function captureThumbnailFingerprint(pngPath: string): CaptureFingerprint | null {
+  try {
+    return fingerprint(pngPath, MAX_PNG);
+  } catch {
+    return null;
+  }
+}
+function workspaceFor(filename: string): { root: string; workspace: string } | null {
+  for (
+    let current = path.dirname(filename);
+    path.dirname(current) !== current;
+    current = path.dirname(current)
+  ) {
+    const artifacts = path.dirname(current);
+    const state = path.dirname(artifacts);
+    if (path.basename(artifacts) === "artifacts" && path.basename(state) === ".harnery")
+      return { root: path.dirname(state), workspace: current };
+  }
+  return null;
+}
+function inside(root: string, filename: string): boolean {
+  const relative = path.relative(root, filename);
+  return (
+    relative !== "" &&
+    relative !== ".." &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+/** Associate only the full-document, standalone HTML and exact PNG produced by
+ * this capture operation. No basename inference and no reads of source pages.
+ * A linked asset, selector fragment, changed output, oversize file or output
+ * outside a managed artifact workspace safely skips registration.
+ * The hidden sidecar binds canonical repository paths, checked file versions
+ * and SHA256 receipts. Web readers also require an empty local asset graph;
+ * manual registrations bind their own complete dependency graph instead. */
+export function registerCaptureThumbnail(input: {
+  htmlPath: string;
+  pngPath: string;
+  html: string;
+  preview: CaptureFingerprint;
+  fullDocument: boolean;
+  stylesheetsLinked: number;
+  resourcesLinked: number;
+}): string | null {
+  if (!input.fullDocument || input.stylesheetsLinked !== 0 || input.resourcesLinked !== 0)
+    return null;
+  try {
+    const htmlPath = realpathSync(input.htmlPath);
+    const pngPath = realpathSync(input.pngPath);
+    if (!/\.html?$/i.test(htmlPath) || !/\.png$/i.test(pngPath)) return null;
+    const owner = workspaceFor(htmlPath);
+    if (!owner || !inside(owner.workspace, pngPath)) return null;
+    const source = fingerprint(htmlPath, MAX_HTML);
+    const preview = fingerprint(pngPath, MAX_PNG);
+    if (
+      !source ||
+      !preview ||
+      source.sha256 !== createHash("sha256").update(input.html).digest("hex") ||
+      preview.version !== input.preview.version ||
+      preview.sha256 !== input.preview.sha256
+    )
+      return null;
+    const sourceRelative = path.relative(owner.root, htmlPath).split(path.sep).join("/");
+    const previewRelative = path.relative(owner.root, pngPath).split(path.sep).join("/");
+    const association: CaptureThumbnailAssociation = {
+      schema_version: 2,
+      producer: "browser-standalone-capture",
+      source: { path: sourceRelative, ...source },
+      preview: { path: previewRelative, ...preview },
+    };
+    const name = `.thumbnail-preview-${createHash("sha256").update(sourceRelative).digest("hex").slice(0, 24)}.json`;
+    const directoryFd = openSync(
+      owner.workspace,
+      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+    );
+    try {
+      let anchor: string | undefined;
+      for (const prefix of ["/proc/self/fd", "/dev/fd"]) {
+        const candidate = `${prefix}/${directoryFd}`;
+        try {
+          if (realpathSync(candidate) === owner.workspace) {
+            anchor = candidate;
+            break;
+          }
+        } catch {
+          /* unsupported descriptor namespace */
+        }
+      }
+      if (!anchor) return null;
+      const target = path.join(anchor, name);
+      const temporary = `${target}.${randomUUID()}.tmp`;
+      const fd = openSync(
+        temporary,
+        constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+        0o600,
+      );
+      try {
+        const bytes = Buffer.from(`${JSON.stringify(association)}\n`);
+        if (bytes.length > 16 * 1024) return null;
+        let offset = 0;
+        while (offset < bytes.length) offset += writeSync(fd, bytes, offset, bytes.length - offset);
+        if (
+          realpathSync(anchor) !== owner.workspace ||
+          realpathSync(owner.workspace) !== owner.workspace
+        )
+          return null;
+        // Stat again after the write, without reading another potentially large
+        // image. ctime detects same-size edits with a restored mtime.
+        const matches = (filename: string, expected: string) => {
+          const s = statSync(filename);
+          return `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}` === expected;
+        };
+        if (!matches(htmlPath, source.version) || !matches(pngPath, preview.version)) return null;
+        renameSync(temporary, target);
+      } finally {
+        closeSync(fd);
+        try {
+          unlinkSync(temporary);
+        } catch {
+          /* renamed */
+        }
+      }
+    } finally {
+      closeSync(directoryFd);
+    }
+    return path.relative(owner.root, path.join(owner.workspace, name)).split(path.sep).join("/");
+  } catch {
+    return null;
+  }
+}

package/src/lib/browser/tiling.ts

@@ -194,3 +194,66 @@ export function bandsCoveringRects(
   }
   return out;
 }
+
+/** All native-pixel candidates, before any per-pack allocation or cropping. */
+export function reviewCandidateRects(args: {
+  width: number;
+  height: number;
+  bandHeight: number;
+  overlap: number;
+  atoms?: VisualAtom[];
+  scopes?: Array<{
+    selector: string;
+    rects: Array<{ label: string; x: number; y: number; width: number; height: number }>;
+  }>;
+}): Array<{
+  id: string;
+  index: number;
+  label: string;
+  rect: { x: number; y: number; width: number; height: number };
+  scope?: string;
+  gate_hits: [];
+}> {
+  const opts = { bandHeight: args.bandHeight, overlap: args.overlap };
+  const bands = args.atoms?.length
+    ? snappedBandRects(0, args.height, 0, args.width, args.atoms, opts).rects
+    : Array.from(
+        {
+          length:
+            Math.ceil(
+              Math.max(0, args.height - args.bandHeight) /
+                Math.max(1, args.bandHeight - args.overlap),
+            ) + 1,
+        },
+        (_, i) => {
+          const y = i * Math.max(1, args.bandHeight - args.overlap);
+          return { x: 0, y, width: args.width, height: Math.min(args.bandHeight, args.height - y) };
+        },
+      );
+  const out: ReturnType<typeof reviewCandidateRects> = bands.map((r, i) => ({
+    id: `band-${i + 1}`,
+    index: i,
+    label: `band ${i + 1}`,
+    rect: { x: r.x, y: r.y, width: r.width, height: r.height },
+    gate_hits: [],
+  }));
+  for (const [scopeIndex, scope] of (args.scopes ?? []).entries()) {
+    const expanded = scope.rects.flatMap((r) => bandOversizedRect(r, args.atoms ?? [], opts));
+    for (const [i, r] of expanded.entries()) {
+      const x = Math.max(0, Math.round(r.x)),
+        y = Math.max(0, Math.round(r.y));
+      const width = Math.min(Math.round(r.width), args.width - x),
+        height = Math.min(Math.round(r.height), args.height - y);
+      if (width <= 0 || height <= 0) continue;
+      out.push({
+        id: `scope-${scopeIndex + 1}-${i + 1}`,
+        index: out.length,
+        label: r.label,
+        scope: scope.selector,
+        rect: { x, y, width, height },
+        gate_hits: [],
+      });
+    }
+  }
+  return out;
+}

package/src/lib/docs-metadata-managed.ts

@@ -18,7 +18,10 @@ export function isExcludedDocsMetadataPath(path: string): boolean {
     // Dashboard surfaces render from copies of other repositories' documents.
     /(?:^|\/)content\/dashboards\//.test(rel) ||
     /(?:^|\/)docs\/shopify\/admin-api\//.test(rel) ||
-    /(?:^|\/)docs\/templates\//.test(rel)
+    // Template skeletons carry placeholder frontmatter by design. Hosts keep
+    // them under docs/templates/ or another documentation root such as
+    // meta-docs/templates/, so match the directory name rather than one root.
+    /(?:^|\/)templates\//.test(rel)
   );
 }
 

package/src/lib/identities/assume.ts

@@ -16,7 +16,6 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-
 import { recordLiveIdentityChangeV3 } from "../../core/agents/live-authority-v3.ts";
 import { recordLiveSweepObservationV3 } from "../../core/agents/live-lifecycle-v3.ts";
 import type { Heartbeat } from "../../core/agents/state/heartbeat-writer.ts";
@@ -27,6 +26,7 @@ import {
 import { resolveForkAncestry } from "../../core/agents/state/names.ts";
 import { instanceHasLivePid, removePidmapRowsForInstance } from "../../core/agents/state/pidmap.ts";
 import { coordFreshnessSeconds } from "../../core/config.ts";
+import type { EventAdapterIdV3 } from "../../core/events/v3/adapter-id.ts";
 import { readRemoteMachines } from "../../core/presence/index.ts";
 import { type AgentIdentity, bareName, ensureIdentity, lookupById, lookupByName } from "./index.ts";
 
@@ -133,7 +133,7 @@ export function reclaimAbandonedLocalConflict(
   if (instanceHasLivePid(coordRoot, conflict.instance_id)) return false;
 
   const hbPath = join(coordRoot, ".harnery", "active", `${conflict.instance_id}.json`);
-  let adapter: "claude-code" | "cursor" | "codex" = "claude-code";
+  let adapter: EventAdapterIdV3 = "claude-code";
   let sessionId = conflict.instance_id;
   let ageSecs: number | undefined;
   const liveRow = readLiveCoordinationRow(coordRoot, conflict.instance_id);
@@ -236,9 +236,10 @@ function acquireLock(coordRoot: string): () => void {
   );
 }
 
-function adapterOf(platform: string | undefined): "claude-code" | "cursor" | "codex" {
+function adapterOf(platform: string | undefined): EventAdapterIdV3 {
   if (platform === "cursor") return "cursor";
   if (platform === "codex") return "codex";
+  if (platform === "openclaw") return "openclaw";
   return "claude-code";
 }
 
@@ -328,11 +329,18 @@ export function assumeIdentity(
       };
     }
 
+    const adapter = adapterOf(hb.platform);
+    if (adapter === "openclaw") {
+      throw new IdentityAssumeError(
+        "not_session",
+        "identity assumption is unavailable for observer-only OpenClaw generations",
+      );
+    }
     const emitted = recordLiveIdentityChangeV3({
       coordRoot,
       owner: instanceId,
       nativeSessionId: hb.native_session_id ?? hb.session_id,
-      adapter: adapterOf(hb.platform),
+      adapter,
       name: identity.name,
       identityId: identity.agent_id,
     });

package/src/lib/instructions/templates.ts

@@ -150,6 +150,7 @@ Use it for anything future-you or a peer will need to pick up your thread.
 and other untracked files that must survive a session, create a managed workspace
 with \`${b} artifacts create <slug> --purpose "<why>"\`. Write files under the
 returned path, then run \`${b} artifacts release <id>\` when active work is done.
+After review, use \`${b} artifacts discard <id> --reason "<why no longer needed>"\` for disposable or superseded evidence: it releases ownership and shortens retention to at most 60 minutes (\`--minutes\` overrides). Keep unresolved failures, handoffs, final evidence, and files awaiting review; use a hold when needed. A passing check cannot establish whether another reader needs the files, so the reviewing agent decides. For known short-lived work, \`${b} artifacts create --minutes <n>\` sets the initial window.
 Do not create a repo-root temp directory; \`${b} artifacts clean\` previews
 expired cleanup and requires \`--yes\` to delete anything.
 

package/src/lib/local-file-url.ts

@@ -4,13 +4,28 @@ export const DEFAULT_WEB_PORT = 4276;
 /** Cookie-isolated host for navigable repo files. */
 export const FILES_ORIGIN_HOST = "harnery-files.localhost";
 
+/**
+ * Percent-encode one URL component so the finished URL is safe as a bare
+ * Markdown destination.
+ *
+ * encodeURIComponent leaves parentheses raw, and a raw ")" ends a `[text](url)`
+ * destination early. The alternative is the angle-bracket destination form,
+ * which is valid CommonMark but is not implemented by every renderer, and one
+ * that skips it can style the text as a link while dropping the href, leaving
+ * something that looks clickable and does nothing. These URLs are written into
+ * Markdown for humans to click, so encode the parentheses instead.
+ */
+export function encodeLinkSafeComponent(value: string): string {
+  return encodeURIComponent(value).replace(/[()]/g, (char) => (char === "(" ? "%28" : "%29"));
+}
+
 /** Encode each repo-path segment while preserving slash-based URL resolution. */
 export function encodedRepoPath(relPath: string): string {
   return relPath
     .replace(/^\/+/, "")
     .split("/")
     .filter(Boolean)
-    .map((segment) => encodeURIComponent(segment))
+    .map((segment) => encodeLinkSafeComponent(segment))
     .join("/");
 }
 
@@ -27,5 +42,5 @@ export function localFileViewerUrl(
   relPath: string,
   port: number | string = DEFAULT_WEB_PORT,
 ): string {
-  return `http://localhost:${port}/files?path=${encodeURIComponent(relPath)}`;
+  return `http://localhost:${port}/files?path=${encodeLinkSafeComponent(relPath)}`;
 }

package/src/lib/tunnel/state.ts

@@ -1,4 +1,4 @@
-// Tunnel config + state persistence + provider helpers. Lives under
+// Tunnel config + state persistence + provider helpers. Commands default to
 // <cwd>/.cache/tunnel/; gitignored, so the allowlist is per-machine.
 
 import { execSync } from "node:child_process";
@@ -12,9 +12,10 @@ import {
 } from "node:fs";
 import { resolve } from "node:path";
 
-// Inline cachePath: tunnel state under <cwd>/.cache/tunnel/.
-function cachePath(tool: string, filename: string): string {
-  const dir = resolve(process.cwd(), ".cache", tool);
+// Tunnel state lives under <root>/.cache/tunnel/. Root defaults to cwd for the
+// command surface and can be supplied by callers that already resolved a repo.
+function cachePath(tool: string, filename: string, root: string = process.cwd()): string {
+  const dir = resolve(root, ".cache", tool);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   return resolve(dir, filename);
 }
@@ -107,8 +108,11 @@ export function writeConfig(cfg: TunnelConfig): void {
   writeFileSync(cachePath("tunnel", CONFIG_FILE), JSON.stringify(cfg, null, 2));
 }
 
-export function readState(name: string = DEFAULT_INSTANCE): TunnelState | null {
-  const p = cachePath("tunnel", stateFile(name));
+export function readState(
+  name: string = DEFAULT_INSTANCE,
+  root: string = process.cwd(),
+): TunnelState | null {
+  const p = cachePath("tunnel", stateFile(name), root);
   if (!existsSync(p)) return null;
   try {
     return normalizeState(JSON.parse(readFileSync(p, "utf-8")) as TunnelState, name);
@@ -117,12 +121,12 @@ export function readState(name: string = DEFAULT_INSTANCE): TunnelState | null {
   }
 }
 
-export function writeState(state: TunnelState): void {
-  writeFileSync(cachePath("tunnel", stateFile(state.name)), JSON.stringify(state, null, 2));
+export function writeState(state: TunnelState, root: string = process.cwd()): void {
+  writeFileSync(cachePath("tunnel", stateFile(state.name), root), JSON.stringify(state, null, 2));
 }
 
-export function clearState(name: string = DEFAULT_INSTANCE): void {
-  const p = cachePath("tunnel", stateFile(name));
+export function clearState(name: string = DEFAULT_INSTANCE, root: string = process.cwd()): void {
+  const p = cachePath("tunnel", stateFile(name), root);
   if (existsSync(p)) unlinkSync(p);
 }
 
@@ -130,14 +134,14 @@ export function clearState(name: string = DEFAULT_INSTANCE): void {
  * Every persisted tunnel instance, newest-started first. Reads every
  * `state*.json` under `.cache/tunnel/`; tolerates missing/corrupt files.
  */
-export function listStates(): TunnelState[] {
-  const dir = resolve(process.cwd(), ".cache", "tunnel");
+export function listStates(root: string = process.cwd()): TunnelState[] {
+  const dir = resolve(root, ".cache", "tunnel");
   if (!existsSync(dir)) return [];
   const out: TunnelState[] = [];
   for (const file of readdirSync(dir)) {
     const name = nameFromStateFile(file);
     if (name === null) continue;
-    const state = readState(name);
+    const state = readState(name, root);
     if (state) out.push(state);
   }
   return out.sort((a, b) => (b.started_at ?? "").localeCompare(a.started_at ?? ""));
@@ -152,6 +156,59 @@ export function isProcessAlive(pid: number): boolean {
   }
 }
 
+export type ProcessAliveCheck = (pid: number) => boolean;
+
+/** True when both the local gate and its provider-side process are live. */
+export function isTunnelStateLive(
+  state: TunnelState,
+  processAlive: ProcessAliveCheck = isProcessAlive,
+): boolean {
+  if (!processAlive(state.gate_pid)) return false;
+  if (state.provider === "tailscale") return true;
+  const providerPid = state.cloudflared_pid ?? state.provider_pid;
+  return typeof providerPid === "number" && processAlive(providerPid);
+}
+
+function tunnelTargetPort(state: TunnelState): number | null {
+  const value = /^[a-z][a-z\d+.-]*:\/\//i.test(state.target)
+    ? state.target
+    : `http://${state.target}`;
+  try {
+    const url = new URL(value);
+    if (url.port) return Number.parseInt(url.port, 10);
+    return url.protocol === "https:" ? 443 : 80;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Newest live tunnel that serves `vhost` on the requested local web port.
+ *
+ * The port alone does not identify a tunnel. Several tunnels can forward to one
+ * upstream port and be told apart only by the Host header they send, and a
+ * server that routes on Host then serves each of them a different site. Picking
+ * by port alone returns whichever such tunnel started last, so a caller that
+ * builds a URL for one site can hand back a host that serves another and every
+ * link 400s. Matching the vhost too keeps the returned tunnel the one that
+ * actually serves the caller's origin.
+ */
+export function findLiveTunnelForOrigin(
+  port: number,
+  vhost: string,
+  root: string = process.cwd(),
+  processAlive: ProcessAliveCheck = isProcessAlive,
+): TunnelState | null {
+  return (
+    listStates(root).find(
+      (state) =>
+        tunnelTargetPort(state) === port &&
+        state.vhost === vhost &&
+        isTunnelStateLive(state, processAlive),
+    ) ?? null
+  );
+}
+
 /**
  * Ensure cloudflared is on PATH or installed at ~/.local/bin/cloudflared.
  * Auto-downloads on Linux; throws on other platforms with brew hint.