harnery 0.0.1 → 0.2.1

package/dist/core/hooks/effects/image-capture.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Image-feed capture: a non-coordination side effect fired from the normalized
+ * `agent-hook` tool handlers (see effects/index.ts for the family rationale).
+ *
+ * When an agent VIEWS an image (Read tool on a `.png`/`.jpg`/…) or PRODUCES one
+ * (a Bash command writes an image file via `harn browse`, `harn image`, `--diff`, …),
+ * we content-address the bytes into `.harnery/images/<sha256>.<ext>` (dedup:
+ * identical bytes collapse to one blob) and emit an `image.captured` event into
+ * the canonical stream. The web image feed (`/images`) groups those events by
+ * hash and streams them live over the existing SSE infra.
+ *
+ * Why this lives at the hook layer: it's the single harness-agnostic chokepoint
+ * that sees every tool call across Claude Code / Cursor / Codex with the full
+ * `tool_input` (file paths) and `tool_response`. No per-command code needed.
+ *
+ * Everything here is best-effort and MUST NOT throw; callers wrap it in
+ * try/catch + logError, matching every other effect.
+ */
+import type { Harness } from "../events/schema.js";
+import type { ParsedPayload } from "../harness/parse.js";
+export interface CaptureContext {
+    eventType: "tool.pre_use" | "tool.post_use";
+    /** The built event data (tool_name, tool_input string, intent, tool_use_id). */
+    data: Record<string, unknown>;
+    /** The full parsed payload, used for the un-clamped command + tool_response. */
+    payload: ParsedPayload | null;
+    instanceId: string;
+    sessionId: string;
+    harness: Harness;
+}
+/**
+ * Inspect one tool event for image references and capture any that resolve to
+ * a real image on disk. Emits zero or more `image.captured` events.
+ */
+export declare function captureImages(coordRoot: string, ctx: CaptureContext): void;
+/**
+ * Prune `.harnery/images/` past a size cap (default 2 GB) and an age cap
+ * (default 30 days), oldest-mtime-first. Fired on session.start next to
+ * scratchJanitor. Pure-fs, fail-soft. Orphaned `image.captured` events whose
+ * blob was pruned render as an "expired" placeholder in the gallery.
+ */
+export declare function imageJanitor(coordRoot: string): void;
+//# sourceMappingURL=image-capture.d.ts.map

package/dist/core/hooks/effects/image-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-capture.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/effects/image-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAoBzD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,cAAc,GAAG,eAAe,CAAC;IAC5C,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,gFAAgF;IAChF,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAUD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CAoC1E;AA2FD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAmDpD"}

package/dist/core/hooks/effects/image-capture.js

