Troubleshooting
Start with /footer status (what is active, in detail), /profile status (the profile and what
it loaded), /update status (versions and channel) and pi list (what is registered).
Install and update
pi reports "No models available". Luna does not choose a model. Run /login, or add an
API key or models.json as pi describes.
node packages/core/install.ts --channel latest says there are no release tags. latest
resolves to the newest vX.Y.Z tag on the public repository and none has been created yet. Use
--channel next (it follows main), or a branch or tag with --git-ref.
"could not list release tags" or "Check network access to the repository". The lookup did not
happen; nothing was changed. Check git ls-remote https://github.com/SATUNIX/luna.git works
from the same shell, then retry. Behind a proxy, configure git's proxy settings: pi and /update
use your git configuration.
Every extension seems to load twice. Two copies of Luna are registered (for example a
checkout and a release). pi list shows them. Run the installer once
(node packages/core/install.ts --profile <name> --yes); it keeps one registration and removes
the other.
/update says a step failed. /update checks the installed state after each step. The message
says what it expected and what it found (for example, Luna is still at the old commit), the run
stopped there, and pi was not reloaded. Fix the cause it names and run /update again. If Luna
was already replaced and only re-applying the profile failed, a second /update has nothing left
to do: the message says so and gives the version to go back to and the installer command that
re-applies the profile instead (tests/kit-update-smoke.ts). Without a terminal UI the same text
goes to standard error, prefixed [update].
Luna is "registered from a retired private source". See Migration.
Node or pi is too old. Luna needs Node 22.19 or newer and pi 0.85.1 or newer. node
--version and pi --version show what you have.
Profiles
/profile <name> was rolled back. A switch snapshots the settings files, runs the installer,
then judges the result by what is on disk (marker, profile, extension list, firewall settings),
not by the installer's exit code. On any mismatch it restores the snapshot and reloads the old
configuration. The message names the failing check. If restoring itself failed, the message names
the backup directory that holds the originals.
A profile switch refuses to start. The firewall settings are validated first: an unknown
mode or policy, an unparseable firewall.json, or an override that removes tool-firewall,
secret-guard or protected-paths stops the switch before anything is written. Fix the file the
message names.
Context and compaction
/compaction status says compaction is off. pi's automatic compaction is a setting
(compaction.enabled in settings.json), and turning it off also turns off recovery from a full
context window. A run that fills the window then ends with a message that says so and how to
recover (/compaction on, or /compress). Sub-agents read the same settings.
A run ended right after a compaction message. Use a recent kit: trigger-compact no longer
compacts in the middle of a run, and it stands down when pi's own trigger is earlier.
Approvals and the firewall
Every refusal carries exactly one label:
| Label | Meaning | What to do |
|---|---|---|
[HARD DENY] |
Policy forbids it. No approval or judge can override it. | Choose another way, or change the policy deliberately. |
[UNCERTAIN ...] |
The judge was unsure, the card timed out, or the console was unusable. Nothing ran. | Ask again and answer the card. |
[OPERATOR DECISION: denied] |
You (or a remembered decision) said no. | Nothing to fix. |
[AUTO-MODE BLOCK] |
Auto mode's judge blocked it with high confidence. | Review the reason; switch mode only if you disagree. |
/firewall list shows remembered approvals with their scope (action, workspace, directory,
session) and expiry, and /firewall revoke <id> removes one. A malformed approvals file is
ignored (never treated as an allow) and reported by /firewall list and on standard error; the
rejected file is kept next to it as .rejected-<hash>.
Delegation
"delegation refused". The message names the reason. The common ones: the tier allows no
children (/effort to raise it), the request's budget is used up (children that failed or were
retried still count), or a required protection could not be located next to Luna. A child is
never started with weaker protection than its parent.
A child exited with code 78 (EX_CONFIG). Inside the child, delegation-guard found that a
required protection did not load, so it blocked every tool and exited. Reinstall Luna; this is
a broken installation, not a task failure.
Status bar
The bar is garbled or has odd symbols. /footer ascii on uses plain characters;
/footer light shows less. The bar is fitted to the terminal width and drops lower-priority
segments as it narrows; /footer status prints everything it dropped.
Web console
401 or 403. The console needs its token and a matching Host. Open the URL /console prints
(it has #token=... at the end); do not paste the token in a query string. See
Web console.
Unattended runs
Unattended mode is not active. Every condition has to hold at load time, and any failure
means the normal rules apply, with a warning on standard error and in /firewall status. See
Autonomous runs.