@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/cli/commands/init/convergence-apply.js

@@ -0,0 +1,325 @@
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { convergeUnitFromTarget, deriveCommitAllowlist } from "./convergence.js";
+export { resolveUntrackedCollision } from "./untracked-collision.js";
+/** Bounded timeout for non-hook Git probes (status, add, rev-parse, diff-tree). */
+export const GIT_PROBE_TIMEOUT_MS = 15_000;
+/**
+ * Default wall for the single hookful `git commit`. Consumer pre-commit chains
+ * (format + audits) routinely exceed the probe budget; Node's spawnSync kills
+ * the child with SIGTERM when `timeout` elapses, which left staged residue and
+ * multi-line partial hook output that looked like success.
+ *
+ * 10 minutes is a durable consumer budget, not infinite hang. Operators can
+ * raise/lower via `WP_SETUP_COMMIT_TIMEOUT_MS` or `AuthorCommitOptions.commitTimeoutMs`.
+ */
+export const DEFAULT_GIT_COMMIT_TIMEOUT_MS = 600_000;
+const GIT_MAX_BUFFER = 1024 * 1024;
+function git(repoRoot, args, timeoutMs) {
+    const result = spawnSync("git", [...args], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        // Node: timeout > 0 arms SIGTERM; 0 / omitted means no artificial wall.
+        ...(timeoutMs > 0 ? { timeout: timeoutMs } : {}),
+        maxBuffer: GIT_MAX_BUFFER,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const timedOut = result.error !== undefined && "code" in result.error && result.error.code === "ETIMEDOUT";
+    return {
+        ok: result.status === 0 && !result.error,
+        stdout: (result.stdout ?? "").trim(),
+        stderr: (result.stderr ?? "").trim(),
+        timedOut,
+        signal: result.signal,
+    };
+}
+/**
+ * Resolve the hookful-commit timeout. Preference order:
+ * 1. explicit `commitTimeoutMs` option (tests / programmatic callers)
+ * 2. `WP_SETUP_COMMIT_TIMEOUT_MS` env (operator override)
+ * 3. {@link DEFAULT_GIT_COMMIT_TIMEOUT_MS}
+ *
+ * Values must be finite numbers ≥ 0. `0` disables the artificial wall (Node default).
+ */
+export function resolveCommitTimeoutMs(options) {
+    const env = options?.env ?? process.env;
+    if (typeof options?.commitTimeoutMs === "number" &&
+        Number.isFinite(options.commitTimeoutMs) &&
+        options.commitTimeoutMs >= 0) {
+        return options.commitTimeoutMs;
+    }
+    const raw = env.WP_SETUP_COMMIT_TIMEOUT_MS;
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return DEFAULT_GIT_COMMIT_TIMEOUT_MS;
+}
+function appendHookOutput(diagnosis, hookOutput) {
+    const trimmed = hookOutput?.trim();
+    if (!trimmed)
+        return diagnosis;
+    const snippet = trimmed.length > 400 ? `${trimmed.slice(0, 400)}…` : trimmed;
+    return `${diagnosis}\n--- hook output (truncated) ---\n${snippet}`;
+}
+/** First-class timeout diagnosis; partial hook stdout/stderr is diagnostic only. */
+export function formatCommitTimeoutError(options) {
+    const budget = options.timeoutMs > 0
+        ? `${options.timeoutMs}ms`
+        : "the configured budget (no artificial wall was set, but the process was still interrupted)";
+    const diagnosis = `Convergence commit timed out after ${budget} while repository hooks were still running. ` +
+        `Node spawnSync kills the git process with SIGTERM on timeout, so no setup commit was authored. ` +
+        `Staged and worktree changes were preserved for remediation. ` +
+        `Re-run after hooks complete, raise WP_SETUP_COMMIT_TIMEOUT_MS / commitTimeoutMs, or fix slow hooks. ` +
+        `Partial hook lines such as "format applied" / "audit … passed" are not success.`;
+    return appendHookOutput(diagnosis, options.hookOutput);
+}
+/**
+ * First-class interrupt diagnosis for non-timeout signal kills (operator kill,
+ * external SIGTERM/SIGKILL). Must not surface raw hook "passed" lines as the
+ * leading operator message.
+ */
+export function formatCommitInterruptError(options) {
+    const diagnosis = `Convergence commit was interrupted by ${options.signal} before completion, so no setup commit was authored. ` +
+        `Staged and worktree changes were preserved for remediation. ` +
+        `This is not a successful setup run. ` +
+        `Partial hook lines such as "format applied" / "audit … passed" are not success.`;
+    return appendHookOutput(diagnosis, options.hookOutput);
+}
+/**
+ * Classify a failed hookful `git commit` result.
+ *
+ * - `timedOut` (spawnSync ETIMEDOUT) → budget timeout diagnosis
+ * - non-null `signal` without timedOut → interrupt diagnosis (names the signal)
+ * - otherwise → hook/git stderr when present, else a generic preserved-index message
+ *
+ * Never lead with bare hook "passed" lines for timeout/interrupt paths.
+ */
+export function classifyCommitFailure(result, timeoutMs) {
+    const hookOutput = [result.stderr, result.stdout].filter(Boolean).join("\n");
+    if (result.timedOut) {
+        return formatCommitTimeoutError({ timeoutMs, hookOutput });
+    }
+    if (result.signal) {
+        return formatCommitInterruptError({ signal: result.signal, hookOutput });
+    }
+    return hookOutput || "git commit failed; hook changes were preserved.";
+}
+/**
+ * Prefix every line of a setup failure so multi-line timeout diagnoses stay
+ * labeled when printed via console.error (avoids a single `wp setup: ` on the
+ * first line and bare hook "passed" lines after it).
+ */
+export function formatWpSetupError(message) {
+    const body = message.trimEnd();
+    if (body.length === 0)
+        return "wp setup: Unable to author convergence commit.";
+    return body
+        .split("\n")
+        .map((line) => `wp setup: ${line}`)
+        .join("\n");
+}
+function lines(value) {
+    return value.length === 0 ? [] : value.split("\n").filter(Boolean).sort();
+}
+function readPorcelainStatus(repoRoot, gitPath) {
+    const result = spawnSync("git", [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+        "--ignored=matching",
+        "--",
+        gitPath,
+    ], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        timeout: GIT_PROBE_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_BUFFER,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.status !== 0 || result.error)
+        return null;
+    const fields = result.stdout.split("\0");
+    const entries = [];
+    for (let index = 0; index < fields.length; index += 1) {
+        const record = fields[index];
+        if (!record || record.length < 4)
+            continue;
+        const code = record.slice(0, 2);
+        entries.push({ code, gitPath: record.slice(3) });
+        if (code.includes("R") || code.includes("C"))
+            index += 1;
+    }
+    return entries;
+}
+function isIgnored(repoRoot, gitPath) {
+    return git(repoRoot, ["check-ignore", "--no-index", "-q", "--", gitPath], GIT_PROBE_TIMEOUT_MS)
+        .ok;
+}
+export function collectAppliedConvergeUnits(repoRoot, candidates) {
+    const units = [];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        let candidateUnit;
+        try {
+            candidateUnit = convergeUnitFromTarget(repoRoot, candidate.targetPath, {
+                action: "modify",
+                scope: "repo-committed",
+                reason: candidate.reason,
+            });
+        }
+        catch {
+            continue;
+        }
+        const statuses = readPorcelainStatus(repoRoot, candidateUnit.gitPath);
+        if (!statuses)
+            continue;
+        for (const { code, gitPath } of statuses) {
+            if (seen.has(gitPath))
+                continue;
+            let unit;
+            try {
+                unit = convergeUnitFromTarget(repoRoot, join(repoRoot, gitPath), {
+                    action: code === "??" || code === "!!" || code.includes("A")
+                        ? "create"
+                        : code.includes("D")
+                            ? "delete"
+                            : "modify",
+                    scope: "repo-committed",
+                    reason: candidate.reason,
+                });
+            }
+            catch {
+                continue;
+            }
+            units.push({
+                ...unit,
+                scope: code === "!!" || (code === "??" && isIgnored(repoRoot, gitPath))
+                    ? "repo-ignored"
+                    : "repo-committed",
+            });
+            seen.add(gitPath);
+        }
+    }
+    return units;
+}
+export function authorConvergenceCommit(options) {
+    const allowlist = deriveCommitAllowlist(options.appliedUnits);
+    if (options.isCi)
+        return { status: "skipped-ci", ok: true, allowlist };
+    if (allowlist.length === 0)
+        return { status: "no-change", ok: true, allowlist };
+    const probe = (args) => git(options.repoRoot, args, GIT_PROBE_TIMEOUT_MS);
+    const before = probe(["rev-parse", "--verify", "HEAD"]);
+    if (!before.ok) {
+        return { status: "failed", ok: false, allowlist, error: before.stderr || "Missing HEAD." };
+    }
+    const add = probe(["add", "--", ...allowlist]);
+    if (!add.ok) {
+        return { status: "failed", ok: false, allowlist, error: add.stderr || "git add failed." };
+    }
+    const staged = probe(["diff", "--cached", "--name-only"]);
+    if (!staged.ok) {
+        return { status: "failed", ok: false, allowlist, error: staged.stderr || "git diff failed." };
+    }
+    if (lines(staged.stdout).length === 0) {
+        return { status: "no-change", ok: true, allowlist };
+    }
+    const commitTimeoutMs = resolveCommitTimeoutMs({
+        commitTimeoutMs: options.commitTimeoutMs,
+    });
+    const commit = git(options.repoRoot, ["commit", "-m", options.message], commitTimeoutMs);
+    if (!commit.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            error: classifyCommitFailure(commit, commitTimeoutMs),
+        };
+    }
+    const committedHead = probe(["rev-parse", "--verify", "HEAD"]);
+    if (!committedHead.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            error: committedHead.stderr || "Unable to validate the authored commit.",
+        };
+    }
+    const committedParent = probe(["rev-parse", "--verify", `${committedHead.stdout}^`]);
+    if (!committedParent.ok || committedParent.stdout !== before.stdout) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            error: "The observed commit does not directly follow the recorded HEAD; no rollback was attempted. Inspect Git history and recover manually.",
+        };
+    }
+    const committedPathsResult = probe([
+        "diff-tree",
+        "--root",
+        "--no-commit-id",
+        "--name-only",
+        "-r",
+        committedHead.stdout,
+    ]);
+    if (!committedPathsResult.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            error: committedPathsResult.stderr || "Unable to inspect the authored commit.",
+        };
+    }
+    const committedPaths = lines(committedPathsResult.stdout);
+    const allowed = new Set(allowlist);
+    const committed = new Set(committedPaths);
+    const unexpectedPaths = committedPaths.filter((path) => !allowed.has(path));
+    const missingPaths = allowlist.filter((path) => !committed.has(path));
+    if (unexpectedPaths.length === 0 && missingPaths.length === 0) {
+        return {
+            status: "committed",
+            ok: true,
+            allowlist,
+            commit: committedHead.stdout,
+        };
+    }
+    const currentHead = probe(["rev-parse", "--verify", "HEAD"]);
+    if (!currentHead.ok || currentHead.stdout !== committedHead.stdout) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            unexpectedPaths,
+            missingPaths,
+            error: "The setup-authored commit changed before validation; no rollback was attempted. Inspect Git history and recover manually.",
+        };
+    }
+    const rollback = probe(["reset", "--mixed", before.stdout]);
+    if (!rollback.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            unexpectedPaths,
+            missingPaths,
+            error: rollback.stderr || "Failed to undo the path-invalid setup commit.",
+        };
+    }
+    return {
+        status: "rolled-back",
+        ok: false,
+        allowlist,
+        commit: committedHead.stdout,
+        unexpectedPaths,
+        missingPaths,
+        error: `A commit hook changed setup commit scope (unexpected: ${unexpectedPaths.join(", ") || "none"}; missing: ${missingPaths.join(", ") || "none"}). ` +
+            "The setup commit was undone and all worktree changes were retained. Update the hook so it does not stage unrelated paths, then stage or discard those paths and rerun wp setup.",
+    };
+}

