agl 21.0.2 → 22.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agl",
-  "version": "21.0.2",
+  "version": "22.0.0",
   "controllerUpgradeManagementVersion": 2,
   "private": false,
   "description": "Agent Gateway Layer for OpenCode and FlexHarness sessions",

package/readme.md

@@ -40,7 +40,7 @@ OpenCode and Flex are independently supervised. An unexpected Flex child exit cl
 
 FlexHarness private state is persisted in separate SmartData domains for scope metadata, public message projections, remembered permissions, canonical Agent events and archives, and background tool jobs. A fenced per-project writer lease excludes overlapping Flex children, while the parent reads a separately committed bounded public projection. Lease heartbeats and writes share one serialized transition boundary; an expired lease still held by the same controller recovers with a fresh owner token and incremented epoch before work continues. Hidden terminal staging and private canonical events never enter that browser-readable projection; a visible Flex save is acknowledged only after the corresponding bounded view is durable.
 
-Flex runtime implementation classes and child internals are private. Supported package surfaces include the `agl` CLI, protocol-v22 controller DTO and request contracts, and the root-exported controller-owned Git reversion types and engine.
+Flex runtime implementation classes and child internals are private. Supported package surfaces include the `agl` CLI, protocol-v22 controller DTO and request contracts, the root-exported AGL home path helpers, and the root-exported controller-owned Git reversion types and engine.
 
 ## Requirements
 
@@ -48,6 +48,7 @@ Flex runtime implementation classes and child internals are private. Supported p
 - Git 2.43 or newer for workspace reversion and controller-owned worktrees
 - A WebAuthn-capable browser
 - Linux or macOS for detached `start` and CLI-managed `stop`
+- A POSIX user identity for data-using startup, migration, and embedded-database commands
 - Native `node-pty` support. When no prebuilt binary is available, installation requires Python 3, `make`, and a C/C++ build toolchain.
 
 No database server is required: the controller ships an embedded engine
@@ -56,7 +57,7 @@ be configured instead.
 
 The package pins `@opencode-ai/sdk` and the official OS/architecture-specific OpenCode binary packages to the same tested version. It resolves the lockfile-installed platform executable directly, without a wrapper postinstall or unrelated global binary. This release is tested against OpenCode `1.18.15`.
 
-The OpenCode child, Flex child, and controller-owned terminal shells receive only ordinary runtime path, user, locale, temporary-directory, XDG, proxy, and CA environment variables by default. Controller/database variables and unrelated parent secrets are not inherited. Explicitly delegate additional environment variables when needed:
+The OpenCode child, Flex child, and controller-owned terminal shells receive only ordinary runtime path, user, locale, temporary-directory, XDG, proxy, and CA environment variables by default. `AGL_HOME` is the deliberate controller-owned path exception; controller/database variables and unrelated parent secrets are not inherited. Explicitly delegate additional environment variables when needed:
 
 ```sh
 export HARNESS_CONTROLLER_FORWARD_ENV='ANTHROPIC_API_KEY,OPENAI_API_KEY'
@@ -120,9 +121,11 @@ agl help
 
 Use the controller's configured port instead of `4097` for both invocations.
 Do not skip the bridge or manually replace the package. This package transition
-does not move controller data again: the current installed data root remains
-`$XDG_CONFIG_HOME/hcon` (default `~/.config/hcon`), and existing internal and
-persisted identities remain unchanged.
+itself leaves controller data under `$XDG_CONFIG_HOME/hcon`. The first data-using
+command (`start`, `foreground`, `upgrade`, or `temp-password`) from an AGL
+version with `AGL_HOME` support subsequently moves that retained state into the
+canonical AGL home described below without changing persisted
+controller, authentication, project, session, Flex, or Git identities.
 
 ### Upgrade behavior
 
@@ -165,6 +168,12 @@ stopped-controller upgrade has no inherited cohort and leaves the target
 stopped. The worker also refuses an upgrade when another pnpm-global controller
 instance exists outside the exact authorized process.
 
+New coordination transactions live under `$AGL_HOME/upgrade`. A target invoked
+by an already-released 21.0.2 worker recognizes that token-bound worker's legacy
+`/tmp/harness-controller-upgrade-*` directory only until the inherited
+transaction reaches its terminal cleanup; unrelated or unbound legacy paths are
+never used as fallback coordination.
+
 `hcon upgrade` must be run from the active pnpm-global installation and is currently supported on Linux and macOS. Before starting the AGL transition, if a prior manual same-package upgrade replaced the management CLI while an older controller remained running, restore that exact older package first so its process identity can be stopped safely:
 
 ```sh
@@ -176,33 +185,86 @@ hcon start --port 4097
 
 This repair sequence does not replace the two bridge-migration invocations.
 