@@ -0,0 +1,288 @@
+/**
+ * Image-feed capture: a non-coordination side effect fired from the normalized
+ * `agent-hook` tool handlers (see effects/index.ts for the family rationale).
+ *
+ * When an agent VIEWS an image (Read tool on a `.png`/`.jpg`/…) or PRODUCES one
+ * (a Bash command writes an image file via `harn browse`, `harn image`, `--diff`, …),
+ * we content-address the bytes into `.harnery/images/<sha256>.<ext>` (dedup:
+ * identical bytes collapse to one blob) and emit an `image.captured` event into
+ * the canonical stream. The web image feed (`/images`) groups those events by
+ * hash and streams them live over the existing SSE infra.
+ *
+ * Why this lives at the hook layer: it's the single harness-agnostic chokepoint
+ * that sees every tool call across Claude Code / Cursor / Codex with the full
+ * `tool_input` (file paths) and `tool_response`. No per-command code needed.
+ *
+ * Everything here is best-effort and MUST NOT throw; callers wrap it in
+ * try/catch + logError, matching every other effect.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { emit } from "../events/emit.js";
+/** Raster + vector image extensions the feed accepts. PDF is intentionally
+ * excluded: book renders aren't an "image feed" and don't thumbnail inline. */
+const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "svg"]);
+/** Skip hashing files larger than this; screenshots are tens of KB; a huge
+ * file mentioned in passing isn't worth the read. */
+const MAX_CAPTURE_BYTES = 25 * 1024 * 1024;
+/** A produced image must have been written within this window of the command
+ * finishing, otherwise a path merely *mentioned* in output (an old baseline,
+ * a doc reference) would be captured. Viewed images skip this gate. */
+const PRODUCED_MTIME_WINDOW_MS = 120_000;
+/** Matches image-ish paths in a command string or its output. Deliberately
+ * permissive on the path body (`~`, `@`, `.`, `-`, `/`); existence + ext + the
+ * mtime gate do the real filtering. */
+const IMAGE_PATH_RE = /[\w./~@+-]+\.(?:png|jpe?g|gif|webp|bmp|svg)\b/gi;
+/**
+ * Inspect one tool event for image references and capture any that resolve to
+ * a real image on disk. Emits zero or more `image.captured` events.
+ */
+export function captureImages(coordRoot, ctx) {
+    const imagesDir = join(coordRoot, ".harnery", "images");
+    const cwd = resolveCwd(ctx.payload);
+    const toolName = String(ctx.data.tool_name ?? "");
+    const candidates = ctx.eventType === "tool.pre_use"
+        ? collectViewed(toolName, ctx.data, cwd)
+        : collectProduced(toolName, ctx.payload, cwd);
+    if (candidates.length === 0)
+        return;
+    for (const cand of candidates) {
+        // Never re-capture our own blob store (would loop on Reads of the gallery).
+        if (cand.path.startsWith(`${imagesDir}/`))
+            continue;
+        const captured = captureOne(imagesDir, cand);
+        if (!captured)
+            continue;
+        emit(coordRoot, {
+            event_type: "image.captured",
+            instance_id: ctx.instanceId,
+            session_id: ctx.sessionId,
+            harness: ctx.harness,
+            data: {
+                hash: captured.hash,
+                ext: captured.ext,
+                bytes: captured.bytes,
+                role: cand.role,
+                source_path: canonicalize(coordRoot, cand.path),
+                tool_name: toolName,
+                tool_use_id: ctx.data.tool_use_id,
+                ...(cand.intent ? { intent: cand.intent } : {}),
+                ...(cand.commandHead ? { command_head: cand.commandHead } : {}),
+            },
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        });
+    }
+}
+/** Read tool → the file_path it's about to show (the "agent saw this" signal). */
+function collectViewed(toolName, data, cwd) {
+    if (toolName !== "Read")
+        return [];
+    const input = parseToolInput(data.tool_input);
+    const filePath = input?.file_path;
+    if (typeof filePath !== "string" || !filePath)
+        return [];
+    if (!hasImageExt(filePath))
+        return [];
+    return [
+        {
+            path: toAbsolute(filePath, cwd),
+            role: "viewed",
+            intent: typeof data.intent === "string" ? data.intent : undefined,
+            requireRecentMtime: false,
+        },
+    ];
+}
+/** Bash tool → scan the command + its output for freshly-written image files. */
+function collectProduced(toolName, payload, cwd) {
+    if (toolName !== "Bash")
+        return [];
+    const command = bashCommand(payload);
+    const responseText = stringifyResponse(payload?.tool_response);
+    const commandHead = command ? command.slice(0, 120) : undefined;
+    const seen = new Set();
+    const out = [];
+    for (const text of [command, responseText]) {
+        if (!text)
+            continue;
+        for (const m of text.matchAll(IMAGE_PATH_RE)) {
+            const raw = m[0];
+            const abs = toAbsolute(raw, cwd);
+            if (seen.has(abs))
+                continue;
+            seen.add(abs);
+            out.push({ path: abs, role: "produced", commandHead, requireRecentMtime: true });
+        }
+    }
+    return out;
+}
+/**
+ * Validate the candidate on disk, hash it, and copy into the content-addressed
+ * store (skipping the copy when the blob already exists). Returns null when the
+ * candidate doesn't qualify.
+ */
+function captureOne(imagesDir, cand) {
+    let st;
+    try {
+        st = statSync(cand.path);
+    }
+    catch {
+        return null; // path doesn't exist (common for "produced" false-positives)
+    }
+    if (!st.isFile() || st.size === 0 || st.size > MAX_CAPTURE_BYTES)
+        return null;
+    if (cand.requireRecentMtime && Date.now() - st.mtimeMs > PRODUCED_MTIME_WINDOW_MS) {
+        return null; // mentioned but not freshly produced by this command
+    }
+    const ext = extOf(cand.path);
+    if (!ext || !IMAGE_EXTS.has(ext))
+        return null;
+    let bytes;
+    try {
+        bytes = readFileSync(cand.path);
+    }
+    catch {
+        return null;
+    }
+    const hash = createHash("sha256").update(bytes).digest("hex");
+    const dest = join(imagesDir, `${hash}.${ext}`);
+    if (!existsSync(dest)) {
+        try {
+            mkdirSync(imagesDir, { recursive: true });
+            const tmp = `${dest}.tmp.${process.pid}`;
+            writeFileSync(tmp, bytes);
+            renameSync(tmp, dest);
+        }
+        catch {
+            return null; // couldn't store, don't emit a dangling event
+        }
+    }
+    return { hash, ext, bytes: st.size };
+}
+/**
+ * Prune `.harnery/images/` past a size cap (default 2 GB) and an age cap
+ * (default 30 days), oldest-mtime-first. Fired on session.start next to
+ * scratchJanitor. Pure-fs, fail-soft. Orphaned `image.captured` events whose
+ * blob was pruned render as an "expired" placeholder in the gallery.
+ */
+export function imageJanitor(coordRoot) {
+    try {
+        const dir = join(coordRoot, ".harnery", "images");
+        if (!existsSync(dir))
+            return;
+        const maxBytes = envInt("HARNERY_IMAGES_MAX_BYTES", 2 * 1024 * 1024 * 1024);
+        const maxAgeMs = envInt("HARNERY_IMAGES_MAX_AGE_DAYS", 30) * 24 * 60 * 60 * 1000;
+        const now = Date.now();
+        const entries = [];
+        for (const name of readdirSync(dir)) {
+            if (name.endsWith(".tmp") || name.includes(".tmp.")) {
+                // Orphaned temp from a crashed copy; sweep it.
+                rmSync(join(dir, name), { force: true });
+                continue;
+            }
+            const full = join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            entries.push({ path: full, size: st.size, mtimeMs: st.mtimeMs });
+        }
+        // Age cap.
+        let total = 0;
+        const survivors = [];
+        for (const e of entries) {
+            if (now - e.mtimeMs > maxAgeMs) {
+                rmSync(e.path, { force: true });
+                continue;
+            }
+            total += e.size;
+            survivors.push(e);
+        }
+        // Size cap: drop oldest first until under.
+        if (total > maxBytes) {
+            survivors.sort((a, b) => a.mtimeMs - b.mtimeMs);
+            for (const e of survivors) {
+                if (total <= maxBytes)
+                    break;
+                rmSync(e.path, { force: true });
+                total -= e.size;
+            }
+        }
+    }
+    catch {
+        // best-effort
+    }
+}
+/* ── helpers ─────────────────────────────────────────────────────────────── */
+function envInt(name, fallback) {
+    const v = process.env[name];
+    if (!v)
+        return fallback;
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function parseToolInput(raw) {
+    if (typeof raw !== "string")
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The un-clamped Bash command from the raw payload (falls back to clamped). */
+function bashCommand(payload) {
+    const ti = payload?.raw?.tool_input;
+    const cmd = ti?.command;
+    return typeof cmd === "string" ? cmd : "";
+}
+function stringifyResponse(value) {
+    if (value == null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "";
+    }
+}
+function resolveCwd(payload) {
+    const raw = payload?.raw;
+    const cwd = raw?.cwd;
+    return typeof cwd === "string" && cwd ? cwd : process.cwd();
+}
+function hasImageExt(p) {
+    const ext = extOf(p);
+    return !!ext && IMAGE_EXTS.has(ext);
+}
+function extOf(p) {
+    const clean = p.split(/[?#]/)[0] ?? p; // drop any query/fragment
+    const dot = clean.lastIndexOf(".");
+    if (dot < 0)
+        return "";
+    return clean.slice(dot + 1).toLowerCase();
+}
+function toAbsolute(p, cwd) {
+    let path = p;
+    if (path.startsWith("~/")) {
+        const home = process.env.HOME;
+        if (home)
+            path = join(home, path.slice(2));
+    }
+    return isAbsolute(path) ? path : resolve(cwd, path);
+}
+/** Strip the coordRoot prefix so the feed shows repo-relative paths. */
+function canonicalize(coordRoot, p) {
+    if (p.startsWith(`${coordRoot}/`))
+        return p.slice(coordRoot.length + 1);
+    return p;
+}

package/dist/core/hooks/effects/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Non-coordination side effects fired from the normalized `agent-hook` handlers.
+ *
+ * These are DELIBERATELY outside the agent-coord path: sounds, scratch
+ * lifecycle, session telemetry, presence detection. They used to live in
+ * per-harness bash adapters. Per the directive ("use the normalized hooks; if
+ * they aren't coordination, implement them outside of coordination") they move
+ * here so the harness configs reference only `agent-hook`, while staying a
+ * distinct concern from the coordination logic in cli.ts / agent-coord.
+ *
+ * Everything here is best-effort: it never throws and never blocks the hook on a
+ * slow dependency (telemetry runs detached).
+ */
+export type { CaptureContext } from "./image-capture.js";
+export { captureImages, imageJanitor } from "./image-capture.js";
+/**
+ * Play a notification sound via the cross-platform utility
+ * (afplay on macOS, powershell.exe on WSL). The
+ * utility backgrounds the actual player, so this returns fast. Rate-limiting
+ * lives in the utility, keyed on CLAUDE_SOUND_SESSION_ID + the per-event count.
+ * Claude-Code-only today (Cursor has no sounds; Codex's never worked).
+ */
+export declare function playSound(repoRoot: string, soundEvent: string, sessionId: string, maxPlays?: number): void;
+/** Map an agent-hook CLI event name → sound, or null if the event has no sound. */
+export declare function soundForEvent(eventName: string): {
+    sound: string;
+    maxPlays: number;
+} | null;
+/** Prune stale scratch archives + sweep orphans (global, fast). Fire-and-forget. */
+export declare function scratchJanitor(repoRoot: string): void;
+/**
+ * Return the one-line scratch recovery cue for SessionStart, or "" if none.
+ * The caller merges it into the session-start additionalContext (it used to be
+ * a standalone additionalContext emission from the previous scratch-on-start adapter).
+ */
+export declare function scratchRecoveryCue(repoRoot: string): string;
+/** Archive the ending agent's scratchpad. Fire-and-forget. */
+export declare function scratchArchive(repoRoot: string, owner: string): void;
+/**
+ * Sync Claude Code session JSONL → BigQuery (`harn claude-sessions sync`). Lives
+ * in the host CLI (parses Claude Code's own ~/.claude/projects/**\/*.jsonl), so harnery
+ * shells out to the harn binary rather than importing it. Detached + unref'd so a
+ * slow BigQuery round-trip never blocks the hook. Stop-path syncs are rate-
+ * limited inside `harn claude-sessions sync`; SessionEnd forces via env. Caller
+ * gates to the claude-code harness.
+ */
+export declare function syncClaudeSessions(repoRoot: string, force: boolean): void;
+/**
+ * Fire the turn-summary extension (Haiku auto-summary of the turn → heartbeat
+ * `turn_summary`). Detached + unref'd; it makes an Anthropic API call and must
+ * never block the Stop hook. Claude-Code-only. The
+ * script self-guards on ANTHROPIC_API_KEY / curl / jq / matching session.
+ */
+export declare function runTurnSummary(repoRoot: string, owner: string, sessionId: string, transcriptPath: string | undefined): void;
+/** Reset per-turn sound rate-limit counters at the start of a new turn. */
+export declare function resetSoundCounters(sessionId: string): void;
+/**
+ * Update the mobile-vs-office presence file from the user's prompt shape, using
+ * harnery's own presence library in-process: no external script, no host-path
+ * dependency. Claude-Code-only (the heuristic is tuned to CC's user-prompt
+ * payload; Cursor/Codex don't surface comparable prompt text). Fire-and-forget.
+ */
+export declare function detectPresence(prompt: string): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/hooks/effects/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/effects/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAI,GACX,IAAI,CAYN;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW3F;AAOD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAYpE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAkBzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,IAAI,CAqBN;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAa1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOnD"}

package/dist/core/hooks/effects/index.js

@@ -0,0 +1,197 @@
+/**
+ * Non-coordination side effects fired from the normalized `agent-hook` handlers.
+ *
+ * These are DELIBERATELY outside the agent-coord path: sounds, scratch
+ * lifecycle, session telemetry, presence detection. They used to live in
+ * per-harness bash adapters. Per the directive ("use the normalized hooks; if
+ * they aren't coordination, implement them outside of coordination") they move
+ * here so the harness configs reference only `agent-hook`, while staying a
+ * distinct concern from the coordination logic in cli.ts / agent-coord.
+ *
+ * Everything here is best-effort: it never throws and never blocks the hook on a
+ * slow dependency (telemetry runs detached).
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { applyDetection } from "../../../lib/presence.js";
+export { captureImages, imageJanitor } from "./image-capture.js";
+/**
+ * Play a notification sound via the cross-platform utility
+ * (afplay on macOS, powershell.exe on WSL). The
+ * utility backgrounds the actual player, so this returns fast. Rate-limiting
+ * lives in the utility, keyed on CLAUDE_SOUND_SESSION_ID + the per-event count.
+ * Claude-Code-only today (Cursor has no sounds; Codex's never worked).
+ */
+export function playSound(repoRoot, soundEvent, sessionId, maxPlays = 0) {
+    try {
+        const player = join(repoRoot, "scripts", "hooks", "play-sound.sh");
+        if (!existsSync(player))
+            return;
+        spawnSync("bash", [player, soundEvent, String(maxPlays)], {
+            env: { ...process.env, CLAUDE_SOUND_SESSION_ID: sessionId },
+            timeout: 4000,
+            stdio: "ignore",
+        });
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Map an agent-hook CLI event name → sound, or null if the event has no sound. */
+export function soundForEvent(eventName) {
+    switch (eventName) {
+        case "stop":
+            return { sound: "stop", maxPlays: 0 };
+        case "stop-failure":
+            return { sound: "error", maxPlays: 0 };
+        case "sub-agent-start":
+            return { sound: "subagent-start", maxPlays: 3 };
+        default:
+            return null;
+    }
+}
+function harnBin(repoRoot) {
+    const bin = join(repoRoot, "harnery", "bin", "harn");
+    return existsSync(bin) ? bin : null;
+}
+/** Prune stale scratch archives + sweep orphans (global, fast). Fire-and-forget. */
+export function scratchJanitor(repoRoot) {
+    try {
+        const bin = harnBin(repoRoot);
+        if (!bin)
+            return;
+        spawnSync("bash", [bin, "scratch", "janitor", "--quiet"], {
+            env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
+            timeout: 5000,
+            stdio: "ignore",
+        });
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Return the one-line scratch recovery cue for SessionStart, or "" if none.
+ * The caller merges it into the session-start additionalContext (it used to be
+ * a standalone additionalContext emission from the previous scratch-on-start adapter).
+ */
+export function scratchRecoveryCue(repoRoot) {
+    try {
+        const bin = harnBin(repoRoot);
+        if (!bin)
+            return "";
+        const r = spawnSync("bash", [bin, "scratch", "recovery-cue"], {
+            env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
+            timeout: 5000,
+            encoding: "utf8",
+        });
+        return (r.stdout ?? "").trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** Archive the ending agent's scratchpad. Fire-and-forget. */
+export function scratchArchive(repoRoot, owner) {
+    try {
+        const bin = harnBin(repoRoot);
+        if (!bin || !owner)
+            return;
+        spawnSync("bash", [bin, "scratch", "archive", "--owner", owner], {
+            env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
+            timeout: 5000,
+            stdio: "ignore",
+        });
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Sync Claude Code session JSONL → BigQuery (`harn claude-sessions sync`). Lives
+ * in the host CLI (parses Claude Code's own ~/.claude/projects/**\/*.jsonl), so harnery
+ * shells out to the harn binary rather than importing it. Detached + unref'd so a
+ * slow BigQuery round-trip never blocks the hook. Stop-path syncs are rate-
+ * limited inside `harn claude-sessions sync`; SessionEnd forces via env. Caller
+ * gates to the claude-code harness.
+ */
+export function syncClaudeSessions(repoRoot, force) {
+    try {
+        const bin = join(repoRoot, "bin", "bp");
+        if (!existsSync(bin))
+            return;
+        const env = {
+            ...process.env,
+            HARNERY_OUTPUT_SESSION_TEE: "0",
+        };
+        if (force)
+            env.HARNERY_CLAUDE_SESSIONS_FORCE = "1";
+        const child = spawn("bash", [bin, "claude-sessions", "sync", "--quiet"], {
+            env,
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Fire the turn-summary extension (Haiku auto-summary of the turn → heartbeat
+ * `turn_summary`). Detached + unref'd; it makes an Anthropic API call and must
+ * never block the Stop hook. Claude-Code-only. The
+ * script self-guards on ANTHROPIC_API_KEY / curl / jq / matching session.
+ */
+export function runTurnSummary(repoRoot, owner, sessionId, transcriptPath) {
+    try {
+        if (!transcriptPath || !existsSync(transcriptPath))
+            return;
+        const script = join(repoRoot, "scripts", "hooks", "harness", "claude_code", "extensions", "turn-summary.sh");
+        if (!existsSync(script))
+            return;
+        const child = spawn("bash", [script, owner, sessionId, transcriptPath], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Reset per-turn sound rate-limit counters at the start of a new turn. */
+export function resetSoundCounters(sessionId) {
+    try {
+        if (!sessionId)
+            return;
+        const dir = os.tmpdir();
+        const prefix = `claude-sounds-${sessionId}-`;
+        for (const f of readdirSync(dir)) {
+            if (f.startsWith(prefix) && f.endsWith(".count")) {
+                rmSync(join(dir, f), { force: true });
+            }
+        }
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Update the mobile-vs-office presence file from the user's prompt shape, using
+ * harnery's own presence library in-process: no external script, no host-path
+ * dependency. Claude-Code-only (the heuristic is tuned to CC's user-prompt
+ * payload; Cursor/Codex don't surface comparable prompt text). Fire-and-forget.
+ */
+export function detectPresence(prompt) {
+    try {
+        if (!prompt)
+            return;
+        applyDetection(prompt);
+    }
+    catch {
+        // best-effort
+    }
+}

package/dist/core/hooks/events/emit.d.ts

@@ -0,0 +1,31 @@
+import { type EventEnvelope, type EventType, type Harness, type Source } from "./schema.js";
+export interface EmitInput<TType extends EventType, TData> {
+    event_type: TType;
+    instance_id: string;
+    session_id: string;
+    harness: Harness;
+    source?: Source;
+    parent_session_id?: string;
+    turn_id?: string;
+    parent_turn_id?: string;
+    ts?: string;
+    data: TData;
+}
+/**
+ * Build a canonical envelope around the caller's `data` payload. Pure;
+ * doesn't touch the filesystem. Useful for tests + replay fixtures.
+ */
+export declare function buildEnvelope<TType extends EventType, TData>(input: EmitInput<TType, TData>): EventEnvelope<TType, TData>;
+/**
+ * Append one canonical event to `.harnery/events.ndjson` under a file lock.
+ * Append-only, one JSON object per line, lock-serialized.
+ *
+ * Synchronous because hooks are short-lived processes: we want the append to
+ * land before the binary exits, and async/await across a tiny write is just
+ * latency for no benefit.
+ *
+ * Returns the envelope so callers can chain off it (debug logs, post-emit
+ * verdict requests).
+ */
+export declare function emit<TType extends EventType, TData>(coordRoot: string, input: EmitInput<TType, TData>): EventEnvelope<TType, TData>;
+//# sourceMappingURL=emit.d.ts.map

package/dist/core/hooks/events/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/events/emit.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,OAAO,EAEZ,KAAK,MAAM,EACZ,MAAM,aAAa,CAAC;AAQrB,MAAM,WAAW,SAAS,CAAC,KAAK,SAAS,SAAS,EAAE,KAAK;IACvD,UAAU,EAAE,KAAK,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,KAAK,CAAC;CACb;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,SAAS,SAAS,EAAE,KAAK,EAC1D,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,GAC7B,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,CAe7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,KAAK,SAAS,SAAS,EAAE,KAAK,EACjD,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,GAC7B,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,CAqC7B"}