@outerlayer/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @outerlayer/cli
+
+## 0.1.0
+
+### Minor Changes
+
+- e27bd86: First release under the `@outerlayer/cli` name. The published package carries no dependencies: everything the CLI needs is bundled into its `dist`, so `npx @outerlayer/cli` installs the single tarball and nothing else.

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 Magu Studios, Inc.
+
+   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,320 @@
+# outerlayer
+
+Capture what your coding agents actually did, and sync it to your OuterLayer
+cloud workspace.
+
+OuterLayer captures the sessions your coding agents already write to disk
+(Claude Code, Codex CLI, Cursor) and syncs them to your OuterLayer cloud
+workspace, where you and your team can see what your agents did across every
+repo. Capture itself is local: it reads the session files your agents already
+write to disk. Uploading is a separate, launch-gated step — what reaches the
+network, and when, is below.
+
+Launch a session naming the work it's for, then sync:
+
+```
+npx @outerlayer/cli init                          # install the capture hooks
+npx @outerlayer/cli work add --issue 42           # create the work item; prints its number
+OUTERLAYER_WORK=7 claude                     # launch a session naming that number
+npx @outerlayer/cli sync --dry-run                # see exactly what would leave your machine
+npx @outerlayer/cli sync                          # upload sessions launched that way
+```
+
+## Privacy, stated plainly
+
+**A session uploads only when you launch it with `OUTERLAYER_WORK` naming
+the work item it's for.** Create the item first with `outerlayer work add`,
+which prints its factory-scoped number, then set that number before
+starting your agent — `OUTERLAYER_WORK=7 claude`. The session-start hook
+then records the launch and the session uploads whole, from its first turn,
+until it ends. A session launched without the variable never leaves the machine,
+in any tool, however `sync` is invoked. There is no way to turn upload on
+mid-session — the decision is made once, at launch.
+
+Only Claude Code has a session-start hook today, so only Claude Code sessions
+can be launched as work. Codex CLI and Cursor sessions are captured locally
+and never upload.
+
+**`outerlayer sync` is the complete upload, and it sends only launched
+sessions.** It runs when you run it. The hooks also fire `outerlayer sync
+--quiet` in the background after each agent turn and when a session ends, at
+most once every five minutes, as soon as `outerlayer login` has saved
+credentials. So a launched session uploads while it is still running, not
+only once it is over. Set `"autoSync": false` in `~/.outerlayer/config.json`
+to leave every automatic upload — the background sync and the daemon's
+streaming below — to your own command.
+
+**`outerlayer daemon` uploads a launched session as it grows, turn by turn,
+while it runs, and nothing else.** The same launch gate as `sync` applies: a
+session started without `OUTERLAYER_WORK` is never streamed, in whole or in
+part, and neither is a session the repo filter excludes. It sends only the
+turns since the last one it already sent, and it stops sending the moment
+the session ends. `"autoSync": false` stops it too, and it is read on every
+send, so turning it off takes effect without restarting the daemon.
+`outerlayer sync` still runs on top of this and remains the complete,
+authoritative upload — the daemon exists so a session's page can follow
+along before that sync ever runs.
+
+These commands also talk to your workspace. None of them sends session
+content:
+
+- **`outerlayer work add`, `remove`, `status`, `list`, `link-session`, `pr`,
+  `claim`, `renew`, `release`** read and write your Floor. The session-start
+  hook spawns `outerlayer work link-session` when you launch a session with
+  `OUTERLAYER_WORK`, naming the item and the session id — the item itself
+  must already exist, created ahead of time with `outerlayer work add`.
+  `outerlayer work pr` sends the session id and the pull request number and
+  repository — never the session's own content. `outerlayer work claim`
+  records a lease for this host before it starts working on an item, so two
+  hosts never build the same piece of work at once; `renew` extends it and
+  `release` marks it done. A runner key needs `git_connection.read` to list
+  and read items, `work_item_claim.insert` to claim, and
+  `work_item_claim.update` to renew or release — the two claim permissions
+  are not granted to a dashboard role by default, since a claim is a host's
+  lease, not a person's.
+- **`outerlayer runner start`** lists, claims, renews and releases work
+  items the same way `work claim`/`renew`/`release` do, on the schedule its
+  config sets — it sends nothing about the job it runs beyond that; the
+  agent it starts is a separate process with its own credentials, from the
+  `runner` block, never the copy-out daemon's. `runner check` makes one
+  list call to confirm the key works and sends nothing else; `runner init`,
+  `runner status` and `runner logs` make no network call at all.
+- **`outerlayer emit artifact`** uploads the file you name — a screenshot, a
+  recording, a report, a log — along with its caption. With no recorded
+  session to attach it to, it uploads immediately, anchored to a pull request
+  or to the git checkout.
+- **`outerlayer emit <name>`** and **`outerlayer emit commit-credit`** send
+  one check's outcome, and one commit's attribution, for a work item. Run
+  from inside a session, they send only when that session carries a launch
+  record — the session's own content may not leave by a second route. Run
+  from CI or a plain shell, where there is no session, they send as they
+  always have.
+- **`outerlayer emit finding`** and **`outerlayer emit findings <file>`** send
+  one finding, or a whole batch of them, for a work item — the same
+  anchoring as `emit <name>` (`--item`, or the recorded session's own item),
+  except a session may record findings on the item it was launched for.
+- **`outerlayer mcp serve`** is the stdio MCP server your editor spawns. It
+  forwards every JSON-RPC message the editor sends to the gateway and returns
+  the reply.
+
+The session-start hook reaches the network in two more cases:
+
+- **In a repository your factory governs**, it asks the control plane which
+  context repository and ref this checkout is pinned to (`GET
+  /v1/context/source`, with your API key), then `git fetch`es that ref. It
+  sends the repository name; it degrades to the last known commit when the
+  control plane cannot be reached.
+- **When your repository's git hooks are missing**, it runs that
+  repository's own `prepare` script (`yarn prepare` / `npm run prepare`).
+  What that script does is your repository's business; installers commonly
+  download packages.
+
+The daemon's one-shot sweep (`outerlayer daemon --once`) makes no network
+calls — the copy-out mirror it performs is the same one the long-running
+daemon runs continuously, and neither the sweep nor an ineligible session
+in the long-running daemon opens a connection. The session-start hook makes
+none either, in a repository your factory does not govern. All three are
+checked rather than promised: a test runs each of them with `fetch` and
+`net.Socket.prototype.connect` replaced by stubs that throw, and asserts
+nothing tried to connect. Those two stubs cover every outbound path this
+process opens itself — anything built on `node:http`, `node:https` or
+`node:tls` opens its socket through `connect`, and `fetch` opens its own
+below that method. A child process opens its sockets in its own address
+space, past both stubs, so the same test records every program each run
+starts and asserts none of them fetches over the network.
+
+Failures the hook cannot show you — a refused `OUTERLAYER_WORK` value, a
+`work add` that could not reach the Floor — are appended to
+`~/.outerlayer/spool/hook-errors.log`, and the next session start says so.
+The addition retries a gateway it cannot reach a few times, with backoff,
+before it gives up.
+
+- **The tier is applied before anything leaves.** The default tier is
+  `full`: message text, thinking, images, and tool input/output all ship.
+  `--tier redacted` strips that content client-side, keeping only structure
+  (repos, branches, file paths, tool names, error signatures) and metrics;
+  `--tier metrics` strips identifiers too (the server additionally clamps to
+  your org's configured ceiling — sending more than it allows stores less).
+- **`--dry-run` shows exactly what would leave** — per-session rows, image
+  bytes, and the precise field classes stripped at the chosen tier. Add
+  `--json` to inspect the literal request payloads. Zero network calls.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `outerlayer sync` | Upload sessions launched with `OUTERLAYER_WORK` to your OuterLayer cloud workspace (incremental — only what's new since the last sync). Tier-gated client-side (`--tier metrics\|redacted\|full`, default `full`); `--dry-run` prints exactly what would leave the machine; `--all` re-sends everything (idempotent server-side). Credentials come from `outerlayer login`, `OUTERLAYER_*` env vars, or `--url/--app-id`. |
+| `outerlayer login [--url] [--app-id]` | Save the cloud URL, app id, and API key to `~/.outerlayer/config.json` once. The key is read from stdin (`echo "$KEY" \| outerlayer login …`) or a prompt with echo off; it is never a flag. `--no-input` refuses to prompt. |
+| `outerlayer init` | Install the capture hooks and the status-line segment. `--json` for scripts. Claude Code deletes transcripts after ~30 days; run `outerlayer daemon` separately to mirror them first — `init` does not start it for you. |
+| `outerlayer daemon` | Run the copy-out daemon in the foreground (`--once` for a single sweep, which uploads nothing). Once cloud credentials exist, it also streams a launched session's new turns as they land — see Privacy, above. `outerlayer watch` is the former name and still works, with a warning. |
+| `outerlayer doctor` | Check the installation: hooks, status-line freshness, and sync health. `--json` prints the checks and a summary for scripts. |
+| `outerlayer context emit [--check]` | Compile `.outerlayer/` into each configured target tool's native files (targets come from `.outerlayer/config.json`). `--check` computes outputs and diffs against disk without writing (CI mode). Bare `outerlayer emit` with no name still compiles, with a deprecation warning. |
+| `outerlayer import ruler` | Port a `.ruler/` tree ([Ruler](https://github.com/intellectronica/ruler)) into the equivalent `.outerlayer/` tree — mostly a rename; never overwrites an existing `.outerlayer/`. |
+| `outerlayer hooks wrap` / `outerlayer hooks unwrap` | Auto-wrap (or undo wrapping) `PreToolUse`/`PostToolUse` hooks for execution evidence — one spawn per firing. |
+| `outerlayer emit artifact <file> --caption <text> [--for <criterion-id>] [--pr <n>]` | Upload a proof artifact — screenshot, recording, report, or log — with its caption. Inside a recorded session it spools locally and ships on the next `sync`; otherwise it uploads immediately, anchored to a pull request or the current checkout. `--replaces` retires artifacts an earlier run uploaded. |
+| `outerlayer emit <name> --result <pass\|fail> [--link <url>] [--body <text>\|--body-file <path>] --item <number>` | Record one named check's outcome on a work item. A check that ran carries the run URL as its proof (`--link`); a judgment you are making yourself carries one sentence (`--body`, or `--body-file` to read it from a file — `-` reads standard input). A `fail` needs at least one of the two; a `pass` needs neither. `--item` names the work item by the number printed when the item was created — always required, in or out of a recorded session; from inside a session it can only name an item that session was NOT launched for (a session cannot record a check on its own item). Prints the recorded check's id. Who recorded it comes from your API key, never from what you send. |
+| `outerlayer emit artifact-review --result <pass\|fail> --artifact <id> [--body <text>\|--body-file <path>]` | Record a person's own pass or fail on one artifact — evidence already emitted, bound to a criterion. `--artifact` names it and replaces `--item`; the gateway resolves the work item from the artifact's own pull request. `--link` is refused. A `fail` reads its sentence from `--body`/`--body-file`, or from standard input when neither is given. Refused from inside a recorded session — an artifact verdict is a person's act, the same rule the gateway enforces. Prints the recorded verdict's id. |
+| `outerlayer emit commit-credit --pr <n> …` | Send one commit's attribution for a pull request. |
+| `outerlayer emit finding --id <id> --subject <change\|context> --title <text> --file <path> --kind <behavior\|hygiene\|proof> --verdict <confirmed\|refuted\|unverified> --source <implementer\|reviewer\|refuter\|gate> --where <label> [--item <number>] …` | Record one finding — what was found wrong about the change (`--subject change`) or about a rule it ran on (`--subject context`, which then needs `--rule-path`, `--rule-quote` and `--rule-relation` together — all three are required, not just `--rule-path`). Validated against the same contract the gateway checks before anything is sent. `--item` names the work item; without it, inside a recorded session, the item that session was launched for is used automatically — unlike `emit <name>`, a session may record findings on its own item. Re-emitting the same `--id` on the item replaces that finding. |
+| `outerlayer emit findings <file> [--item <number>]` | Record a whole batch at once, read from a `FindingBatch` JSON file (`-` for standard input) — the same shape and validation as `emit finding`, one record per subject/title/file/kind/verdict/source/where. Anchored the same way: `--item`, else a recorded session's own item. |
+| `outerlayer mcp install [--transport stdio\|http] [--url] [--name] [--command]` | Write (or update) an `mcpServers` entry in `.mcp.json` for the OuterLayer gateway. Default `stdio`: the client spawns `outerlayer mcp serve`, which reads the API key from `~/.outerlayer/config.json` (or `OUTERLAYER_API_KEY`) each time it connects, so a reconnect picks up a newly saved or rotated key. `--transport http` writes a direct `POST /v1/mcp` entry referencing `${OUTERLAYER_API_KEY}`, resolved by the client from the environment it was launched with. Never writes an API key. Pass `--url`/`--app-id` for self-host. |
+| `outerlayer mcp serve [--url] [--app-id]` | Stdio MCP server bridging stdin/stdout JSON-RPC to the gateway's `POST /v1/mcp`. What the stdio `.mcp.json` entry runs; exits 1 with a clear message when no API key is configured. |
+| `outerlayer work add --issue <n>\|--pr <n> [--repo] [--note]` | Records that a source — a recorded session, a CI run, or the API key's bound member — is working on an issue or pull request. The only way an item becomes visible on the Floor. |
+| `outerlayer work remove --issue <n>\|--pr <n> --reason <text> [--repo]` | Withdraws the caller's own addition, recording the reason. Never deletes anything; the item leaves the Floor only once no live addition remains on it. Removing again is a no-op that still succeeds. |
+| `outerlayer work status --issue <n>\|--pr <n> [--repo]` | Shows one item's stage, section, gate ledger, linked pull requests and sessions, and its additions. |
+| `outerlayer work list [--stage] [--section] [--repo] [--unclaimed] [--startable] [--needs amend]` | Lists live work items for the current factory, filterable by stage, section, claim state and whether an open fail is waiting for an answer. |
+| `outerlayer work pr <n> [--repo] [--session-id]` | Run inside a session on a work item: declares that pull request `<n>` in the checkout's repository belongs to that item. Idempotent — declaring the same pull request twice is a no-op. Refuses when the session is on no item, or the repository is not connected. |
+| `outerlayer work claim --item <n>\|--issue <n> --kind implement\|amend [--repo] [--host] [--seconds]` | Records a lease for this host (default: its own hostname), so two hosts never build the same item at once. A live lease already held by a different host is refused; claiming again under the same host extends it. Lease length defaults to 900 seconds, the server's own cap. |
+| `outerlayer work renew --item <n>\|--issue <n> [--repo] [--host] [--seconds]` | Extends this host's own live lease. Refused if the lease has expired, or if a different host holds it. |
+| `outerlayer work release --item <n>\|--issue <n> [--repo] [--host] [--outcome]` | Marks this host's lease released, optionally recording how the attempt ended. Releasing an already-released lease is a no-op that returns the recorded release time and outcome. |
+| `outerlayer runner init [--config <path>]` | Writes a `runner` block with defaults and three example hooks, keeping every key the config already had. Refuses rather than overwriting an existing block. |
+| `outerlayer runner check [--config <path>]` | Validates the config, the hooks and the key, prints the settings the runner would use, and exits non-zero on a problem. Takes no work and writes no pid file. |
+| `outerlayer runner start [--config <path>]` | Runs the loop: claim work, run it, sync, clean up, report, release with an outcome. Repeat. Reads the `runner` block from the config file (default `~/.outerlayer/config.json`). Refuses to start on a bad config, an unrunnable hook, or a refused key. |
+| `outerlayer runner stop [--config <path>] [--now]` | Takes no more work and waits for running jobs to finish, naming each every five seconds. `--now` ends them immediately with outcome `stopped`. Ctrl-C on a foreground runner drains; a second one stops now. |
+| `outerlayer runner status [--config <path>] [--recent] [--json]` | A header naming the runner's own state, then a row per running job — item, queue, stage, elapsed, started, lease, job directory. `--recent` adds finished jobs, newest first, capped at 20, with their outcomes. |
+| `outerlayer runner logs <item> [--config <path>] [-f]` | Prints the newest attempt's log for one item, following it with `-f`. |
+
+The `work` commands need an API key that carries `Ingest traces`
+(`trace.write`) to add, remove, and declare a pull request (`pr`), and `Read
+the Work page` (`git_connection.read`) to look an item up — which `remove` and
+`status` both do before they act. Tick both when you mint the key, in
+Settings → API keys. Claiming a lease needs `Claim work items`
+(`work_item_claim.insert`); renewing or releasing one needs `Renew or
+release work item claims` (`work_item_claim.update`). Withdrawing an
+addition somebody else made additionally needs `Withdraw others' work from
+the Work page` (`git_connection.update`).
+
+### Recording your own pass or fail on a check
+
+`outerlayer emit` also records a judgment you make yourself, under a check
+name a validator declares, on the work item — not any one pull request, so
+it holds across every pull request the item has. Say what is wrong, in one
+sentence:
+
+```
+outerlayer emit code-review --result fail --item 412 \
+  --body "The button should be the destructive red, not grey."
+```
+
+The sentence can come from a file, or from standard input with `-`:
+
+```
+echo "The button should be the destructive red, not grey." \
+  | outerlayer emit code-review --result fail --item 412 --body-file -
+```
+
+Record a pass once the work is right:
+
+```
+outerlayer emit code-review --result pass --item 412
+```
+
+`--item` is always required, in or out of a recorded session. A session
+records a check only on an item it was NOT launched for, by naming it with
+`--item`; a check on the item the session itself was launched for needs a
+machine key (an API key run outside the recorded session) or CI.
+
+Three things to know. Who recorded a check is decided by the API key you
+used, never by anything in the request. A key bound to a membership records
+the check against that person, and once a fail is recorded, only a person's
+key can record over it. A failing check needs a run link or a sentence,
+because a fail with neither is something nobody can act on. And a check only
+holds a gate once a validator in `.outerlayer/validators/` declares its emit
+name; without one the check is recorded and read back, and blocks nothing.
+
+A review of the work itself is different: it is recorded from the Review
+tab on the work item page, not the CLI, and holds every pull request of the
+item until a person records a pass — no validator declaration needed.
+`outerlayer emit` refuses `work-review` outright; recording it anywhere but
+the work item page is not supported. The gateway refuses a review, and an
+artifact verdict, on an item that is closed or shipped, has no evaluation
+yet, or whose evaluation is still waiting on a session link, with the code
+`item_not_reviewable`. A recorded pass carries the head commit of every
+pull request the item had at the time; once one of them moves, that pass
+stops counting and a fresh review is needed. A repository can require a
+current pass before the evidence check completes by setting the base
+branch's `review` policy key to `required` (default `optional`, alongside
+`merge_gate`) — the check then stays in progress, not failed, until a
+current pass exists.
+
+`outerlayer emit artifact-review` sits between the two: a person's own pass
+or fail, like a review, but on one piece of evidence rather than the whole
+item. A fail here holds the item the same way a review's fail does, and
+counts the work as bad on Quality once, however many artifacts carry one —
+it also lists the item on a queue the API exposes, naming the artifact and
+why it failed, so a host with a session linked to the item can answer it
+with a replacement, or the fail's own recorder can pass over it directly.
+The item's own pass stays available only once every required artifact has
+a pass and no fail is still open.
+
+Every command accepts `--no-color`, and color is off on its own when stdout is not a terminal, when `NO_COLOR` is set, or when `TERM` is `dumb`. `FORCE_COLOR=1` turns it on for a pipe. Commands that print anything accept `--json`.
+
+## Status line
+
+`init` also adds an ambient Claude Code status-line segment showing what your
+session and your agents are costing today:
+
+```
+⬢ OL  $0.87 session · $23.40 today across 3 agents · 12 unsynced
+```
+
+The session figure comes straight from Claude Code's own cost field, so it
+always matches what Claude Code itself would show. The cross-agent total and
+unsynced count come from `~/.outerlayer/statusline.json`, a small file the
+`watch` daemon keeps fresh — the status line itself never parses transcripts,
+so it stays well under Claude Code's refresh budget. On a day with only one
+active agent, the scope adapts: `across N agents` becomes `across N sessions`
+if you ran several sessions with it, or drops entirely to a bare `$X today`
+for a single session — "across 1 agent" never appears.
+
+If a `statusLine` command is already configured, `init` **wraps it rather
+than replacing it**: your existing command's output is printed first, the
+OuterLayer segment appends after. A hang or failure in the wrapped command
+never blanks the line — it times out and OuterLayer's segment prints alone.
+`outerlayer init --remove` restores the original command exactly.
+
+Without `outerlayer watch` running, the line degrades gracefully to the
+session figure alone plus a dim `outerlayer doctor` hint — run `outerlayer
+doctor` to see why (usually: the daemon isn't running, or hasn't refreshed
+recently).
+
+Opt out of the segment with `outerlayer init --no-statusline`.
+
+## Supported agents
+
+| Agent | Source | Status |
+|---|---|---|
+| Claude Code | `~/.claude/projects` (+ raw mirror) | full: turns, tool I/O, thinking, images, subagents, cost |
+| Codex CLI | `~/.codex/sessions` | captured locally only — turns, tool I/O, edits (apply_patch), errors, usage |
+| Cursor | `~/.cursor/chats` | captured locally only — turns, thinking, tool I/O, edits, errors, no cost (Cursor stores no token usage) |
+
+Upload needs a session-start hook to record the launch, and only Claude Code
+has one, so only Claude Code sessions can be launched as work today.
+
+Sessions from every agent land in one canonical schema
+(`@outerlayer/session-schema`), so sync and everything downstream treat them
+identically. Adding an agent is one source adapter.
+
+## How capture works
+
+Your agents already write complete transcripts to disk — OuterLayer treats
+those as the source of truth rather than wrapping or proxying the agent:
+
+- **`init`** adds a <50ms hook that notes each session event and installs
+  the status-line segment.
+- **`outerlayer daemon`** mirrors transcripts before the agent deletes them
+  — so history survives even for agents with retention windows. It's a
+  separate, long-running process you start yourself; `init` doesn't start
+  it for you.
+- **`sync`** parses whatever is on disk and ships the sessions you launched
+  with `OUTERLAYER_WORK`, incrementally, only what's new since the last run.
+
+No API keys, no model calls, no interception. If you uninstall OuterLayer,
+your agents never notice.
+
+## Requirements
+
+Node 22+. macOS and Linux; Windows untested (issues welcome). Capturing
+**Cursor** sessions additionally needs Node 22.5+ (it reads Cursor's SQLite
+chat store via the `node:sqlite` builtin); on older Node, Cursor is not
+captured at all.

package/dist/build-info.json

@@ -0,0 +1 @@
+{"id":"2026-09-23T16:41:05.295Z+7ad24522","root":"/Users/carbonteq/manage-ai/control-plane/cli-release","pkg":"outerlayer"}