QA target: source and package line 0.2.9.
This inventory describes implemented behavior only. A platform is marked tested only when the corresponding runtime or CI environment actually executed it.
| Feature | Purpose and flow | Commands/configuration | Dependencies and platforms | Failure behavior and limits | Test status |
|---|---|---|---|---|---|
| Native Rust CLI | Parses commands with Clap, resolves the current directory as workspace, opens SQLite storage, and dispatches to feature handlers. | utharness --help, utharness --version; UTHARNESS_HOME and UTHARNESS_DB isolate state. |
Rust 2021 workspace; Linux, macOS, Windows builds in CI. | Invalid arguments return readable Clap errors; missing workspace paths fail without creating a database. | Passed local and hosted CI; version regression added in crates/utharness-cli/tests/cli.rs. |
| SQLite persistence | Stores workspaces, sessions, messages, tasks, checkpoints, events, memories, tool calls, permission decisions, and audit records. WAL mode, migrations, and FTS5 search are enabled. | init, sessions list/new, memory add/list/search, checkpoint; default data is below the user data directory. |
Bundled SQLite through rusqlite; offline-capable. | Database open, migration, or integrity errors are returned; FTS queries remain bounded. | Passed Rust unit/integration persistence tests and CLI lifecycle tests. |
| Offline chat | Persists a user prompt and deterministic assistant response when no provider is configured. | utharness chat "prompt". |
No provider credential required. | Never pretends to have performed external work; explicitly instructs users to configure a provider for model-backed execution. | Passed local CLI integration and hosted smoke tests. |
| Provider routing | Sends OpenAI-compatible chat-completion requests to the configured provider endpoint and parses plain JSON or fenced JSON. | OPENROUTER_API_KEY, UTHARNESS_PROVIDER_URL, UTHARNESS_MODEL; autonomous invokes the route. |
reqwest with rustls; network and credential required for real providers. | Missing/empty credentials, HTTP errors, invalid JSON, empty content, and timeouts fail explicitly. | Request shape unit-tested; local mock-provider autonomous E2E passed. Real credential/provider test not repeated in this QA cycle. |
| Bounded autonomous planner | Requests a JSON read-only plan, recommends local skills, applies SAFE policy, executes at most eight read-only steps, redacts output, and persists events. | utharness autonomous PROMPT [--max-steps N] [--workspace PATH]. |
OpenAI-compatible endpoint or local mock; git for git-status/diff steps. | Shell, network, writes, secrets, unsupported tools, and workspace escapes are denied or fail; plan length is clamped to 1–8. | Passed local mock-provider E2E, Rust tests, and CLI smoke. |
| Feature | Purpose and flow | Commands/configuration | Dependencies and platforms | Failure behavior and limits | Test status |
|---|---|---|---|---|---|
| Permission policy | Allows read-only tools in SAFE mode, prompts for mutation in ASK/CUSTOM, and allows all explicitly selected TRUSTED actions. | run --command CMD; add --allow only after review. |
Native Rust; no external service. | SAFE shell execution returns nonzero and prints a review instruction; destructive denylist remains blocked even with --allow. |
Safe denial, trusted execution, and destructive denial passed in local matrix; policy unit tests passed. |
| Path containment | Canonicalizes requested paths and rejects paths outside the workspace. | Used by autonomous file tools and workspace commands. | Native filesystem. | Missing paths and canonicalization errors are readable; traversal outside the workspace is rejected. | Covered by policy unit tests and autonomous tool path logic; additional boundary fixture remains a follow-up. |
| Secret redaction | Redacts common KEY=, TOKEN=, and SECRET= assignments before tool output is persisted or printed. |
Applied internally to autonomous output and reviewed shell command messages. | Native Rust. | Unknown secret formats may not be redacted; credentials are not stored by installers. | Common assignment unit test and mock-provider output check passed; broader token-pattern fuzzing remains a risk. |
| Diagnostics | Reports version, workspace, storage, database, permissions, shell, provider, skills, and runtime state. Termux adds Android-specific checks. | utharness doctor; utharness termux doctor. |
Shell metadata and optional commands; no root required. | Produces pass/warning/failure guidance instead of aborting on optional capability absence. | Local and hosted CLI smoke passed; real device checks pending. |
| Feature | Purpose and flow | Commands/configuration | Dependencies and platforms | Failure behavior and limits | Test status |
|---|---|---|---|---|---|
| Focus-mode Ink TUI | Keeps header/banner, conversation, composer, and telemetry visible while the conversation area changes with terminal size. | utharness, utharness tui; tui --headless for non-interactive status. |
Node.js 22, React 18, Ink 5, @inkjs/ui, chalk, gradient-string, cli-spinners, figures, string-width, wrap-ansi, execa, chokidar, zod. | Missing UI bundle falls back to source UI lookup; missing Node produces an actionable error. | Typecheck, UI tests, build, PTY capture, and Rust-to-Ink bridge passed on Linux. |
| Responsive branding | Renders UTHY/UTHARNESS branding with amber-orange-coral styling and compact fallbacks. | Automatic width and color detection; NO_COLOR=1 for monochrome fallback. |
ANSI terminal; truecolor/256/16-color degradation. | Narrow screens use compact text; screenshots are simulated Linux PTYs, not proof for every emulator. | 40, 60, 80, 120, 160, and 220-column captures generated; compact and wide images visually inspected. |
| Conversation and tool cards | Presents UTHY/YOU rows, timestamps, tool progress, completion, results, and inline cards. | Keyboard-first TUI; overlays and prompt behavior are implemented in the Ink bundle. | Ink runtime and PTY. | Long output is wrapped/truncated according to available space; full provider streaming remains bounded by current runtime behavior. | Screenshot evidence exists for focus, palette, and skills screens; deeper interactive keyboard E2E remains limited. |
| Termux mobile layout | Detects TERMUX_VERSION/PREFIX, selects mobile/narrow/standard breakpoints, and keeps composer/status visible. |
utharness termux info; widths <50, 50–89, 90+. |
Termux environment; optional Termux:API is not required. | Real soft keyboard, Android resizing, and device rendering require Android validation. | Simulated Termux PTY and UI unit tests passed; physical-device test pending. |
| Feature | Purpose and flow | Commands/configuration | Dependencies and platforms | Failure behavior and limits | Test status |
|---|---|---|---|---|---|
| Indexed registry | Normalizes built-in and imported metadata into SQLite/FTS records with categories, health, permissions, compatibility, and source details. | skills, skills search, skills categories, skills info, skills import. |
Bundled SQLite; source adapters. | Invalid or unsafe manifests are rejected; external metadata is not blindly installed. | Registry lifecycle and manifest validation tests passed. Current default seed reports 31 indexed built-ins; the 100k benchmark is not equivalent to 100k shipped records. |
| Lazy installation | Installs reviewed built-ins into an isolated registry path and retains quarantine records for removal/rollback. | skills install, skills remove, skills rollback, skills update. |
Native filesystem and SQLite. | External skills remain metadata-only unless explicitly allowed and still require a trusted adapter. | Built-in lifecycle integration passed; external execution remains intentionally blocked. |
| Health and sync | Re-evaluates installed skills and imports bounded public source metadata. | skills test, skills doctor, skills sync --source ... --limit N. |
Network only for bounded sync. | Source failures are reported per adapter; unsafe permissions quarantine or reject the skill. | Built-in health checks passed; live bulk-source sync is bounded and not run in this cycle. |
| Feature | Purpose and flow | Commands/configuration | Dependencies and platforms | Failure behavior and limits | Test status |
|---|---|---|---|---|---|
| Signed APT repository | Publishes Android aarch64 and x86_64 packages, Packages indexes, Release, InRelease, Release.gpg, public key, and repository checksums to GitHub Pages. |
`curl -fsSL https://uthumany.github.io/utharnessly/termux/install.sh | bash; then pkg install utharness`. |
Termux package manager, curl, signed repository key; no root. | Missing signing secrets fail the release workflow; unsigned metadata is local-test-only. |
| Prefix package layout | Installs only $PREFIX/bin/utharness, $PREFIX/lib/utharness, and $PREFIX/share/utharness; user state stays under the documented $HOME paths. |
pkg upgrade utharness, pkg uninstall utharness. |
Android/Termux package payload. | Maintainer scripts preserve user data; internal updater does not overwrite package-managed files. | Host layout and CI Android builds passed; real Termux install and uninstall remain pending. |
| Optional Termux:API | Discovers and guards battery, clipboard, notification, device, TTS, speech, Wi-Fi, storage, sharing, vibration, and dialog commands. | utharness termux api [capability], pkg install termux-api. |
Optional Termux:API package/app. | Missing API commands produce an optional/unavailable result; core runtime continues. | Missing/present fake-command branches passed; real Android app integration pending. |
| Feature | Purpose and flow | Commands/configuration | Dependencies and platforms | Failure behavior and limits | Test status |
|---|---|---|---|---|---|
| NPM launcher | Downloads the matching native release archive on first use, verifies SHA256SUMS, caches it, and forwards arguments. |
npm install -g utharnessly, npx utharnessly, pnpm add -g utharnessly; aliases utharnessly and utharness. |
Node.js 18+ launcher; native release currently Linux x64, macOS x64/arm64, Windows x64. | Unsupported architecture and download/checksum/extraction errors are explicit. | Local pack/install/version checks passed at source version 0.2.8; NPM 0.2.8 live installation and metadata verification passed. |
| PyPI launcher | Mirrors the NPM launcher through a dependency-free Python entry point and checksum-verified cache. | python -m pip install utharnessly, pipx, uv, uvx. |
Python 3.9+ launcher; native release target must match. | Unsupported target and network/checksum failures are explicit; uninstall prints cache cleanup. | Local wheel/sdist install and version checks passed at source version 0.2.8; PyPI 0.2.8 live installation and metadata verification passed against the canonical index. |
| Shell/PowerShell installers | Select release archive by OS/architecture, download checksums, install to a user path, and report PATH instructions. | packaging/install.sh; packaging/install.ps1. |
curl/tar/sha256sum or PowerShell; supported native targets only. | No fabricated ARM/iOS/FreeBSD package; unsupported targets receive source/remote guidance. | Script syntax and live v0.2.8 release verification passed; fresh native shell install on every OS is not available here. |
Linux x64 is locally exercised. Linux x64, macOS x64/arm64, and Windows x64 are built and tested in hosted CI. Android/Termux aarch64 and x86_64 packages and signed repository metadata are built and verified remotely, but real Android devices/emulators were not available. iOS/iPadOS terminal apps are remote-host workflows rather than claimed local native targets. FreeBSD, ARM desktop variants, Homebrew, apt, Nix, winget, Deno, Rush, Lerna, and cnpm remain unsupported or source/prerequisite paths unless separately published and tested.