@wrongstack/core 0.296.4 → 0.298.0

package/dist/hq/kanban-store.d.ts

@@ -1,4 +1,5 @@
 import { type HqKanbanSnapshotPayload } from './protocol.js';
+export declare const MAX_HQ_KANBAN_CACHE_PROJECTS = 32;
 export declare class HqKanbanStore {
     private readonly dirPath;
     private readonly cache;
@@ -11,6 +12,8 @@ export declare class HqKanbanStore {
     private mergeNow;
     drain(): Promise<void>;
     private writer;
+    private setCached;
+    private trimCache;
     private filePath;
 }
 //# sourceMappingURL=kanban-store.d.ts.map

package/dist/hq/persistence/event-log.d.ts

@@ -6,6 +6,31 @@ export interface HqEventLogOptions {
     maxBytes?: number;
     rotateKeepBytes?: number;
 }
+/**
+ * Named presets for the byte cap. The default (no preset) is the 32 MB cap
+ * per HQ Evolution 2026-08 §10.3. Pick a preset when you want to make
+ * the override path explicit in code review.
+ *
+ *   - `'vps8'`    — 8 MB cap, 2 MB retained. Tightest cap for memory-constrained
+ *                    VPS deployments.
+ *   - `'vps32'`   — 32 MB cap, 16 MB retained. Same as the default.
+ *   - `'desktop'` — 64 MB cap, 24 MB retained. The pre-§10.3 default; for
+ *                    workstations with disk to spare.
+ */
+export type HqEventLogPreset = 'vps8' | 'vps32' | 'desktop';
+export declare const HQ_EVENT_LOG_PRESETS: Readonly<Record<HqEventLogPreset, {
+    maxBytes: number;
+    rotateKeepBytes: number;
+}>>;
+/**
+ * Return the byte-cap fields for a named preset. Throws on unknown preset
+ * names so callers get a clear error at construction time rather than
+ * silently falling back to the default.
+ */
+export declare function hqEventLogPresetFields(preset: HqEventLogPreset): {
+    maxBytes: number;
+    rotateKeepBytes: number;
+};
 /**
  * Append-only JSONL event log. Every received event envelope is appended to
  * `events.jsonl`; when the file exceeds `maxLines` it is rotated under a file

package/dist/hq/persistence.d.ts

@@ -33,7 +33,7 @@ import { HqSimpleLog } from './persistence/simple-log.js';
 import { HqSnapshotStore } from './persistence/snapshot-store.js';
 import { HqTimeseriesStore } from './persistence/timeseries-store.js';
 export { HqKanbanStore } from './kanban-store.js';
-export { HqEventLog, type HqEventLogOptions } from './persistence/event-log.js';
+export { HqEventLog, HQ_EVENT_LOG_PRESETS, hqEventLogPresetFields, type HqEventLogOptions, type HqEventLogPreset, } from './persistence/event-log.js';
 export { HqSimpleLog, type HqSimpleLogOptions } from './persistence/simple-log.js';
 export { HqSnapshotStore, type HqSnapshotStoreOptions } from './persistence/snapshot-store.js';
 export { type HqTimeseriesBreakdownEntry, type HqTimeseriesSample, HqTimeseriesStore, type HqTimeseriesStoreOptions, } from './persistence/timeseries-store.js';

package/dist/hq/protocol/browser.d.ts

@@ -1,5 +1,6 @@
 import type { HqAlertMessage, HqEventEnvelope, HqHeartbeatMessage } from './core.js';
 import type { HqCommandAuditEntry } from '../commands.js';
+import type { HqResumeMessage } from './resume.js';
 import type { HqSnapshot } from './session.js';
 export interface HqBrowserSnapshotMessage {
     type: 'hq.snapshot';
@@ -16,5 +17,5 @@ export interface HqBrowserCommandStatusMessage {
     type: 'hq.command_status';
     command: HqCommandAuditEntry;
 }
-export type HqBrowserMessage = HqBrowserSnapshotMessage | HqBrowserEventMessage | HqBrowserCommandStatusMessage | HqAlertMessage | HqHeartbeatMessage;
+export type HqBrowserMessage = HqBrowserSnapshotMessage | HqBrowserEventMessage | HqBrowserCommandStatusMessage | HqResumeMessage | HqAlertMessage | HqHeartbeatMessage;
 //# sourceMappingURL=browser.d.ts.map

package/dist/hq/protocol/client.d.ts

@@ -65,5 +65,22 @@ export interface HqClientCommandAckMessage {
     status: 'accepted' | 'completed' | 'failed' | 'rejected';
     message?: string;
 }
-export type HqClientMessage = HqClientHelloMessage | HqClientEventMessage | HqClientCommandPollMessage | HqClientCommandAckMessage;
+export interface HqClientResumeMessage {
+    type: 'client.resume';
+    /**
+     * Highest `seq` value the client has already received via prior
+     * `client.event` envelopes. The server replies with `hq.resume_gap`
+     * containing the missed envelopes (capped at 1000 / 1 MB) or `hq.snapshot`
+     * if the gap is too large. See `docs/plans/hq-evolution-2026-08.md` §2.5.
+     */
+    lastSeqSeen: number;
+    /**
+     * Optional identity hint. When present, the server uses it to anchor
+     * the resumption to the previous session's state. When absent, the server
+     * falls back to the WebSocket's existing auth context.
+     */
+    clientId?: string;
+    projectId?: string;
+}
+export type HqClientMessage = HqClientHelloMessage | HqClientEventMessage | HqClientCommandPollMessage | HqClientCommandAckMessage | HqClientResumeMessage;
 //# sourceMappingURL=client.d.ts.map

