Updates
A pi setup has three parts that update separately:
| Part | What it is | Where it comes from |
|---|---|---|
| pi | The agent binary, TUI and session model | @earendil-works/pi-coding-agent on npm |
| Luna | The package: extensions, skills, prompts, profiles, themes | Its public git repository, github.com/SATUNIX/luna, on a channel |
| Linked packages | Other pi packages in your settings, including Luna's companions (pi-lens, pi-readseek, ...) |
npm |
A profile is not a part: it is a setting that chooses what loads from Luna (see Profiles). Updates keep your profile and your hand edits.
/update
The kit-update extension, loaded in every profile, checks all three parts.
- In the background: at most once a day at session start. It never delays startup and never
prompts for git credentials. When something can be updated you get one notice, and the status
bar shows
updates: /update. - On demand:
/updatechecks now and lists what can be updated.
When the kit is installed from git and its main branch has moved ahead of your checked-out
commit, the check adds one line: main is N commits ahead — /update channel next. It appears at
start-up (subject to the once-a-day background throttle), on /update, and under /update status.
next is the channel that follows main, so the suggested command actually moves your copy to
the newer commits; naming the installed release channel (latest, or an exact version) would not.
The line shows even when the release channel you follow is otherwise current, and it is silent
when your copy is in sync or ahead and when the remote could not be reached (offline, or no git
credentials). When this gap exists, this line is the whole start-up kit notice: the
generic Updates available: ... summary is not stacked on it. pi's own built-in update notice is
separate and may still appear.
| Command | What it does |
|---|---|
/update |
Check now, then pick: everything, Luna, pi, linked packages, or a channel switch |
/update status |
Installed and available versions for every part |
/update all |
Update Luna and linked packages, re-apply your profile, reload; then update pi, up to the tested version (below) |
/update kit, /update pi, /update packages |
Update one part |
/update undo |
Return Luna and its configuration files to how they were before the last update |
/update channel latest / next / trunk / X.Y.Z |
Follow the other channel, or pin a release |
Every update asks for confirmation first. A new pi version needs a restart of pi; everything else reloads in place.
pi stays within the tested version
/update moves pi only up to the version the installed Luna release is tested with. That is
the pi version its package.json pins for the test suite (Support lists the tested
and supported versions).
- A newer pi still shows in
/update status, together with the tested version. /update piand/update allleave pi where it is and say why. They cannot stop part-way, becausepi update --selfalways installs the newest pi.- To go past the tested version, update Luna first (a newer release may be tested with the
newer pi), or run
pi update --selfyourself. - If pi is already newer than the tested version,
/update statussays so. - A Luna release whose
package.jsonhas no exact pin keeps offering the newest pi.
tests/kit-update-smoke.ts pins each of these cases.
Updates are verified
An update is only reported as done when the result is what was asked for. After each step
/update re-reads the installed state and checks it: Luna is registered at the expected
release or commit, a linked package is at the version it was moved to, pi reports the new version,
and the profile has been re-applied. A step that ran but left the old state behind is reported as
failed, with what it found, and the run stops there: nothing later runs and pi is not
reloaded. Without a terminal UI (for example under pi -p) the progress and the failure go to
standard error, prefixed [update], so a script sees them.
flowchart TD
go[You confirm the update] --> step[Run one step]
step --> read[Re-read the installed state]
read --> ok{Is it what was asked for?}
ok -->|yes| more{More steps?}
more -->|yes| step
more -->|no| reload[Reload pi]
ok -->|no| failed[Report the step as failed with what was found:<br/>stop, run nothing later, do not reload]
If the repository cannot be reached, the message says so and names the checks to make; it never reports "up to date" for a lookup that did not happen.
After Luna updates, your recorded profile is re-applied, so extensions a new release adds to your profile load, and companions move to Luna's newly reviewed pins.
Verification stops a failed update; it does not by itself undo steps that already succeeded. Before the
first step runs, /update writes <agent dir>/pi-kit/update-journal.json (mode 0600): how Luna was
delivered, its source, version, commit and channel, the pi version, the recorded profile, and a copy of
the configuration files an update can change (settings.json, the install markers, firewall.json,
security.json, overrides.json, profile-settings.json; never .env). If the journal cannot be
written, the update does not start. /update undo reinstalls the recorded Luna version (or commit, or
resets a local checkout with git reset --keep) and then puts those files back byte for byte, removing
one the update created. It offers itself when a step fails, and after a successful update. When the run
stops after Luna was replaced and before the profile was re-applied, the message also names the exact
installer command that finishes the job instead. Pinned by tests/kit-update-smoke.ts (the journal
exists before the first step, the files and version come back, an unwritable journal stops the update).
What /update undo does not undo: pi itself (pi update --self only moves forward; the journal records
the version so you can see what it was) and linked packages a step updated. Changes made to those
files after the update (a /profile switch, a new package, your default model or theme) are lost when they are
restored; the confirm card says so. One journal is kept, for the last update: each update that finishes is replaced by the next one's journal, so
/update undo returns to the version just before the latest update. An update that did not finish keeps its
journal across a retry, so a retry after a partial failure still undoes to the original (pinned by
tests/kit-update-smoke.ts, which updates twice and undoes once). A crash in the middle of an update that left no journal is not covered. Avoid simultaneous
updates or profile switches from multiple sessions.
After an update, one line names any stored setting that was read under an old name and rewritten under
its new one (a renamed profile, firewall policy or extension, security level relaxed). That notice is
temporary: it exists only while those migrations do.
Uninstall uses the installation marker to identify managed companion packages. If any removal
fails, it returns a nonzero exit status and keeps the marker so the same command can be retried
after fixing the error. The marker is removed only after all removals succeed; --dry-run
changes nothing. smoke:install-marker checks partial failure, marker preservation and retry.
Channels
| Channel | Registered in pi as | Gets |
|---|---|---|
latest |
git:github.com/SATUNIX/luna@v<newest release> |
The newest release tag. Betas count until the first stable release; after that, only stable releases |
next |
git:github.com/SATUNIX/luna (no tag) |
Every commit on main |
trunk |
git:github.com/SATUNIX/luna@integration/luna |
The head of the kit's integration branch (git.trunkBranch in packages/core/distribution.json). A canary, opt-in: use it to dogfood a merged cycle before it reaches main. Never selected by default |
| pinned | git:github.com/SATUNIX/luna@v<version> |
Exactly that release, never moved automatically |
latest and a pin look the same in pi's settings (a tag). The installer records which one you
chose in ~/.pi/agent/.pi-kit.json, and /update follows that record.
Switch with /update channel <name>. The switch keeps your profile and is verified like any
other step. Moving from next back to latest can install an older commit than you have now;
that is expected. latest needs at least one release tag on the repository: before the first
release is tagged, /update channel latest fails with a message saying so.
Settings
| Variable | Effect |
|---|---|
PI_KIT_UPDATE_CHECK=0 |
No background check (/update still works) |
PI_KIT_UPDATE_CHECK_HOURS |
Hours between background checks (default 24) |
PI_SYSTEM_GIT_SOURCE |
Git source of the kit, for example git:git@github.com:SATUNIX/luna to use SSH. A value that still names a retired private source is ignored and reported |
PI_KIT_DELIVERY |
git or npm: override the kit's delivery on this machine |
PI_KIT_NPM_REGISTRY |
Registry to query for pi and linked packages (default https://registry.npmjs.org) |
PI_OFFLINE |
pi's offline mode: no background check |
Without the extension
The same updates from a shell:
pi update --self # pi
pi install git:github.com/SATUNIX/luna@v<version> # Luna, to a new release (latest or a pin)
pi update git:github.com/SATUNIX/luna # Luna, on next
pi update --extensions # every unpinned package
node ~/.pi/agent/git/github.com/SATUNIX/luna/packages/core/install.mjs --profile balanced --yes --settings-only
# re-apply a profile (and companion pins)
To find the newest release tag: git ls-remote --tags https://github.com/SATUNIX/luna.git.
Checkouts
A checkout registered in place for development: /update kit runs git pull --ff-only,
re-applies the profile and reloads. Uncommitted work blocks nothing: a fast-forward either
applies cleanly or fails without changing anything. It is reported as behind only when its
upstream branch has commits the checkout does not contain.
/update channel latest (or next) from a checkout registers the released Luna instead of the
checkout. The installer keeps exactly one registered copy of Luna: any other copy (another
checkout, the npm package) would load every extension twice.
Delivery
Where releases come from is set in packages/core/distribution.json ("delivery": "git"). npm
delivery (@satunix/pi-system dist-tags) is built but the package is not published; see
Releasing. When a Luna release changes the delivery,
/update kit moves each install over, keeping its channel and profile.
git.previousSources lists former public delivery sources. Registrations from those
repositories are recognised as Luna, ignoring transport and ref. When one differs from the
current git.source, /update kit offers to move it using the installer, keeping its channel,
profile and project scope. An exact version remains an exact version. This list is separate from
git.legacySources, whose retired private sources must never be contacted. Malformed
previousSources metadata is refused. The shipped list retains the former public repository location
(tests/kit-update-smoke.ts, tests/distribution-smoke.ts and
tests/distribution-contract-smoke.ts).
Luna also recognises itself under the package name @satunix/luna and the repository
github.com/SATUNIX/luna (any ref, any URL form), as well as every pi-system form. A repository
named luna under another owner or host is not Luna, so a fork of it is recognised only
through an explicit previousSources entry. The unrelated npm package luna is never touched by
duplicate-registration cleanup (tests/install-profile-filter-smoke.ts,
tests/profile-command-smoke.ts).
Coming from the private GitLab source
An install registered from the earlier private GitLab source runs that checkout's old code, which
cannot move itself. Install the public Luna package and run its installer (Migration, Route 1);
from then on /update follows the public repository. Where a retired registration or a local
checkout with a retired origin is seen by this release's /update, it reports it and never
contacts that host (/update kit moves a registration; a checkout is left for you to re-point).