@andorra-labs/code 0.0.0-stage → 0.1.5

package/LICENSE.md

@@ -0,0 +1,38 @@
+# Andorra Code — Proprietary Software License
+
+Copyright © 2026 Andorra Labs. All rights reserved.
+
+Andorra Code is proprietary software made available free of charge for authorized use.
+
+**1. License Grant**
+
+You are granted a limited, non-exclusive, non-transferable, revocable license to download, install, and use Andorra Code for personal or commercial purposes, subject to these terms.
+
+**2. Restrictions**
+
+Except where applicable law expressly permits otherwise, you may not:
+
+- Redistribute, resell, sublicense, or republish the software.
+- Modify, decompile, disassemble, or reverse-engineer the software.
+- Remove proprietary notices or copyright information.
+- Create or distribute derivative works without written authorization.
+
+**3. Ownership**
+
+All intellectual property rights in Andorra Code remain with Andorra Labs and its licensors. No ownership rights are transferred to users.
+
+**4. No Warranty**
+
+The software is provided "AS IS", without warranties of any kind, to the maximum extent permitted by applicable law.
+
+**5. Termination**
+
+This license terminates upon a material violation of its terms. Upon termination, you must cease using and uninstall the software.
+
+**6. Third-Party Components**
+
+Third-party components remain subject to their respective licenses, which take precedence for those components.
+
+**7. Additional Terms**
+
+Use of connected services may be governed by separate Terms of Service and Privacy Policies.

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
-
-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.
+# Andorra Code
+
+Andorra Code is a **terminal-first coding agent with a configurable graph-based harness** from Andorra Labs.
+
+Free and signed-out users run a single Software Engineer agent. A free account can build one custom graph of up to 3 nodes in the graph editor; an Andorra paid membership enables more and larger graphs and the Orchestrator. Run `andorra login` (or `/login`) to sign in or create an account; credentials persist securely on this machine. See [accounts, membership and hosted Jev setup](docs/getting-started/accounts.md).
+
+The primary product experience is the `andorra` CLI. Running it from a repository opens an interactive TUI in the same general class of workflow as Codex CLI, Claude Code, and Kimi CLI: the user can describe software work, watch tools execute, inspect progress, answer questions, approve gated actions, and continue interacting with the coding agent from the terminal.
+
+The difference is that Andorra Code's coding behavior is not fixed in one hard-coded agent loop. The active coding harness is a graph composed of full autonomous Agent nodes, deterministic actions, conditions, loops, parallel branches, review stages, approvals, and terminal states. Users can use bundled preset graphs or build their own.
+
+## Primary experience
+
+From a project directory:
+
+```bash
+andorra
+```
+
+This opens the Andorra Code TUI and loads the currently selected graph for that project/user context. If no custom selection exists, Andorra Code can start with a bundled default software-engineering graph.
+
+```text
+┌ Andorra Code · Software Engineer ───────────────────────────────────────────┐
+│ cwd ~/code/portal      branch feature/auth      runtime local · connected   │
+├───────────────────────┬─────────────────────────────────────────────────────┤
+│ GRAPH                 │ RUN                                                 │
+│                       │                                                     │
+│ ✓ Understand task     │ Andorra                                             │
+│ ✓ Repository analyst  │ I found the authentication flow in src/auth/.       │
+│ ● Software engineer   │                                                     │
+│ ○ Tests               │ ● shell  pnpm test auth                             │
+│ ○ Browser QA          │ ● edit   src/auth/session.ts                         │
+│ ○ Security review     │                                                     │
+│ ○ Code review         │                                                     │
+│                       │                                                     │
+├───────────────────────┴─────────────────────────────────────────────────────┤
+│ > Add coverage for expired refresh tokens too.                              │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ /graph  /node  /state  /logs  /artifacts  /pause  /help          ctrl+c     │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Manage harness extensions and sign-in
+
+Use `/skills` to list, install, enable, disable or remove local/GitHub skills; `/mcp` to add, edit, enable, disable or delete stdio and HTTP servers; and `/plugins` to manage bundles of skills and MCP servers. Files live under `~/.andorracode` (or `ANDORRACODE_HOME`), and changes apply to the next task. `/logout` signs out of your Andorra account (then `/login` to switch accounts); `/logout codex` signs out of Codex and exits while retaining configuration and API-key settings. See [extension management](docs/guides/extensions.md) for formats, authentication, permissions and examples.
+
+### Track the task plan
+
+`/dashboard` opens persistent cards for per-model session tokens, current/latest task timing, todos, and the active graph neighbourhood. Ctrl+B returns to the preserved transcript; Ctrl+N cycles displayed model statistics, and Ctrl+G pages the ASCII graph. Steering, clarification and approvals use the same bottom composer. See [Dashboard](docs/guides/tui.md#dashboard).
+
+`/browser` opens a local GUI with projects and sessions in a sidebar, conversation and tool activity, and progress. Send prompts, steer or cancel runs, and answer runtime questions and approvals while the CLI remains available. Sessions retain history; settings control the age filter and light/dark appearance. See [Browser workspace](docs/guides/browser.md).
+
+The Orchestrator creates a shared Todo list at the start of a run. Agent stages update it with `?` pending, `?` in progress, and `?` completed items. Press **Ctrl+T** to expand or collapse the list; **Ctrl+O** toggles tool and approval details. See [Todo progress](docs/guides/tui.md#todo-progress).
+
+### Switch harness graphs inside the TUI
+
+The `/graph` command opens the graph selector:
+
+```text
+/graph
+
+Graphs
+  ● Software Engineer        preset
+    Fast Fix                 custom
+    Full SDLC                custom
+    Review Only              custom
+```
+
+The user can switch between bundled presets and graphs they created in the configuration application. A run is always pinned to one immutable graph revision. If work is already executing, changing graphs starts or prepares a new run rather than silently mutating the graph underneath the active run.
+
+### Graph editor (implemented)
+
+```bash
+andorra        # Use /providers to add or edit a provider first
+andorra graph  # Open the bundled browser editor
+```
+
+The editor ships inside the npm package and runs on localhost. `andorracode --configure` also opens it. Use the searchable Node Library to add your own Agents, import Agents others shared, or insert the built-in Orchestrator, Software Engineer and QA Tester presets. Right-click an Agent to Use, Clone, Share (export as JSON) or Delete it; built-in Agents cannot be deleted. Configure models, capabilities, completion ports, typed inputs/outputs and internal subagent roles in the Inspector. Connect one outcome to several destinations, edit each edge's input mappings, and use Join all/any for explicit synchronization.
+
+New graphs begin with an optional Orchestrator that researches the codebase and clarifies requirements and design choices with you before routing to Engineering, QA or another configured stage. Delete it to start directly at the first connected successor, falling back to the first remaining node when no successor remains. Saved version 3 graphs retain that start without restoring intake. Its optional subagent maximum is a ceiling, not a target. Ctrl-click matching node types to route a shared outcome to one destination in bulk. See [Graph Builder](docs/guides/graph-builder.md) for editing behavior and [Orchestrator intake and bulk routing](design/decisions/0011-orchestrator-entry-and-bulk-routing.md) for the original design.
+
+Save immutable revision snapshots, then select a graph with `/graph` in the TUI or `andorra --graph <id>`. Headless `--prompt` runs cannot answer Orchestrator questions and return `needs_clarification`. Existing graphs load without destructive migration. The current top-level scheduler runs ready nodes serially; bounded subagents can run inside an Agent invocation. `andorra graph --no-open` prints the URL without opening a browser; Ctrl+C stops the server. Missing providers produce guidance to run `andorra` and open `/providers`.
+
+### Agent MCP server (graph automation and session monitoring)
+
+Trusted external agents such as Hermes and OpenClaw can launch `andorra mcp-server --stdio` and use MCP tools to create graph drafts, upsert Agent/Condition/Loop/Join nodes, connect outcome ports, configure prompts/providers, validate actionable errors, and publish immutable revisions. The MCP resource `andorra://graph/architecture` teaches agents the graph structure before editing. Other tools query saved sessions by project, status, and last X minutes or identify work needing human feedback. See [agent MCP setup, tool contract and examples](docs/agents/mcp-server.md) and the [QA plan](tests/agent-centric-mcp-test-plan.md). The same server also runs Andorra as a subagent for a host that wants the work done rather than the graph authored; see [subagent mode](docs/agents/subagent-mode.md).
+
+### Session debug log
+
+Every conversation already keeps a trajectory journal (shown with `/status` in the interactive TUI, or at startup with `--debug`) with each model request and response — including per-call token usage and duration — plus every runtime event such as tool calls with arguments, outputs and timings. Add `--debug` (`andorra --debug` or `andorra --prompt "task" --debug`) to also record the conversation layer around them: a `session.started` banner with the invocation details (created before the first fallible startup step, so failed invocations still explain themselves), a `session.context` record with the resolved providers and workspace; `command.started` / `command.completed` entries with the wall-clock cost of every prompt and slash command, including commands issued while a run is active (steering messages are marked `command.steer`); `command.error` entries for CLI-level failures that never reach the runtime; and a closing `session.ended` summary with session-wide token totals, written even when startup or a run crashes. Credentials (stored keys and the values of provider-named environment variables, including ones added mid-session through `/providers`) and provider reasoning content are redacted from every record, and in `--json` mode the trajectory path is announced on stderr so stdout stays machine-readable.
+
+This browser delivery replaces the earlier Electron plan. See [manual Agents, routing and handoffs](design/decisions/0010-manual-agents-routing-handoffs.md) for schema version 2, explicit data mapping, subagent authority/workspace rules and current limitations. The visual editor follows the [AndorraBot V3 baseline](design/gui-design/). Alongside manual editing, Graph Studio offers an AI edit proposal route, and the agent MCP server supports external agent-driven graph authoring.
+
+## How the harness works
+
+A graph is not merely a sequence of LLM calls. Agent nodes are full autonomous tool-using loops that can inspect repositories, run shell commands, edit files, use Git, browse, test, and iterate until their assigned responsibility is complete.
+
+The default Agent-node executor is a shared **basic ReAct loop**. Each Agent-node invocation has its own role, tools, permissions, and execution counters. Direct handoffs can reuse conversation history with the same provider profile and model; isolation is configurable:
+
+```text
+model
+  ↓
+tool call → tool result
+  ↑             ↓
+  └──── model ──┘
+        ...
+        ↓
+validated node completion
+        ↓
+graph chooses the next edge/node
+```
+
+The same `react-basic` executor can power an Orchestrator, Implementer, PR Review Fixer, QA Agent, or Deployment Troubleshooter while each node has its own model, system prompt, tools, permissions, context, and completion contract.
+
+Edges never own ReAct loops. Deterministic operations such as running a known test command, evaluating a condition, waiting for CI, or deploying a known artifact should normally use deterministic nodes rather than an LLM loop.
+
+See [`design/architecture/react-agent-loop.md`](design/architecture/react-agent-loop.md) for the implementation contract.
+
+A full software-development graph may look like:
+
+```text
+Task
+  ↓
+Understand / Requirements
+  ↓
+Repository Analysis
+  ↓
+Plan
+  ↓
+Software Engineer
+  ↓
+Automated Tests ─────────── fail ─────┐
+  ↓ pass                              │
+Browser QA ───────────────── fail ────┤
+  ↓ pass                              │
+Security Review ──────────── fail ────┤
+  ↓ pass                              │
+Code Review / PR Review ─── issues ───┘
+  ↓ pass
+Deploy / Final Verification
+  ↓
+Done
+```
+
+The graph controls **who works next, what context they receive, what they must produce, how failures route, what tools/models they can use, and what constitutes completion**.
+
+## One harness, multiple interfaces
+
+The executable harness is not owned by the TUI or browser frontend.
+
+```text
+Andorra Code TUI ────────────┐
+                             │
+Browser Configure app ──────┼──► Andorra Code Runtime ───► Harness revision
+Desktop client (app-server) ─┤
+                             │
+Headless CLI / SDK (future) ─┘
+```
+
+All clients operate on the same persisted harness format and runtime semantics. The configuration app may store canvas layout as presentation metadata, but execution never depends on browser state.
+
+This allows a graph created visually to be selected immediately with `/graph` in the TUI without export or translation.
+
+The desktop client is a client of the same runtime: it starts `andorra app-server --stdio` and speaks a
+line-delimited JSON protocol, so its sessions, run records, configuration, and account are the CLI's own.
+See [`docs/guides/desktop-app.md`](docs/guides/desktop-app.md) and [ADR 0014](design/decisions/0014-tauri-desktop-client-and-app-server.md).
+
+## Product surfaces
+
+- **CLI / TUI** — primary coding-agent experience launched with `andorra`.
+- **Graph selector** — `/graph` switches between preset and custom harness graphs.
+- **Configure application** — bundled local browser UI launched with `andorra graph` or `andorra --configure`.
+- **Graph Builder** — Shopify Flow-like canvas for creating and wiring harness graphs.
+- **Node Library** — built-in primitives and reusable user-created nodes.
+- **Manual Agent configuration** - editable shared-executor presets, typed handoffs, reusable custom definitions and optional internal subagents.
+- **Settings / Providers** — configure hosted providers, provider-supported authentication, and OpenAI-compatible local endpoints; configured models become selectable per Agent node.
+- **Headless execution** — machine-readable execution for scripting/CI without requiring the TUI.
+- **Subagent mode** — run Andorra from another agent (Claude CLI, Codex CLI) over MCP or the CLI; the host names a provider/model and gets one Software Engineer run back. See [`docs/agents/subagent-mode.md`](docs/agents/subagent-mode.md).
+- **Session debug log** — `--debug` adds per-command timing, CLI error records and session token totals to the always-on trajectory journal.
+- **Persistent memory** — Graphiti-backed temporal project memory: decisions, verified fixes, conventions and lessons survive between runs; see [`design/architecture/memory.md`](design/architecture/memory.md).
+
+## Key principles
+
+1. **Andorra Code is CLI-first.** `andorra` opens the coding-agent TUI; the browser editor is opened explicitly for configuration.
+2. **The graph is the harness.** The selected graph defines how the coding agent behaves.
+3. **Agent nodes use a shared basic ReAct executor.** One Agent-node attempt owns one independent ReAct loop; graph edges route only after the node returns.
+4. **Agent nodes remain full agents.** Graph orchestration does not replace their inner model/tool autonomy.
+5. **Graphs are swappable.** `/graph` lets users choose preset or custom harnesses without rebuilding the application.
+6. **Runs are revision-pinned.** Switching graphs never silently changes an already-running execution plan.
+7. **Models are configuration, not node identity.** Each Agent node references a configured model profile and can use a different provider/model.
+8. **Verification is independent.** Workers are not trusted simply because they claim success; QA/review/security stages can prove completion.
+9. **State is explicit and durable.** Requirements, findings, diffs, tests, artifacts, approvals, and checkpoints are inspectable and survive client disconnects where configured.
+10. **Permissions follow capabilities.** Nodes receive only the tools, secrets, and destructive permissions they require.
+11. **One runtime, multiple clients.** TUI, browser configuration, headless CLI, and future SDK/API clients use the same harness semantics.
+
+## Documentation
+
+Start at [`docs/README.md`](docs/README.md).
+
+The CLI uses [hosted Jev decisions](design/decision-engine.md) by default for signed-in free and paid users to select eligible CodeGraph and automatic Graphiti context. Runs using the enabled hosted service send a compact, question-scoped routing snapshot to that service: bounded task/node-instruction excerpts plus only the capability metadata needed by the current Jev questions. Retrieved source, Graphiti payloads and conversation history are excluded. Use `/jev off` before submitting work you do not want sent to Jev, `/jev on` to re-enable it, and `/jev status` to inspect the persisted preference (enabled when omitted). Paid users can also disable Jev per Agent in the graph builder. The shared Jev key stays in AWS; no personal Jev key is required.
+
+The coding model still implements the task. Authentication, quota, capability restrictions and safe fallback remain enforced; Jev does not change tool permissions or graph edges. Signed-out users retain ordinary retrieval routing unless they configure a local decision service. [QA evidence](tests/default-active-jev-test-plan.md) records a successful live hosted CLI run; prediction quality and token savings have not been measured. Configure a local model under **Settings > Runtime > Jev decisions > Configure decisions**, with its structured decision API URL, model name and optional authentication environment-variable name. CLI, desktop and browser honor the saved `decisions` configuration; global `/jev off` disables both local and hosted calls. Direct Jev supports shadow evaluation and Laya supports shadow/active CodeGraph and memory routing; ordinary OpenAI-compatible chat models are insufficient. Explicit embedded runtimes retain off/none library defaults.
+
+See [`design/product/tui-design.md`](design/product/tui-design.md) for the primary terminal UX, [`design/product/graph-builder.md`](design/product/graph-builder.md) for the `--configure` graph editor, [`design/architecture/react-agent-loop.md`](design/architecture/react-agent-loop.md) for the default Agent executor, [`design/gui-design/`](design/gui-design/) for the AndorraBot-derived desktop design baseline, and [`design/architecture/overview.md`](design/architecture/overview.md) for the shared runtime architecture.
+
+## Status
+
+Initial executable CLI/runtime is available. See [Getting started](docs/getting-started/README.md) for installation, provider setup, slash commands, headless use and current limitations.
+
+```sh
+npm ci
+npm run build
+npm start
+```
+
+The current CLI includes `/dashboard`, `/model`, `/providers`, `/graph`, `/usage`, `/yolo`, `/tools`, `/status`, `/clear`, `/help`, and `/exit`. The browser Graph Builder adds editable Agent definitions, typed handoffs, fan-out/Join routing and internal subagents. Broader product-direction examples remain subject to the implementation limits documented in ADR 0010.
+
+### Workspace permissions
+
+Use `/permissions` to choose **Read Only**, **Ask for approval** (default), **Approve for me**, or **Full Access**. Selections persist per canonical workspace directory in your global Andorra configuration. The selector marks the current mode; Escape cancels. `/permissions read-only|ask-for-approval|approve-for-me|full-access` also selects directly.
+
+Workspace writes are automatic in Ask for approval and Approve for me; Read Only asks before native writes. Native file operations require per-operation approval outside the workspace or for protected repository/runtime metadata, including a custom `CODEX_HOME`. Graph capability limits remain in force.
+
+Read Only suspends CodeGraph because indexing writes its workspace cache. Switching to Read Only stops active cache writers before saving the mode; if they cannot stop, the change reports an error. Switching back to a writable mode resumes CodeGraph when enabled. Native reads and searches remain available while indexing is suspended.
+
+Restricted shell profiles request workspace-only reads, limited runtime reads, workspace writes according to the selected mode, and no network. **Restricted shell execution currently fails closed before spawning any command. Installed Windows Codex CLI 0.160.0 was observed accepting this profile while still reading an owned Documents file outside the workspace and runtime allowances; no backend has been verified to enforce the required read boundary.** Other operating systems are unsupported. Native file tools and remembered permissions still work. Explicit `sandbox_permissions=require_escalated` with a justification can request approval for one host command; no failed command is automatically retried outside the sandbox.
+
+Restricted shell launcher discovery accepts standard Codex desktop, global npm, or Cargo installation roots. A nested workspace does not trust executables elsewhere in its parent repository. For a custom installation, set `ANDORRA_CODEX_PATH` to an absolute external native executable or npm shim in your launch environment; this explicitly trusts that installation, and the shim is resolved without executing it. Bare names, relative overrides and repository-controlled targets are rejected. File tools ask before following workspace symlinks or junctions; the grant applies only to that operation. Live shell permission changes are checked again after launcher discovery, immediately before spawn; only explicit per-call host approvals survive a downgrade.
+
+Full Access permits host filesystem/network access without prompts while recording automatic authorization events. `/yolo on` and `--yolo` are session-only Full Access overrides; `/yolo off` selects Ask for approval for the session. They do not replace the saved workspace choice. Native reads and writes of protected credential/config roots require approval; recursive searches skip those roots. Restricted Grep uses bounded native file operations without invoking PATH helpers (type, multiline, and only-matching options are unavailable). Git reads and host QA/browser/terminal actions, including QA status probes, require a scoped approval in restricted modes. Each sandbox attempt uses a unique permission profile and a trusted absolute Codex executable outside the workspace; workspace PATH shims cannot supply the launcher. Persistent Graphiti memory is suspended outside Full Access, including initialization, health, retrieval, search and persistence; local command memory remains available. Live downgrades block each later memory request. The model provider connection itself is outside the child-command sandbox.
+
+See [the permissions QA plan](tests/permissions-test-plan.md) for setup, exact checks, and platform validation limits.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,56 @@
+# Third-party notices
+
+## ZCode
+
+Portions of Andorra Code's canonical coding-tool **interface design and behavior** are derived from and adapted from the open-source ZCode project:
+
+- Project: https://github.com/zai-org/ZCode
+- Copyright: Copyright 2026 Z.AI Co., Ltd.
+- License: Apache License 2.0
+- Source reviewed for this integration: ZCode commit `872ad960de7ec172591f7e1952f7849229f94521`
+
+The Andorra implementation is modified substantially: execution remains on Andorra's workspace/capability/approval layer and the vendored Pi coding-agent primitives, while selected ZCode ideas are adapted for tool naming, schemas, read-before-write freshness, Grep output modes, and shell argument conventions.
+
+The Apache License 2.0 text for ZCode is available in the upstream repository at `LICENSE`.
+
+Context efficiency policy also adapts behavior reviewed at ZCode commit
+`29628c9acdb81b703bbd4080c207a0e7ce5e276e`, specifically
+`apps/zcode-cli/packages/core/src/compact/policy.ts`, `compact/microcompact.ts`,
+`runtime/methods/compact.ts`, and `runtime/methods/turn-loop.ts`.
+`src/context-budget.ts` implements modified token reserves, provider-usage anchoring
+and pressure-triggered local cleanup. Andorra preserves source contracts, inherited
+messages and failure evidence, and keeps its own graph, approvals and protocol state.
+The existing Apache-2.0 license copy is `licenses/ZCODE-APACHE-2.0.txt`.
+
+## ZCode engine and bundled skills
+
+The default inner agent loop now uses dependency-isolated ports of ZCode revision
+`29628c9acdb81b703bbd4080c207a0e7ce5e276e`. Exact upstream paths and source/adapted
+hashes are recorded in `vendor/zcode/provenance.json`; the Apache-2.0 license is
+included as `vendor/zcode/LICENSE.upstream`. The upstream phase machine, scheduler,
+compaction policy, estimator and microcompaction modules are adapted alongside the
+regular loop/model-step and compact-selection control flow. Andorra host ports
+replace desktop/session service dependencies and retain graph/Jev, provider,
+permission, cancellation and completion integration. See `docs/zcode-engine.md`.
+
+Bundled web-gui, control-browser and dynamic-workflows skill assets derive from
+the same ZCode revision (Copyright 2026 Z.AI Co., Ltd., Apache-2.0). The ai-elements
+skill is Copyright 2023 Vercel, Inc., Apache-2.0, as recorded upstream. Source hashes
+and retained license notices are included in `src/skills/bundled/provenance.json`.
+React best practices assets were not imported because the upstream notice flags
+missing original MIT copyright text.
+
+## Pi
+
+Andorra Code also vendors source from Pi as recorded in `vendor/engine/provenance.json`, including the exact upstream revision, source paths, rename map, and license information.
+
+## Geist
+
+The graph editor (`src/graph-ui/fonts`) ships the Geist and Geist Mono webfonts so that it renders
+the same face as the desktop client. The font files are the unmodified `latin` subsets of
+`@fontsource/geist-sans` and `@fontsource/geist-mono` version 5.3.0.
+
+- Project: https://github.com/vercel/geist-font
+- Copyright: Copyright 2023 Vercel, made in collaboration with basement.studio
+- License: SIL Open Font License 1.1
+- License copy: `licenses/GEIST-OFL-1.1.txt`

