@adhdev/daemon-core 0.9.82-rc.44 → 0.9.82-rc.441

package/src/providers/provider-schema.ts

@@ -37,6 +37,12 @@ const KNOWN_PROVIDER_FIELDS = new Set<string>([
   'approvalPositiveHints',
   'sessionIdPattern',
   'historyBehavior',
+  // v1 canonical field name. The loader fills this in for legacy v0
+  // manifests that ship the old `canonicalHistory` spelling.
+  'nativeHistory',
+  // Deprecated v0 alias for `nativeHistory`. Kept in the allowed-keys
+  // list so legacy provider.json manifests don't trip the unknown-key
+  // warning during the one-release deprecation window.
   'canonicalHistory',
   'autoFixProfile',
   'ideLevelScripts',
@@ -64,6 +70,8 @@ const KNOWN_PROVIDER_FIELDS = new Set<string>([
   'sendKey',
   'submitStrategy',
   'requirePromptEchoBeforeSubmit',
+  'requiresFinalAssistantBeforeIdle',
+  'augmentStaleSnapshot',
   'timeouts',
   'disableUpstream',
 ])
@@ -128,7 +136,7 @@ export function validateProviderDefinition(raw: unknown): ProviderValidationResu
   }
 
   validateCapabilities(provider as unknown as ProviderModule, controls, errors)
-  validateCanonicalHistory(provider.canonicalHistory, errors)
+  validateNativeHistory(provider.nativeHistory, errors)
   validateMeshCoordinator(provider.meshCoordinator, errors)
 
   for (const control of controls) {
@@ -228,33 +236,43 @@ function validateCapabilities(provider: ProviderModule, controls: ProviderContro
   }
 }
 
-function validateCanonicalHistory(raw: unknown, errors: string[]): void {
+function validateNativeHistory(raw: unknown, errors: string[]): void {
   if (raw === undefined) return
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    errors.push('canonicalHistory must be an object')
+    errors.push('nativeHistory must be an object')
     return
   }
 
-  const canonicalHistory = raw as Record<string, unknown>
-  const format = canonicalHistory.format
+  const nativeHistory = raw as Record<string, unknown>
+  const format = nativeHistory.format
   if (format !== undefined && (typeof format !== 'string' || !format.trim())) {
-    errors.push('canonicalHistory.format must be a non-empty string when provided')
+    errors.push('nativeHistory.format must be a non-empty string when provided')
   }
 
-  const watchPath = canonicalHistory.watchPath
+  const watchPath = nativeHistory.watchPath
   if (watchPath !== undefined && (typeof watchPath !== 'string' || !watchPath.trim())) {
-    errors.push('canonicalHistory.watchPath must be a non-empty string when provided')
+    errors.push('nativeHistory.watchPath must be a non-empty string when provided')
   }
 
-  const mode = canonicalHistory.mode
+  const mode = nativeHistory.mode
   if (mode !== undefined && !['native-source', 'materialized-mirror', 'disabled'].includes(String(mode))) {
-    errors.push('canonicalHistory.mode must be one of: native-source, materialized-mirror, disabled')
+    errors.push('nativeHistory.mode must be one of: native-source, materialized-mirror, disabled')
   }
 
-  const scripts = canonicalHistory.scripts
+  // Chat transcript contract version (transcript-v2.ts). Absent → treated as
+  // v1 by readDeclaredChatContractVersion(). A2 will reject unrecognised
+  // values at load time; A1 only validates the field shape.
+  const chatContractVersion = nativeHistory.contractVersion
+  if (chatContractVersion !== undefined
+      && chatContractVersion !== '1.0'
+      && chatContractVersion !== '2.0') {
+    errors.push(`nativeHistory.contractVersion must be '1.0' or '2.0' when provided (got ${JSON.stringify(chatContractVersion)})`)
+  }
+
+  const scripts = nativeHistory.scripts
   if (scripts === undefined) return
   if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts)) {
-    errors.push('canonicalHistory.scripts must be an object')
+    errors.push('nativeHistory.scripts must be an object')
     return
   }
 
