@giovannijecha/jecode 0.7.0 → 0.7.1

package/README.md

@@ -9,8 +9,8 @@
 <p align="center"><strong>Your code. Your loop.</strong></p>
 
 <p align="center">
-  A focused coding agent that lives in your terminal, keeps tool use visible,
-  and stays under your control.
+  A focused terminal coding agent with visible tool use, durable sessions, and
+  one controller that stays under your control.
 </p>
 
 <p align="center">
@@ -21,367 +21,342 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/giovannijecha/jecode/blob/main/CHANGELOG.md">Changelog</a> ·
+  <a href="https://github.com/giovannijecha/jecode/blob/main/CHANGELOG.md">Changelog</a> &middot;
   <a href="https://github.com/giovannijecha/jecode/releases">Releases</a>
 </p>
 
-> Jecode is an early 0.7.x release. The core loop is usable today; commands and
+> Jecode is currently pre-1.0. The core loop is usable today, but commands and
 > terminal interactions may still evolve before 1.0.
 
 ## Why Jecode
 
-- **One controller.** One visible loop talks to the model, runs tools, and returns
-  control to you. Independent reads can overlap inside one step; writes and
-  commands remain ordered. There are no hidden workers or delegated agents.
-- **Terminal-native.** The transcript, composer, searchable menus, tool output,
-  diffs, approvals, reasoning, and status all share one full-screen TUI.
-- **Permission-aware.** Reads stay transparent; dangerous actions ask first.
-  Session approvals can be reviewed and revoked.
-- **Durable by default.** Interactive conversations survive terminal exits and
-  can be resumed without replaying tools. Batch runs remain stateless.
-- **Context-bounded.** Older model context is summarized automatically while
-  the complete conversation and transcript remain available in the session.
-- **Provider-neutral.** Use Anthropic or OpenAI API keys, a ChatGPT account, or
-  a local/remote Ollama server without changing the workflow.
-- **Lean by construction.** Jecode installs as plain JavaScript, runs on
-  Node.js 22.18+ (22.x) or Node.js 24+, executes no installation scripts, and
-  has zero third-party runtime dependencies.
-
-## Install
-
-Jecode requires **Node.js 22.18+ on the 22.x line, or Node.js 24+**, and npm:
-
-~~~console
+- **One visible loop.** One controller talks to the model, runs tools, and
+  returns control to you. Independent reads may overlap inside a step; writes
+  and commands stay ordered. There are no delegated agents or hidden model
+  workers.
+- **Terminal-native today.** The transcript, composer, searchable menus, tool
+  output, diffs, approvals, reasoning, and status share one full-screen TUI.
+- **Permission-aware.** Tool use is visible. Dangerous actions ask first, and
+  remembered session approvals can be reviewed or revoked.
+- **Durable and context-bounded.** Interactive conversations survive terminal
+  exits. Older model context can be compacted while the complete conversation
+  and transcript remain available in the saved session.
+- **Multi-provider.** Use Anthropic or OpenAI API keys, an eligible ChatGPT
+  account, or a local, cloud, or remote Ollama server without changing the
+  workflow.
+- **Lean by construction.** Jecode ships as owned JavaScript built on Node.js
+  primitives, executes no installation scripts, and has zero third-party
+  runtime dependencies. This is a permanent product constraint, not a temporary
+  optimization.
+
+## Quick start
+
+Jecode requires **Node.js 22.18+ on the 22.x line, or Node.js 24+**, and npm.
+
+```console
 npm install --global @giovannijecha/jecode
 jecode --version
-~~~
+cd path/to/your/project
+jecode
+```
 
-To try prereleases instead, install the opt-in **next** channel with
-`npm install --global @giovannijecha/jecode@next`.
+Jecode opens directly on an empty composer. Use `/providers` to connect a
+service, `/models` to choose a model, then describe the work you want done.
 
-Published npm packages are the supported installation artifacts. Git URL
-installs are intentionally unsupported: the source tree contains no generated
-runtime and defines no install-time build hook.
+```text
+Review this project, explain its architecture, and propose the smallest safe
+change to improve startup performance.
+```
 
-Then open the project you want to work on and run Jecode:
+Use `jecode --root path/to/project` to select another workspace, or
+`jecode --ephemeral` when the conversation must stay memory-only.
 
-~~~console
-cd path/to/your/project
-jecode
-~~~
+Resume a saved conversation for the current workspace with a searchable picker:
 
-Resume a saved conversation for the current project with a searchable picker,
-or open the most recent one directly:
-
-~~~console
+```console
 jecode resume
 jecode resume --latest
-~~~
+```
 
-Use `jecode --ephemeral` when a conversation must stay memory-only.
+Run `jecode --help` for every startup option. Windows, Ubuntu, and macOS are
+covered by the project test matrix.
 
-You can point at another workspace explicitly:
+### Prereleases
 
-~~~console
-jecode --root path/to/your/project
-~~~
+The stable npm package is the supported installation artifact. To try an
+opt-in prerelease:
 
-Run **jecode --help** for all startup options. Tested platforms are Windows,
-Ubuntu, and macOS.
+```console
+npm install --global @giovannijecha/jecode@next
+```
 
-### Update
+Git URL installs are intentionally unsupported: the source tree contains no
+generated runtime and defines no install-time build hook.
 
-Install the current stable release over the existing global command:
+### Update and uninstall
 