package/dist/src/account-presentation.d.ts

@@ -0,0 +1,53 @@
+import { type Membership } from './membership.js';
+import type { AuthStatus } from './auth/types.js';
+export interface AccountPresentation {
+    label: string;
+    notice: string;
+    jevQuota?: string;
+}
+export interface AccountPresentationDependencies {
+    status(signal?: AbortSignal): Promise<AuthStatus>;
+    membership(signal?: AbortSignal): Promise<Membership>;
+}
+export declare const SIGNED_OUT_ACCOUNT: AccountPresentation;
+/**
+ * Whether an auth-status read and a membership read describe the same account.
+ *
+ * They are separate requests — the credential store is read locally, the plan comes from the service —
+ * so a credential change between them can pair one account's identity with another's plan. Two reads that
+ * name the same account match; a read that named nobody (a membership answer that carries no subject) is
+ * not evidence of a change, and a caller must not turn its absence into one.
+ *
+ * A signed-out status is different: a membership that still names an account describes the credential
+ * that was just removed, and a plan that reached the client while the credential was going away must not
+ * be published as this installation's — the run's own preflight reads membership again and would refuse
+ * every graph that plan unlocks.
+ */
+export declare function sameAccount(status: {
+    signedIn: boolean;
+    subject?: string;
+}, membership: {
+    subject?: string;
+}): boolean;
+/**
+ * The membership an account status may publish beside the identity it read locally.
+ *
+ * Two answers are not a verdict about a plan. The first is a pair that names two different accounts:
+ * a credential change between the two reads pairs this identity with the other account's plan, and the
+ * run's own preflight would then refuse every graph that plan unlocks. The second is a membership that
+ * names no subject at all — a 401/403, a malformed body, or a local token the service has already
+ * forgotten. `getMembership` reports that as `paid: false` because nothing is entitled, not because the
+ * account is on the free plan, and the presenter already calls it an access it could not verify. The
+ * structured fields have to say the same: published as they are, every surface that reads them repeats
+ * a confirmed Free plan — and the copy that goes with it — for a session nobody could read.
+ *
+ * No subject travels with the unread answer, whatever the identity read said: the presenter reads a
+ * subject as a successful read, and would report the plan that was just refused rather than the unread
+ * one this is.
+ */
+export declare function publishableMembership(status: {
+    signedIn: boolean;
+    subject?: string;
+}, membership: Membership): Membership;
+/** Read local login state first; signed-out startup never contacts the account service. */ export declare function createAccountPresentationReader(deps: AccountPresentationDependencies): (signal?: AbortSignal) => Promise<AccountPresentation>;
+export declare function getAccountPresentation(signal?: AbortSignal): Promise<AccountPresentation>;

