Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,26 @@
- **fix(install): a failed Pi install exits nonzero, like a declined one.** The
script refused to call a DECLINED upgrade success — "a zero status would tell
a script that everything is ready when the thing that runs people is too old"
— and then reported a FAILED install as success anyway, through two `|| true`
sites. A caller got the happy outro and status 0 with the agent runtime
absent, which is strictly worse than the too-old Pi the decline path already
refuses. **The rationale proved more than the code implemented.** Both sites
now end in the same deliberate family as the decline, naming what did not
happen and the command that fixes it.

**And the rule now has an instrument, which it never had.** Every Pi branch
was reachable only by running the real installer against the real network, so
nothing checked the exit code any of them produced and the rule shipped as a
comment. `installer-pi-exit-codes.test.mjs` runs the script's OWN bytes —
extracted at a marker, executed against stub `pi` and `npm` — over five
behaviours, and carries a control that restores `|| true` in a copy and
asserts the block goes green, so the passing assertions are known to measure
the defect rather than merely to pass.

- **feat(install): the installer installs and upgrades Pi instead of printing a command and hoping.** An absent Pi is installed without asking — chief cannot run a single person without it, so there is nothing to weigh. A Pi that is merely too old is somebody's working tool, and replacing it is a different act, so that one asks: `Upgrade Pi to >= <floor>? [Y/n]`, default yes. Declining exits nonzero and says why, because telling a script that everything is ready when the thing that runs people is too old is worse than failing.
**The floor is read, never restated.** It has one definition in the Rust source, the release process already stamps it into the manifest, and the installer reads it from the manifest it has just unpacked. A version bump needs no edit to the installer, and the repository's single-definition guard stays satisfied — a number copied into a shell script would be a second definition wearing a copy's clothes.
**The prompt reads the terminal, not its own source.** This file is piped into `sh`, so stdin is the script text; reading stdin would eat the rest of the installer. Where there is no terminal at all — CI, a container build — the default is taken and SAID, because a silent choice made on somebody's behalf is what surprises them later. Missing `npm` refuses cleanly rather than half-installing, and a Pi that npm reports as installed is CHECKED against the floor rather than announced as ready.

- **feat(intercom): organization mail rides the same queue as the operator's own typing.** A busy person now reads an ordinary message at the next step boundary inside the running turn, instead of at the end of it. The operator typing mid-turn has always been submitted as a steering message and consumed within seconds; ordinary mail rode the follow-up queue, which Pi consumes only once the agent has no more tool calls or steering messages — so somebody an hour into a piece of work did not see a teammate's message until the hour was over, while the identical words typed by the operator arrived immediately.
**The digest is kept; only its consumption point moves.** Batching is still the answer to twenty messages arriving in one turn, and nothing about how a batch is built has changed.
**The idle and boot rows are byte-identical.** Mail arriving at somebody doing nothing still starts them; mail arriving inside the boot window is still parked. This changes WHEN a busy person reads a message, never whether an idle one is woken — and it touches nothing in the converge, activity or settle paths, so the operator wake lease is untouched by construction.
Expand Down
21 changes: 21 additions & 0 deletions DECISIONS.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,24 @@
- 2026-08-28 — **An exit code is a claim about STATE, not about effort, so a
missing prerequisite may never exit zero.** install.sh already refused to call
a declined Pi upgrade success; it then reported a FAILED install as success
via `|| true`, leaving the agent runtime ABSENT — the worse state — while
telling every calling script that chief was ready. The defect class is the one
this branch keeps producing in new clothes: **the rationale proved more than
the code implemented**, and the carve-out's own words were the argument
against the line three branches away. So the rule is stated positively: every
path that ends without a usable prerequisite exits nonzero and names both what
did not happen and the command that repairs it, and no comment counts those
paths, because a count in a comment goes stale silently. Pinned by
`installer-pi-exit-codes.test.mjs`, which executes the installer's own
extracted bytes against stub `pi`/`npm` rather than asserting over its text,
REFUSES in words when its marker no longer locates the block, and carries a
control that reinstates `|| true` in a copy and requires the block to go green
— a pin nobody has flipped is a claim, not evidence.

