gennady 0.6.1 → 0.7.1

package/dist/cli/utils/prompts/index.d.ts

@@ -1,14 +1,14 @@
 /**
- * @purpose Централизованный доступ к шаблонам промптов (agent, commit, review) из .md-файлов.
+ * @purpose Centralized access to prompt templates (agent, commit, review) from .md files.
+ * @invariant File names: agent/<name> → agent-{name}-prompt.md, commit → commit-{name}-prompt.md, review → review-{name}-prompt.md.
+ * @sideEffect Filesystem: file read on each call.
  * @consumer CommitGen, ReviewGen, cmd/agent
- * @invariant Имена файлов: agent/<name> → agent-{name}-prompt.md, commit → commit-{name}-prompt.md, review → review-{name}-prompt.md.
- * @sideEffect Filesystem: чтение файла при каждом вызове.
  */
 export declare const prompts: {
-    /** @purpose Загрузить промпт для agent по имени (например 'keywords'). */
+    /** @purpose Load agent prompt by name (e.g. 'keywords'). */
     agent: (name: string) => string;
-    /** @purpose Загрузить промпт для commit по имени ('message' | 'changeset'). */
+    /** @purpose Load commit prompt by name ('message' | 'changeset'). */
     commit: (name: string) => string;
-    /** @purpose Загрузить промпт для review по имени (например 'base'). */
+    /** @purpose Load review prompt by name (e.g. 'base'). */
     review: (name: string) => string;
 };

package/dist/cli/utils/review-gen/review-gen.d.ts

@@ -19,32 +19,56 @@ type SpecMethods = {
 };
 type SpecShape = Record<string, SpecGlobal & SpecMethods>;
 /**
- * @purpose Генерировать ревью кода (критические замечания) через LLM с учётом языковых спеков.
+ * @purpose Generate code review (critical remarks) via LLM considering language specs.
+ * @invariant Uses AiLegacyCore and specs from specs/{lang}; returns empty string on error.
  * @consumer CLI (cmd/review)
- * @invariant Использует AiLegacyCore и specs из specs/{lang}; при ошибке возвращает пустую строку.
  */
 export declare class ReviewGen {
+    /** @purpose Cached language specs loaded from specs directory on first access. */
     protected _langSpecs: Record<string, SpecShape>;
+    /** @purpose Configuration with base prompt template and timeout. */
     protected init: ReviewGenInit & {
         basePromptTemplate: string;
         timeout: number;
         logger?: typeof import('../../../shared/common/logger.ts').logger;
     };
+    /**
+     * @purpose Initialize ReviewGen with configuration and AI core.
+     * @param [init] Configuration overrides (timeout, logger).
+     */
     constructor(init?: ReviewGenInit);
+    /** @purpose Instance of AiLegacyCore for calling LLM. */
     protected _ai: AiLegacyCore;
-    /** @purpose Экземпляр AiLegacyCore для вызова LLM. */
+    /**
+     * @purpose Instance of AiLegacyCore for calling LLM.
+     * @returns AiLegacyCore instance.
+     */
     get ai(): AiLegacyCore;
-    /** @purpose Логгер (если передан при инициализации). */
+    /**
+     * @purpose Logger (if passed during initialization).
+     * @returns Logger instance or undefined.
+     */
     get logger(): typeof import('../../../shared/common/logger.ts').logger | undefined;
     /**
-     * @purpose Сгенерировать текст ревью по коду и списку языков.
-     * @param code Исходный код для анализа.
-     * @param [langs] Языки (по умолчанию выводятся из расширения в code).
-     * @returns Текст ревью от LLM.
-     * @sideEffect Network: запрос к AI; Filesystem: чтение specs при первом обращении.
+     * @purpose Generate review text from code and list of languages.
+     * @param code Source code for analysis.
+     * @param [langs] Languages (default derived from extension in code).
+     * @returns Review text from LLM.
+     * @sideEffect Network: request to AI; Filesystem: reading specs on first access.
      */
     generate(code: string, langs?: string[]): Promise<string>;
+    /**
+     * @purpose Build extra rules prompt from language specs matching the code under review.
+     * @param langs List of programming language names.
+     * @param code Source code to scan for known constructs.
+     * @returns Extra rules prompt string (empty if no matches found).
+     */
     protected _getExtraRulesPrompt(langs: string[], code: string): string;
+    /**
+     * @purpose Load and cache language specs from JSON files in the specs directory.
+     * @param langs List of programming language names.
+     * @returns Merged spec shape for all requested languages.
+     */
     protected _loadSpec(langs: string[]): SpecShape;
 }
 export {};

