@wrongstack/core 0.284.1 → 0.286.0

package/dist/hq/publisher.d.ts

@@ -0,0 +1,181 @@
+import type { Logger } from '../types/logger.js';
+import type { Mailbox, MailboxAgentStatus, MailboxMessage } from '../coordination/mailbox-types.js';
+import { type HqMailboxEventAction, type HqMailboxSnapshotOptions } from './mailbox-mapper.js';
+import { type HqClientCapability, type HqClientIdentity, type HqEventEnvelope, type HqEventType, type HqFleetSnapshotPayload, type HqMailboxEventPayload, type HqMailboxSnapshotPayload, type HqProjectIdentity, type HqQueuedCommand, type HqRedactionPolicy, type HqSessionEndedPayload, type HqSessionSnapshotPayload, type HqTranscriptAppendPayload } from './protocol.js';
+export interface HqSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener?(type: 'open' | 'close' | 'error' | 'message', listener: (event: unknown) => void): void;
+    removeEventListener?(type: 'open' | 'close' | 'error' | 'message', listener: (event: unknown) => void): void;
+    on?(type: 'open' | 'close' | 'error' | 'message', listener: (event: unknown) => void): void;
+    off?(type: 'open' | 'close' | 'error' | 'message', listener: (event: unknown) => void): void;
+}
+export type HqSocketFactory = (url: string, init: {
+    token?: string;
+}) => HqSocketLike;
+export interface HqPublisherCommandResult {
+    commandId: string;
+    status: 'accepted' | 'completed' | 'failed' | 'rejected';
+    message?: string;
+}
+export type HqPublisherCommandHandler = (command: HqQueuedCommand) => void | HqPublisherCommandResult | Promise<void | HqPublisherCommandResult>;
+export interface HqPublisherOptions {
+    url: string;
+    token?: string;
+    client: HqClientIdentity;
+    project: HqProjectIdentity;
+    capabilities?: readonly HqClientCapability[];
+    socketFactory?: HqSocketFactory;
+    now?: () => string;
+    idFactory?: () => string;
+    reconnect?: boolean;
+    reconnectBaseMs?: number;
+    reconnectMaxMs?: number;
+    maxQueuedMessages?: number;
+    redactionPolicy?: Partial<HqRedactionPolicy>;
+    commandPollIntervalMs?: number;
+    commandPollLimit?: number;
+    onCommand?: HqPublisherCommandHandler;
+    /**
+     * Local auto-discovery hook: re-resolve the HQ endpoint before EVERY
+     * connect attempt (e.g. by reading `<hq dataDir>/runtime.json`). Returning
+     * `undefined` means no HQ is currently discoverable — the publisher stays
+     * dormant (events keep queueing, bounded) and re-checks every
+     * {@link HqPublisherOptions.discoveryPollMs}. Because the endpoint is
+     * re-resolved per attempt, an HQ started AFTER this client — or restarted
+     * on a different port, or one that minted its first client token on boot —
+     * is picked up automatically.
+     */
+    resolveEndpoint?: () => {
+        url: string;
+        token?: string | undefined;
+    } | undefined;
+    /** Dormant re-check interval while `resolveEndpoint` yields nothing. Default 5s. */
+    discoveryPollMs?: number;
+    /**
+     * Application-level heartbeat interval for the `/ws/client` connection.
+     * The HQ server evicts silent sockets, so this must be comfortably below
+     * the server-side client TTL even when no command handler is installed.
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Diagnostic sink for the one-time consecutive-connect-failure warning.
+     * The publisher is otherwise deliberately silent (dormant queueing), which
+     * made auth failures invisible: a token the server rejects — e.g. a wrong
+     * `WRONGSTACK_HQ_TOKEN` against a remote HQ — looked exactly like "HQ not
+     * running". Defaults to a single structured `console.warn` line.
+     */
+    warn?: (message: string) => void;
+    /** Logger for structured events. When provided, the `warn` callback is derived from it. */
+    logger?: Logger | undefined;
+}
+export interface HqPublishEventOptions {
+    type: HqEventType | (string & {});
+    payload: unknown;
+    sessionId?: string;
+    runId?: string;
+    timestamp?: string;
+    /**
+     * Per-string redaction cap override. Defaults to the generic 500-char
+     * summary cap; chat-transcript event types (`session.transcript`,
+     * `agent.message`) automatically get {@link HQ_TRANSCRIPT_TEXT_CAP} so
+     * full chat history survives when `rawContent` is enabled.
+     */
+    maxSummaryLength?: number;
+}
+export declare class HqPublisher {
+    private readonly options;
+    private readonly socketFactory;
+    private readonly now;
+    private readonly idFactory;
+    private readonly capabilities;
+    private readonly reconnect;
+    private readonly reconnectBaseMs;
+    private readonly reconnectMaxMs;
+    private readonly maxQueuedMessages;
+    private readonly resolvedRedactionPolicy;
+    private readonly logger;
+    private socket;
+    private seq;
+    private queue;
+    private stopped;
+    private reconnectAttempt;
+    private connectWarningEmitted;
+    private lastAttempt;
+    private reconnectTimer;
+    private commandPollTimer;
+    private heartbeatTimer;
+    private lastCommandId;
+    constructor(options: HqPublisherOptions);
+    connect(): void;
+    close(): void;
+    publishEvent<TPayload>(options: HqPublishEventOptions & {
+        payload: TPayload;
+    }): HqEventEnvelope<TPayload>;
+    publishMailboxSnapshot(mailbox: Pick<Mailbox, 'query' | 'getAgentStatuses'>, options: Omit<HqMailboxSnapshotOptions, 'redactionPolicy'> & {
+        sessionId?: string;
+        timestamp?: string;
+    }): Promise<HqEventEnvelope<HqMailboxSnapshotPayload>>;
+    publishMailboxEvent(input: {
+        mailboxId: string;
+        action: HqMailboxEventAction;
+        message?: MailboxMessage;
+        agent?: MailboxAgentStatus;
+        summary?: string;
+        previewLength?: number;
+        sessionId?: string;
+        timestamp?: string;
+    }): HqEventEnvelope<HqMailboxEventPayload>;
+    /** The client identity this publisher announced (clientId, kind, machineId, …). */
+    get identity(): HqClientIdentity;
+    /** The project identity this publisher is bound to. */
+    get project(): HqProjectIdentity;
+    /** Effective publisher-side policy applied before any event leaves this process. */
+    get redactionPolicy(): HqRedactionPolicy;
+    /** Publish a live session/terminal snapshot (state + agents). */
+    publishSessionSnapshot(payload: HqSessionSnapshotPayload, opts?: {
+        timestamp?: string;
+    }): HqEventEnvelope<HqSessionSnapshotPayload>;
+    /** Publish an incremental batch of transcript turns for a session. */
+    publishTranscriptAppend(payload: HqTranscriptAppendPayload, opts?: {
+        timestamp?: string;
+    }): HqEventEnvelope<HqTranscriptAppendPayload>;
+    /** Mark a session/terminal as ended. */
+    publishSessionEnded(payload: HqSessionEndedPayload, opts?: {
+        timestamp?: string;
+    }): HqEventEnvelope<HqSessionEndedPayload>;
+    /** Publish a fleet (multi-agent coordinator) snapshot. */
+    publishFleetSnapshot(payload: HqFleetSnapshotPayload, opts?: {
+        sessionId?: string;
+        timestamp?: string;
+    }): HqEventEnvelope<HqFleetSnapshotPayload>;
+    pollCommands(): void;
+    ackCommand(result: HqPublisherCommandResult): void;
+    private createHelloFrame;
+    private sendHelloNow;
+    private sendFrame;
+    private enqueue;
+    /** Batch-dequeue up to 50 frames at a time, yielding to the microtask
+     *  queue between batches so we don't starve the event loop on reconnect. */
+    private flushQueue;
+    private startCommandPolling;
+    private stopCommandPolling;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private publishHeartbeat;
+    private handleServerMessage;
+    private parseServerMessage;
+    private extractMessageData;
+    private handleCommandBatch;
+    private scheduleReconnect;
+    private emitConnectWarning;
+    /**
+     * Dormant re-check while no HQ endpoint is discoverable. Uses a FIXED
+     * interval (not the exponential reconnect backoff): the check is a cheap
+     * local file read, and backing off would delay attaching to an HQ the
+     * user just started — the whole point of auto-discovery.
+     */
+    private scheduleDiscoveryPoll;
+}
+//# sourceMappingURL=publisher.d.ts.map