- 2026-08-28 — **A shell guard tests USABILITY, never EXISTENCE.** Three separate defects this week were one defect: the check asked whether a thing was THERE when the only question that matters is whether the next line can USE it. A profile file was selected by `[ -f ]` and then written to a path that was not writable; a link was accepted because it resolved to a name, and the name pointed at nothing; and `[ -r /dev/tty ]` answered true inside a container whose `/dev/tty` cannot actually be opened, so the prompt that followed killed the installer with status 2 and no message. The general form is that `-e`, `-f`, `-r` and `-w` report a directory entry and its permission bits, which are a claim about the FILESYSTEM, while the operation that follows is a claim about the KERNEL — and the two disagree for containers, dangling symlinks, read-only mounts, full disks and revoked terminals. So the guard performs the real operation and reads its status: open the file, follow the link, redirect the terminal. **And it performs it where a failure is survivable**, which is the second half of the rule and the half `/dev/tty` taught — `{ : < /dev/tty; }` is a redirect on a special built-in, and under `set -eu` a redirect error there is fatal to the whole shell, so the probe must run in a subshell, `( : < /dev/tty )`, where the status can be read instead of ending the script. A probe that cannot fail safely is not a probe, it is the bug it was written to prevent.

- 2026-08-28 — **Install what is missing; ask before replacing what somebody already has.** The installer now handles Pi, and the asymmetry is the decision: an ABSENT prerequisite is installed with no prompt, because chief cannot run a person without it and there is nothing for the user to weigh; an EXISTING one that is merely below the floor belongs to them, and replacing a working tool without asking is a different act, so it prompts with a default of yes. Declining exits NONZERO — a zero status would tell a calling script the box is ready when the runtime every person needs is too old. Recorded with the constraint that shaped the implementation: **a number with one definition must be READ at every other site, never restated** — the floor is stamped into the release manifest by the release process, so a version bump touches no script, and the single-definition guard is satisfied rather than worked around. And two shell facts learned by running rather than reading, both of which end the installer silently if got wrong: a prompt in a `curl … | sh` script must read `/dev/tty` because stdin is the script itself; and `/dev/tty` must be tested by OPENING it inside a SUBSHELL, since the node exists in containers that have no terminal and a redirection failure on a special built-in is fatal to a non-interactive shell.

- 2026-08-28 — **A message from a teammate reaches a busy person on the same terms as a message from the operator.** Human typing mid-turn rides Pi's steering queue and is consumed at the next step boundary; ordinary mail rode the follow-up queue and waited for the turn to end, which on an hour-long turn is an hour. Interrupt mail already rode the steering lane, so this widens a production-proven path rather than building one, and the digest stays exactly as it was — batching answers volume, and only the moment of consumption moved. Two boundaries recorded with it. **The wake lease is untouched by construction**: this is client-side delivery-mode selection, and the lease's readers key on `person_activity.operator_wake_at`, which this neither reads nor writes — the idle and boot-window rows are byte-identical, so nothing about waking a stopped person changed. And **a decision written as a literal at a call site cannot be asserted**: the delivery table was pinned while the mode passed into it was not, so the timing of every delivery could change with every test still green. Naming the decision was what made the change reviewable, and that is the general lesson — a constant repeated at two call sites is two decisions, and neither of them is testable.

