[FEATURE] Complete native shell/build utilities and provide help and offline manual pages #1
Labels
No labels
bug
ci
docs
duplicate
enhancement
help wanted
invalid
performance
phase-6
question
refactor
security
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
erix/exsh#1
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Problem and motivation
Users must launch compatibility tools and full builds through the native shell, with reliable job control and discoverable documentation. Tool-name exceptions or importing a shell to hide native POSIX gaps would leave the normal user path incomplete.
Proposed behavior and scope
Close selected POSIX shell and utility gaps, integrate real process/job semantics, and provide internal help plus a native man applet. Cover every CLI and IPC/Rust/C API with current indexed documentation and exercise scripts, pipelines, redirection and interactive navigation through real inputs.
This issue records planned work; its unchecked criteria are not implementation proof. The normative basis is Phase 6 and AC1–AC24.
Authority, security and reliability
Preserve native descriptor/job envelopes and exact TTY consent boundaries. Built-in help gains no filesystem authority; manual lookup reads only delegated roots and never executes page macros or embedded commands. Program names, arguments and environment paths cannot select broader authority.
Apply the priority order: security, reliability, then performance. Keep suspected vulnerabilities in the repository’s restricted SECURITY.md reporting channel.
Acceptance criteria
against the selected POSIX shell standard; enumerate remaining syntax, expansion, built-in,
signal, group and stopped-job gaps with tests.
remaining mandatory profile items; preserve native descriptor/job authority and distinguish
true fork from in-process descriptive state copying.
executable-name/argv-specific authority semantics; tools request/fail operations on their own,
within the launch envelope.
wait/trap/job-control interactions against real POSIX processes and groups.
descriptors, interruption and concurrent output; remove incidental shell storage limits
through caller/resource-owned growth.
required clean-room behavior in thematic modules and record where an explicitly inventoried
extended GNU tool is required instead.
trusted consent, output drain and repeated-command behavior under build load; add focused and
existing regression VM coverage.
checking exact output/status and zero authority leakage.
helpcommand with Bash-like behavior: no-argument topiclisting, pattern/topic selection, short description (
-d), manual-style output (-m),synopsis (
-s), option errors and match/no-match exit statuses. Verify combinations againstthe selected Bash reference.
helpfrom exsh's authoritative built-in/topic registry, documentingactual exsh behavior rather than advertising unimplemented Bash extensions; it must not spawn
an external executable or acquire filesystem authority for built-in help. Author original
explanatory text.
flags, invalid requests, redirection, pipelines and exit statuses.
coreutils man: section/name lookup, disambiguation, multiple pages,search/index behavior, terminal versus redirected output, missing-page errors and scoped
manual-directory discovery.
manas a native coreutils applet with readable paging,scrolling/search/quit and plain-text fallback for pipes; safely parse the chosen documented
man format and never execute page macros, escapes or embedded commands.
and Rust/C linkage APIs; inventory every exported interface and require an indexed page or a
clearly linked owning API page.
authority needs and errors for every tool, including
help,man,boot-tool,sha2-tool,exsh and extop; include admitted extended-tool manuals only under their declared
source/license/manifest policy.
layout or signatures, safety/ownership/lifetime/authority, errors, examples and
cross-references to canonical rustdoc/header/manual text.
authority; environment paths cannot broaden the manual scope or cause execution. Make docs
available without network access on both images.
mannavigation,resize, pipe/redirection, missing-page and denied-root VMs. Verify every CLI/interface
inventory entry resolves to useful current content.
For each implementation slice, retain actual formatting, strict Clippy, unit/doctest and warning-denied build results for all altered Rust repositories and valid configurations. Add relevant runtime VM coverage, monitor older unit/VM regressions in exact-head CI, and update canonical component documents and affected technical-manual/API material. Every authored code file must remain below 1,000 physical lines, with meaningful inline documentation and missing_docs enforcement in Rust crates.
Alternatives and tradeoffs
Admitted GNU tools or bash may cover declared non-POSIX recipe needs, but do not substitute for mandatory exsh behavior. Generate documentation from actual semantic registries where useful without advertising unsupported extensions.
Coherent realm dependency prerequisites — 18 September 2026: Signed
f7c1cd200ef13902b1025208ced6ddf659f10eb1selects original shared dependency revisions without changing direct Rust implementation bytes. Six strict development/release Rust configurations pass 961 tests each, with six native builds, fatal linker warnings, strict host/native Clippy, formatting and private rustdoc. All 355 frame-checker controls pass. The initial optimized compiler no-output timeout is retained; the interrupted and remaining compiler commands completed within the separately bounded production compiler budget. Four actual local frame-checker invocations retain exit 1 and empty reports under their unchanged limits. Those runs provide no workspace or complete frame acceptance. Original push/PR CI is under observation. Complete source/effect/frame admission, source-bound consumer VMs, complete realm operation and both full guest builds remain required.Original dependency CI outcome — 18 September 2026: Signed
f7c1cd200ef13902b1025208ced6ddf659f10eb1has complete original logs for CI 264 and CI 263 (315,374 bytes), with zero warnings. Both original runs fail the required complete frame-proof gate after 961 Rust units and 355 checker controls pass. All four CI workspace mappings complete. Runtime analysis retains 256 reached functions and 101 unresolved observations; all-feature analysis retains 236 and 64. Direct early-drop and ordinary source membership remain incomplete. These CI observations do not replace the separately retained empty local reports. No workflow was rerun and no gate was relaxed. Complete realm execution and both full guest builds remain required.Native caller diagnostic producer — 19 September 2026: Signed
183bcb9e9b4e37ecfab65bd0baa0cde53d02c728adds an explicit diagnostic on the existing authenticated Launchd route, sending no capabilities. It exercises eleven calls covering reservation, full-width generation refusal, missing-scope refusal, retirement and record reuse. Five new adversarial controls cover malformed outcomes, every lost call and independent unexpected-receipt cleanup. Eight strict development/release Rust configurations pass 966 tests each, with eight native builds, strict host/native Clippy, formatting and private rustdoc without warnings. Seven authority precondition/cleanup helpers moved to a focused module with unchanged bodies; all authored code remains below 1,000 lines. All 355 checker controls pass. Six native frame observations validate the 4,300,800-byte workspace but retain incomplete frame proof: runtime/all/diagnostic modes have 97/62/99 unresolved observations under both policies. No complete frame or diagnostic VM acceptance is claimed. Matching Integration scenario validation and original CI are in progress; successful preparation, mediator startup/configuration/seal/client I/O, native toolchain rebuilding and both full OS builds remain required.Tracking and rollout
Dependency adoption frame evidence — 15 September 2026
The unpublished dependency-alignment worktree based on
7f9552abf3507b464921361fb985853525aef12dpasses 957 tests in each default/all-feature and production development/release configuration, formatting, strict host/native Clippy, eight native builds, private rustdoc and 59 checker fixtures. Both actual optimized frame inspections still exit 1 with explicit incomplete source domains and 700/613 unresolved observations. Intake reports contain no top-level issues; the selected disassembler runs successfully. This agrees with the existing incomplete proof documented here and does not establish an overflow, stack safety or a passing complete CI gate. The frame limits and CI requirements remain unchanged. The dependency update is not published or accepted for product-image adoption. An earlier local quiet compile exceeded its inactivity deadline before tests; its cleaned-up failure remains retained, and the longer bounded continuation passed.Dependencies: lib-posixabi#1, posixd#1, posixd#2, posixd#3, lib-cstd#1, dynlinkd#1, integration#5, ttyd#1
Dependencies identify required contracts and closure gates; preparatory inventory/design can proceed in parallel under one owner per edited file. Link bounded implementation issues and their PRs here before claiming acceptance. Use
feature/posix-compat, regular signed commits in the canonical contribution format, and WIP PRs linked to the exact coherent component graph. All cross-repository Cargo/catalog selections and CI helpers use full 40-character lowercase commit hashes, including transitive dependencies; do not substitute branch, tag or implicit HEAD selection.Close criteria only with their own reviewed deliverables and validation evidence. Pending, skipped, cancelled, failed or predecessor-only results remain distinct. Keep main images unchanged until explicit promotion direction; technical completion does not authorize merges, release tags or publication.
Native diagnostic observation — 19 September 2026: the first actual caller VM fails before its required success marker. Exsh exits 0xe5, Rootd exits 0xdc and the unchanged progress watchdog stops QEMU. Integration issue 66 records exact reproduction and retained appliance/log identities. All 169 Integration helpers and four strict Rust configurations pass; this does not establish native execution. Request/error telemetry through the existing stdout route is under validation. No cause, weakened gate or completion credit is inferred.
Original Exsh CI 265 and 266, at
183bcb9e9b4e37ecfab65bd0baa0cde53d02c728, fail the complete frame gate. All 966 Rust tests and 355 checker controls pass. Four actual workspace mappings are complete; the runtime/all analyses retain 101/67 unresolved observations. All four terminal logs are complete and hashed, totaling 316,648 bytes without warnings. The different local counts remain separately retained. No workflow was rerun or cancelled.Changed diagnostic observation — 19 September 2026: signed Exsh
e81f0cf0aed0b5a3360d2ee2dac6d3f656c90d3fpasses all eight strict 967-test configurations, native builds, fmt, host/native Clippy and private rustdoc without warnings. Six native frame observations remain incomplete (97/63/100 runtime/all/diagnostic observations). Its bounded failure output uses existing stdout and identifies request 1, BEGIN_REALM, as InvalidReply. The actual telemetry-only VM retains original Launchd5837873167c5e6ed99045af7052004affb5c28ff, the original authority policy, 120-second hard limit and 45-second progress watchdog. It still fails and all 106 artifacts are retained; serial SHA256520999cc511e72ccb0bcb138c107f52ff629e2e3b21aa4d116ff4ad9aa402000(55,858 bytes). No unchanged retry or successful runtime acceptance is claimed.Source review shows that shells receive private script senders, while the initial realm dispatch recognizes these operations only on the public receiver. A Launchd change is under strict validation to enter the shared realm handler after the existing active-envelope and native-owner proof, preserving original held-reply custody and adding no sender. A matching fixed-server VM is required to establish the correction. Integration issue 66 retains both failures. Original Exsh CI 267 and 268 are under observation.
Signed cleanup refinement — 19 September 2026:
9c0f7ab851d527dd9dd10161d6a98e1fdc14598emakes no stdout IPC after uncertain capability disposal. Reportable failures retain their full correlation and status fields through the existing output route. All eight strict configurations pass 968 tests each, with eight native builds, fmt, strict host/native Clippy, private rustdoc and Markdown without warnings. Six native frame observations retain complete workspace mapping and incomplete runtime/all/diagnostic proof (97/62/99 unresolved observations). Original CI 269 and 270 are running. The previous telemetry CI 267/268 finished with the full frame gate failed: all 967 Rust tests and 355 checker controls pass, four complete logs total 317,004 bytes and contain no warnings; runtime/all proof has 101/68 unresolved observations. No workflow was rerun. A fresh matching VM with the signed Launchd correction remains required for Integration issue 66.Corrected native caller VM — 19 September 2026: signed Integration
9139c6c5fa38c139e92520f6d410626b4cf1e4aaselects Launchdca9e7f534e26023a6c011b5cb9a8e256fd56c2d6, Exsh9c0f7ab851d527dd9dd10161d6a98e1fdc14598eand Docsce8a1538ab2220f1b346e1a051265f58f83f47fc. The actual VM passes all eleven admission calls over the shell's existing private script route: reservation, reads, full-width stale-generation rejection, missing-scope refusal, acknowledged retirement, record reuse and stale-abort rejection. Exactly oneERIX_EXSH:REALM_ADMISSION:VERIFIEDprecedesERIX_ROOTD:INITIAL_EXSH:EXITED_OK. The original 120-second hard limit and 45-second progress watchdog are unchanged; scenario status is 0 and no build warning is present.All 106 actual appliance artifacts and complete logs are retained. The 55,738-byte serial log has SHA256
bbf41401e975cb0b39c6d62ca32f8e612f4f751a505a7dbb113fe1f05c6415f7; the post-VM writable disk has SHA2568f7faf83e8923de675bf5d030458f7bf7e8065dc4fdb95ec98714dfebc5f7938. The earlier packaging checksum is retained separately. Independent review verifies all 73 original component revisions, the packaged diagnostic executable and the signed image's exact 72-byte LCH1 version-3 capacity record (four realm records; native arena 102,400 bytes). All 169 helper commands, twelve route/scenario controls and four strict 320/321-test Rust configurations pass, including native builds, fmt, strict host/native Clippy and private rustdoc; all 394 host streams are warning-free. Both failed predecessor images remain evidence in issue 66.The first BEGIN failed because the shell's private script intake lacked realm dispatch. The correction retains active-envelope and original native-owner checks and original reply custody, without delegating a new sender. Exsh's uncertain-disposal path makes no stdout IPC before terminal failure. Original Integration CI 1675 and 1676 are queued. Successful preparation, mediator configuration/readiness/sealing, client byte I/O, complete source/effect/frame proof, native Rust/LLVM rebuilding and both full EriX builds remain required. This partial lifecycle acceptance adds no whole checklist item.
Original Exsh CI 269/270 remains failed at the complete frame gate: 968 Rust tests and 355 checker controls pass, all four logs are complete (317,264 bytes) without warnings, and runtime/all proof retains 101/67 unresolved observations. Native diagnostic success does not waive that gate.
Next native validation — 19 September 2026: add an opt-in Exsh guarded-preparation diagnostic using the existing realm ABI. Keep the passing eleven-call admission-only scenario separate. The new diagnostic will reserve a record, transfer exactly one SEND-only copy of its explicitly supplied startup cwd to the BEGIN-reserved receipt slot, select
bin/truewithin that initial root scope, require PREPARE/Guarded and READ/Guarded, then require ABORT/Retired and a stale READ/NOT_FOUND. The packaged nativetrueexecutable is an unstarted staging fixture; it does not stand in for a running POSIX mediator.The existing authenticated private Launchd route remains the sole request path. No ordinary start, new endpoint, root capability or implicit namespace is introduced. Launchd must retire its received directory copy after exact resolution; Loaderd must return the original staged child and grant, and Procd must retain the actual returned grant and guarded sender branch before acknowledging Guarded. Abort must retire that exact stage and retained custody. Error telemetry must preserve application refusal codes and stop ordinary output after uncertain receipt disposal. Independent host controls will cover literal operation order, transfer scope/rights, full correlation, missing or malformed acknowledgments, surplus receipts and no continuation after failure. The new actual VM retains the 120-second hard and 45-second progress limits and requires its own unique marker before ordinary shell exit. Full source/effect/frame proof, configured/sealed mediator execution, real client byte I/O, native Rust/LLVM rebuilding and both full EriX builds remain required.
Native guarded preparation — 19 September 2026: signed Integration
78557a6c672ecf426dfe894a01cc4aeec73b5e3cselects signed Exshffe50612889dd58a45a40d04593a4aa3a3ffa512for the separateappliance-disk-image-realm-preparation-positivescenario. The actual VM passes the eleven existing admission calls followed by BEGIN/Reserved, PREPARE/Guarded, READ/Guarded, ABORT/Retired and stale READ/NOT_FOUND. It transfers exactly one SEND-only copy of the explicitly supplied initial cwd to the authenticated reservation and selectsbin/trueinside that scope. This packaged executable remains an unstarted staging fixture. The existing private Launchd route is reused; no new endpoint, root grant or implicit namespace is introduced.Exactly one admission marker and one
ERIX_EXSH:REALM_PREPARATION:VERIFIEDprecede ordinary successful initial-shell exit. The original 120-second hard deadline and 45-second progress watchdog remain unchanged; scenario status is zero and build warnings are absent. The separate admission-only scenario is preserved. All 106 actual appliance artifacts and complete logs are retained. Serial SHA256 is7ef35833c2d88abcd093c8813791e11cea0d34edb2e29b8686df6996e2bc32ff(55,776 bytes); post-VM writable disk SHA256 is3439d0750ea456ceb8d9fbb063d6af763b4198a85f0270ae8d22c76c6ff99499. Its earlier packaging checksum is retained separately. Independent artifact review verifies all 73 original component revisions, both diagnostic markers in the actual packaged executable, and the signed image's exact 72-byte LCH1 version-3 configuration with four realm records and a 102,400-byte native arena.All 169 Integration helper commands, seventeen route/scenario controls and four strict 320/321-test Rust configurations pass, including native builds, fmt, strict host/native Clippy and private rustdoc; all 394 host streams are warning-free. The post-validation source delta changes only the two Exsh catalog pins and final documentation status, preserving checked implementation bytes. Exsh passes ten strict 976-test configurations, ten native builds and 355 frame-checker controls without warnings. Eight actual frame observations retain complete workspace mapping but incomplete 97/63/100/100 runtime/all/admission/preparation proof in both policies; the full frame gate remains required.
Original Integration CI 1677 and 1678 are queued. Original Exsh CI 271 and 272 are under observation. Complete typed mediator bootstrap, readiness/configuration/sealing, real client byte I/O, complete source/effect/frame proof, native upstream Rust/LLVM rebuilding and both full EriX build generations remain required. This prerequisite adds no accepted whole checklist item.
Original guarded-preparation CI — 19 September 2026: Exsh run 271 and 272, for signed
ffe50612889dd58a45a40d04593a4aa3a3ffa512, both fail the required complete frame proof. All 976 Rust tests and 355 checker controls pass. Four complete hashed logs total 320,166 bytes without warnings; Markdown passes. Each original workflow reports four complete workspace mappings and incomplete runtime/all frame observations (101/68 unresolved). These actual CI observations are distinct from the local eight-configuration frame observations. The passing guarded-stage VM does not waive this failure. No workflow was rerun or cancelled to obtain acceptance.Manual and dependency validation — 20 September 2026:
Thirty-one additional downstream consumers now have signed dependency-alignment checkpoints, each with four strict unit configurations, four native builds, host/native Clippy, formatting and private rustdoc passing without warnings. All 62 original CI runs pass. Their owning feature issues and WIP PRs retain exact revisions and log evidence. Catalog regression 68 remains open until the remaining Exsh selection and complete original catalog are validated together. Individual repository success is not full service-image acceptance.
Exsh's default development tests pass 976 units. Aggregate release-test compilation and a subsequent explicitly separated library compilation each reached the local unchanged 120-second silence limit before tests ran; both failures remain retained. No release-test success is inferred, no compiler setting or deadline was relaxed, and independent configurations are being collected without rerunning failed commands unchanged. The complete source/effect/frame gate also remains open.
Original Integration 1693/1694 also fails with 127 manifest/catalog mismatches each, before full VM execution. Six complete logs total 604,756 bytes, with no warning candidates. Together with 1683–1692 this is twelve retained original failing runs. Earlier full-VM filesystem timeouts remain separately tracked in ext-family issue 20 and FAT32 issue 58.
Canonical acceptance remains 15/460 leaves, 3.48% weighted. Full service lifecycle, terminal accounting, source/effect/frame proof, the 128-page Pagerd gate, profiler attribution, native external Rust/LLVM/runtime rebuilding and both full EriX-in-EriX generations remain required. Static audit currently passes 3,150 authored code files below 1,000 lines, 74 manifests, 259 explicit Git pins, 172 direct missing_docs gates and 92 conventional Rust roots; full semantic authority and documentation review remain open.
Complete original catalog checkpoint — 20 September 2026:
Integration f9681efc30f1c48989def7f0e7db939974a30e27 is signed and pushed in WIP PR 12. Both complete catalogs now pass exact dependency equality against 73/70 clean original selected checkouts and 72/71 manifests; all 143 selected signatures verify. The original Integration library pin is retained independently of the catalog commit, avoiding a circular source reference. Twenty dependency-policy and 46 immutable-source tests, both native scenario policies, Markdown and whitespace pass. The unchanged orchestration crate retains its verified four 320/321-unit configurations, four native builds and strict Clippy/rustdoc evidence. Corrected-source original CI 1695/1696 is running; bug 68 remains open pending that observation and full consumer acceptance remains separate.
The executed inputs for both first-attempt native VM passes remain exact: 27 new ordinary CPL3 grant-right controls, every earlier lifetime/owned-invocation assertion, original 60-second bounds, zero build warnings and empty QEMU stderr. Both packaged kernels match retained original artifacts and all fifteen original source signatures verify. The final post-VM changes only select the full catalogs and reconcile documentation.
All 31 further fully validated consumer checkpoints pass four strict unit/native configurations and all 62 original CI runs; 124 complete logs total 3,041,213 bytes with no warning candidates. Their owning feature issues and WIP PRs preserve exact source and CI evidence. The full manual and regenerated IPC references are published in Docs WIP PR 4; its 45 tests, 2,429 pages, 448,913 word bounds and eleven changed-page reviews pass, as do original Docs CI 991/992 with zero final warnings.
Exsh dbc958bcdaa557a461e9308a31d23d3b8c189296 in WIP PR 3 is explicitly an incomplete-validation dependency checkpoint. Both development configurations pass 976 units, four native builds and strict Clippy/docs configurations pass, and all 355 checker tests pass. Three local release-unit compilation attempts reached the unchanged 120-second silence bound before tests ran. Four local frame checks return 1 with complete workspace mapping and 97/63 unresolved routes. Original CI 273/274 likewise passes 976 units and 355 checker tests, then fails the full frame/source gate with 101/68 unresolved observations. Four complete CI logs total 319,871 bytes with zero warning candidates. These local and CI artifacts are distinct; no frame or release-unit acceptance, relaxed deadline or unchanged retry is claimed.
Canonical acceptance remains 15/460 leaves, 3.48% weighted. The full in-EriX builds and native external Rust/LLVM/runtime rebuild remain unproven. Full consumer lifecycle, terminal accounting, source/effect/frame proof, the 128-page Pagerd gate and profiler attribution remain required; no canonical leaf closes at this checkpoint.
Original terminal-accounting graph validation — 21 September 2026:
Signed 0d5d5ad9aff082ca75ec79dbc9c29d73f799d8ed adopts the original shared terminal-observation, exact-acknowledgement and final-CPU dependencies. Both development configurations pass 976 Rust tests; all four host/native Clippy, warning-denied host/native build, applicable doctest and private-rustdoc selections pass. All 355 checker controls pass. The shell implementation and release optimization/LTO policy are unchanged.
The new graph independently retains two release unit-test compilation failures:
cargo test --locked --offline --release --all-targetsstops at 126.117857 seconds andcargo test --locked --offline --all-features --release --all-targetsat 120.024146 seconds. Both reach the existing 120-second silence bound within the 600-second hard bound; the child exits on signal 15, the owner reports status 124, and cleanup succeeds. No release unit test executes. These are new original-graph observations in compiler regression 9, with all prior failures retained. The cause needs an actual compiler profile; no optimization, LTO or deadline setting was relaxed.Actual runtime and all-feature PIC artifacts are checked in both deployment profiles using the maintained frame configuration. All four reports return incomplete proof (exit 1), with 97 unresolved routes for runtime and 63 for all features. Workspace mapping passes separately. The original ELF and packaged artifact digests, selected tool/helper identities and failed reports remain retained. Frame regression 4 stays open. Original CI 275/276 is being observed without restart.
The WIP PR awards no complete runtime or self-hosting acceptance. Actual service CPU/profiler VMs, complete authority/source/effect/frame proof, native external Rust/LLVM/runtime rebuilding and both full EriX guest build generations remain required in Phase 6 completion.
Original terminal-graph CI classification — 21 September 2026:
Signed
0d5d5ad9aff082ca75ec79dbc9c29d73f799d8edreaches actual analysis in both original CI 275/276. Each passes 976 unit tests and 355 checker controls before the required frame gate fails. Each run retains four incomplete reports: 101 unresolved runtime observations in both profiles and 68 all-feature observations in both profiles. All four workspace mappings pass separately. These CI artifact observations differ from local 97/63 results and are not interchangeable proof.All four terminal logs are complete and hash-verified (319,902 bytes), with zero warnings. The disassembler intake correction reaches the real proof boundary; tool-selection issue 5 is resolved. Complete frame issue 4 and local release compiler issue 9 remain open. No workflow restart, bound change or conversion of incomplete evidence to a pass occurred.
[FEATURE] [P12] Complete native shell/build utilities and provide help and offline manual pagesto [FEATURE] Complete native shell/build utilities and provide help and offline manual pages