@phnx-labs/agents-cli 1.22.75 → 1.22.77

package/dist/lib/state.d.ts

@@ -319,6 +319,21 @@ export declare function getRuntimeStateDir(): string;
 export declare function getCompanionDir(): string;
 /** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
 export declare function getBrowserRuntimeDir(): string;
+/**
+ * Path to DURABLE browser-profile data (~/.agents/.history/browser-profiles/).
+ *
+ * This is the persistent home for an attach-only profile's `--user-data-dir` —
+ * where a one-time browser sign-in lives. It sits under `.history` (durable),
+ * NOT `.cache` (regenerable), for two reasons the ticket (PHNX-3967) named:
+ *  - `agents browser profiles remove` sweeps `~/.agents/.cache/browser/<name>*`;
+ *    a durable dir here survives that so logins are not wiped by a routine cleanup.
+ *  - A cache wipe or the daemon reaper never touches it, so a signed-in Comet
+ *    survives quit+relaunch.
+ * The user's canonical Comet is launched with this as `--user-data-dir`, and the
+ * ownership guard in the local driver compares the running instance's
+ * `--user-data-dir` against it to reject a foreign port-squatter.
+ */
+export declare function getBrowserDurableDir(): string;
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
 export declare function getHelpersDir(): string;
 /**
@@ -394,6 +409,33 @@ export declare function getDeviceMetaPath(): string;
  */
 export declare function getVersionResourcesPath(): string;
 export declare function withMetaLock<T>(fn: () => T): T;
+/**
+ * Commit the central `agents.yaml` in the user repo, synchronously, so a CLI
+ * config mutation never leaves the working tree dirty on that one shared-line
+ * file at rest.
+ *
+ * Why this exists: CLI config commands rewrite the fleet-shared central
+ * agents.yaml as a plain file write. Left uncommitted, the tree is dirty on
+ * agents.yaml between the write and the daemon's next 15-min publish tick — and
+ * a peer's incoming publish commit (which also touches agents.yaml) then trips
+ * `dirtyTreeRefusal` ("incoming changes touch uncommitted paths: agents.yaml"),
+ * wedging `agents repo pull` fleet-wide (PHNX-3968). Committing the central edit
+ * in the same command that made it closes that window: agents.yaml is clean at
+ * rest, so nothing incoming can collide with it. Called AFTER the meta lock
+ * releases (see {@link commitCentralConfigAfterWrite}) so the git subprocesses
+ * never run inside the short, non-heartbeated lockfile window; the user repo
+ * already pushes.
+ *
+ * Scoped tightly: only called when the central bytes actually changed, and never
+ * from the daemon (see {@link isDaemonProcess}). A commit failure fails open —
+ * a concurrent daemon holding `index.lock`, a mid-rebase repo — leaving
+ * agents.yaml dirty; the next successful central write commits it, and until
+ * then a pull that would collide refuses rather than losing data. A config
+ * command must never fail because git hiccuped.
+ *
+ * Returns whether a commit was created. Exported for the real-repo tests.
+ */
+export declare function commitCentralConfig(userDir: string): boolean;
 /**
  * True when the top-level `~/.agents/agents.yaml` carries a metadata header that
  * is NOT the canonical {@link META_HEADER} — the P1 frozen-header case a box only
@@ -416,8 +458,13 @@ export declare function readTopLevelUserMeta(): Record<string, unknown> | null;
  * writer that needs to read fresh state, decide, and commit within a SINGLE lock
  * acquisition (e.g. browser tombstone eviction) can do so without the
  * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
+ *
+ * Returns whether the central `agents.yaml` bytes actually changed, so the
+ * caller can commit it once — {@link commitCentralConfig} — AFTER releasing the
+ * meta lock (the git subprocesses must not run inside the short, non-heartbeated
+ * lockfile window). This function never commits.
  */
