Wayfinder: trustworthy daily OpenCode replacement

[joaomj]

Destination

TinyHarness becomes a trustworthy, extensible daily replacement for OpenCode, preserving native SmallHarness capabilities by default while making the desktop browser the primary client.

A successful destination provides durable and auditable crash recovery, isolated worktree sessions, safe per-turn undo, visible automatic model routing, portable profiles, searchable recall, proposal-only self-improvement, and a later personal Hermes-style Telegram client.

Product decisions so far

• TinyHarness replaces Vulcan Agent as the product lineage.
• The initial product is for one user across their own machines.
• Trust and durability are the first differentiator.
• After interruption, preserve committed history, identify uncertain effects, and let the user explicitly retry or continue.
• Browser-first, desktop-first; same-machine access initially.
• Preserve the terminal client as a fallback and keep advanced native features available there until exposed in the browser.
• Preserve all native SmallHarness capabilities by default. Changes are expressed as deltas from upstream SmallHarness v1.2.0 at b8b6a6d.
• Review and sync future upstream SmallHarness changes selectively.
• Use a real OpenAI-compatible provider.
• Multiple sessions may be saved, but only one agent turn runs at a time initially.
• Each coding session uses an isolated git worktree. A successful session produces a commit on its session branch.
• Undo restores the exact pre-turn file state without erasing audit history.
• Keep native SmallHarness approval behavior, with an additional non-overridable default denial for detected mutations outside the active project.
• The browser is conversation-first; operational details are available on demand.
• Initial history needs list and resume, not search or cross-session memory.
• Long-term additions: portable profiles, searchable recall, proposal-only self-improvement, visible automatic model routing, and a personal Hermes-style Telegram client.
• Telegram scope: authorized private use with text, voice, files, commands, interruption, and topic/session continuity; no group automation or broader messaging gateway requirement.

Resolved lifecycle decisions

• A browser session is created only after the user selects an existing local Git repository. A project cannot be attached later.

• A new session opens directly into an empty conversation with the selected project identity visible and its prompt composer ready. Repository and worktree details are available on demand.

• The project chooser shows recent repositories and offers an explicit native directory picker for any local repository; only a validated repository can create a session.

• The browser opens on a saved-session list showing each session's project, latest activity, and state. Selecting a session resumes its conversation; a clear action creates a new session.

• A browser disconnect does not interrupt the active turn. Reopening its session reattaches the user to the same turn, with its accumulated transcript and current live status, without resubmitting the prompt.

• Stopping a turn requests cancellation while preserving its partial transcript and file changes for inspection. The session marks the turn interrupted and offers a new prompt or explicit continuation.

• A native approval requirement pauses the browser turn in an inline conversation card. The card shows the requested action and relevant details, provides explicit allow and deny controls, and remains in the transcript.

• A failed turn is retried automatically only when TinyHarness can prove it caused no file mutation or external side effect. A changed or uncertain turn is preserved and requires an explicit user recovery decision.

• File changes are not shown during execution. They become visible when the turn reaches a terminal outcome.

• A successful turn automatically creates a commit on its isolated session branch. The browser then shows the commit identifier and final diff.

• Browser and terminal clients share one persisted session, but exactly one controls it during an active turn or approval. The other client is read-only until an explicit handoff transfers control.

• If agent work completes but its required session-branch commit cannot be created, the session is marked completed-but-uncommitted. The browser preserves the final diff and commit error and offers retrying the commit or a terminal handoff; it never reports silent success.

• If the isolated worktree is missing but its source repository is available and verified, TinyHarness recreates the worktree. If the source repository is unavailable, the session remains read-only with its transcript visible until the location is repaired.

Frontier

Unblocked:

• Grilling: resolve browser session lifecycle #2 — resolve the browser session lifecycle
• Research: define durable turn recovery semantics #3 — define durable turn recovery semantics
• Research: define the native compatibility baseline #5 — define the native compatibility baseline
• Research: define worktree, undo, and completion semantics #6 — define worktree, undo, and completion semantics
• Research: evolve native routing into automatic visible routing #7 — define automatic visible routing
• Research: define the external-mutation safety envelope #8 — define the external-mutation safety envelope
• Prototype: find the client-independent harness boundary #4 — find the client-independent harness boundary
• Research: specify checkpoint storage and durability #9 — specify checkpoint storage and durability
• Research: define exact-workspace platform boundary #10 — define the exact-workspace platform boundary
• Define session branch integration and residue policy #11 — define session branch integration and residue policy

Blocked:

None.

Not yet specified

These areas remain in fog until the frontier reveals stable prerequisites:

