Complete the full planned effort for the detailed ctx.bare code audit
and the new ctx.pear surface, delivering the ability to create, stage,
and integrate real Pear applications from within a booted Bare OS.
### Audit (ctx.bare)
- Performed exhaustive code audit of bare-os-ctx-bare.js (host import
path, drive bundle eval + require.addon wrappers, referrer workarounds).
- Inventoried all manifest/bundle verifiers and related scripts.
- Researched manifest format, implicit tiering model, and dual loading
strategy (JSON + .data.mjs).
- Deep analysis of the local Holepunch clone (bare-* and pear-* packages)
to identify realistic guest vs host-delegate boundaries.
- Full cross-reference of call sites, greps, and historical pain points
(pear:// referrer resolution, nativeHint handling, addon stubs).
### Implementation (ctx.pear)
- Added `pearEntries` tier to bare-module-manifest.json with initial
high-value packages (pear-build, pear-bundle, pear-ref, etc.).
- Implemented `loadPearModuleManifest()` and `buildPearCtxObjectFromHost()`.
- Wired ctx.pear exposure through the booter into the guest context.
- Updated TypeScript definitions (`bare-os-ctx.d.ts`).
### User-Facing Surface
- Created full `/bin/pear` command with `help`, `info`, `list`, `init`
(functional skeleton creation), and improved `stage` subcommands.
- Registered as Tier-1 command (now 183 total commands).
- Added man page and rebuilt coreutils (kernel + seeder).
### Agent Autonomy
- Created production-quality `pear-dev` agent skill.
- Added to skill seed list with cross-references to the appstore skill.
### P2P App Store Integration
- Updated appstore skill with explicit Pear development synergy section.
- Updated p2p-app-store design doc to document the new closed loop.
- Added cross-references in both skills and design documents.
### Verification & Hygiene
- Created `scripts/verify-pear-module-manifest-data.mjs`.
- Enhanced `verify-pear-no-static-node-import.mjs` with explicit pear
command coverage.
- Integrated new verifier into release-checklist and agent hints.
- Performed comprehensive zero-TODO/scaffolding sweep across all new
Pear artifacts (clean).
- Multiple full verification harness runs (all green).
### Documentation & Governance
- Added complete "Pear Development Environment" thread to feature-roadmap.md.
- Updated developer guide (Chapter 12).
- Maintained living plan document and detailed audit notes with full
Implementation Log throughout.
- Updated command counts across READMEs and supporting docs.
All changes follow project governance:
- Bare-only guest constraints strictly observed
- Verifier-first discipline maintained
- Living plan + audit documents kept as single source of truth
- Production quality bar matching the completed P2P App Store feature
Plan items 04–21 completed.
See:
- docs/design/ctx-pear-surface-and-bare-audit-plan.md
- docs/audit/ctx-bare-audit-notes.md (full audit + implementation log)
Protomux timing — Even with a connected socket, messages[0].send() must run after the channel is fully open. A bare send() right after chan.open() often does nothing useful until pairing finishes. Waiting on peer.chan.fullyOpened() (from Protomux) before each send fixed the standalone TCP check and matches real Hyperswarm behavior.
Code changes (packages/bare-os-booter/lib/swarm-disk.js)
read(index) — For each peer, schedule the read request with
peer.chan.fullyOpened().then(() => … send(index)) instead of sending immediately.
addPeer — After this.peers.add(peer), for every pending index in pendingReads, schedule the same fullyOpened() → send path so joiners get block requests once their channel is ready.
packages/bare-os-booter/index.js
Added ctx.bareOsTelnetConnect(host, port, opts) that prefers ctx.bare.bareTcp.createConnection, then new bareTcp.Socket(), with explicit diagnostics if unavailable.
packages/bare-os-coreutils/src/telnet.js already preferred ctx.bareOsTelnetConnect, so it now uses this richer path first automatically.
Added missing ssh command:
New file: packages/bare-os-coreutils/src/ssh.js
Supports -h/--help
Delegates to ctx.bareOsRunSshCli when present
Emits explicit nonzero unavailable/runtime diagnostics when absent
Registered command:
packages/bare-os-coreutils/lib/commands.mjs
Hardened HDMS create mount visibility:
packages/bare-os-booter/lib/hdms-manager.js
hdms create now verifies mount visibility via getMountMap().has(label) and errors non-silently if missing.
Success message now includes mount path (mounted=/mnt/<label>).
Fixed parser/semantics and explicit failures:
packages/bare-os-coreutils/src/kill.js
-1 is now treated as a target (not misparsed as signal shorthand), so kill -TERM -1 is explicit/non-silent.
packages/bare-os-coreutils/src/test.js
Numeric test comparisons now emit diagnostic + exit 2 for empty integer operand cases (keeps existing non-decimal behavior stable).
packages/bare-os-coreutils/src/crontab.js
Explicitly rejects stdin/fd-style installs (-, /dev/fd/*, /proc/self/fd/*) with nonzero error.
Updated ctx typings:
packages/bare-os-booter/lib/bare-os-ctx.d.ts
Added bareOsRunSshCli?
Added bareOsTelnetConnect?
hdms
Added ls alias to list.
Made delegate failures explicit and nonzero in packages/bare-os-coreutils/src/hdms.js.
Added nonzero error exit in packages/bare-os-booter/lib/hdms-manager.js.
git-pear
Implemented clone subcommand routing to git clone in packages/bare-os-coreutils/src/git-pear.js.
trustctl
Added ls alias to status/policy output in packages/bare-os-coreutils/src/trustctl.js.
oidc-publish
Added explicit unknown-subcommand handling and publish subcommand compatibility in packages/bare-os-coreutils/src/oidc-publish.js.
ssh-keygen
Wrapped delegate invocation with explicit error propagation in packages/bare-os-coreutils/src/ssh-keygen.js.
Added success output on generated keypair in packages/bare-os-booter/lib/ssh-keygen-cli.js.
sshd
Added -t config test mode and explicit exit semantics in packages/bare-os-booter/lib/bare-openssh.js.
Ensured wrapper sets exit code consistently in packages/bare-os-openssh/src/sshd.js.
telnet
Changed connector preference to use net.createConnection first when available, then syscall bridge fallback, in packages/bare-os-coreutils/src/telnet.js.
crontab -e flow
Implemented edit flow with VISUAL/EDITOR fallback, unlocked-state checks, temp file handling, install, and cleanup in packages/bare-os-coreutils/src/crontab.js.
Shell/runtime hardcore semantics
Added numeric brace range expansion {1..5} in packages/bare-os-booter/lib/shell-glob.js.
Enabled brace expansion by default unless explicitly disabled.
Added normalization for inline brace-expression tokens in packages/bare-os-booter/lib/shell.js.
Added arithmetic command-form handling for (( ... )) in packages/bare-os-booter/lib/shell.js.
Extended shell signal trap dispatch support for USR1/USR2 (in addition to INT/TERM) in packages/bare-os-booter/index.js.
Hardened kill command delivery validation in packages/bare-os-coreutils/src/kill.js.
Regression tests
Added new: packages/bare-os-coreutils/test/hardcore-bugs.test.mjs.
Extended shell tests in packages/bare-os-booter/test.js for:
default cmdsub behavior,
brace range expansion,
arithmetic command form.
Existing regression files still pass after updates.
packages/bare-os-booter/lib/shell.js
$(...)/backticks are now enabled by default unless explicitly disabled via BARE_OS_SHELL_CMDSUBST=0|false|off.
Fixed sh -c exit/status propagation:
packages/bare-os-booter/lib/shell.js
Syncs BARE_OS_EXIT_STATUS after each executed statement so later commands in the same line (like echo $?) see the immediately previous status.
packages/bare-os-coreutils/src/sh.js
In -c mode, reads final BARE_OS_EXIT_STATUS back into ctx.exitCode for consistent result propagation.
Implemented trap behavior for requested scope (EXIT, INT, TERM):
packages/bare-os-booter/lib/shell.js
exit builtin now runs EXIT trap handler before requesting booter exit.
packages/bare-os-booter/index.js
Signal delivery for shell PID now triggers trap dispatch for INT/TERM.
Hardened ulimit -f invalid diagnostics:
packages/bare-os-coreutils/src/ulimit.js
Explicit invalid-value error for malformed -f setter input, with nonzero exit.
Supported-but-unimplemented setter values still return explicit unsupported-setter error.
if=/dev/zero with finite count*bs now produces requested size directly (not limited by VFS 64KiB pseudo-file).
Raw stdout now uses bareOsEmitRaw, improving pipeline correctness.
Fixed pipeline capture path for FIFO-relevant commands
echo and cat now emit via bareOsEmitRaw (packages/bare-os-coreutils/src/echo.js, packages/bare-os-coreutils/src/cat.js).
Shell pipeline now injects bareOsBinWrite into child contexts when output is captured, so raw writes are captured (packages/bare-os-booter/lib/shell.js).
Improved xattr behavior in packages/bare-os-coreutils/src/xattr.js
Added -p/--print NAME.
-w now logs written attribute name for visible success feedback.
Roundtrip behaviors preserved with sidecar metadata format.
Improved ACL UX in:
packages/bare-os-coreutils/src/getfacl.js
Explicit source header for sidecar and mode fallback (non-compact mode).
packages/bare-os-coreutils/src/setfacl.js
Added -m/--modify ENTRY in addition to stdin blob and -b.
Implemented dynamic ulimit output in packages/bare-os-coreutils/src/ulimit.js
Reads /proc/bare_os/rlimits.json when available.
Supports -a, -n, -Sn, -Hn.
Added shuf -e support in packages/bare-os-coreutils/src/shuf.js.
Added split byte-suffix parsing (k/K/m/M/g/G) and attached -bSIZE support in packages/bare-os-coreutils/src/split.js.
curl --version in packages/bare-os-coreutils/src/curl.js
wget --version in packages/bare-os-coreutils/src/wget.js
openssl version and openssl --version in packages/bare-os-coreutils/src/openssl.js
nano --version (via edit) in packages/bare-os-coreutils/src/edit.js
Updated tar compatibility in packages/bare-os-booter/lib/tar-cli.js:
Added tar --version
Added grouped short-flag parsing (-czf, etc.)
Added first-arg legacy cluster parsing (czf)
Added - archive target support for create/list/extract stream paths
Kept implementation as ustar subset (accepts z for compatibility parsing)
Fixed pipeline/timeout behavior:
Optimized head line mode to stop scanning early (no full split) in packages/bare-os-coreutils/src/head.js
Added bounded safety for yes cap in packages/bare-os-coreutils/src/yes.js
Hardened timeout so timed-out commands reliably produce exit code 124 in packages/bare-os-coreutils/src/timeout.js
Added scoped expr compatibility in shell:
Prevented pathname expansion of bare * only for expr arithmetic-token case in packages/bare-os-booter/lib/shell.js
Added glob option plumbing in packages/bare-os-booter/lib/shell-glob.js
What changed
Fixed /bin generation for AsyncFunction execution in build pipeline:
Added appctl preamble wiring (p2p-suite.js) in packages/bare-os-coreutils/build.mjs.
Added a stripRunExport transform to remove trailing export { run } from generated /bin scripts.
Updated cut delimiter parsing in packages/bare-os-coreutils/src/cut.js:
Supports both -d X and attached -dX forms (including -d' ').
Validates -d argument presence and enforces single-character delimiter.
Improved uname -a output in packages/bare-os-coreutils/src/uname.js:
Better release/version derivation from env and /etc/os-release.
Uses env-backed machine architecture fallback instead of hardcoded unknown where available.
Added help aliases in packages/bare-os-coreutils/src/git-pear.js:
git-pear --help and git-pear -h now map to help output.
Reduced persistent invalid timer spam in packages/bare-os-booter/lib/bare-cron.js:
Added per-file parse-error dedupe/rate-limiting (first-seen, content-change, then hourly).
Added actionable invalid timer format hint in log message.
Route direct .sh invocations (e.g. ./test.sh) through the shell frontend instead of JS evaluation, and add a regression test to cover direct .sh execution.
Peer admission and bootstrap controls
- Fail closed when BARE_OS_PEER_ALLOWLIST_HEX is empty unless explicit
break-glass BARE_OS_PEER_ALLOW_ALL=1.
- Treat BARE_OS_ZERO_TRUST_PROFILE=strict|security like strict admission
posture alongside BARE_OS_PEER_ALLOWLIST_STRICT.
- Document BARE_OS_PEER_ALLOW_ALL and profile semantics; update boot trust
model operator guidance.
Peer system seed and provenance
- In strict/security profile, peer system seed defaults off unless
BARE_OS_PEER_SYSTEM_SEED is explicitly enabled (1/true/yes).
- Disable synthetic capability filling in strict profile; keep compat path
when profile is not strict.
- Extend test.peer-system-seed.js for strict default-off and no-synthesis.
Path capability signer trust
- When BARE_OS_PATH_CAPABILITY_ENFORCE_READ is on, require trusted issuer
if BARE_OS_PATH_CAPABILITY_REQUIRE_TRUSTED_SIGNER is set or profile is
strict; wire verifyPathCapabilityEnvelopeTrusted into the primary deny
path.
- Document BARE_OS_PATH_CAPABILITY_REQUIRE_TRUSTED_SIGNER and trusted key
list usage in environment appendix.
Host delegates (least privilege)
- Under strict/security profile, empty BARE_OS_DELEGATE_ALLOW means deny-all
delegates instead of allow-all; document behavior.
- Add delegate strict-profile test coverage.
Audit durability and telemetry hygiene
- Retain audit chain rows in memory and add bareOsAuditPersistRows for
optional NDJSON persistence via VFS.
- Broaden var-log redaction for secret-shaped strings and env-like assignments.
- Emit boot.log security line when unsafe trust combinations are detected.
Release and CI gates
- Add scripts/verify-zero-trust-gates.mjs and npm run verify:zero-trust-gates.
- Document verifier in scripts/README.md and zero-trust steps in
docs/release-checklist.md.
Tests
- Update bare-os-booter admission tests for allow-all and empty-allowlist
messaging.
- Relax brittle man.json page-count equality to a minimal sanity check to
avoid brittle/os.cwd brittle failures on inventory drift.
Verification (local): npm run verify:zero-trust-gates; npm run test -w
bare-os-booter; peer-system-seed brittle lane as applicable.
Plan file (.cursor/plans/zero-trust-boot-runtime-100-plan_*.plan.md) was not
edited per instructions.
Implement sh -c COMMAND [NAME [ARG...]] in /bin/sh, add shell function
declarations/invocation support, expand export semantics (NAME, NAME=value, -p),
and make until/loop-control behavior available by default. Add focused shell
tests and update sh man-page option docs.
Implement the 50-point Holepunch alignment roadmap with a first-pass delivery across coreutils commands, policy examples, audit tooling, and docs. This adds new operator CLIs (appctl/corestorectl/ctxbaredoctor/dhtctl/trustctl), tiered catalog and runtime-compat reports, release-checklist integration, contributor guidance, and kernel/seeder mirrored artifacts for app registry, trust, network services, corestore namespaces, and update manifest workflows.
Raven Scott
snxraven