package/dist/esm/cli/commands/init/convergence-state.d.ts

@@ -0,0 +1,13 @@
+export declare const CONVERGENCE_STATE_SCHEMA_VERSION: 1;
+export declare const CONVERGENCE_STATE_PATH = ".webpresso/converged.json";
+export interface ConvergenceState {
+    readonly schemaVersion: typeof CONVERGENCE_STATE_SCHEMA_VERSION;
+    readonly agentKitVersion: string;
+    readonly host: string;
+    readonly sentinels: Readonly<Record<string, string>>;
+    readonly writtenAt: string;
+}
+export declare function parseConvergenceState(value: unknown): ConvergenceState | null;
+export declare function readConvergenceState(repoRoot: string): ConvergenceState | null;
+export declare function isConvergenceStateCurrent(state: ConvergenceState | null, expected: Pick<ConvergenceState, "agentKitVersion" | "host" | "sentinels">): boolean;
+export declare function writeConvergenceState(repoRoot: string, state: ConvergenceState): void;

package/dist/esm/cli/commands/init/convergence-state.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { writeJsonFile } from "#shared-utils/write-json-file.js";
+export const CONVERGENCE_STATE_SCHEMA_VERSION = 1;
+export const CONVERGENCE_STATE_PATH = ".webpresso/converged.json";
+function isStringRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+export function parseConvergenceState(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.schemaVersion !== CONVERGENCE_STATE_SCHEMA_VERSION ||
+        typeof record.agentKitVersion !== "string" ||
+        typeof record.host !== "string" ||
+        typeof record.writtenAt !== "string" ||
+        !isStringRecord(record.sentinels)) {
+        return null;
+    }
+    return {
+        schemaVersion: CONVERGENCE_STATE_SCHEMA_VERSION,
+        agentKitVersion: record.agentKitVersion,
+        host: record.host,
+        sentinels: record.sentinels,
+        writtenAt: record.writtenAt,
+    };
+}
+export function readConvergenceState(repoRoot) {
+    try {
+        return parseConvergenceState(JSON.parse(readFileSync(join(resolve(repoRoot), CONVERGENCE_STATE_PATH), "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+export function isConvergenceStateCurrent(state, expected) {
+    if (!state ||
+        state.agentKitVersion !== expected.agentKitVersion ||
+        state.host !== expected.host) {
+        return false;
+    }
+    return Object.entries(expected.sentinels).every(([name, value]) => state.sentinels[name] === value);
+}
+export function writeConvergenceState(repoRoot, state) {
+    const statePath = join(resolve(repoRoot), CONVERGENCE_STATE_PATH);
+    mkdirSync(dirname(statePath), { recursive: true });
+    writeJsonFile(statePath, state, {
+        atomic: true,
+        indent: 2,
+    });
+}

package/dist/esm/cli/commands/init/convergence.d.ts

@@ -0,0 +1,23 @@
+import type { WriteAction } from "./write-plan.js";
+export declare const CONVERGE_SCOPES: readonly ["repo-committed", "repo-ignored"];
+export type ConvergeScope = (typeof CONVERGE_SCOPES)[number];
+export interface ConvergeUnit {
+    readonly repoRoot: string;
+    readonly targetPath: string;
+    readonly gitPath: string;
+    readonly action: WriteAction;
+    readonly scope: ConvergeScope;
+    readonly reason: string;
+}
+export interface CreateConvergeUnitInput {
+    readonly repoRoot: string;
+    readonly targetPath: string;
+    readonly gitPath: string;
+    readonly action: WriteAction;
+    readonly scope: ConvergeScope;
+    readonly reason: string;
+}
+export declare function createConvergeUnit(input: CreateConvergeUnitInput): ConvergeUnit;
+export declare function convergeUnitFromTarget(repoRoot: string, targetPath: string, input: Pick<CreateConvergeUnitInput, "action" | "scope" | "reason">): ConvergeUnit;
+/** Applied units are the sole authority for authored commit scope. */
+export declare function deriveCommitAllowlist(appliedUnits: readonly ConvergeUnit[]): string[];

package/dist/esm/cli/commands/init/convergence.js

@@ -0,0 +1,57 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+export const CONVERGE_SCOPES = ["repo-committed", "repo-ignored"];
+function normalizeGitPath(value) {
+    return value.replaceAll("\\", "/").replace(/^\.\//u, "");
+}
+function assertInsideRepo(repoRoot, targetPath) {
+    const relativePath = relative(repoRoot, targetPath);
+    if (relativePath.length === 0 ||
+        relativePath === ".." ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)) {
+        throw new Error(`Convergence target must be a file inside the repository: ${targetPath}`);
+    }
+    return normalizeGitPath(relativePath);
+}
+export function createConvergeUnit(input) {
+    if (!isAbsolute(input.repoRoot)) {
+        throw new Error(`Convergence repo root must be absolute: ${input.repoRoot}`);
+    }
+    if (!isAbsolute(input.targetPath)) {
+        throw new Error(`Convergence target must be absolute: ${input.targetPath}`);
+    }
+    if (!CONVERGE_SCOPES.includes(input.scope)) {
+        throw new Error(`Unsupported convergence scope: ${input.scope}`);
+    }
+    const repoRoot = resolve(input.repoRoot);
+    const targetPath = resolve(input.targetPath);
+    const derivedGitPath = assertInsideRepo(repoRoot, targetPath);
+    const gitPath = normalizeGitPath(input.gitPath);
+    if (gitPath.length === 0 || isAbsolute(gitPath) || gitPath !== derivedGitPath) {
+        throw new Error(`Convergence git path must match its repo-anchored target: expected ${derivedGitPath}, received ${input.gitPath}`);
+    }
+    return {
+        repoRoot,
+        targetPath,
+        gitPath,
+        action: input.action,
+        scope: input.scope,
+        reason: input.reason,
+    };
+}
+export function convergeUnitFromTarget(repoRoot, targetPath, input) {
+    const anchoredRoot = resolve(repoRoot);
+    const anchoredTarget = resolve(targetPath);
+    return createConvergeUnit({
+        ...input,
+        repoRoot: anchoredRoot,
+        targetPath: anchoredTarget,
+        gitPath: assertInsideRepo(anchoredRoot, anchoredTarget),
+    });
+}
+/** Applied units are the sole authority for authored commit scope. */
+export function deriveCommitAllowlist(appliedUnits) {
+    return [
+        ...new Set(appliedUnits.filter((unit) => unit.scope === "repo-committed").map((unit) => unit.gitPath)),
+    ].sort();
+}

package/dist/esm/cli/commands/init/git-convergence.d.ts

@@ -0,0 +1,19 @@
+export type GitConvergenceStatus = "ready" | "fast-forwarded" | "not-git" | "unborn" | "detached" | "dirty" | "diverged" | "failed";
+export interface GitConvergenceResult {
+    readonly status: GitConvergenceStatus;
+    readonly ok: boolean;
+    readonly repoRoot: string;
+    readonly head?: string;
+    readonly upstream?: string;
+    readonly shouldReplan: boolean;
+    readonly canCommit: boolean;
+    readonly warnings: readonly string[];
+    readonly error?: string;
+}
+export interface PrepareGitConvergenceOptions {
+    readonly repoRoot: string;
+    readonly isCi?: boolean;
+    readonly fetchTimeoutMs?: number;
+    readonly gitCommand?: string;
+}
+export declare function prepareRepositoryForConvergence(options: PrepareGitConvergenceOptions): GitConvergenceResult;

package/dist/esm/cli/commands/init/git-convergence.js

@@ -0,0 +1,168 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+const DEFAULT_GIT_TIMEOUT_MS = 5_000;
+const GIT_MAX_BUFFER = 1024 * 1024;
+function git(repoRoot, args, timeoutMs, command = "git") {
+    const result = spawnSync(command, [...args], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        timeout: timeoutMs,
+        maxBuffer: GIT_MAX_BUFFER,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        ok: result.status === 0 && !result.error,
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+        timedOut: result.error !== undefined && "code" in result.error && result.error.code === "ETIMEDOUT",
+    };
+}
+function failed(repoRoot, status, error) {
+    return {
+        status,
+        ok: false,
+        repoRoot,
+        shouldReplan: false,
+        canCommit: false,
+        warnings: [],
+        error,
+    };
+}
+function parseAheadBehindCounts(stdout) {
+    const parts = stdout.trim().split(/\s+/u);
+    if (parts.length !== 2)
+        return null;
+    if (!parts.every((part) => /^\d+$/u.test(part)))
+        return null;
+    const [ahead, behind] = parts.map((part) => Number.parseInt(part, 10));
+    if (ahead === undefined ||
+        behind === undefined ||
+        !Number.isSafeInteger(ahead) ||
+        !Number.isSafeInteger(behind) ||
+        ahead < 0 ||
+        behind < 0) {
+        return null;
+    }
+    return { ahead, behind };
+}
+export function prepareRepositoryForConvergence(options) {
+    const repoRoot = resolve(options.repoRoot);
+    const timeoutMs = options.fetchTimeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
+    const gitCommand = options.gitCommand ?? "git";
+    const runGit = (args) => git(repoRoot, args, timeoutMs, gitCommand);
+    const inside = runGit(["rev-parse", "--is-inside-work-tree"]);
+    if (!inside.ok || inside.stdout !== "true") {
+        return failed(repoRoot, "not-git", "Repository convergence requires a Git worktree.");
+    }
+    const headResult = runGit(["rev-parse", "--verify", "HEAD"]);
+    if (!headResult.ok) {
+        return failed(repoRoot, "unborn", "Repository convergence requires an existing HEAD commit.");
+    }
+    const head = headResult.stdout;
+    const branch = runGit(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    const detached = !branch.ok;
+    if (detached && !options.isCi) {
+        return failed(repoRoot, "detached", "Repository convergence refuses a detached HEAD.");
+    }
+    const trackedStatus = runGit(["status", "--porcelain=v1", "--untracked-files=no"]);
+    if (!trackedStatus.ok) {
+        return failed(repoRoot, "failed", trackedStatus.stderr || "Unable to inspect Git status.");
+    }
+    if (trackedStatus.stdout.length > 0) {
+        return failed(repoRoot, "dirty", "Repository convergence requires a clean tracked index and worktree.");
+    }
+    const warnings = [];
+    if (detached) {
+        warnings.push("Detached HEAD accepted in CI; skipped upstream update and authored commit.");
+        return {
+            status: "ready",
+            ok: true,
+            repoRoot,
+            head,
+            shouldReplan: false,
+            canCommit: false,
+            warnings,
+        };
+    }
+    const upstreamResult = runGit(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    if (!upstreamResult.ok) {
+        warnings.push("No upstream is configured; skipped fetch and fast-forward.");
+        return {
+            status: "ready",
+            ok: true,
+            repoRoot,
+            head,
+            shouldReplan: false,
+            canCommit: !options.isCi,
+            warnings,
+        };
+    }
+    const upstream = upstreamResult.stdout;
+    const remoteSeparator = upstream.indexOf("/");
+    const remote = remoteSeparator === -1 ? upstream : upstream.slice(0, remoteSeparator);
+    const fetch = runGit(["fetch", "--quiet", "--no-tags", remote]);
+    if (!fetch.ok) {
+        warnings.push(fetch.timedOut
+            ? `Upstream fetch timed out after ${timeoutMs}ms; continuing from local refs.`
+            : `Upstream fetch unavailable; continuing from local refs${fetch.stderr ? `: ${fetch.stderr}` : "."}`);
+    }
+    const counts = runGit(["rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+    if (!counts.ok) {
+        return {
+            ...failed(repoRoot, "failed", counts.stderr || "Unable to compare HEAD with upstream."),
+            head,
+            upstream,
+            warnings,
+        };
+    }
+    const parsedCounts = parseAheadBehindCounts(counts.stdout);
+    if (!parsedCounts) {
+        return {
+            ...failed(repoRoot, "failed", `Unable to parse HEAD/upstream divergence counts from git rev-list output: ${JSON.stringify(counts.stdout)}.`),
+            head,
+            upstream,
+            warnings,
+        };
+    }
+    const { ahead, behind } = parsedCounts;
+    if (ahead > 0 && behind > 0) {
+        return {
+            ...failed(repoRoot, "diverged", `HEAD has diverged from ${upstream}; reconcile it manually.`),
+            head,
+            upstream,
+            warnings,
+        };
+    }
+    if (behind > 0) {
+        const merge = runGit(["merge", "--ff-only", upstream]);
+        if (!merge.ok) {
+            return {
+                ...failed(repoRoot, "failed", merge.stderr || `Unable to fast-forward from ${upstream}.`),
+                head,
+                upstream,
+                warnings,
+            };
+        }
+        const nextHead = runGit(["rev-parse", "--verify", "HEAD"]);
+        return {
+            status: "fast-forwarded",
+            ok: true,
+            repoRoot,
+            head: nextHead.ok ? nextHead.stdout : undefined,
+            upstream,
+            shouldReplan: true,
+            canCommit: !options.isCi,
+            warnings,
+        };
+    }
+    return {
+        status: "ready",
+        ok: true,
+        repoRoot,
+        head,
+        upstream,
+        shouldReplan: false,
+        canCommit: !options.isCi,
+        warnings,
+    };
+}

package/dist/esm/cli/commands/init/gitignore-patcher.js

@@ -55,8 +55,10 @@ export const GENERATED_PATHS_BLOCK = {
         ".runtime/",
         ".opencode/",
         ".codex/",
+        ".grok/",
         "_worktrees/",
         ".webpresso/hooks-manifest.json",
+        ".webpresso/converged.json",
         ".claude/settings.json",
         ".claude/settings.local.json",
         ".claude/agents/",