-export declare function writeMetaUnlocked(meta: Meta): void;
+export declare function writeMetaUnlocked(meta: Meta): boolean;
 /**
  * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
  *
@@ -433,6 +480,16 @@ export declare function readMeta(): Meta;
 export declare function writeMeta(meta: Meta): void;
 /** Update agents.yaml under lock and return the new state. */
 export declare function updateMeta(updates: Partial<Meta> | ((meta: Meta) => Meta)): Meta;
+/**
+ * Commit-on-write, invoked AFTER {@link withMetaLock} releases so the git
+ * subprocesses never run inside the short, non-heartbeated meta-lock window.
+ * A CLI command that actually moved the fleet-shared central agents.yaml commits
+ * it so the tree is never left dirty on that file at rest — the window that
+ * trips `dirtyTreeRefusal` and wedges pulls fleet-wide (PHNX-3968). Gated on a
+ * real byte change and never run in the daemon, whose publish tick owns central
+ * commits. See {@link commitCentralConfig}.
+ */
+export declare function commitCentralConfigAfterWrite(centralChanged: boolean): void;
 /** Derive a filesystem-safe local clone path for a package source URL. */
 export declare function getPackageLocalPath(source: string): string;
 import type { AgentId, ResourceType, VersionResources, ResourcePattern } from './types.js';

package/dist/lib/state.js

