ai-foreman 1.7.6 → 1.7.8

package/README.md

@@ -105,7 +105,7 @@ What each part does:
 | `-y, --yes` | flag | off | Skips preflight confirmation. |
 | `--no-qa` | flag | QA on | Disables per-ticket QA review. |
 | `--continue` | flag | off | Resumes the most recent logged session. |
-| `-r, --resume <sessionId>` | session ID from `.foreman/` logs | none | Resumes a specific Claude/Codex session. |
+| `-r, --resume <sessionId>` | session ID with a stored scoped binding | none | Resumes only after provider, canonical worktree, and workspace identity validation. |
 | `--branch-per-ticket` | flag | off | Runs each selected structured ticket in its own git worktree and branch. Requires initialized `.tickets/`. |
 | `--create-pr` | flag | off | Pushes each successful ticket branch and creates a GitHub PR. Implies `--branch-per-ticket`. |
 | `--pr-ready` | flag | draft PRs | Creates ready-for-review PRs instead of draft PRs when used with `--create-pr`. |
@@ -114,6 +114,10 @@ What each part does:
 | `--base <ref>` | `main` / `origin/main` / `HEAD` | current branch or `HEAD` | Base ref for root ticket branches. |
 | `--branch-prefix <prefix>` | `feature` / `rafi` / another valid Git prefix | `feature` | Prefix for generated ticket branches. Explicit prefixes are preserved verbatim. |
 | `--max-branch-depth <n>` | positive integer | `5` | Maximum selected branch/PR stack depth (root PR is depth 1). |
+| `--show-session-cost` / `--hide-session-cost` | flags | saved role preferences | Show authoritative provider cost or trustworthy cumulative tokens for Builder and QA; does not change context occupancy display. |
+| `--auto-compact-threshold <percent>` | integer `1`–`99` | saved Builder value, then `50` | Initial Builder threshold override. A later explicit Builder-threshold revision wins for the active run. |
+
+Builder and QA context ceilings are configured independently (default `50%`, maximum `10` successful compactions per scoped provider session). Claude and Codex install the ceiling as a native in-turn auto-compaction limit before real work begins; Rafi verifies the post-compaction occupancy and counts provider-native and host-requested compactions together. An ineffective or failed compact receives one bounded retry, followed by a validated cumulative handoff. Status output reports the configured and installed ceilings, lifecycle state, scoped count/maximum, and settings revision without substituting cumulative session tokens for active context occupancy.
 
 Auto-detected tracker files:
 
@@ -124,6 +128,7 @@ Auto-detected tracker files:
 Resume rule:
 
 - Use either `--continue` or `--resume`.
+- Exact resume requires the original canonical worktree and its recorded identity. A deleted, recreated, cross-worktree, ambiguous, or unverifiable session is rejected with fresh/handoff recovery guidance.
 - Do not use both in the same command.
 - In branch mode, use `--continue --ticket <id>` to continue a ticket with its saved builder session.
 - For multiple branch tickets, repeat `--ticket` with `--continue`; do not reuse one explicit `--resume <sessionId>` across multiple tickets.
@@ -141,6 +146,10 @@ ai-foreman start ./my-project --steps 1 --branch-per-ticket --continue --ticket
 
 Saved `tickets.build` defaults in `rafi-config.yaml` can enable branch-per-ticket and completion behavior automatically. Use `--completion pr|auto-merge|direct-merge|none`, `--no-branch-per-ticket`, `--no-create-pr`, or `--auto-merge-wait` / `--no-auto-merge-wait` to override saved defaults for one run.
 
