@jslee124/forge 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jslee124/forge",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A safe, observable, and evaluable coding agent",
   "license": "MIT",
   "type": "module",
@@ -35,9 +35,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@ai-sdk/deepseek": "^3.0.28",
-    "@ai-sdk/openai": "^4.0.43",
-    "ai": "^7.0.66",
+    "@ai-sdk/deepseek": "3.0.28",
+    "@ai-sdk/openai": "4.0.43",
+    "ai": "7.0.66",
     "commander": "^15.0.0",
     "ink": "^7.1.1",
     "react": "^19.2.8",

package/resources/docs/en/ARCHITECTURE.md

@@ -129,10 +129,11 @@ the model; they do not bypass `read_file`, workspace validation, policy, or
 trace events by injecting file contents automatically.
 
 Each interactive prompt starts a fresh bounded run and approval-policy instance.
-Only completed user and assistant text is carried into the next prompt. That
-conversation is persisted as a session and can be restored after restart, while
-tool continuation metadata and approvals remain scoped to the run that produced
-them. See Persistent Sessions and Run Traces.
+Only completed canonical user, assistant, tool-call, and paired tool-result
+blocks are carried into the next prompt. That provider-neutral conversation is
+persisted as session schema v3 and can be restored after restart. Unfinished
+calls, provider continuation metadata, and approvals remain run-scoped. See
+Persistent Sessions and Run Traces.
 
 ### Agent runtime
 

package/resources/docs/en/CLI_UI.md

@@ -88,6 +88,26 @@ session-exit behavior when Forge is otherwise idle.
   later be used for prompt history; history is not required for Milestone 4.6.
 - Shift+Tab cycles through the active model's supported thinking-effort levels.
 
+## Context pressure and controls
+
+The editor footer uses two rows. The first keeps model/effort and a projected
+context indicator visible; the second preserves the existing keyboard
+shortcuts. The indicator uses `○`, `◔`, `◑`, `◕`, or `●` plus a percentage and
+semantic text. Estimated values carry `~`; responsive rendering drops labels
+before it drops the number or ring.
+
+`/context` opens a keyboard-owned panel backed by the same pressure snapshot.
+It shows instructions, tool schemas, active history, draft/image estimates,
+the effective reserve, checkpoint provenance, threshold, strategy, and last
+compaction. Press `p` to preview, `c` to compact once, `a` to enable automatic
+compaction for this process, `s` to explicitly save it as the user default, or
+Escape to close. A first `warn`-mode threshold crossing offers compact once,
+session auto, or dismiss without stealing an active run or approval prompt.
+
+The default remains `warn`. Automatic compaction uses projected pressure, not
+message count, and pauses after cancellation, invalid projection, or low
+reclamation. The canonical transcript remains lossless.
+
 ## Slash-command completion
 
 Typing `/` as the first non-whitespace character opens a list of available
@@ -203,9 +223,11 @@ visual truncation must not silently turn partial content into approval for an
 unseen patch.
 
 The approval controls are visible next to the diff and describe their scope.
-For example, approving the first workspace write covers later workspace writes
-only in the current run, while process commands continue to require separate
-approval.
+`1` allows the displayed action once, `2` allows exactly the displayed scope
+for the current in-memory session, and `3` opens an optional denial-feedback
+field. High-risk actions omit the session option. `/permissions` shows the
+effective profile, active scope identifiers, use counts, and revoke controls;
+grants disappear on `/new`, `/resume`, and process exit.
 
 Process-command approval uses the same dedicated panel. It renders a
 shell-readable `$ command` line followed by clearly labelled working-directory
@@ -218,6 +240,12 @@ approval preview.
 
 ## Sign-in panel
 
+The update checker also renders inside the Ink tree. A late result can add a
+compact current/latest banner without creating transcript text or taking input
+ownership from the editor, stream, or approval panel. Wide terminals include
+the release-notes destination and restart wording; narrow terminals retain the
+versions, `forge update`, restart, and `/update-dismiss` controls.
+
 A pending browser sign-in is a dedicated panel, not transcript text. The Codex
 auth surface reports the URL as a structured `login` output event carrying the
 address as its own field, so the UI never re-parses it out of a text chunk.

package/resources/docs/en/CONFIGURATION.md

@@ -118,6 +118,11 @@ effort.
 Forge does not implement a `full-access` profile. An approved child process is
 still not OS-sandboxed; see Security.
 