+## AGL home
+
+AGL-owned persistent state has one private root selected by `AGL_HOME`. The
+in-progress home migration also uses a transient sibling lock beside that root;
+it is not normal persisted state. Installed packages default to
+`$XDG_CONFIG_HOME/agl` (normally `~/.config/agl`); repository checkouts default to
+`<checkout>/.nogit/agl`. `AGL_HOME`, when supplied, must be an absolute normalized
+non-root path whose direct parent already exists; this parent requirement also
+applies to the selected default root. AGL owns
+these namespaces:
+
+- `database` for the embedded SmartDB storage root;
+- `credentials` for sealed Flex provider credentials;
+- `git-reversion` for captures and controller-owned worktrees;
+- `logs` for controller and upgrade logs;
+- `upgrade` for durable upgrade coordination;
+- `cache` for AGL-owned caches;
+- `runtime/browser`, `runtime/uploads`, `runtime/sockets`, and
+  `runtime/opencode` for private runtime state;
+- `migration` for the current journal and verified retained migration records.
+
+Library consumers can resolve the same root-exported path contract and bind it
+into a child environment without deriving paths from the child's CWD:
+
+```ts
+import { bindAGLHomeEnvironment, resolveAGLHomePaths } from 'agl';
+
+const paths = resolveAGLHomePaths();
+const childEnvironment = bindAGLHomeEnvironment(process.env, paths);
+```
+
+`resolveAGLHomePaths()` returns `development`, `root`, `database`,
+`credentials`, `gitReversion`, `logs`, `legacyLogs`, `upgrade`, `cache`,
+`runtime`, `browserRuntime`, `uploads`, `sockets`, `openCodeRuntime`, and
+`migration`. `bindAGLHomeEnvironment()` returns a copy of the supplied
+environment with `AGL_HOME` bound to `paths.root`.
+
+The package installation itself, user-selected project directories, an explicit
+`HARNESS_CONTROLLER_DB_DIR` (including one that names a recognized legacy
+SmartDB path), an external MongoDB server, and OpenCode's own user-wide
+configuration are not AGL-owned state and remain outside this root.
+`AGL_HOME` is bound into controller, upgrade, Flex, and OpenCode process
+boundaries so a detached process never derives ownership from its launch CWD.
+
+The one-time v23 home migration runs before database model access from `start`,
+`foreground`, `upgrade`, or `temp-password`. It first
+normalizes the prior `harness-controller` to `hcon` migration when necessary,
+then uses SmartDB and SmartSecret relocation APIs for the active database and
+sealed credentials. Git state, browser state, logs, and verified legacy records
+move under the same journal. The migration is same-filesystem only, checks
+private ownership, exact source inventories, live writers, sockets, symlinks,
+target collisions, and source identities before mutation, and safely reconciles
+an interruption. Active controller-owned Git worktree state blocks migration
+because Git's linked-worktree metadata contains absolute paths. Unknown or
+ambiguous state fails closed. Verified historical database material is retained
+under `$AGL_HOME/migration`; committed legacy roots are removed only when their
+known entries are empty. Never move these directories or edit their journals by
+hand.
+
+An explicit non-default `AGL_HOME` in a development checkout starts as an
+isolated fresh home and does not consume that checkout's shared legacy
+`.nogit` state.
+
 ## Database configuration
 
 Structured application state is stored exclusively through SmartData. There is no PID, configuration, authentication, or JSON persistence fallback on the filesystem.
 
 By default the controller runs an embedded `@push.rocks/smartdb` engine — no
 external database server. Storage lives under
-`$XDG_CONFIG_HOME/hcon/smartdb` (default `~/.config/hcon/smartdb`). A repository checkout instead uses
-`./.nogit/smartdb`, keeping development data inside the checkout. Override the
-directory with `HARNESS_CONTROLLER_DB_DIR` (absolute path). On the first
-installed command that needs controller data after upgrading, the controller
-completes any prior XDG-state database import under the retained
-`$XDG_CONFIG_HOME/harness-controller` root. When that config-root database
-exists, SmartDB's stopped-root relocation moves its exact inode to the `hcon`
-root and replaces the old `smartdb` pathname with a verified receipt, not a
-database backup. The controller verifies that receipt, storage identity, and
-logical content digest. This relocation is supported on SmartDB-qualified Linux
-filesystems and writable local APFS on macOS. When only the historical XDG-state
-database exists, it is instead imported directly into the new root with the same
-logical-digest verification while retaining that historical source as the
-non-authoritative backup. The outer migration is journaled and safely retries
-its exact operation after an interruption. Retained legacy sources are never
-imported again after completion; an older controller binary can still open and
-diverge a retained historical backup, so do not resume using it. Keep the old
-controller stopped throughout the one-time migration. Explicit database paths
-and external MongoDB configurations are never moved. The engine listens on a unix socket, and a second controller
+`$AGL_HOME/database`. Override the directory with
+`HARNESS_CONTROLLER_DB_DIR` (absolute path). Explicit database paths and
+external MongoDB configurations are never moved. The engine listens on a
+deterministic Unix socket under `$AGL_HOME/runtime/sockets`, and a second controller
 process on the same machine (for example `agl temp-password`) attaches to the