package/dist/src/account-presentation.js

@@ -0,0 +1,99 @@
+import { membershipPlanLabel, safeAccountEmail } from './membership.js';
+export const SIGNED_OUT_ACCOUNT = {
+    label: 'Signed out | /login',
+    jevQuota: 'Jev sign in',
+    notice: 'Sign in with /login or create an account to use Jev. Local Software Engineer remains available. Paid membership unlocks the Orchestrator, graph builder, and custom graphs.',
+};
+const unavailable = (signedIn, reason) => ({
+    label: signedIn ? 'Signed in | membership unavailable' : 'Account unavailable',
+    jevQuota: 'Jev unavailable',
+    notice: reason
+        ? `${reason === 'tls' ? 'The account service certificate could not be verified; a secure connection could not be established.' : reason === 'dns' ? 'The account service address could not be resolved.' : 'The account service could not be reached.'} Check your network, DNS, or proxy settings, then use /auth status to retry. Hosted Jev and paid features may be unavailable. Local Software Engineer remains available.`
+        : 'Account access could not be verified. Hosted Jev and paid features may be unavailable. Local Software Engineer remains available. Use /auth status to retry or /login to sign in.',
+});
+/**
+ * Whether an auth-status read and a membership read describe the same account.
+ *
+ * They are separate requests — the credential store is read locally, the plan comes from the service —
+ * so a credential change between them can pair one account's identity with another's plan. Two reads that
+ * name the same account match; a read that named nobody (a membership answer that carries no subject) is
+ * not evidence of a change, and a caller must not turn its absence into one.
+ *
+ * A signed-out status is different: a membership that still names an account describes the credential
+ * that was just removed, and a plan that reached the client while the credential was going away must not
+ * be published as this installation's — the run's own preflight reads membership again and would refuse
+ * every graph that plan unlocks.
+ */
+export function sameAccount(status, membership) {
+    if (!status.signedIn)
+        return membership.subject === undefined;
+    if (status.subject === undefined || membership.subject === undefined)
+        return true;
+    return status.subject === membership.subject;
+}
+/**
+ * The membership an account status may publish beside the identity it read locally.
+ *
+ * Two answers are not a verdict about a plan. The first is a pair that names two different accounts:
+ * a credential change between the two reads pairs this identity with the other account's plan, and the
+ * run's own preflight would then refuse every graph that plan unlocks. The second is a membership that
+ * names no subject at all — a 401/403, a malformed body, or a local token the service has already
+ * forgotten. `getMembership` reports that as `paid: false` because nothing is entitled, not because the
+ * account is on the free plan, and the presenter already calls it an access it could not verify. The
+ * structured fields have to say the same: published as they are, every surface that reads them repeats
+ * a confirmed Free plan — and the copy that goes with it — for a session nobody could read.
+ *
+ * No subject travels with the unread answer, whatever the identity read said: the presenter reads a
+ * subject as a successful read, and would report the plan that was just refused rather than the unread
+ * one this is.
+ */
+export function publishableMembership(status, membership) {
+    if (!sameAccount(status, membership))
+        return { paid: false, unavailable: true };
+    // A membership that already says it could not be read keeps that answer and its reason: the presenter
+    // turns the reason into the DNS/TLS advice, and an answer that named nobody because the connection
+    // failed is the same unread membership, not a plan that happens to carry no subject.
+    if (status.signedIn && membership.subject === undefined)
+        return membership.unavailable === true ? membership : { paid: false, unavailable: true };
+    return membership;
+}
+/** Read local login state first; signed-out startup never contacts the account service. */ export function createAccountPresentationReader(deps) {
+    return async (signal) => {
+        let signedIn = false;
+        try {
+            signal?.throwIfAborted();
+            signedIn = (await deps.status(signal)).signedIn;
+            if (!signedIn)
+                return { ...SIGNED_OUT_ACCOUNT };
+            const membership = await deps.membership(signal);
+            if (!membership.subject) {
+                // Refreshing membership can revoke and remove the local session.
+                signal?.throwIfAborted();
+                signedIn = (await deps.status(signal)).signedIn;
+                signal?.throwIfAborted();
+                return signedIn ? unavailable(true, membership.failureReason) : { ...SIGNED_OUT_ACCOUNT };
+            }
+            const email = safeAccountEmail(membership.email);
+            const limit = membership.dailyDecisionLimit;
+            const quota = Number.isSafeInteger(limit) && limit > 0 ? ` ${limit.toLocaleString('en-US')} invocations per UTC day.` : '';
+            const used = membership.dailyDecisionUsed;
+            const reset = membership.dailyDecisionResetsAt;
+            const fresh = reset !== undefined && Number.isFinite(Date.parse(reset)) && Date.parse(reset) > Date.now();
+            const usage = fresh && Number.isSafeInteger(used) && used >= 0 ? used.toLocaleString('en-US') : '?';
+            const plan = membershipPlanLabel(membership.tier, membership.paid);
+            return {
+                label: `Signed in | ${plan}${email ? ` | ${email}` : ''}`,
+                jevQuota: quota ? `Jev ${usage}/${limit.toLocaleString('en-US')} UTC` : 'Jev quota unavailable',
+                notice: `Jev runs on Agent nodes that turn it on; use /jev to toggle.${quota} ${membership.paid ? 'Orchestrator, graph builder, and custom graphs are enabled.' : 'The free tier includes 1 custom graph of up to 3 nodes; paid membership unlocks the Orchestrator and more graphs.'}`,
+            };
+        }
+        catch {
+            signal?.throwIfAborted();
+            return unavailable(signedIn);
+        }
+    };
+}
+export async function getAccountPresentation(signal) {
+    const [{ getAuthStatus }, { getMembership }] = await Promise.all([import('./auth/index.js'), import('./membership.js')]);
+    return createAccountPresentationReader({ status: getAuthStatus, membership: getMembership })(signal);
+}

