@mindlace/chreode 0.0.0-stage → 0.1.0

package/dist/run/step.js

@@ -0,0 +1,182 @@
+import { spawn } from 'node:child_process';
+import { decidePolicedOutcome } from './stderr.js';
+/** After exit, how long to wait for a captured stderr pipe to drain. A grandchild that
+ *  inherited the pipe can hold it open; this bounds the wait. */
+const STDERR_DRAIN_MS = 2_000;
+/** After forwarding SIGINT/SIGTERM, how long a step gets to exit before its group is SIGKILLed. */
+export const INTERRUPT_GRACE_MS = 3_000;
+/**
+ * Run a shell command with a hard wall-clock timeout. The command runs in its OWN process
+ * group (detached) so a timeout can SIGKILL the whole tree, not just the wrapping shell.
+ * Being in its own group, it no longer receives the terminal's Ctrl-C, so SIGINT/SIGTERM
+ * delivered to us are forwarded to the group. Never rejects.
+ */
+export function runWithTimeout(cmd, timeoutMs, opts = {}) {
+    const capture = opts.captureStderr ?? false;
+    const signals = opts.signals ?? process;
+    return new Promise((resolve) => {
+        const child = spawn(cmd, {
+            shell: true,
+            stdio: capture ? ['inherit', 'inherit', 'pipe'] : 'inherit',
+            detached: true,
+            env: opts.env ?? process.env,
+            cwd: opts.cwd
+        });
+        let stderrBuf = '';
+        let stderrEnded = !capture || child.stderr === null;
+        let exitCode;
+        let timedOut = false;
+        let interrupted = false;
+        let settled = false;
+        const killGroup = (signal) => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, signal);
+            }
+            catch {
+                // Group already gone.
+            }
+        };
+        let graceTimer;
+        const onSignal = () => {
+            if (interrupted) {
+                // A second Ctrl-C means "now".
+                killGroup('SIGKILL');
+                return;
+            }
+            interrupted = true;
+            killGroup('SIGTERM');
+            graceTimer = setTimeout(() => killGroup('SIGKILL'), INTERRUPT_GRACE_MS);
+            graceTimer.unref();
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup('SIGKILL');
+        }, timeoutMs);
+        signals.on('SIGINT', onSignal);
+        signals.on('SIGTERM', onSignal);
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(graceTimer);
+            // Reap survivors of the leader's exit (e.g. TERM-ignoring grandchildren).
+            if (interrupted)
+                killGroup('SIGKILL');
+            signals.off('SIGINT', onSignal);
+            signals.off('SIGTERM', onSignal);
+            resolve({ code, timedOut, interrupted, stderr: capture ? stderrBuf : undefined });
+        };
+        if (capture && child.stderr) {
+            // setEncoding decodes through a StringDecoder, so a multi-byte character split across
+            // chunks is not corrupted.
+            child.stderr.setEncoding('utf8');
+            child.stderr.on('data', (chunk) => {
+                stderrBuf += chunk;
+            });
+            child.stderr.on('end', () => {
+                stderrEnded = true;
+                if (exitCode !== undefined)
+                    finish(exitCode);
+            });
+        }
+        child.on('exit', (code) => {
+            exitCode = code;
+            if (stderrEnded)
+                finish(code);
+            else
+                setTimeout(() => finish(code), STDERR_DRAIN_MS).unref();
+        });
+        child.on('error', () => finish(1));
+    });
+}
+export class StepFailure extends Error {
+    label;
+    constructor(label, message) {
+        super(message);
+        this.label = label;
+        this.name = 'StepFailure';
+    }
+}
+function formatDuration(ms) {
+    return ms < 60_000 ? `${Math.round(ms / 1000)}s` : `${Math.round(ms / 60_000)}m`;
+}
+export function timeoutMessage(label, timeoutMs) {
+    return (`\n[chreode] TIMED OUT at: ${label} after ${formatDuration(timeoutMs)}. Suspect a ` +
+        `contending process or a genuinely slow machine. Killed the step's process tree.`);
+}
+/** Run one planned step. Every failure throws StepFailure so the caller's `finally`
+ *  releases the lock before the run exits. */
+export async function runStep(step, opts) {
+    const log = opts.log ?? ((m) => console.log(m));
+    const error = opts.error ?? ((m) => console.error(m));
+    const writeStderr = opts.writeStderr ?? ((s) => void process.stderr.write(s));
+    const runImpl = opts.runImpl ?? runWithTimeout;
+    log(`\n[chreode] ${step.label}: ${step.command}`);
+    const r = await runImpl(step.command, step.timeoutMs, {
+        captureStderr: step.policeStderr,
+        env: { ...(opts.env ?? process.env), CHREODE_SIGNOFF: '1' }
+    });
+    if (r.timedOut) {
+        if (r.stderr)
+            writeStderr(r.stderr);
+        error(timeoutMessage(step.label, step.timeoutMs));
+        throw new StepFailure(step.label, `${step.label} timed out`);
+    }
+    if (r.interrupted) {
+        if (r.stderr)
+            writeStderr(r.stderr);
+        error(`\n[chreode] INTERRUPTED at: ${step.label}`);
+        throw new StepFailure(step.label, `${step.label} interrupted`);
+    }
+    if (!step.policeStderr) {
+        if (r.code !== 0) {
+            error(`\n[chreode] FAILED at: ${step.label} (exit ${r.code})`);
+            throw new StepFailure(step.label, `${step.label} failed`);
+        }
+        return 'passed';
+    }
+    const outcome = decidePolicedOutcome({ code: r.code, stderr: r.stderr }, opts.allowlist);
+    if (outcome.kind === 'fail-exit') {
+        if (outcome.rawStderr)
+            writeStderr(outcome.rawStderr);
+        error(`\n[chreode] FAILED at: ${step.label} (exit ${r.code})`);
+        throw new StepFailure(step.label, `${step.label} failed`);
+    }
+    if (outcome.kind === 'fail-stderr') {
+        if (opts.allowStderr) {
+            error(`\n[chreode] ${step.label} wrote unexpected stderr, allowed by --allow-stderr:`);
+            for (const line of outcome.offendingLines)
+                writeStderr(`${line}\n`);
+            return 'allowed-stderr';
+        }
+        error(`\n[chreode] FAILED at: ${step.label}: it exited 0 but wrote unexpected stderr.\n` +
+            `[chreode] A passing step that logs errors is still a failure: fix it at the source.\n` +
+            `[chreode] Allowlisting genuinely benign noise is a reviewed change to stderrAllowlist\n` +
+            `[chreode] in chreode.config.ts, with a reason. --allow-stderr bypasses for one run.\n` +
+            `[chreode] Offending lines:`);
+        for (const line of outcome.offendingLines)
+            writeStderr(`${line}\n`);
+        throw new StepFailure(step.label, `${step.label} wrote unexpected stderr`);
+    }
+    return 'passed';
+}
+/** Run the plan holding the machine lock; an empty plan touches no lock. The lock is
+ *  released on every exit path. Returns the labels whose stderr --allow-stderr waived. */
+export async function runSteps(steps, lock, run) {
+    if (steps.length === 0)
+        return [];
+    const release = await lock.acquire();
+    const allowed = [];
+    try {
+        for (const step of steps) {
+            if ((await run(step)) === 'allowed-stderr')
+                allowed.push(step.label);
+        }
+        return allowed;
+    }
+    finally {
+        await release();
+    }
+}

