loki-mode 8.5.2 → 8.6.0

package/docs/environment-variables.md

@@ -0,0 +1,102 @@
+# Environment variables
+
+The operator-facing knobs, with defaults read from the source rather than from
+memory. Every variable on this page is asserted by a test to still exist, so
+this document cannot quietly rot into fiction.
+
+## What this page is not
+
+The codebase references a few hundred `LOKI_*` tokens. Most are internal
+plumbing between the CLI and the runner (`LOKI_REG_TARGET`,
+`LOKI_CI_JSON_FINDINGS`, and similar), or prefix fragments that are never a
+whole variable. Publishing that number as an "operator surface" would be
+misleading, so this page covers only what an operator would deliberately set.
+
+`loki config schema` lists 64 more keys that map to environment variables and
+can be written to `.loki/config.yaml`. Those are not repeated here. The
+variables below are the ones **not** in that schema -- historically the ones
+with nowhere to look them up.
+
+## Running a build
+
+| Variable | Default | Effect |
+|---|---|---|
+| `LOKI_PRD_FILE` | none | Path to a spec file, as an alternative to the positional argument. |
+| `LOKI_MAX_ITERATIONS` | `1000` | Hard cap on iterations. Reaching it is a deterministic terminal failure, not a success. Also in `config schema`. |
+| `LOKI_BUDGET_LIMIT` | unset (no cap) | Spend cap in USD. On exhaustion the run stops and reports a terminal failure -- see [exit codes](./exit-codes.md). |
+| `LOKI_MAX_DURATION` | unset (no cap) | Wall-clock cap in seconds. Stops cleanly at the next iteration boundary with a `max_duration_reached` terminal status. `loki start --max-duration` also accepts `90m` / `2h`. |
+| `LOKI_AUTO_CONFIRM` | unset | `true`/`false` to control prompts. Takes precedence over `CI`. |
+| `LOKI_CONFIG_DUMP` | `0` | `1` prints the resolved configuration and exits **without starting a run or spending anything**. |
+
+For a cost estimate before committing to a run, `loki plan <spec> --json` is
+the better tool: it reports complexity, iterations, tokens and cost without
+executing. See [cost controls](./cost-controls.md) for how the three caps
+interact and why hitting one is a failure rather than a success.
+
+## Choosing a model and provider
+
+| Variable | Default | Effect |
+|---|---|---|
+| `LOKI_PROVIDER` | `claude` | `claude`, `cline`, `codex`, or `aider`. |
+| `LOKI_MAX_TIER` | unlimited | Caps model tier, so a run cannot escalate past what you are willing to pay for. |
+| `LOKI_TIER` | per-phase default | Forces a specific tier for the run. |
+| `LOKI_SESSION_MODEL` | provider default | Pins the session model explicitly. |
+| `LOKI_MODEL_OVERRIDE` | unset | Overrides the resolved model outright. |
+
+`LOKI_MAX_TIER` is the cost control worth knowing: it bounds escalation, while
+`LOKI_BUDGET_LIMIT` bounds total spend. They answer different questions and are
+usefully set together.
+
+## Output volume
+
+| Variable | Default | Effect |
+|---|---|---|
+| `LOKI_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error`. |
+| `LOKI_QUIET` | `0` | `1` is shorthand for `warn`. |
+
+**Errors are never suppressed.** `error` is the floor, so even the quietest
+setting still prints failures -- a verbosity control that could hide why a
+build failed would be a footgun. An unrecognized value falls back to `info`
+rather than silencing the run, so a typo in a pipeline config cannot blind you.
+
+Available as flags too: `loki start --quiet`, `loki start --log-level LEVEL`.
+
+Decorative output (the HUD, the completion card, the start headline) already
+suppresses itself when stdout is not a TTY, so CI logs were never the wall of
+banners you might expect. These variables control the remaining `[INFO]` and
+`[STEP]` lines.
+
+## Platform integration
+
+| Variable | Default | Effect |
+|---|---|---|
+| `LOKI_DURABLE_STATE` | `0` | `1` enables durable state **and** the richer process-exit contract that lets Kubernetes distinguish a deterministic failure from a crash. See [exit codes](./exit-codes.md). |
+| `LOKI_SDK_LOOP` | unset | Routes the run through the Bun/TypeScript runner instead of bash. Both implement the same exit contract. |
+
+`LOKI_DURABLE_STATE=1` is the one to set in a Job or task definition. Without
+it every failure collapses to exit 1 and the platform cannot tell "re-running
+this is pointless" from "this crashed and should resume".
+
+## Precedence
+
+Command-line flags beat environment variables, which beat `.loki/config.yaml`,
+which beats `~/.config/loki-mode/config.yaml`.
+
+To see what actually resolved, without starting a run:
+
+```sh
+LOKI_CONFIG_DUMP=1 loki start ./prd.md
+```
+
+## Setting these persistently
+
+`loki config set` writes to the config file for the keys it supports:
+
+```sh
+loki config set budget 25
+loki config set provider claude
+loki config set maxTier sonnet
+```
+
+`loki config schema` lists every key the config file understands, and
+`loki config show` prints the current effective values.

