agent-bober 0.12.0 → 0.15.0

package/dist/incident/resolution-verify.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Resolution verification gate (Sprint 22).
+ *
+ * verifyResolution queries the configured observability MCP provider for the
+ * named metric over the named window, applies the comparison per-sample (lt is
+ * strict <, lte is <=, gt is strict >, gte is >=), and returns verified=true
+ * ONLY when EVERY sample meets the threshold. One outlier = not verified.
+ *
+ * Evidence persistence: every call (verified=true OR false) writes raw samples
+ * to `.bober/incidents/<id>/resolution-evidence/<ISO-timestamp>.json` for
+ * audit and postmortem reconstruction. Presence of the evidence file does
+ * NOT imply resolution — only the VerifyResult.verified boolean does.
+ *
+ * No provider configured: returns verified=false, reason='NO_PROVIDER', hint.
+ * Override path: handled by setIncidentStatus in src/incident/timeline.ts,
+ * not here. This module ONLY measures.
+ *
+ * Sprint 22 — src/incident/resolution-verify.ts
+ */
+import { z } from "zod";
+import type { ObservabilityProvider } from "../config/schema.js";
+import type { IncidentId } from "./types.js";
+export declare const ComparisonSchema: z.ZodEnum<["lt", "gt", "lte", "gte"]>;
+export type Comparison = z.infer<typeof ComparisonSchema>;
+export declare const BaselineComparisonSchema: z.ZodEnum<["absolute", "percent-of-baseline"]>;
+export type BaselineComparison = z.infer<typeof BaselineComparisonSchema>;
+export declare const ResolutionCriteriaSchema: z.ZodObject<{
+    metricName: z.ZodString;
+    threshold: z.ZodNumber;
+    comparison: z.ZodEnum<["lt", "gt", "lte", "gte"]>;
+    windowMinutes: z.ZodNumber;
+    provider: z.ZodString;
+    baselineComparison: z.ZodOptional<z.ZodEnum<["absolute", "percent-of-baseline"]>>;
+}, "strip", z.ZodTypeAny, {
+    provider: string;
+    metricName: string;
+    threshold: number;
+    comparison: "lt" | "gt" | "lte" | "gte";
+    windowMinutes: number;
+    baselineComparison?: "absolute" | "percent-of-baseline" | undefined;
+}, {
+    provider: string;
+    metricName: string;
+    threshold: number;
+    comparison: "lt" | "gt" | "lte" | "gte";
+    windowMinutes: number;
+    baselineComparison?: "absolute" | "percent-of-baseline" | undefined;
+}>;
+export type ResolutionCriteria = z.infer<typeof ResolutionCriteriaSchema>;
+export declare const MetricSampleSchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    value: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    value: number;
+    timestamp: string;
+}, {
+    value: number;
+    timestamp: string;
+}>;
+export type MetricSample = z.infer<typeof MetricSampleSchema>;
+export declare const VerifyResultSchema: z.ZodObject<{
+    verified: z.ZodBoolean;
+    /** Worst-case sample value (the one that failed, else last sample). */
+    observedValue: z.ZodOptional<z.ZodNumber>;
+    /** ISO timestamp of the witness sample. */
+    sampledAt: z.ZodOptional<z.ZodString>;
+    /** Path to the evidence file: .bober/incidents/<id>/resolution-evidence/<ts>.json */
+    evidencePath: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodEnum<["OK", "OUTLIER", "NO_PROVIDER", "NOT_IMPLEMENTED", "MCP_ERROR"]>>;
+    hint: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    verified: boolean;
+    reason?: "OK" | "OUTLIER" | "NO_PROVIDER" | "NOT_IMPLEMENTED" | "MCP_ERROR" | undefined;
+    hint?: string | undefined;
+    observedValue?: number | undefined;
+    sampledAt?: string | undefined;
+    evidencePath?: string | undefined;
+}, {
+    verified: boolean;
+    reason?: "OK" | "OUTLIER" | "NO_PROVIDER" | "NOT_IMPLEMENTED" | "MCP_ERROR" | undefined;
+    hint?: string | undefined;
+    observedValue?: number | undefined;
+    sampledAt?: string | undefined;
+    evidencePath?: string | undefined;
+}>;
+export type VerifyResult = z.infer<typeof VerifyResultSchema>;
+export declare const ResolutionEvidenceSchema: z.ZodObject<{
+    incidentId: z.ZodString;
+    verifiedAt: z.ZodString;
+    criteria: z.ZodObject<{
+        metricName: z.ZodString;
+        threshold: z.ZodNumber;
+        comparison: z.ZodEnum<["lt", "gt", "lte", "gte"]>;
+        windowMinutes: z.ZodNumber;
+        provider: z.ZodString;
+        baselineComparison: z.ZodOptional<z.ZodEnum<["absolute", "percent-of-baseline"]>>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        metricName: string;
+        threshold: number;
+        comparison: "lt" | "gt" | "lte" | "gte";
+        windowMinutes: number;
+        baselineComparison?: "absolute" | "percent-of-baseline" | undefined;
+    }, {
+        provider: string;
+        metricName: string;
+        threshold: number;
+        comparison: "lt" | "gt" | "lte" | "gte";
+        windowMinutes: number;
+        baselineComparison?: "absolute" | "percent-of-baseline" | undefined;
+    }>;
+    samples: z.ZodArray<z.ZodObject<{
+        timestamp: z.ZodString;
+        value: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        timestamp: string;
+    }, {
+        value: number;
+        timestamp: string;
+    }>, "many">;
+    allSamplesPassed: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    incidentId: string;
+    verifiedAt: string;
+    criteria: {
+        provider: string;
+        metricName: string;
+        threshold: number;
+        comparison: "lt" | "gt" | "lte" | "gte";
+        windowMinutes: number;
+        baselineComparison?: "absolute" | "percent-of-baseline" | undefined;
+    };
+    samples: {
+        value: number;
+        timestamp: string;
+    }[];
+    allSamplesPassed: boolean;
+}, {
+    incidentId: string;
+    verifiedAt: string;
+    criteria: {
+        provider: string;
+        metricName: string;
+        threshold: number;
+        comparison: "lt" | "gt" | "lte" | "gte";
+        windowMinutes: number;
+        baselineComparison?: "absolute" | "percent-of-baseline" | undefined;
+    };
+    samples: {
+        value: number;
+        timestamp: string;
+    }[];
+    allSamplesPassed: boolean;
+}>;
+export type ResolutionEvidence = z.infer<typeof ResolutionEvidenceSchema>;
+export interface MetricQueryArgs {
+    name: string;
+    timeRange: {
+        start: string;
+        end: string;
+    };
+    step?: string;
+}
+export interface MetricQueryClient {
+    /** Call obs__<provider>__query_metric and return parsed dataPoints. */
+    queryMetric(provider: string, args: MetricQueryArgs): Promise<MetricSample[]>;
+}
+export interface VerifyResolutionDeps {
+    projectRoot: string;
+    providers: readonly ObservabilityProvider[];
+    /** Injected for tests; default = real spawn via mergeObsTools. */
+    client?: MetricQueryClient;
+    /** Injected clock for tests. Default = () => new Date(). */
+    now?: () => Date;
+}
+/**
+ * Apply the comparison per the criteria. Boundary semantics:
+ *   - 'lt'  : value <  threshold  (strict; value === threshold FAILS)
+ *   - 'lte' : value <= threshold  (inclusive; value === threshold PASSES)
+ *   - 'gt'  : value >  threshold  (strict)
+ *   - 'gte' : value >= threshold  (inclusive)
+ */
+export declare function sampleMeetsThreshold(value: number, threshold: number, comparison: Comparison): boolean;
+export declare function verifyResolution(incidentId: IncidentId, criteria: ResolutionCriteria, deps: VerifyResolutionDeps): Promise<VerifyResult>;
+//# sourceMappingURL=resolution-verify.d.ts.map