-~~~console
+```console
 npm install --global @giovannijecha/jecode
 jecode --version
-~~~
+npm uninstall --global @giovannijecha/jecode
+```
+
+Uninstalling the command preserves `~/.jecode`. Remove that directory only when
+you intentionally want to erase saved settings, credentials, accounts, and
+sessions.
 
-If you installed Jecode from GitHub before the scoped npm package existed,
-remove the old unscoped package once before updating:
+If an older GitHub installation still owns the `jecode` executable, remove the
+legacy unscoped package before installing the scoped package:
 
-~~~console
+```console
 npm uninstall --global jecode
 npm install --global @giovannijecha/jecode
-~~~
+```
 
-An `EEXIST` error for a `bin/jecode` path usually means that this legacy
-executable still owns the command. Remove it instead of installing with
-`--force`.
-
-### Uninstall
-
-~~~console
-npm uninstall --global @giovannijecha/jecode
-~~~
-
-Uninstalling the command preserves **~/.jecode** so saved settings and
-credentials remain available after a reinstall. Remove that directory only
-when you intentionally want to erase Jecode's local data.
+Do not work around the resulting `EEXIST` error with `--force`.
 
 ### Linux and WSL
 
-WSL has its own Node.js installation and `PATH`; the Node.js version installed
+WSL uses its own Node.js installation and `PATH`; the Node.js version installed
 on Windows does not apply inside it. Keep user-installed npm commands in the
-Linux user path and put that path before inherited Windows entries:
+Linux user path:
 
-~~~console
+```console
 npm config set prefix "$HOME/.local"
 export PATH="$HOME/.local/bin:$PATH"
 npm install --global @giovannijecha/jecode
 hash -r
 command -v jecode
 jecode --version
-~~~
+```
 
 Persist the `PATH` export in `~/.profile` or your shell's startup file. Inside
-WSL, **command -v jecode** should resolve below `/home/...`, not below
-`/mnt/c/.../Volta`. Do not ignore an `EBADENGINE` warning: **node --version**
-must report 22.18+ on the 22.x line, or 24+.
+WSL, `command -v jecode` should resolve below `/home/...`, not through an
+inherited Windows path below `/mnt/c`. Do not ignore `EBADENGINE`: `node
+--version` must report 22.18+ on the 22.x line, or 24+.
 
-### Build from source
-
-~~~console
-git clone https://github.com/giovannijecha/jecode.git
-cd jecode
-npm ci --ignore-scripts
-npm run build:release
-npm link
-jecode
-~~~
-
-Development runs TypeScript directly with **npm run start**. **dist/** is an
-ignored, generated tree used only by linked commands and release tarballs.
-**npm run pack:release** rebuilds it from a clean target before packing; the
-trusted publish workflow performs the same explicit build. Installing the
-published package runs no compilation or installation scripts.
-
-## First session
-
-Jecode opens on an empty composer instead of forcing a setup wizard. Type
-**/providers** to connect the services you use, then **/models** to choose from
-their combined live catalogues. **/settings** keeps the selected model and the
-remaining non-secret defaults together. An API key can remain in memory for
-the current session or be saved explicitly under **~/.jecode**; it is never
-stored in the workspace.
+## Providers
 
 | Provider ID | Authentication | Notes |
-|---|---|---|
-| anthropic | ANTHROPIC_API_KEY | Anthropic API |
-| openai | OPENAI_API_KEY | OpenAI API |
-| openai-codex | ChatGPT OAuth | Experimental; uses eligible ChatGPT Codex access |
-| ollama | OLLAMA_API_KEY for Cloud/remote | Cloud with a key, local without one |
-
-Choose **ChatGPT** in **/providers** to sign in on OpenAI's website without
-pasting a key.
-Jecode offers a local browser callback and a device-code flow; WSL and remote
-terminals default to the device code. The connection is saved only after the
-flow completes. Availability and usage limits are determined by the ChatGPT
-account and plan, not by OpenAI API credits. This integration is experimental
-and is not an endorsement of Jecode by OpenAI.
+| --- | --- | --- |
+| `anthropic` | `ANTHROPIC_API_KEY` | Anthropic API |
+| `openai` | `OPENAI_API_KEY` | OpenAI API |
+| `openai-codex` | ChatGPT OAuth | Experimental; uses eligible ChatGPT Codex access |
+| `ollama` | `OLLAMA_API_KEY` for cloud or remote use | Cloud with a key, local without one |
+
+Choose **ChatGPT** in `/providers` to sign in on OpenAI's website without
+pasting a key. Jecode supports a local browser callback and a device-code flow;
+WSL and remote terminals default to the device code. Availability and usage
+limits depend on the ChatGPT account and plan, not on OpenAI API credits. This
+integration is experimental and is not an endorsement of Jecode by OpenAI.
 
 Anthropic remains API-key only. Jecode does not reuse a Claude consumer
 subscription or copy credentials from another client.
 
-Choose **Ollama** in **/providers** to manage its API key and select **cloud**,
-**local**, or a custom endpoint. Existing users with an Ollama API key
-automatically use **https://ollama.com**; without a key, Jecode uses the local
-daemon at **http://127.0.0.1:11434**. Remote custom endpoints must use HTTPS.
+For Ollama, `/providers` can select cloud, local, or a custom endpoint. With an
+Ollama API key Jecode defaults to `https://ollama.com`; without one it defaults
+to `http://127.0.0.1:11434`. Remote custom endpoints must use HTTPS.
 
 ## Use the TUI
 