package/docs/exit-codes.md

@@ -0,0 +1,130 @@
+# Exit codes
+
+Every code below was read from the source, not from a help text. If a command
+is absent from this page it returns only the shell defaults (0 on success,
+nonzero on failure) and you should not build a gate on anything finer.
+
+## The one rule
+
+**Severity rises with the code.** `[ $rc -ge 2 ]` always means "worse than the
+level-1 outcome" for any command on this page. If you remember nothing else,
+remember that a bigger number is never better news.
+
+## `loki start`
+
+Two contracts, and which one you get depends on an environment variable. This
+is the part most likely to surprise a script author.
+
+### Default (local, CI)
+
+| Code | Meaning |
+|---|---|
+| 0 | The run completed |
+| nonzero | Something went wrong |
+
+There is no finer signal. A gate that needs to tell "failed the quality gate"
+from "crashed" must opt into the durable contract below.
+
+### With `LOKI_DURABLE_STATE=1` (the platform contract)
+
+Written for a Kubernetes Job, an ECS task, or a systemd unit that has to decide
+whether retrying is worth anything. The distinction it draws is **will running
+this again produce a different result**.
+
+| Code | Meaning | Should the platform retry? |
+|---|---|---|
+| 0 | Completed, or a human stopped it (council approved, completion promise, force-stop, paused, interrupted, stopped) | No. It is done, or a person is driving. |
+| 20 | Deterministic terminal failure (failed a gate, max iterations, max retries, **budget exceeded**, **wall-clock cap reached**, policy blocked, contradictory spec) | **No.** The same inputs fail the same way; a retry only spends money to arrive here again. |
+| any other nonzero | Crash (SIGKILL, eviction, node loss) | Yes. The restarted run resumes from the durable volume. |
+
+`budget_exceeded` sits with the failures deliberately. It used to exit 0 on the
+reasoning that a human would raise the cap and resume, which is true at a
+terminal and false inside a Job: there is no human, so a build stopped mid-work
+by the cost breaker was reported as a success. Exit 0 must mean the work is
+finished or a person chose to stop it.
+
+Helm wires this up for you: `worker.exitCodes.terminalFailure` (default 20)
+feeds the Job's `podFailurePolicy`, so a deterministic failure fails the Job
+immediately instead of burning `backoffLimit`. Requires Kubernetes 1.31+.
+
+Both the bash runner and the Bun runner (`LOKI_SDK_LOOP`) implement this
+identically; a parity test asserts they agree status for status.
+
+## `loki verify`
+
+| Code | Verdict |
+|---|---|
+| 0 | VERIFIED |
+| 1 | CONCERNS (findings below the block threshold, or inconclusive evidence) |
+| 2 | BLOCKED (findings at or above the block threshold) |
+| 3 | Verifier error: it could not complete, and never silently passes |
+
+Code 3 matters more than it looks. A verifier that cannot run is not a pass,
+so `[ $rc -eq 0 ]` is the only safe test for "verified" -- `[ $rc -ne 2 ]`
+would treat a broken verifier as acceptable.
+
+An early draft spec listed `1=BLOCKED, 2=CONCERNS`. That ordering was rejected:
+it is not used anywhere, it has no consumers, and it inverts the
+severity-rises-with-the-code rule that every other command follows.
+
+## `loki ci`
+
+| Code | Meaning |
+|---|---|
+| 0 | Passed, or all findings are below `--fail-on` |
+| 1 | Findings exceed the `--fail-on` threshold |
+| 2 | Error: missing tools or invalid arguments |
+
+Machine-readable output is `--format json` here, not `--json`.
+
+## `loki doctor`
+
+| Code | Meaning |
+|---|---|
+| 0 | Every required check passed. Optional warnings do not fail the command. |
+| nonzero | At least one required check failed; the output names which |
+
+Safe as a preflight gate in an init container or pipeline step:
+
+```sh
+loki doctor || { echo "host is not ready"; exit 1; }
+```
+
+An absent optional provider CLI is a warning, not a blocker, so this will not
+refuse to start over a tool you were never going to use.
+
+## Security scan
+
+| Code | Meaning |
+|---|---|
+| 0 | No high or critical findings |
+| 1 | At least one HIGH |
+| 2 | At least one CRITICAL |
+
+## Signals
+
+`loki start` handles the usual terminating signals conventionally: 130 for
+SIGINT (Ctrl-C), 143 for SIGTERM. Under the durable contract these are crashes
+in the retryable sense -- a pod terminated by the scheduler resumes rather than
+being treated as a completed build.
+
+## Writing a gate
+
+```sh
+# Block a merge unless verification is clean. Note -ne 0, not -eq 2:
+# a verifier ERROR (3) must not pass.
+loki verify || { echo "not verified"; exit 1; }
+
+# Kubernetes: let the platform decide whether to retry.
+LOKI_DURABLE_STATE=1 loki start ./prd.md
+rc=$?
+case $rc in
+  0)  echo "complete" ;;
+  20) echo "terminal failure -- fix the spec or raise the budget, then re-submit" ;;
+  *)  echo "crashed (rc=$rc) -- resume is safe" ;;
+esac
+```
+
+Do not read an exit code through a pipe. `$?` after a pipeline reports the last
+stage, so `loki verify | tee log` gives you `tee`'s status and always looks
+successful. Use `${PIPESTATUS[0]}` in bash, or capture first and test after.

