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
docs(launch): define measurable MSO readiness contract
Rahmancdf2fe6d506c
diff --git a/CLAUDE.md b/CLAUDE.mdindex 0497c49f..764f1889 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -220,6 +220,7 @@ to `resources/` (rr) and drive any project from one manifest:## 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.the current `git rev-parse --show-toplevel` checkout on `main` is the canonical release SSOT.Never create task-specific `mso-*` siblings under `~/projects` and never let twosessions share one worktree, `HEAD`, or index. If parallel work is necessary, use onediff --git a/README.md b/README.mdindex 69431894..f93f47e3 100644--- a/README.md+++ b/README.md@@ -1,7 +1,7 @@<h1 align="center">Manef Shell OS</h1>-<p align="center"><strong>A workspace for your server. A runtime for your agents.</strong></p>-<p align="center">Real terminals, project-aware AI, files and services — in one self-hosted workspace.</p>-<p align="center"><a href="#see-it-work">Demo</a> · <a href="#install-or-update-mso-from-this-repo">Install</a> · <a href="./docs/COGNITIVE-RUNTIME.md">Agent runtime</a> · <a href="./docs/MCP-HOW-TO.md">Use MCP</a> · <a href="./docs/README.md">Docs</a></p>+<p align="center"><strong>A self-hosted control plane for AI agents.</strong></p>+<p align="center">Let agents work across your projects, tools, workflows and infrastructure while keeping context, permissions and execution evidence under your control.</p>+<p align="center"><a href="#see-it-work">Demo</a> · <a href="./docs/QUICKSTART.md">First 10 minutes</a> · <a href="#install-or-update-mso-from-this-repo">Install</a> · <a href="./docs/LAUNCH-READINESS.md">Launch readiness</a> · <a href="./docs/README.md">Docs</a></p><p align="center"><a href="https://github.com/rahmanef63/mso/actions/workflows/ci.yml"><img alt="Tests and build" src="https://github.com/rahmanef63/mso/actions/workflows/ci.yml/badge.svg" /></a> <a href="https://github.com/rahmanef63/mso/actions/workflows/security-alerts.yml"><img alt="Actual open security findings" src="https://github.com/rahmanef63/mso/actions/workflows/security-alerts.yml/badge.svg" /></a></p>## See it workdiff --git a/docs/AGENT-SECURITY.md b/docs/AGENT-SECURITY.mdnew file mode 100644index 00000000..bb7fa8f4--- /dev/null+++ b/docs/AGENT-SECURITY.md@@ -0,0 +1,47 @@+# Agent security launch contract++> **Current-reference security extension.** [`SECURITY-ASSURANCE.md`](./SECURITY-ASSURANCE.md) remains the evidence authority for current scanners and claim boundaries. This document defines agent-specific abuse cases that must be proven before a stronger public launch label.++## Principle++The model is not an authorization boundary. Downstream tools enforce identity, scope, policy, confirmation and resource bounds on every call.++## Tool risk classes++| Class | Examples | Default control |+|---|---|---|+| Read | bounded status, metadata, project inspection | authenticated scope + rate/bounds + redaction |+| Reversible write | draft/config changes with CAS/revision | write scope + stale-write protection + audit + verify |+| High impact | shell, deploy, delete, credential/provider mutation | exec/owner scope + explicit policy/confirmation + audit + post-action verification |+| Critical/external irreversible | broad destructive actions, identity/security boundary changes | dedicated bounded API, fresh confirmation/human review, deny generic fallback |++## Abuse-case matrix++The release security suite must include repeatable failures for:++1. **Direct/indirect prompt injection** — retrieved web/docs/tool output cannot replace system/developer/tool policy.+2. **Tool misuse** — persuasive model text cannot call a tool outside current scope/allowlist.+3. **Privilege escalation** — Viewer/Operator/read/write identities cannot reach Owner/exec authority.+4. **Data exfiltration** — secret-bearing files, credential stores, cookies and private tool results cannot leak through normal output, logs, artifacts or external tool arguments.+5. **Memory poisoning** — untrusted observations retain provenance and cannot silently become high-authority durable instructions.+6. **Cross-agent identity confusion** — Local Agent/A2A/subagent handoff does not widen the originating principal's authority.+7. **Recursive/cascading failure** — depth, retry, runtime, token/cost and workflow bounds stop runaway delegation.+8. **Stale approval/replay** — revision/CAS/one-time confirmation cannot be reused after target state changes.+9. **Confused deputy** — downstream integrations enforce the intended user/connection/resource rather than accepting model-selected identity by implication.+10. **Audit poisoning** — user/model-provided strings cannot forge successful audit/evidence status.++## Memory admission target++Durable memory should distinguish at minimum:++- user-provided vs system-observed vs verified evidence;+- principal/project scope;+- confidence and provenance;+- superseded/retracted state;+- review/admission status for behavior-shaping procedural memory.++Memory may recommend a route. It may never grant permissions, approve deletion, or override a failed authorization check.++## Launch evidence++A 10/10 agent-security claim requires the abuse matrix to run after material changes to models, prompts/instructions, tools, memory, retrieval, workflow policy or provider integrations. Failure is a release blocker for the affected authority class.diff --git a/docs/DISASTER-RECOVERY.md b/docs/DISASTER-RECOVERY.mdnew file mode 100644index 00000000..0d6da3e4--- /dev/null+++ b/docs/DISASTER-RECOVERY.md@@ -0,0 +1,39 @@+# Disaster recovery contract++> **Target and current boundary.** Local server-memory snapshots with checksum/restore rehearsal are useful, but a same-host partial snapshot is not disaster recovery. See [`MEMORY-SAFETY.md`](./MEMORY-SAFETY.md) for current implementation limits.++## Stable launch target++Use a 3-2-1 posture for critical MSO state:++1. **Live copy** on the active installation.+2. **Independent backup copy** that is not the live state tree.+3. **Encrypted offsite/off-host copy** with separate failure domain and access controls.++A backup counts only when its manifest states scope/completeness and a restore drill proves readable content.++## Initial objectives++| Objective | Public-beta target | Stable target |+|---|---:|---:|+| Critical-state RPO | ≤24 h | ≤4 h or explicitly configured |+| Reference-installation RTO | ≤2 h | ≤60 min |+| Restore drill | before beta + after backup format changes | at least monthly and after material storage changes |+| Offsite copy | required | required |+| Encryption | required for credential/private-session-bearing backup | required |++These are product acceptance objectives, not current measured promises.++## Backup set classes++- **Critical identity/config:** enough to reconstruct approved configuration without publishing secrets.+- **Memory/session/workflow evidence:** typed memory, durable session/archive sources, recipes/workflows and project evidence covered by the server-memory backup allowlist.+- **Source/release metadata:** Git remote/source plus exact release/provenance information.+- **External systems:** provider data stays owned by its provider and needs its own backup/export policy; MSO must not pretend a local snapshot covers it.+- **Reinstallable cache/build data:** excluded unless needed for a specific forensic purpose.++## Restore drill++A passing drill starts in an isolated target, verifies backup manifest/checksums, restores without overwriting production, proves representative session/memory/workflow/config reads, records missing/excluded scope, and demonstrates the documented rebuild path to a healthy MSO runtime.++No successful checksum alone proves the snapshot was complete.diff --git a/docs/LAUNCH-QA.md b/docs/LAUNCH-QA.mdnew file mode 100644index 00000000..a5ae483a--- /dev/null+++ b/docs/LAUNCH-QA.md@@ -0,0 +1,88 @@+# MSO launch Q&A++> Concise answers for launch conversations. Keep these aligned with current code and [`LAUNCH-READINESS.md`](./LAUNCH-READINESS.md). Do not upgrade a limitation into a promise.++### 1. What is MSO?++A self-hosted control plane where AI agents can work across your projects, tools, workflows and infrastructure while MSO keeps permissions, context and execution evidence under your control.++### 2. Who is it for?++Developers, technical operators and small trusted teams who run their own projects/servers and want agentic automation without handing the entire control plane to a hosted black box.++### 3. What problem does it solve?++Agent work is usually fragmented across chat history, terminals, repos, MCP tools, workflow products, provider credentials and deployment consoles. MSO gives those surfaces one identity, execution and evidence layer.++### 4. Why is this not just n8n?++n8n is a specialist workflow-automation product. MSO includes server-native workflows, but its primary boundary is broader: project-aware agent sessions, MCP/tools, host operations, memory/evidence and workflow execution share one permission/runtime model. MSO should not try to beat every n8n integration or editor feature.++### 5. Why not just use a coding agent such as Codex or Claude Code?++A coding agent is one reasoning/execution client. MSO is the self-hosted control plane it can connect to: projects, scoped tools, durable sessions, integrations, workflows, host operations and evidence survive beyond one model/client conversation.++### 6. Is MSO actually an operating system?++No. The OS metaphor is the workspace UI. MSO runs on an existing host and does not replace Linux, your VPS provider or the host's security model.++### 7. Does MSO require one AI provider?++No. The architecture is provider-neutral and supports configurable model/provider paths. A particular provider may expose different capabilities, costs or authentication methods.++### 8. What is the difference between Project, Agent, Session and Workflow?++- **Project:** the bounded code/work context.+- **Agent:** a configured actor that can reason and use permitted capabilities.+- **Session:** one durable conversation/execution history for an actor.+- **Workflow:** an explicit reusable execution graph/process.++Memory stores reusable knowledge/evidence; Organization maps people/agent seats and routing, rather than replacing those four concepts.++### 9. What does MSO remember?++MSO can preserve durable sessions, project memory, typed agent memory, workflow/recipe evidence and related knowledge. Retention and retrieval are bounded. “Stored” does not mean “automatically trusted”; provenance, review and poisoning resistance remain part of the memory-safety contract.++### 10. Can an agent delete my server?++Owner/exec authority is intentionally powerful, so MSO must be treated like SSH-equivalent automation for the service user. The product uses role/scope checks, path bounds, audit, confirmations and tool-specific policies, but no model should be treated as a security boundary. High-impact operations require system-enforced mediation and appropriate human approval.++### 11. Where are credentials stored?++Credentials use private server-side configuration/integration stores and private setup flows. They are not supposed to be pasted into prompts or emitted in normal metadata, logs or portable public source.++### 12. Can two agents work at the same time?++Yes, but source-changing tasks must use isolated worktrees and explicit ownership. Canonical `main` is the release/integration surface, not shared scratch space. The launch gate requires this to become tool-enforced, not merely documented.++### 13. What happens if an agent crashes halfway through?++Sessions/workflows keep durable state and evidence so work can be inspected or resumed. Side effects still depend on the external system involved, so idempotency, revision/CAS checks and explicit verification matter.++### 14. Can I see exactly what an agent did?++MSO records bounded workflow/session/action evidence and audits privileged actions. Sensitive values are intentionally redacted or excluded; an audit trail is evidence of actions, not unrestricted transcript/secret storage.++### 15. If my VPS dies, can I recover everything?++Not yet as a stable-product claim. MSO has local memory snapshots and isolated restore verification, but the current launch blocker is complete resumable coverage plus encrypted offsite recovery and a disaster-recovery drill.++### 16. How secure is MSO?++It has substantial first-party security gates and explicit privilege boundaries, but it has not established “100% secure” or third-party-audited status. Current public claims must distinguish tested controls from remaining posture gaps.++### 17. How is a release proven?++The intended chain is exact source SHA → type/lint/test/security checks → isolated production build → mandatory browser journeys → controlled integration/release → exact live SHA and asset/health verification. A push or successful unit test alone is not deployment proof.++### 18. Is MSO production-ready?++For the maintainer's own/internal technical use, many core paths are heavily exercised. The honest public label remains **Public Alpha / Developer Preview** until P0 concurrency, disaster recovery, measured onboarding, agentic-security and operational-SLO gates are satisfied.++### 19. What is the killer demo?++Pick one real project, let an agent inspect it with bounded reads, perform one isolated verified change using the project's tools/workflow, show the execution evidence, then resume/handoff the session. Do not demo every app in the shell.++### 20. Why should I trust a self-hosted project with infrastructure access?++You should not trust it blindly. Evaluate the boundaries and evidence: source is inspectable, credentials stay private, privileged actions are scoped/audited, releases are exact-SHA verified, and current limitations are published. The launch goal is verifiable control, not “trust the AI.”diff --git a/docs/LAUNCH-READINESS.md b/docs/LAUNCH-READINESS.mdnew file mode 100644index 00000000..284ee845--- /dev/null+++ b/docs/LAUNCH-READINESS.md@@ -0,0 +1,72 @@+# MSO launch readiness contract++> **Target, not a marketing score.** “10/10” means every acceptance gate below has current evidence. A planned feature, old screenshot, historical test, or clean-looking UI does not count. Current code/live state wins.++MSO's launch thesis is intentionally narrow:++> **MSO is a self-hosted control plane where AI agents safely work across your projects, tools, workflows, and infrastructure while preserving context and execution evidence.**++The OS metaphor is presentation. The product is the control plane. Anything that does not strengthen that control plane is secondary.++## Product boundary++**Core:** Projects · Agent Sessions · Tools/MCP/Integrations · Workflows · Execution/Evidence.++**Intelligence:** Memory · Learning/Recipes · Organization · Multi-agent/A2A.++**Operations:** Server · Deployment · Backup/Recovery · Security · Observability.++**Not the promise:** a Linux distribution, a VPS provider, a full enterprise IAM/SSO suite, a replacement for every specialist CI/PaaS/automation product, or a guarantee that an autonomous model is safe by itself.++## 20 gates for a defensible 10/10++| # | Dimension | 10/10 acceptance gate | Required evidence | Current launch blocker |+|---|---|---|---|---|+| 1 | Value proposition | One sentence explains category, user, job and trust boundary; 4/5 fresh technical users can repeat it accurately after 30 seconds. | README hero + 5-user comprehension receipt. | No external comprehension test yet. |+| 2 | Problem clarity | Three primary pains and one end-to-end “killer journey” are explicit; every hero feature maps to one pain. | README/launch copy + demo script. | Feature breadth still competes with the story. |+| 3 | Differentiation | Evidence-backed comparison explains when to use MSO vs specialist tools without claiming universal superiority. | Generated COMPARISON + dated sources. | Keep comparison freshness ≤90 days. |+| 4 | Product scope | Core/Intelligence/Operations are the only top-level product tiers; non-goals are published and feature additions require a tier + user job. | This contract + architecture/docs index. | Existing surfaces still expose historical breadth. |+| 5 | First-time UX | Fresh user reaches first verified useful agent action without editing source/config files; median ≤10 min, p90 ≤20 min on supported Linux baseline. | Fresh-machine timed onboarding runs ≥10. | No measured time-to-first-value cohort. |+| 6 | Installation/onboarding | One supported production path is boring and deterministic: install → doctor → onboard → first action; failures name the broken layer and recovery. | Clean Ubuntu install matrix + screenshots/terminal receipts. | Cross-platform support exists but launch path is not yet measured as one funnel. |+| 7 | Information architecture | A user can distinguish Project, Agent, Session, Workflow, Memory and Organization in one sentence each; primary navigation is task/role shaped. | IA glossary + usability test ≥80% first-try routing. | Concept density remains high. |+| 8 | UI consistency | WCAG AA, no horizontal overflow, token/spacing consistency and no dead loading/error states across desktop, phone portrait and phone landscape/tablet. | Mandatory browser E2E + visual regression/axe receipts. | Coverage is strong but not yet one launch-wide visual baseline. |+| 9 | CLI quality | Every core non-visual operation is discoverable from `mso --help`, uses stable exit semantics, structured output where automation needs it, and never silently widens authority. | CLI contract tests + generated CLI docs. | Keep parity and error UX under release gate. |+| 10 | API/MCP architecture | UI/CLI/MCP delegate to the same domain authority; schemas/scopes/audit/concurrency metadata are stable and tested; no hidden “second implementation.” | Tool-contract, dispatch, API and parity tests. | Provider parity still expands over time. |+| 11 | Agent model | Agent/Local Agent/Subagent/A2A boundaries are explicit; each has identity, scope, lifetime, handoff and cancellation semantics; no implicit authority inheritance. | Architecture + isolation/handoff tests. | Mental model still needs launch-level simplification. |+| 12 | Memory / second brain | Memory has provenance, scope, review/admission, supersession/forget semantics, poisoning tests and visible coverage limits. No memory can authorize destructive cleanup. | Memory lifecycle/adversarial suite + UI coverage receipt. | JEV admission and full learning-coverage review remain incomplete. |+| 13 | Backup / recovery | 3-2-1 posture for critical state: production + independent backup + encrypted offsite copy; restore drill proves RPO/RTO; local snapshot is complete or explicitly partial. | Encrypted offsite backup + isolated restore drill. | Current verified backup is local, partial, not offsite. |+| 14 | Security model | Complete mediation in downstream tools, least privilege, tool risk classes, explicit approvals for high-impact actions, prompt-injection/memory-poisoning/exfiltration/privilege abuse tests. | SECURITY-ASSURANCE + agent abuse-case matrix + current alert inventory. | No third-party audit; some agentic threat gates still need dedicated launch evidence. |+| 15 | Concurrency safety | Automated source mutation never leaves canonical `main` as a shared scratchpad: one task = one isolated worktree; release integration occurs only from clean, proven candidates. | Tool-enforced workspace lease + collision tests + protected main/ruleset evidence. | Current incident proved policy is not yet tool-enforced; GitHub rulesets list is empty. |+| 16 | Release engineering | Exact SHA → full verify → isolated production build → browser E2E → integration queue/canary → rollback → exact live SHA/chunk health. Build/release is repeatable and no unique snowflake. | Release receipt per version. | Existing exact-SHA gates are strong; staged/canary policy still needs formal production evidence. |+| 17 | Operational resilience | Published SLIs/SLOs, error-budget/change-freeze policy, disk/memory thresholds, alerting, restore/runbook ownership, and failure-mode drills. | SLO dashboard + alert/fire-drill receipts. | Disk pressure and capacity policy are not yet a complete product SLO. |+| 18 | Documentation | Docs follow Tutorial / How-to / Reference / Explanation separation; one 10-minute tutorial is the canonical first route. | Docs map + link/check-doc gate + user completion test. | Excellent reference depth, but onboarding is still reference-heavy. |+| 19 | Demoability | A reproducible ≤3-minute demo shows one project → agent/tool action → workflow/evidence → resume/handoff without secrets or hidden manual setup. | Recorded demo + script + clean fixture. | Existing demo is broad rather than one launch narrative. |+| 20 | Launch readiness | Public beta only when all P0 gates are green, every known limitation is published, rollback/recovery is proven, and current main/live evidence matches the release claim. Stable label requires sustained SLO + recovery history. | Signed/dated release readiness receipt. | Public Alpha/Developer Preview remains the accurate label today. |++## P0 before public beta++1. **Enforce source concurrency**, not merely document it: isolated task worktrees, canonical-main mutation guard, clean integration authority, remote protection/ruleset/status checks. See [`SOURCE-CONCURRENCY.md`](./SOURCE-CONCURRENCY.md).+2. **Complete disaster recovery**: complete resumable snapshot, encrypted offsite target, restore drill, explicit RPO/RTO. See [`DISASTER-RECOVERY.md`](./DISASTER-RECOVERY.md).+3. **Agentic security launch suite**: prompt injection, tool misuse, privilege escalation, data exfiltration, memory poisoning, recursive/cascading failure and cross-agent identity tests. See [`AGENT-SECURITY.md`](./AGENT-SECURITY.md).+4. **Measured onboarding**: fresh host, fresh user, no maintainer knowledge; record time-to-first-value and every manual intervention.+5. **One killer journey** across README, Product Hunt, demo and onboarding.+6. **SLO + operational policy**: availability/latency/failed-action/disk-pressure SLIs, error budget, change freeze and rollback policy. See [`RELIABILITY.md`](./RELIABILITY.md).++## P1 before “stable”++- Sustained SLO history across releases rather than one green release.+- Recovery drill repeated from offsite backup.+- Provider-native integrations meet one shared UX/AX/DX contract.+- Memory admission/review is live, explainable and adversarially tested.+- Role/task navigation has external usability evidence.+- Human code-review posture or an explicit public solo-maintainer exception remains documented; do not fabricate review evidence.++## Release decision rule++A launch score is **evidence**, not averaging. One red P0 gate blocks the stronger launch label even if nineteen areas are excellent.++Use separate states:++`IMPLEMENTED → TESTED → INTEGRATED → RELEASED → VERIFIED-LIVE → OPERATED → HUMAN-VALIDATED`++Never collapse them into “done.”diff --git a/docs/PRODUCT_HUNT.md b/docs/PRODUCT_HUNT.mdindex 144693fd..744d2f01 100644--- a/docs/PRODUCT_HUNT.md+++ b/docs/PRODUCT_HUNT.md@@ -9,24 +9,19 @@ MSO — Manef Shell OS## Tagline-Manage your Linux server from any browser.+Self-hosted control plane for AI agents## Description-MSO is an open-source, mobile-friendly visual shell for a Linux server you own. It combines-Files, real PTY Terminal, Code with an integrated terminal, live metrics, a safe Service Center,-cached package-update visibility, a remote Camoufox browser, device-scoped roles, media tools,-optional BYOK Alfa AI, and managed Hermes/OpenClaw controls-inside one private browser workspace.+MSO is an open-source, self-hosted control plane for AI agents working across projects, tools, workflows and infrastructure. It combines project-aware agent sessions, scoped MCP/tools, native integrations, server-native workflows, files/terminal/service operations, memory and execution evidence behind one responsive browser/CLI/MCP runtime.++The OS-style interface is the workspace metaphor, not the product boundary. MSO runs on a server you control and keeps provider credentials and privileged operations behind server-side identity, scope and approval rules.## First comment draft-I built MSO because managing a personal Linux server from a phone is still more awkward than-it should be. SSH is powerful, but on mobile I kept jumping between terminal tabs, file-transfer tools, metrics dashboards, docs and AI chat.+I built MSO because useful agent work kept fragmenting across chat history, repositories, terminals, MCP tools, workflow apps, credentials and deployment consoles. I wanted one self-hosted control plane that could keep the project context, tool authority and execution evidence together.-MSO is not a Linux distribution, desktop environment or VPS provider. "OS" is the interface-metaphor: a responsive workspace over a server you already own.+MSO is not a Linux distribution, VPS provider or a claim to replace every specialist automation product. "OS" is the interface metaphor; the product boundary is the agent control plane over infrastructure you already own.It is owner-first, with live Viewer, Operator, and Owner roles assigned per approved device.Owner remains shell-equivalent to the Linux service account; Operator is limited to bounded,diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdnew file mode 100644index 00000000..b1d4b7eb--- /dev/null+++ b/docs/QUICKSTART.md@@ -0,0 +1,61 @@+# First 10 minutes with MSO++> This is the canonical **tutorial**: one path to first value. It deliberately does not explain every feature. For production hosting, use a supported Linux host and keep the raw app loopback-bound behind your chosen protected HTTPS/private-network path.++## Goal++Reach one verified, read-first agent action against a real project, then see the evidence you can resume later.++## 1. Install and diagnose++```bash+curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash+mso doctor+```++Do not continue past an unexpected doctor failure. Fix the named layer first.++## 2. Open MSO++```bash+mso web+```++Approve the device through the supported local/Owner flow if this browser is new. Treat Owner access like SSH-equivalent authority for the MSO service user.++## 3. Connect one model/provider++Open **Settings → Integrations / Models** and configure one supported provider through the private setup flow. Do not paste provider credentials into agent chat.++## 4. Pick one project++Use the Projects/Files surface or the CLI to identify a real project. Start read-only: inspect its status, current branch and recent work before asking an agent to edit anything.++## 5. Run the first safe agent task++From an MCP client or MSO agent, use a request shaped like:++```text+Check this project's current status and explain the highest-value next task.+Do not change files, branches, services, deployments, credentials or external systems.+```++The first success criterion is not “the model answered.” It is that MSO resolved the project, used bounded reads, and produced inspectable execution evidence without widening authority.++## 6. Make one isolated change++For source-changing work, use one task-specific hidden worktree. Never use canonical `main` as a shared agent scratchpad. Inspect the diff and run the relevant tests before integration.++## 7. Verify and resume++Confirm the session/workflow evidence exists and can be resumed. A completed response is not equivalent to a tested, integrated, released or live-verified change.++## Where next++- **How to connect an AI client:** [`MCP-HOW-TO.md`](./MCP-HOW-TO.md)+- **Install/repair/update:** [`INSTALL.md`](./INSTALL.md)+- **Concepts and architecture:** [`ARCHITECTURE.md`](./ARCHITECTURE.md)+- **Security boundaries:** [`SECURITY-ASSURANCE.md`](./SECURITY-ASSURANCE.md)+- **Memory and retention:** [`MEMORY-SAFETY.md`](./MEMORY-SAFETY.md)+- **Launch/stability gates:** [`LAUNCH-READINESS.md`](./LAUNCH-READINESS.md)+- **Exact CLI reference:** [`CLI.md`](./CLI.md)diff --git a/docs/README.md b/docs/README.mdindex c771dac4..5c8f7df3 100644--- a/docs/README.md+++ b/docs/README.md@@ -20,6 +20,13 @@ evidence and review freshness. The repository quality gate runs both automatical| Document | Contract ||---|---|| [`../README.md`](../README.md) | Product overview and quickstart |+| [`QUICKSTART.md`](./QUICKSTART.md) | Canonical first-10-minutes tutorial: install → doctor → provider → project → safe first agent action → evidence |+| [`LAUNCH-READINESS.md`](./LAUNCH-READINESS.md) | 20 measurable product/launch gates, P0/P1 policy and truthful launch-label contract |+| [`LAUNCH-QA.md`](./LAUNCH-QA.md) | Concise launch answers for category, competitors, agent concepts, security, memory, recovery and readiness |+| [`SOURCE-CONCURRENCY.md`](./SOURCE-CONCURRENCY.md) | One-task-one-worktree, canonical integration authority, remote protection and concurrency acceptance tests |+| [`AGENT-SECURITY.md`](./AGENT-SECURITY.md) | Agent-specific threat model, tool risk classes, abuse cases and memory-admission security contract |+| [`DISASTER-RECOVERY.md`](./DISASTER-RECOVERY.md) | 3-2-1 target, RPO/RTO objectives, backup classes and restore-drill acceptance |+| [`RELIABILITY.md`](./RELIABILITY.md) | Initial SLIs/SLO targets, error-budget policy, disk thresholds and release reliability contract || [`ARCHITECTURE.md`](./ARCHITECTURE.md) | Current runtime, shell, role, host, Agent/Local Agent/subagent, MCP and deployment architecture || [`GATEWAY.md`](./GATEWAY.md) | Provider-neutral gateway state, health, ownership, supervisor and deployment contract || [`COGNITIVE-RUNTIME.md`](./COGNITIVE-RUNTIME.md) | Provider-neutral MCP/session/context/tool-routing runtime and benchmark contract |diff --git a/docs/RELIABILITY.md b/docs/RELIABILITY.mdnew file mode 100644index 00000000..2a8db5de--- /dev/null+++ b/docs/RELIABILITY.md@@ -0,0 +1,48 @@+# Reliability and launch SLO contract++> **Targets, not current SLO claims.** The reference installation needs measured history before MSO can claim these objectives are achieved.++## Initial SLIs++Track at least:++- public and loopback `/api/health` success rate and latency;+- authenticated core-route success rate for project/session/tool/workflow reads;+- privileged action success/refusal/error classification;+- deployment success, rollback and exact-live-SHA convergence;+- disk, memory and process saturation;+- backup freshness/completeness/restore-drill age;+- agent/workflow queue age and bounded failure/retry counts.++## SLO targets++For the maintainer reference production used as public evidence:++- **Public-beta availability target:** 99.5% successful health checks per rolling 30 days.+- **Stable availability target:** 99.9% per rolling 30 days, excluding documented planned maintenance only when users can distinguish it.+- **Health latency target:** p95 <500 ms from the selected probe region under normal load.+- **Release convergence:** supported release path reaches exact healthy live SHA or rolls back/fails closed; no ambiguous half-deployed success.+- **Backup freshness:** within the configured RPO and no overdue restore drill.++100% uptime is not the goal. The goal is explicit reliability that controls change velocity.++## Error-budget/change policy++- When the rolling error budget is healthy, normal feature releases may proceed after gates.+- When exhausted, freeze nonessential feature releases and prioritize reliability/security/recovery work until exit criteria are met.+- Security emergency fixes may proceed through an explicitly recorded exception with rollback evidence.++## Capacity policy++Disk pressure is a correctness concern because sessions, evidence, builds and Docker caches compete for the same host.++- **<75%:** normal.+- **75–85%:** warning; forecast growth and identify reclaimable caches.+- **85–90%:** high; freeze nonessential cache growth/build churn and prepare reviewed cleanup/backup action.+- **≥90%:** critical; alert Owner, preserve primary evidence, require previewed category-specific cleanup or capacity expansion. Never use age alone as proof that session/memory evidence is disposable.++Thresholds are initial operator policy and should be calibrated from measured workload.++## Release strategy++Prefer reproducible automated builds, small isolated changes, exact-SHA evidence, staged/canary exposure when practical, and an explicit rollback path. A test pass, push, merge, deployment start and verified-live state are separate events.diff --git a/docs/SOURCE-CONCURRENCY.md b/docs/SOURCE-CONCURRENCY.mdnew file mode 100644index 00000000..18efbe5d--- /dev/null+++ b/docs/SOURCE-CONCURRENCY.md@@ -0,0 +1,50 @@+# Source concurrency and integration contract++> **Launch target.** Repository policy already requires isolated worktrees for parallel source work. Public-beta readiness requires the rule to be enforced by tooling and remote protection, not only by agent instructions.++## Invariant++`main` is the release/integration authority. It is never a shared agent scratchpad.++```text+user request+ → workflow ownership+ → isolated task worktree+ → scoped commit(s)+ → exact-SHA verification+ → integration queue on latest main+ → changed-base verification+ → release+ → live SHA verification+```++## Required behaviour++1. Every source-changing automated workflow owns exactly one isolated hidden worktree.+2. Two active workflows never share a Git index, worktree or branch.+3. A dirty canonical checkout owned by another workflow is a **hard stop**, not an invitation to stash/reset/commit its work.+4. Integration uses a clean latest `main`; candidate ancestry and remote head are revalidated immediately before integration.+5. Candidate verification does not transfer automatically to a changed integration base. Relevant changed-base tests and the release gate run again.+6. Only the integration/release authority advances canonical `main`.+7. A worktree is removed only after unique tracked/untracked work is proven preserved and accounted for.+8. Release evidence records candidate SHA, integrated SHA, deployed SHA and live SHA separately.++## Remote protection target++GitHub is code storage and a remote policy boundary; MSO/Batonly may remain the CI/CD executor. Protect `main` with a ruleset/branch policy that, where account/repository capabilities allow:++- blocks force pushes and branch deletion;+- requires the project's external status checks before integration;+- requires the branch to be current with the integration head or uses a merge queue equivalent;+- restricts direct updates to the designated integration identity;+- keeps bypass narrow and auditable.++As of the 2026-09-26 launch audit, the public GitHub rulesets collection for `rahmanef63/mso` returned empty. Branch-protection detail could not be read through the installed GitHub App because that integration lacks repository administration permission. Do not claim remote protection from that incomplete evidence.++## Acceptance tests for 10/10++- Simultaneous synthetic workflows attempt to mutate the same canonical project; only task-owned worktrees receive writes.+- A workflow with an isolated-worktree classification cannot silently write source into canonical `main`.+- A dirty canonical tree causes integration to fail without mutation.+- Two independently green candidates are replayed against latest main; stale candidate evidence is not reused as release proof.+- Remote policy rejects unauthorized direct/force update of `main`.diff --git a/scripts/launch-readiness-contract.test.ts b/scripts/launch-readiness-contract.test.tsnew file mode 100644index 00000000..814cd537--- /dev/null+++ b/scripts/launch-readiness-contract.test.ts@@ -0,0 +1,45 @@+import { readFileSync } from "node:fs";+import { describe, expect, it } from "vitest";++const read = (file: string) => readFileSync(file, "utf8");++describe("launch narrative and readiness SSOT", () => {+ it("defines exactly twenty measurable launch dimensions and blocks score-by-averaging", () => {+ const doc = read("docs/LAUNCH-READINESS.md");+ const rows = [...doc.matchAll(/^\| (\d{1,2}) \|/gm)].map((match) => Number(match[1]));+ expect(rows).toEqual(Array.from({ length: 20 }, (_, index) => index + 1));+ expect(doc).toContain("Target, not a marketing score");+ expect(doc).toContain("One red P0 gate blocks the stronger launch label");+ expect(doc).toContain("IMPLEMENTED → TESTED → INTEGRATED → RELEASED → VERIFIED-LIVE → OPERATED → HUMAN-VALIDATED");+ });++ it("keeps the product category consistent across README and launch collateral", () => {+ const readme = read("README.md");+ const productHunt = read("docs/PRODUCT_HUNT.md");+ expect(readme).toContain("A self-hosted control plane for AI agents.");+ expect(productHunt).toContain("Self-hosted control plane for AI agents");+ expect(readme).toContain("./docs/QUICKSTART.md");+ expect(readme).toContain("./docs/LAUNCH-READINESS.md");+ });++ it("keeps the first-run tutorial narrow and read-first", () => {+ const quickstart = read("docs/QUICKSTART.md");+ expect(quickstart).toContain("First 10 minutes with MSO");+ expect(quickstart).toContain("Do not change files, branches, services, deployments, credentials or external systems.");+ expect(quickstart).toContain("Never use canonical `main` as a shared agent scratchpad");+ });++ it("states the canonical concurrency boundary for repository agents", () => {+ const rules = read("CLAUDE.md");+ expect(rules).toContain("release/integration surface, not an agent scratchpad");+ expect(rules).toContain("must happen in a task-owned hidden worktree");+ expect(rules).toContain("stop and preserve it rather than stashing, resetting, committing, merging or overwriting");+ });++ it("keeps launch answers honest about recovery and public readiness", () => {+ const qa = read("docs/LAUNCH-QA.md");+ expect(qa).toContain("Not yet as a stable-product claim");+ expect(qa).toContain("Public Alpha / Developer Preview");+ expect(qa).toContain("You should not trust it blindly");+ });+});