Configuration

Last Light layers configuration at startup: the packaged config/default.yaml (non-secret defaults), then an optional $LASTLIGHT_OVERLAY_DIR/config.yaml overlay, then environment variables (via .env in local dev, or instance/secrets/.env in production). A fourth layer — a managed repo's own .lastlight/ — is applied per run, on top of all three; see Per-repo config. The authoritative source is apps/server/src/config/config.ts in the repo; this page mirrors it.

config/default.yaml  →  instance/config.yaml  →  env  →  <repo>/.lastlight/lastlight.yml
     (packaged)            (your overlay)        (env)          (per-repo, bounded)

Config files & overlay

Non-secret config — managed repos, routes, models, variants, approvals, and disabled.* — lives in YAML. The public config/default.yaml ships safe defaults (and an empty managedRepos list). Your deployment overrides go in an overlay selected by LASTLIGHT_OVERLAY_DIR — the docker-compose stack mounts an instance/ folder there as /app/instance.

Merge rules: maps (models, variants, routes, approval) deep-merge over the defaults; arrays (managedRepos, disabled.*) replace; environment variables override both. Secrets (GitHub App key, provider API keys, Slack tokens, admin secret) stay env-only and never appear in the dashboard Config tab, which shows the Default / Overlay / Merged non-secret config.

Per-repo config

A managed repo can commit a .lastlight/ directory that overrides a bounded subset of the above — models, reasoning effort, approval gates, cron participation, prompts, skills, agent context — for runs against that repo only. It's always read from the repo's default branch, so a pull request can never reconfigure the agent reviewing it, and it's bounded by a repoConfig: block you control (ship it disabled with repoConfig.enabled: false if you'd rather keep every knob central). Out of the box it's inert: nothing changes until a repo actually commits one.

Full contract, worked example and the lastlight repo commands: Per-repo config.

GitHub App

Required if you want to manage repos (not required for messaging-only mode).

Models (agentic-pi)

The agent runtime is agentic-pi (workflow phases) plus @earendil-works/pi-ai (in-process chat). It runs on any model the pi coding agent supports — Claude, GPT, Gemini, Llama, and more, as openai/…, anthropic/… or openrouter/<vendor>/<model> strings. Set whichever provider API keys match your selected models — one OpenRouter key covers most of them if you'd rather have a single billing surface.

Provider endpoints — your own gateway

Every provider ships with the vendor's endpoint baked in. Point one somewhere else — a self-hosted gateway, a corporate proxy, an Azure/Bedrock-fronted endpoint — with a providers: block in your overlay config.yaml. That is how a deployment gets central spend accounting, key custody, rate limiting and audit, and it is the only way to reach a model that isn't one of the ~18 registry entries.

providers:
  # A gateway that speaks Anthropic's dialect: only the URL moves. The models,
  # the request shape and ANTHROPIC_API_KEY are all inherited.
  anthropic:
    baseUrl: https://gateway.internal/anthropic

  # A provider Last Light has never heard of. baseUrl is required; api defaults
  # to openai-completions and envKey to ACME_API_KEY, derived from the prefix.
  acme:
    baseUrl: https://llm.corp.example/v1
    api: openai-completions        # or anthropic-messages
    envKey: ACME_API_KEY