@@ -262,7 +280,7 @@ function validateCanonicalHistory(raw: unknown, errors: string[]): void {
   for (const key of ['readSession', 'listSessions']) {
     const value = scriptConfig[key]
     if (typeof value !== 'string' || !value.trim()) {
-      errors.push(`canonicalHistory.scripts.${key} must be a non-empty string`)
+      errors.push(`nativeHistory.scripts.${key} must be a non-empty string`)
     }
   }
 }
@@ -282,7 +300,11 @@ function validateMeshCoordinator(raw: unknown, errors: string[]): void {
     errors.push('meshCoordinator.reason must be a non-empty string when provided')
   }
 
-  const mcpConfig = meshCoordinator.mcpConfig
+  validateMeshCoordinatorMcpConfig(meshCoordinator.mcpConfig, errors)
+  validateMeshCoordinatorDelegatedWorkerIsolation(meshCoordinator.delegatedWorkerIsolation, errors)
+}
+
+function validateMeshCoordinatorMcpConfig(mcpConfig: unknown, errors: string[]): void {
   if (mcpConfig === undefined) return
   if (!mcpConfig || typeof mcpConfig !== 'object' || Array.isArray(mcpConfig)) {
     errors.push('meshCoordinator.mcpConfig must be an object')
@@ -330,6 +352,57 @@ function validateMeshCoordinator(raw: unknown, errors: string[]): void {
   }
 }
 
+function validateMeshCoordinatorDelegatedWorkerIsolation(raw: unknown, errors: string[]): void {
+  if (raw === undefined) return
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    errors.push('meshCoordinator.delegatedWorkerIsolation must be an object')
+    return
+  }
+  const isolation = raw as Record<string, unknown>
+  const env = isolation.env
+  if (env !== undefined) {
+    if (!env || typeof env !== 'object' || Array.isArray(env)) {
+      errors.push('meshCoordinator.delegatedWorkerIsolation.env must be an object')
+    } else {
+      const unset = (env as Record<string, unknown>).unset
+      if (unset !== undefined && (!Array.isArray(unset) || unset.some((key) => typeof key !== 'string' || !key.trim()))) {
+        errors.push('meshCoordinator.delegatedWorkerIsolation.env.unset must be an array of non-empty strings')
+      }
+    }
+  }
+  const args = isolation.args
+  if (args === undefined) return
+  if (!Array.isArray(args)) {
+    errors.push('meshCoordinator.delegatedWorkerIsolation.args must be an array')
+    return
+  }
+  for (const [index, rule] of args.entries()) {
+    const prefix = `meshCoordinator.delegatedWorkerIsolation.args[${index}]`
+    if (!rule || typeof rule !== 'object' || Array.isArray(rule)) {
+      errors.push(`${prefix} must be an object`)
+      continue
+    }
+    const item = rule as Record<string, unknown>
+    const mode = item.mode
+    if (mode !== 'empty_mcp_config' && mode !== 'config_override') {
+      errors.push(`${prefix}.mode must be one of: empty_mcp_config, config_override`)
+      continue
+    }
+    for (const key of mode === 'empty_mcp_config' ? ['flag'] : ['flag', 'key', 'value']) {
+      const value = item[key]
+      if (typeof value !== 'string' || !value.trim()) {
+        errors.push(`${prefix}.${key} must be a non-empty string`)
+      }
+    }
+    for (const key of ['strictFlag', 'dedupeKey']) {
+      const value = item[key]
+      if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
+        errors.push(`${prefix}.${key} must be a non-empty string when provided`)
+      }
+    }
+  }
+}
+
 function validateControl(control: ProviderControlDef, errors: string[]): void {
   if (!control || typeof control !== 'object') {
     errors.push('controls: each control must be an object')

package/src/providers/provider-trust.ts

@@ -0,0 +1,114 @@
+/**
+ * Provider trust classification.
+ *
+ * Each loaded provider gets a `trust` tag that the daemon and dashboard
+ * use to decide what to surface and what to gate behind a confirmation
+ * prompt. Trust is a function of *where* the provider came from
+ * (upstream / external / userDir) and the *shape of the manifest*
+ * (spec-only vs. carries JavaScript hooks).
+ *
+ * Rationale:
+ *   - Spec-only manifests are static declarative configuration; the
+ *     daemon's spec adapter walks the spec but never executes code
+ *     authored by the provider.
+ *   - Non-spec manifests ship JavaScript (tui-block builders consumed
+ *     by the SDK, scriptDir overrides, or explicit `overrides.* .path`
+ *     bindings). That code runs inside the daemon process with the
+ *     same privileges as adhdev itself.
+ *
+ * Source × shape decides the trust label:
+ *
+ *   layer    | spec-only           | non-spec
+ *   ---------|---------------------|-----------------------
+ *   user     | user-custom         | user-custom
+ *   upstream | trusted             | trusted-with-scripts
+ *   external | external-safe       | external-untrusted
+ *
+ * Dashboards should always show a badge for `trusted-with-scripts`
+ * (info — runs official JS), `external-safe` (info — declarative only,
+ * but 3rd-party), and `external-untrusted` (warning — runs JS from a
+ * 3rd-party). Activation of `external-untrusted` should require an
+ * explicit confirmation step that names the source URL.
+ */
+'use strict';
+
+export type ProviderTrust =
+    | 'user-custom'
+    | 'trusted'
+    | 'trusted-with-scripts'
+    | 'external-safe'
+    | 'external-untrusted';
+
+export type ProviderLayer = 'user' | 'upstream' | 'external';
+
+export interface ProviderManifestShape {
+    /** Has a `tui` block — SDK builders consume it as code paths. */
+    hasTui: boolean;
+    /** Has a non-empty `overrides` object — JS override paths. */
+    hasOverrides: boolean;
+    /** compatibility[].scriptDir or defaultScriptDir is set — JS scripts dir. */
+    hasScriptDir: boolean;
+}
+
+/**
+ * Inspect a manifest to decide whether it ships JavaScript hooks.
+ * Cheap; pure; safe to call on every provider load.
+ */
+export function inspectManifestShape(manifest: Record<string, unknown>): ProviderManifestShape {
+    const hasTui = !!manifest.tui && typeof manifest.tui === 'object'
+        && Object.keys(manifest.tui as Record<string, unknown>).length > 0;
+    const hasOverrides = !!manifest.overrides && typeof manifest.overrides === 'object'
+        && !Array.isArray(manifest.overrides)
+        && Object.keys(manifest.overrides as Record<string, unknown>).length > 0;
+    const compat = Array.isArray(manifest.compatibility) ? manifest.compatibility : [];
+    const compatHasScriptDir = compat.some((entry: any) => typeof entry?.scriptDir === 'string');
+    const hasScriptDir = compatHasScriptDir || typeof manifest.defaultScriptDir === 'string';
+    return { hasTui, hasOverrides, hasScriptDir };
+}
+
+/**
+ * Classify trust given the layer the provider was loaded from + the
+ * manifest's JS-hook footprint.
+ */
+export function classifyTrust(
+    layer: ProviderLayer,
+    shape: ProviderManifestShape,
+): ProviderTrust {
+    const isSpecOnly = !shape.hasTui && !shape.hasOverrides && !shape.hasScriptDir;
+    switch (layer) {
+        case 'user':
+            return 'user-custom';
+        case 'upstream':
+            return isSpecOnly ? 'trusted' : 'trusted-with-scripts';
+        case 'external':
+            return isSpecOnly ? 'external-safe' : 'external-untrusted';
+    }
+}
+
+/**
+ * Returns true when activation should require an explicit user confirm.
+ * Today only `external-untrusted` qualifies; future trust levels may
+ * fold in here.
+ */
+export function requiresConfirmation(trust: ProviderTrust): boolean {
+    return trust === 'external-untrusted';
+}
+
+/**
+ * Render a short human-readable rationale for the trust tag. Used by
+ * the dashboard's confirmation modal and the provider catalog tooltip.
+ */
+export function describeTrust(trust: ProviderTrust): string {
+    switch (trust) {
+        case 'user-custom':
+            return 'Hand-authored in ~/.adhdev/providers/. Runs your own code.';
+        case 'trusted':
+            return 'Official, declarative-only manifest from the ADHDev registry.';
+        case 'trusted-with-scripts':
+            return 'Official manifest from the ADHDev registry. Ships JavaScript hooks executed by the daemon.';
+        case 'external-safe':
+            return 'Manifest from a 3rd-party git source you added. Declarative-only — the daemon never runs JS from this source.';
+        case 'external-untrusted':
+            return 'Manifest from a 3rd-party git source you added. Ships JavaScript that the daemon will execute. Treat as untrusted code — review the source before enabling.';
+    }
+}

package/src/providers/read-chat-contract.ts

@@ -1,8 +1,16 @@
 import type { MessagePart, ModalInfo, ReadChatResult } from './contracts.js'
 import { normalizeMessageParts } from './contracts.js'
 import type { ChatBubbleState, ChatMessage } from '../types.js'
-
-const VALID_STATUSES = ['idle', 'generating', 'waiting_approval', 'error', 'panel_hidden', 'streaming', 'long_generating'] as const
+import {
+  CHAT_CONTRACT_VERSION_V1,
+  CHAT_CONTRACT_VERSION_V2,
+  assertReadChatResultV2Payload,
+  isSupportedChatContractVersion,
+  type ChatContractVersion,
+  type ReadChatResultV2,
+} from './transcript-v2.js'
+
+const VALID_STATUSES = ['idle', 'generating', 'waiting_approval', 'error', 'panel_hidden', 'starting', 'streaming', 'no_progress', 'long_generating'] as const
 const VALID_ROLES = ['user', 'assistant', 'system', 'human'] as const
 const VALID_BUBBLE_STATES = ['draft', 'streaming', 'final', 'removed'] as const
 const VALID_TURN_STATUSES = ['open', 'waiting_approval', 'complete', 'error'] as const
@@ -63,7 +71,7 @@ function validateMessage(message: unknown, source: string, index: number): ChatM
     content: validateMessageContent(message.content, source, index),
   }
 
-  if (typeof message.kind === 'string') normalized.kind = message.kind as any
+  if (typeof message.kind === 'string') normalized.kind = message.kind as ChatMessage['kind']
   if (typeof message.id === 'string') normalized.id = message.id
   if (typeof message.bubbleId === 'string') normalized.bubbleId = message.bubbleId
   if (typeof message.providerUnitKey === 'string') normalized.providerUnitKey = message.providerUnitKey
@@ -71,20 +79,23 @@ function validateMessage(message: unknown, source: string, index: number): ChatM
   if (isFiniteNumber(message.index)) normalized.index = message.index
   if (isFiniteNumber(message.timestamp)) normalized.timestamp = message.timestamp
   if (isFiniteNumber(message.receivedAt)) normalized.receivedAt = message.receivedAt
-  if (typeof (message as any)._turnKey === 'string') normalized._turnKey = (message as any)._turnKey
-  if (Array.isArray(message.toolCalls)) normalized.toolCalls = message.toolCalls as any
-  if (isPlainObject(message.meta)) normalized.meta = message.meta as any
+  // (A2.3) sequence is the monotonic ordering key consumed by ChatSourceMachine.
+  // v1 producers omit it; the daemon derives it in normalizeNativeHistoryMessages.
+  if (isFiniteNumber(message.sequence)) normalized.sequence = message.sequence
+  if (typeof message._turnKey === 'string') normalized._turnKey = message._turnKey
+  if (Array.isArray(message.toolCalls)) normalized.toolCalls = message.toolCalls as ChatMessage['toolCalls']
+  if (isPlainObject(message.meta)) normalized.meta = message.meta as ChatMessage['meta']
   if (typeof message.senderName === 'string') normalized.senderName = message.senderName
-  if (typeof (message as any)._type === 'string') normalized._type = (message as any)._type
-  if (typeof (message as any)._sub === 'string') normalized._sub = (message as any)._sub
-  if (typeof (message as any).visibility === 'string') normalized.visibility = (message as any).visibility
-  if (typeof (message as any).transcriptVisibility === 'string') normalized.transcriptVisibility = (message as any).transcriptVisibility
-  if (typeof (message as any).audience === 'string') normalized.audience = (message as any).audience
-  if (typeof (message as any).source === 'string') normalized.source = (message as any).source
-  if (typeof (message as any).userFacing === 'boolean') normalized.userFacing = (message as any).userFacing
-  if (typeof (message as any).internal === 'boolean') normalized.internal = (message as any).internal
-  if (typeof (message as any).isInternal === 'boolean') normalized.isInternal = (message as any).isInternal
-  if (typeof (message as any).debug === 'boolean') normalized.debug = (message as any).debug
+  if (typeof message._type === 'string') normalized._type = message._type
+  if (typeof message._sub === 'string') normalized._sub = message._sub
+  if (typeof message.visibility === 'string') normalized.visibility = message.visibility
+  if (typeof message.transcriptVisibility === 'string') normalized.transcriptVisibility = message.transcriptVisibility
+  if (typeof message.audience === 'string') normalized.audience = message.audience
+  if (typeof message.source === 'string') normalized.source = message.source
+  if (typeof message.userFacing === 'boolean') normalized.userFacing = message.userFacing
+  if (typeof message.internal === 'boolean') normalized.internal = message.internal
+  if (typeof message.isInternal === 'boolean') normalized.isInternal = message.isInternal
+  if (typeof message.debug === 'boolean') normalized.debug = message.debug
 
   return normalized
 }
