.pi/extensions/_shared/ is installed by deploy-scenario.sh from shared/extensions/
and is not in the scenario's workspace/, so pi-diff listed it as merely
"UNTRACKED in live workspace" -- no comparison at all. The file most likely to
drift, because it is the one shared between scenarios, was the one the diff had
nothing to say about.
Now compared against shared/extensions/ and reported like any other file, with a
missing source called out separately.
Also fixes the counter: the new branch incremented a variable named `changed`
while the summary reads `DIFFS`, so a detected difference printed a diff and then
claimed the installation agreed, and exited 0. Verified by planting drift: exit 1
and "1 difference(s) found", then 0 after redeploying.
curator-tools.ts registers no schema of its own: it fetches the specs from the
backend bridge, so contracts.py stays the single owner and there is no TypeScript
copy to drift. It refuses to activate without a bridge URL and token, because an
agent that silently loses its tools still answers -- from the model's memory of
what a media library might contain.
deploy-scenario.sh now vendors listed shared/extensions modules into
.pi/extensions/_shared/. A tracked extension importing from shared/ cannot
resolve that path once installed outside the repository, so the deployed tree has
to be self-contained; this overwrites rather than merges, keeping the repository
authoritative. common.sh gains toml_list, using tomllib rather than more awk
because an array can span lines or carry comments.
verify-generated.sh checks that generated regions in tracked prompts match the
backend that generates them, and is wired into the pre-commit hook. This is
needed because of finding 22 below: the tool list has to be copied into the
prompt, and a copy drifts silently.
Two findings recorded in docs/pi-runtime-notes.md, both measured:
21. An extension that fails to import is silent -- exit 0, empty stderr, no
tools. A missing --extension path exits 1 with a clear message, but a
module that throws while loading reports nothing. The agent then invented a
complete library listing with plausible episode counts, quality and size.
A later identical run said it had no data instead, so the failure is both
silent and inconsistent.
22. --system-prompt suppresses the tool list. The customPrompt branch returns
before toolsList and guidelines are built, so promptSnippet and
promptGuidelines are inert. The tools stay callable over the provider API,
so tool use becomes a coin flip: one run in four looked at the library and
three said they had not been given any results.
SYSTEM.phase3.md is staged alongside the deployed SYSTEM.md rather than replacing
it: profile.toml still describes the phase-0 configuration that is actually
running, and the live service is untouched.
Scenarios
- memo-inbox: mirrored by copying; the live directory was not moved or modified
and the service was not restarted. All four tracked files match byte for byte
(pi-diff.sh reports SAME). Marked deploy = "mirror" so deploy-scenario.sh
refuses --apply: applying a mirror would invert the direction of truth and
could change a service in daily use.
- curator: target configuration, not yet deployed. .pi/SYSTEM.md replaces pi's
coding-assistant prompt; durable role text is in .pi/APPEND_SYSTEM.md;
profile.toml is the single source of truth for the launch contract.
- pi-grok: registered only. It is genuinely a coding agent, so the isolation
baseline does not apply in full.
Corrections to the documentation, found by testing rather than by reading
- AGENTS.override.md does NOT block parent-directory context files; it only
shadows its own directory. Verified: with an override file in the workspace, a
marker in /tmp/AGENTS.md still reached the system prompt. The only effective
switch is --no-context-files, so durable role text must live in
.pi/APPEND_SYSTEM.md, which is a system-prompt file and unaffected by -nc.
Verified end state: no coding-assistant framing, no pi-docs block, own
identity and role text present, no parent pollution, only own skills/tools.
- PI_CODING_AGENT_DIR isolates settings/models/auth/trust/extensions/skills/
prompts/themes under the agent directory -- stronger than the --no-* flags
because it also repoints credentials -- but does NOT cover ~/.agents/skills.
Measured: find-skills, modsearch and summarize still leak. So it complements
--no-skills rather than replacing it.
- --append-system-prompt accepts a file path, which pi-grok relies on.
- cwd is what anchors .pi discovery: a probe that forgot cwd silently lost
.pi/SYSTEM.md and kept the coding-assistant persona.
Tooling (all dry-run by default; none of them restarts a service)
- pi-diff.sh: compares tracked config against the live install in both
directions, with a key-redacted comparison for models.json
- deploy-scenario.sh: installs a workspace and renders profile.toml into
.pi/launch.json, then checks that every referenced path exists
- deploy-runtime.sh: renders models.json from its template, refusing placeholder
or missing keys. Verified byte-identical to the live file
- pi-backup.sh / pi-restore.sh: archives outside the repo, sha256 manifest
verified before any restore, live paths preserved rather than overwritten
Fixed while testing: pi-backup.sh compared the destination against the repo root
literally, so a relative --dest ./backups wrote credential archives into the work
tree. Now canonicalised with realpath; ./backups, an absolute in-repo path and
./docs/../backups are all refused.
Two defects found by testing the guard against itself:
1. When invoked through the .git/hooks/pre-commit symlink, deriving the repo
root from dirname(BASH_SOURCE)/.. resolved to .git/ instead of the work
tree, so the hook scanned nothing and never blocked. Use
'git rev-parse --show-toplevel' instead.
2. The blanket secrets/ rule rejected secrets/.gitkeep. Replaced with an
explicit allowlist: .gitkeep, README.md, *.example, *.template.
Verified: a staged file containing a Telegram bot token now aborts the commit
and leaves HEAD unchanged.
Establishes this repository as the authoritative source for Pi agent
configuration across scenarios, starting with the documentation layer.
Key verified findings (probe harness included, zero model tokens):
- The skills section of the system prompt is emitted only when an active tool
named 'read' exists (system-prompt.js:59,113). Therefore --no-tools silently
makes every SKILL.md unreachable and --skill a no-op.
- registerTool accepts a plain JSON Schema object, so tool definitions can be
served from a backend instead of duplicated in TypeScript.
- An extension can shadow a built-in tool by name, which is how a dedicated
agent gets a path-restricted 'read' while still satisfying the rule above.
- .pi/SYSTEM.md replaces pi's coding-assistant prompt, but the replacement
branch contributes neither the tool list nor the guidelines.
- Without --no-skills/--no-extensions, user-global resources leak into every
scenario; probed leak was find-skills, modsearch, summarize.
Measured effect of the full baseline: system prompt 2619 -> 960 characters,
coding-assistant framing and pi-docs paths removed, skill finally reachable.
Secrets are guarded by scripts/verify-no-secrets.sh, installed as a pre-commit
hook. Backups deliberately live outside the repository.
Kai