• Portable profile contents, export/import behavior, and synchronization transport.
• Searchable recall ranking, trace access, and relationship to native project memory.
• Proposal-only self-improvement evidence thresholds and proposal format.
• Personal Hermes-style Telegram session mapping and media behavior.
• Exact release and version boundaries.
• Browser visual design and frontend technology.
• Remote access beyond the same machine.
• OS-enforced filesystem confinement and unattended operation.

Out of scope for this map

• Removing native SmallHarness capabilities merely to simplify the fork.
• Telegram group automation or additional messaging platforms.
• Public multi-user hosting.
• Automatic self-modification.
• Producing an implementation roadmap before the architectural decisions are resolved.

Map rules

• Tickets resolve decisions; they do not implement destination features.
• Work only one frontier ticket per planning session.
• Record each resolved answer here before opening newly visible tickets.
• Implementation tickets are created only after the route is clear.

Durable recovery decisions

• SQLite is the authoritative per-session recovery journal; transcript and trace JSONL remain human-readable, idempotently repairable projections.
• Turns, provider attempts, approvals, hooks, and tools have stable identities and explicit durable states.
• Every hook and mutation operation commits intent and reconciliation evidence before crossing its side-effect boundary, then commits its result separately.
• An intent without a terminal result is uncertain. Recovery reconciles it or asks the user; it never automatically replays an uncertain mutation.
• Interrupted provider streams never enter conversation history as complete assistant messages. Retrying creates a linked new attempt and does not claim exactly-once provider delivery.
• Approvals bind to an operation and canonical effective-input hash; rewritten input invalidates approval.
• Completion requires the final assistant message and every referenced operation to be terminal and durable.
• Audit records are bounded and field-aware-redacted; credentials, authorization headers, raw environments, and unbounded outputs are not journaled.
• Worktree/undo evidence remains with Research: define worktree, undo, and completion semantics #6; external mutation classification and confinement remain with Research: define the external-mutation safety envelope #8.

Research artifact: docs/research/durable-turn-recovery.md.

Native compatibility decisions

• The compatibility baseline is SmallHarness v1.2.0 at b8b6a6d; only documented, user-visible outcomes are preserved by default.
• Shared core engine commitments are turn/tool results, approval, session artifacts, workspace boundaries, configured integrations, and serialized mutation-capable operations.
• Native terminal commands and workflow artifacts remain supported by the terminal client; terminal rendering, keystrokes, and ANSI layout are terminal-only.
• Optional configured integrations, including hooks, MCP, web/image, critic, and provider-dependent features, retain their contracts only when exposed and are never enabled implicitly.
• Provider wire formats, auto-selection heuristics, read-only scheduling, cache-key granularity, and current JSONL/checkpoint limitations are implementation-observed rather than compatibility promises unless later explicitly adopted.
• A mutating client must pass four core behavior gates: turn/safety, session/restart, mutation artifact/undo, and representative task evaluation. Each optional integration and core-terminal workflow is gated when exposed or claimed.
• Each future compatibility-relevant upstream sync begins an indexed docs/upstream-sync/ record that captures the upstream SHA, disposition, retained outcomes, evidence, and safety review.
• Issue Prototype: find the client-independent harness boundary #4 may assume a client-neutral seam around turns, tools, approvals, events, session identity, and artifacts, but not terminal rendering or input-loop types.

Research artifact: docs/research/native-compatibility-baseline.md.

Worktree, undo, and completion decisions

• Session creation accepts only a clean source checkout in the first release and anchors a dedicated, locked worktree and collision-resistant session branch to the source HEAD commit without mutating the source checkout.
• Before any mutation intent, TinyHarness durably captures and verifies a whole-workspace checkpoint: HEAD and index identity plus tracked, untracked, and ignored path presence, bytes or symlink target, type, and portable executable mode. Unsupported or incoherent workspaces fail closed.
• Undo is a journaled, conflict-aware restoration from immutable pre-turn and post-turn manifests. It restores exact pre-turn files and index without erasing audit history, and never overwrites externally divergent content or claims to reverse effects outside the worktree.
• Successful turns automatically enter a recoverable commit protocol. TinyHarness durably generates the message, commits the exact terminal turn delta with normal hooks, verifies parent/tree/message/ref identity, then exposes the commit and final diff. Commit failure is completed-but-uncommitted, never silent success.
• External ref movement, missing or moved worktrees, interrupted tools, commits, or undo operations enter reconciliation or needs-attention states; recovery never blindly retries, resets, cleans, force-updates, or force-removes.
• Abandonment preserves changes before it becomes terminal. Physical cleanup is separate, revalidates identity and recoverability, and never automatically force-removes a dirty or uncertain worktree.

Research artifact: docs/research/worktree-undo-completion.md.