-Type **/** to open searchable command completion inside the composer.
+Type `/` to open searchable command completion inside the composer.
 
 | Command | What it does |
-|---|---|
-| /settings | Manage the selected model, limits, context compaction, effort, motion, and provider access |
-| /effort | Change and save reasoning effort directly |
-| /providers | Manage API keys, ChatGPT sign-in, and Ollama connections |
-| /models | Search models across every available provider and select one |
-| /permissions | Change session tool access inline and review remembered approvals |
-| /new | Close the current conversation, start clean, and reset tool permissions |
-| /timeline | Navigate completed turns and select where the next branch starts |
-| /compact | Compact the active model context immediately |
-| /export | Save a timestamped Markdown transcript in the launch directory |
-| /help | Open a temporary keyboard reference in the composer dock |
-| /exit | Restore the terminal and exit |
+| --- | --- |
+| `/settings` | Manage the selected model and saved non-secret defaults |
+| `/effort` | Change and save reasoning effort directly |
+| `/providers` | Manage provider connections, API keys, ChatGPT sign-in, and Ollama endpoints |
+| `/models` | Search all currently usable provider catalogues and select a model |
+| `/permissions` | Change session tool access and review remembered approvals |
+| `/timeline` | Browse completed turns and select where the next branch should begin |
+| `/compact` | Compact the current branch context without deleting saved conversation history |
+| `/new` | Start a new conversation and reset session tool permissions |
+| `/export` | Save a timestamped Markdown transcript in the launch directory |
+| `/help` | Open a temporary keyboard reference in the composer dock |
+| `/exit` | Restore the terminal and exit |
 
 Useful controls:
 
-- **Up/Down** moves through command suggestions, menus, and input history.
-- **Left/Right** moves the composer cursor or changes an inline menu value;
+- **Up/Down** moves through suggestions, menus, and input history.
+- **Left/Right** moves the cursor or changes an inline value;
   **Ctrl+Left/Right** moves by word.
-- **Backspace/Delete** removes one character; **Ctrl+Backspace/Delete** removes
-  one word. **Home/End** moves to the start or end of the composer.
+- **Backspace/Delete** removes one character;
+  **Ctrl+Backspace/Delete** removes one word.
+- **Home/End** moves to the beginning or end of the composer.
 - **Tab** completes a slash command without running it; **Enter** sends.
 - **Alt+Enter** inserts a newline.
-- **Esc** closes a menu or interrupts the foreground operation.
+- **Esc** closes the active menu or interrupts foreground work.
 - **Ctrl+C** interrupts, or exits while idle. **Ctrl+D** requests a clean exit.
-- **PageUp/PageDown** and the mouse wheel scroll the transcript without losing
-  the place you are reading.
+- **PageUp/PageDown** and the mouse wheel scroll the transcript.
 - **Ctrl+O** expands or compacts the latest reasoning or tool-detail block.
 
-The one-line footer keeps model, effort, and workspace on the left. While work
-is active, the right edge shows its current state, elapsed time, and interrupt
-hint; readiness guidance and temporary feedback use the same replaceable space
-without polluting the transcript. Slash commands never append content to the
-conversation or its Markdown export; **/help** closes with **Esc**, and token
-accounting remains internal to the active session.
+The footer keeps the active model, effort, and workspace visible. During work,
+it adds the current state, elapsed time, and interrupt hint. Operational
+feedback uses the same replaceable status area instead of adding noise to the
+conversation or its Markdown export.
+
+## Sessions and context
+
+Interactive conversations are stored under `~/.jecode/sessions` and scoped to
+the canonical workspace path. A fresh or `/new` conversation is not added to
+the resume picker until it has a settled turn. Resuming and continuing a
+conversation keeps its durable session identity and updates one picker entry
+instead of creating duplicates.
+
+`/timeline` shows completed turns in the conversation tree. Selecting an older
+turn changes only the in-memory path: it creates and saves a branch only after
+the next real user message. Cancelling the picker or exiting before that message
+leaves the durable head unchanged. Historical tools are displayed but never
+executed. If a crash interrupted a tool loop, Jecode resumes from the latest
+completed ancestor and lets the next user turn create a branch. `/export`
+writes only the currently selected path.
+
+When model-facing context approaches the selected model's usable capacity,
+Jecode asks the provider for a bounded summary of the older prefix and keeps
+recent turns exact. The default trigger is 85% and can be changed from 50% to
+95%. Live provider metadata or Ollama's allocated context determines the budget
+when available; provider safety limits always win.
+
+Compaction changes only the projection sent to the model. Complete messages,
+tool evidence, transcript, export, and conversation tree remain intact. The
+branch-local summary anchor is saved with the session so resume does not repeat
+the same compaction. `/compact` requests this process immediately, even below
+the automatic threshold; it leaves very small contexts unchanged. After
+selecting a historical turn, send the first new message before compacting so
+shared history is never rewritten.
+
+## Batch mode
+
+When stdin or stdout is not a terminal, Jecode switches to a plain
+line-oriented mode:
+
+```console
+printf "explain this project\n" | jecode --root .
+```
+
+Batch conversations are stateless. Dangerous tools remain denied unless
+`--auto-approve` is supplied explicitly. Terminal failures are written to
+stderr and exit non-zero so scripts and CI pipelines can stop reliably.
 
 ## Configuration
 
 Startup precedence is: command-line flags, environment variables, saved