@@ -129,6 +140,55 @@ function validateControlValues(controlValues: unknown, source: string): Record<s
   return normalized
 }
 
+/**
+ * Read the producer-declared contract version from a raw read_chat payload.
+ * Returns v1 when absent or unrecognised, so legacy producers keep working
+ * through A1. A2 will tighten this to throw when an unsupported version is
+ * declared.
+ */
+export function readPayloadContractVersion(raw: unknown): ChatContractVersion {
+  if (!isPlainObject(raw)) return CHAT_CONTRACT_VERSION_V1
+  const declared = (raw as Record<string, unknown>).contractVersion
+  if (isSupportedChatContractVersion(declared)) return declared
+  return CHAT_CONTRACT_VERSION_V1
+}
+
+/**
+ * Validate a v2 payload. Thin wrapper around assertReadChatResultV2Payload
+ * that prefixes the contract violation with the caller's source label.
+ */
+export function validateReadChatResultV2Payload(raw: unknown, source = 'read_chat'): ReadChatResultV2 {
+  try {
+    return assertReadChatResultV2Payload(raw)
+  } catch (err) {
+    if (err instanceof Error) {
+      err.message = `${source}: ${err.message}`
+    }
+    throw err
+  }
+}
+
+/**
+ * Versioned entry point. Routes on the producer-declared contractVersion:
+ *   - v2 → strict v2 validation (transcript-v2.ts invariants)
+ *   - v1 (or absent) → legacy permissive validation
+ *
+ * Callers that have not yet been audited to handle v2 outputs should use
+ * validateReadChatResultPayload directly; that path stays bound to v1 shape
+ * during the A1 transition.
+ */
+export function validateReadChatResultPayloadVersioned(
+  raw: unknown,
+  source = 'read_chat',
+): { version: typeof CHAT_CONTRACT_VERSION_V1; payload: ReadChatResult & Record<string, unknown> }
+  | { version: typeof CHAT_CONTRACT_VERSION_V2; payload: ReadChatResultV2 } {
+  const version = readPayloadContractVersion(raw)
+  if (version === CHAT_CONTRACT_VERSION_V2) {
+    return { version, payload: validateReadChatResultV2Payload(raw, source) }
+  }
+  return { version: CHAT_CONTRACT_VERSION_V1, payload: validateReadChatResultPayload(raw, source) }
+}
+
 export function validateReadChatResultPayload(raw: unknown, source = 'read_chat'): ReadChatResult & Record<string, unknown> {
   if (!isPlainObject(raw)) {
     throw new Error(`${source}: payload must be an object`)

package/src/providers/sdk/README.md

@@ -0,0 +1,49 @@
+# Provider SDK
+
+> Status: Phase 1 in progress · License of this directory: AGPL-3.0 (part of `oss/`) · See [marketplace plan](../../../../../../docs/design/v1.0.0-marketplace-plan.md).
+
+This directory is the **Provider SDK** — the framework that lets external developers author CLI providers (and later IDE, Extension, ACP) against a versioned, typed contract.
+
+It lives **inside daemon-core**, not as a separate package, by design:
+
+- the contract definitions live next to the runtime that consumes them, eliminating version drift
+- `adhdev provider *` CLI commands call straight into these modules
+- two npm packages are extracted from this source at build time:
+  - `@adhdev/provider-types` (Apache 2.0) — TypeScript types for external authors
+  - `@adhdev/provider-schemas` (Apache 2.0) — JSON Schemas for editor support
+
+## Layout
+
+```
+sdk/
+  v1/                                  ← contract version 1 (current)
+    types/                             ← TypeScript types — extracted to @adhdev/provider-types
+      cli/                             ← CLI category types
+      common/                          ← shared types (settings, capabilities, auth, spawn)
+    schemas/                           ← JSON Schemas — extracted to @adhdev/provider-schemas
+      cli/
+        provider.schema.json           ← top-level provider.json (mirrors adhdev-providers/schemas/v1/cli/)
+      primitives/                      ← per-primitive schemas, namespaced by category
+      common/
+    primitives/                        ← daemon-side primitive implementations
+      cli/                             ← TUI primitives, native-history adapters, capability handlers
+    builders/                          ← functions that turn manifest blocks into runtime handlers
+    validators/                        ← schema check, AST taint analysis, fixture replay
+    scaffolders/                       ← `adhdev provider init` templates
+    fixture-tooling/                   ← PTY capture + replay utilities
+  v2/                                  ← reserved for next contract major
+```
+
+## Primitive identifiers
+
+Primitives are referenced by `$schema: adhdev:<category>/<id>@<version>` in provider manifests. See the audit-derived v1 catalog of 50 primitives at [`audit-cli-v1.md §5`](../../../../../../../adhdev-providers/docs/provider-contract/cli/audit-cli-v1.md#5-proposed-v1-primitive-set).
+
+## Stability
+
+`v1/` is unstable until SDK `1.0.0` is published. Breaking changes between SDK `0.x` releases are permitted during Phase 1-2 migration. After SDK `1.0.0`, breaking changes require an `engines.adhdev` major bump.
+
+## Out of scope
+
+- This SDK does not provide IDE, Extension, or ACP primitives in v1.0.0. They follow in v1.1+.
+- This SDK does not include the registry server code — that lives in [`oss/packages/registry/`](../../../../../registry/) (not yet created).
+- This SDK does not include the marketplace web UI — that lives separately.

package/src/providers/sdk/v1/builders/acp/detect-status.ts

@@ -0,0 +1,144 @@
+/**
+ * buildDetectStatusFromAcp
+ *
+ * Turns a declarative `acp/session-protocol@1` block into a runtime
+ * `(input: AcpStatusInput) => 'idle' | 'generating' | 'waiting_approval' | null`
+ * function.
+ *
+ * Dispatch order:
+ *   1. Not connected → null (no information available).
+ *   2. Error patterns — checked first; first match returns the declared verdict.
+ *   3. Generating pattern — `generating`.
+ *   4. Idle pattern — `idle`.
+ *   5. Default: `null` (no change — caller preserves last known status).
+ *
+ * All regex patterns are compiled once at builder time so the returned
+ * detector function is allocation-free on the hot path.
+ */
+
+// ─── Spec shapes (mirror the JSON schema) ──────────────────────────────
+
+interface AcpRegexPatternSpec {
+  regex: string;
+  flags?: string;
+  description?: string;
+}
+
+interface AcpErrorPatternSpec extends AcpRegexPatternSpec {
+  verdict: 'idle' | 'generating' | 'waiting_approval';
+}
+
+export interface AcpSessionSpec {
+  $schema?: 'adhdev:acp/session-protocol@1';
+  /** Pattern that matches a line emitted when the agent is idle/ready. */
+  idlePattern?: AcpRegexPatternSpec;
+  /** Pattern that matches a line emitted while the agent is actively working. */
+  generatingPattern?: AcpRegexPatternSpec;
+  /**
+   * Error/edge-case patterns. Checked in order; first match returns the
+   * declared verdict. Useful for approval prompts, fatal errors, etc.
+   */
+  errorPatterns?: AcpErrorPatternSpec[];
+  /** Wire format; informational only at the builder level — regex matching
+   *  is identical regardless of promptStyle. */
+  promptStyle?: 'json-rpc' | 'plain-text' | 'mcp';
+  /** Message delimiter used to split incoming bytes (default: newline). */
+  messageDelimiter?: string;
+}
+
+// ─── Input shape ────────────────────────────────────────────────────────
+
+export interface AcpStatusInput {
+  /** The most recently received line from the stdio stream. */
+  lastLine: string;
+  /**
+   * A sliding window of recent output lines (newest last).
+   * Builders may check these when a single line is not enough for context.
+   */
+  recentLines: string[];
+  /** Whether the ACP process is currently connected and running. */
+  isConnected: boolean;
+}
+
+// ─── Output type ────────────────────────────────────────────────────────
+
+export type AcpDetectedStatus = 'idle' | 'generating' | 'waiting_approval' | null;
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+function compile(re: string, flags?: string): RegExp {
+  try {
+    return new RegExp(re, flags ?? 'i');
+  } catch (e) {
+    throw new Error(`Invalid regex /${re}/${flags ?? 'i'}: ${(e as Error).message}`);
+  }
+}
+
+/**
+ * Safe `.test()` wrapper: resets `lastIndex` before each call so that
+ * regexes compiled with the `g` or `y` flag remain stateless across
+ * multiple detect invocations.
+ */
+function testRe(re: RegExp, text: string): boolean {
+  re.lastIndex = 0;
+  return re.test(text);
+}
+
+// ─── Compiled internal representation ───────────────────────────────────
+
+interface CompiledAcpSpec {
+  idle: RegExp | null;
+  generating: RegExp | null;
+  errors: Array<{ re: RegExp; verdict: AcpDetectedStatus }>;
+}
+
+function compileSpec(spec: AcpSessionSpec): CompiledAcpSpec {
+  const idle = spec.idlePattern
+    ? compile(spec.idlePattern.regex, spec.idlePattern.flags)
+    : null;
+
+  const generating = spec.generatingPattern
+    ? compile(spec.generatingPattern.regex, spec.generatingPattern.flags)
+    : null;
+
+  const errors = (spec.errorPatterns ?? []).map((ep) => ({
+    re: compile(ep.regex, ep.flags),
+    verdict: ep.verdict as AcpDetectedStatus,
+  }));
+
+  return { idle, generating, errors };
+}
+
+// ─── Public builder ─────────────────────────────────────────────────────
+
+export function buildDetectStatusFromAcp(
+  spec: AcpSessionSpec,
+): (input: AcpStatusInput) => AcpDetectedStatus {
+  const compiled = compileSpec(spec);
+
+  return function detectAcpStatus(input: AcpStatusInput): AcpDetectedStatus {
+    // 1. No connection → no information.
+    if (!input.isConnected) return null;
+
+    const line = input.lastLine;
+
+    // 2. Error/edge-case patterns take priority.
+    for (const { re, verdict } of compiled.errors) {
+      if (testRe(re, line)) return verdict;
+    }
+
+    // 3. Generating pattern.
+    if (compiled.generating && testRe(compiled.generating, line)) return 'generating';
+
+    // 4. Idle pattern.
+    if (compiled.idle && testRe(compiled.idle, line)) return 'idle';
+
+    // 5. Nothing matched.
+    return null;
+  };
+}
+
+// Internal exports for builder reuse + tests.
+export const __internal = {
+  compileSpec,
+};