harnery 0.35.0 → 0.36.0

package/dist/core/hooks/resolve/coord-root.js

@@ -1,13 +1,15 @@
-import { resolveCoordRoot } from "../../agents/coord-client.js";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 /**
- * The hooks-side name for THE coordination-root resolution.
+ * Resolve the coordination root from path evidence only.
  *
- * Delegates to `resolveCoordRoot()` so the hooks and the CLI cannot resolve
- * different roots. They used to: this walked up from `CLAUDE_PROJECT_DIR` or
- * cwd while the CLI's `monorepoRoot()` asked git for the superproject first, so
- * with a shell inside a submodule that carries its own `.harnery/`, the CLI's
- * `coord.status_observed` landed in a stream this side never read and rule 1/3
- * blocked every turn.
+ * This path-only resolver deliberately does not inspect live producer state.
+ * Code that reads or writes coordination authority must use
+ * `resolveCoordRoot()` from `agents/coord-client.ts`, which disambiguates
+ * nested coordination roots through the registered session. Keeping the two
+ * responsibilities separate lets configuration and other path-only consumers
+ * avoid loading the event recorder and its contract graph.
  *
  * Resolution precedence (see `resolveCoordRoot` for the full rationale):
  *   1. HARNERY_COORD_ROOT_OVERRIDE — explicit pin (tests, git hooks).
@@ -16,9 +18,88 @@ import { resolveCoordRoot } from "../../agents/coord-client.js";
  *      submodules that may carry a `.harnery/` of their own (or none at all,
  *      e.g. a journal dir under /tmp). The session's coordination home is the
  *      project the adapter opened, not wherever the shell happens to sit.
- *   3. The root that already holds this session's heartbeat.
- *   4. The nearest enclosing `.harnery/`, then a git-derived root.
+ *   3. The nearest enclosing `.harnery/`.
+ *   4. A git-derived root when no `.harnery/` exists yet.
  */
 export function findCoordRoot(start = process.cwd()) {
-    return resolveCoordRoot(start);
+    const rootOverride = process.env.HARNERY_COORD_ROOT_OVERRIDE;
+    if (rootOverride)
+        return rootOverride;
+    const projectDir = process.env.CLAUDE_PROJECT_DIR;
+    if (projectDir) {
+        const fromProject = nearestCoordRoot(projectDir);
+        if (fromProject)
+            return fromProject;
+    }
+    const nearest = nearestCoordRoot(start);
+    if (nearest)
+        return nearest;
+    return gitCoordRoots(start)[0] ?? gitToplevel(start);
 }
