Overview of the Synedre OS agentic harness

Overview — the Synedre OS Agentic Harness

This page is the entry point for the agentic harness documentation. It establishes the framework: what the harness is, how its three layers are organised around a central database, the complete lifecycle of a request (email or chat → classification → project → agents → automations → deployment), and the glossary of core system concepts. Each sub-system has its own dedicated page.

1. What the agentic harness is

The agentic harness is the full mechanism that transforms a request (a forwarded email, a message in a hub console, a cron trigger) into an executed and deployed action (committed code, a prepared reply, an updated site), with no business state stored outside the database.

Three principles structure it:

• Database first. The central PostgreSQL database is the sole source of business truth. Documentation files carry only runbooks, architecture diagrams, and doctrines. Every reference entity (VPS, clients, projects, agents, scars, runs) lives in a table.
• Ship/deploy asymmetry. The ./deploy command is issued by the AI, systematically and without prompting (staging, or live rebuild of the mothership). The ./ship command (production release) is gated by the fleet: a per-client-VPS flag determines whether the AI or the scheduled tick may ship automatically, or whether the operation requires manual validation. Unattended nightly shipping additionally requires a green QA proof.
• Governance through guardrails. Tooling hooks (PreToolUse, Stop, etc.), a mandatory antiviral scan before opening any attachment, a single email façade, a secret-leak protection layer, and a 7-step project-creation procedure. Any violation constitutes a priority architecture debt.