package/dist/signoff/plan.d.ts

@@ -0,0 +1,49 @@
+import type { ResolvedConfig, ResolvedStep, RuleConfig } from '../config/types.js';
+export declare class PlanError extends Error {
+    constructor(message: string);
+}
+export interface PlanInput {
+    paths: readonly string[];
+    full: boolean;
+    skip: readonly string[];
+    base: string;
+    head: string;
+    isWorktree: boolean;
+}
+export interface PlannedStep {
+    label: string;
+    command: string;
+    policeStderr: boolean;
+    timeoutMs: number;
+}
+export type SkipReason = {
+    kind: 'not-triggered';
+} | {
+    kind: 'if-false';
+} | {
+    kind: 'skip-flag';
+} | {
+    kind: 'superseded';
+    by: string;
+};
+export interface Plan {
+    triggers: string[];
+    /** Changed paths no rule matched; each one fired every trigger. */
+    unmatched: string[];
+    steps: PlannedStep[];
+    skipped: {
+        label: string;
+        reason: SkipReason;
+    }[];
+    /** Steps that would have run but for --skip: these go in the status description. */
+    skippedByFlag: string[];
+}
+export declare function matchRule(path: string, rules: readonly RuleConfig[]): RuleConfig | null;
+export declare function allTriggers(steps: readonly ResolvedStep[]): string[];
+/** Rules can only make a run smaller by matching: an unmatched path fires everything. */
+export declare function fireTriggers(paths: readonly string[], rules: readonly RuleConfig[], steps: readonly ResolvedStep[]): {
+    triggers: string[];
+    unmatched: string[];
+};
+export declare function planSignoff(config: ResolvedConfig, input: PlanInput): Plan;
+export declare function describeSkip(reason: SkipReason): string;