-settings, built-in defaults.
+settings, then built-in defaults.
 
 | Flag | Environment | Default |
-|---|---|---|
-| --provider | JECODE_PROVIDER | anthropic |
-| --model | JECODE_MODEL | Provider default or interactive selection |
-| --ollama-host | OLLAMA_HOST | Cloud with an Ollama key, local without one |
-| --root | — | Current directory |
-| --effort | JECODE_EFFORT | high |
-| --max-tokens | JECODE_MAX_TOKENS | 64000; not sent by openai-codex |
-| --max-steps | JECODE_MAX_STEPS | 40 |
-| --compaction-percent | JECODE_COMPACTION_PERCENT | 85; accepts 50 through 95 |
-| --reduced-motion | JECODE_REDUCED_MOTION=1 | Off |
-| --auto-approve | JECODE_AUTO_APPROVE=1 | Off |
-| --ephemeral | JECODE_EPHEMERAL=1 | Off |
-
-Persistent preferences live in **~/.jecode/settings.json**. Explicitly saved
-API keys live in **~/.jecode/credentials.json**; the ChatGPT OAuth account lives
-separately in **~/.jecode/accounts.json**. Both secret stores use owner-only
-permissions where the operating system supports them. Environment API keys
-always win. Model selection saves the provider and model as one change; the
-separate startup flags remain available for automation and override that saved
-choice.
-
-Interactive conversations are stored under **~/.jecode/sessions**, scoped to
-the canonical workspace path. A checkpoint contains normalized messages and
-the settled transcript needed to redraw the conversation. It excludes stored
-provider credentials, OAuth tokens, provider-only opaque response data,
-permission choices, draft composer text, transient footer notices, and pending
-tool state. Session
-files use owner-only modes on POSIX; Windows relies on the user-profile ACL.
-`jecode resume` keeps the same durable session identity and advances that
-session's conversation tree, so reopening and continuing a conversation does
-not create duplicate picker entries. `/new` or a fresh launch starts another
-logical session. **/timeline** shows the completed turns in that tree. Selecting
-an earlier turn changes only the visible path; it creates and persists a branch
-only when the next real message is sent. Cancelling the picker or exiting first
-leaves the durable head untouched, and resume returns to the last branch with a
-persisted turn. Historical tools are displayed but never executed. If a crash
-left the newest turn inside a tool loop, the same session resumes from its
-latest completed ancestor and the next turn becomes a branch because
-provider-only continuation data is intentionally not stored. **/export** writes
-only the currently selected path.
-
-When the model-facing context approaches the selected model's usable capacity,
-Jecode asks the provider for one bounded summary of its older prefix and keeps
-the recent turn exact. The trigger defaults to 85% and can be changed from 50%
-through 95% in **/settings**. Live provider metadata or Ollama's allocated
-runtime context determines the budget when available; a metadata failure falls
-back safely without blocking the turn. Only the provider projection is
-replaced: complete messages, tool evidence, transcript, and conversation tree
-remain unchanged. The branch-local summary anchor is checkpointed with the
-session, so resume reuses it instead of summarizing the same prefix again. A
-failed or cancelled optional summary leaves the original context intact; a
-definite provider context-limit rejection may trigger one compacted retry.
-Internal summary requests count toward provider usage but never appear in the
-transcript or Markdown export. **/compact** requests the same model-aware,
-branch-local compaction immediately, even below the automatic trigger. Very
-small contexts are left unchanged. After selecting a historical branch point,
-send its first new message before compacting so shared history is never
-rewritten.
-
-Jecode has one interface theme: dark Steel. **NO_COLOR** is supported for
+| --- | --- | --- |
+| `--provider` | `JECODE_PROVIDER` | `anthropic` |
+| `--model` | `JECODE_MODEL` | Provider default or interactive selection |
+| `--ollama-host` | `OLLAMA_HOST` | Cloud with an Ollama key, local without one |
+| `--root` | - | Current directory |
+| `--effort` | `JECODE_EFFORT` | `high` |
+| `--max-tokens` | `JECODE_MAX_TOKENS` | `64000`; not sent by `openai-codex` |
+| `--max-steps` | `JECODE_MAX_STEPS` | `40` |
+| `--compaction-percent` | `JECODE_COMPACTION_PERCENT` | `85`; accepts `50` through `95` |
+| `--reduced-motion` | `JECODE_REDUCED_MOTION=1` | Off |
+| `--auto-approve` | `JECODE_AUTO_APPROVE=1` | Off |
+| `--ephemeral` | `JECODE_EPHEMERAL=1` | Off |
+
+Non-secret preferences live in `~/.jecode/settings.json`. Explicitly saved API
+keys live in `~/.jecode/credentials.json`, while ChatGPT OAuth accounts live in
+`~/.jecode/accounts.json`. Environment credentials always take precedence.
+Secret stores use owner-only permissions where the operating system supports
+them.
+
+Jecode has one current interface theme, Dark Steel. `NO_COLOR` is supported for
 terminals and pipelines that disable colour.
 