package/dist/hq/publisher.d.ts.map

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

package/dist/hq/redaction.d.ts

@@ -0,0 +1,30 @@
+import { type HqEventEnvelope, type HqRedactionPolicy } from './protocol.js';
+export interface HqRedactOptions {
+    policy?: Partial<HqRedactionPolicy>;
+    projectRoot?: string;
+    maxSummaryLength?: number;
+}
+export interface HqRedactionResult<T> {
+    value: T;
+    redacted: boolean;
+}
+export declare function resolveHqRedactionPolicy(policy?: Partial<HqRedactionPolicy>): HqRedactionPolicy;
+/**
+ * Apply an operator policy as a one-way privacy clamp. An override can make a
+ * publisher policy stricter, but can never enable raw content or broader path
+ * / tool-argument disclosure than the publisher selected.
+ */
+export declare function tightenHqRedactionPolicy(publisherPolicy: HqRedactionPolicy, operatorPolicy?: Partial<HqRedactionPolicy>): HqRedactionPolicy;
+/**
+ * Scrub a free-text preview field and truncate it to a maximum length so
+ * it is safe to embed in HQ event envelopes and broadcast to browsers
+ * without leaking secrets or running away on unbounded input.
+ *
+ * Returns `undefined` when the input is empty or non-string. Truncation
+ * suffix is `"…[truncated:N]"` where N is the number of dropped chars.
+ */
+export declare function scrubAndTruncateHqPreview(value: unknown, maxLength?: number): string | undefined;
+export declare function redactHqValue<T>(value: T, options?: HqRedactOptions): HqRedactionResult<T>;
+export declare function redactHqEvent<TPayload>(event: HqEventEnvelope<TPayload>, options?: HqRedactOptions): HqRedactionResult<HqEventEnvelope<TPayload>>;
+export declare function summarizeHqToolArgs(value: unknown, options?: HqRedactOptions): unknown;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/hq/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../../src/hq/redaction.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAsEvB,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID,wBAAgB,wBAAwB,CACtC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAClC,iBAAiB,CAKnB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,iBAAiB,EAClC,cAAc,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAC1C,iBAAiB,CA8BnB;AAwDD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,MAAY,GACtB,MAAM,GAAG,SAAS,CAGpB;AAyDD,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAE,eAAoB,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAQ9F;AAED,wBAAgB,aAAa,CAAC,QAAQ,EACpC,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,EAChC,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAO9C;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CA4B1F"}

