harnery 0.45.2 → 0.46.1

package/dist/core/presence/mail.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Cross-machine peer messages (ADR 0222). A ping whose recipient lives on
+ * another machine is queued here and published as part of this machine's
+ * mail ref, `refs/harnery/mail/<machine>`, on the same origin the presence
+ * refs use. Each machine writes only its own ref, so force-pushing it never
+ * races another writer.
+ *
+ * The ref is a parentless commit whose message is one JSON blob:
+ *   outbox — messages this machine sent that the recipient machine has not
+ *            acknowledged yet;
+ *   acks   — ids of messages this machine imported from other machines.
+ *
+ * The recipient machine imports envelopes addressed to it into the ordinary
+ * per-instance inbox (keeping the sender's message id, so a re-import is a
+ * no-op) and acknowledges them in its own ref. The sender drops an
+ * acknowledged message from its outbox; the recipient stops acknowledging
+ * once the sender's ref no longer lists it. Delivery is therefore
+ * at-least-once into a deduplicating inbox.
+ *
+ * Local state is one append-only log, `.harnery/mail/log.jsonl`, updated
+ * under the durable-history lease so concurrent hooks on one machine agree.
+ * Repo access is the trust boundary, exactly as for presence: anyone who can
+ * push to origin can publish a mail ref.
+ */
+import type { HarneryInboxService } from "../inbox/service.js";
+export declare const HARNERY_MAIL_ENVELOPE_SCHEMA: "harnery.mail-envelope/v1";
+/** An unacknowledged message stops being offered after this long. */
+export declare const MAIL_TTL_MS: number;
+export interface HarneryMailEnvelopeV1 {
+    schema: typeof HARNERY_MAIL_ENVELOPE_SCHEMA;
+    message_id: string;
+    from_machine: string;
+    to_machine: string;
+    sender_instance_id: string | null;
+    sender_display_name: string;
+    recipient_instance_id: string;
+    recipient_display_name: string;
+    created_at: string;
+    body: string;
+    body_bytes: number;
+}
+export interface HarneryMailBlobV1 {
+    v: 1;
+    machine: string;
+    published_at: string;
+    outbox: HarneryMailEnvelopeV1[];
+    acks: string[];
+}
+/** This machine's mail identity: the same sanitized label as its ref. */
+export declare function mailMachine(): string;
+export interface QueueMailInput {
+    messageId: string;
+    replayOnly?: boolean;
+    toMachine: string;
+    senderInstanceId: string | null;
+    senderName: string;
+    recipientInstanceId: string;
+    recipientName: string;
+    body: string;
+    maxBodyBytes: number;
+    now?: Date;
+}
+export interface HarneryMailQueueReceipt {
+    envelope: HarneryMailEnvelopeV1;
+    state: "queued" | "duplicate";
+    delivery_state: "pending" | "delivered" | "expired";
+    synced: true;
+}
+/** Queue one message for another machine. The caller publishes afterwards. */
+export declare function queueMail(coordRoot: string, input: QueueMailInput): HarneryMailQueueReceipt;
+export type MailPublishResult = {
+    status: "published";
+    machine: string;
+    outbox: number;
+    acks: number;
+    sha: string;
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "error";
+    error: string;
+};
+/**
+ * Publish this machine's mail ref when its content changed, or as a keepalive
+ * while messages are still unacknowledged. A machine that never sent or
+ * received cross-machine mail never creates the ref.
+ */
+export declare function publishMail(coordRoot: string, opts?: {
+    force?: boolean;
+    sync?: boolean;
+    now?: Date;
+}): MailPublishResult;
+export interface MailImportResult {
+    received: number;
+    delivered: number;
+    released: number;
+    rejected: number;
+    published?: MailPublishResult["status"];
+}
+/**
+ * Apply every locally-fetched peer mail ref: import envelopes addressed to
+ * this machine, record acknowledgements of this machine's outbox, and stop
+ * acknowledging messages their sender has dropped. Reads only local refs;
+ * `fetchPresence` brings them in. Never throws.
+ */
+export declare function importMail(coordRoot: string, inbox: HarneryInboxService, opts?: {
+    now?: Date;
+    publish?: boolean;
+    throttle?: boolean;
+}): MailImportResult;
+export interface RemoteSender {
+    instance_id: string;
+    name: string;
+    machine: string;
+}
+/** Senders this machine has received mail from, so a reply can find them even
+ * after their machine's presence goes quiet. */
+export declare function knownRemoteSenders(coordRoot: string): RemoteSender[];
+export interface MailStatus {
+    machine: string;
+    outbox: Array<{
+        message_id: string;
+        to_machine: string;
+        recipient: string;
+        queued_at: string;
+    }>;
+    acks: number;
+    delivered: number;
+    expired: number;
+}
+export declare function mailStatus(coordRoot: string): MailStatus;
+//# sourceMappingURL=mail.d.ts.map