+Permission grants are not configuration. Choosing the numbered session option
+stores a normalized scope only in the active process. Project configuration,
+instructions, Skills, checkpoints, tool results, and plugin hooks cannot persist
+or widen it. `/permissions` shows and revokes the current in-memory grants.
+
 ### Traces and plugins
 
 | Field | Default | Notes |
@@ -138,12 +143,17 @@ toggle. See Plugin authoring and trust.
 | `context.bufferTokens` | `8192` | 1–2,000,000 | A project may increase the safety buffer. |
 | `context.recentTailTokens` | `12000` | 0–2,000,000 | A project may reduce the verbatim recent-history budget. |
 | `context.summaryTargetTokens` | `1200` | 64–2,000,000 | A project may reduce the checkpoint target. |
-
-`warn` measures pressure and reports it without automatically generating a
-checkpoint. `compact` enables automatic checkpoint behavior when required by
-the implemented budget rules. `/compact` remains available as an explicit
-interactive action. The canonical session transcript is retained separately in
-all modes. See Context management.
+| `context.activationThreshold` | `0.78` | 0.5–0.95 | A project may lower the pressure threshold, never raise it. |
+| `context.minimumReclaimTokens` | `8000` | 0–2,000,000 | A project may lower the no-progress floor, never raise it. |
+| `context.minimumReclaimRatio` | `0.2` | 0–0.9 | A project may lower the no-progress ratio, never raise it. |
+
+`warn` measures projected next-request pressure and offers non-blocking TUI
+controls at the activation threshold. `compact` permits pressure-driven
+checkpoint generation. `/context` can enable automatic compaction for only the
+current process, or explicitly save `compact` to user configuration;
+session-only state is never restored. `/compact` remains available in every
+mode. The canonical session transcript is retained separately. See
+Context management.
 
 ## Safe project configuration
 

package/resources/docs/en/CONTEXT_MANAGEMENT.md

@@ -4,10 +4,11 @@
 
 ## Status
 
-Roadmap Milestone 10 is implemented. This document records the design,
-invariants, rollout decision, and follow-up live-evaluation gates. The default
-remains `warn`; automatic checkpoint generation is opt-in until the published
-provider-quality gates pass.
+Roadmap Milestone 10 and Milestone 13.0-13.5 are implemented. The default
+remains `warn`; automatic checkpoint generation is opt-in until published
+provider-quality gates pass. The TUI now projects the complete next-request
+input, keeps a segmented pressure indicator visible, and exposes session-only
+or explicitly persisted automatic mode through `/context`.
 
 The first shipped Forge checkpoint uses a deterministic, redacted extractive
 summarizer so default tests and manual `/compact` make no paid model call. It
@@ -18,15 +19,21 @@ provider-native state, but the current OpenAI AI SDK and DeepSeek adapters
 advertise native compaction as unsupported because their active transports do
 not yet expose a safe compact-item round trip.
 
+The initial activation threshold is `0.78`. Input capacity subtracts
+`max(output reserve, safety buffer)` exactly once. Auto mode pauses when a
+compaction is cancelled, invalid, or reclaims less than the larger of 8,000
+tokens or 20% of projected input. Stable-prefix and cache observations are
+hash-only trace metadata; missing provider cache usage remains unavailable.
+
 ## Why this work is next
 
-Forge already separates project instructions, completed conversation turns,
+Forge already separates project instructions, canonical conversation turns,
 the current user request, and provider continuation data. It also bounds
 instruction files, tool output, model steps, tool calls, and persisted session
 size. These controls make execution inspectable, but they do not manage a
 model's token window.
 
-Today, every completed user/assistant turn is sent again on the next native
+Today, every canonical user/assistant turn is sent again on the next native
 Forge request. A long session can therefore fail at the provider boundary even
 when its persisted JSON remains within the session size limit. During a run,
 assistant tool calls and tool results also accumulate through provider
@@ -111,7 +118,7 @@ Milestone 10 should:
 2. Make every context-selection decision visible in structured events and
    `forge inspect`.
 3. Preserve recent conversational continuity while compacting only older,
-   completed turns.
+   canonical historical turns.
 4. Keep the canonical transcript lossless and separate from the smaller active
    model context.
 5. Preserve Forge's security boundary: old text and summaries cannot restore
@@ -321,12 +328,13 @@ from unexplained holes in the conversation.
 
 ### Checkpoint schema
 