package/dist/hq/session-bridge.d.ts

@@ -0,0 +1,29 @@
+import type { EventBus, TrackedAgentSnapshot } from '../kernel/events.js';
+import type { HqPublisher } from './publisher.js';
+export interface SessionTelemetryBridgeOptions {
+    publisher: HqPublisher;
+    /** Local bus carrying `session.agents_updated`. When omitted, snapshots
+     * still publish (with empty/last-known agents) and the transcript still
+     * streams from disk. */
+    events?: EventBus | undefined;
+    sessionId: string;
+    projectRoot: string;
+    projectName?: string | undefined;
+    /** Override the global root used to resolve the session JSONL path. */
+    globalRoot?: string | undefined;
+    /** Last-known agents to publish immediately before the next bus update. */
+    initialAgents?: readonly TrackedAgentSnapshot[] | undefined;
+    gitBranch?: string | undefined;
+    startedAt?: string | undefined;
+    /** Snapshot republish interval (also refreshes lastActivity). Default 2500ms. */
+    snapshotIntervalMs?: number | undefined;
+    /** Transcript tail poll interval. Default 1200ms. */
+    transcriptIntervalMs?: number | undefined;
+    now?: (() => string) | undefined;
+}
+/**
+ * Start streaming this surface's session telemetry to HQ. Returns a disposer
+ * that stops both streams and publishes a final `session.ended`.
+ */
+export declare function startSessionTelemetryBridge(opts: SessionTelemetryBridgeOptions): () => void;
+//# sourceMappingURL=session-bridge.d.ts.map

