@sayknow-cli/coding-agent 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -5,6 +5,80 @@ This file tracks the **fork's own releases**; upstream's full feature history li
 in that project. Each release notes the upstream version it is built on.
 
 
+## [0.4.4] — 2026-07-22
+
+### Fixed (workflow arbitration native)
+
+- **Port `skc-notifications` to upstream v0.11.6 and switch pi-natives to
+  `sdk.rs`.** 0.4.x synced upstream's coding-agent, whose SDK bus requires the
+  native `NotificationServer` arbitration API (`registerArbitratedAsk`,
+  `retireIfUnclaimed`, `stopAndWait`). But the fork's `skc-notifications` crate
+  was stuck at upstream v0.9.1, so `crates/pi-natives/src/sdk.rs` (restored from
+  v0.11.6) could not compile against it and was dropped from `lib.rs`. The
+  shipped `notifications.rs` `NotificationServer` lacked the arbitration
+  methods, so every SDK session startup threw `NativeRuntimeCompatibilityError`
+  ("required workflow arbitration methods are missing") — extensions failed to
+  load and no session could start on 0.4.1–0.4.3.
+- Upgrades `crates/skc-notifications` v0.9.1 → v0.11.6 (adds the
+  `broker_protocol`/`control`/`query`/`reverse` modules and the `hmac` workspace
+  dependency), wires `mod sdk;` and retires `notifications.rs`. This restores
+  the arbitration API **and** the SKC v3 SDK connection lane
+  (`onSdkFrame`/`sendTo`/`onConnectionClose`/`registerWorkflowGateAsk`/
+  `pushTurnStreamUnchecked`), which was also dead in 0.4.1–0.4.3. No native
+  method that the fork already relied on is removed (`sdk.rs`'s
+  `NotificationServer` is a strict superset of `notifications.rs`).
+
+## [0.4.3] — 2026-07-21
+
+### Fixed (cross-platform native publish)
+
+- **pi-natives ps.rs: restore `Process.incarnation` getter.** The fork's
+  `crates/pi-natives/src/ps.rs` predated upstream v0.11.x's
+  `#[napi(getter)] incarnation` method; the chat/telegram daemon control
+  runtimes (`sdk/bus/{chat,telegram}-daemon-control.ts`) read
+  `processRef.incarnation` for ownership authority, so typecheck failed
+  with `Property 'incarnation' does not exist on type 'Process'`.
+- **sdk/bus/index.ts: use `NotificationServer.stop()` instead of `stopAndWait()`.**
+  The fork's `NotificationServer` (notifications.rs) is synchronous and
+  pre-upstream-split; the v0.11.x TS calls `stopAndWait()` which is the
+  upstream async variant. TODO(port): add `stop_and_wait` to
+  pi-natives/src/notifications.rs when the daemon API is ported forward.
+
+### Strategy change
+
+v0.4.3 is published entirely by CI (no local `bun publish`). v0.4.2's
+release hit an integrity-evidence conflict because the darwin-arm64
+subpackage was published both locally (from a Mac-built .node) and from
+CI (from a CI-built .node) with different SRI hashes; `ci-release-publish`
+correctly rejected the second one. For v0.4.3 all 9 main packages + 5
+platform subpackages publish from a single CI run.
+
+## [0.4.2] — 2026-07-21
+
+### Fixed (post-0.4.0 publish)
+
+- **Native loader: nested node_modules fallback.** Bun's `-g` install creates a
+  nested layout where each workspace package owns its own `node_modules/`. The
+  loader's single hardcoded platform-subpackage path
+  (`../../natives-<platform>/native`) assumed npm's flat hoist, so `bun install
+  -g sayknow-cli` could not resolve the .node and crashed at startup with
+  `Failed to load pi_natives native addon`. Added a third candidate path that
+  covers `natives/node_modules/@sayknow-cli/natives-<platform>/native`.
+- **Catalog resolution via `bun install`.** v0.4.0 was published with stale
+  `bun.lock` workspace versions (still pinned to 0.3.16), so `bun publish`
+  resolved `catalog:` deps to 0.3.16 and the umbrella ended up depending on
+  the previous release's `@sayknow-cli/coding-agent`. v0.4.2 republishes after
+  regenerating `bun.lock` from the bumped catalog (0.4.2 everywhere).
+- **Native version sentinel.** Rebuilt `pi_natives.darwin-arm64.node` after the
+  version bump so it exposes `__piNativesV0_4_2` (the v0.4.0 binary's
+  `__piNativesV0_4_0` failed the loader's release-match check).
+
+### Deprecated (on npm)
+
+- `sayknow-cli@0.4.0` and `@sayknow-cli/*@0.4.0` — broken catalog: resolution.
+- `sayknow-cli@0.4.1` and `@sayknow-cli/*@0.4.1` — loader missing nested
+  `node_modules` fallback.
+
 ## [0.4.0] — 2026-07-21
 
 ### Changed

package/dist/types/append-only-mode.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Single source of truth for append-only context-mode resolution and manager
+ * construction. Both the initial session build (`sdk/session.ts`) and the runtime
+ * model/setting-change path (`agent-session.ts`), plus the status UI, resolve
+ * through here so the auto allowlist and prefix-reset diagnostics never drift.
+ */
+import { AppendOnlyContextManager } from "@sayknow-cli/agent-core";
+/**
+ * Providers for which append-only context auto-enables. Exact provider-string
+ * match only: `anthropic` reached via a gateway/aggregator provider string
+ * (e.g. `openrouter`, a custom gateway) does NOT match and stays opt-in via
+ * `provider.appendOnlyContext: "on"`, because those transports can rewrite or
+ * renormalize the request in ways that have not been validated for append-only
+ * prefix stability.
+ */
+export declare function providerSupportsAppendOnlyAuto(provider: string): boolean;
+/**
+ * Resolve whether to enable append-only context mode based on the setting and provider.
+ *
+ * - `"on"` → always enable
+ * - `"off"` → never enable
+ * - `"auto"` → enable for providers with strong prompt-prefix caching that this
+ *   harness has validated (see {@link providerSupportsAppendOnlyAuto})
+ */
+export declare function resolveAppendOnlyMode(setting: "auto" | "on" | "off" | undefined, provider: string): boolean;
+/**
+ * Construct an {@link AppendOnlyContextManager} wired to emit per-session
+ * stable-prefix reset diagnostics. Use this at every creation site so the
+ * telemetry is uniform.
+ */
+export declare function createAppendOnlyContextManager(provider: string | undefined): AppendOnlyContextManager;