package/dist/signoff/plan.js

@@ -0,0 +1,110 @@
+import picomatch from 'picomatch';
+export class PlanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PlanError';
+    }
+}
+function tester(m) {
+    if (typeof m === 'string')
+        return picomatch(m, { dot: true });
+    return (path) => {
+        // A /g or /y RegExp carries lastIndex between calls; reset so every path is tested fresh.
+        m.lastIndex = 0;
+        return m.test(path);
+    };
+}
+export function matchRule(path, rules) {
+    for (const rule of rules) {
+        const matchers = Array.isArray(rule.match) ? rule.match : [rule.match];
+        if (matchers.some((m) => tester(m)(path)))
+            return rule;
+    }
+    return null;
+}
+export function allTriggers(steps) {
+    return [...new Set(steps.flatMap((s) => s.when))].sort();
+}
+/** Rules can only make a run smaller by matching: an unmatched path fires everything. */
+export function fireTriggers(paths, rules, steps) {
+    const fired = new Set();
+    const unmatched = [];
+    for (const path of paths) {
+        const rule = matchRule(path, rules);
+        const triggers = rule === null ? allTriggers(steps) : rule.triggers;
+        if (rule === null)
+            unmatched.push(path);
+        for (const t of triggers)
+            fired.add(t);
+    }
+    return { triggers: [...fired].sort(), unmatched };
+}
+export function planSignoff(config, input) {
+    const known = config.steps.map((s) => s.label);
+    const unknownSkips = input.skip.filter((l) => !known.includes(l));
+    if (unknownSkips.length > 0) {
+        throw new PlanError(`--skip names unknown step(s): ${unknownSkips.join(', ')} (known: ${known.join(', ')})`);
+    }
+    const { triggers, unmatched } = input.full
+        ? { triggers: allTriggers(config.steps), unmatched: [] }
+        : fireTriggers(input.paths, config.rules, config.steps);
+    const ctx = {
+        base: input.base,
+        head: input.head,
+        paths: input.paths,
+        triggers,
+        isWorktree: input.isWorktree
+    };
+    const fired = new Set(triggers);
+    const skipSet = new Set(input.skip);
+    const skipped = [];
+    const skippedByFlag = [];
+    const survivors = [];
+    for (const step of config.steps) {
+        if (!step.when.some((t) => fired.has(t))) {
+            skipped.push({ label: step.label, reason: { kind: 'not-triggered' } });
+        }
+        else if (step.if && !step.if(ctx)) {
+            skipped.push({ label: step.label, reason: { kind: 'if-false' } });
+        }
+        else if (skipSet.has(step.label)) {
+            skipped.push({ label: step.label, reason: { kind: 'skip-flag' } });
+            skippedByFlag.push(step.label);
+        }
+        else {
+            survivors.push(step);
+        }
+    }
+    const surviving = new Set(survivors.map((s) => s.label));
+    const steps = [];
+    for (const step of survivors) {
+        const by = step.supersededBy.find((l) => surviving.has(l));
+        if (by !== undefined) {
+            skipped.push({ label: step.label, reason: { kind: 'superseded', by } });
+            continue;
+        }
+        const command = typeof step.run === 'function' ? step.run(ctx) : step.run;
+        if (typeof command !== 'string' || command.trim() === '') {
+            throw new PlanError(`step "${step.label}": run() must return a non-empty command`);
+        }
+        steps.push({
+            label: step.label,
+            command,
+            policeStderr: step.policeStderr,
+            timeoutMs: step.timeoutMs
+        });
+    }
+    return { triggers, unmatched, steps, skipped, skippedByFlag };
+}
+export function describeSkip(reason) {
+    switch (reason.kind) {
+        case 'not-triggered':
+            return 'no relevant changes';
+        case 'if-false':
+            return '`if` returned false';
+        case 'skip-flag':
+            return '--skip';
+        case 'superseded':
+            return `superseded by ${reason.by}`;
+    }
+}