package/dist/gennady.js

@@ -1,28 +1,48 @@
 #!/usr/bin/env node
-const e = /* @__PURE__ */ new Set(["help", "--help", "-h"]), a = process.argv[2];
-(!a || e.has(a)) && (await import("./chunks/help.cmd-CWasx25o.js"), process.exit(0));
+import { c as e } from "./chunks/shared-COpFaV-w.js";
+import "node:fs";
+import "node:path";
+import "node:url";
+const i = "0.7.1", t = /* @__PURE__ */ new Set(["help", "--help", "-h"]), a = process.argv[2];
+(!a || t.has(a)) && (await import("./chunks/help.cmd-B_G7EWzF.js"), process.exit(0));
+e({ name: "gennady", version: i });
 switch (a) {
   case "cat":
-    await import("./chunks/index-C4jt5WBP.js");
+    await import("./chunks/index-DeYzAoxF.js");
     break;
   case "review":
-    await import("./chunks/index-Bh0p7rJg.js");
+    await import("./chunks/index-BCqnKvNZ.js");
     break;
   case "vcs-reply":
-    await import("./chunks/index-Bx_P7mlL.js");
+    await import("./chunks/index-BzBhCTHq.js");
     break;
   case "review-verify":
-    await import("./chunks/index-B3r-YFvt.js");
+    await import("./chunks/index-CAWs-GED.js");
     break;
   case "review-issues":
-    await import("./chunks/index-Gy1n7hRU.js");
+    await import("./chunks/index-BLsDffzZ.js");
     break;
   case "resolve-conflicts":
-    await import("./chunks/index-DgAmONSz.js");
+    await import("./chunks/index-BsD-J44e.js");
     break;
   case "commit":
-    await import("./chunks/index-D1Hurfwu.js");
+    await import("./chunks/index-BrSutH7l.js");
+    break;
+  case "remote-console":
+    await import("./chunks/index-O5kqC9i_.js");
+    break;
+  case "lint":
+    await import("./chunks/index-TX0TmKeu.js");
+    break;
+  case "alt-opinion":
+    await import("./chunks/index-CFd_iufb.js");
+    break;
+  case "agent-mon":
+    await import("./chunks/index-Bq4d25CK.js");
+    break;
+  case "sync":
+    await import("./chunks/index-Db09OODV.js");
     break;
   default:
-    await import("./chunks/help.cmd-CWasx25o.js"), process.exit(0);
+    await import("./chunks/help.cmd-B_G7EWzF.js"), process.exit(0);
 }

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from './shared/backend/rc/rc-config.js';
 export * from './shared/common/unguard.js';
 export * from './shared/backend/git/git-diff.js';
 export * from './shared/common/language.js';
+export * from './services/remote-console/remote-console.js';

package/dist/index.js