package/dist/hq/session-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-bridge.d.ts","sourceRoot":"","sources":["../../src/hq/session-bridge.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAU1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,WAAW,CAAC;IACvB;;4BAEwB;IACxB,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,SAAS,oBAAoB,EAAE,GAAG,SAAS,CAAC;IAC5D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,qDAAqD;IACrD,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAClC;AA0CD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,6BAA6B,GAAG,MAAM,IAAI,CAqN3F"}

package/dist/hq/tool-bridge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ToolTelemetryBridge — forwards local tool execution events to the HQ
+ * publisher as `tool.started` and `tool.completed` envelopes, so the command
+ * center can surface live tool activity (what's running, durations, success
+ * rates) across every connected machine.
+ *
+ * Sources:
+ *  - `tool.started` (EventBus) → `tool.started` envelope. Raw tool input is
+ *    shaped via {@link summarizeHqToolArgs} according to the active HQ policy.
+ *  - `tool.executed` (EventBus) → `tool.completed` envelope (carries the
+ *    richer post-execution signal: duration, ok/error, output bytes).
+ *
+ * All payload fields are plain serializable data — no closures. The
+ * `tool.started.input` raw args follow the publisher redaction policy before
+ * publishing.
+ *
+ * @module hq/tool-bridge
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { HqEventEnvelope } from './protocol.js';
+import type { HqPublisher } from './publisher.js';
+export interface ToolTelemetryBridgeOptions {
+    /** Local EventBus emitting `tool.started` and `tool.executed` events. */
+    events: EventBus;
+    /** HQ publisher to forward envelopes to. */
+    publisher: HqPublisher;
+    /** Project root for path redaction in tool input summaries. */
+    projectRoot?: string;
+    /** Optional sessionId to tag envelopes with. */
+    sessionId?: string;
+    /** Override `now()` for deterministic tests. */
+    now?: () => string;
+}
+/**
+ * Start forwarding tool execution events to HQ. Returns a disposer that
+ * unsubscribes all listeners — call on shutdown.
+ */
+export declare function startToolTelemetryBridge(opts: ToolTelemetryBridgeOptions): () => void;
+/** Re-export for type-only consumers. */
+export type { HqEventEnvelope };
+//# sourceMappingURL=tool-bridge.d.ts.map

