commit - 9e7c6a00ad3350f4729ca4fdd20a230b8961eb87
commit + 99b06fce055e09aed16dc6ff082cde94778aeb83
blob - a4dfebc2d9945b992c6729ecd5a55fe48957ae9b
blob + f51a0c42845d8a8afb091612f756578a526f37eb
--- CONTEXT.md
+++ CONTEXT.md
_Avoid_: previous messages, cache index
**Compaction**:
-Replacing the active context with a model-written summary (`/compact`).
+Replacing an older Lead Projection prefix with model-written continuation
+notes, optionally retaining a provider-valid recent suffix (`/compact`).
_Avoid_: summarization (alone)
**Retained Projection**:
invocable as `/name` by the Owner or via the `skill` tool by the model.
**Project context**:
-`FUGU.md` (or `AGENTS.md`) plus personal `~/.fugu/FUGU.md`, injected
-into every projection; `#` lines append captures to the in-tree file.
+Personal `~/.fugu/FUGU.md` plus in-tree `FUGU.md` (or `AGENTS.md`), admitted
+at a System-epoch boundary and injected when current policy selects the full
+System baseline; `#` lines append captures to the in-tree file.
**Provider**:
A model route: the experimental Claude Subscription compatibility profile, or
blob - 7ddc31488bf00265d19486e8af61d54c51f615e9
blob + 6b49757fb26a23f949a702605c73ace91be74886
--- docs/adr/0008-immutable-system-epochs.md
+++ docs/adr/0008-immutable-system-epochs.md
other, while current Provider, Tool, credential, and authority configuration
remains live.
+`/clear` adopts the invocation's current base, reuses the Session-cached
+personal snapshot without re-reading it, and admits a new in-tree project
+snapshot only when `project_context yes`. Under `project_context no`, the new
+project snapshot is empty, the cached personal snapshot remains available in
+the stored full variant, and the restricted variant is selected. The boundary
+also empties Compaction notes, cumulative structured file sets, and any
+Retained Projection.
+
The epoch and its Projection reset form one atomic Journal unit. Automatic
Compaction may carry an exact Retained Projection in that same unit; when a
Turn is active, the unit remains provisional and replay applies it only with
the matching successful Turn terminal. This preserves ADR-0005's all-or-
nothing Turn transaction and cold Projection cursor across every cut.
+Structured file sets remain separate fields rather than being recovered by
+parsing model-written continuation notes.
## Rejected alternatives
blob - bdbbd99776166f2f853207fbc6392a1648aeeede
blob + a99ea2eb75e7a4bf509218bbe4179107f3db3f1e
--- docs/compaction.md
+++ docs/compaction.md
structured file details, and any retained Projection suffix are one Journal
record and are recovered together on resume.
+## System epoch policy
+
+Every successful Compaction carries forward the active epoch's exact base,
+personal, and project snapshots; it does not re-read external files or rebuild
+the baseline. The replacement epoch stores authoritative full and restricted
+System-baseline variants, the new continuation notes and cumulative structured
+file sets, and the exact Retained Projection. On resume, current
+`project_context` policy selects one stored variant without deleting or
+recomposing either. Current Provider, model, Tool, credential, protection,
+write, and network policy remains live.
+
+External context changes are admitted only at a fresh Session or `/clear`.
+`/clear` adopts the invocation's current base, reuses the Session-cached
+personal snapshot without re-reading it, and re-reads the in-tree project file
+only with `project_context yes`. With `project_context no`, it keeps the cached
+personal snapshot in the stored full variant, records an empty project
+snapshot, and selects the restricted variant. It also empties continuation
+notes, structured file sets, and the Retained Projection. A legacy Journal is
+not rewritten: its first resume appends and synchronizes one migration epoch
+before issuing a Provider request.
+
## Threshold and estimate
Automatic threshold Compaction runs only when the Effective window is known.
```
The default reserve is 16,384 tokens. An unknown window skips this threshold
-check. `auto_compact no` disables both threshold cuts and overflow recovery but
-does not disable `/compact`.
+check but leaves typed overflow recovery available. `auto_compact no` disables
+both threshold cuts and overflow recovery but does not disable `/compact`.
+When a known Effective window is not greater than the configured reserve, the
+prospective Generation fails with a configuration error instead of attempting
+an invalid cut.
## Cut selection
blob - 9f04ccad6deb8ee2f3161e583ab5b356683ae65e
blob + 5c4e7ae8ba683d1eb187c4cef11ea98330e06f34
--- docs/research/context-epochs.md
+++ docs/research/context-epochs.md
## Current Fugu inventory
+This inventory records the pre-adoption `e1da63b` implementation used as
+decision evidence. It is not a description of the post-ADR System-epoch
+implementation.
+
Fugu's canonical message vocabulary has only User and Assistant roles
([`msg.h`](../../src/common/msg.h#L23-L33)). The complete provider system
baseline, `sysfull`, is assembled from the configured or built-in base prompt,
|---|---|---|---|---|
| Built-in base system prompt | Compiled into `sysprompt.c` | No | No | New binary silently supplies new bytes ([source](../../src/fugu/sysprompt.c#L20-L46)) |
| Configured `system` prompt | At startup/resume config load | No | No | Current config silently supplies new bytes |
-| Personal context | Once at coordinator startup | No | Exact bytes in `context` record | Resume normally reuses snapshot; `project_context no` disables all external context ([resume](../../src/fugu/coord.c#L2689-L2733), [behavior](../../handoff/behavior.md#project-context-files)) |
+| Personal context | Once at coordinator startup | No | Exact bytes in `context` record | Resume normally reuses snapshot; `project_context no` suppresses external context from model requests ([resume](../../src/fugu/coord.c#L2689-L2733), [behavior](../../handoff/behavior.md#project-context-files)) |
| Project `FUGU.md` context | Fresh Session and `/clear` | Only on explicit `/clear` | Exact bytes in `context` record | Resume reuses snapshot; ordinary external edits are ignored |
| Compaction summary | On successful `/compact` | Replaced only by later success or clear | Exact bytes in `compact` record | Resume reuses summary ([compaction design](../compaction.md#completion-and-failure)) |
| Skill catalogue | Once at process startup | No | No | Current installed/configured catalogue and descriptions are used ([startup](../../src/fugu/coord.c#L4484-L4500), [loader](../../src/fugu/skills.c#L225-L264)) |
unjournaled historical base is unknowable and cannot be recovered.
Selecting the no-context variant must not destroy the stored external
-components. A later `/compact` updates both variants with the new summary;
-only `/clear` while context is disabled voids them, matching current replay.
+components. A later `/compact` updates both variants with the new summary.
+`/clear` reuses the Session-cached personal snapshot under either policy; with
+context disabled it records an empty project snapshot, keeps personal bytes in
+the stored full variant, and selects the restricted variant.
The record should include an encoding version; exact base, external context,
and summary components; and exact full and base-plus-summary variants. Both
| Base `system` text or built-in prompt | Both stored variants keep the epoch's pinned base; new Sessions use new text |
| Project context file | Keep Journaled bytes until Owner invokes `/clear` or starts a new Session |
| Personal context file | Keep Journaled bytes for this Session; `/clear` reuses them, and only a new Session reads the changed file |
-| `project_context no` | Select the stored exact base-plus-summary variant; this intentionally disables the mechanism entirely |
+| `project_context no` | Select the stored exact base-plus-summary variant; suppress external bytes from Lead/Subagent requests and capture without deleting the stored full variant |
| Provider/model default | Use current route by default; persistence of a user's explicit selection is a separate decision |
| Tool or skill installation | Use current available capabilities; successful past skill invocations remain in canonical history |
| Protect/write/network policy | Current Owner/Admin authority always wins |
blob - e560d830dc67656f1004feabeb8ea26b488f9cdb
blob + 869969cca76c2c94f1622d406a08b66b2ce55efd
--- handoff/behavior.md
+++ handoff/behavior.md
fresh conversation. The on-screen transcript stays as scrollback;
the journal is preserved and synchronizes one replacement System epoch so a
resume also starts fresh (§7). It adopts the invocation's current base,
- reuses the Session-cached personal bytes, re-reads project context under
- current policy, and drops Compaction notes and file details.
+ reuses the Session-cached personal bytes without re-reading them, and drops
+ Compaction notes, structured file details, and any Retained Projection. With
+ `project_context yes`, it re-reads the in-tree project context and selects
+ the new full baseline. With `project_context no`, it does not read the
+ in-tree file, records an empty project snapshot, retains the cached personal
+ bytes in the stored full baseline, and selects the restricted baseline.
- **/compact** — replace the active context with a model-written
summary of the conversation (one extra API call, no tools offered to
it). Serialize any prior Compaction notes and the active Projection as one
continuation notes. Prior notes remain quoted User data, never privileged
instructions. Fugu appends deterministic cumulative `<read-files>` and
`<modified-files>` blocks derived only from supported structured Tool calls;
- modified paths win and the Journal stores the sets separately from model
- prose. The complete replacement System epoch and Projection reset are
+ calls with failed Tool results still count because the lists describe
+ model-visible structured work, not audited filesystem outcomes. Modified
+ paths win and the Journal stores the sets separately from model prose. The
+ complete replacement System epoch and Projection reset are
synchronized together; resume carries them into later Compactions (§7). The
UI shows a distinct busy state. Automatic threshold cuts and one-shot
- overflow recovery use this same operation: a conservative prospective
+ overflow recovery use this same operation. Before every prospective Lead
+ Generation, including continuations after Tool results, a conservative
request estimate is compared strictly with Effective window minus
- `compact_reserve_tokens`, and whole recent Turns are retained up to
+ `compact_reserve_tokens`; an unknown window skips only this threshold path.
+ A known window no greater than the reserve is a configuration error.
+ Whole recent Turns are retained up to
`compact_keep_tokens`. An oversized current Turn may split only at a
Provider-valid boundary with every Tool call/result pair intact; its early
prefix is separately delimited as `<turn-context>`.
### Project context files
-For a new Session, fugu reads the first of `FUGU.md` then `AGENTS.md` in the
-working directory, plus the personal `~/.fugu/FUGU.md`, each capped
-at 64 KiB — an oversize, NUL-bearing, or `protect`-listed file is
-skipped with a one-line notice, like skills. The contents are
-injected into every projection alongside the system prompt, personal
-file first, then project file; they compose with the `system` key,
-never replace it. After each `/clear` the in-tree file is re-read by
-the tool-executing role over the existing IPC (so no role widens,
-I9); the personal file's bytes are cached at startup and reused —
-it is never re-read mid-session. The injected bytes are recorded in
-the journal inside a complete System epoch so a resumed session replays the
-exact stored baseline variant and snapshots (invariants.md I14) even if the
-files, configured `system`, or composition code have since changed,
-and the injection position must not create adjacent same-role
-messages. The files are read by roles that already hold the needed
-filesystem access — never the credential custodian (I1); the `#`
-capture line (§3) is the write-side companion. On resume, current
-`project_context yes` selects the stored full baseline; `no` selects the stored
-base-plus-Compaction variant and suppresses stored external bytes from
-Subagents and capture without deleting them. A later resume may select the
-other stored variant. External edits and capture do not mutate the live epoch;
-only `/clear` or a new Session admits them. The manual's CAVEATS must state
-that starting fugu in an untrusted tree injects that tree's
+With `project_context yes`, a new Session reads the personal
+`~/.fugu/FUGU.md` and the first of in-tree `FUGU.md` then `AGENTS.md`, each
+capped at 64 KiB — an oversize, NUL-bearing, or `protect`-listed file is
+skipped with a one-line notice, like skills. With `project_context no`, a new
+Session reads neither external file. Admitted contents are injected alongside
+the system prompt, personal file first, then project file; they compose with
+the `system` key, never replace it. The personal snapshot is cached for the
+Session and never re-read mid-session. On `/clear`, that cached snapshot is
+always reused; the in-tree file is re-read by the tool-executing role only
+under `project_context yes` (so no role widens, I9), and otherwise the new
+project snapshot is empty. The admitted bytes are recorded in the journal
+inside a complete System epoch so a resumed session replays the exact stored
+baseline variant and snapshots (invariants.md I14) even if the files,
+configured `system`, or composition code have since changed, and the injection
+position must not create adjacent same-role messages. The files are read by
+roles that already hold the needed filesystem access — never the credential
+custodian (I1); the `#` capture line (§3) is the write-side companion. On
+resume, current `project_context yes` selects the stored full baseline; `no`
+selects the stored base-plus-Compaction variant and suppresses stored external
+bytes from Subagents and capture without deleting them. A later resume may
+select the other stored variant. External edits and capture do not mutate the
+live epoch; only `/clear` or a new Session admits them. The manual's CAVEATS
+must state that starting fugu in an untrusted tree injects that tree's
instructions into the model's context (invariants.md §4).
## 5. Tools
| `context_limit` *number* | first-priority Effective-window override for /context, the status gauge, and automatic Compaction (§3) [unset] |
| `auto_compact` yes\|no | enable prospective threshold Compaction and one-shot typed overflow recovery [yes] |
| `compact_reserve_tokens` *number* | tokens reserved below the Effective window before automatic Compaction [16384] |
-| `compact_keep_tokens` *number* | target size of the valid recent Projection suffix retained by Compaction [20000] |
+| `compact_keep_tokens` *number* | target size of the valid recent Projection suffix retained by automatic Compaction [20000] |
| `allow_write` yes\|no | offer mutating file tools [yes] |
| `allow_subprocess_net` yes\|no | widen subprocess exec ceiling with network [no] |
| `web_search` yes\|no | offer web_search + web_fetch [yes] |
| `subagent_model` *string* | model id subagents use by default [unset: the lead's active model]; joins the agent tool's per-call palette (§5.12) |
| `subagent_provider` *string* | name of a configured provider block (or the implicit default) whose route and credential `subagent_model` is resolved against [the lead's active provider] |
| `max_bg_jobs` *number* | concurrent background shell jobs; 0 withholds shell_bg/shell_output/shell_kill [4] |
-| `project_context` yes\|no | read and inject FUGU.md/AGENTS.md project context (§4) [yes] |
+| `project_context` yes\|no | select the full or restricted stored System baseline; on a new Session, `yes` admits personal and FUGU.md/AGENTS.md context (§4) [yes] |
| `protect` *string* | whitespace-separated paths or glob(3) patterns relative to the working directory, expanded once at startup, that every tool-executing role unveils with empty permissions before touching untrusted input — contents kernel-unreachable (ENOENT-shaped error) by every tool, subprocess, and subagent, though names may remain visible in listings (invariants.md I5/I9); protecting a directory covers its subtree |
| `notify` yes\|no | terminal bell when a turn completes (curses interface only) [yes] |
| `ascii` yes\|no | ASCII-transliterated interface [no] |
and assistant messages (including tool exchanges), plus one versioned,
binary-safe System-epoch record at fresh start, clear, successful Compaction,
and legacy migration. An epoch owns exact base/personal/project/summary
- components, authoritative full and restricted Lead baselines, structured file
- sets, and an explicit retained Projection snapshot. New reset writers never
- split that state across independently replayable records.
+ components, authoritative full and restricted Lead baselines, cumulative
+ structured file sets, and an explicit retained Projection snapshot. New
+ reset writers never split that state across independently replayable
+ records.
- Undispatched Queue entries (§2.1) are process-local interface state
and are never Journaled. `turn_txn_accept` provisionally appends the
records for messages accepted into the Pending Projection, including
abandoned turns contributing nothing. In particular the projection
sent to the provider after a resume must be one the provider
accepts (no orphaned tool calls, no adjacent same-role messages).
-- Resume selects an already stored exact baseline with current
- `project_context` policy; Provider/model routes, credentials, Tools, skills,
- endpoints, protection, write, and network authority remain live. Legacy
- journals are never rewritten: the first resume reconstructs under old rules
- and appends one synchronized migration epoch before any Provider request.
+- Resume selects the already stored exact full or restricted baseline with
+ current `project_context` policy and preserves the unselected variant;
+ Provider/model routes, credentials, Tools, skills, endpoints, protection,
+ write, and network authority remain live. Legacy journals are never
+ rewritten: the first resume reconstructs under old rules and appends one
+ synchronized migration epoch before any Provider request.
- `/clear` and `/compact` never truncate the file; they append.
- Full journals remain the Owner's plain files; the manual documents
that running fugu from `$HOME` lets the tools read them (CAVEATS).
reruns an already completed Tool batch, recurses through the summarizer, or
retries a second overflow. Status alone, English prose, HTTP 413,
Anthropic `invalid_request_error`, and Claude Subscription errors are not
-classified. Unknown or post-content errors retain the terminal behavior above.
+classified. Unknown or post-content errors, cancellation, Compaction failure,
+and overflow of the summarization request retain the terminal behavior above.
+Usage from the Compaction Generation and retry remains additive.
The built-in system prompt (sent when `system` is unset) must be
concise and cover: fugu's identity as a terminal coding agent on a
blob - e8dc8af05dd5e68f18edd1cb227218ba2d2000be
blob + dd440dd3ce0bf21827d538c554f32c351fbc1b74
--- handoff/invariants.md
+++ handoff/invariants.md
leaves no partial records that a later resume would replay. Resuming
a session yields precisely the conversation state the Owner last saw
after the most recent successful turn. Every reset boundary is one
- versioned, binary-safe System epoch containing exact authoritative baseline
- variants, source snapshots, Compaction/file state, and any retained
- Projection. A cut inside an active Turn is replayable only with that Turn's
- matching successful terminal; a crash or abandonment preserves the prior
- epoch and Projection. Resume selects stored privileged bytes rather than
- rebuilding them from current configuration, files, or code. Legacy migration
- is additive and synchronized before the first resumed Provider request.
+ versioned, binary-safe System epoch containing exact authoritative full and
+ restricted baselines, source snapshots, Compaction notes, cumulative
+ structured file sets, and any Retained Projection. `/clear` adopts the
+ current base and cached personal snapshot even when the restricted baseline
+ is selected, reads project context only when current policy permits it, and
+ atomically clears the notes, file sets, and Projection. A cut inside an
+ active Turn is replayable only with that Turn's matching successful
+ terminal; a crash or abandonment preserves the prior
+ epoch and Projection. Resume uses current `project_context` policy to select
+ one exact stored baseline without deleting the other; it never rebuilds
+ privileged bytes from current configuration, files, or code, while current
+ Provider, Tool, credential, and authority policy remains live. Legacy
+ migration is additive and synchronized before the first resumed Provider
+ request.
(This is also a behavioral requirement; see behavior.md §7.)
### Subagents (new in this version)
blob - 11d176d1a06ecbfebfc9c7962c7f99e5ff6281bc
blob + 5364cf067c69941889e8ca1f030a52d1179585d6
--- handoff/verification.md
+++ handoff/verification.md
equivalents, and the resolved-address (not name) property.
- **Subagent bounds (I15):** concurrency cap honored, nesting refused,
read-only proof per §2, cancellation kills the set.
-- **Project context:** injected bytes journaled and replayed verbatim
- across resume (I14), including after `/clear` re-reads and after
- the file changes on disk mid-session; oversize and NUL-bearing
- files skipped; `#` capture appends atomically and is refused under
- `allow_write no`.
+- **Project context:** admitted bytes journaled and replayed verbatim across
+ resume (I14), including after the files change on disk mid-session. A fresh
+ Session under `project_context no` reads neither external file. `/clear`
+ under `yes` reuses cached personal bytes and re-reads the in-tree file;
+ under `no` it still preserves cached personal bytes in the stored full
+ variant, records an empty project snapshot, and selects the restricted
+ variant. Oversize and NUL-bearing files are skipped; `#` capture appends
+ atomically and is refused under `allow_write no`.
- **System epochs (I14):** binary-safe round trips cover every component,
- authoritative full/restricted variant, reason, structured file array, and
- retained Projection block. Fresh start, clear, successful Compaction, and
- legacy migration synchronize before request/publication. Unsupported,
+ authoritative full/restricted variant, reason, cumulative structured file
+ sets, and retained Projection block. Fresh start, clear, successful
+ Compaction, and legacy migration synchronize before request/publication.
+ Unsupported,
missing, duplicate, inconsistent-derived, over-bound, and malformed fields
hard-fail; a partial final epoch is ignored and retried. Cross-process
fixtures change base configuration, context files, composition code,
across repeated and resumed Compactions, and exercise post-JSON expansion
past the request cap without changing the Projection. Rejected Provider
Generations separately prove the Projection and cache cursor stay paired.
- Prefix planning covers strict threshold boundaries, unknown windows,
- prospective System/Projection/Tool estimates, whole recent Turns, giant-Turn
- safe splits, complete multi-Tool result sets, and no-safe-cut fallback.
- Structured file tests cover cumulative resume/recompact, read-to-modified
- promotion, sorting/deduplication, supported-call-only collection, forged
- paths, empty blocks, failed Tool results, and failure/cancellation rollback.
+ Prefix planning covers strict `>` threshold boundaries before both initial
+ and post-Tool Lead Generations, unknown-window threshold suppression with
+ recovery still enabled, rejection when a known window is no greater than the
+ reserve, prospective System/Projection/Tool estimates, whole recent Turns,
+ giant-Turn safe splits, complete multi-Tool result sets, and no-safe-cut
+ fallback. Structured file tests cover cumulative resume/recompact,
+ read-to-modified promotion, bytewise sorting/deduplication,
+ supported-call-only collection, forged prose paths, malformed and invalid
+ path arguments, XML escaping, empty blocks, failed Tool results, and
+ failure/cancellation rollback.
- **Context meter:** the effective-window resolution order
exercised (`context_limit`, provider-reported, compiled table,
unknown); `/context` leaves the journal byte-identical; the status count
blob - 80eced6a1f837288c640a3b7eada48b2e5c68fba
blob + 1b6cf613204415247ca5af0d8ce5d28da80d2032
--- src/fugu/fugu.1
+++ src/fugu/fugu.1
.It Cm /clear
Reset the active model context while retaining the displayed transcript and
append-only journal.
-The in-tree project context file is read again and a new immutable System
-epoch adopts the current configured or built-in base prompt.
+A new immutable System epoch adopts the current configured or built-in base
+prompt and reuses the Session-cached personal-context snapshot without reading
+it again.
+With
+.Cm project_context yes ,
+the in-tree project context is read again and the full baseline is selected.
+With
+.Cm project_context no ,
+the in-tree file is not read, the new project snapshot is empty, the cached
+personal snapshot remains in the stored full baseline, and the restricted
+baseline is selected.
+Compaction notes, structured file details, and any retained Projection are
+emptied.
.It Cm /compact
Ask the model to replace the active conversation with continuation notes
that preserve goals, constraints, decisions, work state, important paths,
and open questions.
The summary and deterministic read/modified file lists are journaled in a new
System epoch and become resumable context.
+The lists accumulate supported structured
+.Cm read , write , edit ,
+and
+.Cm multi_edit
+calls across repeated and resumed Compactions; modified paths win over
+read-only paths when their containing Projection prefix is summarized.
+A call still counts when its Tool result reports failure, so the lists describe
+model-visible structured work rather than audited filesystem outcomes.
Automatic Compaction uses the same operation; see
.Xr fugu.conf 5 .
.It Cm /model
tool.
.
.Pp
-Unless
-.Cm project_context no
-is configured,
+For a new Session with
+.Cm project_context yes ,
.Nm
-loads the first of
+loads personal
+.Pa ~/.fugu/FUGU.md
+and the first of in-tree
.Pa FUGU.md
and
-.Pa AGENTS.md
-from the current directory, followed by
-.Pa ~/.fugu/FUGU.md .
+.Pa AGENTS.md .
+With
+.Cm project_context no ,
+neither external file is read.
Each is limited to 64 KiB and protected, oversized, or NUL-bearing files are
skipped with a notice.
-Personal context is cached at startup; in-tree context is refreshed after
-.Cm /clear .
-The exact injected bytes are journaled so a resumed session sees the same
-context even if the files later change.
+An admitted personal snapshot is cached for the Session and is never read
+again.
+On
+.Cm /clear ,
+it is reused under either policy; in-tree context is refreshed only with
+.Cm project_context yes
+and is otherwise recorded as empty.
+The exact full and restricted baselines and their source snapshots are
+journaled.
+On resume, current
+.Cm project_context
+policy selects one exact stored baseline without rebuilding it or deleting the
+other, even if external files, configured system text, or composition code have
+changed.
.
.Sh MODEL TOOLS
The model is always offered bounded tools for reading files, running
Other HTTP 4xx responses and failures after streaming begins end the turn.
Provider and TLS error details are shown to the Owner without exposing
credentials.
-When automatic Compaction is enabled, one OpenAI-compatible error whose exact
-structured code is
+When automatic Compaction is enabled, one OpenAI-compatible HTTP 400 response
+or stream error whose exact structured code is
.Li context_length_exceeded
may Compact and retry the rejected Generation once, but only before any
Provider content was accepted.
HTTP status or English prose alone, direct Anthropic errors, Claude
Subscription errors, and HTTP 413 byte limits do not trigger recovery.
+The retry does not rerun a completed Tool batch.
+A second overflow, an overflow from the Compaction Generation, cancellation,
+Compaction failure, or any post-content error ends the Turn without another
+recovery attempt.
+Usage from Compaction and the retried Generation remains additive.
.
.Sh SESSIONS
Every session has an append-only, mode-0600 journal in
A complete versioned System epoch is synchronized before the first Provider
request and at every clear or successful Compaction boundary.
It preserves exact full and no-project-context Lead baselines, source
-snapshots, structured file details, and any retained Projection suffix.
+snapshots, cumulative structured file details, and any retained Projection
+suffix.
A resumed invocation selects one stored baseline using current
.Cm project_context
-policy; it does not rebuild the baseline from current files, configuration,
-or binary composition code.
+policy and preserves the unselected variant; it does not rebuild either
+baseline from current files, configuration, or binary composition code.
+Current Provider, model, Tool, credential, protection, write, and network
+policy remains live.
A legacy journal gains one additive migration epoch before its first resumed
request and is never rewritten.
A failed, cancelled, or abandoned turn contributes no partial conversation
blob - bbc3a96f14f004077b95fe4bca03b4954f3b0adf
blob + a000bbc4683efe3a74d6065cec597be2264d370b
--- src/fugu/fugu.conf.5
+++ src/fugu/fugu.conf.5
Automatically Compact the Lead Projection before a Generation when its
estimated size exceeds the Effective window less
.Cm compact_reserve_tokens .
-When enabled, a recognized Provider context-overflow rejection may also
-Compact and retry the rejected Generation once.
+The comparison is strict and runs before every prospective Lead Generation,
+including continuations after Tool results.
+An unknown Effective window skips this threshold path.
+If a known Effective window is not greater than
+.Cm compact_reserve_tokens ,
+the prospective Generation fails with a configuration error rather than
+attempting a cut against an invalid threshold.
+When enabled, an OpenAI-compatible HTTP 400 response or stream error whose
+exact structured
+.Li error.code
+is
+.Li context_length_exceeded
+may also Compact and retry the rejected Generation once, provided no Provider
+content was accepted.
+The recovery remains available when the Effective window is unknown.
+It retries only that Generation, never a completed Tool batch; Compaction and
+retry usage remains additive.
+A second overflow, an error after content, an overflow from the Compaction
+Generation, cancellation, or Compaction failure does not retry again.
+Status or English prose alone, HTTP 413, Anthropic errors, and Claude
+Subscription errors do not qualify.
With
.Ic no ,
neither automatic path runs;
The default is
.Ic yes .
.It Cm compact_keep_tokens Ar tokens
-Set the target size of the recent Projection suffix retained by automatic and
-manual Compaction.
+Set the target size of the recent Projection suffix retained by automatic
+Compaction.
The value must be between 1 and 1000000000.
The default is 20000.
.It Cm compact_reserve_tokens Ar tokens
Reserve this much of the Effective window when deciding whether to Compact
before a Lead Generation.
+It must be smaller than any known Effective window used for that Generation.
The value must be between 1 and 1000000000.
The default is 16384.
.It Cm context_limit Ar tokens
.Ic yes .
This has no effect in line or print mode.
.It Cm project_context Ic yes | no
-Load and journal personal and in-tree project context and permit
+For a new Session,
+.Ic yes
+loads and journals personal and in-tree project context and permits
.Sq #
-capture.
+capture;
+.Ic no
+reads neither external file and disables capture.
+On resume, the current value selects the exact stored full or restricted
+System baseline without rebuilding either or deleting the unselected variant.
+On
+.Cm /clear ,
+the Session-cached personal snapshot is retained without being read again.
+With
+.Ic yes ,
+the in-tree file is read again and the full baseline is selected;
+with
+.Ic no ,
+the project snapshot is empty, the cached personal snapshot remains in the
+stored full baseline, and the restricted baseline is selected.
The default is
.Ic yes .
.It Cm protect Ar patterns