package/dist/core/presence/mail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail.d.ts","sourceRoot":"","sources":["../../../src/core/presence/mail.ts"],"names":[],"mappings":"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"}

package/dist/core/presence/mail.js

@@ -0,0 +1,464 @@
+/**
+ * Cross-machine peer messages (ADR 0222). A ping whose recipient lives on
+ * another machine is queued here and published as part of this machine's
+ * mail ref, `refs/harnery/mail/<machine>`, on the same origin the presence
+ * refs use. Each machine writes only its own ref, so force-pushing it never
+ * races another writer.
+ *
+ * The ref is a parentless commit whose message is one JSON blob:
+ *   outbox — messages this machine sent that the recipient machine has not
+ *            acknowledged yet;
+ *   acks   — ids of messages this machine imported from other machines.
+ *
+ * The recipient machine imports envelopes addressed to it into the ordinary
+ * per-instance inbox (keeping the sender's message id, so a re-import is a
+ * no-op) and acknowledges them in its own ref. The sender drops an
+ * acknowledged message from its outbox; the recipient stops acknowledging
+ * once the sender's ref no longer lists it. Delivery is therefore
+ * at-least-once into a deduplicating inbox.
+ *
+ * Local state is one append-only log, `.harnery/mail/log.jsonl`, updated
+ * under the durable-history lease so concurrent hooks on one machine agree.
+ * Repo access is the trust boundary, exactly as for presence: anyone who can
+ * push to origin can publish a mail ref.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { resolveMachineLabel } from "../../lib/machine.js";
+import { presenceEnabled } from "../config.js";
+import { HARNERY_INBOX_RECORD_SCHEMA, HarneryInboxCapacityError, HarneryInboxMessageConflictError, HarneryInboxMessageHistoryMissingError, } from "../inbox/contract.js";
+import { readCrashSafeJsonlFile, updateCrashSafeJsonlFile } from "../storage/durable-history.js";
+import { hasOrigin, MAIL_REF_PREFIX, pushMachineRef, readMachineRefs, sanitizeRefComponent, writePresenceCommit, } from "./git.js";
+export const HARNERY_MAIL_ENVELOPE_SCHEMA = "harnery.mail-envelope/v1";
+const MAIL_LOG_SCHEMA = "harnery.mail-log/v1";
+/** An unacknowledged message stops being offered after this long. */
+export const MAIL_TTL_MS = 14 * 24 * 60 * 60_000;
+/** While a message is still unacknowledged, re-push at least this often, so a
+ * detached push that failed heals without anyone noticing. */
+const MAIL_KEEPALIVE_SECS = 600;
+const MAX_OUTBOX = 100;
+/** Hook-driven imports run at most this often (the presence fetch is 60s). */
+const IMPORT_INTERVAL_SECS = 30;
+const MAX_LOG_RECORDS = 20_000;
+const MAX_LOG_RECORD_BYTES = 16_384;
+/** This machine's mail identity: the same sanitized label as its ref. */
+export function mailMachine() {
+    return sanitizeRefComponent(resolveMachineLabel());
+}
+function mailDir(coordRoot) {
+    return join(coordRoot, ".harnery", "mail");
+}
+function logPath(coordRoot) {
+    return join(mailDir(coordRoot), "log.jsonl");
+}
+const LOG_OPTIONS = { max_record_bytes: MAX_LOG_RECORD_BYTES, max_records: MAX_LOG_RECORDS };
+function stamp(now) {
+    return now.toISOString();
+}
+function projectMail(records) {
+    const sent = new Map();
+    const outbound = new Map();
+    const acks = new Map();
+    const imported = new Set();
+    const senders = new Map();
+    let delivered = 0;
+    let expired = 0;
+    for (const record of records) {
+        if (record?.schema !== MAIL_LOG_SCHEMA)
+            continue;
+        switch (record.kind) {
+            case "outbound":
+                outbound.set(record.envelope.message_id, { at: record.at, envelope: record.envelope });
+                sent.set(record.envelope.message_id, {
+                    envelope: record.envelope,
+                    delivery_state: "pending",
+                });
+                break;
+            case "delivered":
+                if (outbound.delete(record.message_id))
+                    delivered++;
+                if (sent.has(record.message_id))
+                    sent.get(record.message_id).delivery_state = "delivered";
+                break;
+            case "expired":
+                if (outbound.delete(record.message_id))
+                    expired++;
+                if (sent.has(record.message_id))
+                    sent.get(record.message_id).delivery_state = "expired";
+                break;
+            case "imported":
+                imported.add(record.message_id);
+                acks.set(record.message_id, { at: record.at, from_machine: record.from_machine });
+                if (record.sender_instance_id) {
+                    senders.set(record.sender_instance_id, {
+                        name: record.sender_display_name,
+                        machine: record.from_machine,
+                        at: record.at,
+                    });
+                }
+                break;
+            case "released":
+                acks.delete(record.message_id);
+                break;
+        }
+    }
+    return { sent, outbox: [...outbound.values()], acks, imported, senders, delivered, expired };
+}
+function readMailLog(coordRoot) {
+    try {
+        return readCrashSafeJsonlFile(logPath(coordRoot), LOG_OPTIONS);
+    }
+    catch {
+        return [];
+    }
+}
+function updateMailLog(coordRoot, update) {
+    mkdirSync(mailDir(coordRoot), { recursive: true });
+    return updateCrashSafeJsonlFile(logPath(coordRoot), LOG_OPTIONS, (records) => update(projectMail(records)));
+}
+/** Queue one message for another machine. The caller publishes afterwards. */
+export function queueMail(coordRoot, input) {
+    if (input.replayOnly !== undefined && typeof input.replayOnly !== "boolean") {
+        throw new Error("invalid replayOnly flag");
+    }
+    if (typeof input.messageId !== "string" ||
+        !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(input.messageId)) {
+        throw new Error("invalid message id");
+    }
+    const bodyBytes = Buffer.byteLength(input.body);
+    if (bodyBytes === 0 || bodyBytes > input.maxBodyBytes) {
+        throw new HarneryInboxCapacityError("message_body_limit", bodyBytes, input.maxBodyBytes);
+    }
+    const now = input.now ?? new Date();
+    const envelope = {
+        schema: HARNERY_MAIL_ENVELOPE_SCHEMA,
+        message_id: input.messageId,
+        from_machine: mailMachine(),
+        to_machine: sanitizeRefComponent(input.toMachine),
+        sender_instance_id: input.senderInstanceId,
+        sender_display_name: input.senderName,
+        recipient_instance_id: input.recipientInstanceId,
+        recipient_display_name: input.recipientName,
+        created_at: stamp(now),
+        body: input.body,
+        body_bytes: bodyBytes,
+    };
+    return updateMailLog(coordRoot, (projection) => {
+        const existing = projection.sent.get(envelope.message_id);
+        if (existing) {
+            const fields = [
+                "from_machine",
+                "to_machine",
+                "sender_instance_id",
+                "sender_display_name",
+                "recipient_instance_id",
+                "recipient_display_name",
+                "body",
+                "body_bytes",
+            ];
+            if (fields.some((field) => existing.envelope[field] !== envelope[field])) {
+                throw new HarneryInboxMessageConflictError(envelope.message_id);
+            }
+            return {
+                result: {
+                    envelope: existing.envelope,
+                    state: "duplicate",
+                    delivery_state: existing.delivery_state,
+                    synced: true,
+                },
+            };
+        }
+        if (input.replayOnly) {
+            throw new HarneryInboxMessageHistoryMissingError(envelope.message_id);
+        }
+        if (projection.outbox.length >= MAX_OUTBOX) {
+            throw new HarneryInboxCapacityError("pending_count_limit", projection.outbox.length, MAX_OUTBOX);
+        }
+        return {
+            append: [{ schema: MAIL_LOG_SCHEMA, kind: "outbound", at: stamp(now), envelope }],
+            result: { envelope, state: "queued", delivery_state: "pending", synced: true },
+        };
+    });
+}
+function statePath(coordRoot) {
+    return join(mailDir(coordRoot), "publish-state.json");
+}
+function readState(coordRoot) {
+    try {
+        return JSON.parse(readFileSync(statePath(coordRoot), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeState(coordRoot, state) {
+    try {
+        mkdirSync(mailDir(coordRoot), { recursive: true });
+        const p = statePath(coordRoot);
+        const tmp = `${p}.tmp.${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(state), "utf8");
+        renameSync(tmp, p);
+    }
+    catch {
+        /* best-effort: the keepalive re-push covers a lost state write */
+    }
+}
+/** Expire stale outbound mail, then return the blob this machine should publish. */
+function currentBlob(coordRoot, now) {
+    const projection = updateMailLog(coordRoot, (p) => {
+        const cutoff = now.getTime() - MAIL_TTL_MS;
+        const stale = p.outbox.filter(({ at }) => Date.parse(at) < cutoff);
+        return {
+            append: stale.map(({ envelope }) => ({
+                schema: MAIL_LOG_SCHEMA,
+                kind: "expired",
+                at: stamp(now),
+                message_id: envelope.message_id,
+            })),
+            result: { ...p, outbox: p.outbox.filter(({ at }) => Date.parse(at) >= cutoff) },
+        };
+    });
+    return {
+        v: 1,
+        machine: mailMachine(),
+        published_at: stamp(now),
+        outbox: projection.outbox.map(({ envelope }) => envelope),
+        acks: [...projection.acks.keys()].sort(),
+    };
+}
+/**
+ * Publish this machine's mail ref when its content changed, or as a keepalive
+ * while messages are still unacknowledged. A machine that never sent or
+ * received cross-machine mail never creates the ref.
+ */
+export function publishMail(coordRoot, opts = {}) {
+    try {
+        if (!presenceEnabled(coordRoot))
+            return { status: "skipped", reason: "disabled" };
+        // A machine that never sent or received cross-machine mail has no log;
+        // the hook path stops here without spawning git.
+        if (!existsSync(logPath(coordRoot)))
+            return { status: "skipped", reason: "no mail" };
+        if (!hasOrigin(coordRoot))
+            return { status: "skipped", reason: "no origin remote" };
+        const now = opts.now ?? new Date();
+        const blob = currentBlob(coordRoot, now);
+        const empty = blob.outbox.length === 0 && blob.acks.length === 0;
+        const hash = createHash("sha256")
+            .update(JSON.stringify([blob.outbox.map((e) => e.message_id), blob.acks]))
+            .digest("hex");
+        const state = readState(coordRoot);
+        if (!opts.force) {
+            if (empty && (state.empty ?? true))
+                return { status: "skipped", reason: "nothing to carry" };
+            const pushedAt = Date.parse(state.pushed_at ?? "");
+            const sincePush = Number.isFinite(pushedAt)
+                ? (now.getTime() - pushedAt) / 1000
+                : Number.POSITIVE_INFINITY;
+            if (state.hash === hash && (blob.outbox.length === 0 || sincePush < MAIL_KEEPALIVE_SECS)) {
+                return { status: "skipped", reason: "unchanged" };
+            }
+        }
+        const sha = writePresenceCommit(coordRoot, JSON.stringify(blob));
+        if (!sha)
+            return { status: "error", error: "commit-tree failed" };
+        const push = pushMachineRef(coordRoot, MAIL_REF_PREFIX, blob.machine, sha, {
+            sync: opts.sync,
+        });
+        if (!push.ok)
+            return { status: "error", error: push.error ?? "push failed" };
+        writeState(coordRoot, { hash, pushed_at: stamp(now), empty });
+        return {
+            status: "published",
+            machine: blob.machine,
+            outbox: blob.outbox.length,
+            acks: blob.acks.length,
+            sha,
+        };
+    }
+    catch (e) {
+        return { status: "error", error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function parseBlob(machine, message) {
+    try {
+        const blob = JSON.parse(message);
+        if (blob?.v !== 1 || sanitizeRefComponent(String(blob.machine)) !== machine)
+            return null;
+        if (!Number.isFinite(Date.parse(blob.published_at)))
+            return null;
+        if (!Array.isArray(blob.outbox) || !Array.isArray(blob.acks))
+            return null;
+        return blob;
+    }
+    catch {
+        return null;
+    }
+}
+function validEnvelope(envelope, from, self) {
+    return (envelope?.schema === HARNERY_MAIL_ENVELOPE_SCHEMA &&
+        envelope.from_machine === from &&
+        envelope.to_machine === self &&
+        typeof envelope.message_id === "string" &&
+        typeof envelope.recipient_instance_id === "string" &&
+        typeof envelope.body === "string" &&
+        Buffer.byteLength(envelope.body) === envelope.body_bytes);
+}
+/**
+ * Apply every locally-fetched peer mail ref: import envelopes addressed to
+ * this machine, record acknowledgements of this machine's outbox, and stop
+ * acknowledging messages their sender has dropped. Reads only local refs;
+ * `fetchPresence` brings them in. Never throws.
+ */
+export function importMail(coordRoot, inbox, opts = {}) {
+    const result = { received: 0, delivered: 0, released: 0, rejected: 0 };
+    try {
+        if (!presenceEnabled(coordRoot))
+            return result;
+        const now = opts.now ?? new Date();
+        if (opts.throttle && !importDue(coordRoot, now))
+            return result;
+        const self = mailMachine();
+        const peers = readMachineRefs(coordRoot, MAIL_REF_PREFIX)
+            .filter(({ machine }) => machine !== self)
+            .map(({ machine, message }) => ({ machine, blob: parseBlob(machine, message) }))
+            .filter((peer) => peer.blob !== null);
+        if (peers.length === 0)
+            return result;
+        updateMailLog(coordRoot, (projection) => {
+            const append = [];
+            const pending = new Map(projection.outbox.map((o) => [o.envelope.message_id, o.envelope]));
+            for (const { machine, blob } of peers) {
+                const listed = new Set();
+                for (const envelope of blob.outbox) {
+                    if (!validEnvelope(envelope, machine, self))
+                        continue;
+                    listed.add(envelope.message_id);
+                    if (projection.imported.has(envelope.message_id))
+                        continue;
+                    if (!receive(inbox, envelope, result))
+                        continue;
+                    append.push({
+                        schema: MAIL_LOG_SCHEMA,
+                        kind: "imported",
+                        at: stamp(now),
+                        message_id: envelope.message_id,
+                        from_machine: machine,
+                        sender_instance_id: envelope.sender_instance_id,
+                        sender_display_name: envelope.sender_display_name,
+                    });
+                }
+                for (const id of blob.acks) {
+                    if (pending.get(id)?.to_machine !== machine)
+                        continue;
+                    pending.delete(id);
+                    append.push({
+                        schema: MAIL_LOG_SCHEMA,
+                        kind: "delivered",
+                        at: stamp(now),
+                        message_id: id,
+                    });
+                    result.delivered++;
+                }
+                const publishedAt = Date.parse(blob.published_at);
+                for (const [id, ack] of projection.acks) {
+                    if (ack.from_machine !== machine || listed.has(id))
+                        continue;
+                    if (publishedAt <= Date.parse(ack.at))
+                        continue;
+                    append.push({
+                        schema: MAIL_LOG_SCHEMA,
+                        kind: "released",
+                        at: stamp(now),
+                        message_id: id,
+                    });
+                    result.released++;
+                }
+            }
+            return { append, result: undefined };
+        });
+        if (opts.publish !== false && result.received + result.delivered + result.released > 0) {
+            result.published = publishMail(coordRoot, { now }).status;
+        }
+    }
+    catch {
+        /* mail must never break a hook */
+    }
+    return result;
+}
+/** Hooks import at most once per interval: refs only change when the
+ * throttled presence fetch lands, so checking every prompt spawns git for
+ * nothing. The stamp is touched first so concurrent hooks do not stampede. */
+function importDue(coordRoot, now) {
+    const path = join(mailDir(coordRoot), "import-stamp");
+    try {
+        if ((now.getTime() - statSync(path).mtimeMs) / 1000 < IMPORT_INTERVAL_SECS)
+            return false;
+    }
+    catch {
+        /* no stamp yet → import */
+    }
+    try {
+        mkdirSync(mailDir(coordRoot), { recursive: true });
+        writeFileSync(path, "", "utf8");
+        utimesSync(path, now, now);
+    }
+    catch {
+        /* best-effort */
+    }
+    return true;
+}
+/** Inbox append for one envelope. A full inbox leaves the message unacknowledged
+ * so the sender keeps offering it; a malformed one is acknowledged and dropped. */
+function receive(inbox, envelope, result) {
+    const record = {
+        schema: HARNERY_INBOX_RECORD_SCHEMA,
+        kind: "message",
+        message_id: envelope.message_id,
+        sender_instance_id: envelope.sender_instance_id,
+        sender_display_name: envelope.sender_display_name,
+        sender_machine: envelope.from_machine,
+        recipient_instance_id: envelope.recipient_instance_id,
+        recipient_display_name: envelope.recipient_display_name,
+        created_at: envelope.created_at,
+        body: envelope.body,
+        body_bytes: envelope.body_bytes,
+    };
+    try {
+        if (inbox.receive(record) === "received")
+            result.received++;
+        return true;
+    }
+    catch (error) {
+        if (error instanceof HarneryInboxCapacityError && error.reason_code !== "message_body_limit") {
+            return false;
+        }
+        result.rejected++;
+        return true;
+    }
+}
+/** Senders this machine has received mail from, so a reply can find them even
+ * after their machine's presence goes quiet. */
+export function knownRemoteSenders(coordRoot) {
+    return [...projectMail(readMailLog(coordRoot)).senders].map(([instance_id, s]) => ({
+        instance_id,
+        name: s.name,
+        machine: s.machine,
+    }));
+}
+export function mailStatus(coordRoot) {
+    const projection = projectMail(readMailLog(coordRoot));
+    return {
+        machine: mailMachine(),
+        outbox: projection.outbox.map(({ at, envelope }) => ({
+            message_id: envelope.message_id,
+            to_machine: envelope.to_machine,
+            recipient: envelope.recipient_display_name,
+            queued_at: at,
+        })),
+        acks: projection.acks.size,
+        delivered: projection.delivered,
+        expired: projection.expired,
+    };
+}

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

@@ -265,7 +265,7 @@ export declare const SemanticMeaningV2Schema: import("@sinclair/typebox").TObjec
         evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
     }>>;
     tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-        value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "delivery" | "documentation" | "infrastructure">[]>>;
+        value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "delivery" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "documentation" | "infrastructure">[]>>;
         basis: import("@sinclair/typebox").TLiteral<"model-synthesis" | "prediction">;
         confidence: import("@sinclair/typebox").TLiteral<"low"> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]>;
         evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
@@ -325,7 +325,7 @@ export declare const SemanticModelReplyV2Schema: import("@sinclair/typebox").TOb
             evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
         }>>;
         tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "delivery" | "documentation" | "infrastructure">[]>>;
+            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "delivery" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "documentation" | "infrastructure">[]>>;
             basis: import("@sinclair/typebox").TLiteral<"model-synthesis" | "prediction">;
             confidence: import("@sinclair/typebox").TLiteral<"low"> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]>;
             evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
@@ -391,7 +391,7 @@ export declare function semanticModelReplyV2SchemaFor(expected: {
             evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<string>[]>>;
         }>>;
         tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "delivery" | "documentation" | "infrastructure">[]>>;
+            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "delivery" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "documentation" | "infrastructure">[]>>;
             basis: import("@sinclair/typebox").TLiteral<"model-synthesis" | "prediction">;
             confidence: import("@sinclair/typebox").TLiteral<"low"> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]>;
             evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<string>[]>>;
@@ -516,7 +516,7 @@ export declare const SemanticAcceptedReadModelV2Schema: import("@sinclair/typebo
             evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
         }>>;
         tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "delivery" | "documentation" | "infrastructure">[]>>;
+            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "delivery" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "documentation" | "infrastructure">[]>>;
             basis: import("@sinclair/typebox").TLiteral<"model-synthesis" | "prediction">;
             confidence: import("@sinclair/typebox").TLiteral<"low"> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]>;
             evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
@@ -844,7 +844,7 @@ export declare const SemanticAgentReadModelV2Schema: import("@sinclair/typebox")
             evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
         }>>;
         tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "delivery" | "documentation" | "infrastructure">[]>>;
+            value: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "research" | "delivery" | "waiting" | "planning" | "implementation" | "verification" | "coordination" | "documentation" | "infrastructure">[]>>;
             basis: import("@sinclair/typebox").TLiteral<"model-synthesis" | "prediction">;
             confidence: import("@sinclair/typebox").TLiteral<"low"> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]> | import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"low">]>;
             evidence_event_ids: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;

package/dist/core/storage/modes.d.ts

@@ -1,5 +1,9 @@
 /** The sharing mode for this process, resolved once. Tests reset it with `resetStorageSharing`. */
 export declare function stateSharing(): "private" | "group";
+/** Directory mode for personal state in the user's home, which never follows project sharing. */
+export declare const PERSONAL_DIR_MODE = 448;
+/** File mode for personal state in the user's home, such as a per-install secret key. */
+export declare const PERSONAL_FILE_MODE = 384;
 export declare function resetStorageSharing(): void;
 /**
  * Mode for a directory of project state. Group mode includes setgid: Harnery chmods directories

package/dist/core/storage/modes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modes.d.ts","sourceRoot":"","sources":["../../../src/core/storage/modes.ts"],"names":[],"mappings":"AAgBA,mGAAmG;AACnG,wBAAgB,YAAY,IAAI,SAAS,GAAG,OAAO,CASlD;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wCAAwC;AACxC,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}
+{"version":3,"file":"modes.d.ts","sourceRoot":"","sources":["../../../src/core/storage/modes.ts"],"names":[],"mappings":"AAgBA,mGAAmG;AACnG,wBAAgB,YAAY,IAAI,SAAS,GAAG,OAAO,CASlD;AAED,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,MAAQ,CAAC;AAEvC,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,MAAQ,CAAC;AAExC,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wCAAwC;AACxC,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}