klyro 1.0.0 → 1.0.2

package/dist/agent/stream-budget.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Rate-limit scheduler for provider streams.
+ *
+ * A global in-flight counter + FIFO semaphore caps concurrent
+ * `ProviderAdapter.stream` calls at `MAX_CONCURRENT_STREAMS` (4). An
+ * adaptive cooldown collapses the cap to 1 while a recent 429 was
+ * observed (`noteRateLimited`), honouring an optional server-provided
+ * `Retry-After` delay, otherwise 60s.
+ *
+ * Consumed by `retryingAdapter` (see `./retry.js`), which acquires one
+ * slot around each `inner.stream` call and releases it in a `finally`.
+ * Aborted waiters are dequeued and rejected promptly.
+ */
+export declare const MAX_CONCURRENT_STREAMS = 4;
+/** Fallback cooldown when no Retry-After delay was provided. */
+export declare const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60000;
+/**
+ * Record a 429 (or equivalent) rate-limit signal. Collapses the stream
+ * cap to 1 for `retryAfterMs` (or 60s when absent/invalid).
+ */
+export declare function noteRateLimited(retryAfterMs?: number): void;
+/**
+ * Acquire a stream slot. Grants immediately when `inFlight` is under the
+ * effective cap, otherwise queues FIFO until a release (or the cooldown
+ * lifting) frees one. Abort-aware: an already-aborted signal rejects
+ * immediately; aborting while queued dequeues and rejects promptly.
+ */
+export declare function acquireStreamSlot(signal?: AbortSignal): Promise<() => void>;
+/** Observable budget state (tests/diagnostics). */
+export declare function streamBudgetState(): {
+    inFlight: number;
+    queued: number;
+    cap: number;
+};
+/** Reset the budget (counters, cooldown, queued waiters). Tests only. */
+export declare function setStreamBudgetForTests(): void;

package/dist/agent/stream-budget.js

@@ -0,0 +1,121 @@
+/**
+ * Rate-limit scheduler for provider streams.
+ *
+ * A global in-flight counter + FIFO semaphore caps concurrent
+ * `ProviderAdapter.stream` calls at `MAX_CONCURRENT_STREAMS` (4). An
+ * adaptive cooldown collapses the cap to 1 while a recent 429 was
+ * observed (`noteRateLimited`), honouring an optional server-provided
+ * `Retry-After` delay, otherwise 60s.
+ *
+ * Consumed by `retryingAdapter` (see `./retry.js`), which acquires one
+ * slot around each `inner.stream` call and releases it in a `finally`.
+ * Aborted waiters are dequeued and rejected promptly.
+ */
+export const MAX_CONCURRENT_STREAMS = 4;
+/** Fallback cooldown when no Retry-After delay was provided. */
+export const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60_000;
+let inFlight = 0;
+/** `Date.now()` timestamp until which the cap stays collapsed at 1. */
+let recent429Until = 0;
+const queue = [];
+function abortError() {
+    const err = new Error('stream slot acquisition aborted');
+    err.name = 'AbortError';
+    return err;
+}
+function effectiveCap(now = Date.now()) {
+    return now < recent429Until ? 1 : MAX_CONCURRENT_STREAMS;
+}
+function makeRelease() {
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        inFlight = Math.max(0, inFlight - 1);
+        pump();
+    };
+}
+/** Grant queued waiters while a slot is free under the current cap. */
+function pump() {
+    while (queue.length > 0 && inFlight < effectiveCap()) {
+        const waiter = queue.shift();
+        if (!waiter)
+            break;
+        if (waiter.signal?.aborted) {
+            waiter.reject(abortError());
+            continue;
+        }
+        if (waiter.signal && waiter.onAbort) {
+            waiter.signal.removeEventListener('abort', waiter.onAbort);
+        }
+        inFlight += 1;
+        waiter.resolve(makeRelease());
+    }
+}
+/**
+ * Record a 429 (or equivalent) rate-limit signal. Collapses the stream
+ * cap to 1 for `retryAfterMs` (or 60s when absent/invalid).
+ */
+export function noteRateLimited(retryAfterMs) {
+    const cooldown = typeof retryAfterMs === 'number' &&
+        Number.isFinite(retryAfterMs) &&
+        retryAfterMs >= 0
+        ? retryAfterMs
+        : DEFAULT_RATE_LIMIT_COOLDOWN_MS;
+    recent429Until = Date.now() + cooldown;
+    // Wake queued waiters once the cooldown lifts even if no release
+    // happens in between (holders may outlive the cooldown). Unref'd so
+    // tests and short-lived processes never hang on this timer.
+    if (cooldown > 0 && cooldown < 3_600_000) {
+        const timer = setTimeout(pump, cooldown);
+        timer.unref?.();
+    }
+}
+/**
+ * Acquire a stream slot. Grants immediately when `inFlight` is under the
+ * effective cap, otherwise queues FIFO until a release (or the cooldown
+ * lifting) frees one. Abort-aware: an already-aborted signal rejects
+ * immediately; aborting while queued dequeues and rejects promptly.
+ */
+export function acquireStreamSlot(signal) {
+    if (signal?.aborted)
+        return Promise.reject(abortError());
+    if (inFlight < effectiveCap()) {
+        inFlight += 1;
+        return Promise.resolve(makeRelease());
+    }
+    return new Promise((resolve, reject) => {
+        const waiter = { resolve, reject };
+        if (signal) {
+            waiter.signal = signal;
+            waiter.onAbort = () => {
+                const idx = queue.indexOf(waiter);
+                if (idx >= 0)
+                    queue.splice(idx, 1);
+                reject(abortError());
+            };
+            signal.addEventListener('abort', waiter.onAbort, { once: true });
+        }
+        queue.push(waiter);
+        // Re-check: the cap may have widened (cooldown expiry) between the
+        // fast-path check and the push.
+        pump();
+    });
+}
+/** Observable budget state (tests/diagnostics). */
+export function streamBudgetState() {
+    return { inFlight, queued: queue.length, cap: effectiveCap() };
+}
+/** Reset the budget (counters, cooldown, queued waiters). Tests only. */
+export function setStreamBudgetForTests() {
+    inFlight = 0;
+    recent429Until = 0;
+    const pending = queue.splice(0, queue.length);
+    for (const waiter of pending) {
+        if (waiter.signal && waiter.onAbort) {
+            waiter.signal.removeEventListener('abort', waiter.onAbort);
+        }
+        waiter.reject(new Error('stream budget reset'));
+    }
+}

