harnery 0.34.1 → 0.36.0

package/src/commands/tunnel.ts

@@ -1,17 +1,15 @@
+import { type ChildProcess, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 
-// Inline cachePath; see lib/tunnel/state.ts for rationale.
-function cachePath(tool: string, filename: string): string {
-  const dir = resolve(process.cwd(), ".cache", tool);
-  return resolve(dir, filename);
-}
-
-import { type ChildProcess, spawn, spawnSync } from "node:child_process";
-import { existsSync, openSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-
 import { resolveBinName } from "../core/config.ts";
+import {
+  processLogDestination,
+  runRotatingProcessSync,
+  spawnRotatingProcess,
+} from "../core/storage/process-log.ts";
 import {
   clearState,
   DEFAULT_INSTANCE,
@@ -79,6 +77,27 @@ interface LogsOpts {
   provider?: boolean;
 }
 
+export function tunnelLogDestinations(
+  name: string,
+  provider: TunnelProvider,
+  env: NodeJS.ProcessEnv = process.env,
+  root = process.cwd(),
+): { gate: string; provider: string } {
+  const destination = (filename: string) =>
+    processLogDestination({
+      coord_root: root,
+      project_root: root,
+      family_id: "tunnel-process-log",
+      filename,
+      legacy_path: resolve(root, ".cache", "tunnel", filename),
+      env,
+    });
+  return {
+    gate: destination(gateLogFile(name)),
+    provider: destination(providerLogFile(name, provider)),
+  };
+}
+
 /**
  * Validate + normalize an instance name. Names become filename fragments
  * (state-<name>.json) and pgrep patterns, so they're restricted to a safe
@@ -348,7 +367,6 @@ function runTailscaleShare(
   httpsPort: number,
   logPath: string,
 ): void {
-  const fd = openSync(logPath, "a");
   const args = [
     tailscaleCommand(mode),
     "--bg",
@@ -357,31 +375,36 @@ function runTailscaleShare(
     `--set-path=${path}`,
     targetUrl,
   ];
-  const r = spawnSync("tailscale", args, {
-    stdio: ["ignore", fd, fd],
+  const status = runRotatingProcessSync({
+    path: logPath,
+    command: "tailscale",
+    arguments: args,
   });
-  if (r.status !== 0) {
+  if (status !== 0) {
     emit.error({
       code: "tunnel_tailscale_failed",
       message: `tailscale ${tailscaleCommand(mode)} failed. Check log: ${logPath}`,
     });
-    process.exit(r.status ?? 1);
+    process.exit(status ?? 1);
   }
 }
 
 function stopTailscaleShare(state: TunnelState): boolean {
   if (state.provider !== "tailscale" || !state.tailscale_mode) return true;
   const cmd = tailscaleCommand(state.tailscale_mode);
-  const logPath = cachePath("tunnel", providerLogFile(state.name, "tailscale"));
-  const fd = openSync(logPath, "a");
+  const logPath = tunnelLogDestinations(state.name, "tailscale").provider;
   const args = [
     cmd,
     `--https=${state.tailscale_https_port ?? 443}`,
     `--set-path=${state.tailscale_path ?? "/"}`,
     "off",
   ];
-  const r = spawnSync("tailscale", args, { stdio: ["ignore", fd, fd] });
-  if (r.status !== 0) {
+  const status = runRotatingProcessSync({
+    path: logPath,
+    command: "tailscale",
+    arguments: args,
+  });
+  if (status !== 0) {
     // The gate is torn down and its port is freed for reuse regardless, so a
     // surviving serve/funnel mapping could later re-expose whatever next binds
     // that port. Surface it loudly so the operator can clear it by hand.
@@ -432,26 +455,22 @@ interface GateSpawnOpts {
  * re-reads — that snapshot is precisely why `reload` has to exist.
  */
 function spawnGate(o: GateSpawnOpts): ChildProcess {
-  const gateFd = openSync(o.gateLogPath, "a");
   // `--name`/`--port` on argv mirror the env vars; they're what makes the gate
   // process distinguishable per-instance in `pgrep -f` (see sweepStrays).
-  const gateProc = spawn(
-    "bun",
-    ["run", gateScriptPath(), "--name", o.name, "--port", String(o.gatePort)],
-    {
-      detached: true,
-      stdio: ["ignore", gateFd, gateFd],
-      env: {
-        ...process.env,
-        HARNERY_TUNNEL_ALLOW: o.allowedIps.join(","),
-        HARNERY_TUNNEL_ACCESS:
-          o.provider === "cloudflare" ? "cloudflare-allowlist" : "trusted-local-proxy",
-        HARNERY_TUNNEL_TARGET: o.target,
-        HARNERY_TUNNEL_VHOST: o.vhost,
-        HARNERY_TUNNEL_PORT: String(o.gatePort),
-      },
+  const gateProc = spawnRotatingProcess({
+    path: o.gateLogPath,
+    command: "bun",
+    arguments: ["run", gateScriptPath(), "--name", o.name, "--port", String(o.gatePort)],
+    env: {
+      ...process.env,
+      HARNERY_TUNNEL_ALLOW: o.allowedIps.join(","),
+      HARNERY_TUNNEL_ACCESS:
+        o.provider === "cloudflare" ? "cloudflare-allowlist" : "trusted-local-proxy",
+      HARNERY_TUNNEL_TARGET: o.target,
+      HARNERY_TUNNEL_VHOST: o.vhost,
+      HARNERY_TUNNEL_PORT: String(o.gatePort),
     },
-  );
+  });
   gateProc.unref();
   return gateProc;
 }
@@ -521,10 +540,9 @@ async function up(opts: UpOpts): Promise<void> {
     process.exit(1);
   }
 
-  const gateLogPath = cachePath("tunnel", gateLogFile(name));
-  const providerLogPath = cachePath("tunnel", providerLogFile(name, provider));
-  writeFileSync(gateLogPath, "");
-  writeFileSync(providerLogPath, "");
+  const logPaths = tunnelLogDestinations(name, provider);
+  const gateLogPath = logPaths.gate;
+  const providerLogPath = logPaths.provider;
 
   const gateProc = spawnGate({
     name,
@@ -551,20 +569,16 @@ async function up(opts: UpOpts): Promise<void> {
   let cloudflaredPid: number | undefined;
 
   if (provider === "cloudflare") {
-    const cfdFd = openSync(providerLogPath, "a");
     // Force HTTP/2 transport. The default QUIC transport wedges at precheck on
     // constrained hosts (e.g. WSL, where UDP receive buffers can't grow and ICMP
     // is restricted): the URL prints but the edge never registers. HTTP/2 is
     // marginally higher-latency but registers reliably, which is what a dev
     // tunnel needs.
-    const cfdProc = spawn(
-      cloudflaredBin!,
-      ["tunnel", "--protocol", "http2", "--url", `http://localhost:${gatePort}`],
-      {
-        detached: true,
-        stdio: ["ignore", cfdFd, cfdFd],
-      },
-    );
+    const cfdProc = spawnRotatingProcess({
+      path: providerLogPath,
+      command: cloudflaredBin!,
+      arguments: ["tunnel", "--protocol", "http2", "--url", `http://localhost:${gatePort}`],
+    });
     cfdProc.unref();
     cloudflaredPid = cfdProc.pid!;
 
@@ -788,7 +802,7 @@ export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; mess
     vhost: state.vhost,
     provider: state.provider,
     allowedIps: cfg.allowed_ips,
-    gateLogPath: cachePath("tunnel", gateLogFile(name)),
+    gateLogPath: tunnelLogDestinations(name, state.provider).gate,
   });
 
   await sleep(800);
@@ -952,8 +966,8 @@ function logs(opts: LogsOpts): void {
   const name = resolveName(opts.name);
   const state = readState(name);
   const provider = state?.provider ?? "cloudflare";
-  const which = opts.provider ? providerLogFile(name, provider) : gateLogFile(name);
-  const path = cachePath("tunnel", which);
+  const destinations = tunnelLogDestinations(name, provider);
+  const path = opts.provider ? destinations.provider : destinations.gate;
   if (!existsSync(path)) {
     emit.error({ code: "tunnel_no_log", message: `No log file at ${path}` });
     process.exit(1);

package/src/commands/web.ts

@@ -2,10 +2,17 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createServer } from "node:net";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
+import { ensureSemanticServiceRunning } from "../core/semantic/service.ts";
+import { processLogDestination } from "../core/storage/process-log.ts";
+import {
+  parsePerformanceWindow,
+  readWebPerformanceReport,
+  WEB_PERFORMANCE_LOG,
+} from "../lib/web-performance.ts";
 import { lazyFetchWebRoot, webRunner } from "./web-fetch.ts";
 
 /**
@@ -15,6 +22,7 @@ import { lazyFetchWebRoot, webRunner } from "./web-fetch.ts";
  *   up [--prod]:   start the server (dev mode default; --prod runs next start)
  *   build:         next build (production bundle)
  *   start:         next start (must `harn web build` first)
+ *   performance:   summarize request latency and event-loop delays
  *
  * Launches the Next.js app under `harnery/web/` against the user's current
  * working directory. The web app reads `.harnery/` via `HARNERY_COORD_ROOT`;
@@ -69,6 +77,38 @@ export function nodeOptionsWithHeapCap(mb: number): string | undefined {
   return `${inherited} --max-old-space-size=${mb}`.trim();
 }
 
+/** Preload the request diagnostics hook without replacing Next's HTTP server. */
+export function nodeOptionsWithWebDiagnostics(webDir: string, mb: number): string {
+  const inherited = nodeOptionsWithHeapCap(mb) ?? "";
+  if (inherited.includes("server-performance.mjs")) return inherited;
+  const preload = pathToFileURL(path.join(webDir, "server-performance.mjs")).href;
+  return `${inherited} --import=${preload}`.trim();
+}
+
+export function webPerformanceLogDestination(
+  coordRoot: string,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): string {
+  return processLogDestination({
+    coord_root: coordRoot,
+    family_id: "web-performance-log",
+    filename: "active.jsonl",
+    legacy_path: path.join(coordRoot, ".harnery", "logs", WEB_PERFORMANCE_LOG),
+    env,
+  });
+}
+
+async function startSemanticServiceWithWeb(coordRoot: string, emit: EmitContext): Promise<void> {
+  const result = await ensureSemanticServiceRunning(coordRoot);
+  if (result.state === "started") emit.log("semantic reader · started automatically", "info");
+  if (result.state === "running") emit.log("semantic reader · already running", "info");
+  if (result.state === "paused") emit.log("semantic reader · paused by operator", "info");
+  if (result.state === "inactive") emit.log("semantic reader · waiting for active V3", "info");
+  if (result.state === "unavailable") {
+    emit.log(`semantic reader · unavailable (${result.error ?? "startup failed"})`, "warn");
+  }
+}
+
 /**
  * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
  * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
@@ -193,10 +233,15 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
 
       if (!(await requireAvailablePort(emit, port))) return;
 
+      await startSemanticServiceWithWeb(coordRoot, emit);
+
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
+      const nodeOptions = nodeOptionsWithWebDiagnostics(root, heapMb);
+      const performanceLogPath = webPerformanceLogDestination(coordRoot);
       emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
       emit.log(`files origin · http://harnery-files.localhost:${port}`, "info");
       emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
+      emit.log(`performance log · ${performanceLogPath}`, "info");
       if (heapMb > 0) emit.log(`heap ceiling · ${heapMb} MB`, "info");
 
       const child = spawn(webRunner(), ["run", mode], {
@@ -205,9 +250,9 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
           ...process.env,
           HARNERY_COORD_ROOT: coordRoot,
           HARNERY_WEB_PORT: String(port),
-          ...(nodeOptionsWithHeapCap(heapMb)
-            ? { NODE_OPTIONS: nodeOptionsWithHeapCap(heapMb) as string }
-            : {}),
+          HARNERY_WEB_MODE: mode,
+          HARNERY_WEB_PERFORMANCE_LOG_PATH: performanceLogPath,
+          NODE_OPTIONS: nodeOptions,
         },
         stdio: "inherit",
       });
@@ -281,9 +326,13 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         return;
       }
       if (!(await requireAvailablePort(emit, port))) return;
+      await startSemanticServiceWithWeb(coordRoot, emit);
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
+      const nodeOptions = nodeOptionsWithWebDiagnostics(root, heapMb);
+      const performanceLogPath = webPerformanceLogDestination(coordRoot);
       emit.log(`harn web · http://localhost:${port} (start)`, "info");
       emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
+      emit.log(`performance log · ${performanceLogPath}`, "info");
       if (heapMb > 0) emit.log(`heap ceiling · ${heapMb} MB`, "info");
 
       const child = spawn(webRunner(), ["run", "start"], {
@@ -292,9 +341,9 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
           ...process.env,
           HARNERY_COORD_ROOT: coordRoot,
           HARNERY_WEB_PORT: String(port),
-          ...(nodeOptionsWithHeapCap(heapMb)
-            ? { NODE_OPTIONS: nodeOptionsWithHeapCap(heapMb) as string }
-            : {}),
+          HARNERY_WEB_MODE: "start",
+          HARNERY_WEB_PERFORMANCE_LOG_PATH: performanceLogPath,
+          NODE_OPTIONS: nodeOptions,
         },
         stdio: "inherit",
       });
@@ -309,4 +358,40 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         process.exitCode = code ?? 0;
       });
     });
+
+  web
+    .command("performance")
+    .description("Summarize dashboard request, event-loop, memory, and GC diagnostics")
+    .option("--coord-root <dir>", "Override the coordination root", process.cwd())
+    .option("--since <window>", "Include the last Nm, Nh, or Nd", "1h")
+    .option("--limit <n>", "Keep the N slowest requests and delays", "20")
+    .option("--json", "Emit structured JSON")
+    .action((opts: { coordRoot: string; since: string; limit: string; json?: boolean }) => {
+      const windowMs = parsePerformanceWindow(opts.since);
+      if (windowMs === null) {
+        emit.error({
+          code: "invalid_web_performance_window",
+          message: `invalid --since value '${opts.since}'`,
+          hint: "Use Nm, Nh, or Nd, for example 30m, 1h, or 7d.",
+        });
+        return;
+      }
+      const limit = Number(opts.limit);
+      if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500) {
+        emit.error({
+          code: "invalid_web_performance_limit",
+          message: `invalid --limit value '${opts.limit}'`,
+          hint: "Use an integer from 1 through 500.",
+        });
+        return;
+      }
+      if (opts.json) emit.config({ format: "json" });
+      emit.data(
+        readWebPerformanceReport({
+          root: opts.coordRoot,
+          since: opts.since,
+          limit,
+        }),
+      );
+    });
 }

package/src/commands/work.ts

@@ -6,9 +6,9 @@ import {
   createBuiltinAdapterRegistry,
   probeBinaryVersion,
 } from "../core/adapters/index.ts";
+import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { workflowSubscriptionOnly } from "../core/config.ts";
 import { findCompletedMissionGoverning, reopenGovernorMission } from "../core/governor/index.ts";
-import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
 import type { PolicyIsolation } from "../core/policy/index.ts";
 import { loadPolicyFile } from "../core/policy/index.ts";
 import {
@@ -467,7 +467,7 @@ export function renderAttemptBudget(record: WorkRecord): string {
 }
 
 function withWorkRoot(emit: EmitContext, fn: (coordRoot: string) => void): void {
-  const coordRoot = findCoordRoot();
+  const coordRoot = resolveCoordRoot();
   if (!coordRoot) {
     emit.error({
       code: "no_coord_root",
@@ -488,7 +488,7 @@ async function withWorkRootAsync(
   emit: EmitContext,
   fn: (coordRoot: string) => Promise<void>,
 ): Promise<void> {
-  const coordRoot = findCoordRoot();
+  const coordRoot = resolveCoordRoot();
   if (!coordRoot) {
     emit.error({
       code: "no_coord_root",

package/src/commands/workflow.ts

@@ -7,8 +7,8 @@ import {
   createBuiltinAdapterRegistry,
   probeBinaryVersion,
 } from "../core/adapters/index.ts";
+import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { resolveBinName, workflowSubscriptionOnly } from "../core/config.ts";
-import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
 import type { PolicyIsolation } from "../core/policy/index.ts";
 import { loadPolicyFile } from "../core/policy/index.ts";
 import type { WorkflowApproval, WorkflowApprovalStatus } from "../core/workflow/approvals.ts";
@@ -132,7 +132,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .option("--approval-to <address>", "Address durable ASK requests (default: operator)")
     .option("--json", "Emit the full RunReport as JSON")
     .action(async (script: string, opts: WorkflowRunOpts) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",
@@ -263,7 +263,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .description("Resume a parked workflow after its durable approval has been resolved.")
     .option("--json", "Emit the full RunReport or parked result as JSON")
     .action(async (runId: string, opts: { json?: boolean }) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",
@@ -345,7 +345,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .description("Show validated allocation, verification, integration, and cleanup state.")
     .option("--json", "Emit the validated workspace status as JSON")
     .action(async (runId: string, opts: { json?: boolean }) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",
@@ -374,7 +374,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .description("List validated isolated and shared-compatibility workspace decisions.")
     .option("--json", "Emit workspace inspections as JSON")
     .action(async (opts: { json?: boolean }) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",
@@ -433,7 +433,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .option("--approval-to <address>", "Address a durable policy ASK request")
     .option("--json", "Emit the durable integration plan as JSON")
     .action(async (runId: string, opts: WorkflowIntegrationPrepareOpts) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",
@@ -521,7 +521,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .option("--yes", "Confirm the target-branch mutation")
     .option("--json", "Emit the durable integration receipt as JSON")
     .action(async (runId: string, opts: WorkflowConfirmedMutationOpts) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",
@@ -565,7 +565,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .option("--yes", "Confirm the worktree and provider-branch removal attempt")
     .option("--json", "Emit the cleanup attempt or receipt as JSON")
     .action(async (runId: string, opts: WorkflowConfirmedMutationOpts) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",
@@ -616,7 +616,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .option("--discard", "Throw the uncommitted work away instead of salvaging it")
     .option("--json", "Emit the reclaim preparation and cleanup result as JSON")
     .action(async (runId: string, opts: WorkflowReclaimOpts) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",
@@ -687,7 +687,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .option("--status <status>", "Filter: pending | approved | denied")
     .option("--json", "Emit approval records as JSON")
     .action(async (opts: WorkflowApprovalListOpts) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({ code: "no_coord_root", message: "no .harnery/ coordination root found" });
         process.exit(1);
@@ -725,7 +725,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .description("Show one durable workflow approval.")
     .option("--json", "Emit the approval record as JSON")
     .action(async (approvalId: string, opts: { json?: boolean }) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({ code: "no_coord_root", message: "no .harnery/ coordination root found" });
         process.exit(1);
@@ -755,7 +755,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
       .option("--reason <text>", "Bounded decision reason")
       .option("--json", "Emit the resolved approval as JSON")
       .action(async (approvalId: string, opts: WorkflowApprovalDecisionOpts) => {
-        const coordRoot = findCoordRoot();
+        const coordRoot = resolveCoordRoot();
         if (!coordRoot) {
           emit.error({ code: "no_coord_root", message: "no .harnery/ coordination root found" });
           process.exit(1);
@@ -798,7 +798,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .description("Show the bounded proof packet for a completed workflow run.")
     .option("--json", "Emit the stored proof packet as JSON")
     .action(async (runId: string, opts: WorkflowProofOpts) => {
-      const coordRoot = findCoordRoot();
+      const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
         emit.error({
           code: "no_coord_root",

package/src/core/agents/canonical-emit.ts

@@ -14,6 +14,7 @@ import { spawnSync } from "node:child_process";
 import type { LiveCoordinationObservationV3 } from "../events/v3/live-observation.ts";
 import { coordBinPath } from "./coord-bin.ts";
 import { resolveCoordRoot } from "./coord-client.ts";
+import type { Heartbeat } from "./state/heartbeat-reader.ts";
 
 export type EventV3EmitObservation =
   | LiveCoordinationObservationV3
@@ -96,3 +97,17 @@ export function normalizeAdapter(platform: string | undefined): "claude-code" |
   if (platform === "codex") return "codex";
   return "claude-code";
 }
+
+/** Producer joins use the private native session ID, never its V3 fingerprint. */
+export function nativeSessionIdentity(
+  row: Pick<Heartbeat, "native_session_id" | "session_id"> | null | undefined,
+  fallback: string,
+): string {
+  if (row?.native_session_id) return row.native_session_id;
+  // A projection-only row carries the privacy-safe canonical session
+  // fingerprint, not the adapter's native session ID needed to join the hook
+  // producer. Until a disposable cache exists, the resolved owner is the only
+  // native identity available to command surfaces.
+  if (row?.session_id && !/^sid_[a-f0-9]{64}$/.test(row.session_id)) return row.session_id;
+  return fallback;
+}

package/src/core/agents/claim-path.ts

@@ -0,0 +1,23 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+/**
+ * Canonical identity for an authority-bearing write claim.
+ *
+ * Workspace paths stay portable and repository-relative. Approved paths
+ * outside the coordination root become resolved absolute paths so a later
+ * release matches whether the caller supplies the stored dot-dot form or the
+ * absolute target. This is lexical identity only; finalization policy owns the
+ * physical containment and symlink checks before a claim is acquired.
+ */
+export function canonicalClaimPath(coordRoot: string, value: string): string {
+  const root = resolve(coordRoot);
+  const absolute = resolve(root, value);
+  const fromRoot = relative(root, absolute);
+  const contained = fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+  if (contained) return portable(fromRoot || ".");
+  return portable(absolute);
+}
+
+function portable(value: string): string {
+  return value.split(sep).join("/");
+}