Skip to content

M5: Compaction-checkpoint fast path + budget voter - #2

Merged
pdettori merged 12 commits into
mainfrom
feat/m5-compaction-checkpoint
Jun 24, 2026
Merged

M5: Compaction-checkpoint fast path + budget voter#2
pdettori merged 12 commits into
mainfrom
feat/m5-compaction-checkpoint

Conversation

@pdettori

@pdettori pdettori commented Jun 24, 2026

Copy link
Copy Markdown
Member

M5 — Compaction-Checkpoint Fast Path + Budget Voter

Implements the pi-track plan's M4 (repo milestone 5). Spec: docs/specs/2026-06-23-m5-compaction-checkpoint-design.md. Plan: docs/superpowers/plans/2026-06-23-m5-compaction-checkpoint.md.

Makes cold-start session reconstruction O(tail) by riding Pi's native compaction as the checkpoint, and adds a per-turn budget voter that blocks tool calls once a token cap is breached.

Changes

  • @sh/session-backend — RedisSessionBackend assigns each entry the Redis stream id "<position>-0", so read(fromPosition) is an O(tail) XRANGE seek instead of a full-stream scan + JS filter. New positionOfId; LogStore interface extended.
  • pi-fork (submodule) — additive SessionManager.openFromCheckpoint() + markerResumePosition helper: reads only the checkpoint marker's resumeFromPosition-forward slice, reuses the existing loadFromEntries/buildSessionContext path, and falls back to openFromBackend when there is no usable marker. openFromBackend is untouched.
  • harness/src/checkpoint-extension.ts — on session_compact, appends a tiny custom/checkpoint marker recording positionOf(firstKeptEntryId).
  • harness/src/budget-voter.ts — pure decideBudget, sessionSpendTotal, and budgetVoterExtension. Gated by env SH_BUDGET_TOKENS (+ optional SH_BUDGET_MARGIN); unset ⇒ inert.
  • harness/src/run-turn.ts — resumes via openFromCheckpoint; always registers the checkpoint extension; registers the budget voter when SH_BUDGET_TOKENS is a finite value > 0.

Submodule

This PR bumps the pi-fork submodule pointer to branch feat/m5-openfromcheckpoint on kagenti/pi (additive openFromCheckpoint loader + a caveat doc comment). No upstream PR.

Verification (no LLM key required)

  • Harness suites 19/19, @sh/session-backend 10/10, all against real Redis.
  • Reconstruction parity gate (the M5 done-criterion): openFromCheckpoint(...).buildSessionContext() deep-equals openFromBackend(...) after a real compaction; slice read is strictly smaller than the full log.
  • pi-fork build (tsgo) passes; targeted session-manager regression tests green.
  • harness/test/run-turn.test.ts is LLM-gated and excluded.

Known caveat (documented + test-locked)

Tail-load drops the session-start thinking_level_change entry (it precedes firstKeptEntryId), so thinkingLevel reconstructs to the settings default on the first post-compaction resume; it self-heals on the next turn and is harmless while thinking level is settings-governed. model is unaffected (re-set by every assistant message, always in the kept tail). A test in checkpoint.test.ts locks this behavior.

Deferred (out of scope)

everyK/forced-checkpoint cadence; cross-turn cumulative budget ledger.

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

Paolo Dettori added 12 commits June 18, 2026 23:19
Paolo Dettori
docs(specs): M10 design — MCP via code-mode in the sandbox
c285761 
Supersedes parent-design §3.3 (gateway forwarding tools). MCP becomes code
the model runs in the sandbox; creds injected + per-call audit at the
AuthBridge egress waypoint. Near-zero Pi surface; lean-both budget.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
docs(specs): M10 v1.1 — credential & identity model for unattended se…
206b019 
…ssions

Add §5: where secrets live (Keycloak + K8s Secret, broker-sidecar memory
only); per-user scoping for unattended sessions via SPIFFE actor + bound
subject + pre-authorized Keycloak delegation (RFC 8693 §4.1); placeholder
swap; OpenShell env-cred complement; best-fit comparison of AuthBridge /
OpenShell / DAM. New decisions D8-D10, consequences, and gate criterion 5.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
docs(specs): M13 design — generalized credentialed egress for non-MCP…
809f7b2 
… HTTP APIs