package/dist/agent/worktree-manager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Git worktree isolation for parallel write-capable child agents.
+ *
+ * Each write-capable child gets its own worktree on a branch
+ * `klyro/<taskId>` so concurrent children never clobber each other's files.
+ * `task_apply` merges the branch back into the parent tree; failures,
+ * cancellations, and timeouts remove the worktree best-effort.
+ *
+ * Semantics worth knowing:
+ *   - Dirty parent: the merge runs in the parent checkout, so uncommitted
+ *     parent edits can conflict. On conflict the merge is ABORTED (no
+ *     commit), the branch is kept, and the caller gets MERGE_CONFLICT with
+ *     the file list — resolve and re-apply.
+ *   - Stale branch: a leftover `klyro/<taskId>` branch (e.g. from a crashed
+ *     session) makes `createWorktree` fail. Delete the stale branch
+ *     (`deleteBranch`) or sweep orphaned worktrees (`pruneStaleWorktrees`)
+ *     before retrying.
+ *   - No-apply: tasks that never reach `succeeded` are NEVER merged — their
+ *     worktrees are removed best-effort and `task_apply` reports NOT_READY.
+ *
+ * All git invocations go through `execFile` argv (no shell) with a ~30s
+ * timeout, so this is safe on Windows.
+ */
+/** Per-command timeout for every git invocation. */
+export declare const GIT_TIMEOUT_MS = 30000;
+export interface WorktreeInfo {
+    worktreePath: string;
+    branch: string;
+}
+export interface MergeResult {
+    merged: boolean;
+    conflictFiles: string[];
+}
+/** True when `cwd` is inside a git working tree. Never throws — false on any failure. */
+export declare function ensureGitRepo(cwd: string): Promise<boolean>;
+/** Resolve the repo top-level for any path inside it. Throws when not in a repo. */
+export declare function repoTopLevel(cwd: string): Promise<string>;
+/**
+ * Create an isolated worktree for a task on branch `klyro/<taskId>`,
+ * rooted at `<repo>/.klyro/worktrees/<taskId>` from HEAD.
+ */
+export declare function createWorktree(opts: {
+    repoCwd: string;
+    taskId: string;
+}): Promise<WorktreeInfo>;
+/**
+ * Merge a task branch into the current checkout (`repoCwd`) with
+ * `git merge --no-ff --no-edit`. On conflict, parses `git status
+ * --porcelain` for unmerged paths (UU/AA/DD), aborts the merge WITHOUT
+ * committing, and returns `{ merged: false, conflictFiles }`.
+ */
+export declare function mergeWorktree(opts: {
+    repoCwd: string;
+    branch: string;
+}): Promise<MergeResult>;
+/** Remove a worktree and prune its metadata. Throws with context on failure. */
+export declare function removeWorktree(opts: {
+    repoCwd: string;
+    worktreePath: string;
+    force?: boolean;
+}): Promise<void>;
+/** Delete a task branch (best-effort cleanup after a successful merge). Never throws. */
+export declare function deleteBranch(opts: {
+    repoCwd: string;
+    branch: string;
+}): Promise<void>;
+/**
+ * Remove worktrees under `.klyro/worktrees` whose task id is NOT in
+ * `activeTaskIds` (orphans from crashed/timed-out sessions). Lists
+ * `git worktree list --porcelain`, force-removes each stale entry, and
+ * returns the removed paths. Never throws — per-worktree failures are
+ * skipped and a failing `git` itself yields `[]`.
+ */
+export declare function pruneStaleWorktrees(repoCwd: string, activeTaskIds: readonly string[]): Promise<string[]>;