package/dist/hq/tool-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-bridge.d.ts","sourceRoot":"","sources":["../../src/hq/tool-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAmE,MAAM,eAAe,CAAC;AACtH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,0BAA0B;IACzC,yEAAyE;IACzE,MAAM,EAAE,QAAQ,CAAC;IACjB,4CAA4C;IAC5C,SAAS,EAAE,WAAW,CAAC;IACvB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AA0BD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,0BAA0B,GAAG,MAAM,IAAI,CA+DrF;AAWD,yCAAyC;AACzC,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/hq/transcript-mapper.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Transcript mapper — converts raw session JSONL events into the canonical
+ * {@link HqTranscriptEntry} shape used by HQ for full chat-history rendering.
+ *
+ * On-disk reality (see `types/session.ts` + `core/agent-tools.ts`):
+ *   - A tool CALL (with its arguments) is NOT a standalone event — it is a
+ *     `tool_use` content block inside the assistant's `llm_response`.
+ *   - The tool RESULT is a separate `tool_result` event carrying the matching
+ *     `id`.
+ * So we extract each `tool_use` block as a tool entry (args) at the assistant's
+ * position, then merge the later `tool_result` (matched by `id`) INTO that same
+ * entry — giving one box per tool (args + result) in strict chronological order.
+ *
+ * @module hq/transcript-mapper
+ */
+import type { HqTranscriptEntry } from './protocol.js';
+/**
+ * Map a single raw JSONL session event to zero or more transcript entries.
+ * An `llm_response` can yield an assistant text entry PLUS one tool entry per
+ * embedded `tool_use` block.
+ */
+export declare function mapSessionEventToEntries(ev: Record<string, unknown>): HqTranscriptEntry[];
+/**
+ * Merge each tool result into its matching args entry (by `toolUseId`),
+ * keeping the args entry's chronological position. Results with no matching
+ * args entry are kept as their own entries. Mutates/keeps order; pure w.r.t.
+ * input ordering.
+ */
+export declare function mergeToolResults(flat: readonly HqTranscriptEntry[]): HqTranscriptEntry[];
+/**
+ * Map + merge an array of raw JSONL events into the final transcript-entry
+ * list: strict chronological order, with each tool's args and result combined
+ * into a single entry.
+ */
+export declare function buildTranscriptFromEvents(events: Iterable<Record<string, unknown>>): HqTranscriptEntry[];
+//# sourceMappingURL=transcript-mapper.d.ts.map

package/dist/hq/transcript-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-mapper.d.ts","sourceRoot":"","sources":["../../src/hq/transcript-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAoB,MAAM,eAAe,CAAC;AAuCzE;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,EAAE,CA0FzF;AAeD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAuBxF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,iBAAiB,EAAE,CAMrB"}

package/dist/hq/worktree-bridge.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WorktreeTelemetryBridge — forwards local git-worktree lifecycle events to
+ * the HQ publisher as `worktree.event` envelopes, so the command center can
+ * render live build phase swim-lanes / DAG across every connected machine.
+ *
+ * Source: the `worktree.*` EventBus events emitted by `WorktreeManager`
+ * (`worktree/worktree-manager.ts`): allocated, committed, merged, conflict,
+ * released, failed. All payload fields are plain serializable data
+ * (handleId, ownerId, branch, diff stats, conflict files) — no closures, no
+ * decoupled relay needed.
+ *
+ * @module hq/worktree-bridge
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { HqEventEnvelope } from './protocol.js';
+import type { HqPublisher } from './publisher.js';
+export interface WorktreeTelemetryBridgeOptions {
+    /** Local EventBus emitting `worktree.*` events. */
+    events: EventBus;
+    /** HQ publisher to forward envelopes to. */
+    publisher: HqPublisher;
+    /** Optional sessionId to tag envelopes with. */
+    sessionId?: string;
+    /** Override `now()` for deterministic tests. */
+    now?: () => string;
+}
+/**
+ * Start forwarding worktree lifecycle events to HQ. Returns a disposer that
+ * unsubscribes all listeners — call on shutdown.
+ */
+export declare function startWorktreeTelemetryBridge(opts: WorktreeTelemetryBridgeOptions): () => void;
+/** Re-export for type-only consumers. */
+export type { HqEventEnvelope };
+//# sourceMappingURL=worktree-bridge.d.ts.map

package/dist/hq/worktree-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-bridge.d.ts","sourceRoot":"","sources":["../../src/hq/worktree-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,eAAe,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,8BAA8B;IAC7C,mDAAmD;IACnD,MAAM,EAAE,QAAQ,CAAC;IACjB,4CAA4C;IAC5C,SAAS,EAAE,WAAW,CAAC;IACvB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAqDD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,8BAA8B,GAAG,MAAM,IAAI,CAuH7F;AAED,yCAAyC;AACzC,YAAY,EAAE,eAAe,EAAE,CAAC"}