Generalizes M10's MCP-over-HTTP egress into a unified credentialed-egress
path where MCP is one special case. Same AuthBridge waypoint, selector,
audit producer, and budget machinery; per-destination credential resolver
(RFC 8693 mint vs. per-user stored grant). Adds in-mesh front-door for
external hosts (no baked CA), generic egress helper + committed GitHub
wrapper, and records the per-user external-credential store + linking flow
as an M7-M9 identity-plane dependency.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
docs(specs): M13 v2.0 — pivot to placeholder-swap + forward proxy
19f8034 
Pivots the non-MCP egress mechanism from an in-mesh front-door + host-based
injection (v1.0) to AuthBridge's own placeholder-swap pattern over a forward
proxy (HTTPS_PROXY + baked CA). The sandbox/tools hold only inert
placeholders; the proxy sees the request at L7 and overwrites with the real
resolved credential. gh/curl/SDKs now work natively and unmodified;
front-door + correctness-wrappers apparatus collapses; full per-call L7
audit preserved; more faithful to AuthBridge. Accepted cost: a baked CA
(trust anchor, not a secret) and a narrow env-inject escape hatch for
request-signing APIs (AWS SigV4). Selector and per-user stored-credential
model unchanged from v1.0.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
docs(specs): M5 compaction-checkpoint fast path + budget voter design
35e171a 
Implements the pi-track plan's Milestone M4 (Tasks 13-14), re-targeted to
the repo's real architecture: ride Pi's native compaction as the checkpoint,
add SessionManager.openFromCheckpoint for O(tail) cold-start reconstruction,
and a per-turn token budget voter. Repo milestone 5 (follows m4-knative).

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
docs(plans): M5 compaction-checkpoint implementation plan
642f40b 
Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
feat(session-backend): O(tail) stream-id read seek + positionOfId
866fb56 
Assigns each entry the Redis stream id "<position>-0" so read(fromPosition)
is an XRANGE seek instead of a full-stream scan, and adds positionOfId for the
M5 checkpoint marker.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
feat(harness): cover openFromCheckpoint tail load + fallback
6b721bc 
Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
feat(harness): per-turn budget voter (decideBudget + tool_call block)
64ccd63 
Pure decideBudget policy plus an extension that meters cumulative assistant
token spend via ctx.sessionManager.getBranch(), blocks the tool call and
appends a single abort entry once the per-turn delta breaches the cap.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
feat(harness): checkpoint-marker extension on session_compact
0b2d2cb 
Appends a resume-pointer custom entry recording positionOf(firstKeptEntryId)
so cold start can seek directly to the kept tail.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
feat(harness): wire openFromCheckpoint + checkpoint & budget extensions
d67c33a 
Resume via the O(tail) openFromCheckpoint loader, always register the
checkpoint-marker extension, and register the budget voter when
SH_BUDGET_TOKENS is set. Adds the reconstruction parity gate.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
Paolo Dettori
docs(m5): correct thinkingLevel tail-load constraint + lock with test
80f258d 
Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <paolo.dettori@example.com>
@pdettori
pdettori merged commit 8083a27 into main Jun 24, 2026
1 check passed
@pdettori
pdettori deleted the feat/m5-compaction-checkpoint branch June 24, 2026 13:52
This was referenced Jul 9, 2026
Closed
Closed
Closed
Closed
Merged
This was referenced Aug 27, 2026
Closed
Merged
Closed
Closed
Merged
cwiklik added a commit that referenced this pull request Sep 9, 2026
@cwiklik
docs(spec): P5 v1.1 — absorb MU1 composition and P6 entry-point asks
a982ffd 
Addresses the two reviews on #242. Ten changes, no change to the three
ordered steps in §3.2 or to the shape of the implementation.

Blocking finding (§4, SettingsManager):

- The three lines cited as "project-scope mutators" were
  `setProjectTrusted()` calls (`settings-manager.ts:447`), which flip an
  in-memory boolean and write nothing. Replaced with the set that can
  write — `updateProjectSettings` (`:635`) → `assertProjectTrustedForWrite`
  (`:527`), reached from `setProjectPackages` (`:942`),
  `setProjectExtensionPaths` (`:958`), `setProjectSkillPaths` (`:974`),
  `setProjectPromptTemplatePaths` (`:990`), `setProjectThemePaths`
  (`:1006`), plus `saveProjectSettings` (`:618`) and the `"project"` branch
  of `enqueueWrite` (`:552-553`).