-Session schema version 2 should retain `messages` as the canonical transcript
-and add an optional derived checkpoint:
+Session schema version 3 retains structured `history` as the canonical
+transcript and uses an optional checkpoint v2. Selection and hashing operate on
+complete user/assistant/tool exchanges and never split a call from its result:
 
 ```ts
 interface ContextCheckpoint {
-  schemaVersion: 1;
+  schemaVersion: 2;
   strategy: "forge-summary" | "provider-native";
   summarizedThroughMessageIndex: number;
   sourceHash: string;
@@ -491,7 +499,8 @@ The implementation must preserve these invariants:
    permission profiles.
 3. A summary cannot mark a previously failing verification as currently
    passing.
-4. Only completed conversation turns are eligible for cross-run compaction.
+4. Only canonical historical conversation messages are eligible for cross-run
+   compaction; pending executable state is never included.
 5. Pending tool calls and results remain paired according to adapter rules.
 6. The canonical transcript is not mutated or deleted by compaction.
 7. Configured secrets are redacted before checkpoint generation and persistence.

package/resources/docs/en/GETTING_STARTED.md

@@ -27,10 +27,10 @@ a provider.
 
 Forge's development workspace remains private. Release automation produces one
 public CLI package, `@jslee124/forge`, while internal packages and the plugin
-SDK remain private. Until the first npm release is visible, run from source or
-link the current checkout globally.
+SDK remain private. Install the published CLI for normal use; run from source
+or link the current checkout globally when contributing to Forge.
 
-For a published build:
+For the current stable build:
 
 ```bash
 npm install --global @jslee124/forge
@@ -47,7 +47,7 @@ pnpm build
 pnpm forge --version
 ```
 
-The final command builds the workspace and should print `0.3.1` for the current
+The final command builds the workspace and should print `0.3.3` for the current
 source release. It does not contact a model provider.
 
 During development you can keep using `pnpm forge`. To expose the same checkout
@@ -223,10 +223,11 @@ pnpm forge resume --last
 pnpm forge inspect <run-id>
 ```
 
-A session stores completed user/assistant turns. A run is one bounded agent-loop
-execution with its own ID and JSONL event trace. Resume restores completed
-conversation text, not old approvals, pending tool calls, child processes, or
-provider continuation state. See Sessions and traces.
+A session stores canonical conversation context. A run is one bounded
+agent-loop execution with its own ID and JSONL event trace. Interactive resume
+replays available historical model and tool events, but it does not reactivate
+old approvals, pending tool calls, child processes, or provider continuation
+state. See Sessions and traces.
 
 ## Next steps
 

package/resources/docs/en/PLUGINS.md

@@ -5,7 +5,7 @@
 
 简体中文 · Documentation index
 
-Forge 0.3.1 works without plugins. A plugin is an optional in-process JavaScript
+Forge 0.3.3 works without plugins. A plugin is an optional in-process JavaScript
 module that can register model-callable tools and explicit local commands,
 contribute instructions, observe immutable run events, or make policy stricter.
 
@@ -608,7 +608,7 @@ would require a restricted process or OS sandbox.
 
 ## Deliberate limitations
 
-Forge 0.3.1 has no plugin installer, dependency resolver, package registry, hot
+Forge 0.3.3 has no plugin installer, dependency resolver, package registry, hot
 reload, TypeScript entry compilation, custom interactive UI, provider
 registration, isolated plugin process, or enforceable filesystem/network
 capabilities. Plugin commands run only through `forge plugins run`; they do not

package/resources/docs/en/PROJECT_CONTEXT.md

@@ -143,7 +143,7 @@ starting an Agent run.
 ## Project-level `.forge/`
 
 The selected workspace root's `.forge/` is reserved for Forge-specific project
-customization. The current 0.3.1 layout is:
+customization. The current 0.3.3 layout is:
 
 ```text
 .forge/

package/resources/docs/en/RELEASING.md

@@ -23,17 +23,18 @@ development-only files cannot enter the registry by accident.
 
 ## Prepare a release
 
-Start from a clean checkout and choose a semantic version:
+Start from a clean checkout and choose a semantic version. Replace `0.3.1`
+below with the release being prepared:
 
 ```bash
-pnpm version:set 0.3.0
+pnpm version:set 0.3.1
 pnpm install --frozen-lockfile
 pnpm check
 pnpm check:docs
 pnpm test
 pnpm eval:deterministic
 pnpm package:verify
