@gigaflow/gmux 0.15.0

package/dist/core/errors.js

@@ -0,0 +1,91 @@
+/**
+ * Error taxonomy.
+ *
+ * Harness-engineering rule: an error message carries the fix inline. A user —
+ * or an agent — should never have to guess the next command. `fix` is printed
+ * directly beneath the message and included in `--json` output.
+ */
+export class GmuxError extends Error {
+    /** The exact command or action that resolves this error. */
+    fix;
+    /** Process exit code. */
+    exitCode;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "GmuxError";
+        this.fix = options.fix;
+        this.exitCode = options.exitCode ?? 1;
+    }
+}
+/** No session matched the given id or prefix. */
+export class SessionNotFoundError extends GmuxError {
+    constructor(id) {
+        super(`No session matches "${id}".`, {
+            fix: "Run `gmux ls` to see recent sessions, or `gmux index --rebuild` if the cache is stale.",
+            exitCode: 4,
+        });
+        this.name = "SessionNotFoundError";
+    }
+}
+/** A prefix matched more than one session. */
+export class AmbiguousSessionError extends GmuxError {
+    constructor(id, matches) {
+        const shown = matches.slice(0, 5).join(", ");
+        super(`"${id}" matches ${matches.length} sessions: ${shown}${matches.length > 5 ? ", …" : ""}`, {
+            fix: "Pass more characters of the session id to disambiguate.",
+            exitCode: 5,
+        });
+        this.name = "AmbiguousSessionError";
+    }
+}
+/** A required external binary is missing. */
+export class MissingDependencyError extends GmuxError {
+    constructor(binary, fix) {
+        super(`Required command "${binary}" was not found on PATH.`, { fix, exitCode: 6 });
+        this.name = "MissingDependencyError";
+    }
+}
+/** A summary provider returned something unusable. */
+export class SummaryProviderError extends GmuxError {
+    constructor(provider, detail) {
+        super(`Summary provider "${provider}" failed: ${detail}`, {
+            fix: "Check the provider CLI works standalone, or run `gmux setup` to choose another.",
+            exitCode: 7,
+        });
+        this.name = "SummaryProviderError";
+    }
+}
+/**
+ * The chat provider behind `gmux ask` failed or said nothing.
+ *
+ * The fix names the provider that actually failed. It used to hardcode
+ * `claude -p`, which told a user who had configured Codex to go and test a
+ * binary they may not even have — non-negotiable #5 asks for the fix to the
+ * problem in front of you, not to the common case.
+ */
+export class AskProviderError extends GmuxError {
+    constructor(provider, detail) {
+        super(`Ask provider "${provider}" failed: ${detail}`, {
+            fix: `Check it works standalone: \`echo hi | ${provider}\`. Or run \`gmux setup\` to choose another.`,
+            exitCode: 7,
+        });
+        this.name = "AskProviderError";
+    }
+}
+/**
+ * No provider is configured — because the user chose "none" in `gmux setup`.
+ *
+ * Distinct from a missing binary, and it must stay distinct: this is a choice
+ * being honored, not a fault. The fix says how to change your mind, not how to
+ * install something.
+ */
+export class NoProviderError extends GmuxError {
+    constructor(what) {
+        super(`${what} needs a model provider, and this machine is configured to make no model calls.`, {
+            fix: "Run `gmux setup` to choose one, or set GMUX_SUMMARY_CMD for a one-off.",
+            exitCode: 8,
+        });
+        this.name = "NoProviderError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,4DAA4D;IACnD,GAAG,CAAqB;IACjC,yBAAyB;IAChB,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,UAA+C,EAAE;QAC5E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IACxC,CAAC;CACF;AAED,iDAAiD;AACjD,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IACjD,YAAY,EAAU;QACpB,KAAK,CAAC,uBAAuB,EAAE,IAAI,EAAE;YACnC,GAAG,EAAE,wFAAwF;YAC7F,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,8CAA8C;AAC9C,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IAClD,YAAY,EAAU,EAAE,OAAiB;QACvC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,KAAK,CAAC,IAAI,EAAE,aAAa,OAAO,CAAC,MAAM,cAAc,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE;YAC9F,GAAG,EAAE,yDAAyD;YAC9D,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,6CAA6C;AAC7C,MAAM,OAAO,sBAAuB,SAAQ,SAAS;IACnD,YAAY,MAAc,EAAE,GAAW;QACrC,KAAK,CAAC,qBAAqB,MAAM,0BAA0B,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,sDAAsD;AACtD,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IACjD,YAAY,QAAgB,EAAE,MAAc;QAC1C,KAAK,CAAC,qBAAqB,QAAQ,aAAa,MAAM,EAAE,EAAE;YACxD,GAAG,EAAE,iFAAiF;YACtF,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IAC7C,YAAY,QAAgB,EAAE,MAAc;QAC1C,KAAK,CAAC,iBAAiB,QAAQ,aAAa,MAAM,EAAE,EAAE;YACpD,GAAG,EAAE,0CAA0C,QAAQ,8CAA8C;YACrG,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC5C,YAAY,IAAY;QACtB,KAAK,CAAC,GAAG,IAAI,iFAAiF,EAAE;YAC9F,GAAG,EAAE,wEAAwE;YAC7E,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/dist/core/fingerprint.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A compact similarity fingerprint, for deciding whether a session has changed
+ * *enough* to re-summarise — not merely *at all*.
+ *
+ * SimHash reduces a document to a 64-bit value where similar text yields similar
+ * bits, so the Hamming distance between two fingerprints tracks how much the
+ * content moved. It's 16 hex characters no matter how long the session gets —
+ * which is the whole point: fixed, tiny metadata for an ever-growing transcript.
+ *
+ * `core` imports nothing internal; this is pure and deterministic.
+ */
+/**
+ * The 64-bit SimHash of `text`, as 16 lowercase hex characters.
+ *
+ * Each token votes on every bit (+1 if its hash has the bit set, −1 otherwise);
+ * the final bit is set when its column of votes is positive. Empty text is all
+ * zeros — a defined value the distance can compare against.
+ */
+export declare function simhash64(text: string): string;
+/** The number of differing bits between two hex fingerprints. */
+export declare function hammingDistance(a: string, b: string): number;

package/dist/core/fingerprint.js

@@ -0,0 +1,59 @@
+/**
+ * A compact similarity fingerprint, for deciding whether a session has changed
+ * *enough* to re-summarise — not merely *at all*.
+ *
+ * SimHash reduces a document to a 64-bit value where similar text yields similar
+ * bits, so the Hamming distance between two fingerprints tracks how much the
+ * content moved. It's 16 hex characters no matter how long the session gets —
+ * which is the whole point: fixed, tiny metadata for an ever-growing transcript.
+ *
+ * `core` imports nothing internal; this is pure and deterministic.
+ */
+const MASK64 = (1n << 64n) - 1n;
+const FNV_OFFSET = 14695981039346656037n;
+const FNV_PRIME = 1099511628211n;
+/** FNV-1a over the bytes of a token → a 64-bit value. Deterministic, no deps. */
+function hashToken(token) {
+    let hash = FNV_OFFSET;
+    for (let i = 0; i < token.length; i++) {
+        hash ^= BigInt(token.charCodeAt(i) & 0xff);
+        hash = (hash * FNV_PRIME) & MASK64;
+    }
+    return hash;
+}
+function tokenize(text) {
+    return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+/**
+ * The 64-bit SimHash of `text`, as 16 lowercase hex characters.
+ *
+ * Each token votes on every bit (+1 if its hash has the bit set, −1 otherwise);
+ * the final bit is set when its column of votes is positive. Empty text is all
+ * zeros — a defined value the distance can compare against.
+ */
+export function simhash64(text) {
+    const votes = new Array(64).fill(0);
+    for (const token of tokenize(text)) {
+        const h = hashToken(token);
+        for (let bit = 0; bit < 64; bit++) {
+            votes[bit] += (h >> BigInt(bit)) & 1n ? 1 : -1;
+        }
+    }
+    let fingerprint = 0n;
+    for (let bit = 0; bit < 64; bit++) {
+        if (votes[bit] > 0)
+            fingerprint |= 1n << BigInt(bit);
+    }
+    return fingerprint.toString(16).padStart(16, "0");
+}
+/** The number of differing bits between two hex fingerprints. */
+export function hammingDistance(a, b) {
+    let xor = (BigInt(`0x${a}`) ^ BigInt(`0x${b}`)) & MASK64;
+    let count = 0;
+    while (xor > 0n) {
+        count += Number(xor & 1n);
+        xor >>= 1n;
+    }
+    return count;
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/core/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/core/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;AAChC,MAAM,UAAU,GAAG,qBAAqB,CAAC;AACzC,MAAM,SAAS,GAAG,cAAc,CAAC;AAEjC,iFAAiF;AACjF,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC3C,IAAI,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAC3B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC;YAClC,KAAK,CAAC,GAAG,CAAE,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,GAAG,CAAE,GAAG,CAAC;YAAE,WAAW,IAAI,EAAE,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC;IACzD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,GAAG,GAAG,EAAE,EAAE,CAAC;QAChB,KAAK,IAAI,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAC1B,GAAG,KAAK,EAAE,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/gmux-types.d.ts

@@ -0,0 +1,102 @@
+import type { HarnessId } from "./types.js";
+/** The five triage-critical pane states, ordered least→most attention-worthy for display. */
+export declare const PANE_STATES: readonly ["working", "idle", "waiting", "error", "done"];
+export type PaneState = (typeof PANE_STATES)[number];
+export declare function isPaneState(value: string): value is PaneState;
+/** A uniform reading from a sensor, regardless of source. */
+export interface Observation {
+    paneId: string;
+    kind: "agent" | "terminal";
+    /** ms epoch when this observation was taken. */
+    ts: number;
+    /** Latest slice of lines (new transcript lines, or pipe-pane/capture tail). */
+    tailLines: string[];
+    /** ms epoch of the last content change seen for this pane (0 if never). */
+    lastActivityTs: number;
+    /** True when the agent transcript's final turn awaits human input (agent panes only). */
+    awaitingInput?: boolean;
+    /** True when the latest slice shows a tool/command failure. */
+    sawError?: boolean;
+    /** True when the agent transcript indicates the task ended/finished. */
+    ended?: boolean;
+}
+/** The human-readable "what it's doing" layer. */
+export interface PaneSemantics {
+    label: string;
+    card: string | null;
+    /** SimHash of the source text the label was written from. */
+    fingerprint: string;
+    updatedAt: number;
+    stale: boolean;
+}
+/** Per-pane memory attribution. */
+export interface PaneResources {
+    /** Subtree RSS sum in bytes. Reliable for ranking, not exact totals. */
+    perPaneRss: number;
+    ts: number;
+}
+/** Durable identity of a pane in the workspace. */
+export interface PaneIdentity {
+    paneId: string;
+    windowId: string | null;
+    active: boolean;
+    harness: HarnessId | null;
+    sessionId: string | null;
+    cwd: string;
+    command: string;
+    pid: number;
+}
+/** One pane's complete state in the model. */
+export interface PaneEntry {
+    identity: PaneIdentity;
+    state: PaneState;
+    semantics: PaneSemantics | null;
+    resources: PaneResources | null;
+    /** ms epoch of last observed activity. */
+    lastActivityTs: number;
+    /** ms epoch of last update to this entry. */
+    ts: number;
+    /** Marked true when the pane vanished; evicted next tick. */
+    gone: boolean;
+}
+/** Host-level memory pressure — the guardian's trigger. Not the sum of panes. */
+export interface HostPressure {
+    /** Used fraction 0..1 (excludes reclaimable cache where the OS distinguishes). */
+    usedRatio: number;
+    /** Bytes not attributed to any tracked pane subtree. */
+    unattributed: number;
+    ts: number;
+}
+/** One guardian action, logged to the model. */
+export interface GuardianLogEntry {
+    ts: number;
+    /** Host used fraction at fire time. */
+    pressure: number;
+    culpritPaneId: string | null;
+    /** Human label of the top consumer, or "source outside tracked panes". */
+    culpritLabel: string;
+    action: "broadcast" | "notify" | "log-only";
+    message: string;
+}
+/** Guardian autonomy policy. */
+export type GuardianPolicy = "off" | "notify" | "auto";
+/** The gmux config block, persisted under GmConfig. */
+export interface GmuxConfig {
+    guardianPolicy: GuardianPolicy;
+    /** Host used fraction that trips the guardian, 0..1. */
+    memoryThreshold: number;
+    /** Minimum seconds between guardian fires. */
+    cooldownSeconds: number;
+    /** Daemon tick interval in ms. */
+    tickMs: number;
+}
+/** The serializable model handed to surfaces over the socket / snapshot file. */
+export interface WorkspaceSnapshot {
+    version: number;
+    updatedAt: number;
+    panes: PaneEntry[];
+    hostPressure: HostPressure | null;
+    guardianLog: GuardianLogEntry[];
+}
+/** Defaults for a fresh install. */
+export declare const DEFAULT_GMUX_CONFIG: GmuxConfig;

package/dist/core/gmux-types.js

@@ -0,0 +1,13 @@
+/** The five triage-critical pane states, ordered least→most attention-worthy for display. */
+export const PANE_STATES = ["working", "idle", "waiting", "error", "done"];
+export function isPaneState(value) {
+    return PANE_STATES.includes(value);
+}
+/** Defaults for a fresh install. */
+export const DEFAULT_GMUX_CONFIG = {
+    guardianPolicy: "auto",
+    memoryThreshold: 0.9,
+    cooldownSeconds: 300,
+    tickMs: 1500,
+};
+//# sourceMappingURL=gmux-types.js.map

package/dist/core/gmux-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmux-types.js","sourceRoot":"","sources":["../../src/core/gmux-types.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAGpF,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAQ,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AA2GD,oCAAoC;AACpC,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,cAAc,EAAE,MAAM;IACtB,eAAe,EAAE,GAAG;IACpB,eAAe,EAAE,GAAG;IACpB,MAAM,EAAE,IAAI;CACb,CAAC"}

package/dist/core/pane-state.d.ts

@@ -0,0 +1,5 @@
+import type { Observation, PaneState } from "./gmux-types.js";
+/** ms of quiet after which a pane is no longer "working". */
+export declare const WORKING_WINDOW_MS = 10000;
+/** Pure heuristic: latest observation → triage state. Deterministic; no I/O. */
+export declare function classifyState(obs: Observation, now: number): PaneState;

package/dist/core/pane-state.js

@@ -0,0 +1,15 @@
+/** ms of quiet after which a pane is no longer "working". */
+export const WORKING_WINDOW_MS = 10_000;
+/** Pure heuristic: latest observation → triage state. Deterministic; no I/O. */
+export function classifyState(obs, now) {
+    if (obs.sawError)
+        return "error";
+    if (obs.ended)
+        return "done";
+    if (obs.awaitingInput)
+        return "waiting";
+    if (now - obs.lastActivityTs < WORKING_WINDOW_MS)
+        return "working";
+    return "idle";
+}
+//# sourceMappingURL=pane-state.js.map

package/dist/core/pane-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pane-state.js","sourceRoot":"","sources":["../../src/core/pane-state.ts"],"names":[],"mappings":"AAEA,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,GAAgB,EAAE,GAAW;IACzD,IAAI,GAAG,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC;IACjC,IAAI,GAAG,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAC7B,IAAI,GAAG,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,GAAG,GAAG,GAAG,CAAC,cAAc,GAAG,iBAAiB;QAAE,OAAO,SAAS,CAAC;IACnE,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/paths.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Where gmux keeps its own state. It never writes anywhere else.
+ *
+ * Two directories and one narrow third category, and the split matters:
+ *
+ * - `cacheDir()` — derived data. Keyed by content hash, thrown away safely.
+ * - `configDir()` — what a human chose. `rm -rf` the cache and you should lose
+ *   summaries, not your provider. Anything a person typed belongs here.
+ * - **Ephemeral IPC** — a scratch buffer one live process writes and its own
+ *   children read, dead the moment that process is, never read by a later run,
+ *   safe to `rm` at any instant. It lives under `cacheDir()` *even though it
+ *   holds typed text*, because "disposable" is what the cache means and this is
+ *   disposable by construction. `askTranscriptDir()` is its ONLY member. The
+ *   category is named here and in AGENTS.md #1 rather than left as a habit,
+ *   because a rule with an unwritten exception is a rule the next person
+ *   "fixes".
+ */
+/** Root of gmux's config. Honors XDG_CONFIG_HOME. */
+export declare function configDir(): string;
+/** The one config file: provider choice and background-summary opt-in. */
+export declare function configPath(): string;
+/** Root of gmux's cache. Honors XDG_CACHE_HOME. */
+export declare function cacheDir(): string;
+/** The parsed-session index. */
+export declare function indexPath(): string;
+/** Directory of generated summaries, one JSON file per session. */
+export declare function summaryDir(): string;
+export declare function summaryPath(harness: string, sessionId: string): string;
+/**
+ * The pane→session links written by `gmux run`. Cache, not config: keyed by tmux
+ * pane ids that die with the server, disposable, regenerated by living in the
+ * tool. Worst case of deleting it: a pane falls back to the cwd heuristic.
+ */
+export declare function paneLinksPath(): string;
+/**
+ * The picker's chat threads — one per live `gmux pick`, gone when it exits.
+ *
+ * The ephemeral-IPC category above, and its only member. Not `configDir()`: the
+ * thread dies with the picker, and config implies a retention policy nobody has
+ * written. Not `os.tmpdir()`: this module never writes outside gmux's two roots,
+ * `XDG_CACHE_HOME` is how the test suite redirects those writes, and a tmp
+ * reaper is free to delete a file mid-append.
+ *
+ * Its own subdirectory, so the orphan sweep is a `readdir` of a directory that
+ * holds nothing but transcripts and cannot mistake `index.json` for one.
+ */
+export declare function askTranscriptDir(): string;
+/**
+ * `runId` is `<pid>-<rand8>`: the random half makes concurrent pickers
+ * collision-free, the pid half makes reaping a `readdir` plus a
+ * `process.kill(pid, 0)` with zero file reads.
+ */
+export declare function askTranscriptPath(runId: string): string;
+/**
+ * Home directory, overridable via GMUX_HOME so tests can point the
+ * adapters at fixture trees instead of the real one.
+ */
+export declare function harnessHome(): string;
+/** Root of gmux's ephemeral daemon state (cache: dies with the tmux server). */
+export declare function gmuxDir(): string;
+/** Unix socket surfaces connect to for live model subscription. */
+export declare function gmuxSocketPath(): string;
+/** Snapshot file written every tick; the fallback when the daemon is down. */
+export declare function gmuxSnapshotPath(): string;
+/** Directory of per-pane pipe-pane logs (non-agent tail). */
+export declare function paneLogDir(): string;
+/** One pane's pipe-pane log. `%3` → `pane-3.log` (tmux ids carry a `%`). */
+export declare function paneLogPath(paneId: string): string;

package/dist/core/paths.js

@@ -0,0 +1,106 @@
+/**
+ * Where gmux keeps its own state. It never writes anywhere else.
+ *
+ * Two directories and one narrow third category, and the split matters:
+ *
+ * - `cacheDir()` — derived data. Keyed by content hash, thrown away safely.
+ * - `configDir()` — what a human chose. `rm -rf` the cache and you should lose
+ *   summaries, not your provider. Anything a person typed belongs here.
+ * - **Ephemeral IPC** — a scratch buffer one live process writes and its own
+ *   children read, dead the moment that process is, never read by a later run,
+ *   safe to `rm` at any instant. It lives under `cacheDir()` *even though it
+ *   holds typed text*, because "disposable" is what the cache means and this is
+ *   disposable by construction. `askTranscriptDir()` is its ONLY member. The
+ *   category is named here and in AGENTS.md #1 rather than left as a habit,
+ *   because a rule with an unwritten exception is a rule the next person
+ *   "fixes".
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Root of gmux's config. Honors XDG_CONFIG_HOME. */
+export function configDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg && xdg.trim() !== "" ? xdg : join(homedir(), ".config");
+    return join(base, "gmux");
+}
+/** The one config file: provider choice and background-summary opt-in. */
+export function configPath() {
+    return join(configDir(), "config.json");
+}
+/** Root of gmux's cache. Honors XDG_CACHE_HOME. */
+export function cacheDir() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    const base = xdg && xdg.trim() !== "" ? xdg : join(homedir(), ".cache");
+    return join(base, "gmux");
+}
+/** The parsed-session index. */
+export function indexPath() {
+    return join(cacheDir(), "index.json");
+}
+/** Directory of generated summaries, one JSON file per session. */
+export function summaryDir() {
+    return join(cacheDir(), "summaries");
+}
+export function summaryPath(harness, sessionId) {
+    return join(summaryDir(), `${harness}-${sessionId}.json`);
+}
+/**
+ * The pane→session links written by `gmux run`. Cache, not config: keyed by tmux
+ * pane ids that die with the server, disposable, regenerated by living in the
+ * tool. Worst case of deleting it: a pane falls back to the cwd heuristic.
+ */
+export function paneLinksPath() {
+    return join(cacheDir(), "pane-links.json");
+}
+/**
+ * The picker's chat threads — one per live `gmux pick`, gone when it exits.
+ *
+ * The ephemeral-IPC category above, and its only member. Not `configDir()`: the
+ * thread dies with the picker, and config implies a retention policy nobody has
+ * written. Not `os.tmpdir()`: this module never writes outside gmux's two roots,
+ * `XDG_CACHE_HOME` is how the test suite redirects those writes, and a tmp
+ * reaper is free to delete a file mid-append.
+ *
+ * Its own subdirectory, so the orphan sweep is a `readdir` of a directory that
+ * holds nothing but transcripts and cannot mistake `index.json` for one.
+ */
+export function askTranscriptDir() {
+    return join(cacheDir(), "ask");
+}
+/**
+ * `runId` is `<pid>-<rand8>`: the random half makes concurrent pickers
+ * collision-free, the pid half makes reaping a `readdir` plus a
+ * `process.kill(pid, 0)` with zero file reads.
+ */
+export function askTranscriptPath(runId) {
+    return join(askTranscriptDir(), `${runId}.jsonl`);
+}
+/**
+ * Home directory, overridable via GMUX_HOME so tests can point the
+ * adapters at fixture trees instead of the real one.
+ */
+export function harnessHome() {
+    const override = process.env.GMUX_HOME;
+    return override && override.trim() !== "" ? override : homedir();
+}
+/** Root of gmux's ephemeral daemon state (cache: dies with the tmux server). */
+export function gmuxDir() {
+    return join(cacheDir(), "gmux");
+}
+/** Unix socket surfaces connect to for live model subscription. */
+export function gmuxSocketPath() {
+    return join(gmuxDir(), "daemon.sock");
+}
+/** Snapshot file written every tick; the fallback when the daemon is down. */
+export function gmuxSnapshotPath() {
+    return join(gmuxDir(), "snapshot.json");
+}
+/** Directory of per-pane pipe-pane logs (non-agent tail). */
+export function paneLogDir() {
+    return join(gmuxDir(), "panes");
+}
+/** One pane's pipe-pane log. `%3` → `pane-3.log` (tmux ids carry a `%`). */
+export function paneLogPath(paneId) {
+    return join(paneLogDir(), `pane-${paneId.replace(/^%/, "")}.log`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/paths.js.map

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

package/dist/core/proc-tree.d.ts

@@ -0,0 +1,9 @@
+export interface ProcRow {
+    pid: number;
+    ppid: number;
+    rss: number;
+    comm: string;
+}
+/** Parse `ps -axo pid,ppid,rss,comm`. RSS is KB on macOS/Linux → convert to bytes. */
+export declare function parsePsOutput(raw: string): ProcRow[];
+export declare function subtreeRss(rootPid: number, rows: ProcRow[]): number;

package/dist/core/proc-tree.js

@@ -0,0 +1,33 @@
+/** Parse `ps -axo pid,ppid,rss,comm`. RSS is KB on macOS/Linux → convert to bytes. */
+export function parsePsOutput(raw) {
+    const rows = [];
+    for (const line of raw.split("\n")) {
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
+        if (!m)
+            continue; // skips the header and blanks
+        rows.push({ pid: Number(m[1]), ppid: Number(m[2]), rss: Number(m[3]) * 1024, comm: m[4].trim() });
+    }
+    return rows;
+}
+export function subtreeRss(rootPid, rows) {
+    const children = new Map();
+    const rss = new Map();
+    for (const r of rows) {
+        rss.set(r.pid, r.rss);
+        (children.get(r.ppid) ?? children.set(r.ppid, []).get(r.ppid)).push(r.pid);
+    }
+    let total = 0;
+    const stack = [rootPid];
+    const seen = new Set();
+    while (stack.length) {
+        const pid = stack.pop();
+        if (seen.has(pid))
+            continue;
+        seen.add(pid);
+        total += rss.get(pid) ?? 0;
+        for (const c of children.get(pid) ?? [])
+            stack.push(c);
+    }
+    return total;
+}
+//# sourceMappingURL=proc-tree.js.map

package/dist/core/proc-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proc-tree.js","sourceRoot":"","sources":["../../src/core/proc-tree.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAC9D,IAAI,CAAC,CAAC;YAAE,SAAS,CAAC,8BAA8B;QAChD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACrG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,IAAe;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,KAAK,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/text.d.ts

@@ -0,0 +1,34 @@
+/** Small pure string/time helpers. No I/O, no internal imports. */
+/** Collapse whitespace and clip to `max`, appending an ellipsis when clipped. */
+export declare function truncate(input: string, max: number): string;
+/** Stable content hash used as a cache key. */
+export declare function hash(input: string): string;
+/**
+ * Compact relative age, e.g. "2h", "3d". Deliberately terse: it is a column in
+ * a list, not prose.
+ */
+export declare function relativeAge(iso: string, now?: Date): string;
+/**
+ * Parse a duration like "3d", "2w", "24h" into an ISO cutoff timestamp.
+ * Returns null for unparseable input.
+ */
+export declare function parseSince(input: string, now?: Date): string | null;
+/**
+ * Greedy word wrap. Returns at least one line, even for empty input, so callers
+ * can always render a row.
+ *
+ * A word longer than the width (a URL, a long path) is hard-split rather than
+ * allowed to overflow — overflowing is the bug this exists to fix.
+ */
+export declare function wrapText(input: string, width: number): string[];
+/**
+ * Single-quote for POSIX shells, escaping any embedded single quote.
+ *
+ * Lives in core because two callers need it: `gmux resume --print` emits a line
+ * meant to be pasted into a shell, and the picker's fzf reload binding is a
+ * shell command string. In both, an unquoted path with a space silently runs
+ * the wrong thing rather than failing loudly.
+ */
+export declare function shellQuote(value: string): string;
+/** Pad or clip a cell to an exact display width. */
+export declare function cell(input: string, width: number): string;