On a provider Last Light already knows you may also re-point envKey — that is how a gateway keeps custody of its own credential (GATEWAY_API_KEY rather than the vendor's key). Leave it alone and pi keeps resolving the credential itself, which is what lets an OAuth subscription login keep working behind a moved endpoint. You may not change a known provider's api: its dialect is fixed, and a gateway that speaks a different one is a provider of your own — give it its own prefix, as acme above.

The endpoint reaches every model call — the cheap screener/classifier helpers, the sandboxed workflow phases, and in-process chat — and the sandbox egress firewall follows it automatically, so no separate allowlist edit is needed. lastlight server setup offers this as a provider choice ("Self-hosted / gateway endpoint") and writes the block for you.

Runtime

Approval gates

Autonomous mode — autonomy

The autonomy block drives the label-driven pipeline: an issue labelled ready-for-agent on a repo listed in autonomy.repos dispatches a gated build with no command typed. It ships inert (repos: []) and is operator-only — there is no per-repo key. The stages, their approval gates, on_merge and the budget ceilings are all documented on Autonomous mode.

Workflow policy — fix, gate, dependencies, review

These blocks have no environment variable at all: they're budgets and blast-radius dials, and those belong in a file you can review and diff rather than in a shell. They live in config/default.yaml with the values below, and you override them in your instance/config.yaml.

# instance/config.yaml

review:
  postsCheck: false            # post the `last-light/review` Check Run
  placeholderCheck: true       # also post the queued/neutral placeholder while a review waits
  sweepPendingGraceMinutes: 60 # the sweep reviews pending CI only after this long
  trigger: after-checks        # eager | after-checks | on-request
  requestLabel: null           # the label that asks for a review in `on-request`
  skipDraft: true              # skip draft PRs
  generatedPaths:              # a push touching only these earns no re-review
    - "*.lock"
    - package-lock.json
    - pnpm-lock.yaml
    - go.sum
    - "*.min.js"
    - "*.generated.*"
    - "**/__generated__/**"
  skipUnchangedDiff: true      # skip a re-review whose own diff did not move
  triage:                      # how much review a RE-review is owed
    enabled: true
    timeoutSeconds: 300
  analysis:
    enabled: false             # the review evidence pipeline — off, and inert
    maxSpecObligations: 40     # SAFETY BOUND for the `spec` family — should never bind
    maxObligations: 48         # TOTAL backstop over the five facts-derived
                               # families, which are capped PER FAMILY (contract
                               # 12, enforcement 12, state 8, security 8, tests
                               # 8). 48 is their sum, so it cannot bind unless
                               # you raise one of those ceilings
    obligationContract: minimal  # minimal | full — how strictly the seeded
                               # obligations' discharge is checked. minimal is
                               # the measured default
    mint: all-in-diff,registrations  # extra seeding rules beyond the original
                               # four; "" = the pre-D2 baseline set
    siteConcurrency: 6         # site investigators running at once (a ceiling,
                               # clamped per sandbox backend). Old name:
                               # surveyConcurrency, still read
    siteTop: 5                 # how many ranked sites get an investigator (1–8)
    surveyUnitConcurrency: 16  # unit survey calls in flight (no backend clamp
                               # — lower it only for provider rate limits)
    surveyUnitsTimeoutSeconds: 600  # whole-phase deadline on the unit calls
    probes: "off"              # off | static | full. NOT ATTACHED yet — the
                               # probe phases skip whatever this says. static
                               # runs them WITHOUT installing anything; full
                               # also installs the PR's dependencies
    probeLifecycleScripts: false  # full only: let the PR's own postinstall run.
                               # Off: it is the author's code, on your machine
    probeTypecheck: false      # the repo's own tsc --noEmit, for per-line diagnostics
    probeCoverage: false       # the one step that runs a test suite
    prepareTimeoutSeconds: 300
    coverageTimeoutSeconds: 900
    probeRounds: 2
    maxProbes: 8               # at most this many hypotheses go in front of
                               # falsify (probe-plan ranks the owed set and cuts
                               # it here); null = no cap
    falsifyTimeoutSeconds: 600 # the oracle's whole-phase ceiling, all rounds
    maxInlineComments: 5       # the attention boundary — findings past this go
                               # to the review body, never dropped. Ranked by a
                               # severity DERIVED from the evidence, not written
                               # by the model
    maxBodyComments: 5         # body-tier budget. N = top N by severity
                               # (default 5); 0 = no overflow at all;
                               # null = unlimited
                               # (`thresholds` and `internalFloor` were removed
                               #  in 2026-09 — the boundary no longer gates on a
                               #  finding's confidence; both keys are ignored.
                               #  So are surveyEngine, reviewEngine,
                               #  independentReview, adjudicate, admit, jevModel,
                               #  jevTimeoutSeconds and surveyPasses, removed
                               #  with the agent survey and the adjudicator)
  risk:                        # risk tiers for the pipeline — a repo may set
    rules: []                  # its own in .lastlight/, matched FIRST. e.g.
                               #   - { glob: "src/billing/**", tier: critical }
                               #   - { glob: "*.stories.tsx", tier: low }
                               # built-ins apply after: docs/tests/generated low,
                               # migrations/schema/auth/CI high, else medium

fix:                           # every PR-fixing workflow: pr-fix, dependabot-ci-fix
  maxAttempts: 3               # attempts ACROSS runs for one PR, then a human is asked
  localIterations: 2           # gate-loop iterations WITHIN one attempt
  escalateModelAfterAttempt: 1 # attempts above this use models["pr-fix-retry"]
  maxCostUsd: 5.0              # cumulative ceiling for ONE PR; null = no ceiling
  maxFlakyDeferrals: 2         # "flaky" verdicts before one is taken at face value
  retryableClasses: [reproducible, env-mismatch]

gate:                          # ONE full build/test gate command (install excluded)
  timeoutSeconds: 900          # a repo may set this in .lastlight/lastlight.yml…
  maxTimeoutSeconds: 1500      # …clamped to this operator-only ceiling
  phaseTimeoutSeconds: 2400    # operator-only budget for a phase that RUNS a gate
                               # (build guardrails_gate, executor)

sandbox:
  agentTimeoutSeconds: 1800    # one agent phase run with no timeout_seconds
  commandTimeoutSeconds: 300   # type: bash / type: script phases
  untilBashTimeoutSeconds: 30  # a generic_loop.until_bash check

dependencies:
  autoMergeMaxImpact: medium   # none | low | medium | high — ceiling for a MAJOR bump
  requireSettledChecks: true   # no merge decision until the head SHA's checks settle
  minSettledChecks: 1          # …and there must be at least this many
  auditComment: true           # post the evidence comment when auto-merging a major

trigger: after-checks means "once the head SHA's checks settle — either colour". The review can then read and cite the CI result instead of guessing at it, and a push storm collapses to one review per settled SHA. There is deliberately no settled-and-passing mode: a PR whose CI never goes green would then never be reviewed, which is exactly the PR most worth a look.

on-request means the review runs only when somebody asks. Three ways to ask: apply the requestLabel — yours, or one the target repo named in its own .lastlight/, both of which are honoured on the pull_request.labeled webhook — comment @last-light review, or — with postsCheck on — press Re-run on the last-light/review check, which is posted as a neutral conclusion so it never blocks a merge. (GitHub's reviewer picker doesn't offer App bot users, so "request a review from the bot" is handled opportunistically but is not the mechanism to rely on.) Under after-checks with postsCheck on, the check is posted queued while CI runs, so branch protection can require it without racing. If you would rather nothing of Last Light's appear on a PR until its CI has settled, set placeholderCheck: false: the check is then created only when a review actually starts, shows it in progress, and concludes with the verdict (or "didn't complete" if the run fails). The trade-off is that a required last-light/review has nothing to wait on until the review starts.

The 30-minute review sweep is the safety net for CI that never finishes (a dead runner, a fork workflow awaiting approval), so it will review a PR whose checks are still pending — but only once they have been pending for sweepPendingGraceMinutes (default 60), measured from the oldest pending check. A fresh push is left alone until its CI settles. If a push lands while a review of the previous commit is still running, the settled review of the new commit replaces it — the stale run is cancelled rather than left to post a review of code that no longer exists.

generatedPaths is the answer to a re-review with nothing new to say. Before it, the only thing suppressing a second review was "we already reviewed this exact head SHA" — and a lock file re-derivation is a new head SHA, so a dependency bump could earn two formal reviews minutes apart. When every path changed since the review we posted matches one of these patterns, the re-review is skipped.

It is deliberately hard to trip. It never suppresses a first review, never suppresses an explicit @last-light review or the request label, and never fires when the push also touched a hand-written file — one non-generated path and the review runs. Any read it can't trust (a compare that failed, a diff GitHub truncated) dispatches. Set it to [] to turn it off. Patterns: * stops at a /, ** crosses one, and a pattern with no / matches a basename anywhere in the tree — so pnpm-lock.yaml means the lock file in every package of a workspace.

With postsCheck on, this skip is the one that still leaves a check: the new head SHA gets a completed last-light/review repeating the verdict of the review that still stands. Every other skip leaves the PR alone, but this one would otherwise strand a required check on a head nobody reviewed. Its conclusion mirrors that earlier review, so a CHANGES_REQUESTED carried forward still blocks the merge.

skipUnchangedDiff answers the case no list of paths can. Merging main into your branch changes no line you wrote, but it is a new head SHA — and the delta since the last review is then every file main brought in, which is exactly what generatedPaths must refuse to suppress. One 73-file pull request was reviewed, had a merge commit land eleven minutes later, and paid for the whole review again. So this gate asks the question directly: is the diff of your branch against its base byte-identical to the one we already reviewed? It covers a merge from the base, a rebase that preserves the tree, and an empty force-push — and it does not fire when the base touched a file you also touched, because the merged patch then really is different.

It is as hard to trip as the gate above, and fails the same way. A first review, an explicit request and the check's Re-run button all override it, and any read it cannot trust — a compare GitHub truncated, a binary file it gave no patch for — dispatches a full review. Set it to false to turn it off. It leaves the same carried-over check.

triage is the middle tier, and it ships on. Between "nothing moved at all" and "this is a substantial new push" sits a real but small delta, and re-running the full review over it costs about what the first one cost. So a re-review starts with one cheap pass that reads only what changed since the last review and decides whether the rest is worth running. On light the analysis phases skip and the reviewer makes a single focused pass over the delta; on full, on a first review, or with this off, you get exactly the review you get today. It errs hard toward full: an unclear answer, an unrecognised one and no answer at all are all read as "review everything".

analysis is the review evidence pipeline, and it ships off. enabled: false reproduces the review you get today byte for byte — not "the feature is on but finds nothing": the variables it governs are absent from the agent's context entirely, and the extra GitHub reads it needs are never issued. Switch it on per deployment, once you want it.

With the pipeline on, a review runs one path. First the pull request is cut into small deterministic units — a changed function or method, a file's module-level code, the pull request as a whole — and Last Light makes one bounded model call per unit on models.review-survey, with no tools and no sandbox, recording every defect each unit might hold. Replies are cached on disk, so a re-review only re-asks the units whose code or context changed, and a unit that does not answer in time is recorded as unanswered rather than dropped. Those records are only a signal of where to look: the stretches of code that many independent units pointed at are ranked, one investigator goes to each of the top five (analysis.siteTop, up to eight; models.review-site, falling back to models.review-survey), and each must ground one to three findings in the code or back a "nothing here" with a probe it actually ran. Each investigator also reads the PR's title, description and closed issues, as a claim to check rather than a reason to stop looking. Set models.review-site-pair to a second, different model and every site gets a second investigator on it: two models miss different things, so the pair finds more than either alone. One selection pass (models.review-select, falling back to models.review) then merges duplicates, decides how important each one is, and writes the comments. It reads the PR's earlier reviews, threads and comments first, so a point someone already raised is recorded rather than posted again. A nit is recorded, never posted. Cheap investigator models measured better than Haiku here, on both recall and precision, at a quarter to a half of the cost — pin models.review-site in your overlay. Because the unit calls read the review workspace directly, analysis.enabled is refused at startup on the kubernetes sandbox backend.

The separate review pass does not run while the pipeline is on; a re-review that triage marks light skips the pipeline and runs it instead. If the pipeline fails and leaves no findings behind, a deterministic floor writes them, unposted, and the review says plainly that the change was not assessed — it is never posted as a clean review.

What it adds today is a spec axis. Every item in the reviewer's rubric — correctness, contracts, edge cases, security, test coverage — is a standards check, and none of them asks whether the change does what was asked. Turning analysis on reads the issues the PR closes and its body, extracts the acceptance criteria out of them, and pairs each one with the files the PR actually changed; each criterion then becomes a question the unit survey has to answer — quote the line that implements it, or say that no changed file does.

A posted finding's severity, which is what the two posting budgets rank on, comes from the importance the selection pass gave it — a must-fix outranks a worth-mentioning for the inline slots — so the budgets keep the strongest claims instead of cutting in document order. The review's opening summary is written only after those budgets have cut, from the findings that actually post, so it never mentions one that was held back (pin models.review-summary to choose the model; unset, it uses models.default).

probes is kept but not attached yet: the probe phases skip whatever it says, because nothing in the review reads their output until they are wired back in. As designed, it is a second switch under the same block, and it has three values because it used to conflate two decisions. It turns on the oracle — a pass that settles a claim by running something instead of reasoning about it — and, separately, it can install the pull request's dependencies. One boolean bought both, so the only way to get the oracle was to pay for an install.

static runs both probe phases and never installs anything: no package manager, no test suite, no postinstall from a pull request head. The oracle works down a cost-ordered ladder that needs none of it — the same input run against the base branch and the head, a changed pure function copied out and run under plain node, a tool that is already on disk, and a re-query of Last Light's own deterministic analysis scoped to the claim. Anything it genuinely cannot run is recorded as unprobed with the reason and still reaches the review. A search or a file read that merely agrees with a claim about what the code does is recorded as corroborated — weaker evidence than a reproduction, and checked mechanically so a grep cannot pass for one. That is not a degraded mode: the best published false-positive-elimination results come from pipelines that never compile the project at all.

full adds the install, and what that buys is the analysis rather than the probes: a review workspace with a node_modules in it is what lets a tsconfig that extends a package resolve — without it the analysis quietly drops a tier and the contract checks find nothing — and it is the only route to a coverage report, without which "no untested changed lines" means nobody measured rather than well tested. It also has a cost nothing meters: warm review workspaces deliberately keep their node_modules between runs, so this is a standing per-repo disk cost on your host. A bare true reads as static, so upgrading never buys you an install you did not ask for.

The sub-switches under it are priced separately on purpose: probeTypecheck is seconds and gives per-line diagnostics (it is not a CI re-run — Last Light already reads your CI result); probeCoverage is the one step that runs your test suite, and it never guesses a command, only one your package.json already names.

probeLifecycleScripts applies to full alone, and is off as a security default rather than a performance one. The install happens at a pull request head, so a postinstall there is code the PR author wrote, running on your infrastructure — and nothing probes exists for needs it.

This one is operator-only — a repo's own .lastlight/ can't turn it on or off. It buys analysis on your budget, and there is no "more conservative" direction for a repo to move it in.

skipDraft matches what the review sweep has always done. A draft PR is skipped on the webhook path too. Marking it Ready for review lifts that skip, but under the packaged after-checks it does not produce a review on its own: it is a PR-attention event, and attention events are deferred in that mode. What actually runs the review is the head SHA's checks settling — or, if no settle event arrives, the 30-minute review sweep. Under trigger: eager, Ready for review is the event that un-defers it.

The fix budgets bound a loop that diagnoses a CI failure before it retries it. maxAttempts and maxCostUsd both bound the current problem, not the PR's lifetime: a push from anyone but the bot is a fresh problem, so it re-arms the attempt counter and the cost window together and clears the escalation with no label to remove by hand. A diagnosis class outside retryableClasses escalates straight away rather than spending budget on a retry that can't help — its members are checked against the five diagnosis classes, so a typo narrows the set with a warning instead of silently making everything terminal. And maxCostUsd ships on: an unbounded agent loop against a genuinely broken PR is the one failure mode that costs real money.

For dependencies, impact rather than semver magnitude is what gates a major bump — a @types/* major is not a framework rewrite. Set autoMergeMaxImpact: none to keep every major in front of a human.

Know which half of that block is enforced where. requireSettledChecks and minSettledChecks are enforced in code: the merge verdict is computed from the head SHA's resolved check state before the run starts and handed to the agent as a decided answer it is told not to re-derive, and requireSettledChecks additionally makes the dispatch gate refuse a PR whose checks are still running. autoMergeMaxImpact is an instruction to the agent: the impact tier is the model's own judgement, reported in the run's completion marker, and the ceiling reaches the run as prompt text — nothing parses the tier or withholds the merge tools from a run that reported one above the ceiling. Lowering the ceiling narrows what the agent is told it may land; it is not a hard stop.

All three are repo-settable, one-way: a repo's .lastlight/ can only ever make itself more conservative than you are. See Per-repo config for the per-key clamps and the three keys a repo can't touch at all.

Build assets

The per-phase build handoff docs — architect-plan.md, status.md, executor-summary.md, reviewer-verdict.md, guardrails-report.md, and the explore-* docs — can live in one of two places, selected by buildAssets.location in YAML (or the LASTLIGHT_BUILD_ASSETS env var). With repo (the default) they're committed into the target repo under .lastlight/<issueKey>/ and ride the working branch — the historical behaviour. With server they're externalized to the Last Light host instead, never committed into the target repo: injected into each phase from outside the repo and harvested back after, PR-body links point at the dashboard's Artifacts view rather than GitHub blob URLs, and the admin API serves them read-only at /admin/api/artifacts.

Admin dashboard

Slack (optional)

Two independent feature groups — see Slack integration for setup.

OpenTelemetry (optional)

Telemetry is disabled by default. Set LASTLIGHT_OTEL_ENABLED=true and point the standard OTEL_* exporter vars at your collector. See Observability for what's exported, content redaction, and how sandbox telemetry is routed per backend.

Feedback signals (optional)

A 👍 or 👎 on something Last Light wrote becomes an eval signal against the workflow run that produced it. Slack works out of the box (it sends a real reaction_added event); the GitHub half has to be polled — GitHub delivers no webhook for reactions at all — so it ships off:

feedback:
  enabled: true              # Slack signals, live
  github: false              # opt into the GitHub reaction poller
  pollSchedule: "*/30 * * * *"
  windowDays: 14             # how long a bot comment stays pollable
  maxAnchorsPerTick: 500     # = 5 GraphQL requests per tick
  retentionDays: 90
  otel: true                 # export each signal onto the run's trace

Env overrides: LASTLIGHT_FEEDBACK_ENABLED, LASTLIGHT_FEEDBACK_GITHUB, LASTLIGHT_FEEDBACK_OTEL, LASTLIGHT_FEEDBACK_WINDOW_DAYS. Operator-only — a target repo cannot set these. See Feedback signals for the emoji vocabulary, the Slack scope you need to add, and how the polling budget stays bounded.

The "my repos" filter (optional)

By default every admin who logs into the dashboard sees every managed repo's runs and sessions. In an org with a lot of repos that is mostly noise. Turn this on and each GitHub-authenticated admin gets a header toggle that filters every list down to the repos their GitHub org teams own, plus the ones their own account owns:

teamVisibility:
  enabled: false             # operator switch — needs the App's `Members: read`
  ttlMinutes: 60             # how long a resolved answer is reused
  maxTeamsPerUser: 50        # more teams than this ⇒ show everything
  maxPagesPerTeam: 20        # 100 repos/page; a bigger grant ⇒ show everything
  maxRequestsPerResolve: 60  # ceiling for one cache miss

This is a view preference, not access control. The filter travels as an ordinary ?repos= query parameter the dashboard asks for; omit it and the server returns global data exactly as before, and a hand-crafted API call still sees everything. That is what lets every budget above fail open: when a team is too big to enumerate, or someone is in too many teams, or GitHub refuses the query, you see more than strictly necessary rather than a partial list that quietly hides work you own.

Setup. Grant the GitHub App the organization Members: read permission, subscribe it to the team, membership and organization webhook events, and re-consent the App on each installation. Until then the resolver fails open and nothing is filtered for anyone — the toggle still appears once enabled is on, and says why it has nothing to offer, so an outstanding setup step reads as an outstanding setup step rather than as a feature that silently did nothing.

Just created a team? A resolved answer is cached for ttlMinutes (60 by default) and served stale-while-revalidate, so the first load after it expires still returns the old answer and refreshes behind you — it takes a second load to see a change. The webhooks above make that instant by invalidating the cache the moment a membership or a team's repo grant changes. Without them, click the toggle while it reads my repos (none) to re-check immediately.

Nothing is crawled up front. A person's teams are resolved the first time they load the dashboard — one GraphQL query per org plus a page or two per team — and cached in the state database, so the cost tracks their team count, not the org's repo count. The webhooks above invalidate the cache when membership or a team's repo grant changes; POST /admin/api/me/repos/resync is the manual fallback. Operator-only — a target repo cannot set these.