-pnpm release:verify-tag v0.3.0
+pnpm release:verify-tag v0.3.1
 ```
 
 `package:verify` builds the public artifact, inspects the tarball, installs it
@@ -45,18 +46,19 @@ Review `npm pack --dry-run` output and release notes before tagging. Never
 include API keys, auth files, local traces, `.env` files, or evaluation
 artifacts that were not explicitly reviewed for publication.
 
-## First npm publication
+## One-time npm setup (completed)
 
-The npm account or organization must control the `@jslee124` scope and have 2FA
-enabled. npm requires a package to exist before a trusted publisher can be
-attached. Bootstrap the package with a reviewed prerelease such as
-`0.3.0-bootstrap.0` under a non-stable dist-tag, then configure the repository's
-`publish.yml` as the package's GitHub Actions trusted publisher. Do not assign
-the bootstrap build to `latest`.
+The first publication was completed for v0.3.0. The `@jslee124` scope is
+controlled by the maintainer, and `.github/workflows/publish.yml` is registered
+as the package's GitHub Actions trusted publisher. The one-time bootstrap used
+`0.3.0-bootstrap.0` under the `bootstrap` dist-tag; `latest` now points to the
+stable `0.3.0` release. Do not repeat the bootstrap procedure for later
+releases.
 
-After trusted publishing is configured, stable releases should come only from
-the tag workflow. It uses OIDC instead of a long-lived npm token and publishes
-the generated package after all release gates pass.
+Stable releases must come only from the tag workflow. It uses OIDC instead of a
+long-lived npm token and publishes the generated package after all release
+gates pass. If the trusted-publisher configuration is ever replaced, review the
+npm package settings and workflow identity together before creating a tag.
 
 ## Publish a stable release
 
@@ -64,17 +66,17 @@ Commit the version, release notes, and generated-input changes, then create an
 annotated immutable tag:
 
 ```bash
-git tag -a v0.3.0 -m "Forge v0.3.0"
-git push origin v0.3.0
+git tag -a v0.3.1 -m "Forge v0.3.1"
+git push origin v0.3.1
 ```
 
 The `Publish npm package` workflow verifies that the Git tag, root version,
 private workspace versions, runtime version, and generated npm package all
-match before it runs `npm publish --access public`.
+match before it publishes with an explicit dist-tag. Stable semantic versions
+route to `latest`; versions with a prerelease component route to `next`.
 
-Use `npm publish --tag next` only for deliberate prereleases. Do not move a
-published Git tag or reuse an npm version. Fix a bad release with a new patch
-version and leave the prior artifact available for rollback.
+Do not move a published Git tag or reuse an npm version. Fix a bad release with
+a new patch version and leave the prior artifact available for rollback.
 
 ## User updates
 
@@ -83,12 +85,15 @@ Installed users can check or update explicitly:
 ```bash
 forge update check
 forge update
-forge update 0.3.1
+forge update 0.3.3
 ```
 
-Interactive startup refreshes an advisory npm check in the background at most
-once per 24 hours and displays cached results on a later launch. It never
-installs an update automatically. Set
+Interactive startup publishes cached, refreshing, available, current, failed,
+or disabled state inside Ink and refreshes npm metadata at most once per 24
+hours. A late result updates the banner without entering conversation history.
+It never installs automatically; `/update-dismiss` dismisses that version. Set
 `FORGE_DISABLE_UPDATE_CHECK=1` to disable startup checks. The explicit update
-command resolves npm metadata to an exact semantic version before invoking
-`npm install --global --ignore-scripts`.
+command remains repeatable and resolves an exact semantic version. It invokes
+npm or pnpm with an argument array and `--ignore-scripts` only when installation
+provenance is recognized; otherwise it reports the version and release notes
+without guessing. A successful install still requires restarting Forge.

package/resources/docs/en/SECURITY.md

@@ -105,6 +105,20 @@ child process that has already been approved.
 
 ## Process boundary
 
+Interactive approval is structured: `1` allows once, `2` creates only the
+displayed in-memory session scope, and `3` denies with optional bounded
+feedback. Command scopes bind the exact program and argument array, canonical
+workspace and cwd, and a timeout ceiling. Workspace-write, network
+tool/destination, and delegated-model scopes use similarly normalized host
+fields rather than model-authored text. `/permissions` lists use counts and can
+revoke one or all grants.
+
+Session grants are never serialized or restored. Changed arguments, cwd,
+destination, workspace, or a timeout above the ceiling re-prompts. Destructive,
+credential-sensitive, install, publish, and broad external-effect commands are
+not eligible for reuse. Plugin policy hooks can still change `allow` to
+`confirm`/`deny` or `confirm` to `deny`; they cannot create or widen a grant.
+
 The v0.1 `run_command` tool accepts a program and an argument array and starts it
 with Node.js `spawn` using `shell: false`. Shell syntax such as pipelines,
 redirection, command substitution, and compound commands is not accepted.
@@ -212,11 +226,13 @@ tool events.
 
 ## Persistent sessions
 
-Resuming a session restores completed conversation messages, not executable
-authority. Forge creates a new policy instance for every resumed run and never
-restores prior approvals, pending tool calls, child processes, or provider
-continuation metadata. Current user configuration and project instructions are
-loaded again before the next prompt.
+Resuming a session restores completed canonical conversation blocks, including
+closed tool-call/result pairs, but never executable authority. Historical tool
+output is untrusted context rather than current verification. Forge creates a
+new policy instance for every resumed run and never restores prior approvals,
+pending tool calls, child processes, or provider continuation metadata. Current
+user configuration and project instructions are loaded again before the next
+prompt.
 
 Session snapshots and traces are stored outside the repository under
 `FORGE_HOME`. They may contain repository text, diffs, commands, and model

package/resources/docs/en/SESSIONS.md

@@ -4,15 +4,17 @@
 
 ## Goal
 
-Forge persists enough trusted metadata and completed conversation history to
-continue an interactive chat after the process exits. This is deliberately
-separate from replaying an in-progress tool call.
+Forge persists enough trusted metadata, completed conversation history, and
+bounded outcomes from incomplete runs to continue an interactive chat after
+the process exits. This is deliberately separate from replaying an in-progress
+tool call.
 
 The core relationship is:
 
 ```text
 Session