package/dist/src/activity.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Live CLI activity shared with the Graph studio tab.
+ *
+ * The interactive CLI writes one small status file beside the installation's `config.json` on
+ * every state transition; the Graph studio server reads it and streams it to the browser tab
+ * so the tab can spin while a run is in progress and mark input requests. It deliberately does
+ * not live in `runs/`, whose enumerable contents are exactly one JSON and one JSON Lines record
+ * per run. The file is a side channel only: failing to write or read it must never disturb a
+ * run.
+ */
+export type ActivityState = 'idle' | 'running' | 'awaiting-input';
+export interface ActivityStatus {
+    state: ActivityState;
+    /** Short human text shown in notifications and titles, for example "Approval needed: shell". */
+    detail?: string;
+    /** Which kind of human input the CLI is waiting for, when state is awaiting-input. */
+    kind?: 'approval' | 'clarification' | 'steering';
+    /** Run id once the runtime has assigned one. */
+    runId?: string;
+    /** Writer's process id, used to detect a crashed CLI and drop a stale running state. */
+    pid: number;
+    updatedAt: string;
+}
+export declare function activityPath(directory: string): string;
+/**
+ * Record a transition. Best effort by design: a notification channel that can fail must not
+ * take the run down with it, so every error is swallowed here rather than by callers. The
+ * returned promise settles once this write (and every earlier one) has completed, so callers
+ * that await it still see an accurate disk state.
+ */
+export declare function writeActivity(directory: string, state: ActivityState, fields?: {
+    detail?: string;
+    kind?: ActivityStatus['kind'];
+    runId?: string;
+}): Promise<void>;
+/**
+ * Read the current activity. A missing, unreadable, or malformed file is idle, and a
+ * running or awaiting-input record whose writer is gone is stale, also idle: a spinner
+ * that outlives its CLI is a false signal, not a safe default.
+ */
+export declare function readActivity(directory: string): Promise<ActivityStatus>;

