Overview of the Synedre OS Agentic Harness

Agentic Harness Overview

The harness is the central component of Synedre OS that transforms every incoming request — a received email, a cockpit message, a scheduled trigger — into a concrete, deployed action: committed code, a drafted reply, an updated website. It operates with no business state outside the database.

Three Structural Principles

• Database as single source of truth. The PostgreSQL database centralises all business entities: VPS instances, clients, projects, agents, scars, runs. Documentation files carry only runbooks and architecture diagrams. No business information lives outside the database.
• Asymmetry between deployment and delivery. Staging deployment is triggered automatically by the system, without human validation. Production delivery is gated by the fleet: each client environment carries a flag authorising or denying automatic shipping; in unattended mode, nightly delivery additionally requires a green QA proof.
• Guardrail-based governance. Hooks intercept before every agent tool action, an antivirus scan is mandatory before any attachment is opened, and a seven-step procedure governs the creation of every project. Any violation is recorded as a priority architecture debt.

The Three Execution Layers

The harness rests on three layers that all share the same database, but through distinct transports.

The Cockpit (Web Interface)

A standalone Nuxt web application constitutes the cockpit /hub/*, accessible on the mothership VPS. It accesses the database via a query adapter that translates certain SQL constructs on the fly into their native PostgreSQL equivalents. The cockpit is split into approximately twenty independent functional modules.

Some translations are automatic (placeholder handling, schema prefixes, insertion conflict handling, date arithmetic). Other specific constructs must be ported manually: conditional updates on insert, last inserted identifier retrieval, string aggregation, list search, date formatting.

The Orchestration Engine (Python Layer)

A collection of Python facades provides full orchestration: classification of incoming requests by the Atlas engine, automaton execution, memory management, audits, email, and deployment. Database access is handled by executing SQL commands inside the database container.

Scripts and Scheduling (Shell/Node Layer)

Shell and Node scripts handle deployment wrappers, launching agents as interactive subprocesses, attachment extraction, backups, and end-to-end tests. Scheduling of virtually all automatons relies on the system crontab — the scheduler built into the web application has been out of service since May 2026.

Topology Diagram

                      REQUEST
   forwarded email ───┐        ┌─── cockpit console chat /hub/runs
   agentic mailbox    │        │    (scoped to mothership or tenant)
                      ▼        ▼
        ┌───────────────────────────────────────────────────────┐
        │  ORCHESTRATION LAYER  (Python facades)                │
        │  Atlas : mailbox poll · classification · spawn        │
        │  Execution : task worker · reflex engine              │
        │  Memory / audits / email / deploy                     │
        │  Claude agent invocation = node-pty launcher          │
        │                      (NEVER in pipeline mode -p)      │
        └──────────────┬───────────────────────┬────────────────┘
       DB access       │                        │ file transfer + service restart
                       ▼                        ▼
        ┌───────────────────────────┐   ┌──────────────────────────┐
        │  DATABASE                 │   │  COCKPIT  (Nuxt app)      │
        │  PostgreSQL               │◄──┤  /hub/*  on the VPS       │
        │  ~270 tables + views      │   │  SQL adapter + modules    │
        └───────────────────────────┘   └──────────────────────────┘
                       ▲
        crontab        │  cron wrapper → Python facades
        (scheduler)    │  shell/Node scripts (backups, scans, deploy)
                       │
        ┌──────────────┴────────────────────────────────────────┐
        │  SCRIPTS LAYER  (deploy, hooks, cron, tests)           │
        │  ./deploy / ./ship → deployment library                │
        │  hooks PreToolUse / Stop / …                           │
        └────────────────────────────────────────────────────────┘

Topological Watch Points

• The database container, the database itself, and the schema carry three distinct names — do not confuse them.
• Several entities exposed as tables are in reality views inherited from the system's progressive migration. Reads go through the view; writes target the underlying physical table.
• The "project" entity is spread across two families of tables originating from two eras of the system; both must be kept consistent.
• The cockpit operates in standalone mode: it no longer extends the public PaaS product core. Access security relies on network infrastructure (tunnel + nginx access guard); a middleware automatically injects a founder session, which satisfies the cockpit-side authentication checks.

Full Request Lifecycle

The canonical path runs from a received email through to a deployed action. Two entry points feed the same engine: the agentic mailbox (forwarded email) and the cockpit's scoped console (Atlas chat).

Step 0 — Ingestion

A forwarded email to the agentic mailbox is detected by the IMAP poll scheduled every minute. It is recorded in the database as two linked entries: the raw message and its processing envelope (status received).

Step 0b — Attachment Scan (P0 Doctrine)

If the message contains attachments, an antivirus and heuristic scan is triggered before any other operation. As long as the verdict is not clean, classification is blocked.

Step 1 — Classification

The Atlas engine submits the message to a language model (via the configured AI provider) and obtains an intent from a strict, controlled enumeration: run, chantier, question, noise, negociation, conseil. Prompt injection is impossible because the enumeration is validated server-side. Classification materialises at most one row in the table corresponding to the detected intent.

Step 2 — Spawn and Orchestration

A process scheduled every five minutes (offset by two minutes to run after classification) retrieves eligible classified requests. An advisory lock in the database prevents any concurrent double-spawn. The Claude agent is launched as an interactive subprocess via a Node/pty launcher with the following parameters:

• No session persistence between spawns — complete isolation, zero context leakage between runs.
• Model: Sonnet.
• Allowed tools: explicit allowlist (optional, e.g. read-only for QA).
• Timeout: 2,400 seconds (configurable at call time; the launcher applies 900 seconds by default).
• Database connection variables and execution context are injected into the subprocess environment.

Documented integration pitfalls:

• The --add-dir argument is varargs: it must appear before all other flags.
• --allowed-tools is also varargs: its value must be followed by a named flag, never by the final prompt.
• The log stream must be closed after the pty exit event is emitted — reversing the order causes silent truncation.
• The stdout drain must complete before process.exit() to avoid truncation on pipe exit.

The agent writes its result to a temporary file and then exits. The post-spawn then orchestrates two branches:

• Code-free branch (run / question / negotiation): an email summary is sent, status actioned.
• Code branch (project): automatic staging deployment, then two-level QA per route:

1. Level 1: HTTP check (status code + regex error patterns).
2. Level 2: headless Playwright navigation (console errors, page errors, screenshot).

401 errors and HTTP/2 errors on staging routes protected by authentication are filtered and ignored. On failure, the spawn is retried up to three times before human escalation.

Step 3 — Project (if intent = chantier)

Project creation follows a seven-step procedure: audit of available agents, drafting the mission brief, recruiting at least two agents. Creation is atomic in the database (project, work, and task tables inserted in a single transaction). Execution then proceeds through the task worker (scheduled per minute) or the reflex engine depending on the nature of the tasks. The status cascade propagates from task to work item and then to the project. A QA team may be recruited if necessary.

The project reaches status test after staging deployment and human review; production delivery (./ship) moves it to done.

Step 4 — Learning (Asynchronous)

Every notable success or failure generates a scar. It feeds the vector memory, suggests a learning rule submitted for human validation in the cockpit, and subsequently integrates into runbooks or behaviour rules — active from the agent's next session onward.

Outbound Email

No message ever goes directly to a client: every outbound email passes through the messaging facade in draft mode, subject to explicit validation before sending. The Atlas agent writes to the system administrator, never to the original requester.

Scheduling

All recurring automatons are driven by the system crontab (the scheduler built into the web application has been out of service since May 2026). Key frequencies are as follows:

Process	Frequency	Role
Agentic mailbox poll (+ scan + classification)	Every minute	Incoming email ingestion
Atlas spawn	Every 5 min (offset by 2 min)	Launching agents on classified requests
Task worker	Every minute	Project task execution
Various recurring automatons	Variable (≈ 69 active entries)	Backups, watchers, audits, maintenance

Glossary of Cardinal Concepts

The following terms form the core vocabulary of Synedre OS. Each concept designates a precise role within the architecture; distinguishing them prevents operational confusion.

Concept	Definition
Atlas	The central orchestrator. Atlas is a persona registered in the database — an agent of the direction family — with no dedicated process running in permanent standby. "Being Atlas" means instantiating a reasoning session with the Atlas cognitive framework, which drives the classification of incoming requests, the launching of delegated agents, and their cascaded orchestration.
Agent	A persona — identity, cognitive framework, and business scope — injected into the context of a language model to execute a task. Synedre OS includes thirty active agents, distributed across four families: direction, framing, execution, and validation. An agent reasons (ReAct cycle); it does not execute a fixed routine.
Automaton	A deterministic script that executes a hardcoded routine. An automaton may invoke a language model, but its control flow remains predefined — it is the conceptual opposite of an agent. Each automaton is registered in a central registry and produces a log entry on every execution.
Project	A structured multi-step mission: the highest-level unit of work. A project is created atomically with at least one job and one task. The hierarchy is: 1 project = N jobs = N tasks.
Job	A granular batch within a project — a phase or sub-objective — with its responsible agent, scope, and exit criteria. Jobs carry status cascades and the unblocking mechanism (bis-job).
Task	The atomic unit assigned to a named agent, with a token consumption estimate and a recommended model.
Run	A scoped execution driven by Atlas over a given perimeter — the mothership or a client VPS — whose context (machine, client, mailbox) is loaded at startup. A run is triggered by an incoming email or from the console. Not to be confused with the execution unit delegated to an agent, which is a distinct object in the data model.
Scar	A recorded lesson derived from a failure (kind = failure) or a reproducible success (kind = victory). Each scar is indexed in a vector database for semantic retrieval, scored by importance, and serves as the entry point of the learning loop.
Orbit	Visual organization ring for agents (1, 2, or 3). Important: the numeric value stored per agent in the database is distinct from the visual rendering in the dashboard, which recomputes the ring from the agent's family (direction → ring 1, framing/execution → ring 2, validation → ring 3). The family is authoritative, not the raw numeric value.
Facade	A single, mandatory entry point for a given capability, making every operation non-bypassable. Facades cover email sending, AI model calls, attachment scanning, and database access, among others. They are generally paired with a pre-execution hook that blocks any direct access.

Other useful terms in the documentation:

• Knock-gate — an upstream filtering device on the hub combining a session cookie and an access token; renders the hub inaccessible without prior authentication.
• Pseudo-TTY — a mandatory system mechanism for programmatically instantiating an agent; invocation as a direct subprocess is prohibited.
• Scan-first — doctrine: no attachment is opened or processed until a clean verdict has been returned by the antivirus engine.
• Bis-job — a job carrying a reference to a blocked (paused) job that it is responsible for unblocking once resolved.

Hard Boundaries (Non-Negotiable)

The following rules are enforced by the entire harness and admit no exceptions. They are summarized here in condensed form; each thematic page details the technical modalities.

• Single database. No business content resides in configuration files or static documents. All structured data is persisted in the central database.
• Secret leak prevention (P0). No secret appears in plaintext in any versioned file. Secrets live in environment files outside the repository and are referenced only by their variable name. Five confidentiality levels are defined.
• Antivirus scan before opening. A received attachment is never opened or forwarded until the detection engine has returned a clean verdict.
• Zero AI-initiated client communication. Every email sent to a client goes through the sending facade with prior human validation (show-before-send). Appointment scheduling goes through a Calendly link; the AI does not compose a direct message without review.
• Seven-step procedure. No project is opened outside the atomic creation procedure with a predefined skeleton. Any project within a client's scope requires at least two distinct agents.
• Continuous-stream commit. No job may be marked complete without the changes being committed. The agent commits; the human operator never enters versioning commands manually. A blocking hook at the end of each session enforces this rule.

Documentation Map

The technical documentation folder is organized into thematic pages. Each page covers a self-contained subsystem.

Page	Subsystem covered
The data layer	Central database, table prefix conventions, relational adaptation layer, Python entity classes, compatibility views, internationalization.
The agentic core	Atlas, agent model, intent classification, instantiation via pseudo-TTY, deployment → QA → email orchestration, orbits, model calibration.
Projects, jobs & tasks	Work unit hierarchy, atomic creation with skeleton, seven-step procedure, multi-session lock, status cascades, bis-job mechanism.
Automatons, crons & runs	Facade catalog, scheduled execution wrapper, automaton registry, distinction between primary run and delegated execution unit, dual scheduler.
The Hub	Supervision application, modules and layers, dashboard pages, API entry points, knock-gate + auto-session authentication, consoles.
Inbox, Atlas Inbox & email	Two IMAP reception pipelines (hub vs Atlas), sending facade, antivirus scan, zero-client-comm doctrine.
Memory & learning	Three-level memory (reference files / knowledge base / vector database), RAG retrieval, scars → suggestions → lessons loop, AI facade.
Deployment & infrastructure	Delivery command asymmetry, configuration-file-based dispatching, centralized build + compressed transfer, mothership self-deployment, client VPS inventory, secret management, commit-before-deploy rule.
Facade & entry point catalog	Inventory of all facades by family, invocation mode (scheduled / CLI / skill / hook / library), listed hooks.
Skills, agents & hooks	Injectable skills, delegatable sub-agents, session hook configuration (pre/post execution), permissions and environment variables.