The harness serves a private mothership (the /hub/* cockpit), distinct from public PaaS products (CodeMyShop) and client tenants. This page covers only the agentic mothership.

2. Topology

Three execution layers all communicate with the same database schema, but via different transports:

• The cockpit (standalone Nuxt 4 application, Nitro) — the /hub/* interface. Database access via a dedicated adapter that translates on-the-fly legacy SQL constructs to standard PostgreSQL: positional placeholders, schema prefix on hub tables, insert-conflict handling, interval arithmetic, date aggregation functions, camelCase aliases. Certain more advanced constructs (ON DUPLICATE KEY UPDATE, LAST_INSERT_ID(), GROUP_CONCAT, FIND_IN_SET, DATE_FORMAT, CURDATE()) are not handled automatically and must be ported manually. The application is split into 27 modular layers.
• The Python orchestration layer — over 200 façades covering Atlas orchestration, automations, memory, audits, email management, and deployment. Database access is performed by executing commands inside the database container.
• Shell, Node, and Python scripts (bin/) — deployment wrappers, terminal spawning, attachment extraction, backups, end-to-end tests. The host machine's Linux crontab schedules the majority of automations (the Nitro built-in scheduler has been disabled since May 2026).

                      REQUEST
   forwarded email ──┐        ┌─── /hub/runs console chat
   agentic mailbox   │        │    (scoped mothership | tenant)
                     ▼        ▼
        ┌───────────────────────────────────────────────────────┐
        │  PYTHON LAYER — orchestration, automations, memory     │
        │  Atlas classification, task execution,                 │
        │  email/deploy management, headless Claude invocation   │
        │  via <spawn-bridge> (node-pty, NEVER claude -p)       │
        └──────────────┬───────────────────────┬────────────────┘
     exec container DB │                        │ scp/docker cp + pm2/docker
                       ▼                        ▼
        ┌───────────────────────────┐   ┌──────────────────────────┐
        │  POSTGRESQL (container DB)│   │  COCKPIT — mothership-app │
        │  central database         │◄──┤  /hub/* interface :3000   │
        │  hub tables + sys tables  │   │  postgres-js adapter      │
        │  (~271 tables + 18 views) │   │  27 modular layers        │
        └───────────────────────────┘   └──────────────────────────┘
                       ▲
        Linux crontab  │  <cron-orchestrator> → Python façades
        (Nitro dead)   │  bin/*.sh + bin/*.mjs (backups, scans, deploy)
                       │
        ┌──────────────┴────────────────────────────────────────┐
        │  bin/ + scripts/ LAYER  (deploy, hooks, cron, tests)   │
        │  ./deploy / ./ship → scripts/deploy/ + deploy lib      │
        │  Claude Code hooks: PreToolUse / Stop / …              │
        └─────────────────────────────────────────────────────────┘

Topology points to bear in mind from the outset (detailed on the data layer page):

• The database container name, the database name, and the schema name are three distinct identifiers — do not conflate them. The port exposed on the host machine differs from PostgreSQL's default port.
• Several apparent tables are in fact views — a legacy of the system's incremental migration (Strangler Fig pattern). The rule: read via the view, write to the underlying physical table.
• The "project" entity is spread across two table families: legacy tables and cockpit tables. Both must remain consistent.
• The cockpit is standalone: it no longer extends the CodeMyShop base. Real hub security relies on the infrastructure (SSH tunnel + nginx knock-gate); a middleware automatically injects a founder session, so that session verification always passes on the mothership side.

3. Complete request lifecycle

The canonical path "email → deployed action". Two entry points feed the same orchestration engine: the agentic mailbox poll and the hub's scoped console.

(0) INGESTION
    Alex forwards an email to the agentic mailbox
       │  cron */1  <agentic-mailbox-poll>  (IMAP SEARCH UNSEEN)
       ▼
    INSERT raw email message ──1:1──► Atlas message (status='received')
       │
(0b) ATTACHMENT SCAN (if present — scan-first doctrine, absolute priority)
       │  <attachment-scanner> → ClamAV + heuristics (Mitnick agent)
       │  verdict ≠ clean ⇒ classification BLOCKED
       ▼
(1) CLASSIFICATION  (LLM via AI provider façade, strict enum, anti-injection)
    <atlas-classifier> → intent ∈
       {run, chantier, question, noise, negociation, conseil}
       │  materialises at most 1 row according to intent:
       │  run / question / negociation / conseil
       ▼
(2) SPAWN + ORCHESTRATION  (cron */5 + 120 s delay)
    <spawn-orchestrator>
       │  PostgreSQL advisory lock (anti-double-spawn)
       │  spawn <spawn-bridge> (node-pty, stream-json)
       │    --no-session-persistence  (inter-run isolation)
       │    --model sonnet  --permission-mode bypassPermissions
       │    --allowed-tools <CSV-tools> (optional — e.g. QA read-only)
       │    DB connection environment variables injected
       │    --timeout-sec 2400 (bridge default = 900 s)
       │    ⚠️ arg order: --add-dir BEFORE other flags (varargs)
       │    ⚠️ --allowed-tools varargs: its value must be followed
       │       by a --flag, never by the final prompt
       │    ⚠️ close the log stream AFTER the pty exit event
       │    ⚠️ drain stdout before process.exit() (anti-pipe-truncation)
       │  Atlas system prompt = investigation + code + git commit, period
       │  → Claude writes /tmp/atlas-spawn-result-<ID>.json then exits
       ▼
    orchestrate_post_spawn()
       ├─ no-code branch (run/question/negociation)
       │    → recap email → status='actioned'
       └─ code branch (chantier) → ./deploy <tenant> --preprod
              └─ 2-level QA per route (<post-deploy-qa-module>):
                     L1 HTTP (status + error regex patterns,
                              optional SSH knock-gate bypass)
                     L2 Playwright chromium headless
                              (console_error, page_error, screenshot)
                     Filters: 401 + ERR_HTTP2 ignored on staging
                              protected by basic-auth
                    ├─ OK   → recap email → status='actioned'
                    └─ FAIL → re-spawn (max 3 iterations)
                              otherwise human escalation
       ▼
(3) PROJECT (if intent=chantier, see dedicated page)
    7-step procedure: agent audit → mission brief
       → recruitment ≥ 2 agents → atomic creation in database
       │  INSERT project + workstreams + tasks in single transaction
       ▼
    Agent execution: task worker (cron */1)
       or ReAct loop (reflex engine)
       │  cascade task → workstream → project
       │  QA team if recruited
       ▼
    project → 'test' (staging, review) ── manual ──► ./ship → 'done'
       ▼
(4) LEARNING (asynchronous)
    scar (failure/success) → pgvector re-indexing
       → learned suggestion → human validation /hub
       → rule in memory/ or doctrine → reflex next session

On the outbound email side, nothing is ever sent directly to the client: everything goes through the client email façade (--draft mode → validation copy → --send after explicit approval). Atlas writes to the founder, never directly to the requester.

Scheduling relies on the Linux crontab (the Nitro scheduler is disabled): the agentic mailbox poll at */1 (poll + scan + classification in the same tick), the spawn orchestrator at */5 offset by 120 seconds (to run after classification), the task worker at */1, plus the dozens of active cron entries covering recurring automations, workers, and watchers.

Glossary of cardinal names

Name	Definition
Atlas	The primary orchestrator. An agent registered in the database with no runtime of its own: "being Atlas" means launching a Claude Code session with the Atlas system prompt. Atlas drives intent classification, agent spawning, and post-spawn orchestration.
agent	A persona (identity + cognitive framework + business scope) injected into a Claude context to execute a task. Thirty active agents, distributed across four families: direction, framing, execution, validation. An agent reasons (ReAct pattern) — it does not execute a hard-coded routine.
automaton	A deterministic script that executes a routine; may call an LLM, but its control flow is hard-coded. Conceptual opposite of the agent.
project	A structured multi-step mission. The highest-level unit of work, created atomically with at least one job and one task. Hierarchy: 1 project = N jobs = N tasks.
job	A granular batch within a project (phase or sub-objective), with its owning agent, its scope, and its exit criteria. Carries status cascades and the job-bis pattern (resolution of a paused job).
task	The atomic unit assigned to an agent, with a token estimate and a recommended model.
run	A scoped execution driven by Atlas over a given scope (mothership or tenant), that scope loading the context (VPS, client, mailbox). Triggered by an incoming email or from the console. Distinct from the execution unit delegated to an agent, which is a separate concept.
scar	A recorded lesson derived from an error or a reproducible success. Indexed in a vector database for semantic retrieval, scored by importance — entry point of the learning loop.
orbit	Agent organisation ring (1, 2, or 3). A dual concept: the numeric value stored in the database does not map directly to the visual rendering in the reactor, which recomputes the ring from the agent's functional group (direction = ring 1, framing/execution = ring 2, validation = ring 3). The functional group is the authoritative reference.
facade	A single, mandatory entry point for a capability, making an operation non-bypassable (email sending, AI call, attachment scanning, database access). Often paired with a hook that blocks any bypass attempt.

Other useful terms:

• knock-gate — nginx gate combining a cookie and a slug upstream of the hub, first line of defence before authentication.
• node-pty — mandatory pseudo-TTY for spawning Claude programmatically; direct sub-process invocation is forbidden.
• scan-first — doctrine: no attachment is opened before the antivirus engine returns a clean verdict.
• job-bis — a job holding a reference to a paused job, allowing it to be unblocked once the prerequisite is resolved.

Hard boundaries (non-negotiable)

The following rules are enforced by the entire harness and admit no exception:

• Single database — zero business content in versioned configuration files; all structured data resides exclusively in the database.
• P0 anti-leak — no secret in plaintext in any file tracked by the version control system. Secrets live outside the repository and are referenced solely by their variable name (five exposure levels, detailed on the deployment page).
• Antivirus scan before opening — any attachment remains closed until the clean verdict has been returned (see the inbox & email page).
• Zero AI-to-client communication — the email-sending facade with prior human validation, and appointment booking via Calendly, are the only authorised channels (see the inbox & email page).
• Seven-step procedure — no project may be opened outside the create_with_skeleton procedure; at least two distinct agents are required for a tenant scope (see the projects page).
• Streaming commits — no completed job may remain uncommitted; the AI performs the commit, and the human operator never types the add and commit commands manually. A blocking hook enforces this rule.

Other pages in this dossier

Page	Subsystem covered
The data layer	Single database, table prefixes, MySQL→PostgreSQL compatibility adapter, Python entity classes, compatibility views, internationalisation.
The agentic core	Atlas, agent model, intent classification, spawning via pseudo-TTY, deployment → QA → email orchestration, orbits, calibration.
Projects, jobs & tasks	Project/job/task hierarchy, atomic skeleton creation, seven-step procedure, multi-session lock, status cascades, job-bis.
Automatons, crons & runs	Deterministic facades, cron wrapper, automaton registry, distinction between primary run and agent-delegated unit, dual scheduler.
The Hub	Mothership Nuxt application, modules and layers, dashboard pages, endpoints, knock-gate + auto-session authentication, consoles.
Inbox, Atlas Inbox & email	Two IMAP pipelines (hub vs Atlas), sending facade, antivirus scan, zero-client-comm policy.
Memory & learning	Three-level memory (context files / knowledge base / vector database), RAG retrieval, scars → suggestions → lessons loop, AI facade.
Deployment & infrastructure	./ship / ./deploy asymmetry, YAML dispatcher, build-host + compression, mothership auto-deployment, client VPS inventory, secrets, commit before deployment.
Facade & entry-point catalogue	Facade inventory by family, invocation mode (cron / CLI / skill / hook / library), hook registry.
Skills, agents & hooks	Declarative skills, delegable sub-agents, session hooks (parameters and permissions), injected environment variables.