package/dist/types/async/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./job-manager";
+export * from "./support";

package/dist/types/async/job-manager.d.ts

@@ -0,0 +1,367 @@
+import type { AgentProgress, AgentSource } from "../task/types";
+export interface AsyncJob {
+    id: string;
+    type: "bash" | "task";
+    status: "running" | "completed" | "failed" | "cancelled" | "paused";
+    startTime: number;
+    /**
+     * Wall-clock ms when the job left the `running` state (completed, failed,
+     * cancelled, or paused). Undefined while running. Frozen on the first
+     * terminal/pause transition so elapsed-time renderers stop counting once a
+     * job is no longer active instead of growing forever against `Date.now()`.
+     */
+    endTime?: number;
+    label: string;
+    abortController: AbortController;
+    promise: Promise<void>;
+    resultText?: string;
+    errorText?: string;
+    metadata?: AsyncJobMetadata;
+    /**
+     * Registry id of the agent that registered the job (e.g. "0-Main",
+     * "3-AuthLoader"). Used by scoped cancel/list APIs so a subagent's teardown
+     * does not cancel its parent's jobs. Undefined for callers that don't
+     * supply an id (e.g. legacy tests, SDK consumers without an agent context).
+     */
+    ownerId?: string;
+}
+/**
+ * Elapsed wall-clock ms for a job, frozen once it stops running. While the job
+ * is active (`endTime` undefined) this counts against `now`; after it stops it
+ * returns the fixed `endTime - startTime` span so status renderers do not keep
+ * incrementing a completed job's timer.
+ */
+export declare function jobElapsedMs(job: Pick<AsyncJob, "startTime" | "endTime">, now?: number): number;
+export interface AsyncJobMetadata {
+    subagent?: {
+        id: string;
+        agent: string;
+        agentSource: AgentSource;
+        description?: string;
+        assignment?: string;
+    };
+    /** True when this bash job was started by the `monitor` tool (vs plain async bash). */
+    monitor?: boolean;
+}
+/**
+ * Typed outcome a subagent task run may produce. A `paused` outcome is
+ * non-terminal and non-delivering: the run suspended at a safe boundary and the
+ * subagent can be resumed from its persisted sessionFile. `completed` always
+ * wins a race with a late pause because the run returns it once it has actually
+ * finished.
+ */
+export type SubagentRunOutcome = {
+    kind: "completed";
+    text: string;
+} | {
+    kind: "paused";
+    note?: string;
+};
+/** Canonical lifecycle of a subagent across pause/resume cycles. */
+export type SubagentLifecycle = "running" | "paused" | "queued" | "completed" | "failed" | "cancelled";
+/** Maximum time allowed to prove owned subagents have stopped before replacement. */
+export declare const OWNER_SUBAGENT_SHUTDOWN_TIMEOUT_MS = 5000;
+export declare class OwnerSubagentShutdownError extends Error {
+    readonly code = "owner_shutdown_in_progress";
+    constructor();
+}
+export interface OwnerSubagentShutdownTarget {
+    subagentId: string;
+    jobId: string | null;
+    source: "record" | "metadata_job";
+}
+export interface OwnerSubagentShutdownLease {
+    ownerId: string;
+    id: string;
+    targets: readonly OwnerSubagentShutdownTarget[];
+}
+export interface OwnerSubagentShutdownProof {
+    ownerId: string;
+    leaseId: string;
+    confirmed: boolean;
+    reason: "confirmed" | "deadline_exceeded" | "missing_terminal_evidence" | "lease_lost";
+    targets: readonly OwnerSubagentShutdownTarget[];
+    terminalIds: readonly string[];
+    unresolvedIds: readonly string[];
+}
+/**
+ * Live, executor-owned control handle for a RUNNING subagent. Registered when a
+ * subagent run starts and removed on pause/terminal so a paused subagent retains
+ * no live `AgentSession` reference (leak-free).
+ */
+export interface SubagentLiveHandle {
+    /** Request a cooperative safe-boundary pause (never aborts the in-flight tool). */
+    requestPause(): void;
+    /** Inject a steering message into the live session. */
+    injectMessage(content: string, deliverAs: "steer" | "followUp" | "nextTurn", opts?: {
+        fromAgentId?: string;
+    }): Promise<void>;
+}
+/**
+ * Canonical, stable-id-keyed record for a subagent. Survives `AsyncJob`
+ * eviction so resume stays addressable by subagent id, and is the single source
+ * of truth for control-plane status and identity.
+ */
+export interface SubagentRecord {
+    subagentId: string;
+    ownerId?: string;
+    /** Current live/last AsyncJob id; null while queued with no active job. */
+    currentJobId: string | null;
+    historicalJobIds: string[];
+    status: SubagentLifecycle;
+    sessionFile: string | null;
+    /** False for ephemeral sessions (no persistent artifacts dir). */
+    resumable: boolean;
+    queued?: {
+        ownerId?: string;
+        seq: number;
+        message?: string;
+        createdAt: number;
+    };
+    /** Resolved model the subagent was asked to use, e.g. "openai-codex/gpt-5.5". */
+    requestedModel?: string;
+    /** Model actually used after auth fallback (#985); equals requestedModel when no fallback. */
+    effectiveModel?: string;
+    /** True when the requested model lacked credentials and the subagent fell back to the parent model. */
+    modelFellBack?: boolean;
+}
+/** Lightweight, manager-owned resume payload. The async layer treats `data` as opaque. */
+export interface ResumeDescriptor {
+    subagentId: string;
+    ownerId?: string;
+    data: unknown;
+}
+/**
+ * In-memory resume runner bound to the session that originally launched a
+ * subagent. Never serialized: process restart drops it so resume fails closed.
+ */
+export type ResumeRunner = (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined;
+export interface AsyncJobManagerOptions {
+    onJobComplete: (jobId: string, text: string, job?: AsyncJob) => void | Promise<void>;
+    maxRunningJobs?: number;
+    retentionMs?: number;
+}
+export interface AsyncJobDisposeDiagnostics {
+    stuckJobIds: string[];
+    deliveriesDrained: boolean;
+}
+export interface AsyncJobDeliveryState {
+    queued: number;
+    delivering: boolean;
+    nextRetryAt?: number;
+    pendingJobIds: string[];
+    deadLettered: number;
+}
+export interface AsyncJobLifecycleCleanup {
+    onCancel?: (job: AsyncJob) => void;
+    onTerminal?: (job: AsyncJob) => void;
+    onEvict?: (job: AsyncJob) => void;
+    /**
+     * Idempotent residual cleanup invoked by a post-eviction tombstone purge
+     * (e.g. a late `job cancel` after the job left the registry). Kept distinct
+     * from the at-most-once lifecycle phases so a tombstone purge never has to
+     * re-invoke a phase hook. Must be safe to call repeatedly.
+     */
+    onTombstonePurge?: (job: AsyncJob) => void;
+}
+export interface MonitorTombstone {
+    jobId: string;
+    ownerId?: string;
+    status: AsyncJob["status"];
+    expiresAt: number;
+    purge: () => unknown;
+}
+export interface AsyncJobRegisterOptions {
+    id?: string;
+    /** Registry id of the agent that owns this job; used to scope cancelAll. */
+    ownerId?: string;
+    /** Structured metadata for tool-specific control surfaces. */
+    metadata?: AsyncJobMetadata;
+    onProgress?: (text: string, details?: Record<string, unknown>) => void | Promise<void>;
+    lifecycle?: AsyncJobLifecycleCleanup;
+}
+/**
+ * Filter applied to job query/cancel APIs. With `ownerId`, results are
+ * restricted to jobs registered by that agent (registry id from
+ * `AgentRegistry`, e.g. "0-Main", "3-AuthLoader").
+ */
+export interface AsyncJobFilter {
+    ownerId?: string;
+}
+/**
+ * A slice of process-stream output for a background job, as recorded by
+ * `appendOutput` / read by `readOutputSince`.
+ *
+ * The cursor model is monotonic UTF-8 byte offsets. `nextOffset` is the offset
+ * to pass to the next read to receive only fresh bytes; `startOffset` is the
+ * first byte the manager still retains for this job. When the requested offset
+ * is older than `startOffset`, the manager returns the retained tail and sets
+ * `truncated: true`.
+ */
+export interface AsyncJobOutputSlice {
+    jobId: string;
+    status: AsyncJob["status"];
+    text: string;
+    startOffset: number;
+    nextOffset: number;
+    truncated: boolean;
+}
+/** Default retention cap for per-job captured output. ~512 KiB matches the
+ *  bash tail-buffer order of magnitude without dominating session memory. */
+export declare const DEFAULT_JOB_OUTPUT_RETENTION_BYTES: number;
+export declare class AsyncJobManager {
+    #private;
+    /** Process-global instance shared by internal URL protocol handlers and tools. */
+    static instance(): AsyncJobManager | undefined;
+    /** Install or clear the process-global instance. */
+    static setInstance(value: AsyncJobManager | undefined): void;
+    /** Reset the process-global instance. Test-only. */
+    static resetForTests(): void;
+    constructor(options: AsyncJobManagerOptions);
+    /**
+     * Subscribe to live-job-set change events. Returns an unsubscribe function.
+     * Listener errors are isolated so one bad subscriber cannot break others.
+     */
+    onChange(cb: () => void): () => void;
+    register(type: "bash" | "task", label: string, run: (ctx: {
+        jobId: string;
+        signal: AbortSignal;
+        reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
+    }) => Promise<string | SubagentRunOutcome>, options?: AsyncJobRegisterOptions): string;
+    /**
+     * Cancel a single job by id. When `filter.ownerId` is set and does not
+     * match the job's owner, the call is treated as not-found (returns false)
+     * so cross-agent cancellation is rejected at the manager level.
+     */
+    cancel(id: string, filter?: AsyncJobFilter): boolean;
+    getMonitorTombstone(jobId: string, filter?: AsyncJobFilter): MonitorTombstone | undefined;
+    purgeMonitorTombstone(jobId: string, filter?: AsyncJobFilter): {
+        found: boolean;
+        status?: AsyncJob["status"];
+    };
+    /** Register or replace the canonical record for a subagent. */
+    registerSubagentRecord(record: SubagentRecord): void;
+    /** Patch model metadata onto an existing subagent record (best-effort; no-op if unknown). */
+    updateSubagentModel(subagentId: string, model: {
+        requestedModel?: string;
+        effectiveModel?: string;
+        modelFellBack?: boolean;
+    }): void;
+    getSubagentRecord(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined;
+    getSubagentRecords(filter?: AsyncJobFilter): SubagentRecord[];
+    registerLiveHandle(subagentId: string, handle: SubagentLiveHandle): void;
+    getLiveHandle(subagentId: string): SubagentLiveHandle | undefined;
+    removeLiveHandle(subagentId: string): void;
+    /**
+     * Retain the latest live `AgentProgress` for a subagent (deep-cloned so later
+     * mutation of the live object cannot corrupt retained state). Read by the
+     * `subagent` await panel; cleared on terminal/cancel/purge/dispose.
+     *
+     * Ignored for ids without a canonical `SubagentRecord` (e.g. foreground/inline
+     * task runs that share the executor path) so the map only holds detached
+     * subagent progress and never accumulates untracked foreground task state.
+     */
+    recordSubagentProgress(subagentId: string, progress: AgentProgress): void;
+    getSubagentProgress(subagentId: string): AgentProgress | undefined;
+    /**
+     * True only when a live, in-session progress producer exists for this id: a
+     * canonical registered record with a live handle or an in-memory running job.
+     * False for `SubagentTool` backward-compat job synthesis and resumed-from-disk
+     * records, which have no live producer to stream from.
+     */
+    hasLiveSubagent(subagentId: string, filter?: AsyncJobFilter): boolean;
+    /** Install the TaskTool-owned resume runner. Returns the new job id, or undefined on failure. */
+    setResumeRunner(runner: ResumeRunner): void;
+    registerResumeDescriptor(descriptor: ResumeDescriptor, runner?: ResumeRunner): void;
+    getResumeDescriptor(subagentId: string, filter?: AsyncJobFilter): ResumeDescriptor | undefined;
+    beginOwnerSubagentShutdown(ownerId: string): OwnerSubagentShutdownLease | undefined;
+    runOwnerProducerCleanups(filter?: AsyncJobFilter): void;
+    runOwnerProducerCleanupsStrict(filter?: AsyncJobFilter): void;
+    cancelAndProveOwnerSubagents(lease: OwnerSubagentShutdownLease, options?: {
+        timeoutMs?: number;
+    }): Promise<OwnerSubagentShutdownProof>;
+    finishOwnerSubagentShutdown(lease: OwnerSubagentShutdownLease, outcome: "commit" | "release"): void;
+    /** Request a graceful safe-boundary pause of a running subagent. */
+    pauseSubagent(subagentId: string, filter?: AsyncJobFilter): {
+        ok: boolean;
+        status?: SubagentLifecycle;
+        reason?: string;
+    };
+    /** Resume a non-running subagent from its sessionFile, optionally injecting a message first. */
+    resumeSubagent(subagentId: string, filter?: AsyncJobFilter, message?: string): {
+        ok: boolean;
+        status?: SubagentLifecycle;
+        jobId?: string;
+        queued?: boolean;
+        reason?: string;
+    };
+    /** Cancel a subagent by stable id across running/paused/queued states (keeps the session file). */
+    cancelSubagent(subagentId: string, filter?: AsyncJobFilter): boolean;
+    getJob(id: string): AsyncJob | undefined;
+    getRunningJobs(filter?: AsyncJobFilter): AsyncJob[];
+    getRecentJobs(limit?: number, filter?: AsyncJobFilter): AsyncJob[];
+    getAllJobs(filter?: AsyncJobFilter): AsyncJob[];
+    /**
+     * Append a sanitized process-stream chunk for a background job. Called from
+     * the unthrottled bash-executor capture hook (`onRawChunk`) so monitor sees
+     * every chunk even when preview/progress callbacks are throttled.
+     *
+     * Offsets are in UTF-8 bytes. Storing chunk metadata avoids unsafe byte
+     * slicing across multibyte characters at read time. The retention window is
+     * a per-job rolling cap (`DEFAULT_JOB_OUTPUT_RETENTION_BYTES`); when it
+     * overflows, oldest whole chunks are evicted and `startOffset` advances —
+     * subsequent reads from a stale offset get `truncated: true`.
+     */
+    appendOutput(jobId: string, chunk: string): void;
+    /**
+     * Read fresh process-stream output for a job since `offset` (in UTF-8
+     * bytes). Returns `undefined` when the job does not exist or when an
+     * `ownerId` filter is set and the job belongs to a different owner — this
+     * mirrors the manager-level "not found" pattern used by `cancel`.
+     *
+     * - `offset < startOffset` returns the retained tail with `truncated: true`.
+     * - `offset > nextOffset` clamps to `nextOffset` and returns an empty text
+     *   slice with `truncated: false`.
+     * - Assembled text slices the leading retained chunk at a UTF-8 codepoint
+     *   boundary when needed, so multibyte characters cannot be split.
+     */
+    readOutputSince(jobId: string, offset: number, filter?: AsyncJobFilter): AsyncJobOutputSlice | undefined;
+    /**
+     * Register an owner-scoped cleanup callback. Returns an unregister function.
+     *
+     * Used by Cron* tools to clear session-scoped timers when the owning agent
+     * is torn down. Invoked by `runOwnerCleanups({ ownerId })` before
+     * `cancelAll({ ownerId })` so timers cannot register new jobs during
+     * teardown.
+     */
+    registerOwnerCleanup(ownerId: string, cleanup: () => void): () => void;
+    /** Run producer cleanups, then perform the legacy destructive subagent purge. */
+    runOwnerCleanups(filter?: AsyncJobFilter): void;
+    getDeliveryState(filter?: AsyncJobFilter): AsyncJobDeliveryState;
+    hasPendingDeliveries(filter?: AsyncJobFilter): boolean;
+    watchJobs(jobIds: string[]): number;
+    unwatchJobs(jobIds: string[]): number;
+    acknowledgeDeliveries(jobIds: string[]): number;
+    /**
+     * Cancel running jobs. With `filter.ownerId` set, cancels only jobs the
+     * matching agent registered; with no filter, cancels every running job
+     * (used by `dispose()` to nuke the manager's state).
+     */
+    cancelAll(filter?: AsyncJobFilter): void;
+    waitForOwnerInFlightDeliveries(ownerId: string, options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    cancelAndSettleOwnerJobs(ownerId: string, options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    getLastDisposeDiagnostics(): AsyncJobDisposeDiagnostics;
+    waitForAll(): Promise<void>;
+    drainDeliveries(options?: {
+        timeoutMs?: number;
+        filter?: AsyncJobFilter;
+    }): Promise<boolean>;
+    dispose(options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    isDeliverySuppressed(jobId: string): boolean;
+}

package/dist/types/async/support.d.ts

@@ -0,0 +1,2 @@
+import type { Settings } from "../config/settings";
+export declare function isBackgroundJobSupportEnabled(settings: Pick<Settings, "get">): boolean;

package/dist/types/autoresearch/dashboard.d.ts

@@ -0,0 +1,4 @@
+import type { Theme } from "../modes/theme/theme";
+import type { AutoresearchRuntime, DashboardController } from "./types";
+export declare function createDashboardController(): DashboardController;
+export declare function renderDashboardLines(runtime: AutoresearchRuntime, width: number, theme: Theme, maxRows: number): string[];

package/dist/types/autoresearch/git.d.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from "../extensibility/extensions";
+export interface EnsureAutoresearchBranchFailure {
+    error: string;
+    ok: false;
+}
+export interface EnsureAutoresearchBranchSuccess {
+    branchName: string | null;
+    created: boolean;
+    ok: true;
+    warning?: string;
+}
+export type EnsureAutoresearchBranchResult = EnsureAutoresearchBranchFailure | EnsureAutoresearchBranchSuccess;
+export declare function getCurrentAutoresearchBranch(_api: ExtensionAPI, workDir: string): Promise<string | null>;
+/**
+ * Ensure the working tree is on an `autoresearch/*` branch when possible.
+ *
+ * If the worktree is dirty and we're not already on an autoresearch branch, this returns
+ * `{ ok: true, branchName: null, warning }` rather than failing. The caller surfaces the
+ * warning and continues on the current branch — `keep` will skip auto-commits and `discard`
+ * will revert only run-modified paths instead of resetting to baseline.
+ */
+export declare function ensureAutoresearchBranch(api: ExtensionAPI, workDir: string, goal: string | null): Promise<EnsureAutoresearchBranchResult>;
+export declare function parseWorkDirDirtyPaths(statusOutput: string, workDirPrefix: string): string[];
+export declare function relativizeGitPathToWorkDir(repoRelativePath: string, workDirPrefix: string): string | null;
+export declare function parseDirtyPaths(statusOutput: string): string[];
+export declare function normalizeStatusPath(rawPath: string): string;
+export interface DirtyPathEntry {
+    path: string;
+    untracked: boolean;
+}
+export declare function parseDirtyPathsWithStatus(statusOutput: string): DirtyPathEntry[];
+export declare function parseWorkDirDirtyPathsWithStatus(statusOutput: string, workDirPrefix: string): DirtyPathEntry[];
+export declare function computeRunModifiedPaths(preRunDirtyPaths: string[], currentStatusOutput: string, workDirPrefix: string): {
+    tracked: string[];
+    untracked: string[];
+};

package/dist/types/autoresearch/helpers.d.ts

@@ -0,0 +1,24 @@
+import type { ASIData, MetricDirection, NumericMetricMap } from "./types";
+export declare const METRIC_LINE_PREFIX = "METRIC";
+export declare const ASI_LINE_PREFIX = "ASI";
+export declare const EXPERIMENT_MAX_LINES = 10;
+export declare const EXPERIMENT_MAX_BYTES: number;
+export declare function parseMetricLines(output: string): Map<string, number>;
+export declare function parseAsiLines(output: string): ASIData | null;
+export declare function mergeAsi(base: ASIData | null, override: ASIData | undefined): ASIData | undefined;
+export declare function commas(value: number): string;
+export declare function fmtNum(value: number, decimals?: number): string;
+export declare function formatNum(value: number | null, unit: string): string;
+export declare function formatElapsed(milliseconds: number): string;
+export declare function killTree(pid: number, signal?: NodeJS.Signals | number): void;
+export declare function isBetter(current: number, best: number, direction: MetricDirection): boolean;
+export declare function inferMetricUnitFromName(name: string): string;
+export declare function normalizePathSpec(value: string): string;
+export declare function pathMatchesSpec(pathValue: string, specValue: string): boolean;
+export declare function dedupeStrings(values: readonly string[]): string[];
+export declare function ensureNumericMetricMap(value: NumericMetricMap | undefined): NumericMetricMap;
+export declare function sanitizeAsi(value: {
+    [key: string]: unknown;
+} | undefined): ASIData | undefined;
+export declare function tryGitStatus(cwd: string): Promise<string>;
+export declare function tryGitPrefix(cwd: string): Promise<string>;

package/dist/types/autoresearch/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionFactory } from "../extensibility/extensions";
+export declare const createAutoresearchExtension: ExtensionFactory;

package/dist/types/autoresearch/state.d.ts

@@ -0,0 +1,17 @@
+import type { SessionEntry } from "../session/session-manager";
+import type { RunRow, SessionRow } from "./storage";
+import type { AutoresearchRuntime, ExperimentResult, ExperimentState, MetricDef, MetricDirection, NumericMetricMap, ReconstructedControlState, RuntimeStore } from "./types";
+export declare function createExperimentState(): ExperimentState;
+export declare function createSessionRuntime(): AutoresearchRuntime;
+export declare function cloneExperimentState(state: ExperimentState): ExperimentState;
+export declare function currentResults(results: ExperimentResult[], segment: number): ExperimentResult[];
+export declare function findBaselineResult(results: ExperimentResult[], segment: number): ExperimentResult | null;
+export declare function findBaselineMetric(results: ExperimentResult[], segment: number): number | null;
+export declare function findBestKeptMetric(results: ExperimentResult[], segment: number, direction: MetricDirection): number | null;
+export declare function findBaselineRunNumber(results: ExperimentResult[], segment: number): number | null;
+export declare function findBaselineSecondary(results: ExperimentResult[], segment: number, knownMetrics: MetricDef[]): NumericMetricMap;
+export declare function sortedMedian(values: number[]): number;
+export declare function computeConfidence(results: ExperimentResult[], segment: number, direction: MetricDirection): number | null;
+export declare function buildExperimentState(session: SessionRow, loggedRuns: RunRow[]): ExperimentState;
+export declare function reconstructControlState(entries: SessionEntry[]): ReconstructedControlState;
+export declare function createRuntimeStore(): RuntimeStore;