+/** Nearest enclosing directory carrying `.harnery/`, or null. */
+export function nearestCoordRoot(start) {
+    return ancestorCoordRoots(start)[0] ?? null;
+}
+/** Every enclosing directory carrying `.harnery/`, nearest first. */
+export function ancestorCoordRoots(start) {
+    const found = [];
+    let dir = resolve(start);
+    while (true) {
+        if (existsSync(join(dir, ".harnery")))
+            found.push(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return found;
+}
+/**
+ * Git-derived roots carrying `.harnery/`, in superproject-first order.
+ *
+ * Spawns use `start` as cwd so a call about another checkout cannot inherit
+ * this process's repository. The common-dir fallback recovers a superproject
+ * from a submodule worktree, where Git reports no direct superproject path.
+ */
+export function gitCoordRoots(start) {
+    const roots = [];
+    const push = (value) => {
+        if (value && existsSync(join(value, ".harnery")) && !roots.includes(value))
+            roots.push(value);
+    };
+    push(gitRevParse(start, "--show-superproject-working-tree"));
+    const common = gitRevParse(start, "--git-common-dir");
+    if (common) {
+        const index = common.indexOf("/.git/modules/");
+        if (index !== -1)
+            push(common.substring(0, index));
+    }
+    push(gitToplevel(start));
+    return roots;
+}
+export function gitToplevel(start) {
+    return gitRevParse(start, "--show-toplevel");
+}
+function gitRevParse(start, flag) {
+    const key = `${start}\0${flag}`;
+    const cached = gitRevParseCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    let value = null;
+    try {
+        // A stale adapter project directory may no longer exist. Treat spawn
+        // failure as no path evidence instead of turning discovery into an error.
+        const result = spawnSync("git", ["rev-parse", flag], {
+            cwd: start,
+            encoding: "utf8",
+        });
+        if (result.status === 0)
+            value = result.stdout.trim() || null;
+    }
+    catch {
+        value = null;
+    }
+    gitRevParseCache.set(key, value);
+    return value;
+}
+const gitRevParseCache = new Map();

package/dist/core/hooks/resolve/owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/owner.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,GAAG,iBAAiB,CAAC;CAC/E,GAAG,IAAI,CA4EP;AA2BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAExF;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBnF"}
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/owner.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,GAAG,iBAAiB,CAAC;CAC/E,GAAG,IAAI,CAgFP;AA2BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAExF;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBnF"}

package/dist/core/hooks/resolve/owner.js

@@ -38,6 +38,11 @@ export function resolveOwner(opts) {
         };
         const childId = value("subagent_id") ?? value("agent_id");
         const sessionId = value("session_id") ?? value("conversation_id");
+        // A payload with one unambiguous session identity needs no projection
+        // lookup. Live-authority tie-breaking matters only when the adapter also
+        // supplies a child candidate that could be stale or belong to the parent.
+        if (sessionId && !childId)
+            return { instance_id: sessionId, source: "payload" };
         const child = childId ? readLiveCoordinationRow(opts.coordRoot, childId) : null;
         const session = sessionId ? readLiveCoordinationRow(opts.coordRoot, sessionId) : null;
         if (child && sessionId && (child.kind === "subagent" || child.session_id === sessionId)) {

package/dist/core/hooks/resolve/transcript.d.ts

@@ -1,3 +1,4 @@
+export declare const ASSISTANT_STATUS_BOX_PREFIX = "\u250C\u2500 agent-";
 /**
  * Scan a CC-style JSONL transcript for the `┌─ agent-` status-box prefix in
  * the most-recent assistant turn. Used by `turn.completed` events to populate
@@ -25,6 +26,13 @@ export declare function scanStatusBoxPresent(transcriptPath: string | undefined)
  * truncated JSON row, which the per-line parse guard skips.
  */
 export declare function scanAssistantTextIncludes(transcriptPath: string | undefined, needle: string): boolean;
+/**
+ * Strict status-box evidence shared by turn telemetry and the Stop-time
+ * continuation fallback. Both inputs are assistant-only surfaces: the JSONL
+ * scanner rejects tool_result rows, while lastAssistantMessage comes directly
+ * from the adapter's completed assistant response.
+ */
+export declare function scanAssistantStatusBoxPresent(transcriptPath: string | undefined, lastAssistantMessage: string | undefined): boolean;
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export declare function scanLatestAssistantText(transcriptPath: string | undefined): string | undefined;
 /**

package/dist/core/hooks/resolve/transcript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/transcript.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,GACb,OAAO,CAiCT;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgB9F;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,OAAO,CAIT;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,CAAA;CAAE,CAAC;AAEpF;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,4BAA4B,CA0B9B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAUrF;AAwDD;4CAC4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd;+EAC2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,qBAAqB,GAAG,SAAS,CA8BnC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAkDpB"}
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/transcript.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,2BAA2B,wBAAc,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,GACb,OAAO,CAiCT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACvC,OAAO,CAKT;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgB9F;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,OAAO,CAIT;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,CAAA;CAAE,CAAC;AAEpF;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,4BAA4B,CA0B9B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAUrF;AAwDD;4CAC4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd;+EAC2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,qBAAqB,GAAG,SAAS,CA8BnC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAkDpB"}

package/dist/core/hooks/resolve/transcript.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { toolResponseMintedSessionName } from "../../agents/session-name-display.js";
+export const ASSISTANT_STATUS_BOX_PREFIX = "┌─ agent-";
 /**
  * Scan a CC-style JSONL transcript for the `┌─ agent-` status-box prefix in
  * the most-recent assistant turn. Used by `turn.completed` events to populate
@@ -77,6 +78,16 @@ export function scanAssistantTextIncludes(transcriptPath, needle) {
     }
     return false;
 }
+/**
+ * Strict status-box evidence shared by turn telemetry and the Stop-time
+ * continuation fallback. Both inputs are assistant-only surfaces: the JSONL
+ * scanner rejects tool_result rows, while lastAssistantMessage comes directly
+ * from the adapter's completed assistant response.
+ */
+export function scanAssistantStatusBoxPresent(transcriptPath, lastAssistantMessage) {
+    return (scanAssistantTextIncludes(transcriptPath, ASSISTANT_STATUS_BOX_PREFIX) ||
+        lastAssistantMessage?.includes(ASSISTANT_STATUS_BOX_PREFIX) === true);
+}
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export function scanLatestAssistantText(transcriptPath) {
     const readablePath = resolveTranscriptPath(transcriptPath);

package/dist/core/inbox/contract.d.ts

@@ -0,0 +1,64 @@
+export declare const HARNERY_INBOX_RECORD_SCHEMA: "harnery.inbox-record/v1";
+export declare const HARNERY_INBOX_STATUS_SCHEMA: "harnery.inbox-status/v1";
+export interface HarneryInboxLimits {
+    max_message_body_bytes: number;
+    max_pending_count: number;
+    max_pending_bytes: number;
+    max_history_bytes: number;
+    max_history_records: number;
+    warning_pressure_ratio: number;
+    max_surface_count: number;
+    max_surface_bytes: number;
+    max_surface_tokens: number;
+    surfaced_grace_ms: number;
+    terminal_grace_ms: number;
+}
+export interface HarneryInboxMessageRecordV1 {
+    schema: typeof HARNERY_INBOX_RECORD_SCHEMA;
+    kind: "message";
+    message_id: string;
+    sender_instance_id: string;
+    sender_display_name: string;
+    recipient_instance_id: string;
+    recipient_display_name: string;
+    created_at: string;
+    body: string;
+    body_bytes: number;
+}
+export interface HarneryInboxSurfacedRecordV1 {
+    schema: typeof HARNERY_INBOX_RECORD_SCHEMA;
+    kind: "surfaced";
+    message_id: string;
+    surfaced_at: string;
+}
+export type HarneryInboxRecordV1 = HarneryInboxMessageRecordV1 | HarneryInboxSurfacedRecordV1;
+export interface HarneryInboxStatusV1 {
+    schema: typeof HARNERY_INBOX_STATUS_SCHEMA;
+    recipient_instance_id: string;
+    pending_count: number;
+    pending_bytes: number;
+    total_history_bytes: number;
+    oldest_pending_at?: string;
+    pressure: "normal" | "warning" | "exhausted";
+    last_surface_at?: string;
+    last_compaction_at?: string;
+}
+export type HarneryInboxCapacityReason = "message_body_limit" | "pending_count_limit" | "pending_bytes_limit" | "history_bytes_limit";
+export declare class HarneryInboxCapacityError extends Error {
+    readonly reason_code: HarneryInboxCapacityReason;
+    readonly current: number;
+    readonly limit: number;
+    constructor(reason_code: HarneryInboxCapacityReason, current: number, limit: number);
+}
+export interface HarneryInboxSurfaceBudget {
+    max_count: number;
+    max_bytes: number;
+    max_tokens: number;
+}
+export interface HarneryInboxSurfaceResult {
+    emitted: readonly HarneryInboxMessageRecordV1[];
+    remaining_pending_count: number;
+    remaining_pending_bytes: number;
+    repeated_after_crash_possible: true;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/core/inbox/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/contract.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,EAAG,yBAAkC,CAAC;AAC9E,eAAO,MAAM,2BAA2B,EAAG,yBAAkC,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,OAAO,2BAA2B,CAAC;IAC3C,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,OAAO,2BAA2B,CAAC;IAC3C,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAAG,2BAA2B,GAAG,4BAA4B,CAAC;AAE9F,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,2BAA2B,CAAC;IAC3C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IAC7C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,0BAA0B,GAClC,oBAAoB,GACpB,qBAAqB,GACrB,qBAAqB,GACrB,qBAAqB,CAAC;AAE1B,qBAAa,yBAA0B,SAAQ,KAAK;IAEhD,QAAQ,CAAC,WAAW,EAAE,0BAA0B;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAFb,WAAW,EAAE,0BAA0B,EACvC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM;CAMzB;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAChD,uBAAuB,EAAE,MAAM,CAAC;IAChC,uBAAuB,EAAE,MAAM,CAAC;IAChC,6BAA6B,EAAE,IAAI,CAAC;CACrC"}

package/dist/core/inbox/contract.js

@@ -0,0 +1,13 @@
+export const HARNERY_INBOX_RECORD_SCHEMA = "harnery.inbox-record/v1";
+export const HARNERY_INBOX_STATUS_SCHEMA = "harnery.inbox-status/v1";
+export class HarneryInboxCapacityError extends Error {
+    reason_code;
+    current;
+    limit;
+    constructor(reason_code, current, limit) {
+        super(`inbox capacity ${reason_code}: ${current}/${limit}; use a managed artifact for larger payloads`);
+        this.reason_code = reason_code;
+        this.current = current;
+        this.limit = limit;
+    }
+}

package/dist/core/inbox/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./contract.js";
+export * from "./lifecycle.js";
+export * from "./service.js";
+export * from "./watcher.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/inbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/core/inbox/index.js

@@ -0,0 +1,4 @@
+export * from "./contract.js";
+export * from "./lifecycle.js";
+export * from "./service.js";
+export * from "./watcher.js";

package/dist/core/inbox/lifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { HarneryInboxLimits, HarneryInboxRecordV1 } from "./contract.js";
+export declare const HARNERY_INBOX_COMPACTION_PLAN_SCHEMA: "harnery.inbox-compaction-plan/v1";
+export type HarneryRecipientLifecycle = "active" | "resumable" | "terminal";
+export interface HarneryInboxCompactionPlan {
+    schema: typeof HARNERY_INBOX_COMPACTION_PLAN_SCHEMA;
+    recipient_instance_id: string;
+    action: "none" | "compact-surfaced" | "prune-terminal";
+    reason_code: "pending_protected" | "active_recipient" | "surfaced_grace" | "terminal_grace" | "eligible";
+    remove_record_count: number;
+    retained_record_count: number;
+    protected_pending_count: number;
+    dry_run: true;
+}
+export declare function planInboxCompaction(input: {
+    recipient_instance_id: string;
+    records: readonly HarneryInboxRecordV1[];
+    lifecycle: HarneryRecipientLifecycle;
+    terminal_at?: string;
+    now: Date;
+    limits: HarneryInboxLimits;
+}): HarneryInboxCompactionPlan;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/core/inbox/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG9E,eAAO,MAAM,oCAAoC,EAAG,kCAA2C,CAAC;AAEhG,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;AAE5E,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,OAAO,oCAAoC,CAAC;IACpD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,gBAAgB,CAAC;IACvD,WAAW,EACP,mBAAmB,GACnB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,UAAU,CAAC;IACf,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,uBAAuB,EAAE,MAAM,CAAC;IAChC,OAAO,EAAE,IAAI,CAAC;CACf;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,SAAS,EAAE,yBAAyB,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,EAAE,kBAAkB,CAAC;CAC5B,GAAG,0BAA0B,CAqD7B"}

package/dist/core/inbox/lifecycle.js

@@ -0,0 +1,41 @@
+import { project } from "./service.js";
+export const HARNERY_INBOX_COMPACTION_PLAN_SCHEMA = "harnery.inbox-compaction-plan/v1";
+export function planInboxCompaction(input) {
+    const projection = project(input.records);
+    const surfacedAt = new Map();
+    for (const record of input.records) {
+        if (record.kind === "surfaced")
+            surfacedAt.set(record.message_id, Date.parse(record.surfaced_at));
+    }
+    const compactableIds = new Set([...surfacedAt]
+        .filter(([, timestamp]) => input.now.getTime() - timestamp >= input.limits.surfaced_grace_ms)
+        .map(([id]) => id));
+    const compactableRecords = input.records.filter((record) => compactableIds.has(record.message_id)).length;
+    if (input.lifecycle === "terminal") {
+        if (projection.pending.length > 0) {
+            return plan(input, "none", "pending_protected", 0, input.records.length, projection.pending.length);
+        }
+        const terminalAt = input.terminal_at ? Date.parse(input.terminal_at) : Number.NaN;
+        if (!Number.isFinite(terminalAt) ||
+            input.now.getTime() - terminalAt < input.limits.terminal_grace_ms) {
+            return plan(input, "none", "terminal_grace", 0, input.records.length, 0);
+        }
+        return plan(input, "prune-terminal", "eligible", input.records.length, 0, 0);
+    }
+    if (compactableRecords === 0) {
+        return plan(input, "none", surfacedAt.size > 0 ? "surfaced_grace" : "active_recipient", 0, input.records.length, projection.pending.length);
+    }
+    return plan(input, "compact-surfaced", "eligible", compactableRecords, input.records.length - compactableRecords, projection.pending.length);
+}
+function plan(input, action, reason_code, remove_record_count, retained_record_count, protected_pending_count) {
+    return {
+        schema: HARNERY_INBOX_COMPACTION_PLAN_SCHEMA,
+        recipient_instance_id: input.recipient_instance_id,
+        action,
+        reason_code,
+        remove_record_count,
+        retained_record_count,
+        protected_pending_count,
+        dry_run: true,
+    };
+}

package/dist/core/inbox/service.d.ts

@@ -0,0 +1,36 @@
+import { type HarneryInboxLimits, type HarneryInboxMessageRecordV1, type HarneryInboxRecordV1, type HarneryInboxStatusV1, type HarneryInboxSurfaceBudget, type HarneryInboxSurfaceResult } from "./contract.js";
+export interface HarneryInboxServiceOptions {
+    coord_root: string;
+    limits: HarneryInboxLimits;
+    now?: () => Date;
+    id?: () => string;
+}
+export interface HarneryInboxSendInput {
+    sender_instance_id: string;
+    sender_display_name: string;
+    recipient_instance_id: string;
+    recipient_display_name: string;
+    body: string;
+}
+export interface HarneryInboxSendReceipt {
+    state: "queued";
+    message_id: string;
+    body_bytes: number;
+    synced: true;
+}
+export declare class HarneryInboxService {
+    #private;
+    constructor(options: HarneryInboxServiceOptions);
+    send(input: HarneryInboxSendInput): HarneryInboxSendReceipt;
+    records(recipientInstanceId: string): HarneryInboxRecordV1[];
+    pending(recipientInstanceId: string): HarneryInboxMessageRecordV1[];
+    status(recipientInstanceId: string): HarneryInboxStatusV1;
+    surface(recipientInstanceId: string, emit: (messages: readonly HarneryInboxMessageRecordV1[]) => Promise<void> | void, budget?: HarneryInboxSurfaceBudget): Promise<HarneryInboxSurfaceResult>;
+}
+export declare function inboxPath(coordRoot: string, recipientInstanceId: string): string;
+export declare function project(records: readonly HarneryInboxRecordV1[]): {
+    pending: HarneryInboxMessageRecordV1[];
+    surfaced: ReadonlySet<string>;
+    lastSurfaceAt?: string;
+};
+//# sourceMappingURL=service.d.ts.map

package/dist/core/inbox/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/service.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,CAAC;CACd;AAED,qBAAa,mBAAmB;;gBAGlB,OAAO,EAAE,0BAA0B;IAK/C,IAAI,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB;IA2C3D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB,EAAE;IAO5D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,2BAA2B,EAAE;IAInE,MAAM,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB;IA0BnD,OAAO,CACX,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAChF,MAAM,GAAE,yBAIP,GACA,OAAO,CAAC,yBAAyB,CAAC;CAoCtC;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,GAAG;IACjE,OAAO,EAAE,2BAA2B,EAAE,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAsBA"}

package/dist/core/inbox/service.js

@@ -0,0 +1,210 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readCrashSafeJsonlFile, updateCrashSafeJsonlFile } from "../storage/durable-history.js";
+import { HARNERY_INBOX_RECORD_SCHEMA, HARNERY_INBOX_STATUS_SCHEMA, HarneryInboxCapacityError, } from "./contract.js";
+export class HarneryInboxService {
+    #options;
+    constructor(options) {
+        validateLimits(options.limits);
+        this.#options = options;
+    }
+    send(input) {
+        const recipient = opaqueId(input.recipient_instance_id, "recipient instance");
+        const bodyBytes = Buffer.byteLength(input.body);
+        const limits = this.#options.limits;
+        if (bodyBytes === 0 || bodyBytes > limits.max_message_body_bytes) {
+            throw new HarneryInboxCapacityError("message_body_limit", bodyBytes, limits.max_message_body_bytes);
+        }
+        const record = {
+            schema: HARNERY_INBOX_RECORD_SCHEMA,
+            kind: "message",
+            message_id: `msg_${this.#options.id?.() ?? randomUUID()}`,
+            sender_instance_id: opaqueId(input.sender_instance_id, "sender instance"),
+            sender_display_name: boundedDisplay(input.sender_display_name),
+            recipient_instance_id: recipient,
+            recipient_display_name: boundedDisplay(input.recipient_display_name),
+            created_at: now(this.#options).toISOString(),
+            body: input.body,
+            body_bytes: bodyBytes,
+        };
+        const path = inboxPath(this.#options.coord_root, recipient);
+        return updateCrashSafeJsonlFile(path, readOptions(limits), (records) => {
+            const projection = project(records);
+            capacityCheck(projection, record, path, limits);
+            return {
+                append: [record],
+                result: {
+                    state: "queued",
+                    message_id: record.message_id,
+                    body_bytes: bodyBytes,
+                    synced: true,
+                },
+            };
+        });
+    }
+    records(recipientInstanceId) {
+        return readCrashSafeJsonlFile(inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")), readOptions(this.#options.limits));
+    }
+    pending(recipientInstanceId) {
+        return project(this.records(recipientInstanceId)).pending;
+    }
+    status(recipientInstanceId) {
+        const recipient = opaqueId(recipientInstanceId, "recipient instance");
+        const path = inboxPath(this.#options.coord_root, recipient);
+        const projection = project(this.records(recipient));
+        const pendingBytes = projection.pending.reduce((sum, record) => sum + record.body_bytes, 0);
+        const ratio = Math.max(projection.pending.length / this.#options.limits.max_pending_count, pendingBytes / this.#options.limits.max_pending_bytes);
+        return {
+            schema: HARNERY_INBOX_STATUS_SCHEMA,
+            recipient_instance_id: recipient,
+            pending_count: projection.pending.length,
+            pending_bytes: pendingBytes,
+            total_history_bytes: existsSync(path) ? statSync(path).size : 0,
+            ...(projection.pending[0] ? { oldest_pending_at: projection.pending[0].created_at } : {}),
+            pressure: ratio >= 1
+                ? "exhausted"
+                : ratio >= this.#options.limits.warning_pressure_ratio
+                    ? "warning"
+                    : "normal",
+            ...(projection.lastSurfaceAt ? { last_surface_at: projection.lastSurfaceAt } : {}),
+        };
+    }
+    async surface(recipientInstanceId, emit, budget = {
+        max_count: this.#options.limits.max_surface_count,
+        max_bytes: this.#options.limits.max_surface_bytes,
+        max_tokens: this.#options.limits.max_surface_tokens,
+    }) {
+        validateSurfaceBudget(budget);
+        const recipient = opaqueId(recipientInstanceId, "recipient instance");
+        const selected = selectOldestFitting(this.pending(recipient), budget);
+        await emit(selected);
+        if (selected.length > 0) {
+            const surfacedAt = now(this.#options).toISOString();
+            updateCrashSafeJsonlFile(inboxPath(this.#options.coord_root, recipient), readOptions(this.#options.limits), (records) => {
+                const stillPending = new Set(project(records).pending.map(({ message_id }) => message_id));
+                return {
+                    append: selected
+                        .filter(({ message_id }) => stillPending.has(message_id))
+                        .map(({ message_id }) => ({
+                        schema: HARNERY_INBOX_RECORD_SCHEMA,
+                        kind: "surfaced",
+                        message_id,
+                        surfaced_at: surfacedAt,
+                    })),
+                    result: undefined,
+                };
+            });
+        }
+        const remaining = this.pending(recipient);
+        return {
+            emitted: selected,
+            remaining_pending_count: remaining.length,
+            remaining_pending_bytes: remaining.reduce((sum, record) => sum + record.body_bytes, 0),
+            repeated_after_crash_possible: true,
+        };
+    }
+}
+export function inboxPath(coordRoot, recipientInstanceId) {
+    const id = opaqueId(recipientInstanceId, "recipient instance");
+    return join(resolve(coordRoot), ".harnery", "inbox", `${id}.jsonl`);
+}
+export function project(records) {
+    const messages = new Map();
+    const surfaced = new Set();
+    let lastSurfaceAt;
+    for (const record of records) {
+        validateRecord(record);
+        if (record.kind === "message") {
+            if (messages.has(record.message_id))
+                throw new Error(`duplicate inbox message ${record.message_id}`);
+            messages.set(record.message_id, record);
+        }
+        else {
+            if (!messages.has(record.message_id))
+                throw new Error(`surfaced marker precedes ${record.message_id}`);
+            surfaced.add(record.message_id);
+            if (!lastSurfaceAt || record.surfaced_at > lastSurfaceAt)
+                lastSurfaceAt = record.surfaced_at;
+        }
+    }
+    return {
+        pending: [...messages.values()].filter(({ message_id }) => !surfaced.has(message_id)),
+        surfaced,
+        ...(lastSurfaceAt ? { lastSurfaceAt } : {}),
+    };
+}
+function selectOldestFitting(pending, budget) {
+    const selected = [];
+    let bytes = 0;
+    let tokens = 0;
+    for (const record of pending) {
+        const recordTokens = Math.ceil(record.body_bytes / 4);
+        if (selected.length >= budget.max_count ||
+            bytes + record.body_bytes > budget.max_bytes ||
+            tokens + recordTokens > budget.max_tokens) {
+            break;
+        }
+        selected.push(record);
+        bytes += record.body_bytes;
+        tokens += recordTokens;
+    }
+    return selected;
+}
+function capacityCheck(projection, record, path, limits) {
+    const pendingBytes = projection.pending.reduce((sum, item) => sum + item.body_bytes, 0);
+    if (projection.pending.length + 1 > limits.max_pending_count) {
+        throw new HarneryInboxCapacityError("pending_count_limit", projection.pending.length, limits.max_pending_count);
+    }
+    if (pendingBytes + record.body_bytes > limits.max_pending_bytes) {
+        throw new HarneryInboxCapacityError("pending_bytes_limit", pendingBytes, limits.max_pending_bytes);
+    }
+    const nextHistoryBytes = (existsSync(path) ? statSync(path).size : 0) + Buffer.byteLength(`${JSON.stringify(record)}\n`);
+    if (nextHistoryBytes > limits.max_history_bytes) {
+        throw new HarneryInboxCapacityError("history_bytes_limit", nextHistoryBytes, limits.max_history_bytes);
+    }
+}
+function readOptions(limits) {
+    return {
+        max_record_bytes: Math.max(limits.max_message_body_bytes * 2, 4_096),
+        max_records: limits.max_history_records,
+    };
+}
+function now(options) {
+    return options.now?.() ?? new Date();
+}
+function opaqueId(value, field) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value))
+        throw new Error(`invalid ${field} id`);
+    return value;
+}
+function boundedDisplay(value) {
+    const result = value.trim();
+    if (result.length === 0 || Buffer.byteLength(result) > 256)
+        throw new Error("invalid display name");
+    return result;
+}
+function validateRecord(record) {
+    if (record.schema !== HARNERY_INBOX_RECORD_SCHEMA)
+        throw new Error("unknown inbox record schema");
+    if (record.kind === "message" && Buffer.byteLength(record.body) !== record.body_bytes) {
+        throw new Error(`inbox message ${record.message_id} has invalid body_bytes`);
+    }
+}
+function validateLimits(limits) {
+    for (const [field, value] of Object.entries(limits)) {
+        if (field === "warning_pressure_ratio")
+            continue;
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error(`invalid inbox limit ${field}`);
+    }
+    if (limits.warning_pressure_ratio <= 0 || limits.warning_pressure_ratio >= 1) {
+        throw new Error("warning_pressure_ratio must be between zero and one");
+    }
+}
+function validateSurfaceBudget(budget) {
+    for (const value of Object.values(budget)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error("invalid inbox surface budget");
+    }
+}

package/dist/core/inbox/watcher.d.ts

@@ -0,0 +1,7 @@
+import type { HarneryInboxMessageRecordV1 } from "./contract.js";
+import type { HarneryInboxService } from "./service.js";
+export declare function watchInbox(service: HarneryInboxService, recipientInstanceId: string, options: {
+    signal: AbortSignal;
+    poll_ms?: number;
+}): AsyncGenerator<HarneryInboxMessageRecordV1>;
+//# sourceMappingURL=watcher.d.ts.map

package/dist/core/inbox/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,wBAAuB,UAAU,CAC/B,OAAO,EAAE,mBAAmB,EAC5B,mBAAmB,EAAE,MAAM,EAC3B,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,cAAc,CAAC,2BAA2B,CAAC,CAc7C"}

package/dist/core/inbox/watcher.js

@@ -0,0 +1,26 @@
+export async function* watchInbox(service, recipientInstanceId, options) {
+    const seen = new Set();
+    while (!options.signal.aborted) {
+        try {
+            for (const message of service.pending(recipientInstanceId)) {
+                if (seen.has(message.message_id))
+                    continue;
+                seen.add(message.message_id);
+                yield message;
+            }
+        }
+        catch {
+            // A transient missing or incomplete source is retried; no cursor is advanced.
+        }
+        await delay(options.poll_ms ?? 250, options.signal);
+    }
+}
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}