-## Automation
-
-When stdin or stdout is piped, Jecode switches to a plain line-oriented mode:
-
-~~~console
-printf "explain this project\n" | jecode --root .
-~~~
-
-Batch conversations are never written to the session store.
-
-Dangerous tools stay denied in batch mode unless **--auto-approve** is supplied
-explicitly. A terminal batch failure is written to stderr and exits non-zero,
-so shell pipelines can stop reliably.
-
 ## Safety model
 
 Jecode treats model output, workspace content, tool output, and terminal text as
 untrusted data.
 
-- Tool paths are confined to the selected workspace. Writes reject symlink and
-  junction components, then revalidate the boundary during atomic replacement.
-- Dangerous tools ask by default unless explicitly allowed for the session in
-  **/permissions** or the process started with **--auto-approve**.
-- Credential fields are masked and excluded from transcripts. Approved shell
-  commands receive no secret-bearing environment variables; `SSH_AUTH_SOCK`
-  is preserved so Git and SSH can use the user's agent, which means an approved
-  command can request that agent to authenticate. Recognized credential values
-  are redacted before tool output reaches the model, screen, history, or export.
+- Current filesystem tools are confined to the selected workspace. Writes
+  reject symlink and junction components, revalidate boundaries, and use atomic
+  replacement.
+- Dangerous tools ask by default unless explicitly allowed for the session or
+  the process starts with `--auto-approve`.
+- Credential fields are masked and excluded from transcripts. Recognized
+  credential values are redacted before output reaches the model, screen,
+  history, or export.
+- Approved shell commands receive no secret-bearing environment variables.
+  `SSH_AUTH_SOCK` is preserved so Git and SSH can use the user's agent, which
+  means an approved command may ask that agent to authenticate.
 - ChatGPT OAuth uses PKCE and an exact loopback callback or the OpenAI device
-  flow. Refresh-token rotation is serialized across Jecode processes; OAuth
-  tokens are withheld and redacted like API keys.
+  flow. Refresh-token rotation is serialized across Jecode processes.
 - Terminal control characters are neutralized before rendering.
-- Remote Ollama endpoints require HTTPS. Provider HTTP redirects are rejected
-  rather than followed across an implicit trust boundary.
+- Remote Ollama endpoints require HTTPS, and provider redirects are rejected.
 - Provider handshakes and idle response bodies have finite deadlines. Only
   idempotent catalogue reads retry; generation requests are never replayed.
-- Model and filesystem input are bounded before they reach the screen or
-  provider.
-- Durable session files are versioned, size-bounded, atomically checkpointed,
-  and treated as untrusted when loaded. A live lease prevents the same saved
-  session from being resumed by two Jecode processes at once.
+- Model, terminal, and filesystem input are bounded before use.
+- Session files are versioned, size-bounded, atomically checkpointed, and
+  treated as untrusted when loaded. A live lease prevents concurrent resume.
 
-`run_command` is not an operating-system sandbox: an approved shell command can
-still access files and account resources available to the current user. Review
-commands carefully and reserve **--auto-approve** for controlled environments.
+`run_command` is not an operating-system sandbox. An approved command can still
+access files and account resources available to the current user. Review
+commands carefully and reserve `--auto-approve` for controlled environments.
 
-Please read [SECURITY.md](SECURITY.md) before reporting a vulnerability.
+Read [SECURITY.md](SECURITY.md) before reporting a vulnerability.
 
-## Community
+## Project direction
 
-Jecode is built around people using the product and telling us where the loop
-can improve.
+The terminal is Jecode's current primary interface, not the limit of the
+product. Future interfaces may reuse the same controller, session model, and
+visible control system. Expansion must remain deliberate: no hidden model
+hierarchy, no delegated authority, and no weakening of the zero-dependency
+runtime.
 