@@ -642,6 +642,21 @@ export function getRuntimeStateDir() { return process.env.AGENTS_STATE_DIR ?? RU
 export function getCompanionDir() { return COMPANION_CACHE_DIR; }
 /** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
 export function getBrowserRuntimeDir() { return BROWSER_RUNTIME_DIR; }
+/**
+ * Path to DURABLE browser-profile data (~/.agents/.history/browser-profiles/).
+ *
+ * This is the persistent home for an attach-only profile's `--user-data-dir` —
+ * where a one-time browser sign-in lives. It sits under `.history` (durable),
+ * NOT `.cache` (regenerable), for two reasons the ticket (PHNX-3967) named:
+ *  - `agents browser profiles remove` sweeps `~/.agents/.cache/browser/<name>*`;
+ *    a durable dir here survives that so logins are not wiped by a routine cleanup.
+ *  - A cache wipe or the daemon reaper never touches it, so a signed-in Comet
+ *    survives quit+relaunch.
+ * The user's canonical Comet is launched with this as `--user-data-dir`, and the
+ * ownership guard in the local driver compares the running instance's
+ * `--user-data-dir` against it to reject a foreign port-squatter.
+ */
+export function getBrowserDurableDir() { return path.join(HISTORY_DIR, 'browser-profiles'); }
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
 export function getHelpersDir() { return HELPERS_DIR; }
 /**
@@ -835,7 +850,9 @@ export function withMetaLock(fn) {
     });
 }
 /** Atomic write only when the on-disk content differs — avoids needless mtime
- * bumps (which would thrash the meta cache) on no-op field routing. */
+ * bumps (which would thrash the meta cache) on no-op field routing. Returns
+ * whether it actually wrote, so a caller can react only to a real change (e.g.
+ * commit the central agents.yaml exactly when its bytes moved). */
 function writeIfChanged(filePath, content) {
     let current = null;
     try {
@@ -843,8 +860,74 @@ function writeIfChanged(filePath, content) {
     }
     catch { /* absent */ }
     if (current === content)
-        return;
+        return false;
     atomicWriteFileSync(filePath, content);
+    return true;
+}
+/**
+ * True in the always-on daemon process (launched as `agents __daemon-run`,
+ * see cli/src/index.ts). The daemon owns central git commits through
+ * fleet-shared-repo-sync's publish tick, so a central write from inside the
+ * daemon must NOT also commit here — that would race the publisher's own
+ * add/commit/rebase/push on the same index. Every ordinary CLI invocation
+ * returns false and commits its own central edit synchronously.
+ */
+function isDaemonProcess() {
+    return process.argv[2] === '__daemon-run';
+}
+/**
+ * Commit the central `agents.yaml` in the user repo, synchronously, so a CLI
+ * config mutation never leaves the working tree dirty on that one shared-line
+ * file at rest.
+ *
+ * Why this exists: CLI config commands rewrite the fleet-shared central
+ * agents.yaml as a plain file write. Left uncommitted, the tree is dirty on
+ * agents.yaml between the write and the daemon's next 15-min publish tick — and
+ * a peer's incoming publish commit (which also touches agents.yaml) then trips
+ * `dirtyTreeRefusal` ("incoming changes touch uncommitted paths: agents.yaml"),
+ * wedging `agents repo pull` fleet-wide (PHNX-3968). Committing the central edit
+ * in the same command that made it closes that window: agents.yaml is clean at
+ * rest, so nothing incoming can collide with it. Called AFTER the meta lock
+ * releases (see {@link commitCentralConfigAfterWrite}) so the git subprocesses
+ * never run inside the short, non-heartbeated lockfile window; the user repo
+ * already pushes.
+ *
+ * Scoped tightly: only called when the central bytes actually changed, and never
+ * from the daemon (see {@link isDaemonProcess}). A commit failure fails open —
+ * a concurrent daemon holding `index.lock`, a mid-rebase repo — leaving
+ * agents.yaml dirty; the next successful central write commits it, and until
+ * then a pull that would collide refuses rather than losing data. A config
+ * command must never fail because git hiccuped.
+ *
+ * Returns whether a commit was created. Exported for the real-repo tests.
+ */
+export function commitCentralConfig(userDir) {
+    const rel = 'agents.yaml';
+    try {
+        execFileSync('git', ['-C', userDir, 'rev-parse', '--is-inside-work-tree'], { stdio: 'ignore' });
+    }
+    catch {
+        return false; // plain ~/.agents with no git repo — leave it a loose write.
+    }
+    try {
+        execFileSync('git', ['-C', userDir, 'add', '--', rel], { stdio: 'ignore' });
+        // Nothing staged for agents.yaml (its bytes matched HEAD after all) → no
+        // empty commit. `diff --cached --quiet` exits 0 when the index equals HEAD
+        // for this path, 1 when it differs.
+        try {
+            execFileSync('git', ['-C', userDir, 'diff', '--cached', '--quiet', '--', rel], { stdio: 'ignore' });
+            return false;
+        }
+        catch { /* exit 1 → staged changes present, commit them */ }
+        // Pathspec-scoped commit: records ONLY agents.yaml even if other paths are
+        // staged, so a config write never sweeps unrelated staged work into its commit.
+        execFileSync('git', ['-C', userDir, '-c', 'commit.gpgsign=false', 'commit', '--no-verify',
+            '-m', 'chore(config): update agents.yaml', '--', rel], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false; // fail open — see the doc comment.
+    }
 }
 /**
  * Partition the in-memory Meta across four files by sync-domain:
@@ -1134,8 +1217,20 @@ function serializeCentral(central) {
  * writer that needs to read fresh state, decide, and commit within a SINGLE lock
  * acquisition (e.g. browser tombstone eviction) can do so without the
  * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
+ *
+ * Returns whether the central `agents.yaml` bytes actually changed, so the
+ * caller can commit it once — {@link commitCentralConfig} — AFTER releasing the
+ * meta lock (the git subprocesses must not run inside the short, non-heartbeated
+ * lockfile window). This function never commits.
  */
 export function writeMetaUnlocked(meta) {
+    const writesDeviceRoutines = Object.prototype.hasOwnProperty.call(meta, 'deviceRoutines');
+    const writesDeviceConfig = Object.prototype.hasOwnProperty.call(meta, 'deviceConfig');
+    const writesDeviceBrowser = Object.prototype.hasOwnProperty.call(meta, 'deviceBrowser');
+    const writesDeviceFleet = Object.prototype.hasOwnProperty.call(meta, 'deviceFleet');
+    const writesDeviceHosts = Object.prototype.hasOwnProperty.call(meta, 'deviceHosts');
+    const writesDeviceAccounts = Object.prototype.hasOwnProperty.call(meta, 'deviceAccounts');
+    const writesProjectRoot = Object.prototype.hasOwnProperty.call(meta, 'projectRoot');
     // INVARIANT: every key destructured here must also be in BESPOKE_DEVICE_KEYS (and
     // vice versa) — a bespoke device key that is classified but NOT pulled out here
     // would fall into `central`, and the generic router skips it (BESPOKE_DEVICE_KEY_SET),
@@ -1191,17 +1286,17 @@ export function writeMetaUnlocked(meta) {
     delete doc.isolatedAgents;
     if (Array.isArray(deviceRoutines))
         doc.routines = deviceRoutines;
-    else
+    else if (writesDeviceRoutines)
         delete doc.routines;
     const hasDeviceConfig = !!deviceConfig && Object.keys(deviceConfig).length > 0;
     if (hasDeviceConfig)
         doc.config = deviceConfig;
-    else
+    else if (writesDeviceConfig)
         delete doc.config;
     const hasDeviceBrowser = !!deviceBrowser && Object.keys(deviceBrowser).length > 0;
     if (hasDeviceBrowser)
         doc.browser = deviceBrowser;
-    else
+    else if (writesDeviceBrowser)
         delete doc.browser;
     // PHNX-3315 device-scoped fleet/hosts/accounts blocks. Each is this box's OWN
     // slice; the effective fleet view is unioned across every device doc at read
@@ -1219,12 +1314,12 @@ export function writeMetaUnlocked(meta) {
             df.ignored = fleetIgnored;
         doc.fleet = df;
     }
-    else
+    else if (writesDeviceFleet)
         delete doc.fleet;
     const hasDeviceHosts = !!deviceHosts && Object.keys(deviceHosts).length > 0;
     if (hasDeviceHosts)
         doc.hosts = deviceHosts;
-    else
+    else if (writesDeviceHosts)
         delete doc.hosts;
     const accountsNative = deviceAccounts?.native && Object.keys(deviceAccounts.native).length > 0
         ? deviceAccounts.native : undefined;
@@ -1238,12 +1333,12 @@ export function writeMetaUnlocked(meta) {
             da.bindings = accountsBindings;
         doc.accounts = da;
     }
-    else
+    else if (writesDeviceAccounts)
         delete doc.accounts;
     const hasProjectRoot = typeof projectRoot === 'string' && projectRoot.length > 0;
     if (hasProjectRoot)
         doc.projectRoot = projectRoot;
-    else
+    else if (writesProjectRoot)
         delete doc.projectRoot;
     // Generic device-scoped keys (PHNX-3315): any key left in `central` that this
     // version classifies as device but does NOT bespoke-route round-trips through
@@ -1284,8 +1379,9 @@ export function writeMetaUnlocked(meta) {
         fs.mkdirSync(path.dirname(vrPath), { recursive: true });
         writeIfChanged(vrPath, JSON.stringify(versions, null, 2) + '\n');
     }
-    writeIfChanged(META_FILE, serializeCentral(central));
+    const centralChanged = writeIfChanged(META_FILE, serializeCentral(central));
     metaCache = null;
+    return centralChanged;
 }
 /**
  * Overlay this machine's local state onto a central-portable Meta:
@@ -1471,7 +1567,15 @@ export function readMeta() {
             if (parsed.registries) {
                 meta.registries = parsed.registries;
             }
-            writeMeta(meta);
+            // Lock-safe, commit-free write: withMetaLock is reentrant (see
+            // metaLockDepth), so this writes under the lock when called standalone and
+            // is a no-op re-entry when readMeta runs inside updateMeta/writeMeta's held
+            // lock — and writeMetaUnlocked never spawns git. Calling the PUBLIC
+            // writeMeta here would run commit-on-write's git subprocess inside a held,
+            // non-heartbeated lock. This one-shot legacy migration needs no synchronous
+            // commit: it self-heals on the daemon's next publish tick or the next real
+            // CLI central write.
+            withMetaLock(() => writeMetaUnlocked(meta));
             try {
                 fs.unlinkSync(oldMetaFile);
             }
@@ -1525,18 +1629,36 @@ export function readMeta() {
 }
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export function writeMeta(meta) {
-    withMetaLock(() => writeMetaUnlocked(meta));
+    const centralChanged = withMetaLock(() => writeMetaUnlocked(meta));
+    commitCentralConfigAfterWrite(centralChanged);
 }
 /** Update agents.yaml under lock and return the new state. */
 export function updateMeta(updates) {
-    return withMetaLock(() => {
+    let centralChanged = false;
+    const newMeta = withMetaLock(() => {
         const meta = readMeta();
-        const newMeta = typeof updates === 'function'
+        const nm = typeof updates === 'function'
             ? updates(meta)
             : { ...meta, ...updates };
-        writeMetaUnlocked(newMeta);
-        return newMeta;
+        centralChanged = writeMetaUnlocked(nm);
+        return nm;
     });
+    commitCentralConfigAfterWrite(centralChanged);
+    return newMeta;
+}
+/**
+ * Commit-on-write, invoked AFTER {@link withMetaLock} releases so the git
+ * subprocesses never run inside the short, non-heartbeated meta-lock window.
+ * A CLI command that actually moved the fleet-shared central agents.yaml commits
+ * it so the tree is never left dirty on that file at rest — the window that
+ * trips `dirtyTreeRefusal` and wedges pulls fleet-wide (PHNX-3968). Gated on a
+ * real byte change and never run in the daemon, whose publish tick owns central
+ * commits. See {@link commitCentralConfig}.
+ */
+export function commitCentralConfigAfterWrite(centralChanged) {
+    if (centralChanged && !isDaemonProcess()) {
+        commitCentralConfig(USER_AGENTS_DIR);
+    }
 }
 /** Derive a filesystem-safe local clone path for a package source URL. */
 export function getPackageLocalPath(source) {

package/dist/lib/summarizer/config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Session-summarizer configuration (PHNX-3939).
+ *
+ * Resolves the three knobs behind the daemon summarizer — enabled / base URL /
+ * model — from `agents config` (`summarizer.*`, user-scope in the central
+ * agents.yaml) with a per-process env override
+ * (`AGENTS_SUMMARIZER_ENABLED` / `AGENTS_SUMMARIZER_BASEURL` /
+ * `AGENTS_SUMMARIZER_MODEL`). Off by default: with no config and no env, the
+ * summarizer is disabled and makes zero model calls.
+ *
+ * `isSummarizerReady()` is memoized on a short TTL because the display merge
+ * (the watch-stream projections) calls it once per session row — a fresh
+ * agents.yaml read per row would defeat the "blazing fast" requirement.
+ */
+export interface SummarizerConfig {
+    enabled: boolean;
+    /** Anthropic-wire base URL (Ollama/vLLM/LiteLLM), or undefined when unconfigured. */
+    baseUrl?: string;
+    /** Model id to request, or undefined when unconfigured. */
+    model?: string;
+}
+/**
+ * Resolve the full summarizer config. Env overrides the stored config key by key;
+ * an unset env var falls through to `agents config`, then to the built-in
+ * default (disabled). Never throws — a missing/corrupt config reads as unset.
+ */
+export declare function resolveSummarizerConfig(env?: NodeJS.ProcessEnv): SummarizerConfig;
+/**
+ * True only when the summarizer is enabled AND has a base URL + model to call.
+ * A configuration that is `enabled` but missing an endpoint cannot produce a
+ * summary, so it is treated as unconfigured (the service no-ops, the merge marks
+ * `skipped`) rather than erroring on every tick.
+ */
+export declare function isSummarizerRunnable(config: SummarizerConfig): boolean;
+/**
+ * Memoized "will a summary actually be produced?" check for the hot merge path.
+ * Reflects {@link isSummarizerRunnable} — enabled AND a base URL AND a model —
+ * NOT just `enabled`, because an enabled-but-unconfigured summarizer computes
+ * nothing, so a row with no cached summary must read `skipped`, not a `pending`
+ * that never resolves (the exact case: `summarizer.enabled on` set before the
+ * endpoint). TTL keeps a config change visible within a few seconds without a
+ * per-row agents.yaml read.
+ */
+export declare function isSummarizerReady(nowMs?: number): boolean;
+/** Test seam: drop the memoized ready flag so the next read re-resolves. */
+export declare function resetSummarizerReadyCacheForTest(): void;

package/dist/lib/summarizer/config.js

@@ -0,0 +1,83 @@
+/**
+ * Session-summarizer configuration (PHNX-3939).
+ *
+ * Resolves the three knobs behind the daemon summarizer — enabled / base URL /
+ * model — from `agents config` (`summarizer.*`, user-scope in the central
+ * agents.yaml) with a per-process env override
+ * (`AGENTS_SUMMARIZER_ENABLED` / `AGENTS_SUMMARIZER_BASEURL` /
+ * `AGENTS_SUMMARIZER_MODEL`). Off by default: with no config and no env, the
+ * summarizer is disabled and makes zero model calls.
+ *
+ * `isSummarizerReady()` is memoized on a short TTL because the display merge
+ * (the watch-stream projections) calls it once per session row — a fresh
+ * agents.yaml read per row would defeat the "blazing fast" requirement.
+ */
+import { getConfigValue } from '../device-config.js';
+/** Parse a boolean-ish env value; undefined when the var is unset. */
+function envBool(raw) {
+    if (raw === undefined)
+        return undefined;
+    const v = raw.trim().toLowerCase();
+    if (v === '1' || v === 'true' || v === 'on' || v === 'yes')
+        return true;
+    if (v === '0' || v === 'false' || v === 'off' || v === 'no' || v === '')
+        return false;
+    return undefined;
+}
+function envString(raw) {
+    const v = raw?.trim();
+    return v ? v : undefined;
+}
+/**
+ * Resolve the full summarizer config. Env overrides the stored config key by key;
+ * an unset env var falls through to `agents config`, then to the built-in
+ * default (disabled). Never throws — a missing/corrupt config reads as unset.
+ */
+export function resolveSummarizerConfig(env = process.env) {
+    let storedEnabled;
+    let storedBaseUrl;
+    let storedModel;
+    try {
+        storedEnabled = getConfigValue('summarizer.enabled').value;
+        storedBaseUrl = getConfigValue('summarizer.baseUrl').value;
+        storedModel = getConfigValue('summarizer.model').value;
+    }
+    catch {
+        // A missing/corrupt config store must not break the read path — treat as unset.
+    }
+    const enabled = envBool(env.AGENTS_SUMMARIZER_ENABLED) ?? storedEnabled ?? false;
+    const baseUrl = envString(env.AGENTS_SUMMARIZER_BASEURL) ?? envString(storedBaseUrl);
+    const model = envString(env.AGENTS_SUMMARIZER_MODEL) ?? envString(storedModel);
+    return { enabled, baseUrl, model };
+}
+/**
+ * True only when the summarizer is enabled AND has a base URL + model to call.
+ * A configuration that is `enabled` but missing an endpoint cannot produce a
+ * summary, so it is treated as unconfigured (the service no-ops, the merge marks
+ * `skipped`) rather than erroring on every tick.
+ */
+export function isSummarizerRunnable(config) {
+    return config.enabled && Boolean(config.baseUrl) && Boolean(config.model);
+}
+let cachedReady = null;
+const READY_TTL_MS = 3_000;
+/**
+ * Memoized "will a summary actually be produced?" check for the hot merge path.
+ * Reflects {@link isSummarizerRunnable} — enabled AND a base URL AND a model —
+ * NOT just `enabled`, because an enabled-but-unconfigured summarizer computes
+ * nothing, so a row with no cached summary must read `skipped`, not a `pending`
+ * that never resolves (the exact case: `summarizer.enabled on` set before the
+ * endpoint). TTL keeps a config change visible within a few seconds without a
+ * per-row agents.yaml read.
+ */
+export function isSummarizerReady(nowMs = Date.now()) {
+    if (cachedReady && nowMs - cachedReady.at < READY_TTL_MS)
+        return cachedReady.value;
+    const value = isSummarizerRunnable(resolveSummarizerConfig());
+    cachedReady = { at: nowMs, value };
+    return value;
+}
+/** Test seam: drop the memoized ready flag so the next read re-resolves. */
+export function resetSummarizerReadyCacheForTest() {
+    cachedReady = null;
+}

package/dist/lib/summarizer/pass.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One session-summarizer pass (PHNX-3939) — the work the background
+ * SessionSummarizerService does per tick, factored out so it is testable with an
+ * injected model stub and no daemon scaffolding.
+ *
+ * Off the request path by construction: it reads THIS box's already-published
+ * live sessions (the warm cache the session-state service writes — never a fresh
+ * gather) and, per session, reuses the transcript-keyed `session_summaries` row
+ * until the transcript bytes change, so an unchanged session costs one indexed
+ * read and zero model calls. When the summarizer is disabled or has no endpoint,
+ * the pass does nothing at all.
+ */
+import type { ActiveSession } from '../session/active.js';
+import { type SummarizerConfig } from './config.js';
+import { summarize as defaultSummarize } from './summarize.js';
+/** Max sessions summarized per tick — a debounce ceiling on local-model calls. */
+export declare const SUMMARIZER_MAX_PER_TICK = 8;
+export interface SummarizerPassOptions {
+    now?: number;
+    config?: SummarizerConfig;
+    /** Live sessions to consider; default = this box's warm local-session cache. */
+    sessions?: ActiveSession[];
+    /** Injectable model call (tests stub the endpoint here). */
+    summarizeImpl?: typeof defaultSummarize;
+    signal?: AbortSignal;
+    maxPerTick?: number;
+    /** Injectable stat for tests; defaults to fs.statSync. */
+    statFile?: (p: string) => {
+        mtimeMs: number;
+        size: number;
+    };
+    /** Skip the reader-recency gate (tests pass sessions directly). */
+    requireReader?: boolean;
+}
+export interface SummarizerPassResult {
+    disabled: boolean;
+    computed: number;
+    reused: number;
+    skipped: number;
+}
+/**
+ * Run one pass. Returns per-outcome counts. Never throws — a per-session failure
+ * is isolated so one bad transcript can't stall the whole tick.
+ */
+export declare function runSummarizerPass(opts?: SummarizerPassOptions): Promise<SummarizerPassResult>;

package/dist/lib/summarizer/pass.js

@@ -0,0 +1,112 @@
+/**
+ * One session-summarizer pass (PHNX-3939) — the work the background
+ * SessionSummarizerService does per tick, factored out so it is testable with an
+ * injected model stub and no daemon scaffolding.
+ *
+ * Off the request path by construction: it reads THIS box's already-published
+ * live sessions (the warm cache the session-state service writes — never a fresh
+ * gather) and, per session, reuses the transcript-keyed `session_summaries` row
+ * until the transcript bytes change, so an unchanged session costs one indexed
+ * read and zero model calls. When the summarizer is disabled or has no endpoint,
+ * the pass does nothing at all.
+ */
+import * as fs from 'node:fs';
+import { readSessionSummary, readSessionSummaryAny, writeSessionSummary, } from '../session/db.js';
+import { isActiveSessionsJournalReaderRecent, readActiveSessionsCache, } from '../session/session-cache.js';
+import { resolveSummarizerConfig, isSummarizerRunnable } from './config.js';
+import { summarize as defaultSummarize } from './summarize.js';
+/** Max sessions summarized per tick — a debounce ceiling on local-model calls. */
+export const SUMMARIZER_MAX_PER_TICK = 8;
+/**
+ * Merge model checkpoint TEXTS with any prior stored checkpoints so a line that
+ * already existed keeps its original `at`, and only genuinely new lines get
+ * stamped `now`. Order follows the model output (newest last).
+ */
+function stampCheckpoints(texts, prior, nowIso) {
+    const priorAt = new Map((prior ?? []).map((c) => [c.text, c.at]));
+    return texts.map((text) => ({ text, at: priorAt.get(text) ?? nowIso }));
+}
+/**
+ * Run one pass. Returns per-outcome counts. Never throws — a per-session failure
+ * is isolated so one bad transcript can't stall the whole tick.
+ */
+export async function runSummarizerPass(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const config = opts.config ?? resolveSummarizerConfig();
+    const result = { disabled: false, computed: 0, reused: 0, skipped: 0 };
+    if (!isSummarizerRunnable(config)) {
+        result.disabled = true;
+        return result;
+    }
+    let sessions = opts.sessions;
+    if (!sessions) {
+        // Reader-gated like the active-sessions warm tick: no watcher, no work.
+        if (opts.requireReader !== false && !isActiveSessionsJournalReaderRecent(now))
+            return result;
+        sessions = readActiveSessionsCache('local')?.sessions ?? [];
+    }
+    const stat = opts.statFile ?? ((p) => {
+        const s = fs.statSync(p);
+        return { mtimeMs: s.mtimeMs, size: s.size };
+    });
+    const runSummarize = opts.summarizeImpl ?? defaultSummarize;
+    const maxPerTick = opts.maxPerTick ?? SUMMARIZER_MAX_PER_TICK;
+    const nowIso = new Date(now).toISOString();
+    let budget = maxPerTick;
+    for (const s of sessions) {
+        if (opts.signal?.aborted)
+            break;
+        if (budget <= 0)
+            break;
+        const id = s.sessionId;
+        const file = s.sessionFile;
+        if (!id || !file)
+            continue;
+        let stamp;
+        try {
+            const st = stat(file);
+            stamp = { fileMtimeMs: Math.round(st.mtimeMs), fileSize: st.size };
+        }
+        catch {
+            continue; // transcript unreadable this tick — try again next time
+        }
+        // Cached for these exact bytes → never recompute (the core "blazing fast" rule).
+        if (readSessionSummary(id, stamp)) {
+            result.reused++;
+            continue;
+        }
+        budget--;
+        const prompt = (s.firstUserMessage ?? s.topic ?? '').trim();
+        const prior = readSessionSummaryAny(id);
+        if (!prompt) {
+            // No extractable intent yet — cache a skip against these bytes so we don't
+            // re-attempt every tick; a later transcript write (new bytes) retries.
+            writeSessionSummary({ id, ...stamp, summary: { summaryState: 'skipped' } });
+            result.skipped++;
+            continue;
+        }
+        let computed;
+        try {
+            computed = await runSummarize(prompt, { todos: s.todos, plan: s.plan, phase: s.phase }, { baseUrl: config.baseUrl, model: config.model, ...(opts.signal ? { signal: opts.signal } : {}) });
+        }
+        catch {
+            computed = undefined;
+        }
+        if (!computed) {
+            writeSessionSummary({ id, ...stamp, summary: { summaryState: 'skipped' } });
+            result.skipped++;
+            continue;
+        }
+        const entry = {
+            // Goal is computed ONCE at first sight — a prior goal is kept across
+            // progress deltas so it stays stable while checkpoints/checklist refresh.
+            goal: prior?.goal ?? computed.goal,
+            checkpoints: stampCheckpoints(computed.checkpoints, prior?.checkpoints, nowIso),
+            summaryChecklist: computed.checklist,
+            summaryState: 'ready',
+        };
+        writeSessionSummary({ id, ...stamp, summary: entry });
+        result.computed++;
+    }
+    return result;
+}