- Re-ran the reachability audit against those five, which the review could
  not settle because GitHub code search does not index the pinned fork.
  Their only non-test callers are the interactive TUI
  (`config-selector.ts:484-490`, `:558`) and `pi packages` via
  `package-manager.ts:798`/`:806`/`:824` → `installAndPersist` (`:989`) /
  `removeAndPersist` (`:1014`) → `package-manager-cli.ts:601`/`:606`, both
  also requiring `local: true` (`:783`, `:814`, `:994`). Neither exists in
  server mode: `sdk.ts` constructs no `PackageManager` and `run-turn.ts`
  passes none (`:499-504`). The conclusion survives; only the evidence did
  not, and both are now recorded.
- Residual #1 retargeted at the five `setProject*` methods.

MU1 composition (§3.6 of the now-merged control-plane spec):

- §3.2 step 1 keeps "no new credential *path*" but requires the tagged
  `UpstreamCredential` union, with both silent failure directions.
- §3.2 declines to pin "an inbound `X-SH-Subject` is always honoured";
  pins the durable form instead — the subject is resolved from the
  request, never from process state — with `subject_conflict` (400).
- §5 lock-down row rescoped from process to **environment**, citing
  ADR-0033's accepted divergence; notes the stronger claim should be gated
  on direct mode being disabled rather than weakened.
- §5 fail-closed row rephrased on resolvability, so MU1 need not invert it.

P6 (#244) entry-point asks:

- §3.2 step 3: land the scrub as an exported function `startServer()`
  calls, so the VM worker — a third entry point that never calls
  `listen()` — is not the one path that runs unscrubbed at W×S.
- §4: `stdoutTakeoverState` pin reworded to "any non-CLI entry point".
- §4: verdicts scoped to correctness and silent on liveness, pointing the
  liveness question at the deployment-model slice.
- §5: write the two-tenant test against a parameterizable entry point.
- Residual #2 expanded with the `cwd` → single-lockfile chain, the absence
  of an async `withLock`, the `AuthStorage` non-hazard
  (`auth-storage.ts:76-98`, but `getApiKey` `:464` →
  `refreshOAuthTokenWithLock` `:409` → `withLockAsync` `:417`), and P6
  §5.2's event-loop lag p99 as the existing instrument.

Nits and coherence:

- Quoted `session-manager.ts:1421` in full, including the elided
  `sessionDir` branch.
- `redis-backend.ts:6-7` → full path, with the
  `buffered-redis-backend.ts` disambiguation.
- §6 names P6 as the deployment-model slice's realization and lists the
  three forward references it consumes; §9 adds MU1 and ADR-0033.

Two review details corrected in passing: `package-manager-cli.ts` lives at
`packages/coding-agent/src/`, not `src/core/`, and the `AuthStorage` spin
starts at `:76`.

Refs #239 #244
Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>

Signed-off-by: cwiklik <cwiklikj@gmail.com>
@pdettori pdettori mentioned this pull request Sep 22, 2026
Closed
pdettori added a commit that referenced this pull request Sep 28, 2026
@pdettori
feat(tui): session manager with remint, per-session queue and retries
9f6926d 
- Adds ActiveSession for managing per-session turn queue, token lifecycle, and retry logic
- Implements SessionManager for creating, resuming, and removing sessions
- Handles token remint with 30s margin before expiry
- Retries on token errors (invalid, expired) and 503 with Retry-After
- Never retries once frames have flowed (stream_truncated error continues queue)
- Reports turn-start, frame, retrying, and turn-end events
- Integrates with TranscriptStore for persistent turn history
- Review Focus #1 (truncated stream ends as error, queue continues) and
  #2 (token_expired remints once and succeeds) both tested and passing

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
@pdettori pdettori mentioned this pull request Oct 5, 2026
Merged
@ingpaolodettori-dev ingpaolodettori-dev mentioned this pull request Oct 7, 2026
Merged
4 of 5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@pdettori