@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/curation-config.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Sweeper curation budgets — the per-file token limits the post-turn curator
+ * keeps OVERVIEW.md / CHANGELOG.md / CLAUDE.md under (issue #379), with a
+ * per-project override layer (issue #384).
+ *
+ * ── Config discipline (the `recovery`/`driveMode` pattern) ────────────────────
+ * Every budget is an instance default (`PADDOCK_CURATION_*` env, YAML instance
+ * file beneath it — resolved in config.ts's `loadCurationConfig`) with an
+ * optional PER-PROJECT override (`project.yaml` →
+ * {@link import("./projects.js").ProjectYaml.curation}). An absent/invalid
+ * override inherits the instance default, resolved at sweep time by
+ * {@link resolveCurationConfig} — never baked into the DTO (mirrors how
+ * `recovery` resolves via `resolveRecoveryConfig`). A malformed override is
+ * ignored rather than fatal so a hand-edited `project.yaml` can't wedge a sweep.
+ *
+ * #379 shipped these instance-only; #384 adds the override so a docs-heavy
+ * project can raise its CHANGELOG budget (or a lean project tighten it) without
+ * changing the fleet-wide default.
+ */
+/**
+ * Resolved curation budgets — all fields concrete. Held on {@link
+ * import("./config.js").PaddockConfig.curation} (instance defaults) and produced
+ * per-sweep by {@link resolveCurationConfig} (project override else instance).
+ */
+export interface CurationConfig {
+    /** Budget for OVERVIEW.md (regenerated wholesale each sweep). */
+    overviewMaxTokens: number;
+    /** Budget for CHANGELOG.md (injected into the preload; the biggest lever). */
+    changelogMaxTokens: number;
+    /** Budget for the CLAUDE.md curated-notes section (auto-loaded every turn). */
+    claudeMaxTokens: number;
+}
+/**
+ * A per-project curation override as stored in `project.yaml` — every field
+ * optional (an absent field inherits the instance default at sweep time).
+ */
+export type CurationOverride = Partial<CurationConfig>;
+/** Built-in defaults when neither env nor YAML nor a project override sets a budget. */
+export declare const DEFAULT_CURATION: CurationConfig;
+/**
+ * Validate + normalise an untrusted value (from `project.yaml` or a PATCH body)
+ * into a {@link CurationOverride}, dropping any field that is missing or invalid,
+ * and returning `undefined` when nothing valid remains (so an empty override is
+ * never persisted). Each budget must be a positive integer. Defensive by design —
+ * a malformed hand-edit degrades to "inherit the instance default", never a
+ * sweep crash.
+ */
+export declare function sanitizeCurationOverride(value: unknown): CurationOverride | undefined;
+/**
+ * Resolve the effective curation budgets for a sweep: a valid per-project
+ * override wins field-by-field; every absent field inherits the instance default
+ * (which is itself `env > paddock.config.yaml > built-in default`). The override
+ * is re-sanitised so a corrupt on-disk value can't leak through.
+ */
+export declare function resolveCurationConfig(override: CurationOverride | undefined, instanceDefault: CurationConfig): CurationConfig;

package/packages/server/dist/curation-config.js

@@ -0,0 +1,64 @@
+/**
+ * Sweeper curation budgets — the per-file token limits the post-turn curator
+ * keeps OVERVIEW.md / CHANGELOG.md / CLAUDE.md under (issue #379), with a
+ * per-project override layer (issue #384).
+ *
+ * ── Config discipline (the `recovery`/`driveMode` pattern) ────────────────────
+ * Every budget is an instance default (`PADDOCK_CURATION_*` env, YAML instance
+ * file beneath it — resolved in config.ts's `loadCurationConfig`) with an
+ * optional PER-PROJECT override (`project.yaml` →
+ * {@link import("./projects.js").ProjectYaml.curation}). An absent/invalid
+ * override inherits the instance default, resolved at sweep time by
+ * {@link resolveCurationConfig} — never baked into the DTO (mirrors how
+ * `recovery` resolves via `resolveRecoveryConfig`). A malformed override is
+ * ignored rather than fatal so a hand-edited `project.yaml` can't wedge a sweep.
+ *
+ * #379 shipped these instance-only; #384 adds the override so a docs-heavy
+ * project can raise its CHANGELOG budget (or a lean project tighten it) without
+ * changing the fleet-wide default.
+ */
+/** Built-in defaults when neither env nor YAML nor a project override sets a budget. */
+export const DEFAULT_CURATION = Object.freeze({
+    overviewMaxTokens: 2000,
+    changelogMaxTokens: 8000,
+    claudeMaxTokens: 6000,
+});
+/** True when `n` is a usable budget: a positive, finite integer. */
+function isPositiveInt(n) {
+    return typeof n === "number" && Number.isInteger(n) && n > 0 && Number.isFinite(n);
+}
+/**
+ * Validate + normalise an untrusted value (from `project.yaml` or a PATCH body)
+ * into a {@link CurationOverride}, dropping any field that is missing or invalid,
+ * and returning `undefined` when nothing valid remains (so an empty override is
+ * never persisted). Each budget must be a positive integer. Defensive by design —
+ * a malformed hand-edit degrades to "inherit the instance default", never a
+ * sweep crash.
+ */
+export function sanitizeCurationOverride(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const o = value;
+    const out = {};
+    if (isPositiveInt(o.overviewMaxTokens))
+        out.overviewMaxTokens = o.overviewMaxTokens;
+    if (isPositiveInt(o.changelogMaxTokens))
+        out.changelogMaxTokens = o.changelogMaxTokens;
+    if (isPositiveInt(o.claudeMaxTokens))
+        out.claudeMaxTokens = o.claudeMaxTokens;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Resolve the effective curation budgets for a sweep: a valid per-project
+ * override wins field-by-field; every absent field inherits the instance default
+ * (which is itself `env > paddock.config.yaml > built-in default`). The override
+ * is re-sanitised so a corrupt on-disk value can't leak through.
+ */
+export function resolveCurationConfig(override, instanceDefault) {
+    const clean = sanitizeCurationOverride(override) ?? {};
+    return {
+        overviewMaxTokens: clean.overviewMaxTokens ?? instanceDefault.overviewMaxTokens,
+        changelogMaxTokens: clean.changelogMaxTokens ?? instanceDefault.changelogMaxTokens,
+        claudeMaxTokens: clean.claudeMaxTokens ?? instanceDefault.claudeMaxTokens,
+    };
+}

package/packages/server/dist/environment-prompt.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Paddock's built-in **environment** system prompt (issue #635).
+ *
+ * Paddock injects no system prompt of its own: on a default instance the keeper
+ * runs on Claude Code's stock `claude_code` preset, which is written for a
+ * terminal. Nothing anywhere tells the model that its replies are rendered as
+ * GitHub-Flavored Markdown in a browser (`MarkdownRenderer.tsx` = react-markdown
+ * + remark-gfm), or that `mcp__paddock__send_file` renders a file inline.
+ *
+ * This text is a small **append** to whatever system prompt the agent already
+ * has — it states environmental fact about the deployment, and deliberately does
+ * not instruct on role, tone or workflow (that is the `CLAUDE.md` hierarchy's
+ * layer, and it stays the user's).
+ *
+ * ## Why exactly two rules
+ *
+ * The text is not written from first principles — an earlier draft was, and the
+ * audit in issue #635 refuted most of it. It comes from auditing the 100 most
+ * recent chats on the dogfood instance (3,944 assistant text blocks, 2.1 MB of
+ * user-facing prose). Two findings carried ~90% of the measured value:
+ *
+ *  - **`#123` is dead text.** 4,440 bare refs vs 155 markdown links. Bare URLs
+ *    autolink under GFM and came out fine (only 4 inert, all backticked), so the
+ *    defect is specifically issue/PR refs — and it is not inability: single
+ *    messages link some refs and leave others bare.
+ *  - **Visual work is described, never shown.** 194 image reads, 138
+ *    screenshots, and **zero** images ever sent to a user. `send_file` was used
+ *    10 times, none of them an image. In one chat this cost a full re-work round
+ *    — the agent read 17 QC frames, showed none, misread one, and shipped a
+ *    regression the user then had to screenshot themselves.
+ *
+ * Things measured and deliberately **cut**, so they don't get re-added: "no ANSI
+ * colour" (0 escapes in 2.1 MB), "don't paste long content" (0 fences ≥40 lines;
+ * median fence is 3), "use markdown structure" (580 headings, 892 bullets, 101
+ * well-formed tables — already excellent), `file.ts:123` guidance (real but
+ * low-stakes; 72 of 75 sampled sit in backticks beside the symbol name), and
+ * mermaid (0 genuine missed opportunities; an instruction would over-trigger).
+ *
+ * ## Keep in sync
+ *
+ * The `send_file` tool description (`send-file-mcp.ts`) is the only other
+ * Paddock-aware signal in a normal turn. These two are the same message told
+ * twice; change one and re-read the other.
+ */
+/**
+ * The default environment prompt appended to every keeper turn unless the
+ * instance overrides or opts out (see `environmentPrompt` in config.ts).
+ *
+ * Kept verbatim from issue #635's evidence pass. Resist adding a third rule
+ * without measurement — several plausible candidates were cut above.
+ */
+export declare const DEFAULT_ENVIRONMENT_PROMPT = "You are running in Paddock, a web app \u2014 your replies render as GitHub-Flavored\nMarkdown in a browser, not as terminal output.\n\n- Show, don't describe. A screenshot, rendering, chart or file the user is meant\n  to look at should be sent with `mcp__paddock__send_file`, which renders it\n  inline. A filesystem path, or \"it's up on port 5026\", leaves them unable to see\n  your evidence \u2014 or to catch you misreading it.\n- Make clickable things clickable. Bare URLs autolink; `#123` does not \u2014 write\n  `[#123](https://github.com/owner/repo/issues/123)`. Prefer a full URL to a bare\n  port number, and link a chat or project rather than quoting its id.";

package/packages/server/dist/environment-prompt.js

@@ -0,0 +1,61 @@
+/**
+ * Paddock's built-in **environment** system prompt (issue #635).
+ *
+ * Paddock injects no system prompt of its own: on a default instance the keeper
+ * runs on Claude Code's stock `claude_code` preset, which is written for a
+ * terminal. Nothing anywhere tells the model that its replies are rendered as
+ * GitHub-Flavored Markdown in a browser (`MarkdownRenderer.tsx` = react-markdown
+ * + remark-gfm), or that `mcp__paddock__send_file` renders a file inline.
+ *
+ * This text is a small **append** to whatever system prompt the agent already
+ * has — it states environmental fact about the deployment, and deliberately does
+ * not instruct on role, tone or workflow (that is the `CLAUDE.md` hierarchy's
+ * layer, and it stays the user's).
+ *
+ * ## Why exactly two rules
+ *
+ * The text is not written from first principles — an earlier draft was, and the
+ * audit in issue #635 refuted most of it. It comes from auditing the 100 most
+ * recent chats on the dogfood instance (3,944 assistant text blocks, 2.1 MB of
+ * user-facing prose). Two findings carried ~90% of the measured value:
+ *
+ *  - **`#123` is dead text.** 4,440 bare refs vs 155 markdown links. Bare URLs
+ *    autolink under GFM and came out fine (only 4 inert, all backticked), so the
+ *    defect is specifically issue/PR refs — and it is not inability: single
+ *    messages link some refs and leave others bare.
+ *  - **Visual work is described, never shown.** 194 image reads, 138
+ *    screenshots, and **zero** images ever sent to a user. `send_file` was used
+ *    10 times, none of them an image. In one chat this cost a full re-work round
+ *    — the agent read 17 QC frames, showed none, misread one, and shipped a
+ *    regression the user then had to screenshot themselves.
+ *
+ * Things measured and deliberately **cut**, so they don't get re-added: "no ANSI
+ * colour" (0 escapes in 2.1 MB), "don't paste long content" (0 fences ≥40 lines;
+ * median fence is 3), "use markdown structure" (580 headings, 892 bullets, 101
+ * well-formed tables — already excellent), `file.ts:123` guidance (real but
+ * low-stakes; 72 of 75 sampled sit in backticks beside the symbol name), and
+ * mermaid (0 genuine missed opportunities; an instruction would over-trigger).
+ *
+ * ## Keep in sync
+ *
+ * The `send_file` tool description (`send-file-mcp.ts`) is the only other
+ * Paddock-aware signal in a normal turn. These two are the same message told
+ * twice; change one and re-read the other.
+ */
+/**
+ * The default environment prompt appended to every keeper turn unless the
+ * instance overrides or opts out (see `environmentPrompt` in config.ts).
+ *
+ * Kept verbatim from issue #635's evidence pass. Resist adding a third rule
+ * without measurement — several plausible candidates were cut above.
+ */
+export const DEFAULT_ENVIRONMENT_PROMPT = `You are running in Paddock, a web app — your replies render as GitHub-Flavored
+Markdown in a browser, not as terminal output.
+
+- Show, don't describe. A screenshot, rendering, chart or file the user is meant
+  to look at should be sent with \`mcp__paddock__send_file\`, which renders it
+  inline. A filesystem path, or "it's up on port 5026", leaves them unable to see
+  your evidence — or to catch you misreading it.
+- Make clickable things clickable. Bare URLs autolink; \`#123\` does not — write
+  \`[#123](https://github.com/owner/repo/issues/123)\`. Prefer a full URL to a bare
+  port number, and link a chat or project rather than quoting its id.`;

package/packages/server/dist/event-bus.d.ts

@@ -0,0 +1,87 @@
+/**
+ * In-process lifecycle event bus (Epic G, ticket G1 — hook foundation).
+ *
+ * Paddock lifecycle events (a chat archived, later: created/forked/unarchived) fire
+ * INSIDE Paddock's own server — unlike schedules (Epic D), there is no herdctl seam
+ * to add. This tiny typed emitter is that seam: the place that COMMITS a lifecycle
+ * action ({@link ArchiveEvent}, from the archive route / the self-MCP archive tool)
+ * `emit`s the event AFTER it commits, and the hook dispatcher (wired in `ws.ts`)
+ * `on`s it to fire each of the project's enabled hooks via `startAgentTurn`.
+ *
+ * Two invariants make this safe as a foundation (GG-2, non-blocking after-commit):
+ *
+ *  1. **`emit` never throws into its caller and never blocks it.** Listeners run
+ *     fire-and-forget; a listener that throws (sync or async) is swallowed so the
+ *     triggering action (the archive) can NEVER fail or hang because of a hook. This
+ *     is the whole point — a buggy hook must not break the thing that triggered it.
+ *  2. **The bus event name IS a hook/trigger `event` value.** So a dispatcher is a
+ *     trivial `bus.on("onArchive", …)` that matches hooks/triggers with that `event`.
+ *     v1 wired `onArchive` (hooks + event triggers); T5 adds `afterTurn`, which drives
+ *     the folded-in sweeper (the default post-turn curator trigger).
+ *
+ * Kept deliberately minimal (no Node `EventEmitter`: its `error`-event footgun and
+ * default max-listener warnings are noise here) and dependency-free, matching the
+ * hand-rolled sidecar style of the rest of the server.
+ */
+/**
+ * Payload for the `onArchive` event: which chat, in which project, was archived.
+ * The dispatcher passes `slug` to resolve the project's hooks and `sessionId` into
+ * the fired hook's prompt so the hook knows WHAT was archived (e.g. which pm server
+ * / clone to tear down).
+ */
+export interface ArchiveEvent {
+    /** The project slug whose chat was archived. */
+    slug: string;
+    /** The archived chat's session id. */
+    sessionId: string;
+}
+/**
+ * Payload for the `afterTurn` event (Epic T / T5): a turn just completed in `slug`.
+ * Emitted at every post-turn commit site (a human chat turn, a session-mode wake, and
+ * every server-initiated `startAgentTurn`) so the folded-in sweeper — the default
+ * `curate-overview` `event`/`afterTurn` trigger — dispatches EXACTLY ONCE per turn.
+ * `sessionId` is the chat whose turn completed (`null` when none was resolved), carried
+ * for parity with `onArchive`; the curator only needs the `slug` to sweep.
+ */
+export interface AfterTurnEvent {
+    /** The project slug whose chat turn just completed. */
+    slug: string;
+    /** The completed turn's session id, or `null` if none was resolved. */
+    sessionId: string | null;
+}
+/**
+ * The typed event map. The bus event name IS a trigger/hook `event` value, so
+ * `on`/`emit` line up with the dispatchers. `onArchive` fires the enabled onArchive
+ * hooks + event triggers (Epic G/T); `afterTurn` (T5) drives the post-turn curator
+ * (the sweeper). Adding a sibling event is: a new value here + its payload + an `emit`
+ * at the commit site.
+ */
+export interface PaddockEventMap {
+    onArchive: ArchiveEvent;
+    afterTurn: AfterTurnEvent;
+}
+/** A lifecycle event name — a key of {@link PaddockEventMap}, matching a trigger/hook event. */
+export type PaddockEventName = keyof PaddockEventMap;
+/** A listener for event `E`; may be async — its result is awaited-and-swallowed. */
+export type EventListener<E extends PaddockEventName> = (payload: PaddockEventMap[E]) => void | Promise<void>;
+/**
+ * A minimal typed publish/subscribe hub. One instance is constructed in `app.ts` and
+ * shared by the commit sites (archive route / self-MCP archive tool → `emit`) and the
+ * hook dispatcher in `ws.ts` (→ `on`).
+ */
+export declare class PaddockEventBus {
+    private readonly listeners;
+    /**
+     * Subscribe `listener` to `event`. Returns an unsubscribe function. Multiple
+     * listeners per event are supported (v1 registers one — the hook dispatcher).
+     */
+    on<E extends PaddockEventName>(event: E, listener: EventListener<E>): () => void;
+    /**
+     * Fire `event` to every subscribed listener, FIRE-AND-FORGET. Returns immediately
+     * (never awaits a listener) and never throws into the caller — a listener that
+     * throws synchronously or rejects asynchronously is swallowed. So the action that
+     * emitted the event (an archive commit) is fully decoupled from hook execution: it
+     * neither waits on hooks nor fails because of them (GG-2).
+     */
+    emit<E extends PaddockEventName>(event: E, payload: PaddockEventMap[E]): void;
+}

package/packages/server/dist/event-bus.js

@@ -0,0 +1,48 @@
+/**
+ * A minimal typed publish/subscribe hub. One instance is constructed in `app.ts` and
+ * shared by the commit sites (archive route / self-MCP archive tool → `emit`) and the
+ * hook dispatcher in `ws.ts` (→ `on`).
+ */
+export class PaddockEventBus {
+    listeners = new Map();
+    /**
+     * Subscribe `listener` to `event`. Returns an unsubscribe function. Multiple
+     * listeners per event are supported (v1 registers one — the hook dispatcher).
+     */
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return () => {
+            this.listeners.get(event)?.delete(listener);
+        };
+    }
+    /**
+     * Fire `event` to every subscribed listener, FIRE-AND-FORGET. Returns immediately
+     * (never awaits a listener) and never throws into the caller — a listener that
+     * throws synchronously or rejects asynchronously is swallowed. So the action that
+     * emitted the event (an archive commit) is fully decoupled from hook execution: it
+     * neither waits on hooks nor fails because of them (GG-2).
+     */
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set || set.size === 0)
+            return;
+        for (const listener of set) {
+            try {
+                // A listener may be sync or async. Wrap in Promise.resolve so a synchronous
+                // throw and an async rejection are both funneled into the same swallow — the
+                // emitter's caller is never affected either way.
+                void Promise.resolve()
+                    .then(() => listener(payload))
+                    .catch(() => undefined);
+            }
+            catch {
+                /* a synchronous throw before the microtask — swallow too */
+            }
+        }
+    }
+}

package/packages/server/dist/git.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Clone an external git repo into `dest` — the checkout that becomes a
+ * repo-backed project's working directory (issue #187). Shells out to the `git`
+ * binary via execFile (arg array, no shell → no injection surface), the same
+ * discipline as {@link GitService}.
+ *
+ * A FULL clone (not `--depth 1`): a repo-backed project is where you *do
+ * engineering*, so the keeper wants real history — `git log`, blame, bisect, and
+ * a non-shallow base for branches/PRs — from the start. Credentials are the
+ * ambient git environment's job (a public URL needs none; a private repo needs a
+ * box-level credential helper / token — per-project scoped credentials are a
+ * documented #187 follow-up). Throws with git's stderr on failure so the caller
+ * can surface a clean error and roll back the half-created project.
+ */
+export declare function cloneRepo(url: string, dest: string): Promise<void>;
+/** A single changed path within a project (porcelain v1 semantics). */
+export interface GitFileChange {
+    /** Path relative to the project directory. */
+    path: string;
+    /** Two-letter porcelain code, trimmed (e.g. "M", "??", "A", "RM"). */
+    status: string;
+    /** Whether the change is staged (index differs from HEAD). */
+    staged: boolean;
+    /** True for an untracked ("??") path. */
+    untracked: boolean;
+    /** Lines added (undefined for a binary change). Untracked text files count as all-added. */
+    added?: number;
+    /** Lines removed (undefined for a binary change / an untracked file). */
+    removed?: number;
+    /** True when the change is binary (no line-level stat). */
+    binary?: boolean;
+}
+/** A project's git status (or `repo: false` when the store isn't a repo). */
+export interface GitProjectStatus {
+    /** Whether `projectsRoot` is a git working tree at all. */
+    repo: boolean;
+    /** Current branch (omitted when not a repo / detached). */
+    branch?: string;
+    /** Changes confined to this project's subtree. */
+    files: GitFileChange[];
+    /** True when the project subtree has no pending changes. */
+    clean: boolean;
+}
+export declare class GitService {
+    private readonly projectsRoot;
+    private readonly author;
+    /** Cached repo-detection result for `projectsRoot` (null = not yet checked). */
+    private repoFlag;
+    /**
+     * @param projectsRoot Absolute path to the projects root the service operates on.
+     * @param author Commit identity used when Paddock commits on a project's behalf.
+     *   Folded into PaddockConfig from `PADDOCK_GIT_AUTHOR_*` (issue #269); defaults
+     *   preserve the pre-fold values so a bare `new GitService(root)` is unchanged.
+     */
+    constructor(projectsRoot: string, author?: {
+        name: string;
+        email: string;
+    });
+    /** Run git in a directory, returning stdout. Throws on non-zero exit. */
+    private git;
+    /**
+     * Whether the backing store is a git working tree. Cached after the first
+     * successful check (repo-ness doesn't change under a running server); a thrown
+     * git / missing-binary error resolves to `false`.
+     */
+    isRepo(): Promise<boolean>;
+    /** Force the next `isRepo()` to re-check (e.g. after `git init` at runtime). */
+    resetRepoCache(): void;
+    /**
+     * Status for one project's subtree. Returns `{ repo: false }` when the store
+     * isn't a repo (the UI then hides the git affordance). Paths are relative to
+     * `projectDir`.
+     */
+    projectStatus(projectDir: string): Promise<GitProjectStatus>;
+    /**
+     * `git diff --numstat` for a project's tracked working-tree changes, keyed by
+     * PROJECT-relative path (`--relative` makes git emit paths relative to the
+     * project dir, matching the porcelain paths). Binary changes report `-\t-` and
+     * are flagged `binary`. Returns an empty map on any failure.
+     */
+    private trackedNumstat;
+    /**
+     * Unified diff for a project's tracked changes (working tree vs HEAD), or for
+     * a single file when `file` is given. Untracked files don't appear in a diff
+     * (they're listed by `projectStatus`). Returns "" when not a repo / no diff.
+     */
+    projectDiff(projectDir: string, file?: string): Promise<string>;
+    /** Commit identity (from config, no global git config needed). */
+    private identity;
+    /** Origin remote info + ahead/behind vs upstream (best-effort). */
+    remote(): Promise<{
+        repo: boolean;
+        configured: boolean;
+        url?: string;
+        branch?: string;
+        ahead?: number;
+        behind?: number;
+    }>;
+    /**
+     * Stage + commit a single project's changes (tracked mods, deletions, and
+     * untracked files within its subtree). `committed: false` when nothing was
+     * pending. Explicit identity so the LXC needs no global git config.
+     *
+     * When `paths` (project-relative) is given, commit ONLY those files — the
+     * pathspec scopes both the staging and the commit, so unselected changes stay
+     * uncommitted (issue #258). Paths are validated to stay inside the subtree; an
+     * all-invalid selection is an error rather than a silent commit-everything.
+     * Omitting `paths` keeps the legacy commit-the-whole-subtree behavior.
+     */
+    commitProject(projectDir: string, message: string, paths?: string[]): Promise<{
+        committed: boolean;
+        hash?: string;
+        error?: string;
+    }>;
+    /**
+     * Uncommitted-file counts per top-level project subtree, in ONE `git status`
+     * over the whole store (cheap — no per-project fan-out) so the projects grid
+     * can flag "N uncommitted" without opening each project (issue #258). Keyed by
+     * the first path segment (= project slug); only dirty projects appear. `{}`
+     * when the store isn't a repo.
+     */
+    dirtyCounts(): Promise<Record<string, number>>;
+    /** Push the current branch to origin (sets upstream on first push). */
+    push(): Promise<{
+        pushed: boolean;
+        error?: string;
+    }>;
+}