pi-fabric-hardening
Idempotent, marker-guarded runtime patches for pi-fabric and pi-fold: survive a full temp dir, keep the real cause of a dead child, configurable recovery watchdog.
Package details
Install pi-fabric-hardening from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-fabric-hardening- Package
pi-fabric-hardening- Version
0.2.0- Published
- Nov 21, 2026
- Downloads
- 333/mo · 47/wk
- Author
- xuqianhui
- License
- MIT
- Types
- extension
- Size
- 30.9 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"./extensions/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-fabric-hardening
Runtime hardening for pi-fabric (and pi-fold), as an extension instead of a fork.
Why this exists
Every fix here comes from a real incident where Fabric's failure mode was worse than its bug:
| Symptom | Root cause |
|---|---|
The whole Pi process disappears with Unknown system error -122 |
A full tmpfs made writeRecord() throw EDQUOT; the throw escaped as an uncaughtException. One status write killed the host. |
| Six parallel children "failed" with the same unrelated message | A child's stderr (an extension complaining) replaced the real cause of death, so SIGSEGV was invisible. |
Children killed with made no recovery progress for 60000ms while still retrying |
The recovery watchdog's timeout is a hardcoded 60 s and only resets on content deltas — longer than a slow gateway's TTFT, shorter than Pi's own retry backoff. |
| Atomic state writes fail once and stay failed | renameAtomic retried EPERM/EACCES/EEXIST/EBUSY but not EDQUOT/ENOSPC/EIO, so quota pressure became permanent corruption. |
A --no-session child logs Evidence ingestion requires an absolute Pi session file |
pi-fold's evidence hook throws when there is no session file, which then becomes the child's reported death cause. |
A child is killed with requested X, but assistant reports Y; terminating child after 8 turns and 0 artifacts |
Model admission is strict even for a different model of the same provider, so a legitimate mid-run re-point (the pool's alias ladder, a latency failover) destroys finished work. |
pi install runs with --ignore-scripts and upgrades replace node_modules wholesale, so a manual edit never survives. This extension re-applies a small patch set on every Pi start.
The patch set
| id | package | effect |
|---|---|---|
status-write-guard |
pi-fabric | a failed status write degrades to a stderr line; the host keeps running |
rename-quota-retry |
pi-fabric | atomic rename retries EDQUOT/ENOSPC/EIO/EMFILE/ENFILE (transient under quota pressure) |
recovery-watchdog-timeout |
pi-fabric | timeout reads PI_FABRIC_RECOVERY_TIMEOUT_MS, default 600 000 ms (was hardcoded 60 000) |
exit-signal-decl, exit-signal-capture, exit-signal-record |
pi-fabric | the child's terminating signal is captured and stored as exitSignal |
error-ordering |
pi-fabric | "was killed by SIGSEGV" comes first, stderr becomes ; last stderr: … |
tolerate-same-provider-model-drift |
pi-fabric | a child served by another model of the same provider logs the drift and keeps running; another provider, or a missing attribution, is still fatal |
evidence-no-session-guard |
pi-fold | skip evidence archiving when there is no session file instead of throwing |
grow-loop-child-guard |
@llblab/pi-grow-loop | grow_loop refuses inside a Fabric child (PI_FABRIC_DEPTH>=1); a looping child never reaches a terminal state the parent can see, so agents.wait blocked to timeout |
grow-loop-state-visible |
@llblab/pi-grow-loop | the tool result says ⟳ 续轮 #N instead of an ambiguous "scheduled" sentence |
grow-loop-state-guideline |
@llblab/pi-grow-loop | the prompt guideline requires an explicit ⟳ 续轮 / ■ 结束 marker |
Plus one patch-free fix: TMPDIR relocation. When /tmp is a tmpfs with less than PI_FABRIC_TMPDIR_MIN_FREE_MB (default 4096) MB free, TMPDIR is pointed at ~/.cache/pi-tmp before Fabric creates its run roots. A real disk is left alone.
Design rules
- Idempotent. Each patch carries a marker comment (
[pi-fabric-hardening:<id>]). A file that already has it is left untouched, so restarting Pi is free. - Found by content, not filename. pi-fabric's compiled chunks are renamed on every release (
chunk-QUWC6YCN.jstoday, something else tomorrow), so patches search the declared roots and apply to every file containing the upstream text — including the two chunk files that each defineRETRYABLE_RENAME_CODES. - Fails soft. Package missing (
pi-fabricnot installed), file missing, or upstream text changed: the patch is skipped and reported. Nothing throws, nothing blocks startup. - No forking, no bundling. Patches are text substitutions against the installed package; the extension has no dependency on pi-fabric.
- Atomic writes. A patched file is written to a temp name and renamed into place, so an interrupted write can never leave a half-written chunk behind.
Install
pi install npm:pi-fabric-hardening
# or
pi install ./packages/fabric-hardening
Restart Pi. On the first start you will see lines like:
[fabric-hardening] patched pi-fabric: status writes degrade instead of crashing the host (1 file)
[fabric-hardening] TMPDIR /tmp -> /home/you/.cache/pi-tmp (tmpfs had 812 MB free)
Configuration
| Variable | Default | Meaning |
|---|---|---|
PI_FABRIC_HARDENING |
on | 0/off disables all patches; id1,id2 applies only those ids |
PI_FABRIC_HARDENING_EXCLUDE |
— | ids to skip |
PI_FABRIC_RECOVERY_TIMEOUT_MS |
600000 |
recovery watchdog timeout (consumed by patch 3) |
PI_FABRIC_TMPDIR |
unset | off disables relocation; a path forces that directory |
PI_FABRIC_TMPDIR_MIN_FREE_MB |
4096 |
relocate only when the tmpfs has less free space than this |
PI_NPM_DIR |
~/.pi/agent/npm/node_modules |
where Pi installs packages |
PI_CODING_AGENT_DIR |
~/.pi/agent |
Pi agent directory |
Limits
- These are patches to compiled JavaScript inside someone else's package. An upstream release that rewrites the matched text turns a patch into a
skipped … upstream text changedline — check the startup output after upgrading pi-fabric, and open an issue (or better, an upstream PR) when that happens. - Patch text is validated against pi-fabric 0.135.2 and pi-fold 4.3.0. Older and newer versions apply whatever still matches.
recovery-watchdog-timeoutonly lengthens the watchdog; it does not make a genuinely hung model call succeed.- A patched file is written in place, so
node --checkon the whole package is worth doing if you suspect breakage. Reinstalling the package withpi updaterestores the pristine files.
Uninstall
pi remove npm:pi-fabric-hardening
pi update --extensions # or reinstall pi-fabric / pi-fold to revert the patched files