Harness Overview

This page sets the frame for the Synedre OS agentic harness: what it is, how its three layers fit around the single database, the full life cycle of a request (from email or chat all the way to deployment), and the glossary of the system's cardinal names. Each subsystem then has its own dedicated page.

What the harness is

The "harness" is the whole apparatus that turns a request — a forwarded email, a message in a hub console, a cron trigger — into an executed and deployed action: committed code, a reply drafted for the Founder, an updated site. All of it with no business state living outside the database.

Three principles give it structure:

• DB-first. The PostgreSQL database is the only source of business truth. The .md files carry only runbooks, architecture diagrams and doctrines. Every reference — VPS, clients, chantiers, agents, scars, runs — lives in a table.
• Ship / deploy asymmetry. ./deploy is run by the intelligence, systematically and without asking (preprod, or an in-place rebuild of the mothership). ./ship is a manual gesture reserved for the Founder (production). The intelligence never types ./ship.
• Governance through safeguards. Coding-agent hooks (before each tool, at session stop…), mandatory antivirus scan before opening any attachment, a single email façade, secret-leak prevention, a seven-step chantier creation procedure. Any violation becomes a P0 architecture debt.

The harness serves a private mothership — the /hub/* cockpit hosted locally on the host machine — distinct from the public PaaS products (CodeMyShop OSS) and the client tenants that live elsewhere in the repository. This page covers only the agentic mothership.

The real topology

Three execution layers all talk to the same PostgreSQL schema, but over different transports:

• Nuxt layer — the standalone Nuxt 4 app (Nitro runtime), the /hub/* cockpit. DB access through a postgres-js pool with an adapter that translates legacy MySQL SQL into PostgreSQL on the fly. Split into about twenty Nuxt layers.
• Python layer (synedre/) — several hundred Python façades (orchestrator orchestration, automates, memory, audits, email, deploy…). DB access through a psql subprocess run inside the PostgreSQL container.
• Scripts layer (bin/) — shell / Node / Python scripts (deploy wrappers, pseudo-TTY agent spawning, attachment extraction, backups, E2E tests), plus the Linux crontab that schedules most of the automates.

                      REQUEST
   forwarded email ──┐        ┌─── chat console /hub/runs
                     │        │    (scoped mothership|tenant)
                     ▼        ▼
        ┌───────────────────────────────────────────────┐
        │  PYTHON LAYER   synedre/*.py                    │
        │  Orchestrator: poll / classify / spawn          │
        │  execution: task worker, ReAct                  │
        │  memory / audits / email / deploy: ac_*.py      │
        │  headless Claude invocation = node-pty          │
        └────────────┬──────────────────────┬─────────────┘
        docker psql  │                       │ copy + pm2/docker
                     ▼                       ▼
        ┌─────────────────────────┐  ┌──────────────────────────┐
        │  POSTGRESQL             │  │  NUXT LAYER  mothership    │
        │  schema vaisseau_mere_ac│◄─┤  cockpit /hub/*            │
        │  ps_ac_* / sy_* / ps_*  │  │  postgres-js + adapter     │
        │  + views                │  │  ~20 layers                │
        └─────────────────────────┘  └──────────────────────────┘
                     ▲
        crontab      │  cron wrapper → ac_*.py
                     │  bin/*.sh + bin/*.mjs (backups, scans, deploy)
                     │
        ┌────────────┴──────────────────────────────────┐
        │  bin/ + scripts/ LAYER (deploy, hooks, cron)   │
        │  ./deploy / ./ship → scripts/deploy/*           │
        │  pre-tool / session-stop hooks                  │
        └─────────────────────────────────────────────────┘

Topology traps to keep in mind from the outset (detailed in the data-layer chapter):

• The PostgreSQL container and the database carry distinct names, and the schema is not public but a dedicated one. Worth keeping in mind for any query.
• Several ps_ac_* tables are in fact views pointing at physical sy_* tables — a legacy of the Strangler Fig migration. You read through the view and write into the physical sy_* table.
• A single "chantier" entity is spread across both prefixes: ps_ac_chantier* tables (legacy) and sy_* tables (cockpit).
• The mothership is standalone: it no longer extends the OSS core. The hub's real security is the infrastructure (SSH tunnel + nginx knock-gate); a middleware auto-injects a Founder session, so the server-side session check always passes.

The full life cycle of a request

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
    An email is forwarded to the agentic mailbox
       │  cron: IMAP poll (search unseen)
       ▼
    INSERT raw message ──1:1──► agentic email (status='received')
       │
(0b) ATTACHMENT SCAN (scan-first doctrine, P0)
       │  ClamAV + heuristics (Mitnick agent)
       │  verdict ≠ clean ⇒ classification BLOCKED
       ▼
(1) CLASSIFY  (LLM via the AI façade, strict enum, anti-injection)
    intent ∈ {run, chantier, question, noise, negotiation, advisory}
       │  materialises at most 1 row: run / question /
       │  negotiation / advisory  (chantier = downstream drafting)
       ▼
(2) SPAWN + ORCHESTRATION  (cron, after classify)
       │  PG advisory lock (anti double-spawn)
       │  spawn headless Claude via node-pty (stream-json)
       │  system prompt: INVESTIGATION + CODE + commit, full stop
       │  → the agent writes a result then exits
       ▼
    post-spawn orchestration
       ├─ no-code branch (run/question/negotiation) → recap email → 'actioned'
       └─ code branch (chantier) → ./deploy  --preprod
              └─ browser QA per route
                    ├─ OK   → recap email to the Founder → 'actioned'
                    └─ FAIL → re-spawn (max 3 iterations) else escalate
       ▼
(3) CHANTIER (if intent=chantier)
    seven-step procedure: agent audit → mission letter → recruit ≥2 agents
       │  skeleton creation = atomic INSERT
       │     chantier + travail + task(s)
       ▼
    AGENT EXECUTION: delegated execution (worker) or ReAct
       │  cascade task→travail→chantier (max 1 step); QA team if recruited
       ▼
    chantier → 'test' (preprod, Founder review) ── manual ──► ./ship → 'done'
       ▼
(4) LEARNING (asynchronous)
    scar (failure/victory) → pgvector reindex → suggestion →
    human validation → rule → reflex of the next session

On the outbound email side, nothing ever goes to the client directly: everything passes through the send façade (--draft → validation copy to the Founder → --send after explicit approval). The orchestrator writes to the Founder, never to the requester.

Scheduling rests on the Linux crontab: mailbox poll (poll + scan + classify in the same tick), the spawn offset so it runs after classify, the task worker running continuously, plus the fifty or so recurring automates.

Glossary of cardinal names

Name	Definition	Physical backing
Atlas	The orchestrator. An agent registered in the database, with no runtime of its own: "being Atlas" = launching the coding agent with Atlas's system prompt. Drives classification, spawning and post-spawn orchestration.	synedre/ac_atlas_*.py façades + node-pty spawn
agent	A persona (identity + cognitive frame + business scope) injected into a Claude's context to carry out a task. Thirty active agents, in four families: direction, framing, execution, validation. An agent thinks (ReAct); it does not run a fixed routine.	sy_agents table (ps_ac_agents view)
automate	A deterministic script that runs a routine; it may call an LLM but its control flow is hard-coded. The conceptual opposite of an agent.	sy_automates registry; sy_automate_logs journal
chantier	A structured multi-step mission. The highest-level unit of work. Created atomically with ≥1 travail and ≥1 task. Hierarchy: 1 chantier = N travaux = N tasks.	ps_ac_chantier
travail	A granular batch of a chantier (phase / sub-objective), with its owner agent, its scope and its exit criteria. Carries the status cascades and the travail-bis pattern.	ps_ac_chantier_travail
task	The atomic unit assigned to an agent, with a token estimate and a recommended model.	sy_chantier_tache
run	An Atlas-driven scoped execution over a perimeter (mothership or tenant), the perimeter loading the context (VPS, client, mailbox). Triggered by email or chat. Not to be confused with the execution unit delegated to an agent.	sy_run; /hub/runs console
scar (cicatrice)	An engraved lesson from an error (kind='failure') or a reproducible success (kind='victory'). Indexed in pgvector for recall, scored by importance, the entry point of the learning loop.	ps_ac_cicatrices + embeddings
orbit	An organising ring for agents (1/2/3). A twofold notion: the numeric column does not map 1:1 onto the visual rendering, which recomputes the ring from the family (direction=1, framing/execution=2, validation=3). The family is authoritative.	orbite column + group_name
façade	A single mandatory entry point for a capability, which makes an operation non-bypassable (email, AI, attachment scan, DB access). Often paired with a hook that blocks any bypass.	synedre/ac_*.py + pre-tool hooks

Other useful terms: knock-gate (nginx cookie + slug gate upstream of the hub), node-pty (pseudo-TTY required to spawn Claude programmatically), scan-first (no attachment opened before a clean verdict), travail-bis (a travail carrying a resolution link to unblock a paused travail).

The hard borders (non-negotiable)

A condensed reminder of the rules the whole harness enforces:

• Single DB — zero business content in .json / .ts / .md; everything in the dedicated schema.
• Anti-leak P0 — no secret in clear text in any git-tracked file; secrets live outside the repository, referenced by variable name only.
• Antivirus scan before opening — no attachment is opened until a clean verdict is returned.
• Zero client communication by the intelligence — email façade + show-before-send + appointment booking through a dedicated link only.
• Seven-step procedure — no chantier outside skeleton creation, ≥2 distinct agents for a tenant scope.
• Commit-in-flow — no completed work left uncommitted; the intelligence commits, the Founder never types git add / commit; a blocking session-stop hook.