§39 Loams Software Factory and Loams Bot: Embedded Collaboration Apps, A2A Agents and the Closed Loop

Status: Proposed · 2026-10-02. The direction is the owner's, from 2026-10-02:

"write a plan for integrating the UI of Plane, Forgejo, Zulip, GlitchTip, Langfuse 4 for agent tracing and OpenObserve for distributed tracing; for now pick the Slack, Jira, GitHub part [Zulip, Plane, Forgejo first] if you finish it fast; and in our deepseek fork harness in desktop and mobile apps, there should be a single chat interface called Loams bot, where we drive agents of each platform — Plane, Zulip, Forgejo, GlitchTip + product analytics — using A2A. It's a loop, called Loams Software Factory. Make it available as first in our Cloud marketplace page."

Owner rulings later the same day, applied here: (1) the names are Loams Bot and Loams Software Factory in prose, titles and decisions (the quotation above keeps the owner's original words); (2) the desktop app is native, not Tauri: a fork of zeron (github.com/zeronsh/zeron, MIT; Rust on GPUI; "a native control plane for Claude Code, Codex, Cursor, Devin and other coding agents", with a local engine daemon and optional multi-device sync), and Loams Bot on the desktop builds on zeron's agent and session engine. The browser console stays cordis; the phones stay native SwiftUI and Compose. This document cites §37 (amended for a native desktop, D440-series pending) and does not design the desktop shell; it designs what the factory adds to it (§3.4, §13).

This document turns that direction into decisions D460–D479 and open questions Q460–Q479 (staged in docs/design/_pending/39-log.md, not yet in the decision log). Everything beyond the quoted direction (the embed rules, the A2A mapping, the loop's gates, the open/commercial split) is a proposal until the owner confirms it. No code is written by this document. The hosted factory and the marketplace are commercial and are designed in the private loam-platform repository (its doc 05); this document only states the interface between the two.

Numbering. main ends at D459 and Q453 (§38). D460–D479 and Q460–Q479 are a block reserved for this document; renumber at merge if another branch took them. The private repository has its own numbers (PD47 onward).

Markers: (verified) means read on the web on 2026-10-02 at the source in §17. (verify) means the plan that builds it checks it first. (estimate) means computed, not measured. "The harness" is the DeepSeek Harness (MIT) in its desktop and mobile forms (§37 §3); "our fork" is the harness code Loams adapts, per D421, never a copy-and-fork of the whole repository.

1. SummaryCopy Anchor Link

2. Goals and non-goalsCopy Anchor Link

2.1 GoalsCopy Anchor Link

1. One place for a team's loop. Someone using the console, the desktop app or a phone sees chat, issues, code review, errors and analytics without leaving Loams, and without Loams re-implementing any of those apps.
2. One chat that does things. "Why did checkout errors spike?" becomes a triage thread, an issue and a draft fix, each performed by the right agent, each visible, each stoppable.
3. Autonomy with a short leash. Agents act only through their own principals, inside budgets, behind approvals the person signs, with a kill switch and a complete record.
4. Everything traced. Any agent step can be opened in Langfuse (what the model saw and did) and in OpenObserve (how the request moved through the system).
5. Buy, not build (user preference). Plane, Zulip, Forgejo, GlitchTip, OpenPanel, Langfuse and OpenObserve are used as they are; the A2A SDKs are the official ones; the workflow engine is §21's Resonate.
6. Self-hostable by one organisation (D220), with the marketplace as a convenience for those who do not want to run it.

2.2 Non-goalsCopy Anchor Link

• No patched apps, no forks (§4, D476). A feature the apps lack is built as a panel or an agent skill.
• No new chat product. Loams Bot is the harness's chat with a different set of agents; it does not replace Zulip, which is the team's chat.
• No A2A on the phones. Kotlin and Swift have no official SDK, and D420 already gives the apps one protocol (§5.1).
• No autonomous production changes by default (D473). Removing the gates is an organisation policy that an owner sets, recorded in the audit log.
• No second durability layer. The loop's state is §21's; the apps keep their own data.
• No analytics product of our own. The analytics agent reads OpenPanel.
• No mobile Langfuse, OpenObserve or Forgejo diff viewer. Phones get status, summaries and deep links (§3.5).

3. Embedding the appsCopy Anchor Link

3.1 The apps and how Loams reaches themCopy Anchor Link

Langfuse 4. A v4 line exists (verified): Langfuse describes v4 as one open-source platform for tracing, prompts, evaluation and experiments, on a wide, immutable observations table in ClickHouse (ClickHouse acquired Langfuse in January 2026; Langfuse already ran on it); the SDKs are built on OpenTelemetry and the server accepts OTLP traces. The product features were all open-sourced under MIT on 2025-06-04, and what remains commercial in ee/ includes SCIM, audit logs, data-retention policies, project-level RBAC, protected prompt labels, server-side data masking, UI customisation, organisation creators and the organisation- and instance-management APIs (per Langfuse's licence-key documentation; SF5 Task 0 re-reads the list). Server-side masking being commercial is why our masking runs in the collector (§9.1). A third-party page lists v4.38.0 as of 2026-09-17 (verify the current release at SF5 Task 0). It needs Postgres, ClickHouse, Redis and an S3 bucket; RustFS serves the last. Phase 2 runs it as an optional profile.

3.2 Embed or API-driven native panels, per app (D461)Copy Anchor Link

The test for each app: does the loop read or write it, and is the app's UI too deep to rebuild? The loop's objects get native panels, so Loams Bot's cards, the console's overview and the phones can show them without a web view. Everything deeper is the app's own UI, embedded.

3.3 Edge, CSP and X-Frame-Options (D462)Copy Anchor Link

All seven apps send headers that forbid framing by default or by convention (Forgejo's [cors] X_FRAME_OPTIONS defaults to SAMEORIGIN (verified); the others are checked in SF1 Task 2 and SF5 Task 2). The apps stay unmodified, so the edge decides:

The app registry. GetInstance (AP0) gains an apps field, and loams.collab.v1.ListApps returns, per app: id, kind (zulip, plane, forgejo, glitchtip, openpanel, langfuse, openobserve), base_url, embed_url, api_capable, deep_link_templates and phase. A plugin activates only if its app is listed, as rpc.* services activate by api_versions (D424).

3.4 Sessions, isolation and SSO per surfaceCopy Anchor Link

Browser console (cordis). A sandboxed <iframe sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads"> per app (allow-same-origin is the app's own origin, which is not the console's, so it cannot reach the console). The iframe loads <app>/ and the app signs the user in by OIDC against Authentik, silently when the browser has an Authentik session (prompt=none), so there is one visible sign-in. The console never passes a Loams token to a frame. Messages from frames are ignored; the app registry decides what loads.

Desktop (native, a zeron fork; §37 amended, D440-series pending). The desktop app has no web runtime of its own (zeron draws with GPUI and its architecture lists no webview crate; its README mentions a sidebar browser, which SF1 Task 0 inspects), so app UIs arrive in three tiers:

1. Native panels for the objects the factory touches (issues, PRs, threads, errors, tiles, runs, approvals), drawn in GPUI from loams.collab.v1 and loams.factory.v1 through a shared Rust client crate (loams-apps-client, §7). This is the default and the only tier the factory needs.
2. System browser for depth: "Open in browser" on every panel and card opens the app's URL top-level, where the person's Authentik session already exists, so SSO is the browser's and nothing is stored by the desktop app. Opened through the OS URL handler after the URL is checked against the app registry's origins.
3. An in-app sidebar browser, optional and spike-gated. If a wry-based webview can be hosted inside GPUI on macOS, Windows and Linux (the community gpui-wry crate is the candidate (verify)), the app offers a docked pane that loads an app's URL top-level (never in an iframe, so X-Frame-Options does not apply), with one data store per (environment, app), a navigation allowlist (the app's origin and Authentik's; everything else goes to the system browser), no native bridge exposed to the page, and downloads refused. Sign-in happens in the pane once per profile; WebAuthn inside embedded webviews varies by OS (Q461). If the spike fails on an OS, that OS has tiers 1 and 2 only, and the plan is unchanged.

Deep links loams://app/<env>/<app>/<path> are registered by the native app (OS registration is §37's amendment), parsed against the app's allowlist of prefixes, and open the native panel for that object if one exists, else the system browser. A deep link navigates, never acts (D432).

Mobile. No embedded web views for the apps (D461). Links open in the system browser: Custom Tabs on Android, which share the browser's cookies, and the default browser on iOS (UIApplication.open), because SFSafariViewController does not share Safari's cookies (verify, AP3). The user's Authentik session is the browser's, so one sign-in covers every app.

Forward-auth apps. For OpenPanel and OpenObserve the outpost authenticates the person against Authentik, checks membership in the OpenFGA-projected group (factory-viewers), and logs in to the app as one shared service user per app with a read-only role where the app has roles. This is honest about the gap: those two apps have one user, not per-person identity (Q475), so audit of "who looked" is Authentik's log, not the app's.

3.5 What each plugin providesCopy Anchor Link

In the browser console all are cordis plugins in web/plugins/* (D422), first-party, Apache-2.0. The desktop has the same surfaces as native GPUI panels (below the table). New slots are added to §37 §5.5's catalog by SF1 Task 1.

New slots: embed.pane (keyed by app id), app.panel (keyed by <app> or <app>.<panel>; props { environment, query }), bot.message.renderer (keyed by part kind), bot.card (keyed by artifact kind; props { artifact, onAction }), and factory.stage.detail (keyed by stage id).

Desktop native surfaces (D461, D478). Crates in the desktop fork, each a set of GPUI views registered in zeron's shell the way its own conversation and diff panes are: loams-ui-collab (Zulip thread, Plane issue and cycle, Forgejo PR and CI, GlitchTip error and OpenPanel tile panels, and the artifact cards), loams-ui-bot (the cards inside the conversation, the @agent mentions, the Loams Bot sidebar section), loams-ui-factory (runs, run detail with the stage graph, approvals, agents, policy and budgets, the kill switch), and loams-harness-bot (the Harness, §13). They read through loams-apps-client.

Mobile native surfaces (D461, D478). Each is a screen over Connect services, in SwiftUI and Compose: the chat; the run list and run timeline; approvals (existing loams.approvals.v1); the issue list and detail (Plane); the PR list and checks (Forgejo); the error list (GlitchTip, phase 2); analytics tiles (phase 2); an apps screen with deep links into each app's web UI. Phones show data the engine already fetched, cached with freshness timestamps (D437).

3.6 Native panels read through Loams, with OpenFGACopy Anchor Link

A native panel never calls an app directly. It calls loams.collab.v1 (served by loams-collab, §6.3), which:

1. authenticates the user's Loams token and resolves the principal;
2. asks OpenFGA (the one model of §22 §7) which objects of that type the user can read (ListObjects, cached for seconds, as §22 §8.1 does);
3. calls the app's API with a service credential held by the credential broker (never visible to the browser, the phone or the model) and filters the result;
4. returns typed messages (Issue, PullRequest, Thread, CheckRun, ErrorIssue, MetricSeries).

Writes (comment, create, merge) take an idempotency key, go through the same check, and are audited. A write that §8's policy marks as needing approval returns an operation in awaiting_approval, not an error.

4. Licences, and what running each app unmodified means (D476)Copy Anchor Link

Verified 2026-10-02 unless marked; §22 §4 has the earlier matrix and the reasoning, which stands.

Offering the apps hosted (commercial). AGPL and GPL allow running unmodified copies for paying customers when the source remains available; the hosted marketplace listing therefore links each app's source and licence. Whether any app's trademark or commercial terms restrict reselling hosted instances is a legal question we do not answer here (owner action in loam-platform doc 05).

5. Loams Bot and A2ACopy Anchor Link

5.1 A2A as it stands (verified 2026-10-02)Copy Anchor Link

5.2 Shape (D465, D466)Copy Anchor Link

 Loams Desktop (native, zeron fork)   browser console (cordis)    iOS / Android (native)               external A2A or MCP clients
 LoamsBotHarness ─┐                   @loams/plugin-bot ─┐       chat, runs, approvals ─┐            │ A2A 1.0 (JSON-RPC / REST + SSE)
   loams.bot.v1 (Connect, Rust client)  rpc.bot (Connect)     loams.bot.v1 (Connect)        │            │
                    ▼                                        ▼                      ▼
 ┌───────────────────────────────── Loams Bot (loams-bot) ─────────────────────────────────────────┐
 │ chat sessions as durable executions (§21, D24) · harness agent loop (headless) · model: DeepSeek  │
 │ default via the AI gateway · `subagent-a2a` provider on `ctx.subagents` · policy, budgets, trace   │
 │ exposes: loams.bot.v1 (Connect)  +  an A2A server card for "loams-bot" (Q469)                        │
 └──────┬───────────┬────────────┬─────────────┬──────────────────┬────────────────────────────────┘
        │ A2A       │ A2A        │ A2A         │ A2A              │ A2A      (client side: a2a-lf)
        ▼           ▼            ▼             ▼                  ▼
   zulip agent  plane agent  forgejo agent  glitchtip agent  analytics agent     each: its own principal,
   (SF2)        (SF2)        (SF2)          (SF5)            (SF5)               a signed Agent Card
        │           │            │             │                  │
        ▼           ▼            ▼             ▼                  ▼             credential broker injects the
   Zulip API    Plane API    Forgejo API   GlitchTip API    OpenPanel API         app credential per call
        └───────────┴────────────┴──────┬──────┴──────────────────┘
                                         ▼
        OTel GenAI spans ──► collector ──► Langfuse 4 (LLM view)  +  OpenObserve (all signals)  +  Loams (D73)

• Loams Bot's agent loop is the harness's, run headless on the server (the harness's SDK server half) rather than inside each app. It is a durable execution (D24), so a phone that locks or a laptop that sleeps loses nothing, and the same session is visible from every device.
• Delegation is by natural language over A2A. Loams Bot sends the plane agent a Message ("create an issue for the checkout 500s, label factory, link thread X"); the agent chooses its own skills. Loams Bot does not call a Plane tool. The agents' skills are visible to the model as tool descriptions derived from their Agent Cards, so routing is the model's choice; @plane in the composer forces it.
• subagent-a2a is a new provider for the harness's ctx.subagents, patterned on subagent-acp; it maps start, continue and cancel to SendMessage (with taskId), SendMessage follow-up, and CancelTask, and maps the harness's userQuestions and approval services to INPUT_REQUIRED.
• Client protocol. loams.bot.v1 (Connect, AP0 rules: unary and server-streaming, snapshot-then-changes, heartbeat every 15 s, resume cursors, idempotency keys) mirrors the A2A Message, Part, Task and Artifact types by importing A2A's own protobuf where it can (Q467), so a client and an agent speak one vocabulary and A2A conformance is a property of the data, not a translation.
• A2A bindings in our servers. Agents serve HTTP+JSON and JSON-RPC with SSE, on axum (the same server stack as connect-rust, D128). gRPC is not served: it would add tonic beside connect-rust for no client that needs it. Loams Bot's client side uses the same two bindings.

5.3 Task lifecycle, streaming and push (D467)Copy Anchor Link

5.4 Agent cards (D466)Copy Anchor Link

Each agent serves one card, signed by the instance key and carrying the instance JWKS key id. Example, the plane agent (abridged; risk is a Loams extension, URI https://loams.dev/a2a/ext/risk/v1):

{
  "name": "plane-agent",
  "description": "Issues, cycles and modules in this instance's Plane.",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://agents.<domain>/plane/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" },
    { "url": "https://agents.<domain>/plane/a2a/rest", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0" }
  ],
  "capabilities": { "streaming": true, "pushNotifications": true, "extendedAgentCard": true },
  "securitySchemes": { "loams": { "oauth2SecurityScheme": { "flows": { "clientCredentials": {
        "tokenUrl": "https://<gateway>/api/v1/oauth/token",
        "scopes": { "plane:read": "Read issues and cycles", "plane:write": "Create and update issues" } } } } } },
  "securityRequirements": [ { "schemes": { "loams": { "list": ["plane:read"] } } } ],
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    { "id": "issues.search", "name": "Search issues", "description": "Find issues by text, label, state or cycle.",
      "tags": ["read"], "examples": ["open issues labelled factory"] },
    { "id": "issues.create", "name": "Create an issue", "description": "Create an issue, or return the existing one for the same run.",
      "tags": ["write"], "securityRequirements": [ { "schemes": { "loams": { "list": ["plane:write"] } } } ] },
    { "id": "issues.close_bulk", "name": "Close many issues", "description": "Close more than five issues at once (needs an approval).",
      "tags": ["destructive"], "securityRequirements": [ { "schemes": { "loams": { "list": ["plane:write", "plane:destructive"] } } } ] },
    { "id": "cycles.summary", "name": "Summarise a cycle", "description": "Progress, scope and blockers of a cycle.", "tags": ["read"] }
  ],
  "signatures": [ { "protected": "…", "signature": "…" } ]
}

Field names follow the A2A 1.0 protobuf JSON mapping (oauth2SecurityScheme, securityRequirements with a schemes map, a required skill description); SF2 Task 3 validates this example against the pinned a2a.proto and fixes any difference.

The extended card (after authentication) lists the instance's project ids and the principal's own limits. A client verifies the signature against /.well-known/jwks.json before trusting the card; an unsigned or unverified card is refused (SF2 Task 3).

5.5 The five agentsCopy Anchor Link

5.6 MCP against A2A (D471)Copy Anchor Link

6. Identity, tokens and credentials (D469)Copy Anchor Link

6.1 PrincipalsCopy Anchor Link

• Loams Bot is an agent principal (loams-bot) per organisation. It acts for a user: each chat session carries the user's token as the subject and Loams Bot as actor.
• Each platform agent is an agent principal with its own policy (the actions and the projects it may reach) and a 15-minute token cap (§19 §5.1). Suspending one revokes its tokens within the change feed's latency (§19 §5.4).
• App identities. The provisioning saga (§22 §7.3) creates, per agent, an app-native identity: a Zulip bot user, a Plane workspace member with an API key, a Forgejo user with a fine-grained token, a GlitchTip token, an OpenPanel client. They appear in each app as their own named users (loams-plane-agent), so every action in the app is attributable in the app too.

6.2 The token pathCopy Anchor Link

1. The user signs in at Authentik; the gateway issues Loams tokens (§37, amended for a native desktop; RFC 8693 exchange).
2. A chat message reaches Loams Bot with the user's access token.
3. For each A2A call, Loams Bot asks the gateway to exchange that token for one audience-bound to the agent, with scp the intersection of the agent's policy and the user's rights, a top-level sub that is the user, an act claim whose sub is the platform agent (the current actor) nesting act = agent:loams-bot (the prior actor), that is act = { sub: agent:<name>, act: { sub: agent:loams-bot } } (RFC 8693 §4.1), and an aud claim equal to the agent's interface URL (§19 §5.3 defines env as the environment audience; SF2 Task 4 adds aud, §18). Loams Bot is the exchange's client: the user's token is the subject_token, Loams Bot's own token the actor_token. TTL up to 15 minutes. It attenuates only (§19 §5.2 flow 3).
4. The agent verifies the JWT locally (signature, aud, exp, env), as every Loams gateway does, and the Authorizer still decides.
5. For the app call, the agent asks the credential broker for a short-lived call permit (a handle request that presents the agent token; it is not a second token exchange and mints no token); the broker holds the app secret (Dapr secret store, §24), checks OpenFGA, and performs or signs the call. The app secret is never in the agent's memory, the model's context, a trace or a log (§30's secret canary test is extended to the agents, SF2 Task 9).

6.3 Agent-to-agent authenticationCopy Anchor Link

Agent cards declare oauth2 with the gateway as authorization server (§5.4). A2A's mutual-TLS scheme is available for in-cluster hops (Knative with the mesh's mTLS, §38), but the JWT is the contract, because the user chain must travel with the call.

7. Where the code lives (D475, D476)Copy Anchor Link

8. Approvals and human-in-the-loop (D468)Copy Anchor Link

1. Risk is declared by the agent, enforced by Loams. Each skill carries read, write or destructive in its card tags. The org's factory policy (a Live document, versioned, audited) maps (agent, skill, environment) to allow, approve or deny. Defaults: read allow; write allow in non-protected environments, approve in protected ones; destructive approve; prs.merge approve in every environment; deploy approve.
2. The agent cannot skip the gate. approve makes the agent's durable function wait on the approval promise (§21 §6.5); only a settled promise releases it. The server-side check is in the credential broker: a destructive call carries the approval id and the broker verifies it is settled and matches the call's hash. A prompt-injected agent that "decides" not to wait still cannot get the credential.
3. The approval is §37's: loams.approvals.v1, a server-rendered summary, a decision proof signed by the person's device key, the requester and the user an agent acts for unable to approve (Q432), a typed confirmation for destructive ones, 72-hour timeout, no always-allow. Loams Bot shows the approval as a card and opens the approval screen; it never carries the decision.
4. Questions are not approvals. INPUT_REQUIRED for a clarification is answered in chat; Loams Bot may answer a question itself only if the agent marked it answerable_by_orchestrator (for example "which project?" when the thread names one).
5. Prompt-injection posture. Text from apps (issue bodies, chat messages, error messages, PR descriptions) is untrusted data. Agents receive it in data parts tagged untrusted, the harness renders it in a quoted block, and no tool call is chosen only on it without the policy gate. Red-team fixtures are in SF2 Task 9 and SF4 Task 9.

9. Tracing and observability (D470)Copy Anchor Link

9.1 The collectorCopy Anchor Link

One OpenTelemetry Collector (per cluster; loams dev runs without) receives OTLP from every service and has two pipelines:

• traces/llm : a filter processor keeps every span that carries a gen_ai.* attribute or an agent-step attribute (a2a.task_id or resonate.promise_id), and their parents, so each agent step reaches Langfuse even when it made no model call; a masking step removes secret-canary matches and untrusted bodies over 2 KB before export, and the pipeline fails closed if masking cannot run (Langfuse's own server-side masking is an ee/ feature we do not use); exporter otlphttp/langfuse receives only masked spans, at the Langfuse OTLP endpoint with the project's key pair as basic auth over TLS (verify the path and headers, SF5 Task 3).
• traces/all, logs, metrics: a transform processor deletes gen_ai.prompt, gen_ai.completion and gen_ai.*.content attributes; exporter otlphttp/openobserve to /api/<org>/v1/{traces,logs,metrics} with basic auth (verified shape).

A third exporter sends the same stream to Loams's own OTLP ingest (D73, Q43) so the console's run view needs neither tool.

9.2 What content is captured (Q476)Copy Anchor Link

Default: prompts and completions are captured in Langfuse only, in a project per environment, with the collector as the only masking boundary (§9.1: it drops values matching the secret canary's patterns and the untrusted data parts' bodies over 2 KB, and fails closed; Langfuse's own server-side masking is an ee/ feature we do not use); OpenObserve never receives content. Production environments may turn content capture off per org. Either way the console's run view shows the step's summary from factory_events, which holds no model content.

10. The Loams Software Factory loop (D472)Copy Anchor Link

10.1 StagesCopy Anchor Link

        ┌──────────────────────────────────────────────────────────────────────────────────────────┐
        ▼                                                                                          │
 1 intake ──► 2 triage ──► 3 plan ──► 4 fix ──► 5 review ──► 6 deploy ──► 7 observe ──► 8 close ──┘
 signal       Zulip        Plane      Forgejo    approval     GitOps       GlitchTip,    summary,
 dedupe       thread       issue      branch,    (merge)      sync         OpenPanel,    new signal
 severity     + decision              PR, CI                              Langfuse,     if regressed
                                      (loop ≤N)                           OpenObserve

10.2 As a durable workflow (D472)Copy Anchor Link

factory.run is a Resonate function on §21 (Rust SDK in-process, the embedded server). Its shape, in pseudocode that SF4 turns into tests:

fn factory_run(ctx, signal):
    run = ctx.run(open_run, signal)                       # idempotent on signal.fingerprint + generation
    guard = Guard::new(run, policy)                       # budgets, kill switch, cooldown
    guard.check(ctx)?                                     # before every stage and every A2A call: each stage helper below begins with it
    thread = a2a(ctx, "zulip",   open_triage(run, evidence(signal)))
    decision = ctx.promise(triage_decision(run.id), timeout=policy.triage_timeout)   # human or auto
    if decision != Fix { return close(run, Ignored) }
    guard.check(ctx)?
    issue = a2a(ctx, "plane",   create_issue(run, thread))
    let mut ci_green = false          # policy validation requires max_attempts >= 1, so `pr` is always set after the loop
    for attempt in 1..=policy.max_attempts:
        guard.check(ctx)?
        pr = a2a(ctx, "forgejo", propose_patch_and_open_pr(run, issue, attempt, last_ci_log))
        ci = ctx.promise(ci_result(pr.id))               # settled by the Forgejo webhook receiver
        if ci.ok { ci_green = true; break }
    if !ci_green { return fail_safe(ctx, run, pr) }      # draft PR, label factory:needs-human, thread and issue say so, no approval is requested
    guard.check(ctx)?
    approve(ctx, merge_approval(run, pr))                # waits on approvals promise (§21 §6.5)
    guard.check(ctx)?
    deploy = deploy_stage(ctx, run, pr)                  # approval order depends on the mechanism (§10.1 stage 6): GitOps (merge is the deploy) settles both approvals before the merge; a separate deploy step merges first, then asks a deploy approval bound to the merge commit
    guard.check(ctx)?
    verdict = observe(ctx, run, window=policy.observe_window)
    match verdict:
        Resolved      => close(run, Resolved)
        Regressed     => { revert_pr(ctx, run, pr); spawn_next(ctx, run.generation + 1) }
        Inconclusive  => extend_once_then_ask(ctx, run)

• Idempotency. Every a2a(...) call carries a deterministic messageId (promise id of the step); agents dedupe on it; the Forgejo and Plane skills are written as create-if-absent keyed by run id (a Plane issue with external id factory:<run>, a branch named factory/<run>).
• Compensation. A run that is killed, ignored or abandoned before merge closes its PR, deletes its branch, comments on the issue, and posts the outcome in the thread (a saga, §21 §6.3). fail_safe (CI attempts exhausted) is a deliberate human handoff, not a failure to compensate: it keeps the draft PR and its branch, labelled factory:needs-human, and the run ends failed; compensation does not touch it. After merge the compensation is the revert PR, which is itself gated.
• Resumption. A crash resumes the workflow from its last checkpoint; a model call is never paid twice (§21 §6.6).
• Where the loop runs. In the Loams process that holds Resonate for the org (single org: the one embedded server).

11. Safety: budgets, kill switch, loops, audit (D473)Copy Anchor Link

12. The factory run record (D474)Copy Anchor Link

Live table factory_runs (one row per run, updated by the workflow; subscribed by the console and phones through the Live sync API, §20 §7): id, org, env, generation, parent_run, signal { source, fingerprint, title, link }, state (open, waiting, paused, succeeded, failed, killed), stage, stage_state, links { zulip_thread, plane_issue, forgejo_pr, deploy_ref, langfuse_trace_ids[], openobserve_query }, approvals[], budget { limit, spent }, verdict, started_at, updated_at.

Stream factory_events: one CloudEvent per transition (io.loams.dev.factory.run.opened.v1, …stage.completed.v1, …approval.requested.v1, …run.completed.v1, …), idempotent producer (D72), linked into a collection for search (§22 §8.1).

Console pages (@loams/plugin-factory): Runs (filter by state, project, severity; a lifetime-cost column); Run detail (the stage graph, each stage opening its artifacts: the thread, the issue, the PR, the CI log, the deploy, and "open trace in Langfuse" and "open in OpenObserve", which use the embed panes); Approvals (the org's queue); Agents (cards, health, last task, principal state, suspend); Policy and budgets (versioned, approval-gated in protected environments); Kill switch. Mobile has the run list and timeline, the approval screen and a kill button.

13. Loams Bot in the apps (D478)Copy Anchor Link

Desktop (a zeron fork). zeron's engine drives coding agents through a Harness trait (Claude Code as a subprocess over stream-json, Codex over JSON-RPC, a mock; zeron-harness), and its UI (zeron-ui: sidebar, conversation, composer, terminal, diff pane) renders any harness's AgentEvent stream. Loams Bot is a new harness, loams-harness-bot, whose "agent" is a server-side Loams Bot thread: a RunRequest becomes BotService.Send, Watch events become AgentEvents (text deltas; a subagent card per A2A task as a tool call with its state; a user question; an approval request), steering and interrupt become Cancel and follow-up sends, and the session appears in zeron's attention-sorted sidebar beside local coding sessions. The thread is authoritative on the server (a durable execution, SF3); zeron's session doc mirrors it for the UI, so a thread opened on a second device simply Watches again. zeron's own sync backend (Cloudflare Durable Objects, per its architecture notes) is not used: the desktop runs in zeron's Local profile and the Loams instance is the sync (Q468 covers whether the fork keeps zeron's Claude Code and Codex harnesses and how their sessions sync). Artifact cards, @agent mentions and the slash commands are GPUI views in loams-ui-bot; /kill asks for a step-up and confirms; /approvals opens the native approvals view; none decides anything.

What is taken from zeron, and what is not (verified 2026-10-02 from its ARCHITECTURE.md and crate manifests): taken, the Harness trait, the session and transcript model, the UI crates, the theme registry, the local engine daemon and its headed or headless modes, and its mcp crate as a pattern; not taken, its Loro-over-Cloudflare sync, its voice crate, its WebRTC-based preview crate, and its own RPC (zeron-rpc stays between zeron's engine and UI; everything toward Loams is Connect, D420). zeron is MIT; it depends on a forked GPUI (Apache-2.0; "we do not use Zed's GPL crates", per its architecture notes) and Loro (MIT) (licences checked at SF3 Task 0). Its zeron-mobile crate is a UniFFI core for iOS and Android with platform-painted UI; the phones here stay native over connect-swift and connect-kotlin (D433), and that crate is a pattern, not a dependency.

Browser console (cordis). @loams/plugin-bot ports the DeepSeek harness's conversation UI as cordis plugins (ui-conversation, ui-tool, ui-subagent, ui-user-questions, ui-trajectory, ui-input-trigger, ui-commands) over rpc.bot on Connect. The composer has @agent mentions, slash commands (/run, /status, /kill, /approve opens the approval, never decides), links as attachments and the model picker (default: DeepSeek through the AI gateway). Messages render as parts: text, subagent cards (agent, task state, streaming status) and artifact cards (bot.card keyed by kind: issue, PR, error, metric, run, approval, thread). It is a page and a docked overlay (shell.overlay).

Mobile. Native chat in SwiftUI and Compose, modelled on the mobile harness's chat screen (streamed turns, a glyph per tool, expandable tool cards, goal and question docks), over loams.bot.v1 with the binary Connect codec; artifact cards are native views; push opens loams://bot/threads/<id>; transcripts are cached read-only offline; sending needs a connection (no queued sends, D437).

Model and cost. Loams Bot's default model is DeepSeek, through Loams's AI gateway, which meters tokens per principal and exports GenAI spans. A different model is a gateway route (Q468). Managed model costs and managed agents are the commercial part (§14); self-hosters bring their own key.

14. Open source and commercial (D475, D479)Copy Anchor Link

OSS emits business events (io.loams.dev.factory.run.completed.v1 with counts) as any consumer can read; the platform's metering consumes them. This repository never depends on loam-platform.

15. RisksCopy Anchor Link

16. Phase 2: the observability appsCopy Anchor Link

Detailed in plan SF5; the decisions in brief:

• GlitchTip: native error list and detail (/api/0, §3.2), embedded UI behind OIDC, a webhook receiver that creates signals, the glitchtip agent.
• OpenPanel: native tiles through the analytics agent (AGPL, forward-auth for the dashboard embed), baseline and anomaly checks as a scheduled workflow.
• Langfuse 4: the collector pipeline (§9.1); embed panes that open a trace, session or score page by id; the traces card in the run view; Langfuse's own OIDC through Authentik; the ee/ features never used.
• OpenObserve: the collector pipeline; an embed pane at a query pre-filtered by factory.run_id; forward-auth because the open edition has no SSO; the console's own run view does not depend on it.

17. SourcesCopy Anchor Link

• A2A: a2a-protocol.org (the overview, the specification, "What's new in v1.0"); github.com/a2aproject (the specification and SDK repositories, Apache-2.0, including a2a-rs); the Linux Foundation project announcement (2025); community SDKs: JetBrains Koog agents-features-a2a-core, Victory-Apps/a2a-swift. All read 2026-10-02.
• Langfuse: langfuse.com/resources/engineering/clarifications (v4, ClickHouse, OTLP, MIT and ee/), the open-sourcing post of 2025-06-04, third-party release notes for v4.38. Read 2026-10-02; the current release is a SF5 Task 0 check.
• OpenObserve: github.com/openobserve/openobserve (AGPL-3.0, the enterprise feature list, the OTLP path pattern). Read 2026-10-02.
• Forgejo: forgejo.org/docs/latest/admin/config-cheat-sheet/ (X_FRAME_OPTIONS, default SAMEORIGIN). Read 2026-10-02.
• Not found on the web in this pass (so marked verify): Zulip's and Plane's framing headers, Plane CE's API coverage, OpenPanel's read API, Langfuse's OTLP path and headers.
• zeron: github.com/zeronsh/zeron (README, ARCHITECTURE.md, crates/*/Cargo.toml: engine, harness, proto, doc, sync, rpc, ui, mobile, mcp, preview). Read 2026-10-02 through the GitHub API; the sidebar browser's implementation was not found in the architecture notes (SF1 Task 0).
• This repository: §19, §21, §22, §24, §30, §36, §37, §38, docs/open-core.md, the decision log; the DeepSeek harness repositories at ~/Documents/research-clones/deepseek-harness-desktop (packages/client/ui-*, packages/subagent/*, packages/acp, packages/interaction/*) and deepseek-harness-mobile.

18. Contradictions with earlier decisions, and how they are resolvedCopy Anchor Link

19. Open questionsCopy Anchor Link

The questions are Q460–Q479 in docs/design/_pending/39-log.md.