-running daemon's engine instead of opening the storage files again.
+running daemon's engine instead of opening the storage files again. The complete
+embedded Unix socket path must be no longer than 100 UTF-8 bytes; a second
+controller must use the same `AGL_HOME` and database directory to attach.
+During the one-time home migration only, AGL also probes the published legacy
+`/tmp/harness-controller-<16-hex>.sock` name to prove that the old embedded
+engine is stopped. New runtime sockets are never created at that legacy path.
 
 When upgrading from a controller release backed by FlexHarness 2, the new Flex child migrates each active project's legacy snapshot during initialization, before admitting runtime work. Migration preflights every destination, writes per-session domains before publishing scope discovery, repairs crash-interrupted streaming messages as cancelled, and safely reruns after partial completion. A durable completion marker prevents the retained source from being reapplied after live FlexHarness 3 state evolves. The legacy private snapshot remains retained as a non-authoritative recovery source until that project is removed; startup also repairs any bounded public projection whose prior save was not acknowledged.
 
@@ -226,12 +288,18 @@ Use the `MONGODB_URL` from `.nogit/env.json` as `HARNESS_CONTROLLER_MONGO_URL`.
 
 ## First start
 
-From the workspace OpenCode should control:
+Start AGL without creating an implicit project:
 
 ```sh
 agl start
 ```
 
+To register one existing directory during startup, pass it explicitly:
+
+```sh
+agl start --directory /absolute/path/to/project
+```
+
 The detached process first reserves the controller listener (`127.0.0.1:4097` in local mode; `0.0.0.0:4097` only with `--behind-tls-proxy`), spawns the isolated Flex child, starts the official OpenCode server in headless server mode on `127.0.0.1:4098`, and validates local PTY support. On an unsupported runtime the spawned Flex child reports `unsupported`; Flex startup is isolated and does not block OpenCode readiness. Before the first enrollment only, the terminal prints a one-time setup code — a random 32-byte value by default, or the operator's own value when `--setup-code` is passed.
 
 Open the printed URL, enter the setup code, and create a passkey. The code expires after 30 minutes and is atomically consumed by the first successful credential enrollment. If an unenrolled code expires, stop and start the controller to rotate it.
@@ -255,27 +323,28 @@ agl help
 agl --version
 ```
 
-First-start options:
+Initial runtime options:
 
 ```text
 --port <port>              controller port, default 4097
 --opencode-port <port>     loopback OpenCode port, default 4098
---directory <path>         fixed OpenCode workspace, default current directory
+--directory <path>         register this existing directory as an initial project;
+                           omitted means no implicit project
 --projects-root <path>     default base directory: relative project paths and
                            initial suggestions resolve here; explicitly typed