- 2026-08-28 — **A parameter description is a promise about the schema, and the schema is what the model obeys.** A documented default that the schema does not implement does not produce a caller who ignores the prose — it produces one who believes the prose, discovers the field is required anyway, and IMPROVISES a value. That is what happened: "DEFAULT: the department YOU head" over a required field, and an agent that reasoned its way to omitting the field, could not, and filled it with the most salient name in context. The instrument is the schema; the description is a claim about it; they must agree, and where they disagree the claim is what gets believed and the schema is what gets obeyed. The general question worth asking of any tool surface — **does the schema permit what the prose promises?** — is answerable mechanically, which is why the sweep was the substance of this change rather than an appendix to it. Recorded with the sharper reason the company-name alias stays rejected: with a real default in place the alias would exist ONLY on the override path, where a mid-level head naming the company means their own team — so it would resolve to the impressive-sounding wrong target rather than the semantically right one, which is worse than the refusal it would replace.
Expand Down
122 changes: 118 additions & 4 deletions install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -231,12 +231,126 @@ have tmux || {
say " macOS: brew install tmux"
say " Debian/Ubuntu: apt-get install -y tmux"
}
have pi || {
say ""
say "Pi is the agent runtime every person in a company runs, and was not found. Install it:"
say " $PI_INSTALL"
# --- Pi -------------------------------------------------------------------
#
# chief installs and upgrades Pi rather than printing a command and hoping.
# The asymmetry is deliberate: an ABSENT Pi is installed without asking, since
# chief cannot run a single person without it and there is nothing to weigh.
# An EXISTING Pi that is merely too old is the user's, and replacing somebody's
# working tool without asking is a different act, so that one prompts.
#
# THE FLOOR IS READ, NEVER WRITTEN HERE. `pi_floor.rs` holds the single
# definition, `release-chiefd.ts` stamps it into the release manifest as
# `piFloor`, and this reads it out of the manifest already unpacked above. A
# version bump therefore needs no edit to this file, and the repository's
# single-definition guard stays satisfied — a number restated here would be a
# second definition wearing a copy's clothes.
pi_floor="$(grep -m1 '"piFloor"' "$dest/manifest.json" 2>/dev/null \
| sed -E 's/.*"piFloor"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')"

# Sorts dotted versions without assuming a numeric field count.
version_below() {
[ "$1" != "$2" ] && [ "$(printf '%s\n%s\n' "$1" "$2" | sort -t. -k1,1n -k2,2n -k3,3n | head -n1)" = "$1" ]
}

# A PROMPT IN A PIPED SCRIPT MUST NOT READ ITS OWN SOURCE.
#
# This file is `curl … | sh`, so stdin is the script text: reading stdin would
# consume the rest of the installer. The question goes to the terminal
# directly. Where there is no terminal — CI, a container build — nothing can be
# asked, so the default answer is taken and SAID, because a silent choice made
# on somebody's behalf is the thing that surprises them later.
confirm_default_yes() {
# OPENABLE, not merely present. `[ -r /dev/tty ]` is TRUE in a container with
# no controlling terminal — the device node exists and the permission bits
# allow reading — and the redirect then fails with a raw shell error that no
# `2>/dev/null` on the command can suppress, because the shell reports it
# while setting the redirection up. Measured, not reasoned: it printed
# "cannot create /dev/tty: No such device or address" twice, before the
# question. Testing the open is the only honest test of whether it will work.
# A SUBSHELL, and that is load-bearing rather than stylistic. `:` is a POSIX
# SPECIAL BUILT-IN, and a redirection error on one is fatal to a
# non-interactive shell — `{ : < /dev/tty; } 2>/dev/null` does not evaluate
# to false in a container, it ENDS THE INSTALLER, silently, with status 2 and
# no message. Measured: the run stopped dead at this line. The subshell
# contains the death so the `if` sees an ordinary false.
if ( : < /dev/tty ) 2>/dev/null; then
printf '%s [Y/n] ' "$1" > /dev/tty
read -r reply < /dev/tty || reply=""
else
reply=""
say "$1 [Y/n] — no terminal to ask on, taking the default (yes)."
fi
case "$reply" in
[Nn]*) return 1 ;;
*) return 0 ;;
esac
}

pi_version_now() {
pi --version 2>/dev/null | tr -d 'v' | awk '{print $NF}'
}