package/docs/image-provenance.md

@@ -0,0 +1,124 @@
+# Verifying the container image
+
+Everything on this page is a command you run against the public registry and
+the public sigstore transparency log. None of it requires an account with us,
+and none of it trusts anything we say here: if a command below fails, the
+correct conclusion is that the image is not what we claim, not that the
+instructions are stale.
+
+## What is covered, and from which version
+
+Read this section before the commands. Provenance that claims more than it
+delivers is worse than none, because it is exactly what an auditor will test.
+
+| Artifact | Signature | SBOM |
+|---|---|---|
+| Container image (`asklokesh/loki-mode`) | first release after v8.5.2 | first release after v8.5.2 |
+| npm tarball (`loki-mode`) | v7.4.10 and later | v7.4.10 and later |
+
+**Images published up to and including v8.5.2 are not signed and have no SBOM.** A signing
+workflow existed from v7.4.10 but was triggered on `release: published`, and
+because our releases are created by a workflow using the default
+`GITHUB_TOKEN`, GitHub never emitted that event. The workflow therefore never
+ran on a real release, which the registry confirms: no `sha256-*.sig` tags
+existed for any version through v8.5.2. Signing now runs inside the same job
+that pushes the image, so it cannot be skipped by a trigger that does not fire.
+
+We are not backfilling signatures for older tags. A signature applied today by
+a different pipeline than the one that built the artifact months ago attests
+to far less than it appears to, and the appearance is the dangerous part.
+
+## Verify the signature
+
+Requires [cosign](https://github.com/sigstore/cosign) v2.x. Substitute your
+version for `8.6.0`.
+
+Signatures are bound to the image **digest**, not to a tag. Tags are mutable --
+`latest` moves every release, and even a version tag can be repointed -- so
+resolve the digest first and verify that.
+
+```sh
+VERSION=8.6.0   # or whichever release first carried signing; see the table above
+DIGEST=$(docker buildx imagetools inspect "asklokesh/loki-mode:${VERSION}" \
+  --format '{{json .Manifest.Digest}}' | tr -d '"')
+echo "$DIGEST"
+
+cosign verify \
+  --certificate-identity-regexp 'https://github.com/asklokesh/loki-mode/.github/workflows/release.yml@.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  "asklokesh/loki-mode@${DIGEST}"
+```
+
+The two `--certificate-*` flags are the part that matters, and omitting them
+is the most common way to get a meaningless pass. Keyless signing means anyone
+with a GitHub account can produce a valid sigstore signature over our image;
+what makes the signature *ours* is that it was issued to our workflow identity
+by GitHub's OIDC issuer. Without those flags cosign will happily confirm that
+the image was signed by somebody.
+
+A pass prints a JSON block including the certificate's subject, which should
+name `release.yml` in this repository.
+
+## Verify and read the SBOM
+
+The SBOM is attached to the image as a CycloneDX attestation. Note this is a
+*separate* artifact from the npm SBOM published on the GitHub Release: the
+image carries an OS layer, a Python runtime and system packages that the npm
+tarball's SBOM never described. If you are deploying by Helm, ECS, or any
+other image-based path, the image SBOM is the one that matches what you run.
+
+```sh
+cosign verify-attestation \
+  --type cyclonedx \
+  --certificate-identity-regexp 'https://github.com/asklokesh/loki-mode/.github/workflows/release.yml@.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  "asklokesh/loki-mode@${DIGEST}" \
+  | jq -r '.payload' | base64 -d | jq '.predicate' > image-sbom.cdx.json
+
+jq '.components | length' image-sbom.cdx.json
+```
+
+`verify-attestation` checks the signature over the SBOM before you read it,
+which is the point: an SBOM you downloaded unverified tells you what someone
+wanted you to believe is in the image.
+
+**Scope limit worth knowing.** We publish a multi-arch image (linux/amd64 and
+linux/arm64). The signature covers the manifest list, so it covers both
+architectures. The SBOM does not: it is generated from a single resolved
+platform, so package versions specific to the other architecture may differ
+from what it lists. If you deploy on arm64 and need an exact bill of materials
+for that architecture, generate it against the arch-specific digest yourself:
+
+```sh
+syft "asklokesh/loki-mode:${VERSION}" --platform linux/arm64 -o cyclonedx-json
+```
+
+Feed `image-sbom.cdx.json` to Grype, Trivy, Dependency-Track or any other
+CycloneDX consumer for CVE scanning.
+
+## Air-gapped environments
+
+Both commands above reach the public sigstore infrastructure (Rekor and
+Fulcio) to check the transparency log. To verify inside an air-gapped network,
+mirror the trust root and the artifacts on a connected host first:
+
+```sh
+cosign save "asklokesh/loki-mode@${DIGEST}" --dir ./loki-image-bundle
+cosign initialize --mirror <your-tuf-mirror> --root <your-root.json>
+```
+
+Then transfer `loki-image-bundle/` and verify with `cosign verify --local-image
+./loki-image-bundle`. See `loki doctor --airgap` for the full host inventory
+the engine itself needs at runtime.
+
+## If verification fails
+
+Do not deploy the image. In order of likelihood:
+
+1. **You verified a tag instead of a digest.** Re-resolve the digest.
+2. **You omitted the `--certificate-*` flags**, verified a digest that was
+   never ours, and got a pass or a confusing mismatch. Both flags are required.
+3. **The version is v8.5.2 or earlier.** See the coverage table above; those images
+   are genuinely unsigned and no command will make them verify.
+4. **The image is not what we published.** Report it at
+   https://github.com/asklokesh/loki-mode/issues and do not run it.