@@ -1,9 +1,10 @@
-import { u, r as m } from "./chunks/shared-D0kSJB49.js";
-import { G as y, h as d, i as A, j as f, k as w } from "./chunks/shared-D0kSJB49.js";
+import { u, r as m } from "./chunks/shared-COpFaV-w.js";
+import { G as y, i as d, j as A, k as f, m as R } from "./chunks/shared-COpFaV-w.js";
+import { R as C, f as O, r as T, g as L, c as $ } from "./chunks/services-Dnk3nB2x.js";
 class h {
   /**
-   * @purpose Создать экземпляр с дефолтными настройками (Ollama local).
-   * @returns Экземпляр с model=llama3.1:8b, url=localhost:11434.
+   * @purpose Create an instance with default settings (Ollama local).
+   * @returns Instance with model=llama3.1:8b, url=localhost:11434.
    */
   static getDefault() {
     return new h({
@@ -11,8 +12,14 @@ class h {
       url: "http://127.0.0.1:11434/api/generate"
     });
   }
+  /** @purpose Model initialization config with name, URL, and key. */
   _init;
+  /** @purpose Cached ping promise to avoid duplicate pings. */
   _pingPromise = null;
+  /**
+   * @purpose Create an AI model instance with the given configuration.
+   * @param init Partial initialization config (model, url, key, extra).
+   */
   constructor(n) {
     this._init = {
       model: n.model ?? "llama3.1:8b",
@@ -20,23 +27,32 @@ class h {
       ...n
     };
   }
-  /** @purpose Имя модели (для логов и заголовков). */
+  /**
+   * @purpose Model name (for logs and headers).
+   * @returns Model name string.
+   */
   get name() {
     return this._init.model;
   }
-  /** @purpose URL эндпоинта API. */
+  /**
+   * @purpose API endpoint URL.
+   * @returns API URL string.
+   */
   get url() {
     return this._init.url;
   }
-  /** @purpose API-ключ (если требуется авторизация). */
+  /**
+   * @purpose API key (if authorization is required).
+   * @returns API key string or undefined.
+   */
   get key() {
     return this._init.key;
   }
   /**
-   * @purpose Проверить доступность модели коротким запросом.
-   * @param [timeout] Таймаут в мс (по умолчанию 10e3).
-   * @returns Кортеж [true, null] при успехе, [null, Error] при сбое.
-   * @sideEffect Network: один запрос к API; Logs: debug/error.
+   * @purpose Check model availability with a short request.
+   * @param [timeout] Timeout in ms (default 10e3).
+   * @returns Tuple [true, null] on success, [null, Error] on failure.
+   * @sideEffect Network: single request to API; Logs: debug/error.
    */
   async ping(n = 1e4) {
     return this._pingPromise ??= (async () => {
@@ -56,11 +72,11 @@ class h {
     })(), this._pingPromise;
   }
   /**
-   * @purpose Отправить промпт в LLM и получить ответ (с подстановкой __KEY__ и удалением think-блоков).
-   * @param prompt Текст запроса пользователя.
-   * @param [init] system, temperature, timeout, replacements для подстановки в промпт/system.
-   * @returns Кортеж [текст ответа, null] при успехе, [null, Error] при ошибке сети/парсинга.
-   * @sideEffect Network: POST к this.url.
+   * @purpose Send a prompt to the LLM and get a response (with __KEY__ substitution and think-block removal).
+   * @param prompt User prompt text.
+   * @param [init] system, temperature, timeout, replacements for substitution in prompt/system.
+   * @returns Tuple [response text, null] on success, [null, Error] on network/parsing error.
+   * @sideEffect Network: POST to this.url.
    */
   async generate(n, r = {}) {
     try {
@@ -99,11 +115,11 @@ class h {
     }
   }
   /**
-   * @purpose Выполнить POST-запрос к API и вернуть JSON или ошибку.
-   * @param params Тело запроса (Ollama- или OpenAI-формат).
-   * @param [timeout] Таймаут в мс.
-   * @returns Кортеж [parsed JSON, null] или [null, Error].
-   * @sideEffect Network: fetch с AbortController.
+   * @purpose Execute a POST request to the API and return JSON or an error.
+   * @param params Request body (Ollama or OpenAI format).
+   * @param [timeout] Timeout in ms.
+   * @returns Tuple [parsed JSON, null] or [null, Error].
+   * @sideEffect Network: fetch with AbortController.
    */
   async _fetchAsJson(n, r = 12e4) {
     const e = new AbortController(), o = setTimeout(
@@ -155,9 +171,14 @@ class h {
 export {
   h as AiLegacyModel,
   y as GennadyRc,
+  C as RemoteConsoleStdoutWriter,
+  O as connectRemoteConsoleClient,
   d as getProgrammingLanguage,
   A as getSysLang,
   f as parseGitDiff,
-  w as unguard,
+  T as remoteConsoleClient,
+  L as serializeRemoteConsoleArg,
+  $ as startRemoteConsoleServer,
+  R as unguard,
   u as unguardOrThrow
 };

package/dist/services/agent-mon/diff/diff.d.ts

@@ -0,0 +1,9 @@
+import type { AgentSession } from '../model/agent-session.type.js';
+import type { SessionChanges } from '../model/session-changes.type.js';
+/**
+ * @purpose Compare two AgentSession snapshots and produce added, removed, updated change categories.
+ * @param prev Previous snapshot of sessions — may be empty.
+ * @param curr Current snapshot of sessions — may be empty.
+ * @returns SessionChanges with sessions partitioned by change type (all arrays may be empty).
+ */
+export declare function diff(prev: AgentSession[], curr: AgentSession[]): SessionChanges;

package/dist/services/agent-mon/diff/index.d.ts

@@ -0,0 +1 @@
+export { diff } from './diff.js';

package/dist/services/agent-mon/index.d.ts

@@ -0,0 +1,10 @@
+export { createMonitor } from './monitor/index.js';
+export { diff } from './diff/index.js';
+export { observe } from './observe/index.js';
+export type { AgentSession } from './model/index.js';
+export type { SessionChanges } from './model/index.js';
+export type { ScanOpts } from './model/index.js';
+export type { ObserveOpts } from './model/index.js';
+export type { AgentProvider } from './model/index.js';
+export { DuplicateProviderError } from './model/index.js';
+export { ProviderNotFoundError } from './model/index.js';

package/dist/services/agent-mon/model/agent-provider.type.d.ts

@@ -0,0 +1,20 @@
+import type { AgentSession } from './agent-session.type.js';
+import type { ScanOpts } from './scan-opts.type.js';
+/**
+ * @purpose Contract for agent session providers — single extension point for new agent systems.
+ * @invariant Scan is stateless: calling scan() does not change provider state.
+ * @invariant Error policy: scan failures return empty array ([]), never propagate to scanAll() — graceful degradation.
+ * @invariant Read-only: scan() must not write to the source data.
+ */
+export interface AgentProvider {
+    /** @purpose Unique provider key for registration | @invariant Non-empty string, unique per AgentMonitor */
+    readonly key: string;
+    /**
+     * @purpose Scan the provider's source and return normalized agent sessions.
+     * @param [opts] Optional scan filtering parameters.
+     * @throws Never — failures return [] per graceful degradation contract.
+     * @returns Normalized agent sessions (may be empty).
+     * @sideEffect Read access to provider's data source (filesystem, database).
+     */
+    scan(opts?: ScanOpts): Promise<AgentSession[]>;
+}

package/dist/services/agent-mon/model/agent-session.type.d.ts

@@ -0,0 +1,49 @@
+/** @purpose Normalized representation of an agent session across all providers. */
+export type AgentSession = {
+    /** @purpose Provider key this session belongs to | @invariant Non-empty string, unique per AgentMonitor */
+    provider: string;
+    /** @purpose Process ID | @invariant null for providers without OS process (OpenCode) */
+    pid: number | null;
+    /** @purpose Unique session identifier */
+    sessionId: string;
+    /** @purpose Parent session ID for subagent chains | @invariant V1 optional, tree deferred to V2 */
+    parentId?: string;
+    /** @purpose Display title of the session */
+    title: string;
+    /** @purpose Human-readable slug identifier | @invariant OpenCode-specific, absent in Claude */
+    slug?: string;
+    /** @purpose Working directory of the session */
+    cwd: string;
+    /** @purpose Project name derived from cwd | @invariant basename of working directory */
+    project: string;
+    /** @purpose AI model used in the session */
+    model?: string;
+    /** @purpose Agent kind identifier */
+    agent?: string;
+    /** @purpose Current lifecycle state | @invariant 'active' — process alive, 'idle' — no activity > threshold, 'completed' — process dead or archived */
+    status: 'active' | 'idle' | 'completed';
+    /** @purpose Session start timestamp | @invariant Epoch milliseconds */
+    startedAt: number;
+    /** @purpose Session completion timestamp | @invariant Epoch milliseconds */
+    completedAt?: number;
+    /** @purpose Last activity timestamp | @invariant Epoch milliseconds */
+    lastActivityAt?: number;
+    /** @purpose Total elapsed time | @invariant Seconds */
+    elapsedSeconds: number;
+    /** @purpose Idle time since last activity | @invariant Seconds, computed from lastActivityAt */
+    idleSeconds?: number;
+    /** @purpose CPU usage percentage | @invariant Claude-only, absent for OpenCode */
+    cpuPercent?: number;
+    /** @purpose Memory usage in megabytes | @invariant Claude-only, absent for OpenCode */
+    memoryMb?: number;
+    /** @purpose Total tool call count */
+    toolCallCount?: number;
+    /** @purpose Total error count */
+    errorCount?: number;
+    /** @purpose Last message content, truncated | @invariant Truncated for display, not full text */
+    lastMessage?: string;
+    /** @purpose Input token count | @invariant OpenCode-specific */
+    tokensInput?: number;
+    /** @purpose Output token count | @invariant OpenCode-specific */
+    tokensOutput?: number;
+};

package/dist/services/agent-mon/model/errors.d.ts

@@ -0,0 +1,20 @@
+/** @purpose Raised when attempting to register a provider with a key already in use. */
+export declare class DuplicateProviderError extends Error {
+    /** @purpose The conflicting provider key */
+    readonly key: string;
+    /**
+     * @purpose Construct with the duplicate key and a trace-prefixed message.
+     * @param key The provider key that is already registered.
+     */
+    constructor(key: string);
+}
+/** @purpose Raised when attempting to access a provider that is not registered. */
+export declare class ProviderNotFoundError extends Error {
+    /** @purpose The missing provider key */
+    readonly key: string;
+    /**
+     * @purpose Construct with the missing key and a trace-prefixed message.
+     * @param key The provider key that was not found.
+     */
+    constructor(key: string);
+}

package/dist/services/agent-mon/model/index.d.ts

@@ -0,0 +1,7 @@
+export type { AgentSession } from './agent-session.type.js';
+export type { SessionChanges } from './session-changes.type.js';
+export type { ScanOpts } from './scan-opts.type.js';
+export type { ObserveOpts } from './observe-opts.type.js';
+export type { AgentProvider } from './agent-provider.type.js';
+export { DuplicateProviderError } from './errors.js';
+export { ProviderNotFoundError } from './errors.js';

package/dist/services/agent-mon/model/observe-opts.type.d.ts

@@ -0,0 +1,7 @@
+/** @purpose Configuration for the observe polling cycle. */
+export type ObserveOpts = {
+    /** @purpose Polling interval in milliseconds */
+    interval: number;
+    /** @purpose Idle detection threshold in milliseconds | @invariant Default 300000 when absent */
+    idleThresholdMs?: number;
+};

package/dist/services/agent-mon/model/scan-opts.type.d.ts

@@ -0,0 +1,7 @@
+/** @purpose Filtering options for session scanning. */
+export type ScanOpts = {
+    /** @purpose Return sessions started after this timestamp or today's date | @invariant Epoch ms or the string 'today' */
+    since?: number | 'today';
+    /** @purpose Idle detection threshold in milliseconds | @invariant Default 300000 (5 min) when absent */
+    idleThresholdMs?: number;
+};

package/dist/services/agent-mon/model/session-changes.type.d.ts

@@ -0,0 +1,10 @@
+import type { AgentSession } from './agent-session.type.js';
+/** @purpose Result of comparing two session snapshots — what appeared, disappeared, or changed. */
+export type SessionChanges = {
+    /** @purpose Sessions present in current but absent in previous */
+    added: AgentSession[];
+    /** @purpose Sessions present in previous but absent in current */
+    removed: AgentSession[];
+    /** @purpose Sessions present in both but with semantic fields changed */
+    updated: AgentSession[];
+};

package/dist/services/agent-mon/monitor/agent-monitor.d.ts

@@ -0,0 +1,44 @@
+import type { AgentProvider } from '../model/agent-provider.type.js';
+import type { AgentSession } from '../model/agent-session.type.js';
+import type { ScanOpts } from '../model/scan-opts.type.js';
+/**
+ * @purpose Provider registry and scan coordination — owns the provider map, orchestrates scanning across all registered providers.
+ * @invariant Undamaged-by-one: provider failure in scanAll does not interrupt remaining providers (graceful degradation per N3).
+ * @invariant Stateless scans: no caching between calls; each scanAll / scanOne is a fresh invocation.
+ */
+/** @implements {AgentMonitor} in specs/agent-mon/monitor/monitor.spec.md#agentmonitor */
+export declare class AgentMonitor {
+    /** @purpose Provider registry — maps string keys to AgentProvider instances | @invariant Empty on construction; mutated only via register/unregister */
+    protected readonly _providers: Map<string, AgentProvider>;
+    /**
+     * @purpose Register a provider under a unique key; rejects on duplicate.
+     * @param key Unique provider identifier — non-empty string.
+     * @param provider The provider instance implementing AgentProvider.
+     * @throws {DuplicateProviderError} When key is already registered.
+     * @post Provider is stored in the registry under the given key.
+     */
+    register(key: string, provider: AgentProvider): void;
+    /**
+     * @purpose Remove a provider from the registry; no-op when the key is not found.
+     * @param key Provider key to remove.
+     * @post Provider with the given key is no longer in the registry.
+     */
+    unregister(key: string): void;
+    /**
+     * @purpose Scan all registered providers concurrently, aggregate and sort results by startedAt descending.
+     * @invariant Graceful degradation: a failing provider returns [] and does not abort other providers.
+     * @param [opts] Optional scan filtering (since timestamp or 'today').
+     * @returns All sessions from all providers, sorted by startedAt descending.
+     * @sideEffect Calls each registered provider's scan() — may read filesystem / database.
+     */
+    scanAll(opts?: ScanOpts): Promise<AgentSession[]>;
+    /**
+     * @purpose Scan a single provider by key; rejects when the provider is not registered.
+     * @param key Registered provider key.
+     * @param [opts] Optional scan filtering.
+     * @throws {ProviderNotFoundError} When the key is not registered.
+     * @returns Sessions from the specified provider.
+     * @sideEffect Calls the provider's scan() — may read filesystem / database.
+     */
+    scanOne(key: string, opts?: ScanOpts): Promise<AgentSession[]>;
+}

package/dist/services/agent-mon/monitor/create-monitor.d.ts

@@ -0,0 +1,6 @@
+import { AgentMonitor } from './agent-monitor.js';
+/**
+ * @purpose Create a fresh AgentMonitor instance with an empty provider registry.
+ * @returns A new AgentMonitor ready for provider registration.
+ */
+export declare function createMonitor(): AgentMonitor;

package/dist/services/agent-mon/monitor/index.d.ts

@@ -0,0 +1,2 @@
+export { AgentMonitor } from './agent-monitor.js';
+export { createMonitor } from './create-monitor.js';

package/dist/services/agent-mon/observe/index.d.ts

@@ -0,0 +1 @@
+export { observe } from './observe.js';

package/dist/services/agent-mon/observe/observe.d.ts

@@ -0,0 +1,12 @@
+import type { AgentMonitor } from '../monitor/agent-monitor.js';
+import type { ObserveOpts } from '../model/observe-opts.type.js';
+import type { SessionChanges } from '../model/session-changes.type.js';
+/**
+ * @purpose Continuous async iterable yielding session changes at a configurable interval.
+ * @param monitor AgentMonitor instance with registered providers — used for scanAll() each cycle.
+ * @param opts Observation options: interval (≥100ms), idleThresholdMs (default 300000).
+ * @throws {RangeError} When opts.interval < 100 — contract violation per DbC.
+ * @returns AsyncIterable yielding SessionChanges after each poll cycle; first iteration establishes baseline and does NOT yield.
+ * @sideEffect Polling: calls monitor.scanAll() per cycle; uses setTimeout for non-blocking delay.
+ */
+export declare function observe(monitor: AgentMonitor, opts: ObserveOpts): AsyncIterable<SessionChanges>;

package/dist/services/agent-mon/providers/claude/claude-provider.d.ts

@@ -0,0 +1,50 @@
+import { logger } from '#logger';
+import type { AgentSession } from '../../model/agent-session.type.js';
+import type { ScanOpts } from '../../model/scan-opts.type.js';
+import type { AgentProvider } from '../../model/agent-provider.type.js';
+import { psInfo as defaultPsInfo, parseClaudeArgs as defaultParseClaudeArgs } from './ps.js';
+import { readSessionJson as defaultReadSessionJson, readSessionTitle as defaultReadSessionTitle } from './session-json.js';
+/** @purpose DI-injectable dependencies for ClaudeProvider — enables test mocking without global monkey-patching. */
+type ClaudeProviderDeps = {
+    /** @purpose Batch ps inspection function */
+    psInfo?: typeof defaultPsInfo;
+    /** @purpose Claude CLI argument parser */
+    parseClaudeArgs?: typeof defaultParseClaudeArgs;
+    /** @purpose Session JSON file reader */
+    readSessionJson?: typeof defaultReadSessionJson;
+    /** @purpose Session title extractor from JSONL */
+    readSessionTitle?: typeof defaultReadSessionTitle;
+};
+/**
+ * @purpose Adapter scanning Claude Code sessions from ~/.claude/sessions/.
+ * @implements {AgentProvider} in ../../model/agent-provider.type.ts
+ * @invariant Stateless — every scan() call is independent.
+ * @invariant Graceful degradation: missing sessions dir or ps failure returns [], never throws.
+ * @invariant Batch ps: one spawn per scan (not per PID).
+ */
+export declare class ClaudeProvider implements AgentProvider {
+    /** @see {AgentProvider#key} in ../../model/agent-provider.type.ts */
+    readonly key: 'claude';
+    /** @purpose Batch ps inspection function */
+    protected _psInfo: typeof defaultPsInfo;
+    /** @purpose Claude CLI argument parser */
+    protected _parseClaudeArgs: typeof defaultParseClaudeArgs;
+    /** @purpose Session JSON file reader */
+    protected _readSessionJson: typeof defaultReadSessionJson;
+    /** @purpose Session title extractor from JSONL */
+    protected _readSessionTitle: typeof defaultReadSessionTitle;
+    /** @purpose Logger instance */
+    protected _logger: typeof logger;
+    /**
+     * @purpose Construct with optional DI overrides for testing.
+     * @param [deps] Injectable function replacements; omitted deps use real implementations.
+     */
+    constructor(deps?: ClaudeProviderDeps);
+    /**
+     * @param [opts] Optional scan filtering parameters.
+     * @returns Parsed agent sessions array.
+     * @see {AgentProvider#scan} in ../../model/agent-provider.type.ts
+     */
+    scan(opts?: ScanOpts): Promise<AgentSession[]>;
+}
+export {};

package/dist/services/agent-mon/providers/claude/index.d.ts

@@ -0,0 +1,5 @@
+export { ClaudeProvider } from './claude-provider.js';
+export { psInfo, parseClaudeArgs } from './ps.js';
+export type { PsInfoEntry } from './ps.js';
+export { readSessionJson, readSessionTitle } from './session-json.js';
+export type { SessionJsonData } from './session-json.js';

package/dist/services/agent-mon/providers/claude/ps.d.ts

@@ -0,0 +1,36 @@
+/** @purpose Result of a batch ps query for a single alive process. */
+export type PsInfoEntry = {
+    /** @purpose Process ID */
+    pid: number;
+    /** @purpose CPU usage percentage */
+    cpuPercent: number;
+    /** @purpose Memory usage in megabytes | @invariant Converted from RSS KB: rss / 1024 */
+    memoryMb: number;
+    /** @purpose Full command-line arguments of the process */
+    args: string;
+};
+/**
+ * @purpose Batch process inspection: one ps spawn for all PIDs — returns alive processes only.
+ * @invariant Single `ps -p` call regardless of PID count; dead PIDs are absent from the result Map.
+ * @invariant On ps command failure: warn-log and return empty Map — graceful degradation.
+ * @param pids Array of process IDs to inspect.
+ * @returns Map of pid → PsInfoEntry for alive processes; empty Map if no PIDs or ps fails.
+ * @sideEffect Process: spawns `ps` via execSync.
+ */
+export declare function psInfo(pids: number[]): Map<number, PsInfoEntry>;
+/**
+ * @purpose Extract --model and --effort values from Claude process command-line arguments.
+ * @param args Full command-line arguments string from ps.
+ * @returns Parsed model and effort strings (undefined when absent).
+ */
+export declare function parseClaudeArgs(args: string): {
+    model?: string;
+    effort?: string;
+};
+/**
+ * @purpose Extract a context hint from Claude process args — uses Read/Edit allowed paths.
+ * @invariant Returns the most specific path segment from allowedTools, or undefined.
+ * @param args Full ps command-line string.
+ * @returns Short context description, e.g. "sdd/directives" or undefined.
+ */
+export declare function parseContextHint(args: string): string | undefined;

package/dist/services/agent-mon/providers/claude/session-json.d.ts

@@ -0,0 +1,37 @@
+/** @purpose Parsed data from a Claude session JSON file (sessions/PID.json). */
+export type SessionJsonData = {
+    /** @purpose Process ID of the Claude session */
+    pid: number;
+    /** @purpose Unique session identifier */
+    sessionId: string;
+    /** @purpose Working directory of the session */
+    cwd: string;
+    /** @purpose Session start timestamp | @invariant Epoch milliseconds */
+    startedAt: number;
+};
+/**
+ * @purpose Read and parse a Claude session JSON file from ~/.claude/sessions/PID.json.
+ * @invariant Validates presence of required fields (pid, sessionId, cwd, startedAt); returns null on missing fields.
+ * @invariant On parse failure: error-log and return null — does not throw.
+ * @param filePath Absolute path to the session JSON file.
+ * @returns Parsed session data or null when file is invalid or unreadable.
+ * @sideEffect Filesystem: readFileSync on the session JSON file.
+ */
+export declare function readSessionJson(filePath: string): SessionJsonData | null;
+/**
+ * @purpose Extract session title from Claude JSONL project file.
+ * @invariant cwd path encoding: '/' replaced with '-', leading '-' stripped — matches Claude project directory naming.
+ * @invariant Priority: ai-title entry > first user message > 'Unknown' fallback.
+ * @param cwd Working directory of the session.
+ * @param sessionId Unique session identifier.
+ * @returns Session title string; 'Unknown' when JSONL is missing or unparseable.
+ * @sideEffect Filesystem: existsSync + readFileSync on ~/.claude/projects/.../<sessionId>.jsonl.
+ */
+export declare function readSessionTitle(cwd: string, sessionId: string): string;
+/**
+ * @purpose Read active task title from ~/.claude/tasks/<sessionId>/ as fallback when JSONL is missing.
+ * @invariant Returns the subject of the first in-progress task, or the first task overall.
+ * @param sessionId Unique session identifier.
+ * @returns Active task subject or 'Unknown' when no tasks directory exists.
+ */
+export declare function readActiveTaskTitle(sessionId: string): string;