+With the saved `current` strategy, Foreman works in the active branch while the user owns Git. It may edit, test, run QA, and update tracker/recovery state, but all branch/worktree, commit, push, merge, rebase, and review lifecycle commands are fenced. An unexpected active ref or worktree change pauses the run. Explicit isolated flags are reported as run overrides.
+
+The active terminal line always includes the current role/provider, activity, truthful context state, successful compaction count, and handoff generation. At the Builder threshold, Foreman settles the in-flight action, verifies native compaction plus a fresh provider usage sample, and resumes the frozen action. The configured maximum defaults to ten successful compactions per location-scoped provider session; the next crossing uses a validated fresh handoff instead of exceeding it. Disposable QA snapshots never reuse a prior QA conversation in a new `/tmp/rafi-qa-*` worktree; they transfer cumulative state through an accepted handoff.
+
 ### GitHub PR Failure Recovery
 
 When `--create-pr` cannot prepare GitHub, push a branch, or create a PR, Foreman records a structured failure and blocks the affected ticket cleanly. Blocked worktrees are retained automatically so you can repair the environment and retry without losing the ticket session.
@@ -502,8 +511,14 @@ ai-foreman tickets accept-future-work 1 --project ./my-project --ticket-id T051
 ai-foreman tickets cancel T001 --project ./my-project --summary "Superseded by T002"
 ai-foreman tickets reorder T051 --project ./my-project --after T050
 ai-foreman tickets archive --project ./my-project --older-than-days 30
+
+# Inspect immutable creation groups and reset an exact approved group
+ai-foreman tickets groups list --project ./my-project
+ai-foreman tickets reset --group TG-3 --project ./my-project
 ```
 
+Ticket creation groups use stable repository-local IDs (`TG-1`, `TG-2`, …); newest-first list position is separate and may change. Missing definitions remain immutable members with a validated recovery snapshot. Non-interactive group restoration requires an explicit deleted-ticket policy, and missing dependency definitions stop the reset atomically.
+
 ## How The Loop Works
 
 Before implementation starts:
@@ -514,6 +529,8 @@ Before implementation starts:
 
 Every implementation turn must end with exactly one marker.
 
+Builder and QA turns also publish a bounded cumulative continuity delta. Automatic fresh transitions stage a versioned JSON/Markdown handoff, require `HANDOFF_ACCEPTED` plus a valid successor checkpoint, and only then move the role lease. The all-in-one `rafi` CLI exposes durable handoff inspection and cache/history maintenance commands.
+
 Marker rules:
 
 - Put the marker on the final non-empty line.
@@ -592,6 +609,14 @@ pnpm build
 pnpm dev -- start ../../examples/dummy-project --steps 2
 ```
 
+Changes to provider adapters or context lifecycle enforcement also require the opt-in authenticated gate:
+
+```bash
+pnpm test:live-providers
+```
+
+It exercises Claude and Codex as both Builder and QA with a low native ceiling, verifies in-turn compaction and same-session continuation, then verifies a maximum-one boundary interruption and validated fresh handoff. Set `RAFI_LIVE_CONTEXT_THRESHOLD_PERCENT` to an integer from `1` through `10` to override its default `10%` ceiling. Very low Claude ceilings can intentionally fail the capability check when they fall below the SDK's minimum native window. The gate uses locally authenticated provider CLIs and is intentionally skipped by the ordinary test suite.
+
 Package output:
 
 - The package publishes an `ai-foreman` binary from `dist/index.js`.

package/dist/activity.d.ts