package/dist/incident/resolution-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution-verify.d.ts","sourceRoot":"","sources":["../../src/incident/resolution-verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,eAAO,MAAM,gBAAgB,uCAAqC,CAAC;AACnE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,wBAAwB,gDAA8C,CAAC;AACpF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;EAOnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,kBAAkB;;;;;;;;;EAG7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,kBAAkB;;IAE7B,uEAAuE;;IAEvE,2CAA2C;;IAE3C,qFAAqF;;;;;;;;;;;;;;;;;;EAIrF,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAI1E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC5C,kEAAkE;IAClE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAOtG;AAID,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,YAAY,CAAC,CA6EvB"}

package/dist/incident/resolution-verify.js

@@ -0,0 +1,210 @@
+/**
+ * Resolution verification gate (Sprint 22).
+ *
+ * verifyResolution queries the configured observability MCP provider for the
+ * named metric over the named window, applies the comparison per-sample (lt is
+ * strict <, lte is <=, gt is strict >, gte is >=), and returns verified=true
+ * ONLY when EVERY sample meets the threshold. One outlier = not verified.
+ *
+ * Evidence persistence: every call (verified=true OR false) writes raw samples
+ * to `.bober/incidents/<id>/resolution-evidence/<ISO-timestamp>.json` for
+ * audit and postmortem reconstruction. Presence of the evidence file does
+ * NOT imply resolution — only the VerifyResult.verified boolean does.
+ *
+ * No provider configured: returns verified=false, reason='NO_PROVIDER', hint.
+ * Override path: handled by setIncidentStatus in src/incident/timeline.ts,
+ * not here. This module ONLY measures.
+ *
+ * Sprint 22 — src/incident/resolution-verify.ts
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { mergeObsTools, namespaceToolName, stopAll } from "../orchestrator/observability/merge.js";
+// ── Schemas ────────────────────────────────────────────────────────────────────
+export const ComparisonSchema = z.enum(["lt", "gt", "lte", "gte"]);
+export const BaselineComparisonSchema = z.enum(["absolute", "percent-of-baseline"]);
+export const ResolutionCriteriaSchema = z.object({
+    metricName: z.string().min(1),
+    threshold: z.number(),
+    comparison: ComparisonSchema,
+    windowMinutes: z.number().int().positive(),
+    provider: z.string().min(1),
+    baselineComparison: BaselineComparisonSchema.optional(),
+});
+export const MetricSampleSchema = z.object({
+    timestamp: z.string(),
+    value: z.number(),
+});
+export const VerifyResultSchema = z.object({
+    verified: z.boolean(),
+    /** Worst-case sample value (the one that failed, else last sample). */
+    observedValue: z.number().optional(),
+    /** ISO timestamp of the witness sample. */
+    sampledAt: z.string().optional(),
+    /** Path to the evidence file: .bober/incidents/<id>/resolution-evidence/<ts>.json */
+    evidencePath: z.string().optional(),
+    reason: z.enum(["OK", "OUTLIER", "NO_PROVIDER", "NOT_IMPLEMENTED", "MCP_ERROR"]).optional(),
+    hint: z.string().optional(),
+});
+export const ResolutionEvidenceSchema = z.object({
+    incidentId: z.string(),
+    verifiedAt: z.string(),
+    criteria: ResolutionCriteriaSchema,
+    samples: z.array(MetricSampleSchema),
+    allSamplesPassed: z.boolean(),
+});
+// ── Per-sample comparator ──────────────────────────────────────────────────────
+/**
+ * Apply the comparison per the criteria. Boundary semantics:
+ *   - 'lt'  : value <  threshold  (strict; value === threshold FAILS)
+ *   - 'lte' : value <= threshold  (inclusive; value === threshold PASSES)
+ *   - 'gt'  : value >  threshold  (strict)
+ *   - 'gte' : value >= threshold  (inclusive)
+ */
+export function sampleMeetsThreshold(value, threshold, comparison) {
+    switch (comparison) {
+        case "lt": return value < threshold;
+        case "lte": return value <= threshold;
+        case "gt": return value > threshold;
+        case "gte": return value >= threshold;
+    }
+}
+// ── Main entry point ───────────────────────────────────────────────────────────
+export async function verifyResolution(incidentId, criteria, deps) {
+    ResolutionCriteriaSchema.parse(criteria);
+    // 1. baselineComparison = 'percent-of-baseline' is documented but deferred.
+    //    Sprint 22 does not implement baseline retrieval — there is no baseline
+    //    data infrastructure in the repo. Return NOT_IMPLEMENTED as per contract.
+    if (criteria.baselineComparison === "percent-of-baseline") {
+        return {
+            verified: false,
+            reason: "NOT_IMPLEMENTED",
+            hint: "baselineComparison='percent-of-baseline' is not implemented in Sprint 22. Use 'absolute' or omit. Tracked as a follow-up.",
+        };
+    }
+    // 2. Provider lookup. No provider → NO_PROVIDER with actionable hint.
+    const providerDecl = deps.providers.find((p) => p.name === criteria.provider && p.enabled !== false);
+    if (!providerDecl) {
+        return {
+            verified: false,
+            reason: "NO_PROVIDER",
+            hint: `No observability provider '${criteria.provider}' configured for metric '${criteria.metricName}'. ` +
+                `Add it to bober.config.json under observability.providers, or use overrideToken='SKIP_METRIC_VERIFY: <reason>' when calling setIncidentStatus(..., 'resolved', { overrideToken }).`,
+        };
+    }
+    // 3. Window → ISO time range.
+    const now = (deps.now ?? (() => new Date()))();
+    const end = now.toISOString();
+    const start = new Date(now.getTime() - criteria.windowMinutes * 60_000).toISOString();
+    // 4. Query the metric via injected client (default = spawn via mergeObsTools).
+    let samples;
+    try {
+        const client = deps.client ?? (await defaultMcpClient([providerDecl]));
+        samples = await client.queryMetric(criteria.provider, {
+            name: criteria.metricName,
+            timeRange: { start, end },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            verified: false,
+            reason: "MCP_ERROR",
+            hint: `Failed to query metric: ${msg.replace(/\b[A-Z_][A-Z0-9_]*=\S+/g, "[redacted]")}`,
+        };
+    }
+    // 5. Per-sample comparison; allSamplesPassed is the gate.
+    //    Guard: empty samples array → every() returns true on empty, so guard with length > 0.
+    const allSamplesPassed = samples.length > 0 &&
+        samples.every((s) => sampleMeetsThreshold(s.value, criteria.threshold, criteria.comparison));
+    // 6. Worst-case sample for observedValue (the one that FAILED, else last).
+    const lastSample = samples[samples.length - 1];
+    const failingSample = samples.find((s) => !sampleMeetsThreshold(s.value, criteria.threshold, criteria.comparison));
+    const witness = failingSample ?? lastSample;
+    // 7. Write evidence file ALWAYS (audit/postmortem).
+    const evidencePath = await writeEvidenceFile(deps.projectRoot, incidentId, {
+        incidentId,
+        verifiedAt: end,
+        criteria,
+        samples,
+        allSamplesPassed,
+    });
+    return {
+        verified: allSamplesPassed,
+        observedValue: witness?.value,
+        sampledAt: witness?.timestamp,
+        evidencePath,
+        reason: allSamplesPassed ? "OK" : samples.length === 0 ? "MCP_ERROR" : "OUTLIER",
+    };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────────
+async function writeEvidenceFile(projectRoot, incidentId, evidence) {
+    const dir = join(projectRoot, ".bober", "incidents", incidentId, "resolution-evidence");
+    await mkdir(dir, { recursive: true });
+    const fname = `${evidence.verifiedAt.replace(/[:.]/g, "-")}.json`;
+    const fpath = join(dir, fname);
+    await writeFile(fpath, JSON.stringify(evidence, null, 2) + "\n", {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    return fpath;
+}
+async function defaultMcpClient(providers) {
+    const { servers } = await mergeObsTools(providers);
+    // Map providerName → server for direct callTool invocations.
+    const serverByName = new Map(servers.map((s) => [s.name, s]));
+    return {
+        async queryMetric(provider, args) {
+            const server = serverByName.get(provider);
+            if (!server) {
+                // best-effort stop before throwing
+                await stopAll(servers).catch(() => { });
+                throw new Error(`provider '${provider}' not running after mergeObsTools`);
+            }
+            // The upstream name is 'query_metric'; namespaceToolName is for the diagnoser's tool list,
+            // NOT for direct callTool invocation on the server (per Pattern D in briefing).
+            const upstreamName = namespaceToolName(provider, "query_metric").replace(`obs__${provider}__`, "");
+            try {
+                const raw = await server.callTool(upstreamName, args);
+                return extractSamples(raw);
+            }
+            finally {
+                await stopAll(servers).catch(() => { });
+            }
+        },
+    };
+}
+/**
+ * Parse the metrics MCP response shape (from docs/observability-mcps/metrics.md):
+ *   { metric, labels, dataPoints: [{ timestamp, value }] }
+ * Tolerates the SDK callTool() envelope (which may wrap content in `content`).
+ */
+function extractSamples(raw) {
+    // The MCP SDK callTool returns { content: [{type:'text',text:...}], isError }.
+    // Real implementations may return structured JSON in `content[0].text` OR
+    // a typed result. Accept both shapes defensively.
+    const candidate = raw;
+    if (Array.isArray(candidate.dataPoints)) {
+        return candidate.dataPoints
+            .map((p) => MetricSampleSchema.safeParse(p))
+            .filter((r) => r.success)
+            .map((r) => r.data);
+    }
+    if (Array.isArray(candidate.content) && candidate.content[0]?.text) {
+        try {
+            const parsed = JSON.parse(candidate.content[0].text);
+            if (Array.isArray(parsed?.dataPoints)) {
+                return parsed.dataPoints
+                    .map((p) => MetricSampleSchema.safeParse(p))
+                    .filter((r) => r.success)
+                    .map((r) => r.data);
+            }
+        }
+        catch {
+            // fallthrough — return empty array
+        }
+    }
+    return [];
+}
+//# sourceMappingURL=resolution-verify.js.map

package/dist/incident/resolution-verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution-verify.js","sourceRoot":"","sources":["../../src/incident/resolution-verify.ts"],"names":[],"mappings":"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"}

package/dist/incident/rollback.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Rollback awareness helpers (Sprint 21).
+ *
+ * Reads changelog.jsonl for an incident, identifies ChangeEntries that are
+ * effective-status 'executed' (not yet rolled back), and provides:
+ *
+ *   planRollback  — returns a RollbackPlan with steps in reverse execution order.
+ *   executeRollback — runs each step via the Sprint 20 risky-action gate (per-step).
+ *   presentPlan   — renders the plan to a human-readable string for CLI output.
+ *
+ * Escalation design note (Sprint 21):
+ *   True checkpoint-based escalation is deferred to Sprint 24 (full /bober-incident
+ *   flow). Escalation here consists of:
+ *     1. A 'rollback_halted' timeline event with remaining step ids.
+ *     2. A stderr warning via writeWarn.
+ *     3. result.escalated=true + result.remaining=[...] returned to the caller.
+ *   Sprint 24 can wrap this return value in a real checkpoint if needed.
+ *
+ * JSONL semantics: changelog.jsonl is append-only; "latest line per id wins".
+ * When a change is executed, Sprint 20 writes two lines (pending, executed).
+ * After rollback, Sprint 21 appends a third line (rolled-back). Effective status
+ * is determined by the LAST line in file-order with a given id.
+ *
+ * Reverse execution order: sort by the FIRST entry's executedAt (when the action
+ * originally ran), then reverse. File order guarantees write monotonicity.
+ *
+ * Sprint 21 — src/incident/rollback.ts
+ */
+import type { ExecutorSeam } from "../orchestrator/deploy/types.js";
+import type { RiskyActionConfig } from "../orchestrator/deploy/resolve.js";
+import type { IncidentId } from "./types.js";
+export interface RollbackStep {
+    originalChangeId: string;
+    originalDescription: string;
+    inverseDescription: string;
+    inverseCommand?: string;
+    /** ISO-8601 from the original ChangeEntry's first (pending/executed) record. */
+    originalExecutedAt: string;
+}
+export interface RollbackPlan {
+    incidentId: string;
+    totalChanges: number;
+    rollbackableChanges: number;
+    /** Count of changes excluded because no inverse is available. */
+    unrollbackableChanges: number;
+    steps: RollbackStep[];
+    warnings: string[];
+}
+export interface PlanRollbackOpts {
+    /** Include only changes executed AFTER this changeId (strict-after semantics). */
+    since?: string;
+}
+export interface ExecuteRollbackOpts {
+    /** Pipeline config — forwarded to executeAction for gate resolution. */
+    config?: RiskyActionConfig;
+    /** Injected executor (for tests). Default = real execa-based executor. */
+    executor?: ExecutorSeam;
+    /** Stderr writer override (for capturing warnings in tests). Default = process.stderr.write. */
+    writeWarn?: (msg: string) => void;
+    /** Injectable clock (for tests). Default = () => new Date(). */
+    now?: () => Date;
+}
+export interface RollbackExecutionEntry {
+    /** ISO-8601 timestamp of when the rollback step was attempted. */
+    timestamp: string;
+    originalChangeId: string;
+    inverseDescription: string;
+    status: "rolled-back" | "rolled-back-failed";
+    durationMs: number;
+    errorMessage?: string;
+}
+export interface RollbackResult {
+    attempted: number;
+    succeeded: number;
+    /** 0 or 1 — the sequence halts on the first failure. */
+    failed: number;
+    /** Non-empty when failed === 1; contains steps that were not attempted. */
+    remaining: RollbackStep[];
+    /** true when the rollback halted due to a failure — caller should escalate. */
+    escalated: boolean;
+}
+/**
+ * Build a RollbackPlan from a changelog.
+ *
+ * Effective-status semantics (latest-line-wins):
+ *   For each unique `id`, group all entries; the LAST entry in file order
+ *   determines the effective status. Only `executed` entries are rollbackable.
+ *
+ * Reverse execution order:
+ *   Steps are sorted ascending by the FIRST entry's executedAt (the original
+ *   execution time), then reversed. This means the most recent action is
+ *   rolled back first.
+ *
+ * --since semantics (changeId-based, strict-after):
+ *   Only changes whose FIRST entry's executedAt is strictly greater than the
+ *   --since changeId's first entry's executedAt are included.
+ *
+ * @param projectRoot  Absolute path to the project root.
+ * @param incidentId   Incident to plan a rollback for.
+ * @param opts         Optional PlanRollbackOpts.
+ * @throws Error if opts.since references a non-existent changeId.
+ */
+export declare function planRollback(projectRoot: string, incidentId: IncidentId, opts?: PlanRollbackOpts): Promise<RollbackPlan>;
+/**
+ * Render a RollbackPlan to a human-readable string for CLI output.
+ *
+ * Always includes:
+ * - Header with incident ID
+ * - Change counts (total, rollbackable, unrollbackable)
+ * - Numbered steps in reverse execution order
+ * - Warnings section (if any)
+ */
+export declare function presentPlan(plan: RollbackPlan): string;
+/**
+ * Execute a RollbackPlan step by step.
+ *
+ * Each step is a risky action that MUST pass through the Sprint 20 gate
+ * individually. This means N rollback steps → N gate invocations.
+ *
+ * On success of each step:
+ *   - Appends a ChangeEntry with id=originalChangeId, status='rolled-back'.
+ *   - Appends a RollbackExecutionEntry with status='rolled-back'.
+ *
+ * On failure of any step:
+ *   - Appends a ChangeEntry with id=originalChangeId, status='rolled-back-failed'.
+ *   - Appends a RollbackExecutionEntry with status='rolled-back-failed'.
+ *   - Halts the sequence (remaining steps are NOT attempted).
+ *   - Emits a 'rollback_halted' timeline event.
+ *   - Returns result.escalated=true with result.remaining=[unrolled steps].
+ *
+ * @param projectRoot  Absolute path to the project root.
+ * @param incidentId   Incident to execute the rollback for.
+ * @param plan         The plan produced by planRollback.
+ * @param opts         Optional injections (config, executor, writeWarn, now).
+ */
+export declare function executeRollback(projectRoot: string, incidentId: IncidentId, plan: RollbackPlan, opts?: ExecuteRollbackOpts): Promise<RollbackResult>;
+//# sourceMappingURL=rollback.d.ts.map

package/dist/incident/rollback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.d.ts","sourceRoot":"","sources":["../../src/incident/rollback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAQH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,MAAM,WAAW,YAAY;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,gGAAgG;IAChG,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,aAAa,GAAG,oBAAoB,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;CACpB;AA0ED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAyEvB;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CA8BtD;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,YAAY,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,cAAc,CAAC,CA2HzB"}