@indx-workspace/embedded 0.0.0-bootstrap → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog — `@indx-workspace/embedded`
+
+One heading per release, newest first. Released in lock-step with `@indx-workspace/contracts`, with
+the same version (ADR-0082 D3).
+
+## 0.3.0 — unreleased
+
+The first release of this package on npm; there was no 0.2.1 of it.
+
+### Added
+
+- The local runtime as one package (ADR-0109): `dist/launch.js` (the bundled web, gateway and
+  runner), `dist/bin.js` (the `./launch` export and the `agent-workspace-embedded` bin),
+  `dist/web/` (the production webpack build of the web app) and `dist/migrations/`.
+- `./package.json` is exported, so `aw dev` can check the runtime's version.
+- The project file's policy ceiling reaches the local runtime (#534, ADR-0109 slice-2 amendment):
+  `start.environment.policy` is written to `AW_DEPLOYMENT_POLICY` as canonical JSON (keys sorted,
+  no whitespace). A hand-set `AW_DEPLOYMENT_POLICY` that is not a valid JSON policy ceiling, a blank
+  one included, is refused as `invalid_value`, and one that differs from the project file's policy
+  as `conflicting_value`; both name the variable, never its value. With no `policy` in the project
+  file a valid hand-set ceiling still applies, and the runtime prints
+  `warning: AW_DEPLOYMENT_POLICY is set in the environment or .env and agent-workspace.yaml has no policy; that ceiling applies`.
+  The comparison is of canonical JSON, so key order and number spelling do not count but array
+  order does. Declared gap: nothing in the server reads `AW_DEPLOYMENT_POLICY` yet; the ceiling is
+  enforced once S2-04b lands (plan C13).
+- The local runtime refuses to start when its environment, after `.env` is loaded, holds a name
+  from `start.environment.withheld` in any case (#534, SD17): the message names the secret and says
+  to remove it from `.env` and start `aw dev` with it in its environment instead.
+
+### Fixed
+
+- `aw dev` starts under WSL2 mirrored networking (#556). The embedded PostgreSQL's default port
+  moves from 54329, inside Windows' dynamic range 49152-65535 that Linux cannot bind in mirrored
+  mode, to 25432, outside every default ephemeral range. `AW_DATABASE_PORT` (environment or the
+  project's `.env`, a whole number from 1024 to 65535) overrides it; `DATABASE_URL` still uses your
+  own PostgreSQL instead; a value equal to the web, gateway or runner port is refused before
+  anything starts, naming the clash. A port that cannot be bound although nothing listens on it now
+  fails with `port <n> cannot be bound on 127.0.0.1, but no process is listening on it: ...`, an
+  inconclusive listener check with `... and whether a process holds it could not be determined: ...`,
+  and a real collision with `port <n> is already in use: ...` followed by what holds it and what to
+  do, where all three used to read as "already in use" or as the generic start failure.
+- The startup `Runtime:` line names the driver that actually runs, and the no-tenant-isolation
+  warning is printed whenever that driver is `local`, even when the host would prefer Docker (#476).
+- An agent pushed with no runtime profile can run (#504): the start creates or adopts a runtime
+  profile named `local` and makes it the workspace default unless one is already chosen, and under
+  posture `local` the in-process `local` driver no longer needs a Test Runtime first.
+- An agent whose version names the `default` connection but no model, as a new project's scaffold
+  writes it, can run (#506): the launcher sets `AW_DEPLOYMENT_DEFAULT_MODELS` to a per-provider
+  deployment default (`claude-sonnet-4-5` for Anthropic, `gpt-5.1` for OpenAI) unless `.env` or the
+  environment sets it, so the run is no longer refused with `422 model_connection_unresolved`.
+- Ctrl+C on `aw dev` stops the runtime in order (#510): the embedded PostgreSQL postmaster is
+  spawned by the runtime in its own process group (ADR-0112), so the terminal's SIGINT reaches only
+  the launcher, which revokes the credential, closes the server and its database pools and then
+  stops PostgreSQL. A closed terminal or console (SIGHUP) and Ctrl+Break (SIGBREAK) run the same
+  ordered stop. The
+  server's database pools (and the migration and bootstrap lock clients) report a failed
+  connection as one `[db] … (<code>)` line instead of an uncaught `57P01` error. A launcher
+  killed with SIGKILL now leaves the postmaster running, and the next start reports the embedded
+  PostgreSQL's port in use until it is stopped.
+- `aw dev` explains the ports it cannot use (#560). `environments.local.port` 4000 and 8080, the
+  local runtime's own gateway and runner ports, are refused by `aw check` and `aw dev` with the
+  file position. The launcher also refuses a port equal to the gateway or runner port `.env` sets
+  (naming `GATEWAY_PORT` or `RUNNER_PORT`, read as each service reads it, so a blank `RUNNER_PORT`
+  is 8080) and the embedded PostgreSQL's port unless `DATABASE_URL` is set.
+  A port the process may not listen on, such as 80 as a normal user, is reported as
+  `permission denied to listen on port 80; ports below 1024 need elevated privileges, choose a port from 1024 to 65535`
+  instead of `the local runtime failed to start (Error)`. A second `aw dev` in a project whose
+  runtime is still running is reported as
+  `port <n> is already in use, and this project's local runtime may already be running (.agent-workspace/runtime.pid records process <pid>); if aw dev is running in this project, stop that aw dev before running it again`,
+  from the pid the launcher keeps in `.agent-workspace/runtime.pid` while it runs. A pid cannot
+  prove its process is an aw runtime, so the message never says to stop that pid, and a start whose
+  services all bind over a live record (a stale pid reused by another process) re-records itself.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Agent Workspace contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,309 @@
+# `@indx-workspace/embedded` — the Agent Workspace local runtime
+
+The control plane (web), the model gateway and the runner in **one Node process**, over an
+embedded PostgreSQL 17 and local files. A generated project runs it as `aw dev`, which resolves
+this package's `./launch` export from the project's dependencies and forks it; it never imports
+it ([ADR-0109](../../docs/adr/0109-the-local-runtime-publishes-as-one-bundled-package-that-aw-dev-runs-from-the-project.md)).
+`aw dev` itself is a later unit of the developer journey (S1-13).
+
+The package exports no importable API. Its `exports` are exactly:
+
+| Export           | Target           | Who reads it                                            |
+| ---------------- | ---------------- | ------------------------------------------------------- |
+| `./launch`       | `./dist/bin.js`  | `aw dev`, which resolves the path and forks it          |
+| `./package.json` | `./package.json` | `aw dev`, which checks the runtime's version equals its |
+
+The server images stay the production path. The local runtime has no tenant isolation: the
+`local` runtime driver runs commands as you.
+
+## Installing
+
+A generated project depends on this package, at the same version as `@indx-workspace/aw`. Its
+`embedded-postgres` dependency installs the PostgreSQL binaries for your platform from one of the
+eight `@embedded-postgres/*` packages, whose install script restores the binaries' symlinks.
+
+- **npm** runs dependencies' install scripts by default, so `npm install` needs nothing more.
+- **pnpm** runs none it has not been told to allow: a pnpm project must allow the eight
+  `@embedded-postgres/*` builds (`allowBuilds` in `pnpm-workspace.yaml`).
+- **After `npm install --ignore-scripts`**, run `npm rebuild @embedded-postgres/<platform>` (for
+  example `@embedded-postgres/linux-x64`). It restores the PostgreSQL symlinks and runs no other
+  package's script.
+
+The release smoke (`pnpm release:pack --smoke`) installs the packed tarballs this way and boots the
+runtime from them: `ready`, `credential`, `GET /api/me` answering 200, and exit 0 on SIGINT. The
+first npm publish is the Owner's step (see "Declared gap"), so until then the package is proven
+from tarballs only.
+
+## Two ways to run it
+
+**Contributor path, from a repository clone.** `pnpm start:embedded` compiles `src/` with `tsc`
+into `dist/contributor` (the `build-contributor` target) and runs `dist/contributor/index.js`. The
+web server is Next development mode from `apps/web`, as before; the command prints
+`Agent Workspace is ready at …` once every server answers.
+
+**Published path.** `pnpm --filter @indx-workspace/embedded build` (also part of `pnpm build`)
+runs `node src/packaging/main.ts` (Node strips the types) and writes:
+
+- `dist/launch.js`: an esbuild bundle of `src/launch.ts` (ESM, no splitting, no source map).
+  Every workspace member it reaches (the server packages, the four engine adapters, the CLI, the
+  contracts and the SDK) is inlined; every third-party package stays an external `import`.
+- `dist/bin.js`: a few lines from `src/bin.ts`. When it is `argv[1]` it imports `./launch.js` and
+  runs the runtime; importing it does nothing. It takes no arguments and refuses any it is given
+  (exit 1) rather than ignore them; configuration comes from the environment and from `.env` in the
+  working directory, which is optional. A failed start exits with a non-zero code: the bin calls
+  `process.exit` itself, because `embedded-postgres` installs an exit hook that would otherwise
+  end the process with 0. `argv[1]` is resolved as Node resolves the main module, so
+  `node dist/bin` and `node dist/launch` are recognised as well.
+- `dist/web/`: `next build --webpack` of `apps/web` into the distDir `.next-embedded`, without the
+  build cache, the route types, the traces, the `*.nft.json` files and source maps, plus a
+  generated `next.config.mjs` naming that distDir. The launcher serves it with
+  `startWeb(env, { dir: dist/web, dev: false })`.
+- `dist/migrations/`: a copy of the repository's `migrations/`, journal included. The launcher sets
+  `MIGRATIONS_DIR` to it unless it is already set.
+- `publish/`: the staging directory the package is packed from (git-ignored). See below.
+
+**Never run `dist/launch.js` directly.** Inlined modules compare their own `import.meta.url` with
+`argv[1]` to decide whether they are the main module, and inside the bundle that URL is the
+bundle's. Run directly, it refuses with `run dist/bin.js, not the bundle` and exits 1. `launch.ts`
+reaches the servers only through a dynamic `import()`, so that refusal runs before any inlined
+module's top level. It does not run before the third-party externals, which ESM links first (see
+"Why the externals are pinned here too"): the refusal assumes they are installed, as they are in
+the repository and in an installed package, and a missing one fails with Node's resolution error
+instead.
+
+The web build leaves `apps/web` as it found it: Next rewrites `apps/web/tsconfig.json` and
+`next-env.d.ts` for a custom distDir, so both are saved byte for byte and restored, and
+`apps/web/.next-embedded` is removed, in a `finally`. The build then fails if
+`git status --porcelain apps/web` differs from what it was before the build. A contributor's own
+uncommitted edits under `apps/web` are therefore allowed; a trace the build left is not. The Nx
+`build` target runs after `web:typecheck` and `web:lint`, so CI's parallel fast checks never read
+the half-written build.
+
+## The published launcher (`aw dev`)
+
+`dist/bin.js` behaves in one of two ways. Started without an IPC channel (`node dist/bin.js`), it
+keeps the environment-only start described above. Forked with an IPC channel, as `aw dev` forks
+it, it is the launcher of S1-11 (issue #449) and speaks the protocol of
+`@indx-workspace/contracts/local-runtime`:
+
+1. `aw` → runtime: `start {projectDir, environment: {port, runtimeDriver?, bootstrapAdmin}}`.
+   The launcher waits up to 60 seconds for it. A message that schema refuses (an unknown key, a
+   wrong type, or a runtime-to-`aw` message such as `ready`) is answered with `failed`.
+2. runtime → `aw`: `ready {url, contractsVersion}`, once the web server, the gateway and the
+   runner answer and the server serves this package's contracts version. `url` is always a
+   loopback URL.
+3. runtime → `aw`: `credential {token, expiresAt, workspaceId, workspaceSlug}`, where `token` is
+   a workspace API key (`ak_live_…`) for the local workspace (`WORKSPACE_SLUG`, or `default`),
+   minted in process by the server's own `issueLocalApiKey` at a role no higher than the
+   bootstrap admin's, expiring after 12 hours (ADR-0109's S1-21 amendment, issue #500). `aw` can
+   then reach every control-plane route it calls without a device grant, and keeps the key in its
+   own owner-only `~/.config/agent-workspace/local-credentials.json`. The key cannot write
+   `/api/api-keys`, `/api/users` or `/api/memberships`, so nothing it mints outlives the run;
+   `aw workspaces` and `aw invitations` refuse API keys, so use the browser sign-in for them. The
+   key travels only over the IPC channel and is revoked on stop, before the database stops; a key
+   a crashed run left behind is revoked on the next start. Before minting it, the launcher makes
+   a runtime profile named `local`, on the `local` driver, the workspace default, creating or
+   adopting it, unless the workspace already has a default (ADR-0109's S1-22 amendment, issue
+   #504), so an agent pushed with no runtime profile runs on it. A profile named `local` on
+   another driver is left alone with one warning on stderr.
+4. Any failure, before or after `ready`, sends `failed {message}` instead, releases what was
+   started and exits 1. The message is terminal-safe (no control character, at most 4096
+   characters) and never carries a secret. A port already in use is reported as
+   `port <n> is already in use`. For the embedded PostgreSQL's port, 25432 by default, the message
+   goes on to say that another process holds it (for example another project's `aw dev`, or a
+   PostgreSQL a killed run left behind) and what to do (stop it, or set `AW_DATABASE_PORT` in
+   `.env` to another free port below 49152). A PostgreSQL port that cannot be bound although
+   nothing listens on it is reported as
+   `port <n> cannot be bound on 127.0.0.1, but no process is listening on it: ...`, and one whose
+   listener check is inconclusive as
+   `port <n> cannot be bound on 127.0.0.1, and whether a process holds it could not be determined: ...`,
+   both naming `AW_DATABASE_PORT` and `DATABASE_URL` (see "The embedded PostgreSQL's port" below). A start
+   that has not sent `credential` five minutes after `start` arrived is reported as
+   `the local runtime did not become ready in time`.
+   A port the process may not listen on is reported as `permission denied to listen on port <n>`,
+   with a hint to choose a port from 1024 to 65535 when it is below 1024 (issue #560). The
+   runtime's own gateway (4000) and runner (8080) ports are refused as `environments.local.port`
+   by `aw check` and `aw dev`; the project file is shared, so that check follows the fixed ports
+   whatever `.env` says. The launcher refuses again the ports this machine's runtime will bind: the
+   `GATEWAY_PORT` and `RUNNER_PORT` that `.env` sets (the message names the variable), and the
+   embedded PostgreSQL's port unless `DATABASE_URL` is set. The launcher records its pid in
+   `.agent-workspace/runtime.pid` while it runs; a second start in the same project that collides
+   on a port while that process is alive is reported as
+   `port <n> is already in use, and this project's local runtime may already be running (.agent-workspace/runtime.pid records process <pid>); if aw dev is running in this project, stop that aw dev before running it again`.
+   The file only words that diagnosis: it never refuses a start, and a pid cannot prove its process
+   is an aw runtime, so a start whose services all bind over a live record re-records itself.
+
+`projectDir` must be an existing absolute directory. The launcher changes into it and keeps all
+its state under `<projectDir>/.agent-workspace/`: the embedded PostgreSQL in `postgres/`, the
+file, skill and transcript storage, and the secrets.
+
+**The environment it sets (contract C1).** From `start`: `PORT`, `BOOTSTRAP_ADMIN` and, when given,
+`RUNTIME_DRIVER`. For the local posture: `AW_DEPLOYMENT_POSTURE=local`, `HOST=127.0.0.1` and
+`AW_LOCAL_SURFACE_SESSIONS=1`. `MIGRATIONS_DIR` defaults to `dist/migrations`. A value already set
+in the process environment or in `.env` that differs from the one required is refused, never
+silently overridden: the launcher sends `failed` naming the variable (never its value), so
+`HOST=0.0.0.0` fails with `local posture needs a loopback HOST`, and another loopback host such
+as `HOST=localhost` with `the local runtime binds 127.0.0.1`. A `WORKSPACE_SLUG` that is set
+must be a workspace slug, and an unreadable `.env` is refused naming its path. The one forced value is
+`NODE_ENV=production`: it states how the bundle and `dist/web` were built, not a setting. The
+server's deployment-posture check then runs on the result. `GATEWAY_PRICING_JSON`, which the
+gateway needs to start, defaults to the fail-closed sentinel `.env.example` ships (it matches no
+real provider model, so metered runs fail closed); set reviewed rates in `.env` to replace it.
+`AW_DEPLOYMENT_DEFAULT_MODELS` defaults to `{"anthropic":"claude-sonnet-4-5","openai":"gpt-5.1"}`,
+so an agent whose version names the `default` connection but no model runs on that provider's id
+(contract C7, the last layer of the run model ladder, ADR-0103 amendment); a value set in `.env` or
+the environment wins, and an empty one turns it off.
+
+**The runtime directory and its secrets.** Before it writes anything else into `.agent-workspace/`,
+the launcher writes `.agent-workspace/.gitignore` containing `*`, so a project without a root
+`.gitignore` never stages the database, the storage or the secrets. An existing `.gitignore` there
+must keep a line that is exactly `*` and contain no negation (`!…`) line, which could un-ignore
+the secrets file, or the launcher refuses to start; so it does when `.agent-workspace` is not a
+directory. On the first start it
+generates `SESSION_SECRET`, `MASTER_ENCRYPTION_KEY`, `GATEWAY_TOKEN_SECRET` and
+`BOOTSTRAP_ADMIN_PASSWORD` into `.agent-workspace/local-secrets.json`, created with mode `0600`.
+Later starts reuse the file unchanged (and tighten a looser mode back to `0600` on POSIX), so
+sessions, encrypted secrets and gateway tokens survive a restart. A file that cannot be parsed or
+fails validation is refused with an error that names its path and never its contents. The
+precedence is the process environment, then `.env` in the project directory, then
+`local-secrets.json`: a value from either of the first two wins over the file. A blank value,
+such as the `SESSION_SECRET=` line `.env.example` ships, counts as unset.
+
+**The key.** It travels only over the IPC channel: the launcher never writes it to stdout,
+stderr, a log or a file. On SIGINT, SIGTERM, SIGHUP (a closed terminal or console window), SIGBREAK
+(Windows' Ctrl+Break) or the IPC channel disconnecting, the launcher revokes
+it first, while the database is still up, then closes its database root and the servers, and
+exits 0. The same triggers during the start (and a signal while it still waits for `start`)
+abandon the step in progress at once, release what was acquired and exit 0 without sending
+`failed`. A crash or a `SIGKILL` cannot revoke it, so such a key stays valid until it expires,
+twelve hours after it was issued (the CLI token lifetime), or until the next start, which revokes
+every unrevoked key whose name starts with the reserved `aw dev local runtime` prefix before
+minting its own.
+
+**Ctrl+C in a terminal.** The terminal sends SIGINT to every process in its foreground process
+group. The runtime starts the embedded PostgreSQL postmaster itself, `detached` (ADR-0112): on POSIX
+in its own session and process group, on Windows in its own process group with no console. So a
+Ctrl+C reaches only the launcher, which revokes the key, closes the server and its database pools,
+and only then stops PostgreSQL (SIGINT, a fast shutdown; SIGKILL to the postmaster's group if it has
+not exited within 30 seconds; `taskkill /t` on Windows). A database connection that still fails
+during that stop is reported as one `[db] a database connection failed (<code>)` line, never an
+uncaught error. A closed terminal (SIGHUP) or Ctrl+Break (SIGBREAK) runs the same ordered stop. An
+exit through `process.exit`, an uncaught exception or an empty event loop sends the postmaster
+SIGINT from an `exit` hook. A launcher killed with `SIGKILL`, or ended by another signal's default
+action (such as SIGQUIT, `Ctrl+\`), runs no code at all, so it leaves the postmaster running: the
+next start then fails with `port 25432 is already in use` (or the `AW_DATABASE_PORT` port) until
+that postmaster is stopped (`kill <pid>`, the pid being the first line of
+`.agent-workspace/postgres/postmaster.pid`). On a first start, `initdb` still runs in the
+launcher's group, so a Ctrl+C during the first initialisation aborts it, and the start is
+abandoned as any other interrupted start is.
+
+**The sign-in line.** On the first start, when the password was generated into
+`local-secrets.json`, the launcher prints the admin email and that password once on stdout. Later
+starts print only where the password is: the path of `local-secrets.json`, or that it is set in
+`.env`.
+
+`src/local-launcher.integration.test.ts` forks the built `dist/bin.js` in a temporary project
+directory on free ports and checks the sequence end to end: `ready` then `credential`,
+`GET /api/me` and `GET /api/model-connections` with the key answering 200, the `.gitignore` and
+the secrets file (its mode outside Windows), exit 0 on SIGINT, a restart that reuses the secrets
+byte for byte and answers 401 to the first, revoked key, and no key in either run's stdout or
+stderr. A second describe forks the launcher `detached`, so that it leads its own process group as
+a terminal job does, and sends SIGINT to that whole group (on Windows it closes the IPC channel):
+the postmaster is in a group of its own, the launcher exits 0 with no revoke warning, no
+`terminating connection` error and no stack trace, the postmaster and port 25432 are gone, and a
+restart answers 401 to the first key, whose row was revoked before the first runtime exited. Its
+last test
+holds port 25432 and checks that a start then answers `failed` with the full in-use message and
+exits 1. The embedded PostgreSQL listens on that fixed port, so the earlier tests fail, naming it,
+while another embedded runtime runs on the same host.
+
+**The embedded PostgreSQL's port.** It is 25432, fixed and deterministic, below every default
+ephemeral range (Linux 32768-60999, Windows and macOS 49152-65535). The earlier 54329 sat in
+Windows' dynamic range, which Linux cannot bind under WSL2 mirrored networking (issue #556).
+`AW_DATABASE_PORT`, from the environment or the project's `.env`, overrides it; it must be a whole
+number from 1024 to 65535, and any other value fails the start before anything is started, naming
+the variable and the range. A port equal to the web (`PORT`), gateway (`GATEWAY_PORT`) or runner
+(`RUNNER_PORT`) port also fails before anything starts, with
+`port <n> is both the embedded PostgreSQL's port and <VARIABLE>: ...`. When `DATABASE_URL` is set,
+no embedded PostgreSQL starts at all and the runtime uses that database. If the port cannot be
+bound, the start checks whether anything listens on it: if something does, it fails with
+`port <n> is already in use: ...`; if nothing does, the operating system reserves the port (a
+Hyper-V or WSL excluded range, for example) and it fails with
+`port <n> cannot be bound on 127.0.0.1, but no process is listening on it: ...`; if the check is
+inconclusive (it times out), it fails with
+`port <n> cannot be bound on 127.0.0.1, and whether a process holds it could not be determined: ...`.
+The last two tell you to set `AW_DATABASE_PORT` in `.env` to a free port below 49152, or
+`DATABASE_URL` to your own PostgreSQL. The start never moves to another port by itself: a second start on the same data
+directory must fail naming the port rather than start a second postmaster (ADR-0109, issue #556
+amendment).
+
+**The contributor path is unchanged.** `pnpm start:embedded` still generates fresh secrets on
+every run and writes no `local-secrets.json`.
+
+## The staging directory and the zero-leak gate
+
+This workspace manifest names the server members as `workspace:*` dependencies, so Nx builds them
+first and esbuild can inline them, and it stays `"private": true`. It is never packed. The build
+writes `publish/package.json` instead (the release packs `publish/`), from a whitelist of this manifest's fields (`name`,
+`version`, `description`, `license`, `homepage`, `repository`, `bugs`, `engines`, `type`,
+`exports`, `bin`), public `publishConfig`, and a `dependencies` map holding exactly:
+
+- every third-party package `dist/launch.js` imports (the externals in the esbuild metafile);
+- every package a webpack external module of the server chunks loads (`next`, `pg`);
+- the required (non-optional) peers of those, recursively (`react` and `react-dom` for `next`).
+
+The metadata fields beyond ADR-0109's list (`description`, `homepage`, `bugs`, `engines`), the
+public `publishConfig` and the required peers are deliberate: npm shows the first four, a scoped
+package publishes as restricted without the access setting, and `next` does not load without its
+peers installed beside it. The published `description` therefore describes the package alone.
+
+Each is at the exact version the lockfile installed, read with `module.findPackageJSON` from its
+importer. `dist/bin.js`, `dist/launch.js`, `dist/web/`, `dist/migrations/`, this README, `LICENSE`
+and `CHANGELOG.md` are copied beside it. The build fails, with a typed `EmbeddedBuildError`, when
+two importers resolve one external to two versions, when an external has no installed manifest,
+when a pin below differs from the installed version, or when a literal `require`/`import` in the
+server chunks is neither a webpack external nor one of the reviewed `NON_EXTERNAL_LOADS` (an
+optional `encoding` require of the bundled `node-fetch`, and two package names that occur only in
+the text of an AWS SDK error message).
+
+The packed tarball must not contain the private workspace scope anywhere, `dist/web/` and the
+packed manifest included. Inlined members that are reached through a dynamic `import()` (the
+runner's engine adapters) keep their whole namespace in the bundle, so no inlined module may hold
+its own package name as a string: the source does not carry one, and the bundle step rewrites
+nothing. The build fails (`foreign_scope_in_bundle`) if `dist/launch.js` or `dist/bin.js` names the
+private scope. `src/bundle.test.ts` packs `publish/` with `pnpm pack` and runs the
+release checks of `scripts/release/pack-packages.mjs` on it (`checkTarballEntries`,
+`checkPackedManifest`, `checkDistContents`), then logs the packed and unpacked sizes. A size budget
+is set from those measurements, not invented (ADR-0016).
+
+## Why the externals are pinned here too
+
+ESM links every static `import` of a module graph before any of it runs, and the bundle hoists the
+externals of its lazily initialised modules to the top of `dist/launch.js`. So the bundle, run from
+this directory in the repository, needs every external to resolve from `packages/embedded`. This
+manifest therefore pins each staged dependency at the same exact version, and the build fails when
+the two lists differ in either direction.
+
+## The knip exception
+
+`knip.json` lists, under this workspace's `ignoreDependencies`, the dependencies no file under
+`src/` imports by name: the bundle externals that only inlined members import, and the inlined
+workspace members that are reached only through other members. They are real run-time
+dependencies of the bundle, which knip cannot see. `src/knip-exception.test.ts` holds the list to
+that rule, so it cannot over-ignore: every name in it must be a staged dependency or an inlined
+workspace member.
+
+## Declared gap
+
+ADR-0082 D5: the first version of a new package is published by hand by the Owner (a
+`0.0.0-bootstrap` placeholder, as for the other five) before a trusted publisher can be
+configured. Until then `npm create @indx-workspace` cannot install this package from the public
+registry, and the publish workflow refuses a `packages-v*` release before publishing any package,
+so no partial lock-step set reaches npm; re-running its publish job after the Owner's step finishes
+the release ([docs/release](../../docs/release/README.md#npm-packages)). CI proves the path from
+tarballs only.
+
+Follow-up for the bundle build (S1-10): the Next build inlines `import.meta.url` values and page
+source paths as absolute paths of the build machine into about 200 `dist/web/` files. Nothing reads
+them at run time (the launcher sets `MIGRATIONS_DIR`, and `open` falls back to the system opener),
+but the published tarball names the CI runner's paths and is not reproducible across build hosts.