package/dist/signoff/preconditions.d.ts

@@ -0,0 +1,10 @@
+import { type Exec } from '../run/exec.js';
+export declare class PreconditionError extends Error {
+    constructor(message: string);
+}
+export interface Preconditions {
+    branch: string;
+    /** git user.email: named in the status description. */
+    signer: string;
+}
+export declare function checkPreconditions(baseBranch: string, exec?: Exec): Preconditions;

package/dist/signoff/preconditions.js

@@ -0,0 +1,49 @@
+import { defaultExec } from '../run/exec.js';
+export class PreconditionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PreconditionError';
+    }
+}
+export function checkPreconditions(baseBranch, exec = defaultExec) {
+    if (exec('git', ['status', '--porcelain']).trim() !== '') {
+        throw new PreconditionError('working tree is dirty; commit or stash before signing off');
+    }
+    let branch;
+    try {
+        branch = exec('git', ['symbolic-ref', '-q', '--short', 'HEAD']).trim();
+    }
+    catch {
+        throw new PreconditionError('HEAD is detached; check out a branch before signing off');
+    }
+    if (branch === baseBranch) {
+        throw new PreconditionError(`on ${baseBranch} itself; signoff is for branches that merge into ${baseBranch}`);
+    }
+    let behind = '';
+    try {
+        behind = exec('git', ['rev-list', 'HEAD..@{u}']).trim();
+    }
+    catch {
+        // No upstream yet: nothing to be behind.
+    }
+    if (behind !== '') {
+        throw new PreconditionError('HEAD is behind its upstream; pull before signing off');
+    }
+    try {
+        exec('gh', ['auth', 'status']);
+    }
+    catch {
+        throw new PreconditionError('gh is not authenticated; run `gh auth login`');
+    }
+    let signer = '';
+    try {
+        signer = exec('git', ['config', 'user.email']).trim();
+    }
+    catch {
+        // Reported below.
+    }
+    if (signer === '') {
+        throw new PreconditionError('git config user.email is unset; the status description names the signer');
+    }
+    return { branch, signer };
+}

package/dist/signoff/run.d.ts

@@ -0,0 +1,36 @@
+import type { ResolvedConfig } from '../config/types.js';
+import { type MachineLock } from '../lock/machine-lock.js';
+import { type Exec, type Run } from '../run/exec.js';
+import { type StepOutcome } from '../run/step.js';
+import { type Plan, type PlannedStep } from './plan.js';
+import { type TailEffects } from './tail.js';
+export interface SignoffOptions {
+    full: boolean;
+    dryRun: boolean;
+    noMerge: boolean;
+    noPush: boolean;
+    allowStderr: boolean;
+    base: string | null;
+    skip: string[];
+}
+export interface SignoffDeps {
+    exec: Exec;
+    run: Run;
+    lock: MachineLock;
+    runStep: (step: PlannedStep) => Promise<StepOutcome>;
+    tail: TailEffects;
+    log: (m: string) => void;
+    warn: (m: string) => void;
+    error: (m: string) => void;
+}
+export declare function printPlan(plan: Plan, where: {
+    base: string;
+    head: string;
+    paths: readonly string[];
+    full: boolean;
+}, log: (m: string) => void): void;
+/**
+ * `loadConfig` is called once up front and again after a merge that changed the branch, so
+ * a merge that brings in a new chreode.config.ts is planned and run under that config.
+ */
+export declare function runSignoff(loadConfig: () => Promise<ResolvedConfig>, opts: SignoffOptions, overrides?: Partial<SignoffDeps>): Promise<number>;

package/dist/signoff/run.js