-|-- completed user/assistant turns
+|-- canonical user/assistant/tool-call/tool-result history
+|-- bounded failed/denied/cancelled run outcomes
 |-- provider-exposed reasoning summaries for completed assistant turns
 |-- optional derived context checkpoint
 |-- workspace and working-directory metadata
@@ -37,16 +39,28 @@ $FORGE_HOME/
     `-- <run-id>.jsonl
 ```
 
-Session snapshots use `schemaVersion: 2`; v1 snapshots migrate on load. Trace
+Session snapshots use `schemaVersion: 3`; v1/v2 snapshots migrate on load. The
+v3 snapshot stores provider-neutral content blocks and a fidelity marker. Trace
 envelopes retain `schemaVersion: 1`. Files are written only under the resolved
 Forge home. Session snapshots are replaced atomically. Run traces are append-only
 while their run is active.
 
+A durable session snapshot is limited to 4 MiB after redaction and final JSON
+serialization. Forge checks the same byte limit on save and load. An oversized
+save fails before the atomic replacement, so the previous resumable snapshot is
+preserved. Because canonical history is intentionally lossless and checkpoints
+do not delete it, the current retention strategy is to start a new session as
+the limit approaches and archive the old JSON file outside the active
+`sessions/` directory if it no longer needs to appear in resume listings.
+
 Each session stores:
 
 - Session ID, creation time, and last-updated time
 - Canonical workspace root and the saved working directory
-- Completed user and assistant messages
+- Completed user and assistant messages, assistant tool calls, and exactly
+  paired model-visible tool results or failures
+- User requests and bounded, authority-free outcome summaries for incomplete
+  runs or completed runs that encountered tool failures
 - Provider-exposed reasoning text associated with completed assistant messages
 - The ordered run IDs belonging to the session
 - An optional versioned checkpoint with source/tail hashes and provenance
@@ -67,23 +81,41 @@ forge resume --last
 
 The interactive `/resume` command opens a bounded list of saved sessions for
 the current canonical workspace. Selecting one replaces the empty/current
-conversation with its completed history and continues in that saved session.
+conversation with its canonical history and continues in that saved session.
+When every referenced trace is available, the interactive transcript is rebuilt
+from the same ordered `RunEvent` stream used during the original run. This
+restores reasoning summaries, intermediate model text, tool proposals,
+decisions, completions, and failures instead of displaying the bounded model
+context summary as assistant prose.
 
 Resume follows these rules:
 
-1. Only completed user/assistant turns and their provider-exposed reasoning are
-   restored for display.
+1. Completed user/assistant/tool turns are restored. Failed, denied, cancelled, and
+   limit-reached runs restore the original request plus a bounded outcome
+   summary. A completed run that encountered tool failures retains a bounded
+   tool-outcome suffix as well.
 2. A new prompt always starts a new bounded run with a new run ID.
 3. Current configuration and `AGENTS.md` instructions are loaded again.
