Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
chore(ci): require agent PR readiness evidence
Abdurrahman Fakhrul7c1182c183d8
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdnew file mode 100644index 00000000..3d92097a--- /dev/null+++ b/.github/pull_request_template.md@@ -0,0 +1,21 @@+## Summary+- Change:+- Risk/rollback:++## Agent validation evidence (required)+- Exact branch / HEAD SHA:+- Targeted regression tests:+- `bun run pr:local`: PASS / FAIL / BLOCKED (evidence):+- `bun run pr:security`: PASS / FAIL / BLOCKED (evidence):+- Missing tooling or environment constraints:++## Remote readiness checklist+- [ ] All required GitHub CI and security jobs pass on the **latest HEAD**.+- [ ] No new unresolved CodeQL/code-scanning security alerts.+- [ ] All review threads resolved after actual fixes.+- [ ] Test, build, security evidence matches the reviewed commit.+- [ ] Deployment not claimed until changes reach `origin/main` and runtime verified.++**Policy:** If any preflight check is incomplete, open or leave this PR as **Draft**.+Never bypass required checks, hide parser failures, or dismiss security findings+to manufacture a green status.diff --git a/AGENTS.md b/AGENTS.mdindex c85023a4..784386f8 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -100,6 +100,36 @@ and official skill `mso-agent-bootstrap`, not by jumping to `exec_run`.- System service actions require exact owner allowlisting and fixed argv. Do not add wildcard units,raw `systemctl` arguments, or package-update/apply buttons to the Viewer/Operator surface.+## Pull request readiness (mandatory for all coding agents)++**A code change is not PR-ready because it compiles or has been committed.**+After targeted tests and a local commit on an isolated worktree:++1. Run `bun run pr:local` and capture the exact HEAD SHA + first failure.+ This reuses the full committed `scripts/gates.sh`: typecheck, lint, coverage,+ architecture/docs/audit, isolated build, and mandatory browser journeys.+2. Run `bun run pr:security` when Docker is available (pinned Semgrep + ShellCheck,+ same arguments/images as CI). **No Docker, failed scan, or incomplete evidence is+ BLOCKED, not PASSED.** Never interpret Semgrep's "0 findings" as success when+ its process exits nonzero; `--strict` also checks parse warnings.+3. If any check fails, fix it and rerun. If an environment prerequisite cannot+ be satisfied, create/leave a **Draft PR**, record the missing evidence, and do+ not assert "ready" or bypass checks. Never use `--no-verify`, `SKIP`, branch+ protection bypass, scanner suppression, or `continue-on-error` to fake green.+4. After opening the draft, verify the exact pushed SHA in GitHub Actions.+ CodeQL/Code scanning, Dependency Review and other remote required checks must+ complete successfully; resolve all actual review threads after fixing their+ underlying issues, then mark the PR ready. CodeQL new alerts require real+ remediation and retesting, not a blanket dismissal.+5. Report a compact evidence table: SHA, local result, security result, remote+ result, failing log URLs, unresolved threads, and merge-readiness. Never+ merge/declare shipped while required checks are red or the PR is a draft.++Run `bun run pr:preflight` to request both local and scanner parity in one+command. The gate exits 2 when required local tools are missing. If security+scanners cannot run locally, CI can provide the missing evidence *after* a+Draft PR; a local-only pass never implies CodeQL approval.+## ShippingRun validation with `umask 077`: security fixtures must create private files/directories, not inherit group-writable shell defaults. On a busy shared host, bound Vitest concurrency with `VITEST_MAX_WORKERS=2` before changing timeout or coverage limits.diff --git a/CLAUDE.md b/CLAUDE.mdindex ff954650..23ff6f40 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -218,6 +218,15 @@ to `resources/` (rr) and drive any project from one manifest:- For browser verification, discover an available authenticated/local or mock-only endpoint fromthe current installation; do not encode an operator hostname or home path into tests.+## Pull request readiness++Follow the cross-agent hard gate in [`AGENTS.md`](./AGENTS.md#pull-request-readiness-mandatory-for-all-coding-agents).+Use `bun run pr:local` before pushing a committed task branch and+`bun run pr:security` for pinned CI scanner parity where Docker is available.+If either is missing/failed, keep the PR in **Draft** and explicitly record the+blocker. CodeQL and review-thread clearance are GitHub-side gates after PR+creation; a local green run cannot supersede them. Never bypass branch rules.+## Rules in force- **One canonical checkout; parallel work only through isolated hidden worktrees.**The canonical `main` checkout is a **release/integration surface, not an agent scratchpad**. Automated source-changing work must happen in a task-owned hidden worktree; if canonical is dirty with another session's work, stop and preserve it rather than stashing, resetting, committing, merging or overwriting on that session's behalf. Only a release/integration step may advance canonical after the candidate and concurrent work are independently preserved and verified.@@ -237,8 +246,9 @@ to `resources/` (rr) and drive any project from one manifest:not hex, mobile-first. Barrel-only cross-slice imports.- `/api/v1` host ops go through `lib/host` (bounds + realpath checks) — never call`fs`/`child_process` straight from a route.-- Solo-dev: push direct to `main` once `bun run verify` is green (typecheck + lint +- test + check + audit). Conventional commits + Claude co-author.+- Autonomous coding agents must use isolated task branches and PR review, never push+ directly to `main`. Human-owned release integration still uses the verified+ `bun run ship` path after review. Conventional commits + Claude co-author.- **The gates live in `scripts/gates.sh`, which IS committed.** `.git/hooks/pre-push`is a one-line shim that execs it; reinstall with `bash scripts/gates.sh --install`.They used to live in the untracked hook itself, which meant a fresh clone had NOdiff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex e07ff546..36920532 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -123,6 +123,12 @@ verb, and `docs/CLI.md` was regenerated from the help text (the same change keepgates passed (100% routing recall, 97.3% schema reduction, deterministic selection). Per the P7 #5 / P8 #6closed-loop rule, a passing corpus is not evidence of a defect, so it reported the observed gate values insteadof inventing a speculative change.+## 2026-10-17: Make PR readiness auditable across MSO coding agents (candidate)++PR #123 showed four distinct blockers: two gateway tests failing during CI coverage, a ShellCheck SC2164 warning, strict Semgrep exiting 3 with zero findings, and two new CodeQL filesystem race alerts. Existing `AGENTS.md` and the pre-push `scripts/gates.sh` offered guidance but could not establish whether another AI surface had run it, and GitHub-only CodeQL cannot be proven before the PR exists.++The candidate adds an explicit agent-facing `scripts/pr-preflight.sh` and Bun commands `pr:local`, `pr:security`, `pr:preflight`. Local mode reuses the checked-in gates and strict audit rather than defining a weaker test suite; security mode reproduces pinned Semgrep/ShellCheck CI checks and fails closed when Docker is missing. A PR template and both agent manuals require exact-commit evidence, Draft state for unavailable checks, required GitHub CodeQL/review-thread clearance before marking ready, and no bypass. Automated contracts pin scanner parity. This is a candidate branch, **not deployed or merged into main**; GitHub-required checks and review resolution remain separate.+## 2026-10-17: Handoff the managed-domain CLI candidate for a new sessionThe owner explicitly requested a committed, pushed draft PR checkpoint and progress record before continuing in a new session. Implementation is preserved on `agent/mso-103047d38625`; the code commit is `da3ce4f69dfcdcb44a26f4522ced653194ec6172`, based on `89d61bb0d73b47047c67e51df9a6ee30351c8c3a`. The task worktree is `~/.cache/mso-worktrees/mso-103047d38625`; canonical remains `~/mso`. Keep the draft separate from release integration until the remaining checks pass.diff --git a/package.json b/package.jsonindex fcc6d3f5..76e5d9f3 100644--- a/package.json+++ b/package.json@@ -17,6 +17,9 @@"check": "node scripts/check-cycles.mjs && node scripts/check-architecture.mjs && node scripts/check-docs.mjs && node scripts/gen-comparison.mjs --check && node scripts/check-contrast.mjs && bun scripts/check-skill-flows.mjs && bun run check:instance-literals && bun run test:ci && bun run parity:nakama && bun run test:parity","audit": "node scripts/audit.mjs","verify": "bun run typecheck && bun run lint && bun run coverage && bun run check && bun run audit",+ "pr:preflight": "bash scripts/pr-preflight.sh --full",+ "pr:local": "bash scripts/pr-preflight.sh --local",+ "pr:security": "bash scripts/pr-preflight.sh --security","security:ultimate": "bash scripts/security-ultimate.sh","e2e": "node scripts/e2e/shell.mjs","e2e:preview": "node scripts/e2e/preview.mjs",diff --git a/scripts/pr-preflight.sh b/scripts/pr-preflight.shnew file mode 100755index 00000000..fa209716--- /dev/null+++ b/scripts/pr-preflight.sh@@ -0,0 +1,78 @@+#!/usr/bin/env bash+# Agent-facing pre-PR gate. Uses the same repository gates and scanner versions as CI.+# Exit 0 = selected LOCAL checks passed; remote CodeQL/reviews are never implied.+set -euo pipefail+umask 077+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"+cd "$ROOT"++usage() {+ cat <<'HELP'+Usage: bash scripts/pr-preflight.sh [--local|--security|--full]+ --local Verify committed code, strict audit, out-of-tree build and E2E.+ --security Reproduce CI Semgrep and ShellCheck scans using pinned Docker images.+ --full Both local and security (default).+Exit: 0 = selected local checks passed; 1 = check failed; 2 = cannot validate.+Never mark a PR ready until its required GitHub checks, CodeQL alerts and review+threads are also cleared. Open a Draft PR if a local check cannot run.+HELP+}+case "${1:---full}" in+ --local) mode=local ;;+ --security) mode=security ;;+ --full) mode=full ;;+ --help|-h) usage; exit 0 ;;+ *) usage >&2; exit 64 ;;+esac+if (($# > 1)); then usage >&2; exit 64; fi++block() { printf 'BLOCKED: %s\n' "$*" >&2; exit 2; }+fail() { printf 'FAILED: %s\n' "$*" >&2; exit 1; }+command -v git >/dev/null 2>&1 || block 'git is required'+command -v bash >/dev/null 2>&1 || block 'bash is required'++branch="$(git symbolic-ref --short -q HEAD)" || block 'detached HEAD; use a task branch'+[[ "$branch" != main && "$branch" != master ]] || block 'work on an isolated task branch, not main'+[[ -z "$(git status --porcelain --untracked-files=normal)" ]] || block 'uncommitted/untracked changes; commit intended changes and re-run'+git diff --check HEAD^ HEAD || fail 'commit contains whitespace errors'+git rev-parse --verify HEAD >/dev/null || block 'no committed HEAD'+printf 'MSO PR preflight | branch=%s | sha=%s | mode=%s\n' "$branch" "$(git rev-parse --short=12 HEAD)" "$mode"++if [[ "$mode" == local || "$mode" == full ]]; then+ command -v bun >/dev/null 2>&1 || block 'bun is required'+ [[ -d node_modules ]] || block 'install dependencies using bun install --frozen-lockfile'+ # This already includes typecheck, lint, coverage, policy checks, dependency+ # audit, the isolated build, and mandatory browser journeys. Never replace it+ # with a shortened "green" command.+ echo '>> Repository-owned pre-push verification'+ bash scripts/gates.sh || fail 'repository gates failed (see first error above)'+ echo '>> Fail-closed CI dependency audit'+ bun run audit:strict || fail 'strict dependency audit failed'+fi++if [[ "$mode" == security || "$mode" == full ]]; then+ command -v docker >/dev/null 2>&1 || block 'Docker unavailable; cannot reproduce CI security scanners'+ docker info >/dev/null 2>&1 || block 'Docker daemon unavailable'+ semgrep_image='semgrep/semgrep@sha256:f1f7b71861c7b28b6e0f661225a2c4f58a484f5d0f182465c6d6b3b22f972ade'+ shellcheck_image='koalaman/shellcheck-alpine@sha256:9955be09ea7f0dbf7ae942ac1f2094355bb30d96fffba0ec09f5432207544002'+ echo '>> Strict Semgrep with pinned CI image'+ docker run --rm -v "$ROOT:/src:ro" "$semgrep_image" \+ semgrep scan --metrics=off --config=p/javascript --config=p/typescript \+ --config=p/owasp-top-ten --strict --error /src \+ || fail 'Semgrep failed, including parser warnings; zero findings is not sufficient'+ echo '>> ShellCheck warning-level scan with pinned CI image'+ # NUL delimiters preserve valid paths with spaces.+ mapfile -d '' -t files < <(git grep -Ilz '^#!.*sh' -- '*.sh' 'bin/*' 'scripts/*' 'claude-skills/*' || true)+ args=()+ for file in "${files[@]}"; do args+=("/src/$file"); done+ if (("${#args[@]}" > 0)); then+ docker run --rm -v "$ROOT:/src:ro" "$shellcheck_image" \+ shellcheck --severity=warning -e SC1090,SC2034 "${args[@]}" \+ || fail 'ShellCheck warnings detected'+ fi+fi++[[ -z "$(git status --porcelain --untracked-files=normal)" ]] || fail 'validation modified tracked/untracked sources; inspect and recommit'+echo "PASS: selected local preflight completed for $(git rev-parse --short=12 HEAD)."+echo 'REMOTE REQUIRED: open Draft PR, inspect all required GitHub checks, CodeQL alerts,'+echo 'and unresolved review threads. Only mark ready once all are clear.'diff --git a/scripts/pr-preflight.test.ts b/scripts/pr-preflight.test.tsnew file mode 100644index 00000000..4e911822--- /dev/null+++ b/scripts/pr-preflight.test.ts@@ -0,0 +1,38 @@+import { readFileSync } from "node:fs";+import { spawnSync } from "node:child_process";+import { describe, expect, it } from "vitest";++const preflight = readFileSync(new URL("./pr-preflight.sh", import.meta.url), "utf8");+const securityCI = readFileSync(new URL("../.github/workflows/security-core.yml", import.meta.url), "utf8");+const securityUltimate = readFileSync(new URL("./security-ultimate.sh", import.meta.url), "utf8");++describe("agent PR preflight", () => {+ it("exposes a documented, non-executing help route", () => {+ const result = spawnSync("bash", ["scripts/pr-preflight.sh", "--help"], { encoding: "utf8" });+ expect(result.status).toBe(0);+ expect(result.stdout).toContain("CodeQL");+ expect(result.stdout).toContain("Draft PR");+ });+ it("rejects unknown switches instead of quietly ignoring them", () => {+ const result = spawnSync("bash", ["scripts/pr-preflight.sh", "--skip-security"], { encoding: "utf8" });+ expect(result.status).toBe(64);+ });+ it("reuses the committed release gate and refuses incomplete evidence", () => {+ expect(preflight).toContain("bash scripts/gates.sh");+ expect(preflight).toContain("bun run audit:strict");+ expect(preflight).toContain("git status --porcelain");+ expect(preflight).toContain("BLOCKED:");+ expect(preflight).toContain("CodeQL");+ expect(preflight).not.toContain("continue-on-error");+ });+ it("keeps shell and SAST scanner digests pinned to the required CI checks", () => {+ for (const name of ["semgrep/semgrep", "koalaman/shellcheck-alpine"]) {+ const image = preflight.match(new RegExp(name.replace("/", "\\/") + "@sha256:[a-f0-9]{64}"))?.[0];+ expect(image).toBeDefined();+ expect(securityCI).toContain(image);+ expect(securityUltimate).toContain(image);+ }+ expect(preflight).toContain("--strict --error /src");+ expect(preflight).toContain("--severity=warning -e SC1090,SC2034");+ });+});