@@ -0,0 +1,194 @@
+import { committedPaths, isWorktree, resolveBase, resolveRef } from '../git/change-set.js';
+import { mergeBaseBranch } from '../git/merge.js';
+import { repoInfo } from '../github/status.js';
+import { signoffLock } from '../lock/machine-lock.js';
+import { defaultExec, defaultRun } from '../run/exec.js';
+import { StepFailure, runStep, runSteps } from '../run/step.js';
+import { PlanError, describeSkip, planSignoff } from './plan.js';
+import { PreconditionError, checkPreconditions } from './preconditions.js';
+import { defaultTailEffects, runTail } from './tail.js';
+function defaultDeps(config, opts) {
+    // Children can detect the gate (e.g. to quiet build-tool stderr) via CHREODE_SIGNOFF=1.
+    const env = { ...process.env, CHREODE_SIGNOFF: '1' };
+    let repo = null;
+    const getRepo = () => (repo ??= repoInfo(defaultExec));
+    return {
+        exec: defaultExec,
+        run: (command) => defaultRun(command, env),
+        lock: signoffLock(),
+        runStep: (step) => runStep(step, { allowStderr: opts.allowStderr, allowlist: config.stderrAllowlist, env }),
+        tail: defaultTailEffects(getRepo, config.statusContext),
+        log: (m) => console.log(m),
+        warn: (m) => console.warn(m),
+        error: (m) => console.error(m)
+    };
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Why the checkout no longer matches `head`, or null when it is clean and unmoved. */
+function checkoutChange(head, exec) {
+    if (exec('git', ['status', '--porcelain']).trim() !== '')
+        return 'the working tree is dirty';
+    const now = exec('git', ['rev-parse', 'HEAD']).trim();
+    return now !== head ? `HEAD moved to ${now}` : null;
+}
+export function printPlan(plan, where, log) {
+    log(`[chreode] base=${where.base} head=${where.head}${where.full ? ' (--full)' : ''}`);
+    log(`[chreode] changed paths (${where.paths.length}):`);
+    for (const p of where.paths)
+        log(`  ${p}`);
+    if (plan.unmatched.length > 0) {
+        log(`[chreode] matched no rule, so every trigger fired: ${plan.unmatched.join(', ')}`);
+    }
+    log(`[chreode] triggers: ${plan.triggers.length > 0 ? plan.triggers.join(', ') : '(none)'}`);
+    log(`[chreode] plan: ${plan.steps.length > 0 ? plan.steps.map((s) => s.label).join(', ') : '(no steps: a no-op signoff)'}`);
+    for (const { label, reason } of plan.skipped) {
+        log(`[chreode] skipping ${label} (${describeSkip(reason)})`);
+    }
+}
+/**
+ * `loadConfig` is called once up front and again after a merge that changed the branch, so
+ * a merge that brings in a new chreode.config.ts is planned and run under that config.
+ */
+export async function runSignoff(loadConfig, opts, overrides = {}) {
+    let config = await loadConfig();
+    let d = { ...defaultDeps(config, opts), ...overrides };
+    const baseBranch = config.baseBranch;
+    // 1. Preconditions
+    let pre;
+    try {
+        pre = checkPreconditions(baseBranch, d.exec);
+    }
+    catch (err) {
+        if (err instanceof PreconditionError) {
+            d.error(`[chreode] ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    // 2. Merge
+    const merge = mergeBaseBranch(baseBranch, { noMerge: opts.noMerge }, d.exec, d.warn);
+    if (merge.kind === 'conflict') {
+        d.error(`\n[chreode] merging origin/${baseBranch} hit a conflict. The merge is in progress.\n` +
+            `Resolve it, run \`git commit --no-edit\`, then re-run signoff.\n` +
+            `To bail out: \`git merge --abort\`.`);
+        return 1;
+    }
+    if (merge.kind === 'failed') {
+        d.error(`[chreode] merging origin/${baseBranch} failed: ${merge.message}`);
+        return 1;
+    }
+    if (merge.kind === 'merged') {
+        d.log(`[chreode] merged origin/${baseBranch} into ${pre.branch}`);
+        if (config.afterMerge) {
+            d.log(`[chreode] afterMerge: ${config.afterMerge}`);
+            const before = d.exec('git', ['rev-parse', 'HEAD']).trim();
+            try {
+                d.run(config.afterMerge);
+            }
+            catch {
+                d.error('[chreode] afterMerge failed');
+                return 1;
+            }
+            const moved = checkoutChange(before, d.exec);
+            if (moved) {
+                d.error(`[chreode] afterMerge changed the checkout (${moved}); commit the change and re-run signoff.`);
+                return 1;
+            }
+        }
+        // The merge may have changed the config itself: plan under what is now checked out.
+        try {
+            config = await loadConfig();
+        }
+        catch (err) {
+            d.error(`[chreode] the config merged in from origin/${baseBranch} failed to load: ${message(err)}\n` +
+                `Fix it in a commit on this branch, then re-run signoff.`);
+            return 1;
+        }
+        d = { ...defaultDeps(config, opts), ...overrides };
+    }
+    // 3. Resolve base
+    const head = d.exec('git', ['rev-parse', 'HEAD']).trim();
+    let base;
+    let source;
+    try {
+        if (opts.base !== null) {
+            base = resolveRef(opts.base, d.exec);
+            source = 'flag';
+        }
+        else {
+            ({ base, source } = resolveBase(baseBranch, d.exec));
+        }
+    }
+    catch (err) {
+        d.error(`[chreode] could not resolve the base: ${message(err)}`);
+        return 1;
+    }
+    if (!opts.full && base === head) {
+        d.log(source === 'note'
+            ? `[chreode] already signed off at ${head}; nothing to do (--full re-runs everything)`
+            : `[chreode] nothing to sign off: ${base} is HEAD`);
+        return 0;
+    }
+    // 4. Plan
+    const paths = committedPaths(base, head, d.exec);
+    let plan;
+    try {
+        plan = planSignoff(config, {
+            paths,
+            full: opts.full,
+            skip: opts.skip,
+            base,
+            head,
+            isWorktree: isWorktree(d.exec)
+        });
+    }
+    catch (err) {
+        if (err instanceof PlanError) {
+            d.error(`[chreode] ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    printPlan(plan, { base, head, paths, full: opts.full }, d.log);
+    if (opts.dryRun) {
+        d.log('[chreode] --dry-run: stopping before the run');
+        return 0;
+    }
+    // 5. Run
+    let allowedStderr;
+    try {
+        allowedStderr = await runSteps(plan.steps, d.lock, d.runStep);
+    }
+    catch (err) {
+        if (!(err instanceof StepFailure))
+            d.error(`[chreode] ${message(err)}`);
+        return 1;
+    }
+    // What was tested must be exactly HEAD.
+    const changed = checkoutChange(head, d.exec);
+    if (changed) {
+        d.error(`[chreode] the steps changed the checkout (${changed}); ` +
+            `commit the change and re-run signoff. Nothing was posted.`);
+        return 1;
+    }
+    // 6. Tail
+    try {
+        runTail({
+            sha: head,
+            signer: pre.signer,
+            noPush: opts.noPush,
+            ranLabels: plan.steps.map((s) => s.label),
+            skippedByFlag: plan.skippedByFlag,
+            allowedStderr,
+            baseFlag: opts.base,
+            context: config.statusContext
+        }, d.tail, d.log);
+    }
+    catch (err) {
+        d.error(`[chreode] ${message(err)}`);
+        return 1;
+    }
+    return 0;
+}

package/dist/signoff/tail.d.ts

@@ -0,0 +1,32 @@
+import { type RepoInfo } from '../github/status.js';
+import { type Exec, type Run } from '../run/exec.js';
+export interface TailEffects {
+    push(): void;
+    postStatus(sha: string, description: string): void;
+    writeNote(sha: string, ranLabels: readonly string[]): void;
+    prUrl(): string | null;
+}
+export interface TailWork {
+    sha: string;
+    signer: string;
+    noPush: boolean;
+    ranLabels: readonly string[];
+    skippedByFlag: readonly string[];
+    /** Policed steps that passed only because --allow-stderr waived their stderr. */
+    allowedStderr: readonly string[];
+    /** The --base ref as given, or null when the base came from the last signoff. */
+    baseFlag: string | null;
+    context: string;
+}
+/** Why this run must not become an incremental base: the note means "everything the
+ *  changes since the last note needed passed", and a partial run cannot vouch for that. */
+export declare function noteWithheldReasons(work: TailWork): string[];
+/**
+ * After every step passed: push, post the status, then write the note. The note is the
+ * incremental cache ("this commit is signed off"), so it goes last: a failed post must not
+ * leave a note that makes the next run a no-op with no status on GitHub. A partial run
+ * (--skip, --base, or stderr waived by --allow-stderr) posts a status that says so but
+ * writes no note, so the next signoff diffs from the last full one.
+ */
+export declare function runTail(work: TailWork, effects: TailEffects, log?: (m: string) => void): void;
+export declare function defaultTailEffects(repo: () => RepoInfo, context: string, exec?: Exec, run?: Run): TailEffects;