-                           absolute projects may be outside it; adopted once on
-                           first v2 start, immutable afterward
+                            absolute projects may be outside it; fresh installs
+                            default to the user home and it is immutable afterward
 --public-origin <origin>   exact browser WebAuthn origin
 --rp-id <hostname>         WebAuthn RP ID
 --behind-tls-proxy         declare trusted TLS termination upstream
 --setup-code <code>        operator-chosen setup code (see the warning above)
 ```
 
-Runtime configuration is durable and immutable per controller port. Later management commands must use the same `--port`; omitted first-start options are loaded from SmartData.
+Runtime configuration is durable and immutable per controller port. Later management commands must use the same `--port`; omitted initial runtime options are loaded from SmartData. `--directory` is different: it is a transient request to register one existing project and may be supplied on a later start without changing the durable runtime configuration.
 
 `upgrade` keeps the CLI attached to its detached, crash-survivable worker and streams progress until the durable transaction succeeds or fails. Before stopping a running controller it closes new harness-prompt admission, durably records the exact cohort and absolute preparation deadline, then acknowledges the bounded request while controller-owned work waits for active operations and asks those sessions to pause at the earliest convenience. The worker polls that private transaction with bounded source-process checks; it cannot stop the controller or enter package installation until preparation completion is durably committed on time. The global upgrade lock also drains controller-start and `temp-password` database-writer leases, then package replacement requires the source port to be closed and no exact source controller, `temp-password`, or Flex child writer to remain. A failed or expired preparation compensates settled pauses and leaves uncertain cleanup fail-closed. The retained cohort is limited to 64 exact sessions. `--grace-period-seconds` accepts 1–3600 seconds and defaults to 300. Without `--continue-sessions`, the upgraded controller reopens prompt admission without sending another message. With it, the matching continuation message is submitted at most once to the durably retained paused cohort after the upgraded controller returns. Rollback recovery attempts to compensate paused sessions within a separate maximum 60-second finalization window and does not overlap an unresolved pause with a continuation. `--json` replaces progress lines with one terminal JSON document after worker admission; preflight and launch failures still use normal CLI errors. That document includes worker identity and log path, whether the controller was running, source version, optional target version, terminal phase/success/error, and pause/continuation state counts; failures exit nonzero after writing it.
 
-The detached CLI does not write a PID file. It appends the controller's stderr diagnostics to `$XDG_CONFIG_HOME/harness-controller/controller-<port>.log` (default `~/.config/harness-controller/`, or `./.nogit/` in a repository checkout; rotated to `.old` past 1 MiB on start; stdout stays discarded because the transport logs every connection there). The log file must be a regular file owned by the current user without group or world access — the start fails loudly rather than logging somewhere surprising. The initial setup code travels once over parent-child IPC. `status` connects only to `127.0.0.1` and validates package and protocol identity. `stop` additionally validates the exact CLI path (relative launches are resolved against the process's working directory), command, effective port (an argv without `--port` verifies as the default port), process group, and process-start fingerprint. It sends cooperative `SIGTERM` only to that exact PID so the controller can stop harnesses and database resources in order. If the process remains after 30 seconds, a foreground controller receives exact-PID `SIGKILL`; a detached controller must still be the reverified process-group leader before its complete group receives `SIGKILL`. It never kills processes by name.
+The detached CLI does not write a PID file. It appends the controller's stderr diagnostics to `$AGL_HOME/logs/controller-<port>.log` (rotated to `.old` past 1 MiB on start; stdout stays discarded because the transport logs every connection there). The log file must be a regular file owned by the current user without group or world access — the start fails loudly rather than logging somewhere surprising. The initial setup code travels once over parent-child IPC. `status` connects only to `127.0.0.1` and validates package and protocol identity. `stop` additionally validates the exact CLI path (relative launches are resolved against the process's working directory), command, effective port (an argv without `--port` verifies as the default port), process group, and process-start fingerprint. It sends cooperative `SIGTERM` only to that exact PID so the controller can stop harnesses and database resources in order. If the process remains after 30 seconds, a foreground controller receives exact-PID `SIGKILL`; a detached controller must still be the reverified process-group leader before its complete group receives `SIGKILL`. It never kills processes by name.
 
 `foreground` is available for attached operation and diagnostics. Detached management is intentionally limited to Linux and macOS in this release.
 
@@ -287,7 +356,19 @@ The command talks to the controller database directly, so it requires the same d
 
 ## Projects and default models
 
-Chats are organized into projects. A project is any registered **existing** directory on disk: the browser's add-project field accepts full absolute paths (`/any/path/on/disk`) as well as paths relative to the configured `--projects-root` default base (`org/repo`), and suggests matching folders live while typing either form — absolute queries browse the actual filesystem. Hidden directories are never suggested (though an explicitly typed absolute path may contain dot segments), dot navigation is rejected, and registration fails visibly when the path does not exist — the controller never creates project directories. Projects inside the default base get short relative display names; projects elsewhere are named by their absolute path. Every session method is scoped to one project. One supervised OpenCode server serves all projects through per-call directory scoping, while the Flex child resolves each session to its registered project root before providing filesystem or shell tools. On the first v2 start the fixed workspace directory is registered as the initial project automatically. Removing a project first blocks new resource operations and requires every durable terminal and browser resource to be retired. The controller then persists removal intent before destructive work, hides the project from normal admission, drains Session Intelligence and harness operations, clears controller-owned state, asks Flex to remove that exact project namespace, and removes controller-owned Git worktrees, worktree records, and reversion capture roots. Interrupted removals resume on startup and remain pending when required runtime cleanup cannot be confirmed. Flex storage is never deleted merely because a project is absent from an active-project snapshot. Files in the registered project working tree are never deleted; path cleanup is limited to controller-owned worktrees, while controller-private capture stores and worktree records are removed only from controller-owned storage. Note the trust consequence: an authenticated browser session can register and operate on any directory the controller's user can read.
+Startup preserves the exact project registry: an empty controller remains
+empty, and only an explicit `--directory` registers an initial project. The
+supervised OpenCode server runs from
+`$AGL_HOME/runtime/opencode/<controller-hash>`, never from a project or the
+invoking shell's CWD for its implicit runtime state. Relative `--directory` and
+`--projects-root` values are resolved against the invoking shell before the
+detached process starts. A stored `projectsRoot` is validated lexically during
+startup and resolved only when a relative project operation needs it, so a
+temporarily unavailable root does not stop the controller. This v23 persisted
+document/home migration revision supersedes the historical v2 automatic-workspace
+registration; the wire protocol remains v22.
+
+Chats are organized into projects. A project is any registered **existing** directory on disk: the browser's add-project field accepts full absolute paths (`/any/path/on/disk`) as well as paths relative to the configured `--projects-root` default base (`org/repo`), and suggests matching folders live while typing either form — absolute queries browse the actual filesystem. Hidden directories are never suggested (though an explicitly typed absolute path may contain dot segments), dot navigation is rejected, and registration fails visibly when the path does not exist — the controller never creates project directories. Projects inside the default base get short relative display names; projects elsewhere are named by their absolute path. Every session method is scoped to one project. One supervised OpenCode server serves all projects through per-call directory scoping, while the Flex child resolves each session to its registered project root before providing filesystem or shell tools. Startup never derives or registers a project from the process CWD. Removing a project first blocks new resource operations and requires every durable terminal and browser resource to be retired. The controller then persists removal intent before destructive work, hides the project from normal admission, drains Session Intelligence and harness operations, clears controller-owned state, asks Flex to remove that exact project namespace, and removes controller-owned Git worktrees, worktree records, and reversion capture roots. Interrupted removals resume on startup and remain pending when required runtime cleanup cannot be confirmed. Flex storage is never deleted merely because a project is absent from an active-project snapshot. Files in the registered project working tree are never deleted; path cleanup is limited to controller-owned worktrees, while controller-private capture stores and worktree records are removed only from controller-owned storage. Note the trust consequence: an authenticated browser session can register and operate on any directory the controller's user can read.
 
 Registration persists the complete ordered device/inode ancestry from the filesystem root through every project path component, with the target recorded as a directory. Controller requests, Flex tools, Git reversion, background cleanup, and shutdown revalidate the entire chain before using the path, so preserving the project leaf inode beneath a substituted ancestor does not authorize the replacement. The first upgrade to this format binds each currently available truly legacy project exactly once under its owning controller. A legacy project that is unavailable during that migration remains terminally unbound, and an incomplete pre-release `bound` record becomes terminally unbound instead of acquiring missing ancestors. Such projects stay visible for operator diagnosis but are excluded from runtime admission and path-sensitive cleanup. Their removal retires controller-owned metadata while intentionally retaining retired resource tombstones and path-scoped OpenCode, Flex, and Git artifacts. A pending bound removal remains durable until its original complete binding is available, rather than completing against an untrusted replacement.
 
@@ -301,7 +382,7 @@ Flex `/undo` and `/redo` move transcript and workspace history together. Startin
 
 Each capture owns one controller-private `captures/<captureKey>` root. Every participating repository gets a private bare Git metadata store and disposable object generations; the bound source object database is available only as a read-only alternate. Capture, finalize, inspection, and release therefore do not add controller refs, metadata blobs, trees, or generated objects to the source repository. Apply is the sole capture-traversal operation that mutates captured worktree, index, or ref state: before mutation it creates an operation-unique, self-contained closure pack in private storage, imports that exact bounded pack without a reverse index or controller ref, and retains it with an operation-owned `.keep` file through roll-forward or compensation. The explicit worktree create/remove methods separately update the source repository's linked-worktree metadata. Private publication and capture-root lifecycle are journaled so startup can recover interrupted publication, apply, creation, and deletion without trusting files inside the tree being removed.
 
-Library consumers can construct the root-exported `ControllerGitReversion` with `IGitReversionOptions`, register each project with its canonical `IControllerProjectFilesystemIdentity`, and call `init()` or `recover()` before source-sensitive work. Capture flow uses `IGitReversionCaptureRequest` with `prepare()`, `inspectCapture()`, and `finalize()`; undo and redo use `IGitReversionApplyRequest` with `inspectApply()` and `apply()`. `IGitReversionMetadataRequest` drives `listAffected()` and `getReversionMetadata()`, while `IGitReversionWorktreeRequest` and `IGitReversionWorktreeRemoveRequest` drive the detached-session worktree methods. Only when no further undo, redo, inspection, or recovery is needed should terminal cleanup call `release()` with `IGitReversionReleaseRequest`, which permanently deletes the capture root. Call `close()` to seal admission and drain or fail closed on owned work.
+Library consumers can construct the root-exported `ControllerGitReversion` with `IGitReversionOptions`, register each project with its canonical `IControllerProjectFilesystemIdentity`, and call `init()` or `recover()` before source-sensitive work. Its default private root is under `$AGL_HOME/git-reversion`; `temporaryRoot` can still supply an explicit absolute owner root. Capture flow uses `IGitReversionCaptureRequest` with `prepare()`, `inspectCapture()`, and `finalize()`; undo and redo use `IGitReversionApplyRequest` with `inspectApply()` and `apply()`. `IGitReversionMetadataRequest` drives `listAffected()` and `getReversionMetadata()`, while `IGitReversionWorktreeRequest` and `IGitReversionWorktreeRemoveRequest` drive the detached-session worktree methods. Only when no further undo, redo, inspection, or recovery is needed should terminal cleanup call `release()` with `IGitReversionReleaseRequest`, which permanently deletes the capture root. Call `close()` to seal admission and drain or fail closed on owned work.
 
 Flex also exposes `/worktree create`, `/worktree list`, and `/worktree remove <worktreeId>`. These commands explicitly create and manage detached, locked, controller-owned worktrees for the current conversation; worktrees are never created automatically. Creation durably binds the private parent before `git worktree add`, then binds the child before activation. Recovery, cleanup, and removal revalidate the required parent and child bindings; a replacement is fenced and retained. Listing validates the registered project before reading bounded private records, but does not dereference or revalidate every listed worktree path. The run-scoped `git_worktree` tool provides the same create/list/remove operations to the agent, with permission required for create and remove. Removal refuses any worktree containing tracked, untracked, or ignored changes.
 
@@ -442,7 +523,7 @@ Audit records may contain bounded peer, credential, session, or permission-reque
 
 Flex private snapshots and public projections are published separately. The controller reads only integrity-checked public records. For each project, every public candidate is bounded to 2,048 sessions, 2,048 messages, 64 MiB of message data, and 480 KiB per message; up to four public candidates are retained per project. Pages contain at most 50 messages or 512 KiB. Unreferenced staged candidates are age-gated and reconciled through paged, batched maintenance. Provider credentials never enter these records.
 
-Running terminal processes, output scrollback, peer cursors, grid state, active human browser views, browser-frame streams, BrowserRuntime capabilities and leases, Flex browser channels, and composer drafts are memory-only. Durable terminal resource identifiers may appear as bounded request identifiers in lifecycle audit records, but session layouts contain only OpenCode and Flex session IDs. Terminal input and output are never persisted. Draft text and attachment bytes are never written to SmartData or audit records. Attachment files exist only in private controller-owned temporary directories for the lifetime of their exact harness operation and are removed on operation cleanup or process shutdown.
+Running terminal processes, output scrollback, peer cursors, grid state, active human browser views, browser-frame streams, BrowserRuntime capabilities and leases, Flex browser channels, and composer drafts are memory-only. Durable terminal resource identifiers may appear as bounded request identifiers in lifecycle audit records, but session layouts contain only OpenCode and Flex session IDs. Terminal input and output are never persisted. Draft text and attachment bytes are never written to SmartData or audit records. Attachment files exist only in private operation directories under `$AGL_HOME/runtime/uploads` for the lifetime of their exact harness operation and are removed on operation cleanup or process shutdown.
 
 ## Development
 

package/readme.plan.md

@@ -36,14 +36,27 @@ targets.
   credential records, SmartSecret service/store/account identities, harness
   IDs, audit vocabulary, browser storage keys, and persisted protocol fields.
 - Preserve existing `HARNESS_CONTROLLER_*` environment variables, private IPC
-  identities, log locations, and management coordination paths.
-- Preserve user projects, workspaces, controller runtime configuration, session
-  state, Flex credentials, Git captures, and controller-owned worktrees.
-- Keep the current installed data root at `$XDG_CONFIG_HOME/hcon` (default
-  `~/.config/hcon`). Its migration is already committed; neither upgrade phase
-  performs another data-root move or imports the old root again.
-- Development checkouts continue to use `.nogit`. Package and CLI branding may
-  change only at the public target boundary, not inside persisted identities.
+  identities, and persisted controller, project, session, Flex, Git, and
+  WebAuthn identities. Physical AGL-owned paths may move only through a
+  versioned migration under `ts_migration/`.
+- Post-transition AGL versions use one canonical `AGL_HOME`: installed packages
+  default to `$XDG_CONFIG_HOME/agl`, and development checkouts to `.nogit/agl`.
+  The v23 migration moves the retained `hcon`, `harness-controller`, and
+  historical state assets into that root without reimporting committed data.
+- Persisted `workspaceDirectory` is removed by the v23 document migration.
+  Existing project records remain authoritative; an empty registry remains
+  empty, and `--directory` is a transient project-registration request that can
+  also be supplied on a later start.
+  A missing persisted `projectsRoot` adopts the legacy workspace when present;
+  otherwise fresh configuration defaults it to the user home.
+- New logs and management coordination live under `AGL_HOME`; the in-progress
+  home-migration lock is a transient sibling beside that root. The legacy `/tmp`
+  coordination path remains recognized only for an exact token-bound worker
+  inherited from the already-published 21.0.2 implementation.
+- An explicit `HARNESS_CONTROLLER_DB_DIR` remains outside the migration root and
+  is never relocated, even when it names the recognized legacy SmartDB path.
+- The v23 document/home revision is persisted-state migration metadata; the wire
+  protocol remains v22.
 
 ## Coordination Compatibility
 
@@ -185,4 +198,6 @@ for recovery.
   no-traversal recovery, bounded discovery barriers, and crash-safe replay.
 - Final E2E from actual published 20.0.2 to bridge 20.0.3 to target 21.0.0,
   confirming data, credentials, sessions, Git state, command ownership, and the
-  unchanged `~/.config/hcon` root.
+  preserved legacy `~/.config/hcon` root before the first v23 startup; then
+  confirm that v23 moves that state into canonical `AGL_HOME` without identity
+  changes.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: 'agl',
-  version: '21.0.2',
+  version: '22.0.0',
   description: 'Agent Gateway Layer for OpenCode and FlexHarness sessions'
 }

package/ts/classes.aglhome.ts

@@ -0,0 +1,116 @@
+import * as plugins from './plugins.js';
+
+export const aglHomeEnvironmentVariable = 'AGL_HOME';
+
+export interface IAGLHomeOptions {
+  packageRoot?: string;
+  homeDirectory?: string;
+  environment?: NodeJS.ProcessEnv;
+}
+
+export interface IAGLHomePaths {
+  development: boolean;
+  root: string;
+  database: string;
+  credentials: string;
+  gitReversion: string;
+  logs: string;
+  legacyLogs: string;
+  upgrade: string;
+  cache: string;
+  runtime: string;
+  browserRuntime: string;
+  uploads: string;
+  sockets: string;
+  openCodeRuntime: string;
+  migration: string;
+}
+
+const modulePackageRoot = plugins.path.resolve(
+  plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url)),
+  '..',
+);
+
+const isDevelopmentCheckout = (packageRootArg: string): boolean => {
+  try {
+    const stats = plugins.fs.lstatSync(plugins.path.join(packageRootArg, '.git'));
+    return stats.isDirectory() || stats.isFile();
+  } catch {
+    return false;
+  }
+};
+
+const assertAbsoluteNormalizedPath = (pathArg: string, labelArg: string): string => {
+  if (
+    typeof pathArg !== 'string'
+    || !plugins.path.isAbsolute(pathArg)
+    || plugins.path.normalize(pathArg) !== pathArg
+    || plugins.path.parse(pathArg).root === pathArg
+    || pathArg.includes('\0')
+    || Buffer.byteLength(pathArg, 'utf8') > 4096
+  ) {
+    throw new Error(`${labelArg} must be an absolute normalized non-root path.`);
+  }
+  return pathArg;
+};
+
+const defaultConfigHome = (
+  environmentArg: NodeJS.ProcessEnv,
+  homeDirectoryArg: string,
+): string => {
+  const configured = environmentArg.XDG_CONFIG_HOME?.trim();
+  return configured && plugins.path.isAbsolute(configured)
+    ? plugins.path.normalize(configured)
+    : plugins.path.join(homeDirectoryArg, '.config');
+};
+
+export const resolveAGLHomePaths = (
+  optionsArg: IAGLHomeOptions = {},
+): IAGLHomePaths => {
+  const environment = optionsArg.environment ?? process.env;
+  const packageRoot = assertAbsoluteNormalizedPath(
+    plugins.path.normalize(optionsArg.packageRoot ?? modulePackageRoot),
+    'AGL package root',
+  );
+  const homeDirectory = assertAbsoluteNormalizedPath(
+    plugins.path.normalize(optionsArg.homeDirectory ?? plugins.os.homedir()),
+    'User home directory',
+  );
+  const configuredHome = environment[aglHomeEnvironmentVariable]?.trim();
+  const development = isDevelopmentCheckout(packageRoot);
+  const root = assertAbsoluteNormalizedPath(
+    configuredHome
+      ? configuredHome
+      : development
+        ? plugins.path.join(packageRoot, '.nogit', 'agl')
+        : plugins.path.join(defaultConfigHome(environment, homeDirectory), 'agl'),
+    aglHomeEnvironmentVariable,
+  );
+  const runtime = plugins.path.join(root, 'runtime');
+  const logs = plugins.path.join(root, 'logs');
+  return {
+    development,
+    root,
+    database: plugins.path.join(root, 'database'),
+    credentials: plugins.path.join(root, 'credentials'),
+    gitReversion: plugins.path.join(root, 'git-reversion'),
+    logs,
+    legacyLogs: plugins.path.join(logs, 'legacy'),
+    upgrade: plugins.path.join(root, 'upgrade'),
+    cache: plugins.path.join(root, 'cache'),
+    runtime,
+    browserRuntime: plugins.path.join(runtime, 'browser'),
+    uploads: plugins.path.join(runtime, 'uploads'),
+    sockets: plugins.path.join(runtime, 'sockets'),
+    openCodeRuntime: plugins.path.join(runtime, 'opencode'),
+    migration: plugins.path.join(root, 'migration'),
+  };
+};
+
+export const bindAGLHomeEnvironment = (
+  environmentArg: NodeJS.ProcessEnv,
+  pathsArg: IAGLHomePaths = resolveAGLHomePaths({ environment: environmentArg }),
+): NodeJS.ProcessEnv => ({
+  ...environmentArg,
+  [aglHomeEnvironmentVariable]: pathsArg.root,
+});

package/ts/classes.authmodels.ts

@@ -92,30 +92,22 @@ const isValidPort = (valueArg: unknown): valueArg is number =>
 const isRuntimeConfig = (valueArg: unknown): valueArg is IControllerRuntimeConfig => {
   if (!isPlainObject(valueArg)) return false;
   if (
-    // projectsRoot is optional only because pre-v2 documents lack it; once
-    // present it must be a canonical absolute path like the workspace.
     !hasExactKeys(valueArg, [
       'controllerPort',
       'publicOrigin',
       'rpId',
-      'workspaceDirectory',
+      'projectsRoot',
       'opencodePort',
       'tlsMode',
-    ], ['projectsRoot'])
-    || (
-      Object.hasOwn(valueArg, 'projectsRoot')
-      && (
-        !isNonEmptyString(valueArg.projectsRoot)
-        || !plugins.path.isAbsolute(valueArg.projectsRoot)
-      )
-    )
+    ])
+    || !isNonEmptyString(valueArg.projectsRoot)
+    || !plugins.path.isAbsolute(valueArg.projectsRoot)
+    || plugins.path.normalize(valueArg.projectsRoot) !== valueArg.projectsRoot
     || !isValidPort(valueArg.controllerPort)
     || !isValidPort(valueArg.opencodePort)
     || valueArg.controllerPort === valueArg.opencodePort
     || !isNonEmptyString(valueArg.publicOrigin)
     || !isNonEmptyString(valueArg.rpId)
-    || !isNonEmptyString(valueArg.workspaceDirectory)
-    || !plugins.path.isAbsolute(valueArg.workspaceDirectory)
     || !['local', 'proxy'].includes(valueArg.tlsMode as string)
   ) {
     return false;

package/ts/classes.authstore.ts

@@ -154,11 +154,7 @@ const cloneRuntimeConfig = (
   controllerPort: runtimeConfigArg.controllerPort,
   publicOrigin: runtimeConfigArg.publicOrigin,
   rpId: runtimeConfigArg.rpId,
-  workspaceDirectory: runtimeConfigArg.workspaceDirectory,
-  // The key must be absent, not undefined-valued, for exact persistence.
-  ...(runtimeConfigArg.projectsRoot !== undefined
-    ? { projectsRoot: runtimeConfigArg.projectsRoot }
-    : {}),
+  projectsRoot: runtimeConfigArg.projectsRoot,
   opencodePort: runtimeConfigArg.opencodePort,
   tlsMode: runtimeConfigArg.tlsMode,
 });
@@ -169,7 +165,6 @@ const runtimeConfigsEqual = (
 ): boolean => leftArg.controllerPort === rightArg.controllerPort
   && leftArg.publicOrigin === rightArg.publicOrigin
   && leftArg.rpId === rightArg.rpId
-  && leftArg.workspaceDirectory === rightArg.workspaceDirectory
   && leftArg.projectsRoot === rightArg.projectsRoot
   && leftArg.opencodePort === rightArg.opencodePort
   && leftArg.tlsMode === rightArg.tlsMode;
@@ -726,39 +721,6 @@ export class SmartDataAuthStore implements IAuthStore {
     const existing = await ControllerAuthModel.exact.findStoredOne({ id: controllerId });
     if (existing) {
       const document = ControllerAuthModel.exact.toPersisted(existing);
-      if (
-        document.config.projectsRoot === undefined
-        && runtimeConfigArg.projectsRoot !== undefined
-      ) {
-        // One-time v2 upgrade: adopt the resolved projects root into the
-        // stored document; every other field must still match exactly.
-        this.assertRuntimeConfigMatches(
-          { ...document.config, projectsRoot: runtimeConfigArg.projectsRoot },
-          runtimeConfigArg,
-        );
-        const upgraded = cloneRuntimeConfig(runtimeConfigArg);
-        const result = await ControllerAuthModel.exact.transition({
-          current: existing,
-          change: (model) => {
-            model.config = upgraded;
-          },
-        });
-        if (result.status === 'transitioned') {
-          return this.finalizeRuntimeConfigDocument(
-            ControllerAuthModel.exact.toPersisted(result.document),
-            runtimeConfigArg,
-          );
-        }
-        const reconciled = await ControllerAuthModel.exact.findStoredOne({ id: controllerId });
-        if (!reconciled) {
-          throw new AuthError(
-            'ambiguous_write',
-            'Controller runtime configuration upgrade has an ambiguous outcome.',
-          );
-        }
-        const reconciledDocument = ControllerAuthModel.exact.toPersisted(reconciled);
-        return this.finalizeRuntimeConfigDocument(reconciledDocument, runtimeConfigArg);
-      }
       return this.finalizeRuntimeConfigDocument(document, runtimeConfigArg);
     }