-4. Approval state is new for every resumed run.
+4. Approval state is new for every resumed run; memory-only session grants are
+   cleared before the saved conversation is loaded.
 5. Provider continuation records and partially completed tool calls are never
-   resumed.
+   resumed. Closed historical tool exchanges are model-visible context, but
+   remain untrusted historical observations: the next run must re-inspect the
+   workspace and obtain fresh approval before acting.
 6. A saved session from another workspace is rejected unless the user starts
    from that workspace explicitly.
 7. Missing or invalid session files produce an actionable configuration-style
    error without starting a model request.
 8. A valid checkpoint restores the same bounded active view; a stale or invalid
    checkpoint is ignored without changing the canonical transcript.
+9. Legacy snapshots are always migrated losslessly as text. Structured tool
+   history is backfilled only when every
+   referenced run trace is readable and the existing canonical messages form
+   an exact ordered subsequence of the reconstruction. Otherwise the snapshot
+   remains unchanged.
+10. If any referenced trace is missing or invalid, Forge renders the canonical
+    structured fallback instead of a misleading partial event timeline. Tool
+    calls/results remain available and the final answer is not duplicated.
 
 This means Forge restores conversation context, not authority or executable
 state. Saved reasoning remains display-only and is not added to the model's
@@ -107,8 +139,10 @@ assembled from terminal strings.
 ## Redaction and safety
 
 Before persistence, Forge redacts configured credential values and recognized
-secret-bearing fields. In particular, `DEEPSEEK_API_KEY` must never appear in a
-session snapshot or run trace.
+secret-bearing fields. Bounded run-outcome summaries omit tool output, file
+content, command arguments, and raw error messages; they retain only safe tool
+identifiers, file paths or command programs, and error codes. In particular,
+`DEEPSEEK_API_KEY` must never appear in a session snapshot or run trace.
 
 Run traces may still contain repository contents, diffs, commands, model text,
 and provider-returned reasoning. Files under `sessions/` and `runs/` are local
@@ -117,6 +151,8 @@ sensitive data and must not be committed to a repository.
 Session resume does not weaken the existing security model:
 
 - Previous approvals are not restored.
+- `/permissions` grants, scope identifiers, and use counts are runtime-only and
+  are not written to the session snapshot or derived checkpoint.
 - A previous permission profile is not trusted as a grant; current user
   configuration and explicit CLI choices determine the next run.
 - Project files cannot edit session metadata under `FORGE_HOME` through

package/resources/docs/en/TROUBLESHOOTING.md

@@ -148,6 +148,22 @@ behavior. Run in a terminal, narrow the task to read-only behavior, or use a
 purpose-built automation/evaluation approval channel. Do not switch profiles
 expecting OS isolation: neither profile sandboxes an approved process.
 
+In the interactive Forge Engine, choose `1` for one action or `2` only when the
+displayed session scope is appropriate. Use `/permissions` to inspect and
+revoke grants. Changed command arguments, cwd, network destination, workspace,
+timeout above the ceiling, or high-risk install/publish/destructive commands
+correctly prompt again. Choose `3`, optionally type guidance, and press Enter to
+return a denial result to the active run without granting authority.
+
+## An update is shown but `forge update` will not install it
+
+Forge installs only when it recognizes npm or pnpm global-install provenance.
+For an unknown or copied executable it reports the exact new version and
+release-notes URL without guessing a package manager. Use the installer that
+originally installed Forge. After a successful explicit update, restart the
+running process. `FORGE_DISABLE_UPDATE_CHECK=1` disables only the startup check;
+`forge update check` remains explicit and authoritative.
+
 ## A project plugin is listed but skipped
 
 Project plugins are discovered from the canonical workspace root's
@@ -220,8 +236,9 @@ pnpm forge resume --last
 
 Session snapshots live under `$FORGE_HOME/sessions`. Changing `FORGE_HOME`,
 moving the checkout, deleting a snapshot, or corrupting its JSON changes what
-is available. Resume restores only completed turns; it cannot continue an
-interrupted stream or pending tool call.
+is available. Resume restores completed turns plus bounded outcomes from
+failed, denied, cancelled, or limit-reached runs. It cannot continue an
+interrupted stream or pending tool call; the next run re-inspects current state.
 
 ## Terminal input or rendering looks wrong