package/dist/agent/worktree-manager.js

@@ -0,0 +1,189 @@
+/**
+ * Git worktree isolation for parallel write-capable child agents.
+ *
+ * Each write-capable child gets its own worktree on a branch
+ * `klyro/<taskId>` so concurrent children never clobber each other's files.
+ * `task_apply` merges the branch back into the parent tree; failures,
+ * cancellations, and timeouts remove the worktree best-effort.
+ *
+ * Semantics worth knowing:
+ *   - Dirty parent: the merge runs in the parent checkout, so uncommitted
+ *     parent edits can conflict. On conflict the merge is ABORTED (no
+ *     commit), the branch is kept, and the caller gets MERGE_CONFLICT with
+ *     the file list — resolve and re-apply.
+ *   - Stale branch: a leftover `klyro/<taskId>` branch (e.g. from a crashed
+ *     session) makes `createWorktree` fail. Delete the stale branch
+ *     (`deleteBranch`) or sweep orphaned worktrees (`pruneStaleWorktrees`)
+ *     before retrying.
+ *   - No-apply: tasks that never reach `succeeded` are NEVER merged — their
+ *     worktrees are removed best-effort and `task_apply` reports NOT_READY.
+ *
+ * All git invocations go through `execFile` argv (no shell) with a ~30s
+ * timeout, so this is safe on Windows.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as path from 'node:path';
+import { filteredEnv } from '../tools/shell/shell-exec.js';
+const execFileAsync = promisify(execFile);
+/** Per-command timeout for every git invocation. */
+export const GIT_TIMEOUT_MS = 30_000;
+async function git(repoCwd, args) {
+    // Filtered env (same call shape as shell-exec) so secrets never reach
+    // child processes. Then strip repo-pinning vars so discovery is always
+    // relative to `repoCwd` (a sandbox may export GIT_DIR for its own
+    // harness — that must not make every directory look like a repo).
+    const env = { ...filteredEnv() };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_NAMESPACE;
+    const r = await execFileAsync('git', [...args], {
+        cwd: repoCwd,
+        timeout: GIT_TIMEOUT_MS,
+        windowsHide: true,
+        maxBuffer: 4 * 1024 * 1024,
+        env,
+    });
+    return { stdout: r.stdout, stderr: r.stderr };
+}
+/** True when `cwd` is inside a git working tree. Never throws — false on any failure. */
+export async function ensureGitRepo(cwd) {
+    try {
+        const r = await git(cwd, ['rev-parse', '--is-inside-work-tree']);
+        return r.stdout.trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the repo top-level for any path inside it. Throws when not in a repo. */
+export async function repoTopLevel(cwd) {
+    const r = await git(cwd, ['rev-parse', '--show-toplevel']);
+    return r.stdout.trim();
+}
+function branchForTask(taskId) {
+    return `klyro/${taskId}`;
+}
+/**
+ * Create an isolated worktree for a task on branch `klyro/<taskId>`,
+ * rooted at `<repo>/.klyro/worktrees/<taskId>` from HEAD.
+ */
+export async function createWorktree(opts) {
+    const branch = branchForTask(opts.taskId);
+    const top = await repoTopLevel(opts.repoCwd);
+    const worktreePath = path.join(top, '.klyro', 'worktrees', opts.taskId);
+    await git(opts.repoCwd, ['worktree', 'add', '-b', branch, worktreePath, 'HEAD']);
+    return { worktreePath, branch };
+}
+/**
+ * Merge a task branch into the current checkout (`repoCwd`) with
+ * `git merge --no-ff --no-edit`. On conflict, parses `git status
+ * --porcelain` for unmerged paths (UU/AA/DD), aborts the merge WITHOUT
+ * committing, and returns `{ merged: false, conflictFiles }`.
+ */
+export async function mergeWorktree(opts) {
+    try {
+        await git(opts.repoCwd, ['merge', '--no-ff', '--no-edit', opts.branch]);
+        return { merged: true, conflictFiles: [] };
+    }
+    catch {
+        const conflictFiles = await unmergedFiles(opts.repoCwd);
+        try {
+            await git(opts.repoCwd, ['merge', '--abort']);
+        }
+        catch {
+            /* best-effort: leave the repo as-is if abort itself fails */
+        }
+        return { merged: false, conflictFiles };
+    }
+}
+async function unmergedFiles(repoCwd) {
+    try {
+        const r = await git(repoCwd, ['status', '--porcelain']);
+        const out = [];
+        for (const line of r.stdout.split('\n')) {
+            if (line.length < 4)
+                continue;
+            const x = line[0];
+            const y = line[1];
+            const unmerged = (x === 'U' || y === 'U' || x === 'A' || y === 'A') && (x === 'U' || y === 'U' || (x === 'A' && y === 'A'));
+            // Unmerged statuses: UU, AA, DD, AU, UA, UD, DU.
+            const code = `${x}${y}`;
+            if (['UU', 'AA', 'DD', 'AU', 'UA', 'UD', 'DU'].includes(code) || unmerged) {
+                out.push(line.slice(3).trim());
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** Remove a worktree and prune its metadata. Throws with context on failure. */
+export async function removeWorktree(opts) {
+    const args = ['worktree', 'remove', ...(opts.force ? ['--force'] : []), opts.worktreePath];
+    try {
+        await git(opts.repoCwd, args);
+    }
+    catch (err) {
+        throw new Error(`git worktree remove failed for ${opts.worktreePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        try {
+            await git(opts.repoCwd, ['worktree', 'prune']);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/** Delete a task branch (best-effort cleanup after a successful merge). Never throws. */
+export async function deleteBranch(opts) {
+    try {
+        await git(opts.repoCwd, ['branch', '-D', opts.branch]);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Remove worktrees under `.klyro/worktrees` whose task id is NOT in
+ * `activeTaskIds` (orphans from crashed/timed-out sessions). Lists
+ * `git worktree list --porcelain`, force-removes each stale entry, and
+ * returns the removed paths. Never throws — per-worktree failures are
+ * skipped and a failing `git` itself yields `[]`.
+ */
+export async function pruneStaleWorktrees(repoCwd, activeTaskIds) {
+    const removed = [];
+    try {
+        const r = await git(repoCwd, ['worktree', 'list', '--porcelain']);
+        const active = new Set(activeTaskIds);
+        for (const line of r.stdout.split('\n')) {
+            const raw = /^worktree (.+)$/.exec(line.trim())?.[1];
+            if (!raw)
+                continue;
+            // git prints forward slashes even on win32 — normalize so returned
+            // paths textually match the path.join-built worktreePath.
+            const wp = path.normalize(raw);
+            // Only manage our own namespace: <repo>/.klyro/worktrees/<taskId>.
+            const parts = wp.split(/[\\/]/);
+            const idx = parts.lastIndexOf('worktrees');
+            if (idx < 1 || parts[idx - 1] !== '.klyro' || idx + 1 >= parts.length)
+                continue;
+            const taskId = parts[idx + 1];
+            if (!taskId || active.has(taskId))
+                continue;
+            try {
+                await removeWorktree({ repoCwd, worktreePath: wp, force: true });
+                removed.push(wp);
+            }
+            catch {
+                /* skip — never throws */
+            }
+        }
+    }
+    catch {
+        /* git itself failed (not a repo, binary missing) — return what we have */
+    }
+    return removed;
+}

package/dist/checkpoints/store.d.ts

@@ -1,5 +1,14 @@
 /**
  * 4.5 — Checkpoint snapshots: every mutation to checkpoints dir
+ *
+ * Snapshot bytes stay RAW (no redaction): checkpoint copies must be
+ * bit-identical to the working tree so undo() restores exact fidelity —
+ * redacting at snapshot time would corrupt restores (a redacted snapshot
+ * written back would permanently replace real code with [REDACTED]).
+ * Same-trust-domain rationale: snapshots never leave the project dir and
+ * are only read back by undo() into the same tree, so secret hygiene is
+ * enforced at the trace/persist boundaries (TraceWriter, SessionStore)
+ * instead of here.
  */
 export declare function snapshot(cwd: string, files: string[]): Promise<string>;
 export declare function listCheckpoints(cwd: string): Promise<string[]>;

package/dist/checkpoints/store.js

@@ -1,12 +1,47 @@
 /**
  * 4.5 — Checkpoint snapshots: every mutation to checkpoints dir
+ *
+ * Snapshot bytes stay RAW (no redaction): checkpoint copies must be
+ * bit-identical to the working tree so undo() restores exact fidelity —
+ * redacting at snapshot time would corrupt restores (a redacted snapshot
+ * written back would permanently replace real code with [REDACTED]).
+ * Same-trust-domain rationale: snapshots never leave the project dir and
+ * are only read back by undo() into the same tree, so secret hygiene is
+ * enforced at the trace/persist boundaries (TraceWriter, SessionStore)
+ * instead of here.
  */
 import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 function ckptDir(cwd) {
     return path.join(cwd, '.klyro', 'checkpoints');
 }
+/**
+ * Best-effort permission lockdown (0600 files / 0700 dirs).
+ * Windows ACLs ignore POSIX mode bits — no-op by design.
+ */
+function lockDown(p, mode) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        fsSync.chmodSync(p, mode);
+    }
+    catch { /* best-effort only */ }
+}
+/** Best-effort fsync of a just-written file (crash safety). */
+async function fsyncFile(p) {
+    try {
+        const fh = await fs.open(p, 'r+');
+        try {
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    catch { /* ignore on Windows */ }
+}
 /**
  * Resolve a checkpoint file list entry inside cwd. Returns null for anything
  * escaping the project (no arbitrary read/write outside cwd, via either the
@@ -22,9 +57,11 @@ function containedPath(cwd, base, rel) {
 export async function snapshot(cwd, files) {
     const dir = ckptDir(cwd);
     await fs.mkdir(dir, { recursive: true });
+    lockDown(dir, 0o700);
     const id = `${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
     const dest = path.join(dir, id);
     await fs.mkdir(dest, { recursive: true });
+    lockDown(dest, 0o700);
     const missing = [];
     const kept = [];
     for (const f of files) {
@@ -39,6 +76,8 @@ export async function snapshot(cwd, files) {
                 continue;
             await fs.mkdir(path.dirname(out), { recursive: true });
             await fs.writeFile(out, data);
+            lockDown(out, 0o600);
+            await fsyncFile(out);
             kept.push(rel);
         }
         catch (e) {
@@ -47,8 +86,12 @@ export async function snapshot(cwd, files) {
                 missing.push(f);
         }
     }
-    // Save meta
-    await fs.writeFile(path.join(dest, '.meta.json'), JSON.stringify({ id, files: kept, missing, ts: Date.now() }, null, 2));
+    // Save meta (fsync before the checkpoint is visible — mirrors the
+    // SessionStore.writeIndex atomic pattern).
+    const metaPath = path.join(dest, '.meta.json');
+    await fs.writeFile(metaPath, JSON.stringify({ id, files: kept, missing, ts: Date.now() }, null, 2));
+    lockDown(metaPath, 0o600);
+    await fsyncFile(metaPath);
     // Best-effort last.diff for the repair guard (guardRepair reads it).
     try {
         const { spawn } = await import('node:child_process');
@@ -86,8 +129,15 @@ export async function snapshot(cwd, files) {
                 resolve('');
             });
         });
-        if (diffText)
+        if (diffText) {
             await fs.writeFile(path.join(dir, 'last.diff'), diffText, 'utf-8');
+            // Per-checkpoint diff file (best-effort); the repair guard keeps
+            // reading last.diff, so its behavior is unchanged.
+            try {
+                await fs.writeFile(path.join(dir, `${id}.diff`), diffText, 'utf-8');
+            }
+            catch { /* best-effort only */ }
+        }
     }
     catch { /* best-effort only */ }
     return id;
@@ -96,8 +146,9 @@ export async function listCheckpoints(cwd) {
     const dir = ckptDir(cwd);
     try {
         const entries = await fs.readdir(dir);
-        // last.diff is a guard artifact, not a checkpoint (must never be an undo target).
-        return entries.filter((e) => !e.startsWith('.') && e !== 'last.diff').sort();
+        // last.diff is a guard artifact and <id>.diff files are per-checkpoint
+        // diffs — neither is a checkpoint (must never be an undo target).
+        return entries.filter((e) => !e.startsWith('.') && e !== 'last.diff' && !e.endsWith('.diff')).sort();
     }
     catch {
         return [];

package/dist/cli/auth.js

@@ -111,7 +111,11 @@ export async function runLogout(provider) {
         const creds = JSON.parse(raw);
         if (provider) {
             delete creds[provider];
-            await fs.writeFile(credPath(), JSON.stringify(creds, null, 2), 'utf-8');
+            await fs.writeFile(credPath(), JSON.stringify(creds, null, 2), { mode: 0o600 });
+            try {
+                await fs.chmod(credPath(), 0o600);
+            }
+            catch { /* ignore on Windows */ }
             process.stdout.write(`Removed ${provider} key\n`);
         }
         else {
@@ -128,6 +132,17 @@ export async function runLogout(provider) {
 }
 export function getStoredKey(provider) {
     try {
+        // Warn (don't refuse) when the credentials file is group/other-readable.
+        // Refusing would lock out existing users with old umasks; warn instead.
+        if (process.platform !== 'win32') {
+            try {
+                const st = fsSync.statSync(credPath());
+                if ((st.mode & 0o077) !== 0) {
+                    process.stderr.write(`warning: credentials file ${credPath()} is group/other-readable (mode ${(st.mode & 0o777).toString(8)}) — run chmod 600 on it\n`);
+                }
+            }
+            catch { /* missing file → no warning */ }
+        }
         const raw = fsSync.readFileSync(credPath(), 'utf-8');
         const creds = JSON.parse(raw);
         const v = creds[provider];

package/dist/cli/commit.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `klyro commit` — conventional commit of already-staged changes.
+ *
+ * Steps:
+ *   (a) `git status --porcelain` must show staged entries (index column set).
+ *       Nothing staged → error 'nothing staged (git add first)', exit 2.
+ *       (`--yes` never bypasses this — there is nothing to commit.)
+ *   (b) Secret-scan the staged diff via `redact()`: if redaction shrinks or
+ *       alters the diff, refuse and list the files (exit 2) unless
+ *       `--force-secret` is passed.
+ *   (c) Build a conventional message: type heuristic + top-dir scope +
+ *       `--message` summary (or `update <n> files`).
+ *   (d) `git commit -m` via execFileSync (no shell). Verification hooks always
+ *       run — by construction this file contains no flag that skips them.
+ *   (e) `--dry-run` prints the message + files and exits 0 without committing.
+ */
+export interface CommitOptions {
+    cwd: string;
+    yes?: boolean;
+    dryRun?: boolean;
+    message?: string;
+    forceSecret?: boolean;
+}
+/** Porcelain XY: staged iff the index (first) column is set. Handles renames. */
+export declare function stagedFilesFromPorcelain(porcelain: string): string[];
+/** Type heuristic: test-only→test, docs-only→docs, lockfiles→chore, else feat. */
+export declare function commitTypeFor(files: string[]): string;
+/** Scope = most common top-level dir among staged files with a dir; '' if none. */
+export declare function commitScopeFor(files: string[]): string;
+export declare function buildCommitMessage(files: string[], summaryOpt?: string): string;
+export declare function runCommit(opts: CommitOptions): Promise<number>;