install_pi() {
have npm || die "npm is required to install Pi, and it is not on PATH. Install Node.js, then run: $PI_INSTALL"
say "Installing Pi ($PI_INSTALL)…"
# A failure here is REPORTED, never silent, and never claimed as success.
if ! $PI_INSTALL; then
say "Pi could not be installed. chief is installed; run this yourself and it will work:"
say " $PI_INSTALL"
return 1
fi
have pi || {
say "npm reported success but pi is not on PATH yet — open a new shell, or run:"
say " $PI_INSTALL"
return 1
}
installed_version="$(pi_version_now)"
# CHECKED, not assumed. npm exiting zero is not the same as the floor being
# met — a global install can land somewhere earlier on PATH, or resolve to a
# version that is still too old — and reporting "ready" without looking is
# the same shape as every other claim that outran its evidence.
if [ -n "$pi_floor" ] && [ -n "$installed_version" ] && version_below "$installed_version" "$pi_floor"; then
say "Pi is $installed_version, still below $pi_floor. Install it yourself with:"
say " $PI_INSTALL"
return 1
fi
say "Pi ${installed_version:-installed} is ready."
}

say ""
if ! have pi; then
# ABSENT: no question. chief cannot run a person without it.
say "Pi is the agent runtime every person in a company runs, and was not found."
# NONZERO, for the same reason the declined upgrade below is nonzero, and more
# strongly. `install_pi` has already told the PERSON what to run; what it
# cannot do is tell a CALLER. A failed install here leaves the thing that runs
# people ABSENT, which is strictly worse than the too-old Pi the decline path
# already refuses to call success — so this cannot be the branch that reports
# ready. `|| true` said the opposite to every script consuming this installer.
install_pi || die "chief itself is installed under $CHIEF_HOME; Pi did not install — run: $PI_INSTALL"
else
pi_version="$(pi_version_now)"
if [ -n "$pi_floor" ] && [ -n "$pi_version" ] && version_below "$pi_version" "$pi_floor"; then
say "Pi $pi_version is installed; chief needs $pi_floor or newer."
if confirm_default_yes "Upgrade Pi to >= $pi_floor?"; then
# Nonzero for the reason above: an ACCEPTED upgrade that then failed
# leaves exactly the too-old Pi the branch below refuses to call success.
# Agreeing to fix it does not make it fixed.
install_pi || die "chief itself is installed under $CHIEF_HOME; Pi did not upgrade — run: $PI_INSTALL"
else
# One of the places this script exits nonzero after chief is installed —
# countless, because a count in a comment is a fact that goes stale
# silently. It is not a failed install: it is a declined prerequisite, and
# saying so with a zero status would tell a script that everything is
# ready when the thing that runs people is too old. The failed-install
# paths above exit nonzero for the same reason, applied to a worse state.
say ""
die "chief requires Pi $pi_floor or newer, and the upgrade was declined. chief itself is installed under $CHIEF_HOME."
fi
fi
fi

say ""
say "Then found your first company:"
say " mkdir acme && cd acme && chief"
4 changes: 4 additions & 0 deletions scripts/guard-wiring-manifest.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -478,6 +478,10 @@ export const GUARD_WIRING_MANIFEST = {
// --filter=./packages/*` before it shards, and `--ignore-scripts` does not
// skip devDependencies. A lane of its own was written first and deleted:
// it would have been a second place to keep those prerequisites correct.
// The installer's exit-code contract: a missing prerequisite may not be
// reported as success. Runs the script's own bytes against stub `pi`/`npm`,
// and carries its own control proving the assertions bite.
'installer-pi-exit-codes.test.mjs': { status: 'wired' },
'installed-release-extensions-load-under-pi.test.mjs': { status: 'wired' },
// The minimum Pi version, and the documents that quote it. Same shape as the
// beacond port above and for the same measured reason: a compiled-in constant
Expand Down
Loading