@@ -34,6 +34,7 @@ export declare class ActivityReporter {
     private lastHeartbeatAt;
     private lineVisible;
     private paused;
+    private agentStatusLine?;
     constructor(command: string, options?: ActivityReporterOptions);
     begin(label: string): () => void;
     update(state: string, detail?: string, metadata?: {
@@ -44,6 +45,8 @@ export declare class ActivityReporter {
     pulse(detail?: string): void;
     note(message: string): void;
     writePersistent(text: string): void;
+    /** Keep role/provider/context state in the single bottom-most TTY line. */
+    setAgentStatus(line: string | undefined): void;
     pause(): () => void;
     dispose(): void;
     private startTimer;

package/dist/activity.js

@@ -23,6 +23,7 @@ export class ActivityReporter {
     lastHeartbeatAt = 0;
     lineVisible = false;
     paused = 0;
+    agentStatusLine;
     constructor(command, options = {}) {
         this.command = command;
         this.output = options.output ?? {
@@ -90,6 +91,20 @@ export class ActivityReporter {
             this.output.write("\n");
         this.render(true);
     }
+    /** Keep role/provider/context state in the single bottom-most TTY line. */
+    setAgentStatus(line) {
+        this.agentStatusLine = line ? clean(line, 500) : undefined;
+        if (this.agentStatusLine && !this.timer) {
+            this.lastSignalAt = this.now();
+            this.lastHeartbeatAt = this.lastSignalAt;
+            this.startTimer();
+        }
+        if (!this.agentStatusLine && this.phases.size === 0) {
+            this.idle();
+            return;
+        }
+        this.render(true);
+    }
     pause() {
         this.paused++;
         this.clearLine();
@@ -104,6 +119,7 @@ export class ActivityReporter {
     }
     dispose() {
         this.phases.clear();
+        this.agentStatusLine = undefined;
         this.idle();
     }
     startTimer() {
@@ -113,6 +129,14 @@ export class ActivityReporter {
         this.timer.unref();
     }
     idle() {
+        if (this.agentStatusLine) {
+            this.clearLine();
+            this.detail = undefined;
+            this.provider = undefined;
+            this.model = undefined;
+            this.render(true);
+            return;
+        }
         if (this.timer)
             clearInterval(this.timer);
         this.timer = undefined;
@@ -120,27 +144,28 @@ export class ActivityReporter {
         this.detail = undefined;
         this.provider = undefined;
         this.model = undefined;
+        this.agentStatusLine = undefined;
     }
     currentPhase() {
         return [...this.phases.values()].at(-1);
     }
     render(force) {
         const phase = this.currentPhase();
-        if (!phase || this.paused > 0)
+        if ((!phase && !this.agentStatusLine) || this.paused > 0)
             return;
         const now = this.now();
-        const elapsed = now - phase.startedAt;
+        const elapsed = phase ? now - phase.startedAt : now - this.commandStartedAt;
         if (!force && elapsed < this.displayDelayMs)
             return;
         const quietFor = now - this.lastSignalAt;
-        if (quietFor >= this.quietWarningMs && !this.quietWarningPrinted) {
+        if (phase && quietFor >= this.quietWarningMs && !this.quietWarningPrinted) {
             this.quietWarningPrinted = true;
             this.note(`rafi: ${this.provider ?? "provider"} has been quiet for ${formatDuration(quietFor)}; RAFI is still responsive and will keep waiting`);
             return;
         }
         const provider = [this.provider, this.model].filter(Boolean).join("/");
         const quiet = quietFor >= this.quietWarningMs ? `provider quiet ${formatDuration(quietFor)}; RAFI is responsive` : this.detail;
-        const body = [phase.label, provider || undefined, quiet].filter(Boolean).join(" — ");
+        const body = [phase?.label, provider || undefined, phase ? quiet : undefined, this.agentStatusLine].filter(Boolean).join(" — ");
         if (this.output.isTTY) {
             const line = `${FRAMES[this.frame++ % FRAMES.length]} RAFI working: ${body} (${formatDuration(now - this.commandStartedAt)})`;
             this.output.write(`\r\x1b[2K${line}`);
@@ -211,8 +236,8 @@ export function reportBuilderEvent(event) {
         reporter.update("processing agent response");
     else if (event.kind === "session-transition")
         reporter.update(`session ${event.transition}`, event.detail);
-    else if (event.kind === "context-usage")
-        reporter.pulse(event.percentage === undefined ? undefined : `context ${event.percentage.toFixed(0)}%`);
+    else if (event.kind === "context-compaction")
+        reporter.update(event.phase === "started" ? "compacting context" : event.phase === "succeeded" ? "context compacted" : "context compaction failed", `${event.origin} ${event.providerEventId}`, { provider: event.provider });
     else if (event.kind === "turn-complete")
         reporter.update(event.result.isError ? "agent turn failed" : "agent turn complete");
     else if (event.kind === "error")

package/dist/adapters/claude.d.ts

@@ -1,14 +1,34 @@
-import type { PermissionResult } from "@anthropic-ai/claude-agent-sdk";
+import type { SDKSessionInfo, PermissionResult } from "@anthropic-ai/claude-agent-sdk";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export declare function requireClaudeSDK(): Promise<typeof import("@anthropic-ai/claude-agent-sdk")>;
-import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, PermissionDecision, ProviderSettingSwitch, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextManagementPolicy, ContextUsage, InterruptResult, PermissionDecision, PreparedContextManagement, ProviderSettingSwitch, ProviderSessionUsage, TurnResult } from "./types.js";
+import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 /**
  * Pure function: build the `options` object passed to `query()`.
  * Extracted so tests can assert on the shape without making a live SDK call.
  * `canUseTool` is omitted here — it's a closure that the constructor adds.
  */
 export declare function buildClaudeQueryOptions(opts: Omit<BuilderAdapterOptions, "permission">): Record<string, unknown>;
+export declare function probeClaudeSession(ref: ProviderSessionRefV1, input: {
+    cwd: string;
+    configRoot?: string;
+    workspaceIdentity?: string;
+    role?: ProviderSessionRefV1["role"];
+    stream?: string;
+    ticketId?: string;
+    deliveryUnitId?: string;
+    getSessionInfo?: (sessionId: string, options?: {
+        dir?: string;
+    }) => Promise<SDKSessionInfo | undefined>;
+    now?: Date;
+}): Promise<SessionAvailabilityV1>;
 export declare function permissionDecisionToClaudeResult(decision: PermissionDecision, toolUseID?: string): PermissionResult;
+/** Project one cumulative SDK result without inventing or double-counting counters. */
+export declare function mergeClaudeProviderSessionUsage(prior: ProviderSessionUsage, rawResult: Record<string, unknown>, observedAt?: string): {
+    sample: ProviderSessionUsage;
+    inputTokens?: number;
+    outputTokens?: number;
+};
 export declare function claudeApiRetryEvent(message: {
     error: string;
     attempt: number;
@@ -23,21 +43,42 @@ export declare function claudeApiRetryEvent(message: {
 export declare class ClaudeAdapter implements BuilderAdapter {
     private readonly opts;
     readonly agent: "claude";
-    private readonly inbox;
+    private inbox;
     private readonly eventQueue;
-    private readonly query;
-    private readonly abort;
-    private readonly pumpDone;
+    private query;
+    private abort;
+    private pumpDone;
+    private readonly queryFactory;
+    private transportGeneration;
+    private transportObservedSessionId?;
     private _sessionId?;
+    private _sessionRef?;
     private readonly stderrChunks;
     private turnSignals;
     private structuredError?;
     private apiErrorStatus?;
     private compactResult?;
+    private contextPolicy?;
+    private contextSequence;
+    private compactionSequence;
+    private activeCompaction?;
+    private manualCompactionPending;
+    private boundaryInterrupt?;
+    private compactionTerminalObserved;
+    private lastContextUsage?;
+    /** Full provider context capacity, before Rafi narrows Claude's auto-compact window. */
+    private modelContextWindow?;
+    /** SDK-owned space between autoCompactWindow and the actual used-token trigger. */
+    private nativeAutoCompactReserve?;
+    private contextPrepared;
+    private cumulativeUsage;
     private pending?;
+    private terminalResult?;
+    private streamEnded;
     private closed;
     static create(opts: BuilderAdapterOptions): Promise<ClaudeAdapter>;
     private constructor();
+    private openQuery;
     /** Background loop: consume the SDK message stream until it ends. */
     private pump;
     private handle;
@@ -45,9 +86,23 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private sendTurnInternal;
     private captureStderr;
     sessionId(): string | undefined;
+    sessionRef(): ProviderSessionRefV1 | undefined;
+    adoptSessionRef(ref: ProviderSessionRefV1): void;
+    validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
     contextUsage(): Promise<ContextUsage | undefined>;
+    prepareContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    updateContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    interruptTurnAtCompactionBoundary(providerEventId?: string): Promise<InterruptResult>;
+    sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
+    private observeSession;
+    private makeContextUsage;
+    private configureContextManagement;
+    private restartTransport;
+    private completeCompaction;
+    private settlePending;
+    private streamFailureResult;
 }