sliceagent 0.1.15__tar.gz → 0.2.0__tar.gz

{sliceagent-0.1.15 → sliceagent-0.2.0}/.gitignore

@@ -27,6 +27,9 @@ scratch/
 evals/prompt_ab/variants/
 evals/prompt_ab/runs/
 
+# internal design doc — kept local, not published to the repo or the sdist
+CORE-DESIGN.md
+
 # local sliceagent state / monitor runtime (personal; not part of the repo)
 .sliceagent/
 .memagent/          # legacy pre-rename state dir (ignore so an upgraded checkout stays clean)

{sliceagent-0.1.15 → sliceagent-0.2.0}/CHANGELOG.md

@@ -5,6 +5,119 @@ this project aims for [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-07-10
+
+A typed re-architecture of the core around a single canonical design (elastic slice, execution kernel,
+crash-safe persistence), plus a rebuilt Rich TUI. No change to the thesis — same history-bounded,
+task-elastic slice — but the invariants are now enforced by typed subsystems rather than convention.
+
+### Added
+- **Typed core kernel.** The active slice is split into typed semantic regions (intent, task, evidence,
+  working set, continuity, turn runtime), each owning its own seal/reset lifecycle, replacing the flat
+  field-classification table. A provenance-tagged **intent ledger** captures verbatim user directives with
+  their source handles, deterministically promotes explicit constraint language (`must`/`never`/`only`),
+  and records supersession/satisfaction as explicit transitions.
+- **Execution kernel.** Structured tool outcomes (succeeded/failed/cancelled/**indeterminate**), ordered
+  read/write waves (pure reads parallel, effects as barriers), reconciliation gates that block dependent
+  actions after an unprovable outcome, and one capacity-preflighted model-call path.
+- **Crash-safe persistence.** A pending-journal → immutable-artifact → checkpoint compare-and-swap commit
+  order with idempotent replay, a full error taxonomy, and an OS-backed workspace lease, so an interrupted
+  turn resumes without re-running side effects. Dependency-scoped workspace revisions stale only the claims
+  whose inputs actually changed.
+- **Rebuilt TUI.** A single `TurnProgress` event reducer folds loop events into an immutable snapshot;
+  the renderer projects that snapshot (semantic tool buckets, bounded plan/tally, width-responsive
+  diagnostics, one live-status owner) instead of interpreting events independently.
+
+### Changed
+- Elastic residency is centralized: a pressure controller chooses graded fidelity globally
+  (full → excerpt → digest → locator) so no region can consume the window unnoticed.
+- Per-turn cost framing corrected throughout the docs to **history-bounded, task-elastic** — bounded with
+  respect to session length, not a fixed size regardless of task breadth.
+
+### Fixed
+- **Intent ledger and progress signals no longer lost on resume.** Checkpoint state is deep-frozen on
+  write; the resume and crash-recovery paths now thaw it fully at the boundary (and the deserializers
+  accept any `Mapping`), so binding user directives and their provenance survive a restart instead of
+  being silently dropped.
+- **A completed first-turn objective no longer stays pinned as a mandatory, un-pageable block** — a clean
+  turn with no unresolved state marks it pageable background; unresolved state or explicit continuation
+  keeps it active.
+- Security/reliability hardening from external review: WAL/recovery redacts tool-call arguments; process
+  kill reaps the whole spawn-captured process group; `code_review` and the read-only git policy refuse
+  external-diff/textconv and config injection; subagent children charge their tokens to the parent budget,
+  stay isolated from the parent's private state, and write durable state 0600/0700.
+
+## [0.1.18] — 2026-07-09
+
+### Added
+- **The standing roster is now visible** to the agent — a bounded STANDING SPECIALISTS manifest in the slice
+  advertises your named specialists (and the `read_file("roster/index.md")` / wake calls), so a fresh
+  session discovers them instead of never finding the feature. The roster read is bounded-work (rank by a
+  cheap stat, parse only the top-K), so it stays flat per turn as the roster grows.
+- **A calibrated `reviewer` agent kind** — a read-only, parallel reviewer whose prompt enforces a severity
+  rubric and four anti-cry-wolf disciplines (read the adjacent comment, trace tainted data to its real
+  consumer, single-user-local threat model, refute your own finding). `spawn_agent(agent="reviewer", …)`.
+
+### Changed
+- **One delegation tool.** `spawn_explore` / `spawn_subagent` are collapsed into `spawn_agent(agent=<kind>,
+  name?, grants?)` (measured parallel-fan-out parity). The delegation mental model is rewritten around two
+  orthogonal dials — the KIND (`agent=`) and the IDENTITY (`name=` → omit for a one-shot temp, pass to HIRE
+  a standing specialist you can WAKE later). Old tool names still work.
+- **No roster hire cap.** A dormant specialist is just files on disk; the bound is on the surfaced view, not
+  the stored count.
+
+### Fixed
+- **Streaming hard-deadline** is re-raised (not downgraded to a partial truncation) so a wall-clock stall is
+  actually retried.
+- **Auto-approve safety:** a broad `AGENT_AUTO_APPROVE` glob no longer silently approves `git push`, package
+  publishes, or `rmdir` — they fall through to a confirmation.
+- Delegation guidance is spliced into the system prompt again (its gate keyed on a removed tool); a path
+  auto-grant no longer trips on version-shaped tokens; ripgrep subprocesses decode as UTF-8; a topic-park
+  failure no longer masquerades as "no such topic"; an unknown scheduler access type serializes safely; the
+  virtual roster FS resolves `profile.json` as well as `profile.md`.
+
+## [0.1.17] — 2026-07-09
+
+### Added
+- **Standing specialist roster — hire once, wake many.** A named delegation
+  (`spawn_agent`/`spawn_explore` with `name="…"`) now HIRES a durable specialist; re-using the name WAKES
+  it, rehydrated from its own sealed archive at flat cost regardless of career length (identity is an
+  archive key, not a running process). A woken specialist is seeded with a bounded identity block: its
+  recent career manifest, its lessons, and an abstention self-model ("your memories are only your sealed
+  reports — say so beyond them"). The hippocampus now records who your agent works with, what they were
+  told, and what they found.
+- **Instance identity + verbatim-brief provenance.** Every sealed artifact carries the instance `name` and
+  the exact brief it was given, so a report's reader always sees the question alongside the answer;
+  `subagents/index.md` is the roster and `subagents/<name>.md` aliases a specialist's latest job.
+- **Capability grants.** A parent wires one child's sealed report to another by granting an exact handle in
+  the brief — default-deny, one-hop (no re-grant), spawn-time existence-checked — so children still couple
+  only through seals.
+- **Synthesiser agent + lessons + searchable delegated work.** A read-only `synthesiser` kind reduces N
+  granted sibling reports into one cited synthesis; a seal-time `LESSON:` reflection is curated into the
+  specialist's profile (deduped, capped, provenance-tagged); and delegated work is dual-written to the FTS5
+  index so `search_history` finds it by content without touching the turn timeline.
+
+### Fixed
+- **Race-safe hire + durable-store hardening.** Concurrent same-name hires are atomic (in-process lock +
+  `O_EXCL` create + cap enforced under the lock), profile writes are atomic (tmp + `os.replace`), and the
+  roster tolerates corrupt/legacy records (null date fields no longer crash the wake seed or the roster
+  listing) — surfaced and fixed across three adversarial bug-hunt rounds.
+
+## [0.1.16] — 2026-07-08
+
+### Added
+- **Subagent structured artifacts.** A delegated child now seals a typed report into a `subagents/`
+  archive and hands the parent a bounded digest plus a `read_file("subagents/sub-N.md")` recall handle —
+  the cache-not-log moat applied to delegation. The parent absorbs O(1)-sized digests while the child's
+  full detail stays paged out on disk yet fully recallable (manifest at `subagents/index.md`, per-child
+  reports, grep). Ids are assigned race-safely under concurrent fan-out, secrets are redacted on persist,
+  and a child is isolated from the parent's `history/`, siblings' `subagents/`, and `search_history`.
+
+### Fixed
+- **FileLock flush-before-release.** The advisory lock now flushes buffered writes before releasing the
+  lock, so a concurrent appender counting lines can't race a half-written file (surfaced by parallel
+  subagent fan-out).
+
 ## [0.1.15] — 2026-07-08
 
 ### Added

{sliceagent-0.1.15 → sliceagent-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sliceagent
-Version: 0.1.15
+Version: 0.2.0
 Summary: A coding agent with a new context-engineering framework: bounded, deterministic, reconstructed context (slice architecture) — built for long-horizon work.
 Author: TT-Wang
 License-Expression: MIT
@@ -34,15 +34,15 @@ Description-Content-Type: text/markdown
 
 [![CI](https://github.com/TT-Wang/sliceagent/actions/workflows/ci.yml/badge.svg)](https://github.com/TT-Wang/sliceagent/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/sliceagent.svg)](https://pypi.org/project/sliceagent/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
 
-> **A coding agent that reconstructs a small, exact working context every turn — instead of accumulating a chat transcript and summarizing it when it overflows.**
+> **A coding agent that reconstructs a history-bounded, task-elastic working context every turn — instead of accumulating a chat transcript and summarizing it when it overflows.**
 
-That one change is the whole product. Because context is rebuilt from ground truth each turn rather than piled up:
+That one change is the whole product. Because context is reconstructed from active semantic state and live ground truth each turn rather than piled up:
 
-- **Cheap at scale** — per-turn input stays flat no matter how long the session runs; no grow-to-window sawtooth, so tokens (and cost) don't balloon on long tasks.
-- **Less wall-clock** — a small, stable prompt each turn means less to send and less to reason over; long, iterative work finishes faster.
-- **No context rot, no compaction** — every turn re-reads the live files and the last error verbatim, so nothing drifts into a lossy summary and there is no history to compact.
+- **History-bounded cost** — when active task state stays stable, per-turn input does not grow merely because the session is older; there is no transcript-driven grow-to-window sawtooth.
+- **Task-elastic focus** — simple tasks stay lean, while real user constraints, coupled files, and unresolved evidence can expand the working slice when needed.
+- **Recoverable live state** — every turn re-observes relevant workspace state and faithfully carries current failures; retired detail pages out behind stable handles instead of forcing routine transcript compaction.
 
-The field's default is *bigger windows + summarize*. sliceagent does the opposite: **remember less, reconstruct precisely.**
+The field's default is *bigger windows + summarize*. sliceagent does the opposite: **carry what remains active; archive and recover the rest.**
 
 *Pre-1.0: on `0.x`, CLI flags, config keys, and APIs may change between releases; breaking changes are noted in the [CHANGELOG](CHANGELOG.md).*
 
@@ -52,17 +52,17 @@ The field's default is *bigger windows + summarize*. sliceagent does the opposit
 
 <p align="center">
   <img src="assets/sliceagent-core-loop.gif" width="840"
-       alt="The core loop: a transcript agent re-sends its entire growing history every turn (208k to 1.66M tokens over 6 turns), while sliceagent rebuilds a fixed-size seed from the carried slice, live files, and lessons, then seals each turn to disk, and the hippocampus pages past turns back into future seeds on demand — peak input stays ~12-15k, 112x smaller by turn 6. Real per-turn numbers from the s1 benchmark.">
+       alt="The core loop: a transcript agent re-sends its entire growing history every turn (208k to 1.66M tokens over 6 turns), while sliceagent rebuilds a history-bounded, task-elastic seed from the carried slice, live files, and lessons, then seals each turn to disk, and the hippocampus pages past turns back into future seeds on demand — peak input stayed ~12-15k in the s1 benchmark, 112x smaller by turn 6.">
 </p>
 
-sliceagent's memory is organized like a brain: fast, lossy **perception** of the live world; a small **working memory** for the current task; a **hippocampus** that records what just happened; and a **neocortex** that distills durable lessons. Every turn *reconstructs* a bounded working set from these — it never replays a growing transcript.
+sliceagent's memory is organized like a brain: fast, lossy **perception** of the live world; an elastic **working memory** for the current task; a **hippocampus** backed by always-on local artifacts; and an optional **neocortex** that derives durable lessons. Every turn *reconstructs* a history-bounded working set from these — it never replays a growing transcript.
 
 | Region | Role |
 |---|---|
-| **Sensory cortex** — live perception | Re-derives the world each turn: git state, project facts, repo map. Never stored or recalled. |
-| **Prefrontal cortex** — working memory | The carried **Slice**: bounded, provenance-tagged state (findings, plan, change-set), sealed at each turn boundary. |
-| **Hippocampus** — episodic memory | Losslessly records each turn; pages a specific past turn back in on demand. |
-| **Neocortex** — long-term memory | Distills successful episodes into durable cross-session lessons, auto-surfaced when relevant. |
+| **Sensory cortex** — live perception | Re-derives the world each turn—git state, project facts, repo map—rather than trusting remembered copies. |
+| **Prefrontal cortex** — working memory | The carried **Slice**: task-elastic, provenance-tagged state (intent, findings, plan, change-set), sealed at each turn boundary. |
+| **Hippocampus** — episodic memory | Seals each turn or child report into the always-on local artifact store; pages a specific record back in on demand. |
+| **Neocortex** — long-term memory | Optionally derives and retrieves provenance-tagged cross-session lessons; it is not required for task recovery. |
 
 ```text
 ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
@@ -83,20 +83,20 @@ sliceagent's memory is organized like a brain: fast, lossy **perception** of the
                          └───────────────────────────────────┘
                                            ▼
                       ┌─────────────────────────────────────────┐
-                      │   PFC updated · turn sealed to memory   │
+                      │  PFC updated · turn sealed to artifact  │
                       └─────────────────────────────────────────┘
 
-  ↻  next turn: only the PFC slice carries forward —
-     everything else re-derives live from disk.
+  ↻  next turn: the active slice remains resident;
+     live views re-derive, archived detail returns by handle.
 ```
 
-Each turn faults in exactly what the turn references — the carried slice, live views, and any relevant lessons — and hands the model that bounded **Seed**. The model acts; observations fold back into working memory; at the turn boundary the episode is sealed into the hippocampus; on success the neocortex distills a durable lesson. Net effect: **per-turn context stays flat no matter how long the session runs.**
+Each turn faults in what the active task references — the carried slice, live views, selected artifacts, and any relevant derived lessons — and hands the model an elastic **Seed**. The model acts; observations fold back into working memory; at the turn boundary the episode is sealed into an immutable local artifact and the next checkpoint is published. If semantic memory is available, it may additionally distill a durable lesson. Net effect: **for stable active task state, context does not grow merely with session age; it can still expand with genuine task complexity.**
 
 ## Benchmark
 
 On public benchmarks, sliceagent matches Codex's solve rate while using 2.5× fewer tokens and 1.3× less cost on ColBench, and up to 149× smaller peak input on long sessions.
 
-Two questions decide whether reconstructing context every turn actually works: does it stay as **capable** as a transcript agent, and does it keep **per-turn cost flat** as a session grows? All three benchmarks are head-to-head vs **OpenAI Codex** on the same model (`gpt-5.5`).
+Two questions decide whether reconstructing context every turn actually works: does it stay as **capable** as a transcript agent, and does it keep **per-turn cost history-bounded as the session grows** — sized to the current task, not the accumulated history? All four benchmarks are head-to-head vs **OpenAI Codex** on the same model (`gpt-5.5`) — the fourth adds a third question: what does it cost to *orchestrate a subagent fleet*.
 
 ### 1. In-turn capability — Terminal-Bench 2.0 (public)
 
@@ -145,7 +145,7 @@ Iterative coding sessions where a transcript really piles up. Each scenario is a
 | wall · total | **1,069s** | 1,761s | **61%** |
 | **cost** (cache-aware $) | **$1.30** | $9.43 | **14%** |
 
-Per task — note how the transcript agent's peak input scales with the session while the slice stays flat:
+Per task—the transcript agent's peak input scales with the session while the slice remained within a narrow band in these runs:
 
 | scenario | agent | solved | peak input | total tokens | wall |
 |---|---|:--:|--:|--:|--:|
@@ -158,6 +158,32 @@ Per task — note how the transcript agent's peak input scales with the session
 
 Same capability — **109–149× smaller peak context, 11.7× fewer tokens, 7.3× cheaper, 1.6× faster.** On `s3`, Codex's transcript reached a **2.44M-token** single-request peak while sliceagent held **16k** — a 149× gap that **widens the longer the session runs.**
 
+### 4. Subagent fan-out — hosting a delegation fleet ([`benchmarks/subagent_fanout.py`](benchmarks/subagent_fanout.py))
+
+A ColBench-style human-sim (a staff engineer) **explicitly tells both agents to fan out** — one explorer subagent per module across a 6-module service — then asks four parent-only follow-ups: a 6-turn session, 2 fan-out turns + 4 follow-ups. Codex `exec` ships its **own** `spawn_agent` primitive, so **both agents genuinely delegate.** The question isn't who *can* delegate; it's what the **orchestrator** pays to run a fleet. Both `gpt-5.5` at `high`; each agent's own subagent tokens are counted — Codex's child threads recovered from its session rollouts — for a true total-vs-total. **N = 3 runs, mean [min–max]:**
+
+| metric | sliceagent | OpenAI Codex | % of Codex |
+|---|--:|--:|:--:|
+| subagent spawns | 14 | 11.7 | both fan out |
+| **orchestrator peak** (largest single request) | **17,362** [15.7k–20.3k] | 362,595 [332k–387k] | **4.8%** |
+| delegated · own children | 341,515 | 568,027 | 60% |
+| **true total** (orchestrator + children) | **610,612** [536k–656k] | 2,235,243 [2.11M–2.32M] | **27%** |
+
+Per turn (mean of 3 runs) — the orchestrator's context is what caps how large a fleet you can keep running:
+
+| turn | sliceagent orchestrator | OpenAI Codex orchestrator |
+|---|--:|--:|
+| 1 · fan-out | 37,191 | 119,397 |
+| 2 · fan-out | 36,817 | 258,580 |
+| 3 · follow-up | 39,447 | 282,281 |
+| 4 · follow-up | 82,232 | 305,855 |
+| 5 · follow-up | 41,447 | 338,507 |
+| 6 · follow-up | 31,963 | 362,595 |
+
+In these runs, sliceagent's orchestrator peak stayed roughly flat because each turn retained active digests and handles rather than child trajectories; its largest single request averaged **~17k** across the six-turn workload. A transcript orchestrator **re-carries the whole session every turn**, so the same delegation-heavy session reached a **~21× larger orchestrator peak and ~3.7× more total tokens** once both agents' children were counted. Parent context does not grow with child trajectory length, though it may still grow when more delegated results are genuinely relevant. Delegation is table stakes; the architectural advantage is durable, re-readable child artifacts plus a history-bounded parent.
+
+*N = 3 runs, single model, one opponent, needs the Codex CLI installed. A value-recall sub-check varied wildly run-to-run (sliceagent 1–3 / 3, Codex 0–2 / 3) — it turns on a behavioral re-read choice, so it is within noise and **not** part of the claim. The defensible result is the orchestrator-context and total-token gap, which is structural and held across all three runs (orchestrator 8.8–14.3×, total 3.2–4.3×).*
+
 <details>
 <summary><b>How the cost numbers are calculated</b> (exact token counts × published rates)</summary>
 
@@ -194,9 +220,9 @@ One honest wrinkle worth naming: Codex's append-only transcript actually earns a
 
 </details>
 
-> The pattern across all three: **capability holds, and the cost gap grows with session length** — exactly the flat-per-turn-cost thesis. "Solved" is solution correctness, scored identically for both agents. ColBench is [public](https://huggingface.co/datasets/facebook/collaborative_agent_bench); the long-horizon scenarios are reproducible under [`benchmarks/`](benchmarks/).
+> The pattern across all four is evidence for the **history-bounded-cost thesis in these scenarios**: capability held while per-turn cost tracked the current task rather than accumulated history. The same pattern extended to subagent orchestration. "Solved" is solution correctness, scored identically for both agents. ColBench is [public](https://huggingface.co/datasets/facebook/collaborative_agent_bench); the long-horizon scenarios are reproducible under [`benchmarks/`](benchmarks/).
 >
-> **These are early, small-scale results** — modest task counts (N = 32 / 20 / 3), single trial per task, one model, one opponent. Treat them as a directional signal, not a settled claim. We're actively expanding to larger and more varied test sets, more trials, and more baselines, and will update these numbers as that work lands.
+> **These are early, small-scale results** — modest task counts (N = 32 / 20 / 3 tasks; §4 is one task × 3 runs), single trial per task, one model, one opponent. Treat them as a directional signal, not a settled claim. We're actively expanding to larger and more varied test sets, more trials, and more baselines, and will update these numbers as that work lands.
 
 ## Install & quickstart
 
@@ -212,7 +238,7 @@ curl -fsSL https://raw.githubusercontent.com/TT-Wang/sliceagent/main/install.sh
 irm https://raw.githubusercontent.com/TT-Wang/sliceagent/main/install.ps1 | iex
 ```
 
-(Installs `uv` + sliceagent, and Git Bash + ripgrep if you don't have them — the agent's shell commands run under Git Bash, same as other coding agents. Interactive PTY sessions (`terminal_open`) aren't available natively yet; everything else works. Prefer WSL2? The Linux one-liner above works there as-is.)
+(Installs `uv` + sliceagent, and Git Bash + ripgrep if you don't have them — the agent's shell commands run under Git Bash, same as other coding agents. Persistent process and interactive PTY tools are optional and disabled by default everywhere; `AGENT_ADVANCED_TOOLS=1` enables them where supported, but `terminal_open` is not available on native Windows yet. Prefer WSL2? The Linux one-liner above works there as-is.)
 
 **The installer handles everything**: `uv`, its own Python 3.12, ripgrep, and sliceagent — in an isolated tool env, no sudo, no prerequisites, no conflict with any Python you already have (conda base at 3.10? Rosetta-Intel conda on an M-series Mac? Doesn't matter). Then just:
 
@@ -243,13 +269,19 @@ Run `sliceagent` in your project and type what you want in plain language. It re
 ```text
 ❯ why does retry_with_backoff drop the last attempt? fix it
 
-  🔍 grep "retry_with_backoff"   📖 read errors.py:40-72   ✎ edit errors.py
+  │ 1 search · 2 read  retry.py, tests/test_retry.py
+  │ write retry.py
+  │ plan 2/3 · add a regression test
+  ◌ 2/3 add a regression test · Running pytest -q · 00:12
+  │ run pytest -q
+  │   38 passed
+  │ ◆ The regression reproduces the bug and passes with the fix.
   ┌─ assistant ─────────────────────────────────────────────┐
   │ The loop exits on `attempt == max` before the final      │
   │ sleep+retry, so the last attempt never runs. Changed the  │
   │ bound to `attempt <= max` and added a regression test.    │
   └──────────────────────────────────────────────────────────┘
-  ✓ done · 4 steps · 6.1k tokens
+  ✓ turn saved · plan 3/3 · 2 passes · 4 read · 1 edit · 1 cmd · 00:18
 ```
 
 Attach a file or path to your message with `@`: `@src/errors.py explain the backoff`.
@@ -261,15 +293,27 @@ Attach a file or path to your message with `@`: `@src/errors.py explain the back
 | `/config` · `/model` · `/reasoning` | add/switch providers · switch model / reasoning effort (persists) |
 | `/mode` | permission mode: **baby-sitter** (confirm each edit + command) · **teenager** (default; confirm risky ones) · **let-it-go** (auto-run all but catastrophic) |
 | `/undo` | revert the last edit(s) |
-| `/cwd <path>` | change the workspace root mid-session |
+| `/cwd [path]` | show the fixed workspace root; with a path, show where to relaunch |
 | `/cost` | tokens and estimated $ spent this session |
 | `/skills` · `/tools` · `/mcp` · `/plugins` · `/agents` | list what's available to the agent |
 | `/threads` · `/resume` | switch between, or resume, parked topics |
 | `/learn <note>` | save a durable lesson yourself |
-| `/plan` | draft a plan before it starts editing |
+| `/plan` | show the current task plan |
 | `Ctrl-C` · `exit` | interrupt the turn · quit |
 
-It can edit code (workspace-confined, reversible with `/undo`), run shell commands and interactive processes through a sandbox (`local` by default, `docker` for full isolation), search the tree and the web, delegate decomposable work to subagents (each on its own bounded slice), and remember lessons across sessions. Three permission modes gate it, all with a hard floor on catastrophic commands; secrets are scrubbed from anything it runs or logs.
+Prefix an unrelated request with `New task:` to start it with fresh task state while parking the current task
+for `/resume`. Ambiguous follow-ups deliberately continue the active task so context is never discarded on a
+guess.
+
+It can edit code (workspace-confined, reversible with `/undo`), run regular shell commands through a sandbox (`local` by default, `docker` for full isolation), search the tree and the web, and delegate decomposable research to a fresh one-shot read-only explorer (each child gets its own history-bounded, task-elastic slice). That narrow surface is the demo default. Set `AGENT_ADVANCED_AGENTS=1` to expose writable and named specialist delegation (and nested delegation when `AGENT_SUBAGENT_DEPTH` is raised above its default of `1`), or `AGENT_ADVANCED_TOOLS=1` to expose persistent process and interactive terminal tools. The flags are independent. Three permission modes gate actions, all with a hard floor on catastrophic commands; secrets are scrubbed from anything persisted or logged.
+
+Every clean or interrupted agent task turn and every subagent report is sealed into the always-on local artifact/checkpoint path, independently of semantic memory. The model can refine retained detail through the read-only `artifacts/` namespace. Cross-session semantic lessons are a separate, optional derived layer powered by memem; task recovery does not depend on it.
+
+If a timeout or disconnect leaves an operation's side effects uncertain, SliceAgent carries a durable,
+target-scoped reconciliation gate into the next turn: it permits matching live read-only inspection, then
+requires an explicit evidence-backed resolution before more effects or task switching in that workspace.
+Opaque shell/code effects also require live user confirmation; a directory listing is never treated as proof
+of file contents. Ambiguous recovery journals stop startup before plugins or MCP processes run.
 
 **Configuration.** `sliceagent config --list` prints every setting. Set them persistently in `~/.sliceagent/config.toml` (written by `init`), or override any one via an environment variable:
 
@@ -279,7 +323,12 @@ It can edit code (workspace-confined, reversible with `/undo`), run shell comman
 | `AGENT_POLICY` | `teenager` | permission mode |
 | `AGENT_SANDBOX` | `local` | `local` or `docker` (isolated) |
 | `AGENT_MAX_STEPS` | `60` | per-turn step ceiling |
-| `SLICEAGENT_VAULT` | `~/.sliceagent/vault` | where episodic memory + task state persist (cross-session memory is on by default) |
+| `AGENT_CONTEXT_WINDOW` | *(catalog or unset)* | explicit provider window for strict per-call preflight; unknown models otherwise use compatibility mode |
+| `AGENT_ADVANCED_AGENTS` | *(off)* | enable writable and named specialists; unlock the nested surface subject to the depth ceiling |
+| `AGENT_SUBAGENT_DEPTH` | `1` | delegation depth ceiling; raise it to permit nested advanced agents |
+| `AGENT_ADVANCED_TOOLS` | *(off)* | enable persistent process and interactive terminal tools |
+| `SLICEAGENT_CACHE_DIR` | `~/.sliceagent` | always-on local checkpoints, immutable artifacts, and recovery journals |
+| `SLICEAGENT_VAULT` | `~/.sliceagent/vault` | optional semantic-memory and legacy compatibility records |
 | `AGENT_VERIFY_CMD` | *(unset)* | test command used as the verification oracle |
 
 ## License
@@ -288,7 +337,7 @@ It can edit code (workspace-confined, reversible with `/undo`), run shell comman
 
 ## Acknowledgements
 
-sliceagent's design was informed by two excellent open-source agents: **[Hermes](https://github.com/NousResearch/hermes)** (MIT) and **[Kimi Code](https://github.com/MoonshotAI/kimi-code)**. A few peripheral utilities are ported from Hermes (see [NOTICE](NOTICE)); most of the rest are patterns we studied and reimplemented on our own terms. Cross-session memory is powered by [memem](https://github.com/TT-Wang/memem). With thanks to their authors.
+sliceagent's design was informed by two excellent open-source agents: **[Hermes](https://github.com/NousResearch/hermes)** (MIT) and **[Kimi Code](https://github.com/MoonshotAI/kimi-code)**. A few peripheral utilities are ported from Hermes (see [NOTICE](NOTICE)); most of the rest are patterns we studied and reimplemented on our own terms. The optional cross-session semantic-memory layer is powered by [memem](https://github.com/TT-Wang/memem); local artifacts and recovery do not depend on it. With thanks to their authors.
 
 ## Contact
 

{sliceagent-0.1.15 → sliceagent-0.2.0}/QUICKSTART.md

@@ -1,6 +1,7 @@
 # Quickstart
 
-Get from zero to your first completed task in ~5 minutes.
+Get from zero to your first completed task in ~5 minutes. For the architecture behind the CLI, see the
+canonical [Core Design](CORE-DESIGN.md): **history-bounded, task-elastic, and recoverable by construction**.
 
 ## 1. Install
 
@@ -64,10 +65,27 @@ You get an inline prompt with a pinned input box. Type a task — e.g. *"add a `
 test for it"* — and watch it work. The conversation stays in your normal terminal scrollback, so
 **select + copy/paste and scroll work natively** on any terminal (including macOS Terminal.app).
 
+The demo defaults to the narrow core: the parent can edit and run regular commands, while delegation creates
+a fresh, one-shot, read-only explorer. Advanced surfaces are explicit opt-ins:
+
+```bash
+export AGENT_ADVANCED_AGENTS=1   # writable and named specialists; nesting uses AGENT_SUBAGENT_DEPTH
+export AGENT_ADVANCED_TOOLS=1    # persistent processes and interactive terminal/PTY tools
+```
+
+The flags are independent; leave either unset to keep that surface out of the model's tool set. Delegation
+depth defaults to `1`; raise `AGENT_SUBAGENT_DEPTH` only if you intentionally want advanced agents to spawn
+children. Local checkpoints and immutable turn/subagent artifacts are always on and can be read through
+`artifacts/`. Semantic cross-session lessons are an optional derived layer; recovery does not depend on them.
+An uncertain timeout parks the task and gates further effects until the agent re-observes every affected
+live target and records reconciliation; unrelated reads cannot clear the gate, and opaque effects require
+live user confirmation.
+
 Useful keys & commands:
 
 - **Enter** sends · **Ctrl-J** inserts a newline · **Ctrl-C** aborts the current turn · **Ctrl-D** quits.
 - `/help` lists slash commands · `/plan` shows the agent's plan · `/threads` lists topics · `/exit` quits.
+- Start an unrelated task explicitly with `New task: ...`; the current task is parked for `/resume`.
 
 UI modes (via `AGENT_TUI`): `rich` (default, inline) · `live` (always-pinned box, streams above it) ·
 `off` (plain stdout, good for pipes/CI).
@@ -75,9 +93,12 @@ UI modes (via `AGENT_TUI`): `rich` (default, inline) · `live` (always-pinned bo
 ## 4. Reading the output
 
 The status bar reads `model · net · policy · Σ tokens · fresh`. The **fresh** number is the one to watch:
-it's the per-turn non-cached input cost, and sliceagent's whole design keeps it flat as a session grows.
+it's the per-turn non-cached input cost. With active task state held stable, it does not grow merely because
+the session is older; it can still expand when the task gains genuine constraints, files, or evidence.
 
 ## Troubleshooting
 
 Common snags: no API key (run `sliceagent init`), `rg` (ripgrep) not installed, or an MCP server that fails to
-start. `sliceagent config --list` shows every setting and its current value.
+start. For a model whose context window is not in the catalog, set `AGENT_CONTEXT_WINDOW` to its documented
+token limit to enable strict per-call capacity rejection; leaving it unset uses the explicit compatibility
+mode. `sliceagent config --list` shows every setting and its current value.