package/dist/hq/protocol/core.d.ts

@@ -1,9 +1,11 @@
 import type { HqClientCapability, HqClientMessage } from './client.js';
 import type { HqQueuedCommand } from './fleet.js';
 import { type HqServerKanbanSnapshotMessage } from './kanban.js';
+import type { HqResumeMessage } from './resume.js';
 import type { HqRedactionPolicy } from './tool.js';
-export declare const HQ_PROTOCOL_VERSION: 1;
-export type HqProtocolVersion = typeof HQ_PROTOCOL_VERSION;
+import { HQ_PROTOCOL_VERSION, type HqEventEnvelope, type HqEventType, type HqProtocolVersion } from './envelope.js';
+export { HQ_PROTOCOL_VERSION };
+export type { HqEventEnvelope, HqEventType, HqProtocolVersion };
 export interface HqWelcomePayload {
     type: 'hq.welcome';
     protocolVersion: HqProtocolVersion;
@@ -11,19 +13,6 @@ export interface HqWelcomePayload {
     acceptedCapabilities: readonly HqClientCapability[];
     redactionPolicy: HqRedactionPolicy;
 }
-export interface HqEventEnvelope<TPayload = unknown> {
-    id: string;
-    type: HqEventType | (string & {});
-    schemaVersion: HqProtocolVersion;
-    timestamp: string;
-    clientId: string;
-    projectId: string;
-    sessionId?: string;
-    runId?: string;
-    seq: number;
-    payload: TPayload;
-}
-export type HqEventType = 'client.hello' | 'client.heartbeat' | 'session.started' | 'session.status' | 'session.usage' | 'tool.started' | 'tool.completed' | 'fleet.snapshot' | 'fleet.event' | 'mailbox.snapshot' | 'mailbox.event' | 'kanban.snapshot' | 'worklist.snapshot' | 'git.snapshot' | 'agent.message' | 'agent.status' | 'session.snapshot' | 'session.transcript' | 'session.ended' | 'brain.event' | 'worktree.event' | 'mcp.health.snapshot' | 'mcp.operation';
 export interface HqUsagePayload {
     inputTokens?: number;
     outputTokens?: number;
@@ -70,7 +59,7 @@ export interface HqServerCommandBatchMessage {
     type: 'hq.command_batch';
     commands: readonly HqQueuedCommand[];
 }
-export type HqServerMessage = HqServerCommandBatchMessage | HqServerKanbanSnapshotMessage | HqWelcomePayload;
+export type HqServerMessage = HqServerCommandBatchMessage | HqServerKanbanSnapshotMessage | HqWelcomePayload | HqResumeMessage;
 /**
  * Discriminated parse result for {@link parseHqFrame}. The `reason` field
  * is only present when `ok` is `false`; consumers should narrow on `ok`

package/dist/hq/protocol/envelope.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HQ protocol envelope primitives — dependency leaf.
+ *
+ * This module is intentionally free of imports from any other HQ protocol
+ * module so that the shared envelope/version contracts can be consumed by
+ * every domain module (`core`, `client`, `session`, `fleet`, `resume`, …)
+ * without creating a module cycle back through `core.ts`.
+ *
+ * `core.ts` re-exports these symbols for backward compatibility; new modules
+ * that only need the envelope shape should import from here directly.
+ *
+ * @module hq/protocol/envelope
+ */
+export declare const HQ_PROTOCOL_VERSION: 1;
+export type HqProtocolVersion = typeof HQ_PROTOCOL_VERSION;
+export type HqEventType = 'client.hello' | 'client.heartbeat' | 'session.started' | 'session.status' | 'session.usage' | 'tool.started' | 'tool.completed' | 'fleet.snapshot' | 'fleet.event' | 'mailbox.snapshot' | 'mailbox.event' | 'kanban.snapshot' | 'worklist.snapshot' | 'git.snapshot' | 'agent.message' | 'agent.status' | 'session.snapshot' | 'session.transcript' | 'session.ended' | 'brain.event' | 'worktree.event' | 'mcp.health.snapshot' | 'mcp.operation' | 'governance.snapshot' | 'peer.rehydrate' | 'peer.lost';
+export interface HqEventEnvelope<TPayload = unknown> {
+    id: string;
+    type: HqEventType | (string & {});
+    schemaVersion: HqProtocolVersion;
+    timestamp: string;
+    clientId: string;
+    projectId: string;
+    sessionId?: string;
+    runId?: string;
+    seq: number;
+    payload: TPayload;
+}
+//# sourceMappingURL=envelope.d.ts.map

package/dist/hq/protocol/governance.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Credential-free, project-scoped governance telemetry published to HQ.
+ * This is deliberately observational: HQ cannot use this payload to stop,
+ * approve, or otherwise control project execution.
+ */
+export type HqGovernanceSignalLevel = 'healthy' | 'notice' | 'warning' | 'unavailable';
+export type HqGovernanceSignalCode = 'attachment_broker_healthy' | 'attachment_broker_initializing' | 'attachment_broker_status_unavailable' | 'attachment_broker_degraded' | 'attachment_broker_audit_unhealthy' | 'attachment_broker_revocation_pending' | 'attachment_broker_stopped' | 'broker_missing' | 'broker_invalid' | 'connection_failed' | 'request_rejected' | 'unexpected_response';
+export interface HqGovernanceSnapshotPayload {
+    readonly schemaVersion: 1;
+    readonly projectId: string;
+    readonly observedAt: string;
+    readonly available: boolean;
+    readonly signal: {
+        readonly level: HqGovernanceSignalLevel;
+        readonly code: HqGovernanceSignalCode;
+        readonly operatorAction: 'none' | 'observe' | 'investigate';
+        readonly executionDisposition: 'continue';
+    };
+    readonly daemon?: {
+        readonly pid: number;
+        readonly startedAt: string;
+    };
+    readonly attachmentBroker?: {
+        readonly state: 'idle' | 'active' | 'retry_wait' | 'stopped';
+        readonly health: 'initializing' | 'healthy' | 'degraded' | 'stopped';
+        readonly consecutiveFailures: number;
+        readonly pendingRevocations: number;
+        readonly auditHealthy: boolean;
+        readonly expiresAt?: string;
+        readonly nextActionAt?: string;
+    } | null;
+}
+export declare function isHqGovernanceSnapshotPayload(value: unknown): value is HqGovernanceSnapshotPayload;
+//# sourceMappingURL=governance.d.ts.map

package/dist/hq/protocol/peer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Peer lifecycle envelopes — broadcast from the HQ server to surviving clients
+ * when a project's leader session terminates. Carries no runnable command by
+ * default; the broadcast is informational. The envelope is piggybacked on
+ * the existing client WS channel via `client.command_poll` (per
+ * `docs/plans/hq-evolution-2026-08.md` §10.1).
+ *
+ * Two event types:
+ *  - `peer.rehydrate` — the project lost its leader AND has at least one
+ *    surviving client. Envelope carries project id, machine id, leader
+ *    client id, reason, and an opaque `rehydrateHint` (≤ 280 chars).
+ *  - `peer.lost` — the project lost its leader AND has no surviving clients.
+ *    Envelope is informational; the server still emits it so the cockpit and
+ *    any future reconnecting client can see the leader is gone.
+ *
+ * Both events are v1-protocol additive (no `protocolVersion: 2` bump required).
+ *
+ * @module hq/protocol/peer
+ */
+export type HqPeerRehydrateReason = 'graceful' | 'crash' | 'heartbeat-timeout' | 'auth-revoked';
+export declare const HQ_PEER_REHYDRATE_REASONS: Set<HqPeerRehydrateReason>;
+/** Maximum length of the opaque `rehydrateHint` field. */
+export declare const HQ_PEER_REHYDRATE_HINT_MAX_CHARS = 280;
+/**
+ * Synthetic `clientId` the HQ server uses on `peer.rehydrate` / `peer.lost`
+ * envelopes. It is *not* a real publisher identity — it identifies the
+ * browser-side cursor bucket the dashboard uses to dedupe / replay peer
+ * lifecycle envelopes across reconnects. Both the server (`hq-server/ws.ts`)
+ * and the browser (`webui-hq`) must agree on this literal; hoisting it here
+ * keeps a single source of truth.
+ */
+export declare const HQ_BROWSER_PEER_RESUME_CLIENT_ID = "__hq_peer__";
+export interface HqPeerRehydratePayload {
+    projectId: string;
+    machineId: string;
+    leaderClientId: string;
+    previousLeaderHandle: string;
+    reason: HqPeerRehydrateReason;
+    detectedAt: string;
+    /** Opaque, project-specific. Client decides what to do with it. */
+    rehydrateHint?: string;
+    /** Optional, only if the previous leader explicitly registered a command. */
+    rehydrateCommandId?: string;
+}
+export interface HqPeerLostPayload {
+    projectId: string;
+    machineId: string;
+    leaderClientId: string;
+    previousLeaderHandle: string;
+    reason: HqPeerRehydrateReason;
+    detectedAt: string;
+}
+export declare function isHqPeerRehydratePayload(x: unknown): x is HqPeerRehydratePayload;
+export declare function isHqPeerLostPayload(x: unknown): x is HqPeerLostPayload;
+//# sourceMappingURL=peer.d.ts.map

package/dist/hq/protocol/project.d.ts

@@ -1,3 +1,4 @@
+import type { HqGovernanceSnapshotPayload } from './governance.js';
 export type HqWorkspaceKind = 'git' | 'directory' | 'unknown';
 export type HqProjectStatus = 'active' | 'idle' | 'stale' | 'error';
 export type HqPathPolicy = 'none' | 'project-relative' | 'redacted' | 'full';
@@ -22,5 +23,7 @@ export interface HqProjectRecord {
     totalCostUsd: number;
     lastActivityAt: string;
     status: HqProjectStatus;
+    /** Latest project-owner advisory. It never grants HQ transition authority. */
+    governance?: HqGovernanceSnapshotPayload;
 }
 //# sourceMappingURL=project.d.ts.map

package/dist/hq/protocol/resume.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Sync ladder — server → client resume envelopes.
+ *
+ * Triggered when a client reconnects after a network interruption and sends
+ * `client.resume { lastSeqSeen }`. The server replies with one of:
+ *  - `hq.resume_gap` — bounded list of missed envelopes from the event log.
+ *  - `hq.snapshot` — full snapshot when the gap is too large (>1000 envelopes
+ *    or >24 h stale) or when the event log cannot serve the gap.
+ *
+ * The envelope is additively v1; existing v1 clients ignore unknown types.
+ *
+ * See `docs/plans/hq-evolution-2026-08.md` §2.5 and §7.
+ *
+ * @module hq/protocol/resume
+ */
+import type { HqEventEnvelope } from './envelope.js';
+/** Maximum envelopes per `hq.resume_gap` reply. */
+export declare const HQ_RESUME_GAP_MAX_ENVELOPES = 1000;
+/** Maximum bytes per `hq.resume_gap` reply (sum of `JSON.stringify(envelope).byteLength`). */
+export declare const HQ_RESUME_GAP_MAX_BYTES = 1048576;
+/** Maximum age of `lastSeqSeen` for which the gap-fill route is acceptable. */
+export declare const HQ_RESUME_GAP_MAX_STALE_MS: number;
+/**
+ * Server-to-client gap-fill envelope. The server reads the unbounded
+ * `HqEventLog` for envelopes with `(clientId, seq) > lastSeqSeen` and
+ * returns them capped at `{HQ_RESUME_GAP_MAX_ENVELOPES}` items and
+ * `{HQ_RESUME_GAP_MAX_BYTES}` bytes. The client is expected to dedupe
+ * on `envelope.id` (already in the `HqEventEnvelope` shape).
+ */
+export interface HqResumeGapMessage {
+    type: 'hq.resume_gap';
+    /** The `lastSeqSeen` the client reported on `client.resume`. */
+    lastSeqSeen: number;
+    /** Envelopes the client missed. Bounded by the limits above. */
+    envelopes: readonly HqEventEnvelope[];
+    /** True when the response was capped; the client should request a snapshot. */
+    truncated: boolean;
+}
+/**
+ * Server-to-client resume indicator. The server uses this to tell the
+ * client why the gap-fill could not be served (e.g. snapshotted instead).
+ */
+export interface HqResumeRejectMessage {
+    type: 'hq.resume_reject';
+    reason: 'gap_too_large' | 'last_seen_too_old' | 'log_unavailable';
+    /** ISO timestamp the server received the resume. */
+    detectedAt: string;
+}
+export type HqResumeMessage = HqResumeGapMessage | HqResumeRejectMessage;
+/**
+ * Returns `true` if `envelope` is a `HqResumeGapMessage` with valid shape.
+ * Defensive against malformed payloads from misbehaving servers.
+ */
+export declare function isHqResumeGapMessage(x: unknown): x is HqResumeGapMessage;
+export declare function isHqResumeRejectMessage(x: unknown): x is HqResumeRejectMessage;
+//# sourceMappingURL=resume.d.ts.map

package/dist/hq/protocol.d.ts

@@ -1,12 +1,15 @@
-export * from './protocol/client.js';
-export * from './protocol/session.js';
-export * from './protocol/mcp.js';
-export * from './protocol/mailbox.js';
-export * from './protocol/fleet.js';
 export * from './protocol/brain.js';
-export * from './protocol/tool.js';
-export * from './protocol/project.js';
 export * from './protocol/browser.js';
-export * from './protocol/kanban.js';
+export * from './protocol/client.js';
 export * from './protocol/core.js';
+export * from './protocol/fleet.js';
+export * from './protocol/governance.js';
+export * from './protocol/kanban.js';
+export * from './protocol/mailbox.js';
+export * from './protocol/mcp.js';
+export * from './protocol/peer.js';
+export * from './protocol/project.js';
+export * from './protocol/resume.js';
+export * from './protocol/session.js';
+export * from './protocol/tool.js';
 //# sourceMappingURL=protocol.d.ts.map