@spinalfluid/ultrac 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,657 @@
-# Temporary Holding Version
+# ultrac
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`ultrac` is the terminal-native coding agent for Ultrac - a Claude Code-style CLI that
+understands your repository, proposes and makes tightly scoped edits, runs verification, and keeps
+an auditable session transcript. It is built for Cosmic 1 over Ultrac's private, OpenAI-compatible
+API. Cosmic 1 is live on GCP, with a native 262,144-token context window shared
+between input and output. The hosted API supports streaming and native tool calls.
+
+## Install
+
+```bash
+npm install -g @spinalfluid/ultrac
+ultrac login
+ultrac doctor
+ultrac
+```
+
+The npm package is public. Model access still requires an approved Ultrac account and `ultrac login`.
+Requires Node.js >= 22.12.0. The command is `ultrac`; the package is `@spinalfluid/ultrac`.
+The unrelated public packages named `ultrac` and `ultracode` are different products.
+
+The CLI checks npm at most once every 24 hours and shows a terminal notice when a newer release is
+available. Registry failures stay silent during normal sessions. Check or update explicitly with:
+
+```bash
+ultrac update --check
+ultrac update
+```
+
+The update command installs `@spinalfluid/ultrac@latest` globally through npm. It never sends Ultrac API
+credentials to npm, and it does not update itself in the middle of an active interactive session.
+For local testing before a registry release, build and install the verified tarball:
+
+```bash
+pnpm check
+pnpm verify:install
+npm pack
+npm install -g ./spinalfluid-ultrac-0.1.0.tgz
+ultrac login
+```
+
+The `echo` provider is an offline wiring check and does not call Cosmic 1. Interactive
+sessions and `ultrac run` execute tools on your machine with the permissions you grant.
+Hosted background tasks need a separate worker deployment and are not ready on GCP.
+
+## Sign in
+
+```bash
+ultrac login     # opens the browser; sign in on ultrac.io; the CLI is authenticated
+ultrac whoami    # show the current sign-in state and where it came from
+ultrac logout    # drop local credentials and revoke the minted key
+```
+
+For interactive use, `ultrac login` opens `https://ultrac.io/cli/login` (or the same path on a local
+site). Approve the CLI using your existing website account; the site mints a key and the CLI stores
+it in `~/.ultrac/auth.json` with `0600` permissions. You do not need to create or paste a key.
+
+For scripts and CI, do not run the browser sign-in flow. Create a dedicated API key in the account's
+`/keys` page, store it in your CI secret manager, and expose it to the command as `ULTRAC_API_KEY`.
+The environment key takes precedence over a stored browser login. `ultrac login --manual` prompts
+for an existing key, and `ultrac login --key <key>` verifies and stores one; use these only when you
+intentionally need a local saved credential, not as the default CI setup. Avoid putting secrets in
+shell history, command arguments, project config, or source control. An approved Ultrac account is required for model access.
+
+The minted key is checked with `GET <base>/models` before it is saved: a 401/403 is refused and
+nothing is written; if the API cannot be reached the key is saved anyway with a warning.
+
+### Cosmic 1, in a repo
+
+Start a live model session in your repository:
+
+```bash
+ultrac login
+cd your-repo
+ultrac
+```
+
+Default and `coding` modes advertise file edits (`write_file`, `replace_in_file`, `multi_edit`,
+`apply_patch`) and `run_shell`. Interactive sessions prompt before a write or a shell. For `run_shell`,
+the prompt shows the full command, resolved working directory, timeout, and a warning that it runs as
+your user with access to files and network available to your account. `once` approves only that
+command; `always` grants shell access to all shell-using tools for the rest of the session. Unattended
+`ultrac run` needs `--allow-write` and `--allow-shell` (or a trusted
+`.ultrac/config.json`). `plan` enforces a read-only tool set; `review` also disables writes, while
+its diagnostics tool still requires explicit shell permission. `ultrac task` queues on `/v1/runs` and
+needs a hosted worker, which is not deployed on GCP; ordinary `ultrac` / `ultrac run` talk to `/v1/chat/completions` and
+do not wait on that worker.
+
+### Endpoint and environment
+
+The authenticated Ultrac API is served by the site under `/v1` (`/v1/chat/completions`, `/v1/models`,
+`/v1/runs`, served model `cosmic-1`). The default base URL is `https://ultrac.io/v1`. Precedence,
+highest first:
+
+| Setting | Flag | Environment | Stored | Default |
+| --- | --- | --- | --- | --- |
+| API key | `login` (browser), `login --manual`, or `login --key <existing-key>` | `ULTRAC_API_KEY` | `~/.ultrac/auth.json` | - |
+| Base URL | `--base-url <url>` (on `login`, `ask`, `run`, `task`/`tasks`, and the interactive session) | `ULTRAC_BASE_URL` | `~/.ultrac/auth.json` | `https://ultrac.io/v1` |
+| Key page | - | `ULTRAC_LOGIN_URL` | - | `/keys` on the base URL's origin (`--manual` only) |
+
+`ULTRAC_API_KEY` always wins over the stored key; `ultrac doctor` and `ultrac whoami` report which
+source is in use. Use a CI secret manager to inject it for automation. For local development against
+a site running on your machine, point the CLI at `http://localhost:3000/v1`:
+
+```bash
+ultrac login --base-url http://localhost:3000/v1
+# or, without saving anything:
+ULTRAC_API_KEY="$LOCAL_ULTRAC_API_KEY" ULTRAC_BASE_URL=http://localhost:3000/v1 ultrac ask "say hello"
+```
+
+Other variables: `ULTRAC_HOME` (global home directory, default `~/.ultrac`), `ULTRAC_MODEL`
+(default model name, default `cosmic-1`), `ULTRAC_AST_GREP_BIN` (see Safety Model). The CLI reads
+only `ULTRAC_*` names; there is no legacy fallback.
+
+## Use
+
+Start an interactive session (this is the default command):
+
+```bash
+ultrac
+```
+
+Or seed it with a first prompt:
+
+```bash
+ultrac "Find the main entry points and summarize the architecture"
+```
+
+Inside a session:
+
+- Type to talk to Ultrac; it gathers repository context first and can call tools.
+- Gated tools (file writes, shell, network) prompt for approval: `once` / `always` / `no`.
+- Coding commands: `/plan [task]`, `/coding`, `/review [focus]`, `/diff [--staged]`,
+  `/test [instructions]`, `/init`, `/max-steps [number]`.
+- Context and sessions: `/context`, `/compact [focus]`, `/usage`, `/status`, `/save`,
+  `/sessions`, `/resume <id>`, `/new`, `/clear`.
+- Controls: `/help`, `/model [name]`, `/mode [name]`, `/permissions [readonly|workspace|full]`,
+  `/allow <perm>`, `/deny <perm>`, `/whoami`, `/tools`, `/memory`, `/skills`, `/exit`.
+  Permission profiles change tool grants; they are not operating-system sandboxes. `readonly`
+  revokes write, shell and network access and suppresses permission prompts until explicitly granted.
+  `/usage` shows reported agent-step counts, excluding compaction and ancestor-session calls.
+- Skills can add their own slash commands (see [Skills](#skills)). `/help` lists them; built-ins
+  always win a name clash.
+- Transcripts are saved under `.ultrac/sessions` in the workspace on exit. They contain prompts
+  and tool results. On POSIX, a newly created sessions directory uses mode `0700` and atomic
+  session files use mode `0600`; saving into an existing directory does not change that directory's
+  mode.
+- MCP tool results sent to the model are bounded previews. When archiving succeeds, the full
+  structured result is stored under `.ultrac/sessions/<session-id>.artifacts`; on POSIX, the
+  artifact directory is set to mode `0700` and new files are created with mode `0600`. These
+  permissions are local access controls, not encryption. The CLI does not change repository ignore
+  rules or automatically delete session data: exclude `.ultrac/sessions/` from version control and
+  manage retention yourself.
+
+Non-interactive, scriptable one-shot runs:
+
+```bash
+ultrac run "Review this patch" --mode review
+ultrac run "Inspect this repo" --provider echo     # offline smoke provider, no key
+ultrac run --continue <session-id> "Follow up on the last result"
+```
+
+One prompt, one reply, no tools or workspace context - the smallest end-to-end check of the wiring:
+
+```bash
+ultrac ask "say hello"                                   # streams the reply to stdout
+ultrac ask "say hello" --base-url http://localhost:3000/v1 --model cosmic-1
+ultrac ask "say hello" --provider echo                   # offline
+ultrac ask "say hello" --json --no-stream                # {"provider","model","text"}
+```
+
+### Tasks
+
+Hosted background tasks are not deployed on GCP. Use `ultrac run` for testing.
+
+A task is one model request that runs off the request path: the API queues it (`POST /v1/runs`),
+a worker next to the model executes it and appends events, and the CLI follows the event stream
+(`GET /v1/runs/<id>/events`, server-sent events). A task can take minutes, so the stream is built
+to be left and rejoined: the server ends every connection at its own cap, and the CLI reconnects
+with `Last-Event-ID` and misses nothing. Close the laptop, come back, `tasks follow` the same id.
+
+```bash
+ultrac task "Summarize the trade-offs of event sourcing"   # queue, then stream the answer
+ultrac task --chat <chatId> "Follow up on the above"       # attach the run to a dashboard chat
+ultrac task --no-follow "Long job"                         # print the run id and return
+ultrac task --json "Long job"                              # one JSON line per event
+ultrac tasks                                               # list your runs (id, status, age, title)
+ultrac tasks show <id>                                     # the record, with the output once done
+ultrac tasks follow <id>                                   # stream from the start (or --since <seq>)
+ultrac tasks cancel <id>                                   # stop a queued or running task
+echo "a long prompt" | ultrac task -                       # read the prompt from stdin
+```
+
+`ultrac tasks run` is the same command as `ultrac task`. While following, the answer streams
+to stdout as it arrives and everything else - the run id, restarts, tool calls, the outcome - goes to
+stderr, so `ultrac task "..." > answer.md` captures the answer alone. The exit code is the run's
+outcome: `0` done, `1` failed, `130` cancelled. Ctrl-C asks the server to cancel the run and exits
+`130`; with `--detach` it exits and leaves the run going, to be picked up again with `tasks follow`.
+`--json` prints `{ "id", "event", "data" }` per event (the SSE id is the event's seq), the first line
+being `"event": "created"` with the run, the last the terminal `done`, `error`, or `status` event.
+A reclaimed attempt (`status: running` with `attempt > 1`) streams from the beginning again; the
+CLI notes it on stderr and resets, the same way the dashboard does. `--no-follow` prints the id on
+stdout, or the whole run with `--json`; `tasks show` and `tasks list` accept `--json` as well.
+
+API errors print as one line with the stable code, e.g. `too_many_active_runs (HTTP 429): ...` when
+the account already has 3 queued or running tasks, or `run_not_found (HTTP 404): ...` for an id that
+is not yours. Tasks use the same key and base URL as every other command (see
+[Endpoint and environment](#endpoint-and-environment)).
+
+When a terminal event is marked `truncated: true`, the CLI reads the finished run record for its bounded
+output. In JSON mode this adds an `output` event with `{ text, source: "run_record" }`. If the record
+cannot be confirmed within the retry window, it adds `output_incomplete`, keeps the text received so
+far, and exits non-zero rather than treating a prefix as complete.
+
+## Providers
+
+- `ultrac` (default) - Cosmic 1 via the authenticated Ultrac API (`https://ultrac.io/v1`, model
+  `cosmic-1`). The API uses the OpenAI-compatible chat-completions wire format with SSE streaming
+  and native tool calling; this does not mean a separate OpenAI provider is supported. The hosted
+  Cosmic 1 model is live; an approved account and valid API key are required.
+- `echo` - a deterministic local stub for smoke tests and offline wiring checks; no network, no
+  key, and no real model work. It is not a way to use the harness with another model or to get a
+  real model answer.
+
+### Fallback chain
+
+`.ultrac/config.json` can name an ordered chain that retries and, as a last resort, falls back to
+the offline `echo` stub after a retryable transport failure:
+
+```json
+{
+  "provider": "ultrac",
+  "model": "cosmic-1",
+  "fallback": {
+    "chain": [{ "provider": "ultrac" }, { "provider": "echo" }],
+    "attemptsPerProvider": 3,
+    "baseDelayMs": 250,
+    "requestTimeoutMs": 60000
+  }
+}
+```
+
+`model` is optional per entry and defaults to that provider's default model. Only transport failures
+- network errors, timeouts, HTTP 408, 429, and 5xx - retry with jittered backoff and then fail over.
+Authentication (401/403) and bad-request (400) failures are terminal and do not fall through to a
+different model. Their diagnostics show a safe category and HTTP status, not the provider's raw
+message. A stream that fails *after* tokens have been emitted keeps its partial reply instead of
+restarting on another model. The REPL prints a notice naming the model that took over, and its banner
+names the entry that is actually answering rather than the configured chain head.
+`requestTimeoutMs` defaults to 120,000 milliseconds for CLI configuration. It bounds a complete or
+native-tool attempt and time-to-first-token for text streams; set it to `0` only when an upstream
+deadline is guaranteed. Retry waits are cancelled immediately by Ctrl-C.
+
+The current `not_configured` response for Cosmic 1 is terminal and does not fall through to `echo`.
+If a configured transport fallback does use `echo`, its deterministic placeholder is not a model
+answer or a completed task.
+
+Provider failures show a safe category and, when available, an HTTP status rather than the provider's
+response body or SDK error message. MCP startup status likewise reports only a failure phase and
+allowlisted process error code; child stderr is drained and discarded. This does not redact
+intentional tool output: shell stdout/stderr and MCP tool results are passed through to the model and
+may be shown in the terminal.
+
+An MCP tool-call timeout, in-flight cancellation, or transport loss reports an unknown outcome: the server may have completed
+the action. The CLI does not retry automatically; after a timeout or cancellation it sends a best-effort cancellation
+notification, which is cooperative and does not roll back an action. Verify remote state before
+retrying. The CLI does not provide duplicate prevention or rollback guarantees for MCP side effects.
+Cancellation before dispatch is reported as not sent.
+
+Interactive turn cancellation also reaches process-backed tools. A pre-aborted call does not spawn;
+an active command receives termination followed by forced process-group cleanup after a two-second
+grace period on POSIX. Partial output is retained and marked cancelled. Descendants that escape the
+original group are not guaranteed to stop; Windows descendant cleanup is best-effort. Cancellation
+does not roll back files, Git changes, or remote actions, and is not a universal interrupt for every
+tool's filesystem operation.
+
+Native tool calling is selected from the *head* of the chain, because that is the entry that answers
+until it breaks. When a turn reaches a later entry that has no native tool calling, the chain renders
+the transcript and tool schemas into the text JSON tool protocol and parses the reply back into
+structured calls instead of skipping the entry - chain order is your preference ranking, so a later
+model is never promoted over an earlier one just for having a richer protocol. The REPL prints a
+notice when that happens, so a session started with `native tools` never silently changes protocol.
+No entry is ever passed over without an event.
+
+## Trusting a workspace
+
+`.ultrac/config.json` lives in the repository, so whoever wrote the repository wrote it. Two of its
+fields make the CLI act: `permissions` turns on write, shell or network without a prompt, and
+`mcpServers` names commands to start. Those two are honoured only for a workspace you have trusted;
+everything else in the file - model, mode, tools, budgets - applies regardless.
+
+Opening an untrusted workspace whose config asks for either shows what it asks for and offers to
+trust it; the record lives in `~/.ultrac/trusted-workspaces.json`, never in the repository. Approval
+is bound to a fingerprint of the permission grants and normalized MCP launch settings, including
+commands, arguments, environment values and passthrough names. Those values are not copied into the
+trust store. Changing security-sensitive settings requires approval again; changing model, mode or
+other unrelated settings does not. Older path-only approvals are withheld until renewed. `ultrac run`
+never asks - it is the non-interactive entry point - so it withholds the grants and says so on
+stderr; `--allow-*` flags still apply to that run, because those are your words rather than the
+repository's.
+
+```bash
+ultrac trust            # allow this workspace's config to grant permissions and start servers
+ultrac trust --revoke   # stop
+ultrac trust --list     # workspaces with a current approval
+```
+
+A server's `envPassthrough` cannot name a credential either way: the environment a server starts
+with has every secret-shaped variable removed, and a passthrough list cannot ask for one back.
+
+## Long code generation
+
+The Ultrac provider does not set an output-token cap. Input, tool schemas and output share the
+model's finite context window. The SDK request timeout matches GCP's one-hour request lifetime;
+SDK retries are disabled so the harness can cancel a failed GPU request before retrying it.
+
+Native generation hands off one complete tool call at a time. As soon as the first call's full
+JSON arguments and required fields arrive, the provider explicitly cancels the remaining GPU
+generation, then returns that call to the permission-gated local executor. This prevents the model
+from continuing to generate dependent reads and repeated overwrites before seeing tool results.
+Large implementations can use repeated complete file edits or append sections; no code-length
+limit is imposed by this handoff. A missing finish marker, malformed call, or a reported length
+cutoff is an error rather than a completed action. Both input schemas and tool permissions remain
+enforced locally.
+
+## Context budget
+
+Cosmic 1 runs on a 262,144-token window - about 1,048,000 characters at 4 characters per token - and a
+request that does not fit comes back as a 400, not as a shorter answer. The whole tool registry is 48
+tools, including `ask_user`; their names, descriptions, and JSON Schemas serialise to 29,410 characters
+when `--tools all` is selected. Three things keep a session inside the window and the model focused
+on the tools it needs.
+
+**Each mode advertises the tools it actually uses.** `--tools` selects the schemas sent to the model;
+`plan` and `review` additionally enforce their mode allowlists at dispatch and disable workspace
+writes. Other modes rely on the usual tool permission gates.
+
+| mode | tools | characters |
+| --- | --- | --- |
+| `default` | 16 | 9,152 |
+| `plan` | 12 | 7,339 |
+| `review` | 12 | 8,312 |
+| `coding` | 20 | 13,035 |
+| `security` | 24 | 14,321 |
+| everything (`--tools all`) | 48 | 29,410 |
+
+`default` is the compact core - read, list, search, shell, edit, patch, `git status`/`git diff`,
+todos, plus shared memory reading, skills, delegation and `ask_user`. `coding` adds tests, diagnostics, package scripts, and AST search; `security` adds local
+evidence tools (hashes, strings, hex, secret scan, timeline, blame) and `fetch_url`; `plan` and
+`review` enforce their fixed tool sets and disable workspace writes. `review` diagnostics still need
+shell permission. `ultrac tools --mode coding` lists a mode's set, and `ultrac tools --budget` prints
+the table above from the live registry.
+
+Two escape hatches, on `ultrac` and `ultrac run`:
+
+```bash
+ultrac --tools all                          # advertise the whole registry, as before
+ultrac --tools read_file,search_files,git_diff   # advertise exactly these
+```
+
+The same thing in `.ultrac/config.json`, as `"tools": "all"` or `"tools": ["read_file", "git_diff"]`.
+
+**Ordinary tool results are capped at 6,000 characters** before they go into the transcript. A result over
+the cap keeps its head and ends in a marker saying how many characters were cut and how to reach the
+rest; `read_file` prefers a line range over a hard cut, returning whole lines and naming the
+`startLine` to continue from. The full output is still recorded in the saved session under
+`.ultrac/sessions` - the cap is about what the model re-reads on every later turn. Change it with
+`--max-tool-result-chars`, `ULTRAC_MAX_TOOL_RESULT_CHARS`, or `"maxToolResultChars"` in the config.
+Successful `ask_user` answers are kept whole so a constraint at the end is not lost. They still
+count against the context window, so an oversized request fails locally before it reaches the API.
+
+**Every request is measured before it is sent.** The provider adds up the system prompt, the
+serialised tools, and the transcript. Over 60% of the window, the harness first tries to compact
+the oldest turns that would otherwise be dropped into a bounded `[compacted-context]` summary.
+If summarising fails or there is not enough room, it falls back to dropping whole old turns, so an
+assistant `tool_calls` entry and its `tool` replies are removed together. The system prompt, pinned
+user messages (including follow-up corrections), successful `ask_user` results, and the turn being
+answered are retained verbatim when they fit; if those required messages cannot fit the full window,
+the request fails locally rather than silently dropping them. Startup workspace context and older
+assistant/tool history may be summarized or dropped; generated summaries are not lossless records.
+The budget uses a character estimate (about four characters per token), not the model's tokenizer.
+The hard check keeps a 2% wire margin for tokenizer and request-envelope variance. You are told when
+compaction is applied or skipped and when trimming starts. A request that still cannot fit fails
+locally with the numbers - system, tools, history, window - instead of being sent to come back a 400.
+In the REPL, `/context` runs the same planner used by the next request and reports system, tool, and
+history estimates, selected and omitted messages, and prompt/window headroom.
+
+Direct user messages and successful `ask_user` question/answer pairs are saved in order and replayed
+as pinned user messages on `--continue`; they are not executable tool calls. Their order is kept,
+but their exact placement among the old assistant/tool steps is not. Assistant/tool history may
+still be summarized or dropped to fit the context window. `/clear` starts a new conversation. Older
+sessions without a constraint ledger retain the known initial task plus the existing task summary
+and tool-step restore; later direct messages and `ask_user` answers cannot be recovered from those
+files.
+
+The window defaults to 262,144 tokens and is set with `--context-tokens`, `ULTRAC_MODEL_CONTEXT_TOKENS`,
+or `"contextTokens"` in the config, in that order of precedence. The session banner prints the
+budget it started with:
+
+```
+tools 16 (mode default) ≈ 9,152 chars · window 262,144 tokens · tool results capped at 6,000 chars
+```
+
+Every `ask`, `run`, and interactive process creates a private `0600` JSONL lifecycle log under
+`.ultrac/logs` and prints its path. It records correlated provider attempts, request heartbeats,
+first chunks, retries, cancellation, compaction, tools, subagents, and checkpoints. Prompt text,
+tool arguments/results, request bodies, headers, and credentials are replaced by lengths and
+SHA-256 fingerprints; they are never written raw. The directory is ignored by workspace discovery
+and Git.
+
+For a more detailed opt-in context audit trail, set `ULTRAC_CONTEXT_REPORT_PATH` to a JSONL file path. Each model request
+records roles, message lengths and SHA-256 fingerprints, selected/omitted and pinned counts, compaction
+source counts, native tool-schema count and fingerprint, estimated budget, truncation-marker counts,
+duration, and partial file-read provenance for structured `read_file` and `read_many_files` results.
+The file section distinguishes results kept in the provider request from results dropped by its budget
+planner, and reports source ranges/byte limits plus whether the transcript cap may have cut the result.
+It does not enumerate the repository or claim that unlisted files were excluded. Startup context,
+search results, shell/MCP output, compaction summaries, and older results without structured metadata
+are counted as unknown rather than attributed to specific files.
+
+By default the report never writes prompt, transcript, tool-schema text, or file paths. To include
+validated workspace-relative paths in the file section, separately set `ULTRAC_CONTEXT_REPORT_PATHS=1`.
+Paths may reveal proprietary project structure; the report file is created with mode `0600` either way.
+Message fingerprints can still identify known text, so keep the report private. Metadata does not
+reveal the exact text sent, and this partial provenance is not a complete file-access log.
+
+For opt-in freshness diagnostics, also set `ULTRAC_CONTEXT_STALE_CHECK=1`. The setting has no effect
+without `ULTRAC_CONTEXT_REPORT_PATH`. Before a request, Ultrac rechecks only structured reads that
+survive that request's context budget plan. The report records `fresh`, `changed`,
+`missing_or_unreadable`, or `unknown` statuses and counts, not file hashes or paths. This check is
+limited to the exact selected read payload (a line range or byte prefix), not the whole file or a
+version lock; edits outside that payload may still report `fresh`, and a file can change after the
+check. Legacy/restored, transcript-capped, unstable, and otherwise unsupported reads are `unknown`.
+Revalidation reads at most 1 MiB per request and stops after 500 ms; timed-out work may finish in the
+background. The diagnostic does not refresh context or prevent the model from acting on stale text.
+
+## Memory
+
+Ultrac keeps a file-based memory, like Claude Code, so durable facts and preferences survive across
+sessions. One fact per Markdown file with YAML frontmatter, plus a `MEMORY.md` index that is small
+enough to load into the agent's context every turn. Two scopes:
+
+- **global** - `~/.ultrac/memory/` (shared across every workspace)
+- **project** - `.ultrac/memory/` (checked in with the repo)
+
+```bash
+ultrac memory list                                   # index across both scopes
+ultrac memory add no-pill --description "UI rule" --type feedback --body "No pill+dot indicators."
+echo "Use aws login for tokens." | ultrac memory add aws-auth --description "AWS auth" --scope global
+ultrac memory show no-pill
+ultrac memory search composer
+ultrac memory remove no-pill
+```
+
+During a session the agent sees the memory index automatically and pulls a specific memory in full
+with the `memory_read` tool. It persists new durable facts with `memory_write` (needs `--allow-write`),
+and can prune stale ones with `memory_delete`. Types are `user`, `feedback`, `project`, `reference`.
+
+## Skills
+
+Every installation includes eight built-in playbooks: `coding-workflow`, `debugging`, `testing`,
+`security-review`, `refactoring`, `release-readiness`, `frontend-quality`, and `backend-reliability`.
+They are embedded in the CLI artifact, work offline, and require no separate skill downloads.
+Use `ultrac skills list` and `ultrac skills show coding-workflow` to inspect them.
+Skills supply instructions; they do not grant shell, write or network access or provide a model backend.
+
+Personal skills override built-ins; trusted project skills override personal skills. Untrusted
+project skills cannot hide installed playbooks or register slash commands. Skill files are limited
+to 64 KiB, with at most 128 directories per custom scope. Symlinked skill directories/files and
+sensitive paths are skipped. Run `ultrac trust` only for a repository whose instructions you accept.
+
+Skills are reusable SKILL.md playbooks the agent can load on demand - the same idea as Claude Code's
+custom skills. Each skill is a folder with a `SKILL.md` (YAML frontmatter + Markdown instructions):
+
+```
+~/.ultrac/skills/<name>/SKILL.md      # global (personal, every workspace)
+.ultrac/skills/<name>/SKILL.md        # project (checked in; overrides a global skill of the same name)
+```
+
+```bash
+ultrac skills create open-pr --description "Open a pull request" \
+  --when "the user asks to open a PR" --permissions shell,network
+ultrac skills list
+ultrac skills show open-pr
+```
+
+Only each skill's name + description are injected into context (progressive disclosure). When a task
+matches, the agent calls the `skill` tool to load the full steps, then follows them. `list_skills`
+enumerates what is available.
+
+### Custom slash commands
+
+A skill that adds a `command:` key to its frontmatter is also callable as a REPL slash command:
+
+```yaml
+---
+name: open-pr
+description: Open a pull request with a generated title and body.
+command: open-pr
+argument-hint: <branch>
+---
+```
+
+Typing `/open-pr feature-x` seeds the turn with the skill's instructions plus the verbatim arguments.
+Built-in commands always win a name clash, project scope outranks global scope, and malformed or conflicting command
+declarations appear under `/help`. Untrusted or unsafe files are skipped before reading their declarations.
+
+## Safety Model
+
+The CLI treats the current workspace as the trust boundary.
+
+- Paths are resolved inside the workspace root.
+- `inspect_project`, `repo_map`, `repo_handbook`, `context_bundle`, `verification_plan`,
+  `verification_report`, `read_file`, `read_many_files`, `list_files`, `search_files`,
+  `ast_search`, `inspect_artifact`, `hex_dump`, `extract_strings`, `scan_secrets`,
+  `file_timeline`, `task`, Git inspection tools (including `git_blame`), and session search tools
+  are available by default. `ast_search`, `inspect_artifact`, `extract_strings`, and `task` are
+  callable with no permission, but each degrades rather than escalating: `ast_search` answers from
+  its text fallback until `--allow-shell` unlocks the `ast-grep` binary, `inspect_artifact` and
+  `extract_strings` use a Node implementation until `--allow-shell` unlocks `file`/`strings`, and
+  `task` keeps its child transcript in memory until `--allow-write` lets it be persisted.
+- Secret-like files such as `.env*`, `.npmrc`, `.netrc`, `.ssh/*`, `.aws/credentials`, `*.pem`,
+  `*.key`, `*.p12`, and `*.pfx` are hidden from listings and refused by direct file reads.
+- `git_worktree_summary` reports branch, upstream divergence, dirty-file counts, and diff stats
+  without shell permission.
+- Every Git tool spawns `git` with repo-controlled command execution disabled. A repository can
+  name a command in its own `.git/config` that git then runs - `core.fsmonitor` on `git status`,
+  `diff.external` on `git diff` - which would be arbitrary execution under tools that declare no
+  permissions and are handed to read-only subagents. All Git invocations go through one helper that
+  prepends neutralising `-c` flags (`core.fsmonitor`, `core.hooksPath`, `core.pager`, `core.askPass`,
+  `core.sshCommand`, `core.gitProxy`, `credential.helper`, `diff.external`, `protocol.ext.allow`,
+  `uploadpack.packObjectsHook`), which override both repo and global config.
+- `verification_plan` reads Git state and package scripts to recommend the checks an agent should
+  run before claiming completion. It does not execute project scripts.
+- `context_bundle` packages selected files, repository shape, Git state, and task instructions into
+  a Markdown or JSON context artifact. Rendering is read-only; saving to `.ultrac/context` requires
+  `--allow-write`.
+- `verification_report` renders Git evidence, check outcomes, and handoff notes into a Markdown or
+  JSON report. Writing the report to `.ultrac/reports` requires `--allow-write`.
+- `multi_edit` requires `--allow-write` and applies several exact replacements to one file atomically (all-or-nothing).
+- `memory_read`, `memory_list`, `memory_search`, `list_skills`, `skill`, `todo_write`, and `todo_read` are read-only and available by default; `memory_write` and `memory_delete` require `--allow-write`.
+- `write_file` requires `--allow-write`.
+- `replace_in_file` requires `--allow-write` and refuses ambiguous single replacements.
+- `apply_patch` requires `--allow-write` and applies unified diffs inside the workspace.
+- `git_commit` requires `--allow-write` and stages either selected paths or all worktree changes; any files
+  already staged anywhere in the repository are included in the commit. Before staging, it checks the full
+  existing index plus the requested candidate paths for known sensitive names (`.env`, `.env.*`, `.netrc`,
+  `.npmrc`, `.pypirc`, `.git-credentials`, private-key names/extensions, non-public `.ssh` paths,
+  `.git/config`, `.aws/credentials`, and `.ultrac/config.json`) and generated
+  `.ultrac/{sessions,archives,episodes,subagents,context,reports}` artifacts. It refuses when any effective
+  Git clean/process filter is configured because staging could transform content
+  or execute a command. This is a path-name guard, not secret-content scanning, and it does not isolate against
+  concurrent filesystem changes; inspect and stage intentionally outside the tool when it refuses.
+- `git_push` requires `--allow-network` and pushes a named or current branch.
+- `ast_search` matches code by syntax-tree shape using the optional `ast-grep` binary. Calling it
+  needs no permission, but running that binary - including the `--version` probe used to detect it -
+  is a child process and requires `--allow-shell`. Without shell, or with no binary installed, it
+  spawns nothing and degrades to the `search_files` text path, reporting `backend: "text-fallback"`
+  plus a `degradedReason` so approximate results are not over-trusted. `ULTRAC_AST_GREP_BIN`
+  overrides binary detection; the value must be a path made only of `[A-Za-z0-9_./+@:-]`, with no
+  `..` segment, resolving to an existing regular file (relative values resolve against the
+  workspace, so a bare name is a workspace file, not a `PATH` lookup - unset the variable to get the
+  `PATH` search of `ast-grep`/`sg` back). A refused override degrades to the fallback and reports
+  why.
+- `task` spawns a read-only child agent with its own context window for search-heavy exploration or
+  a focused review pass, and returns only its summary. The child is always read-only regardless of
+  what the parent holds, cannot spawn its own subagent, and is bounded by turn, tool-call, and
+  wall-clock caps. Its full transcript is always recorded in the parent's saved session for audit,
+  and is additionally written to `.ultrac/subagents` when the session holds `--allow-write`; a
+  read-only session keeps it in memory only and leaves the workspace untouched.
+
+  Several `task` calls in one model step run **concurrently**, so five independent searches cost
+  about as long as the slowest one rather than the sum of all five. While they run, the terminal
+  shows a live line - how many have finished, how long it has been, what it has spent:
+
+  ```
+    ○ ultrac  task ×6  2/6 agents done · 1m 04s · ↓ 128.4k tokens
+  ```
+
+  Concurrency is decided per tool and conservatively: a call may overlap its neighbours only when it
+  needs neither write nor shell access. Anything that writes runs alone, and results are always
+  recorded in the order the model asked for them, so what the model reads back never depends on
+  which call happened to finish first. Children are one level deep - a subagent still cannot spawn
+  its own.
+
+  Each model response can request at most 30 tool calls. A top-level one-shot run or interactive
+  turn can dispatch at most 120 top-level calls; each subagent run has its own budget. An over-budget
+  response runs none of its tools and ends with a clear error. Each run's safe batch is limited to 8
+  concurrent calls, with results kept in request order; this is not a process-wide cap because
+  subagents run their own batches. Provider failover does not reset a turn's budget.
+- `run_package_script` requires `--allow-shell` and only runs scripts declared in `package.json`.
+- `run_tests` requires `--allow-shell`. It detects the project's runner (vitest, jest, `node --test`,
+  pytest, `cargo test`, `go test`) and returns pass/fail counts plus per-failure records with file,
+  line, expected/actual, a category, and a likely cause instead of raw stdout.
+- `diagnostics` requires `--allow-shell`. It runs the project's type checker (and a cheap linter when
+  one is installed) and returns deduplicated `{file, line, column, code, severity, message}` records.
+  Pass `paths` to scope results to the files you just edited.
+- `run_shell` requires `--allow-shell`. It refuses a short list of obviously destructive command
+  patterns (`rm -rf`, `git reset --hard`, `sudo`, `mkfs`, fork bombs, curl-piped-to-shell), which is a
+  speed bump and not a sandbox: the command reaches a real shell, and a denylist over shell syntax can
+  always be worked around. `--allow-shell` grants broad, unsandboxed shell access; commands run as
+  your user and can access files and network resources available to your account. Use it only in a
+  workspace you trust.
+- Child-process tools redact common API keys, cloud credentials, tokens, and SSH agent handles from
+  the environment before running project code.
+- `fetch_url` requires `--allow-network`. It is an HTTP(S) client for a URL you name (GET by
+  default; POST/PUT/PATCH/DELETE with a body), follows bounded redirects, and blocks loopback and
+  private addresses. That block is not something the model can switch off - set
+  `ULTRAC_ALLOW_PRIVATE_HOSTS=1` in the environment if you need it, which is a decision you make,
+  not the agent. One request per call; it is not a port scanner.
+- `list_processes` requires `--allow-shell` and runs `ps` with a fixed argument list on this
+  machine. It is host inventory, not a remote scan.
+- `hex_dump` and `extract_strings` refuse the same sensitive paths `read_file` does.
+  `scan_secrets` reports that those files exist without opening them, and redacts every match it
+  does return from source.
+- Session transcripts are stored under `.ultrac/sessions` in the target workspace.
+- A `--continue` session records its immediate parent and replays the bounded saved lineage (up to
+  32 ancestors and 64 MiB of session files). Keep parent session files if you need to continue the
+  full history; missing parents or limits stop continuation instead of silently shortening it.
+- `ultrac sessions list|show|search` makes those transcripts inspectable from the terminal.
+- `ultrac sessions export <id>` turns one transcript into a Markdown or JSON episode package for
+  audits, evals, and handoffs. An export contains only that session and names any parent dependency;
+  it does not bundle the parent transcript. Exports can include `--outcome` and `--notes`, and record
+  saved context bundles and verification report artifacts used during the run.
+
+## Local package smoke (maintainers)
+
+To check a locally built tarball before release, run `npm pack` and pass the resulting archive to
+the repository smoke script:
+
+```bash
+archive="$(npm pack --silent)"
+node scripts/smoke-package-install.mjs "$archive"
+```
+
+The script currently supports POSIX systems. It installs that `.tgz` into a temporary prefix with
+temporary home and npm config, disables lifecycle scripts and network access, checks the installed
+package and `ultrac` binary, runs only `--version` and `--help`, uninstalls the package, and removes
+the temporary directory. It uses the existing `~/.npm` cache when present; set
+`ULTRAC_NPM_CACHE` to another pre-populated npm cache if needed. Missing offline dependencies are
+reported as a prerequisite; the script never falls back to the network. The smoke checks only a
+trusted local build: it does not establish archive signature or provenance, and it is not a sandbox
+for untrusted packages. The script is repository-only and is not included in the published tarball.
+
+## Documentation and support
+
+Product documentation lives at [ultrac.io/docs](https://ultrac.io/docs). Bugs, questions, and
+access requests go through [ultrac.io/contact](https://ultrac.io/contact). There is no public issue
+tracker: the source repository is private.
+
+## Licence
+
+`@spinalfluid/ultrac` is proprietary software, copyright Aditya Pundir. Installing it gives you a
+revocable, non-transferable right to *run* the published build - nothing more. Copying,
+modification, redistribution, and reverse engineering are reserved. The full terms are in the
+`LICENSE` file that ships inside the package, and they are the whole agreement: nothing on this
+page grants a right the licence withholds.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node