-- Ask questions, share workflows, and explore ideas in
-  [GitHub Discussions](https://github.com/giovannijecha/jecode/discussions).
-- Report reproducible bugs and focused feature requests through
-  [GitHub Issues](https://github.com/giovannijecha/jecode/issues).
-- Report security concerns privately through the repository Security tab.
+The single-controller rule limits delegation, not duration or scope. Jecode may
+eventually supervise visible, interruptible processes such as development
+servers, file watchers, and test runners. Those processes remain tools owned by
+the controller; they do not receive independent goals, model loops, or tool
+authority.
 
-Public pull requests are not accepted at this stage; code changes remain a
-maintainer/collaborator workflow. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
-short routing guide and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community
-expectations.
+The selected workspace is the current default filesystem boundary. Any future
+access to additional directories or resources must use explicit, reviewable,
+revocable grants rather than silently widening that boundary.
 
-## Development
+## Build from source
 
-~~~console
+```console
+git clone https://github.com/giovannijecha/jecode.git
+cd jecode
 npm ci --ignore-scripts
-npm run check
-~~~
+npm run build:release
+npm link
+jecode --version
+```
 
-The visual lab exercises the complete production TUI—golden conversation,
-live tool trace, output tails, change-centric diffs, approvals, menus, and
-fields—without a provider, network access, tool execution, or workspace writes:
+Development runs TypeScript directly with `npm run start`. `dist/` is an
+ignored generated tree used only by linked commands and release tarballs.
+`npm run pack:release` rebuilds it from a clean target. Installing the published
+package runs no compilation or installation scripts.
 
-~~~console
-npm run tui:lab
-~~~
+Run the complete project checks with:
 
-For a manual long-session rendering probe, run **npm run bench:transcript**.
+```console
+npm run check
+```
 
-Architecture and security boundaries are documented in
-[docs/architecture.md](docs/architecture.md). Brand assets and usage rules live
+Use `npm run tui:lab` to inspect production TUI components with inert local
+fixtures, and `npm run bench:transcript` for a manual long-session rendering
+probe. Architecture and security boundaries are documented in
+[docs/architecture.md](docs/architecture.md); brand assets and usage rules live
 in [docs/brand.md](docs/brand.md).
 
+## Community
+
+- Ask questions, share workflows, and explore early ideas in
+  [GitHub Discussions](https://github.com/giovannijecha/jecode/discussions).
+- Report reproducible bugs and focused feature requests through
+  [GitHub Issues](https://github.com/giovannijecha/jecode/issues).
+- Report security concerns privately through the repository Security tab.
+
+Public pull requests are not accepted at this stage. Code changes remain a
+maintainer and invited-collaborator workflow. See
+[CONTRIBUTING.md](CONTRIBUTING.md) and
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
 ## License
 
 Jecode is available under the [MIT License](LICENSE).

package/dist/config.js

@@ -3,29 +3,24 @@ import * as path from "node:path";
 import { DEFAULT_COMPACTION_PERCENT, MAX_COMPACTION_PERCENT, MIN_COMPACTION_PERCENT, } from "./context/policy.js";
 import { EFFORTS, readSettings } from "./settings.js";
 import { parseOllamaEndpoint } from "./providers/ollama-endpoint.js";
-const FLAGS = [
+const VALUE_FLAGS = [
     "provider",
     "model",
     "ollama-host",
-    "reduced-motion",
     "effort",
     "max-tokens",
     "max-steps",
     "compaction-percent",
     "root",
+];
+const BOOLEAN_FLAGS = [
+    "reduced-motion",
     "auto-approve",
     "ephemeral",
 ];
+const FLAGS = [...VALUE_FLAGS, ...BOOLEAN_FLAGS];
 export function loadConfig(argv, saved = readSettings()) {
     const flags = parseFlags(argv);
-    // A flag nobody declared is a typo. Swallowed in silence it becomes a
-    // setting the user believes is on, and the run that ignores it looks like
-    // the feature is broken rather than misspelled.
-    for (const name of Object.keys(flags)) {
-        if (!FLAGS.includes(name)) {
-            throw new Error(`unknown flag --${name} (known: ${FLAGS.map((f) => `--${f}`).join(", ")})`);
-        }
-    }
     const providerId = pick(flags.provider, process.env.JECODE_PROVIDER, saved.provider ?? "anthropic");
     const ollamaHost = optional(flags["ollama-host"], process.env.OLLAMA_HOST, saved.ollamaHost);
     const effort = pick(flags.effort, process.env.JECODE_EFFORT, saved.effort ?? "high");
@@ -45,7 +40,9 @@ export function loadConfig(argv, saved = readSettings()) {
         maxSteps: toInt(pick(flags["max-steps"], process.env.JECODE_MAX_STEPS, String(saved.maxSteps ?? 40)), "max-steps"),
         compactionPercent: toPercent(pick(flags["compaction-percent"], process.env.JECODE_COMPACTION_PERCENT, String(saved.compactionPercent ?? DEFAULT_COMPACTION_PERCENT))),
         root: path.resolve(pick(flags.root, undefined, process.cwd())),
-        autoApprove: flags["auto-approve"] === "true" || process.env.JECODE_AUTO_APPROVE === "1",
+        autoApprove: flags["auto-approve"] === "true" ||
+            flags["auto-approve"] === "1" ||
+            process.env.JECODE_AUTO_APPROVE === "1",
         ephemeral: bool(flags.ephemeral, process.env.JECODE_EPHEMERAL, false),
     };
 }
@@ -85,27 +82,55 @@ function toPercent(value) {
     }
     return percent;
 }
-// Accepts --key value, --key=value, and bare --flag (which reads as "true").
+// Value flags accept --key value and --key=value. Boolean flags are bare or
+// take a real boolean value, so an accidental positional argument is never
+// swallowed as configuration.
 function parseFlags(argv) {
     const flags = {};
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
-        if (arg === undefined || !arg.startsWith("--"))
+        if (arg === undefined)
             continue;
+        if (!arg.startsWith("--"))
+            throw new Error(`unexpected argument "${arg}"`);
         const body = arg.slice(2);
         const eq = body.indexOf("=");
-        if (eq !== -1) {
-            flags[body.slice(0, eq)] = body.slice(eq + 1);
+        const name = eq === -1 ? body : body.slice(0, eq);
+        const inline = eq === -1 ? undefined : body.slice(eq + 1);
+        if (!FLAGS.includes(name)) {
+            throw new Error(`unknown flag --${name} (known: ${FLAGS.map((flag) => `--${flag}`).join(", ")})`);
+        }
+        if (BOOLEAN_FLAGS.includes(name)) {
+            if (inline === undefined) {
+                const next = argv[i + 1];
+                if (next !== undefined && ["true", "false", "1", "0"].includes(next)) {
+                    flags[name] = next;
+                    i++;
+                }
+                else {
+                    flags[name] = "true";
+                }
+            }
+            else if (["true", "false", "1", "0"].includes(inline)) {
+                flags[name] = inline;
+            }
+            else {
+                throw new Error(`--${name} must be true or false`);
+            }
             continue;
         }
-        const next = argv[i + 1];
-        if (next !== undefined && !next.startsWith("--")) {
-            flags[body] = next;
-            i++;
+        if (inline !== undefined) {
+            if (inline === "")
+                throw new Error(`--${name} requires a value`);
+            flags[name] = inline;
+            continue;
         }
-        else {
-            flags[body] = "true";
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--")) {
+            throw new Error(`--${name} requires a value`);
         }
+        flags[name] = next;
+        i++;
     }
     return flags;
 }

package/dist/credential-safety.js

@@ -40,17 +40,21 @@ export function credentialRedactor(source = process.env) {
             const ready = [];
             let at = 0;
             while (at < combined.length) {
+                const rest = combined.slice(at);
+                // A complete shorter credential can also be the prefix of a longer
+                // one. Hold that ambiguous suffix until the next chunk proves which
+                // value arrived, otherwise the longer credential leaks its tail.
+                if (rest.length < longest &&
+                    values.some((value) => value.length > rest.length && value.startsWith(rest))) {
+                    pending = rest;
+                    return ready.join("");
+                }
                 const complete = values.find((value) => combined.startsWith(value, at));
                 if (complete !== undefined) {
                     ready.push(REDACTED);
                     at += complete.length;
                     continue;
                 }
-                const rest = combined.slice(at);
-                if (rest.length < longest && values.some((value) => value.startsWith(rest))) {
-                    pending = rest;
-                    return ready.join("");
-                }
                 ready.push(combined[at]);
                 at++;
             }

package/dist/providers/anthropic-wire.js

@@ -1,5 +1,6 @@
 // Translation between the normalized vocabulary and the Anthropic wire shape.
 // Pure functions, no I/O — which is what makes them testable without a key.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return { name: tool.name, description: tool.description, input_schema: tool.input };
 }
@@ -70,10 +71,10 @@ function normalizeUsage(data) {
     if (usage === undefined)
         return undefined;
     return {
-        inputTokens: usage.input_tokens ?? 0,
-        outputTokens: usage.output_tokens ?? 0,
-        cachedInputTokens: usage.cache_read_input_tokens ?? 0,
-        cacheWriteInputTokens: usage.cache_creation_input_tokens ?? 0,
+        inputTokens: wireTokenCount(usage.input_tokens),
+        outputTokens: wireTokenCount(usage.output_tokens),
+        cachedInputTokens: wireTokenCount(usage.cache_read_input_tokens),
+        cacheWriteInputTokens: wireTokenCount(usage.cache_creation_input_tokens),
         reasoningTokens: 0,
     };
 }

package/dist/providers/ollama-wire.js

@@ -6,6 +6,7 @@
 // Chat Completions differs on two points that matter here — a tool result is a
 // message of its own with role "tool", not a block inside a user turn, and tool
 // arguments travel as a JSON string rather than an object.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return {
         type: "function",
@@ -83,8 +84,8 @@ function normalizeUsage(reply) {
     if (reply.usage === undefined)
         return undefined;
     return {
-        inputTokens: reply.usage.prompt_tokens ?? 0,
-        outputTokens: reply.usage.completion_tokens ?? 0,
+        inputTokens: wireTokenCount(reply.usage.prompt_tokens),
+        outputTokens: wireTokenCount(reply.usage.completion_tokens),
         cachedInputTokens: 0,
         cacheWriteInputTokens: 0,
         reasoningTokens: 0,

package/dist/providers/openai-wire.js

@@ -1,6 +1,7 @@
 // Translation between the normalized vocabulary and the OpenAI Responses wire
 // shape: a flat `input` list where tool calls and their outputs are top-level
 // items keyed by `call_id`, rather than blocks nested inside a message.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return {
         type: "function",
@@ -83,11 +84,11 @@ function normalizeUsage(data) {
     if (usage === undefined || usage === null)
         return undefined;
     return {
-        inputTokens: usage.input_tokens ?? 0,
-        outputTokens: usage.output_tokens ?? 0,
-        cachedInputTokens: usage.input_tokens_details?.cached_tokens ?? 0,
-        cacheWriteInputTokens: usage.input_tokens_details?.cache_write_tokens ?? 0,
-        reasoningTokens: usage.output_tokens_details?.reasoning_tokens ?? 0,
+        inputTokens: wireTokenCount(usage.input_tokens),
+        outputTokens: wireTokenCount(usage.output_tokens),
+        cachedInputTokens: wireTokenCount(usage.input_tokens_details?.cached_tokens),
+        cacheWriteInputTokens: wireTokenCount(usage.input_tokens_details?.cache_write_tokens),
+        reasoningTokens: wireTokenCount(usage.output_tokens_details?.reasoning_tokens),
     };
 }
 // Arguments arrive as a JSON string and models vary in how they escape it, so

package/dist/providers/wire-usage.js

@@ -0,0 +1,6 @@
+// Usage comes from remote JSON and eventually reaches the strict session
+// codec. Normalize it at the wire boundary so one malformed counter cannot
+// make an otherwise valid saved session unreadable.
+export function wireTokenCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}

package/dist/tui/app.js

@@ -40,12 +40,21 @@ export async function runApp(session, transcriptRoot, environment = {}) {
     let escapeTimer;
     let stopResize = () => { };
     let stopInput = () => { };
+    let failure;
     // Timers outlive the teardown they were scheduled before. Painting after the
     // terminal has been handed back would write escapes into the user's shell.
     let live = true;
     const done = new Promise((resolve) => {
         closed = resolve;
     });
+    const guard = (action) => {
+        try {
+            action();
+        }
+        catch (error) {
+            fail(error);
+        }
+    };
     const view = () => {
         const now = Date.now();
         return {
@@ -94,8 +103,9 @@ export async function runApp(session, transcriptRoot, environment = {}) {
     const render = (block) => {
         if (block !== undefined)
             transcript.invalidate(block);
-        if (live && frameTimer === undefined)
-            frameTimer = setTimeout(draw, FRAME_MS);
+        if (live && frameTimer === undefined) {
+            frameTimer = setTimeout(() => guard(draw), FRAME_MS);
+        }
     };
     const feedback = feedbackController((next) => {
         state.feedback = next;
@@ -143,6 +153,10 @@ export async function runApp(session, transcriptRoot, environment = {}) {
         terminal.leave();
         closed?.();
     }
+    function fail(error) {
+        failure ??= { error };
+        quit();
+    }
     function requestQuit() {
         const activity = state.activity;
         if (activity === undefined) {
@@ -159,7 +173,7 @@ export async function runApp(session, transcriptRoot, environment = {}) {
         const activity = begin(kind, label);
         state.activity = activity;
         state.status = label;
-        spinTimer = setInterval(() => {
+        spinTimer = setInterval(() => guard(() => {
             if (!session.config.reducedMotion)
                 state.spin++;
             let activeTool;
@@ -171,7 +185,7 @@ export async function runApp(session, transcriptRoot, environment = {}) {
                 break;
             }
             render(activeTool);
-        }, session.config.reducedMotion ? 1_000 : SPIN_MS);
+        }), session.config.reducedMotion ? 1_000 : SPIN_MS);
         render();
         return activity;
     }
@@ -253,39 +267,47 @@ export async function runApp(session, transcriptRoot, environment = {}) {
             }
         }
     }
-    terminal.enter(session.config.reducedMotion);
-    stopResize = terminal.onResize(() => {
-        paint.invalidate();
-        draw();
-    });
-    stopInput = terminal.onInput((chunk) => {
-        if (escapeTimer !== undefined)
-            clearTimeout(escapeTimer);
-        for (const key of keys.push(chunk)) {
-            if (!live)
-                break;
-            input.handle(key);
-        }
-        if (!live)
-            return;
-        escapeTimer = setTimeout(() => {
-            escapeTimer = undefined;
+    try {
+        terminal.enter(session.config.reducedMotion);
+        stopResize = terminal.onResize(() => guard(() => {
+            paint.invalidate();
+            draw();
+        }));
+        stopInput = terminal.onInput((chunk) => guard(() => {
+            if (escapeTimer !== undefined)
+                clearTimeout(escapeTimer);
+            for (const key of keys.push(chunk)) {
+                if (!live)
+                    break;
+                input.handle(key);
+            }
             if (!live)
                 return;
-            for (const key of keys.flush())
-                input.handle(key);
-            if (live)
-                render();
-        }, ESCAPE_MS);
-        render();
-    });
-    draw();
-    try {
-        await resumeAtLaunch;
+            escapeTimer = setTimeout(() => guard(() => {
+                escapeTimer = undefined;
+                if (!live)
+                    return;
+                for (const key of keys.flush())
+                    input.handle(key);
+                if (live)
+                    render();
+            }), ESCAPE_MS);
+            render();
+        }));
+        draw();
+        if (resumeAtLaunch !== undefined)
+            await Promise.race([resumeAtLaunch, done]);
         if (live)
             await done;
+        if (failure !== undefined)
+            throw failure.error;
     }
     finally {
-        await session.persistence?.close();
+        try {
+            quit();
+        }
+        finally {
+            await session.persistence?.close();
+        }
     }
 }

package/dist/tui/picker.js

@@ -1,6 +1,6 @@
 // One interaction model for every terminal selector.
 import { row } from "../ui/render.js";
-import { elide } from "../ui/width.js";
+import { elide, graphemes } from "../ui/width.js";
 import { menuWindow, renderMenuRows } from "./components/menu.js";
 import { promptCursor, promptLine } from "./components/prompt.js";
 const WINDOW = 6;
@@ -33,7 +33,7 @@ export function type(picker, text) {
 export function backspace(picker) {
     if (picker.searchable !== true || (picker.query ?? "") === "")
         return picker;
-    return withQuery(picker, Array.from(picker.query ?? "").slice(0, -1).join(""));
+    return withQuery(picker, graphemes(picker.query ?? "").slice(0, -1).join(""));
 }
 export function clear(picker) {
     return withQuery(picker, "");

package/dist/ui/terminal-text.js

@@ -38,5 +38,8 @@ export function terminalText(text, options = {}) {
     return safe;
 }
 function isBidiControl(code) {
-    return (code >= 0x202a && code <= 0x202e) || (code >= 0x2066 && code <= 0x2069);
+    return code === 0x061c ||
+        (code >= 0x200e && code <= 0x200f) ||
+        (code >= 0x202a && code <= 0x202e) ||
+        (code >= 0x2066 && code <= 0x2069);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giovannijecha/jecode",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "An owned coding agent with zero external runtime dependencies.",
   "license": "MIT",
   "repository": {