package/dist/src/activity.js

@@ -0,0 +1,79 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const DETAIL_LIMIT = 160;
+export function activityPath(directory) {
+    return join(directory, 'activity.json');
+}
+function truncate(value) {
+    const flat = value.replace(/\s+/g, ' ').trim();
+    return flat.length <= DETAIL_LIMIT ? flat : `${flat.slice(0, DETAIL_LIMIT - 1)}…`;
+}
+function status(state, fields = {}) {
+    return { state, ...(fields.detail ? { detail: truncate(fields.detail) } : {}), ...(fields.kind ? { kind: fields.kind } : {}), ...(fields.runId ? { runId: fields.runId } : {}), pid: process.pid, updatedAt: new Date().toISOString() };
+}
+// Synthesized once, not per read: the server polls this file every second and deduplicates by
+// the whole serialized record, so a fresh idle timestamp for a missing or malformed marker
+// would re-emit an unchanged idle state on every tick.
+const synthesizedIdle = status('idle');
+// Writes are serialized so the newest transition is always the last one to reach the disk.
+// Pause/resume transitions are fire-and-forget from the CLI's signal handler, and an unawaited
+// older write finishing after the awaited idle write would leave the live CLI's process id
+// attached to a stale awaiting-input state, which no dead-writer check can clear.
+let queued = Promise.resolve();
+/**
+ * Record a transition. Best effort by design: a notification channel that can fail must not
+ * take the run down with it, so every error is swallowed here rather than by callers. The
+ * returned promise settles once this write (and every earlier one) has completed, so callers
+ * that await it still see an accurate disk state.
+ */
+export function writeActivity(directory, state, fields = {}) {
+    queued = queued.then(async () => {
+        const target = activityPath(directory);
+        // A per-process staging name: the queue serializes this process's writes, and distinct CLI
+        // processes have distinct pids, so two writers never stage over each other's file.
+        const staging = `${target}.tmp-${process.pid}`;
+        try {
+            await mkdir(directory, { recursive: true });
+            await writeFile(staging, JSON.stringify(status(state, fields)) + '\n', { mode: 0o600 });
+            // Rename replaces the marker atomically, so a concurrent reader sees the previous or the
+            // next complete record, never the truncated middle of a write misread as idle.
+            await rename(staging, target);
+        }
+        catch { /* Activity reporting is advisory; the run continues without it. */ }
+        finally {
+            await rm(staging, { force: true }).catch(() => { });
+        }
+    });
+    return queued;
+}
+function processAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Read the current activity. A missing, unreadable, or malformed file is idle, and a
+ * running or awaiting-input record whose writer is gone is stale, also idle: a spinner
+ * that outlives its CLI is a false signal, not a safe default.
+ */
+export async function readActivity(directory) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(activityPath(directory), 'utf8'));
+    }
+    catch {
+        return synthesizedIdle;
+    }
+    const candidate = value;
+    if (!candidate || typeof candidate !== 'object' || !['idle', 'running', 'awaiting-input'].includes(candidate.state))
+        return synthesizedIdle;
+    if (candidate.state !== 'idle' && !processAlive(candidate.pid))
+        return synthesizedIdle;
+    return candidate;
+}