2938 lines
129 KiB
HTML
2938 lines
129 KiB
HTML
<!doctype html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||
<meta
|
||
name="description"
|
||
content="A small, agent-first proposal for strong Orca orchestration primitives."
|
||
/>
|
||
<title>Orca Orchestration: Strong Primitives, Little Magic</title>
|
||
<link rel="stylesheet" href="../src/renderer/src/assets/main.css" />
|
||
<style>
|
||
* {
|
||
box-sizing: border-box;
|
||
}
|
||
|
||
html {
|
||
scroll-behavior: smooth;
|
||
}
|
||
|
||
body {
|
||
min-height: 100vh;
|
||
margin: 0;
|
||
background: var(--background);
|
||
color: var(--foreground);
|
||
font-family: var(--app-font-family);
|
||
font-size: 14px;
|
||
letter-spacing: 0.01em;
|
||
}
|
||
|
||
a {
|
||
color: inherit;
|
||
}
|
||
|
||
button {
|
||
color: inherit;
|
||
font: inherit;
|
||
}
|
||
|
||
code,
|
||
pre {
|
||
font-family: var(--font-mono);
|
||
}
|
||
|
||
code {
|
||
font-size: 0.92em;
|
||
}
|
||
|
||
pre {
|
||
overflow-x: auto;
|
||
margin: 0;
|
||
padding: 16px;
|
||
border: 1px solid var(--border);
|
||
border-radius: calc(var(--radius) * 0.8);
|
||
background: var(--editor-surface);
|
||
font-size: 12px;
|
||
line-height: 1.65;
|
||
}
|
||
|
||
.page-shell {
|
||
display: grid;
|
||
grid-template-columns: 236px minmax(0, 1fr);
|
||
min-height: 100vh;
|
||
}
|
||
|
||
.sidebar {
|
||
position: sticky;
|
||
top: 0;
|
||
height: 100vh;
|
||
overflow-y: auto;
|
||
border-right: 1px solid var(--sidebar-border);
|
||
background: var(--sidebar);
|
||
color: var(--sidebar-foreground);
|
||
}
|
||
|
||
.sidebar-inner {
|
||
display: flex;
|
||
min-height: 100%;
|
||
flex-direction: column;
|
||
padding: 24px 16px;
|
||
}
|
||
|
||
.brand {
|
||
padding: 0 8px 20px;
|
||
}
|
||
|
||
.brand-title {
|
||
margin: 0;
|
||
font-size: 16px;
|
||
font-weight: 700;
|
||
line-height: 1.3;
|
||
}
|
||
|
||
.brand-copy {
|
||
margin: 8px 0 0;
|
||
color: var(--muted-foreground);
|
||
font-size: 12px;
|
||
line-height: 1.5;
|
||
}
|
||
|
||
.eyebrow {
|
||
margin: 0 0 8px;
|
||
color: var(--muted-foreground);
|
||
font-size: 11px;
|
||
font-weight: 600;
|
||
letter-spacing: 0.05em;
|
||
text-transform: uppercase;
|
||
}
|
||
|
||
.nav {
|
||
display: grid;
|
||
gap: 3px;
|
||
}
|
||
|
||
.nav a {
|
||
padding: 8px 10px;
|
||
border-radius: calc(var(--radius) * 0.8);
|
||
color: var(--muted-foreground);
|
||
font-size: 13px;
|
||
text-decoration: none;
|
||
}
|
||
|
||
.nav a:hover,
|
||
.nav a[aria-current='true'] {
|
||
background: var(--sidebar-accent);
|
||
color: var(--sidebar-accent-foreground);
|
||
}
|
||
|
||
.sidebar-footer {
|
||
margin-top: auto;
|
||
padding: 24px 8px 0;
|
||
}
|
||
|
||
.theme-button {
|
||
width: 100%;
|
||
min-height: 32px;
|
||
padding: 6px 10px;
|
||
border: 1px solid var(--border);
|
||
border-radius: calc(var(--radius) * 0.8);
|
||
background: transparent;
|
||
cursor: pointer;
|
||
text-align: left;
|
||
}
|
||
|
||
.theme-button:hover {
|
||
background: var(--accent);
|
||
color: var(--accent-foreground);
|
||
}
|
||
|
||
main {
|
||
min-width: 0;
|
||
}
|
||
|
||
.content {
|
||
width: min(1040px, calc(100% - 64px));
|
||
margin: 0 auto;
|
||
padding: 72px 0 120px;
|
||
}
|
||
|
||
section {
|
||
scroll-margin-top: 24px;
|
||
padding: 46px 0;
|
||
border-bottom: 1px solid var(--border);
|
||
}
|
||
|
||
section:first-child {
|
||
padding-top: 0;
|
||
}
|
||
|
||
section:last-child {
|
||
border-bottom: 0;
|
||
}
|
||
|
||
h1,
|
||
h2,
|
||
h3,
|
||
p {
|
||
margin-top: 0;
|
||
}
|
||
|
||
h1 {
|
||
max-width: 860px;
|
||
margin-bottom: 20px;
|
||
font-size: clamp(34px, 5vw, 58px);
|
||
font-weight: 720;
|
||
letter-spacing: -0.035em;
|
||
line-height: 1.02;
|
||
}
|
||
|
||
h2 {
|
||
margin-bottom: 12px;
|
||
font-size: 25px;
|
||
letter-spacing: -0.02em;
|
||
}
|
||
|
||
h3 {
|
||
margin-bottom: 8px;
|
||
font-size: 15px;
|
||
}
|
||
|
||
p,
|
||
li {
|
||
line-height: 1.65;
|
||
}
|
||
|
||
.lede {
|
||
max-width: 780px;
|
||
margin-bottom: 28px;
|
||
color: var(--muted-foreground);
|
||
font-size: 17px;
|
||
line-height: 1.65;
|
||
}
|
||
|
||
.section-heading {
|
||
max-width: 780px;
|
||
margin-bottom: 28px;
|
||
}
|
||
|
||
.section-heading p:last-child {
|
||
margin-bottom: 0;
|
||
color: var(--muted-foreground);
|
||
}
|
||
|
||
.scope-banner {
|
||
display: grid;
|
||
grid-template-columns: auto 1fr;
|
||
gap: 14px;
|
||
align-items: start;
|
||
margin-top: 30px;
|
||
padding: 18px;
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius);
|
||
background: var(--muted);
|
||
}
|
||
|
||
.scope-mark {
|
||
display: grid;
|
||
width: 32px;
|
||
height: 32px;
|
||
place-items: center;
|
||
border: 1px solid var(--border);
|
||
border-radius: 999px;
|
||
background: var(--background);
|
||
font-weight: 700;
|
||
}
|
||
|
||
.scope-banner strong,
|
||
.scope-banner p {
|
||
display: block;
|
||
}
|
||
|
||
.scope-banner p {
|
||
margin: 4px 0 0;
|
||
color: var(--muted-foreground);
|
||
}
|
||
|
||
.chip-row {
|
||
display: flex;
|
||
flex-wrap: wrap;
|
||
gap: 8px;
|
||
}
|
||
|
||
.chip {
|
||
display: inline-flex;
|
||
align-items: center;
|
||
min-height: 24px;
|
||
padding: 3px 9px;
|
||
border: 1px solid var(--border);
|
||
border-radius: 999px;
|
||
background: var(--muted);
|
||
color: var(--muted-foreground);
|
||
font-size: 11px;
|
||
}
|
||
|
||
.grid-2,
|
||
.grid-3,
|
||
.grid-5 {
|
||
display: grid;
|
||
gap: 14px;
|
||
}
|
||
|
||
.grid-2 {
|
||
grid-template-columns: repeat(2, minmax(0, 1fr));
|
||
}
|
||
|
||
.grid-3 {
|
||
grid-template-columns: repeat(3, minmax(0, 1fr));
|
||
}
|
||
|
||
.grid-5 {
|
||
grid-template-columns: repeat(5, minmax(0, 1fr));
|
||
}
|
||
|
||
.card {
|
||
padding: 18px;
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius);
|
||
background: var(--card);
|
||
color: var(--card-foreground);
|
||
}
|
||
|
||
.card p:last-child,
|
||
.card ul:last-child {
|
||
margin-bottom: 0;
|
||
}
|
||
|
||
.card p {
|
||
color: var(--muted-foreground);
|
||
}
|
||
|
||
.number-card {
|
||
position: relative;
|
||
padding-top: 54px;
|
||
}
|
||
|
||
.number {
|
||
position: absolute;
|
||
top: 16px;
|
||
left: 18px;
|
||
color: var(--muted-foreground);
|
||
font-family: var(--font-mono);
|
||
font-size: 12px;
|
||
}
|
||
|
||
.principle {
|
||
margin: 24px 0 0;
|
||
padding: 18px 20px;
|
||
border-left: 3px solid var(--foreground);
|
||
background: var(--muted);
|
||
font-size: 16px;
|
||
line-height: 1.6;
|
||
}
|
||
|
||
.compare {
|
||
display: grid;
|
||
grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr);
|
||
gap: 14px;
|
||
align-items: stretch;
|
||
}
|
||
|
||
.compare + .compare {
|
||
margin-top: 14px;
|
||
}
|
||
|
||
.compare-arrow {
|
||
align-self: center;
|
||
color: var(--muted-foreground);
|
||
}
|
||
|
||
.table-wrap {
|
||
overflow-x: auto;
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius);
|
||
}
|
||
|
||
table {
|
||
width: 100%;
|
||
border-collapse: collapse;
|
||
background: var(--card);
|
||
}
|
||
|
||
th,
|
||
td {
|
||
padding: 12px 14px;
|
||
border-bottom: 1px solid var(--border);
|
||
text-align: left;
|
||
vertical-align: top;
|
||
line-height: 1.55;
|
||
}
|
||
|
||
th {
|
||
color: var(--muted-foreground);
|
||
font-size: 11px;
|
||
font-weight: 600;
|
||
letter-spacing: 0.05em;
|
||
text-transform: uppercase;
|
||
}
|
||
|
||
tr:last-child td {
|
||
border-bottom: 0;
|
||
}
|
||
|
||
.sequence {
|
||
overflow: hidden;
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius);
|
||
}
|
||
|
||
.sequence-row {
|
||
display: grid;
|
||
grid-template-columns: 1fr 1.2fr 1fr;
|
||
}
|
||
|
||
.sequence-row + .sequence-row {
|
||
border-top: 1px solid var(--border);
|
||
}
|
||
|
||
.sequence-row > div {
|
||
padding: 12px 14px;
|
||
line-height: 1.5;
|
||
}
|
||
|
||
.sequence-row > div + div {
|
||
border-left: 1px solid var(--border);
|
||
}
|
||
|
||
.sequence-head {
|
||
background: var(--muted);
|
||
color: var(--muted-foreground);
|
||
font-size: 11px;
|
||
font-weight: 600;
|
||
letter-spacing: 0.05em;
|
||
text-transform: uppercase;
|
||
}
|
||
|
||
.runtime-step {
|
||
background: color-mix(in srgb, var(--muted) 55%, var(--card));
|
||
}
|
||
|
||
.plain-list {
|
||
margin: 12px 0 0;
|
||
padding-left: 20px;
|
||
}
|
||
|
||
.plain-list li + li {
|
||
margin-top: 6px;
|
||
}
|
||
|
||
.flow {
|
||
display: grid;
|
||
grid-template-columns: repeat(5, minmax(0, 1fr));
|
||
gap: 10px;
|
||
align-items: center;
|
||
}
|
||
|
||
.flow-step {
|
||
min-height: 106px;
|
||
padding: 14px;
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius);
|
||
background: var(--card);
|
||
}
|
||
|
||
.flow-step p {
|
||
margin: 6px 0 0;
|
||
color: var(--muted-foreground);
|
||
font-size: 12px;
|
||
}
|
||
|
||
.roadmap {
|
||
display: grid;
|
||
gap: 0;
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius);
|
||
background: var(--card);
|
||
}
|
||
|
||
.roadmap-item {
|
||
display: grid;
|
||
grid-template-columns: 140px 1fr;
|
||
gap: 18px;
|
||
padding: 18px;
|
||
}
|
||
|
||
.roadmap-item + .roadmap-item {
|
||
border-top: 1px solid var(--border);
|
||
}
|
||
|
||
.roadmap-meta {
|
||
color: var(--muted-foreground);
|
||
font-family: var(--font-mono);
|
||
font-size: 12px;
|
||
}
|
||
|
||
.roadmap-item p {
|
||
margin-bottom: 0;
|
||
color: var(--muted-foreground);
|
||
}
|
||
|
||
details {
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius);
|
||
background: var(--card);
|
||
}
|
||
|
||
details + details {
|
||
margin-top: 10px;
|
||
}
|
||
|
||
summary {
|
||
padding: 14px 16px;
|
||
cursor: pointer;
|
||
font-weight: 600;
|
||
}
|
||
|
||
details > div {
|
||
padding: 0 16px 16px;
|
||
color: var(--muted-foreground);
|
||
line-height: 1.65;
|
||
}
|
||
|
||
.footer-note {
|
||
color: var(--muted-foreground);
|
||
font-size: 12px;
|
||
}
|
||
|
||
@media (max-width: 900px) {
|
||
.page-shell {
|
||
display: block;
|
||
}
|
||
|
||
.sidebar {
|
||
position: static;
|
||
width: 100%;
|
||
height: auto;
|
||
border-right: 0;
|
||
border-bottom: 1px solid var(--sidebar-border);
|
||
}
|
||
|
||
.nav {
|
||
grid-template-columns: repeat(2, minmax(0, 1fr));
|
||
}
|
||
|
||
.sidebar-footer {
|
||
margin-top: 12px;
|
||
padding-top: 0;
|
||
}
|
||
|
||
.content {
|
||
width: min(100% - 36px, 760px);
|
||
padding-top: 48px;
|
||
}
|
||
|
||
.grid-3,
|
||
.grid-5,
|
||
.flow {
|
||
grid-template-columns: 1fr;
|
||
}
|
||
}
|
||
|
||
@media (max-width: 640px) {
|
||
.grid-2,
|
||
.compare,
|
||
.sequence-row,
|
||
.roadmap-item {
|
||
grid-template-columns: 1fr;
|
||
}
|
||
|
||
.compare-arrow {
|
||
transform: rotate(90deg);
|
||
justify-self: center;
|
||
}
|
||
|
||
.sequence-row > div + div {
|
||
border-top: 1px solid var(--border);
|
||
border-left: 0;
|
||
}
|
||
|
||
.nav {
|
||
grid-template-columns: 1fr;
|
||
}
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div class="page-shell">
|
||
<aside class="sidebar">
|
||
<div class="sidebar-inner">
|
||
<div class="brand">
|
||
<p class="eyebrow">Fresh proposal</p>
|
||
<p class="brand-title">Orchestration primitives</p>
|
||
<p class="brand-copy">Strong building blocks for agents, with little hidden policy.</p>
|
||
</div>
|
||
|
||
<nav class="nav" aria-label="Document sections">
|
||
<a href="#summary">Summary</a>
|
||
<a href="#findings">Findings</a>
|
||
<a href="#principles">Principles</a>
|
||
<a href="#model">Small model</a>
|
||
<a href="#start">Start worker</a>
|
||
<a href="#messages">Messages and wait</a>
|
||
<a href="#output">Read output</a>
|
||
<a href="#safety">Minimal safety</a>
|
||
<a href="#skill">Agent cookbook</a>
|
||
<a href="#scope-discipline">Scope discipline</a>
|
||
<a href="#roadmap">Roadmap</a>
|
||
<a href="#non-goals">Non-goals</a>
|
||
</nav>
|
||
|
||
<div class="sidebar-footer">
|
||
<button class="theme-button" id="theme-toggle" type="button">Use dark theme</button>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
<main>
|
||
<div class="content">
|
||
<section id="summary">
|
||
<p class="eyebrow">Orca orchestration proposal</p>
|
||
<h1>Strong primitives. Little magic. No orchestration product inside the product.</h1>
|
||
<p class="lede">
|
||
Orca should make it intuitive for a coordinating agent to start workers, communicate,
|
||
wait, observe output, and recover safely. Orca supplies dependable building blocks;
|
||
the agent decides the orchestration strategy.
|
||
</p>
|
||
|
||
<div class="chip-row">
|
||
<span class="chip">CLI and runtime only</span>
|
||
<span class="chip">agent-directed</span>
|
||
<span class="chip">multi-server capable</span>
|
||
<span class="chip">explicit effects</span>
|
||
<span class="chip">no commit tracking</span>
|
||
</div>
|
||
|
||
<div class="scope-banner">
|
||
<div class="scope-mark" aria-hidden="true">→</div>
|
||
<div>
|
||
<strong>The common agent loop</strong>
|
||
<p>
|
||
Create and bind one Run for the coordination effort; after that its ID is carried
|
||
automatically. Create tasks, start workers on this or another connected Orca
|
||
server, send messages, wait for inbox mail, and read or stop workers. Options
|
||
refine those operations without adding policy.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
The test for the design is simple: after reading a few examples, an agent should be
|
||
able to predict what every command creates, reuses, blocks on, and returns.
|
||
</p>
|
||
</section>
|
||
|
||
<section id="findings">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">What we learned</p>
|
||
<h2>The current problems are coordination problems, not missing product surfaces.</h2>
|
||
<p>
|
||
The research found real reliability gaps, but the earlier proposal responded by
|
||
adding a scheduler, integration subsystem, dashboard, and large control-plane model.
|
||
Those additions would make the common agent workflow harder to understand.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="compare">
|
||
<div class="card">
|
||
<p class="eyebrow">Current</p>
|
||
<h3>Lifecycle mail arrives through prompt injection</h3>
|
||
<p>
|
||
Messages persist, but coordinator delivery may wait for the agent to pause. If it
|
||
keeps polling or working, messages can collect and flood the editable input after
|
||
a manual interruption.
|
||
</p>
|
||
</div>
|
||
<div class="compare-arrow" aria-hidden="true">→</div>
|
||
<div class="card">
|
||
<p class="eyebrow">Needed</p>
|
||
<h3>A structured, blocking inbox call</h3>
|
||
<p>
|
||
Typed worker lifecycle messages return from a pending tool request or the next explicit
|
||
read. Routine lifecycle delivery never writes into the coordinator's prompt.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="compare">
|
||
<div class="card">
|
||
<p class="eyebrow">Current</p>
|
||
<h3>Starting a worker is assembled from low-level pieces</h3>
|
||
<p>
|
||
Creating a worktree may already create a terminal, but an agent can miss that and
|
||
create another terminal before launching the worker.
|
||
</p>
|
||
</div>
|
||
<div class="compare-arrow" aria-hidden="true">→</div>
|
||
<div class="card">
|
||
<p class="eyebrow">Needed</p>
|
||
<h3>One composed start operation with full topology and setup choices</h3>
|
||
<p>
|
||
The operation composes existing worktree, setup, terminal, and agent creation and
|
||
returns exactly which resources it created or reused.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="compare">
|
||
<div class="card">
|
||
<p class="eyebrow">Current</p>
|
||
<h3>Terminal scrollback is treated as agent history</h3>
|
||
<p>
|
||
Full-screen TUIs can redraw or discard the useful conversation, making terminal
|
||
reads incomplete or misleading.
|
||
</p>
|
||
</div>
|
||
<div class="compare-arrow" aria-hidden="true">→</div>
|
||
<div class="card">
|
||
<p class="eyebrow">Implemented</p>
|
||
<h3>Exact structured output with a truthful fallback</h3>
|
||
<p>
|
||
Orca reuses its pane-scoped hook association to read a supported Codex, Claude,
|
||
OpenClaude, or Grok transcript. When it cannot prove that source, it returns
|
||
labeled bounded terminal output instead of guessing a session.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="compare">
|
||
<div class="card">
|
||
<p class="eyebrow">Current</p>
|
||
<h3>Results are mostly worker assertions</h3>
|
||
<p>
|
||
Orca verifies that the active dispatch reported <code>worker_done</code>, but the
|
||
summary, changed files, tests, and report path come from the worker.
|
||
</p>
|
||
</div>
|
||
<div class="compare-arrow" aria-hidden="true">→</div>
|
||
<div class="card">
|
||
<p class="eyebrow">Needed</p>
|
||
<h3>Be explicit about what Orca observed</h3>
|
||
<p>
|
||
Keep lifecycle authority separate from worker-reported content. Do not add commit,
|
||
test, merge, or integration tracking merely to make the report appear stronger.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section id="principles">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Design rules</p>
|
||
<h2>Reliability should live underneath a small interface.</h2>
|
||
<p>
|
||
Strong primitives have narrow, testable contracts. They do not need to expose every
|
||
mechanism used to make the contract safe.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="grid-3">
|
||
<div class="card number-card">
|
||
<span class="number">01</span>
|
||
<h3>The coordinator owns strategy</h3>
|
||
<p>
|
||
The agent chooses decomposition, ordering, parallelism, placement, review, and when
|
||
to wait. Orca does not schedule ready tasks automatically.
|
||
</p>
|
||
</div>
|
||
<div class="card number-card">
|
||
<span class="number">02</span>
|
||
<h3>Every effect is visible</h3>
|
||
<p>
|
||
Responses say which connected server, worktree, setup, terminal, execution host,
|
||
and agent were created or reused. Defaults are reported, not hidden.
|
||
</p>
|
||
</div>
|
||
<div class="card number-card">
|
||
<span class="number">03</span>
|
||
<h3>Simple default, explicit escape hatch</h3>
|
||
<p>
|
||
The common path needs few arguments and preserves worktree/setup choices. Uncommon
|
||
custom launches stay on the existing low-level commands instead of bloating start.
|
||
</p>
|
||
</div>
|
||
<div class="card number-card">
|
||
<span class="number">04</span>
|
||
<h3>Observation is honest</h3>
|
||
<p>
|
||
Orca distinguishes observed process state from worker-reported claims and labels
|
||
the source of transcript or terminal output.
|
||
</p>
|
||
</div>
|
||
<div class="card number-card">
|
||
<span class="number">05</span>
|
||
<h3>Remote ambiguity stays ambiguous</h3>
|
||
<p>
|
||
A disconnect after a remote mutation returns <code>outcome_unknown</code>. Orca
|
||
does not silently repeat a command that may have succeeded.
|
||
</p>
|
||
</div>
|
||
<div class="card number-card">
|
||
<span class="number">06</span>
|
||
<h3>Safety is not orchestration policy</h3>
|
||
<p>
|
||
Stable identity, stale-worker fencing, and owner routing prevent corruption. They
|
||
do not choose what work should happen next.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
A feature belongs in the core only if it makes an existing primitive safer or clearer.
|
||
Tracking extra domain facts—commits, merges, budgets, priorities, or organizational
|
||
roles—is not automatically a stronger primitive.
|
||
</p>
|
||
</section>
|
||
|
||
<section id="model">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Primitive 1 · Scope and identity</p>
|
||
<h2>Four public concepts, each with one job.</h2>
|
||
<p>
|
||
A Run prevents unrelated coordination efforts from mixing. Tasks describe work,
|
||
Dispatches authorize workers, and Messages communicate. Existing worktree and
|
||
terminal resources remain independently usable.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="grid-2">
|
||
<div class="card">
|
||
<h3>Run</h3>
|
||
<p>A lightweight namespace and stable coordinator mailbox. It never schedules work.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Task</h3>
|
||
<p>A durable description, status, and optional dependencies. Creating it starts nothing.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Dispatch</h3>
|
||
<p>One supervised worker assignment and its current lifecycle authority.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Message</h3>
|
||
<p>Durable communication or a typed lifecycle report returned through the inbox.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Persisted worker state</th>
|
||
<th>Task state and allowed next action</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>starting</code> / <code>ready</code></td>
|
||
<td>Task is dispatched; only show, read, message, or stop may act on it.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>start_unknown</code></td>
|
||
<td>Task is blocked; recover the same request receipt, inspect, stop, or abandon.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>failed</code></td>
|
||
<td>
|
||
Confirmed start failure and authenticated worker failure both leave Task
|
||
failed. Either permits an explicit <code>--retry-of</code> replacement.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>succeeded</code></td>
|
||
<td>Task is completed; create a follow-up Task rather than retrying it.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>stopping</code> / <code>stop_unknown</code></td>
|
||
<td>
|
||
Task is blocked and lifecycle authority is fenced; inspect termination or
|
||
explicitly abandon before replacement.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>stopped</code> / <code>abandoned</code></td>
|
||
<td>Task is blocked and permits an explicit <code>--retry-of</code> replacement.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Run operation</th>
|
||
<th>Exact effect</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>run-create</code></td>
|
||
<td>
|
||
Creates a run and stable coordinator mailbox on the coordinator's selected
|
||
Orca server—its Run home—then binds the current coordinator terminal as its
|
||
active consumer.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>run-use --id run_123</code></td>
|
||
<td>
|
||
Explicitly binds or rebinds the current terminal to that run. Rebinding fences
|
||
the prior consumer generation and cancels its waiter. A terminal has at most
|
||
one active run binding.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>run-current</code> / <code>run-list</code> / <code>run-show</code></td>
|
||
<td>Reports bindings and state without changing tasks, workers, or mail.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3>Run IDs stay out of the common path</h3>
|
||
<p>
|
||
A command resolves the run only from explicit <code>--run</code> or the current
|
||
terminal binding—never from a worktree or an “exactly one candidate” guess.
|
||
Commands return the resolved Run or <code>runId</code> where it is needed for later
|
||
control; agents do not carry a separate resolution-mode field.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Low-level commands remain run-free</h3>
|
||
<p>
|
||
Ordinary worktree, terminal, and full-handoff commands do not create or require a
|
||
Run. Runs exist only for supervised coordination that needs durable grouping.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>One home, workers anywhere</h3>
|
||
<p>
|
||
A Run has one home server that owns its tasks and inbox. A Dispatch may point to a
|
||
worker on any connected Orca server; Orca relays that worker's messages back to the
|
||
home automatically.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
ELI5: a Run is a folder label plus a return address. It keeps one coordination
|
||
effort's tasks and mail together and gives workers on your Mac or Windows server the
|
||
same stable place to reply.
|
||
Create or select it once, then ordinary orchestration commands inherit it. It does
|
||
not create resources, choose workers, schedule tasks, or group projects.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
If a supervised command has neither <code>--run</code> nor a terminal binding, return
|
||
<code>run_required</code> with exact <code>run-create</code> and <code>run-use</code>
|
||
examples. Never silently create or infer a Run.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
V1 does not archive or delete Runs. <code>run-list</code> and <code>run-show</code> keep
|
||
old coordination state inspectable; retention administration waits for a demonstrated
|
||
clutter or storage problem instead of complicating the common lifecycle now.
|
||
</p>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Canonical command</th>
|
||
<th>Compatibility decision</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>run-create/list/show/use/current</code></td>
|
||
<td>New lightweight scope commands. They never decompose or schedule tasks.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>task-create/list/update</code></td>
|
||
<td>Keep the current flat command names and add Run association.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>dispatch</code></td>
|
||
<td>Keep as the low-level binding to an exact existing terminal.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>worker-start/show/read/stop/abandon</code></td>
|
||
<td>New composed supervised-worker operations.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>send/ask/reply/check</code></td>
|
||
<td>Keep and strengthen the current message operations.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Current scheduler-like <code>orchestration run --spec</code></td>
|
||
<td>
|
||
Must be removed or renamed in Phase 0 before <code>run-*</code> can ship. It is
|
||
not an alias for a lightweight Run and is not part of this scheduler-free
|
||
design.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>ID</th>
|
||
<th>Who normally carries it</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>runId</code></td>
|
||
<td>The terminal binding carries it; agents pass it only to override context.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>taskId</code></td>
|
||
<td>The coordinator uses it for dependencies and worker start.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>dispatchId</code></td>
|
||
<td>
|
||
Receipts and worker preambles carry it; show, read, stop, abandon, retry, and
|
||
lifecycle reports use it.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>deliveryId</code></td>
|
||
<td>The current mailbox consumer carries only its last unacknowledged delivery.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>messageId</code> / <code>threadId</code></td>
|
||
<td>
|
||
<code>reply</code> takes a message ID and infers its thread. Agents do not
|
||
manage a separate question identifier.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Resource IDs</td>
|
||
<td>Receipt data until an agent explicitly reads, stops, or reuses that resource.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>RPC request ID</td>
|
||
<td>
|
||
The client transport creates it automatically. Agents only echo the returned
|
||
retry token after an unknown outcome; they never invent one.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<pre style="margin-top: 20px"><code>orca orchestration run-create --objective "Improve message delivery"
|
||
# → run_123, bound to this coordinator terminal
|
||
orca orchestration task-create --spec "Audit message delivery"
|
||
# → task_a, runId run_123 (bound)
|
||
orca orchestration worker-start --task task_a --worktree current --agent codex
|
||
orca orchestration check --wait --timeout-ms 60000</code></pre>
|
||
</section>
|
||
|
||
<section id="start">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Primitive 2 · Supervised worker start</p>
|
||
<h2>One request, predictable behavior for every topology.</h2>
|
||
<p>
|
||
<code>worker-start</code> is one synchronous composition of existing worktree, setup,
|
||
terminal, and dispatch operations. It is not a background executor, external
|
||
transaction, or placement engine. The coordinator chooses the topology; Orca returns
|
||
only after the composition is ready, failed, or honestly unknown.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Topology</th>
|
||
<th>Default terminal behavior</th>
|
||
<th>Setup behavior</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Current worktree</td>
|
||
<td>
|
||
Create one fresh agent terminal. Never reuse the coordinator terminal or an
|
||
arbitrary idle terminal. Reuse requires explicit <code>--terminal</code>.
|
||
</td>
|
||
<td><code>not_applicable</code>; do not rerun setup or configured tabs.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Named existing worktree</td>
|
||
<td>Create one fresh agent terminal; reuse only an explicitly selected terminal.</td>
|
||
<td><code>not_applicable</code>; creation-time setup is not replayed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>New child worktree</td>
|
||
<td>
|
||
Use agent-first worktree creation and reuse its returned agent terminal. Never
|
||
create a second shell/agent terminal.
|
||
</td>
|
||
<td>
|
||
Default to <code>run</code>. Setup and agent launch start side by side unless the
|
||
repository explicitly uses <code>wait-for-setup</code>. <code>skip</code> or
|
||
<code>inherit</code> must be explicit.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>New top-level worktree</td>
|
||
<td>Same agent-first behavior, with top-level Orca lineage.</td>
|
||
<td>
|
||
Same setup default: run a configured hook; use an explicit escape hatch only
|
||
for a concrete reason.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3>Worktree option parity means pass-through</h3>
|
||
<p>
|
||
The exact repository selector, name, base branch, child/top-level lineage, setup,
|
||
and display/comment metadata are validated and passed to the existing worktree
|
||
primitive. <code>--on</code> already chooses the connected Orca server, so V1 does
|
||
not add a second project/host placement vocabulary to <code>worker-start</code>;
|
||
agents may use low-level <code>worktree create</code> when that convenience selector
|
||
is important.
|
||
</p>
|
||
<p class="footer-note">
|
||
Folder projects have no distinct Git worktree to create. New-child and
|
||
new-top-level therefore fail before effects; use current or an exact existing
|
||
folder workspace.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Choose a connected server only when needed</h3>
|
||
<p>
|
||
The default is the Run home. Use <code>--on windows</code> (a saved Orca environment
|
||
name or ID) only to place a worker on another connected server. V1 resource IDs
|
||
are server-scoped, so every remote existing worktree or terminal also requires
|
||
<code>--on</code>. Orca never guesses an owner from a same-looking ID and echoes the
|
||
resolved server name in the receipt.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Agent selection is honest</h3>
|
||
<p>
|
||
When creating a terminal, V1 requires an explicit <code>--agent</code> that resolves
|
||
through Orca's configured launcher before any effect. Composed start does not
|
||
promise custom model, environment, or arbitrary command arguments that agent-first
|
||
worktree creation cannot actually pass through.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Setup is the safe default</h3>
|
||
<p>
|
||
For every new worktree, omitted <code>--setup</code> resolves to
|
||
<code>run</code>. If a setup hook exists, Orca launches it; if none exists, the
|
||
receipt says <code>not_configured</code>. Preserve the repository's existing
|
||
<code>setupAgentStartupPolicy</code>: its default is <code>start-immediately</code>,
|
||
so setup does not delay agent launch or task delivery. Only an explicit
|
||
<code>wait-for-setup</code> policy gates the agent. An agent may choose
|
||
<code>skip</code> or <code>inherit</code> only for a specific reason it states in its
|
||
work log. Orca trusts that judgment and adds no approval gate.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Supervised means lifecycle injection</h3>
|
||
<p>
|
||
Task and dispatch input is delivered only after agent readiness. Ordinary
|
||
worktree/terminal commands remain the full-handoff path without lifecycle duties.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
<code>worker-start --on windows</code> is deliberately different from Orca's existing
|
||
global <code>--environment windows</code>. <code>--on</code> keeps the command and Task on
|
||
the bound Run home while selecting only the worker server. The global flag still means
|
||
“send this whole CLI command to that environment” and must not silently change meaning.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
Validate conflicts before effects: <code>--terminal</code> requires a current or named
|
||
existing worktree and cannot combine with <code>--agent</code>, setup, or new-worktree
|
||
creation options. New worktrees require a name and accept only options supported by
|
||
the selected underlying worktree command. Custom agent argv stays on the explicit
|
||
low-level <code>worktree create</code> → <code>terminal create --command</code> →
|
||
<code>dispatch</code> path, but that two-step path is legal only with
|
||
<code>start-immediately</code>; it cannot preserve an explicit
|
||
<code>wait-for-setup</code> policy because the later terminal is not the creation-time
|
||
startup. Use an agent-first configured launcher or stop and ask rather than bypassing
|
||
that policy. <code>current</code> always means the coordinator's current
|
||
worktree on the Run home and cannot combine with remote <code>--on</code>. A remote
|
||
existing worker needs an exact worktree/terminal selector or an explicit server so
|
||
same-looking resources are never guessed. Every resolved default includes its source.
|
||
Discover a remote selector with an explicit read-only command such as
|
||
<code>orca --environment windows worktree list --json</code>, then copy the returned
|
||
opaque worktree ID into <code>worker-start --on windows</code>.
|
||
</p>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Placement/federation error</th>
|
||
<th>Meaning</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>server_required</code></td>
|
||
<td>The selected runtime cannot provide connected-server orchestration.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>worktree_not_found_on_server</code></td>
|
||
<td>The exact worktree does not exist on the selected worker server.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>terminal_worktree_mismatch</code></td>
|
||
<td>The exact terminal is not owned by the selected worktree.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>resource_server_mismatch</code></td>
|
||
<td>
|
||
A worker-server receipt names a different Dispatch or authenticated Run home;
|
||
Orca never adopts that attachment.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>agent_unconfigured</code></td>
|
||
<td>The requested launcher is unavailable; no worktree or terminal was created.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Task acceptance</th>
|
||
<th>Worker-start effect</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>First start</td>
|
||
<td>
|
||
Requires a ready Task with no current Dispatch. The runtime creates the
|
||
Dispatch and moves the Task to dispatched in one local transaction before
|
||
running the composed effects.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Replacement attempt</td>
|
||
<td>
|
||
Requires <code>--retry-of</code> naming the Task's current failed, stopped, or
|
||
abandoned Dispatch while the Task is failed or blocked. Start creates the next
|
||
Dispatch generation and moves the Task back to dispatched atomically; the agent
|
||
never performs a preparatory <code>task-update</code>.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Anything else</td>
|
||
<td>
|
||
Return <code>task_not_startable</code> naming the rejected Task/Dispatch and
|
||
perform no worker effects. Completed work gets a new follow-up Task; an unknown
|
||
or nonterminal Dispatch must first be inspected, stopped, or abandoned.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
<code>ready</code> has one testable meaning: the selected agent terminal reached
|
||
<code>tui-idle</code>, the local or remote Dispatch attachment is durable, and the
|
||
lifecycle preamble plus task input was accepted. Under the default
|
||
<code>start-immediately</code> policy, setup may still be running and its exact state is
|
||
returned in the receipt; its outcome never gates readiness, even if failure is observed
|
||
before the agent reaches <code>tui-idle</code>. Under an explicit
|
||
<code>wait-for-setup</code> repository policy, setup must complete successfully before
|
||
agent launch and task injection. Agent-first worktree creation launches without the
|
||
task prompt so Orca can establish authority before injection. The effective timeout
|
||
and startup policy are echoed in every receipt.
|
||
A successful gated receipt reports setup <code>succeeded</code>. A confirmed setup
|
||
spawn/script failure reports <code>failed</code> before task input, while a timeout may
|
||
honestly retain <code>running</code> rather than inventing a failure.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
Underneath the call, one transaction creates a <code>starting</code> Dispatch, moves the
|
||
Task, and records the retry request before effects. Orca journals each irreversible
|
||
stage and resource receipt before advancing. Restart recovery can therefore prove
|
||
no-effect, return a durable remote result, or remain honestly
|
||
<code>outcome_unknown</code>. A pending accepted start retains its Dispatch ID, so
|
||
repeating the exact request after restart returns that ID and its
|
||
<code>worker-show</code> command instead of inviting a second start. Orca does not
|
||
resume unfinished orchestration stages in the background; a setup process
|
||
intentionally launched under
|
||
<code>start-immediately</code> may continue exactly as its receipt states.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
With <code>start-immediately</code>, the start receipt carries the latest observed setup
|
||
state. Only a setup state change after that receipt updates <code>worker-show</code> and
|
||
emits a typed notice; setup never rewrites Dispatch readiness or decides whether the
|
||
worker should stop. With explicit <code>wait-for-setup</code>, setup failure is a start
|
||
failure before task input is sent.
|
||
</p>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<pre><code>orca orchestration worker-start --task task_a --worktree new-child --name message-audit --agent codex --setup run
|
||
|
||
# Returns when the worker is ready, start failed, or the outcome is unknown.
|
||
# Coordinators can issue independent start calls in parallel.</code></pre>
|
||
<pre><code># "result" excerpt from --json
|
||
{
|
||
"runId": "run_123",
|
||
"taskId": "task_a",
|
||
"dispatchId": "dispatch_7",
|
||
"state": "ready",
|
||
"stage": "input_accepted",
|
||
"setup": {
|
||
"requested": "run",
|
||
"effective": "run",
|
||
"source": "explicit_request",
|
||
"hookFound": true,
|
||
"startupPolicy": "start-immediately",
|
||
"state": "running"
|
||
},
|
||
"timeoutMs": 60000,
|
||
"effects": [
|
||
{ "kind": "worktree", "action": "created_child", "id": "worktree_9" },
|
||
{ "kind": "terminal", "role": "setup", "action": "created", "id": "term_setup_11", "tabId": "tab_2", "leafId": "leaf_1" },
|
||
{ "kind": "setup", "action": "run", "requested": "run", "effective": "run", "source": "explicit_request", "hookFound": true, "startupPolicy": "start-immediately", "state": "running", "terminalId": "term_setup_11" },
|
||
{ "kind": "terminal", "role": "agent", "action": "reused_agent_terminal", "id": "term_12" },
|
||
{ "kind": "terminal", "role": "configured_tab", "action": "created", "id": "term_13", "tabId": "tab_3", "leafId": "leaf_1" },
|
||
{ "kind": "dispatch_input", "role": "agent", "id": "term_12", "state": "accepted" }
|
||
],
|
||
"residualResources": [],
|
||
"mutation": { "requestId": "req_7", "replayed": false }
|
||
}</code></pre>
|
||
</div>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
Receipts enumerate every created or reused terminal with a role—agent, setup, or each
|
||
configured terminal (including each tab/split pane), with exact tab and leaf identity
|
||
when available. Setup may be reported <code>running</code> only after its exact
|
||
PTY spawn receipt is durable. These role-tagged effects are also the authoritative
|
||
residual-resource list used by restart inspection and failure recovery.
|
||
</p>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Start state</th>
|
||
<th>Meaning and next action</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>ready</code></td>
|
||
<td>
|
||
Agent is ready and lifecycle input was accepted. The return receipt contains
|
||
every created or reused effect; no separate startup notice is required.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>failed</code></td>
|
||
<td>
|
||
Return the failed stage, last error, residual resources, Task/Dispatch state,
|
||
and the durable mutation receipt. The composition itself has returned, but any
|
||
surviving setup, terminal, or agent process is listed honestly as a residual
|
||
resource; Orca never implies that failure cleaned it up. The coordinator
|
||
chooses the matching recovery branch below.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>outcome_unknown</code></td>
|
||
<td>
|
||
The connection failed after an effect may have happened. Return the operation
|
||
stage, <code>mutation.requestId</code>, durable effects/residuals, and exact
|
||
<code>worker-show</code>/<code>worker-abandon</code> commands. A replacement is
|
||
rejected until inspection proves it safe or the coordinator explicitly
|
||
abandons the old Dispatch.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Unknown-start recovery</th>
|
||
<th>Exact contract</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Query and reconcile</td>
|
||
<td>
|
||
<code>worker-show --dispatch dispatch_7</code> routes from the Run home to the
|
||
owning worker server and execution host. If its durable receipt proves the
|
||
original worker became ready, failed, or stopped, the home reconciles that same
|
||
Dispatch; no separate adopt operation exists.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Safe retry</td>
|
||
<td>
|
||
<code>--retry-of dispatch_7</code> links a new attempt but does not silently
|
||
reuse prior placement. The coordinator repeats an explicit valid topology and
|
||
agent/terminal choice, which may deliberately differ from the old attempt. A
|
||
new Dispatch is allowed only after the prior one is failed, stopped, abandoned,
|
||
or reconciled as no-effect. While it remains unknown, return
|
||
<code>task_not_startable</code> without mutation.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Explicit stop</td>
|
||
<td>
|
||
<code>worker-stop --dispatch dispatch_7</code> may fence a
|
||
<code>ready</code> or <code>start_unknown</code> Dispatch. The owning server
|
||
closes a terminal only when its durable attachment still matches the exact
|
||
pane and process incarnation. Unattached, missing, exited, or identity-changed
|
||
workers become <code>stop_unknown</code> with no process action. If the remote
|
||
server durably stopped the exact worker but its response was lost, a later
|
||
<code>worker-show</code> reconciles that authoritative stopped receipt.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Explicit abandon</td>
|
||
<td>
|
||
<code>worker-abandon --dispatch dispatch_7</code> fences future lifecycle
|
||
mutations from that Dispatch and records every possibly-live resource. It sends
|
||
no remote command, claims no process stopped, deletes nothing, and warns that a
|
||
concurrent worker may remain. The coordinator may then start a replacement.
|
||
Abandoning an older superseded Dispatch is a no-op and cannot block or rewrite
|
||
the replacement Task.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
The Dispatch ID is the worker identity. Do not add another agent-facing start ID.
|
||
Every mutating CLI result includes one opaque <code>mutation.requestId</code> for
|
||
recovering that exact request after a lost response; agents never invent it. A
|
||
transport failure exposes the same value as <code>orchestrationRequestId</code> in its
|
||
error recovery data. Semantic retry
|
||
explicitly names the prior Dispatch ID and never replays an unknown effect. After a
|
||
remote start, show, read, stop, abandon, and message routing use the Dispatch receipt;
|
||
the agent does not repeat <code>--on</code> for those controls or carry server IDs. A
|
||
replacement <code>worker-start</code> is a new placement decision and names its target
|
||
again.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
Transport retry and semantic retry are different. If the response itself was lost,
|
||
reissue the identical mutation with <code>--retry-request req_7</code> to recover its
|
||
durable receipt; a changed canonical payload returns <code>request_mismatch</code>. Once
|
||
that receipt says <code>outcome_unknown</code>, inspect by Dispatch ID instead of
|
||
replaying it repeatedly. <code>--retry-of dispatch_7</code> creates a new worker attempt
|
||
only after the old attempt is safe to replace.
|
||
</p>
|
||
</section>
|
||
|
||
<section id="messages">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Primitives 3 and 4 · Message and wait</p>
|
||
<h2>Structured mail is inbox-only, durable, and explicitly consumed.</h2>
|
||
<p>
|
||
The inbox is an agent API, not product UI and not terminal input. It strengthens
|
||
Orca's existing message store and <code>check --wait</code>; it does not add an Event
|
||
subsystem or a second orchestration engine.
|
||
</p>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
<code>send</code>, <code>ask</code>, <code>reply</code>, completion, heartbeat, and runtime
|
||
notices only persist structured state and wake a pending tool waiter. Only explicit
|
||
<code>dispatch --inject</code> and <code>terminal send</code> may modify terminal input.
|
||
From an active Dispatch, lifecycle <code>send</code> and <code>ask</code> default to that
|
||
Dispatch's owning Run mailbox. “Sent” means durably accepted—not pasted, observed, or
|
||
acted upon.
|
||
</p>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3><code>run:run_123</code></h3>
|
||
<p>The stable coordinator mailbox stored with that Run in the Orca runtime.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3><code>dispatch:dispatch_7</code></h3>
|
||
<p>The exact supervised worker generation, independent of terminal handle changes.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
V1 deliberately has no <code>task:</code> message recipient. Use the Run for guidance
|
||
that survives reassignment and the exact Dispatch for attempt-specific control. This
|
||
avoids a hidden acceptance-time retargeting rule.
|
||
</p>
|
||
|
||
<p class="principle">
|
||
Orca authenticates lifecycle reports automatically. The worker supplies only the Task
|
||
and Dispatch IDs injected in its preamble; it never supplies Run, runtime, host,
|
||
terminal, capability, or attestation IDs. At injection, Orca gives the managed pane a
|
||
narrow unforgeable Dispatch capability through its CLI bridge. The worker server
|
||
verifies that capability and its local pane; the Run home accepts the relayed report
|
||
only from the pinned paired peer for that Dispatch. Stop, abandon, or replacement
|
||
revokes it. Other reports remain stale history and cannot change Task state. This is
|
||
lifecycle integrity, not a general permission system.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
A federated worker omits <code>--to</code> and <code>--run</code>; its authenticated
|
||
Dispatch already identifies the only valid Run home. Explicit targets are rejected
|
||
instead of being silently ignored or redirected.
|
||
</p>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3>One Run home</h3>
|
||
<p>
|
||
The coordinator's server stores the authoritative Run, tasks, inbox ordering, and
|
||
acknowledgments. Worker servers do not replicate the Run database or elect a new
|
||
home.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Remote mail waits safely</h3>
|
||
<p>
|
||
A worker server durably retains messages for its remote Dispatch until the Run
|
||
home imports and acknowledges them. Replies wait at the home until the worker
|
||
server reconnects. This is a narrow relay queue, not a replicated global inbox.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="sequence" aria-label="Structured wait sequence">
|
||
<div class="sequence-row sequence-head">
|
||
<div>Coordinator</div>
|
||
<div>Run home ↔ worker server</div>
|
||
<div>Worker</div>
|
||
</div>
|
||
<div class="sequence-row">
|
||
<div>Starts every independent worker</div>
|
||
<div class="runtime-step">Persists home record and remote attachment</div>
|
||
<div>Works concurrently</div>
|
||
</div>
|
||
<div class="sequence-row">
|
||
<div>Calls <code>check --wait</code> only when no local work remains</div>
|
||
<div class="runtime-step">Returns the outstanding batch or registers one waiter</div>
|
||
<div>Continues independently</div>
|
||
</div>
|
||
<div class="sequence-row">
|
||
<div>Pending tool call is blocked</div>
|
||
<div class="runtime-step">Durably relays question, failure, or completion</div>
|
||
<div>Reports one typed lifecycle message</div>
|
||
</div>
|
||
<div class="sequence-row">
|
||
<div>Receives a structured batch</div>
|
||
<div class="runtime-step">Persists and returns one opaque Delivery ID</div>
|
||
<div>No coordinator prompt injection</div>
|
||
</div>
|
||
<div class="sequence-row">
|
||
<div>Processes every message, then acknowledges and waits</div>
|
||
<div class="runtime-step">Atomically ack → check → register</div>
|
||
<div>May continue, stop, or receive a reply</div>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
<code>check --wait</code> always targets the Run home and fans in mail from every active
|
||
remote Dispatch. One disconnected worker server does not block local or other-server
|
||
messages. Imported relay items are idempotent by their authenticated Dispatch and
|
||
source sequence, then follow the same FIFO delivery and acknowledgment rules as local
|
||
mail.
|
||
</p>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<pre><code>orca orchestration check --wait --timeout-ms 60000
|
||
# → returns delivery_81 with an ordered message batch
|
||
|
||
# Process every message and start newly-ready work.
|
||
orca orchestration check --ack delivery_81 --wait --timeout-ms 60000</code></pre>
|
||
<pre><code># "result" excerpt from --json
|
||
{
|
||
"runId": "run_123",
|
||
"deliveryId": "delivery_81",
|
||
"messages": [
|
||
{
|
||
"id": "msg_481",
|
||
"run_id": "run_123",
|
||
"from_handle": "dispatch:dispatch_7",
|
||
"to_handle": "run:run_123",
|
||
"subject": "Review complete",
|
||
"type": "worker_done",
|
||
"payload": "{\"taskId\":\"task_a\",\"dispatchId\":\"dispatch_7\",\"outcome\":\"succeeded\"}",
|
||
"read": 0
|
||
}
|
||
],
|
||
"count": 1,
|
||
"replayed": false,
|
||
"acknowledged": null,
|
||
"timedOut": false,
|
||
"cancelled": false,
|
||
"connectionLost": false
|
||
}</code></pre>
|
||
</div>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Inbox rule</th>
|
||
<th>V1 contract</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Ordering and size</td>
|
||
<td>FIFO by mailbox sequence, bounded to 50 messages per delivery.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Outstanding batch</td>
|
||
<td>
|
||
One per mailbox. Until acknowledged, return the same Delivery ID and batch;
|
||
newer mail waits behind it.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Acknowledgment</td>
|
||
<td>
|
||
Whole-batch and idempotent. Repeating an acknowledged Delivery ID returns the
|
||
recorded result and does not consume newer mail. A Delivery is bound to the
|
||
consumer generation that received it; a fenced coordinator gets
|
||
<code>consumer_fenced</code> and cannot consume the replacement's mail. The same
|
||
current-consumer check applies to coordinator replies and other mailbox
|
||
mutations.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Waiters</td>
|
||
<td>
|
||
One active actionable waiter per mailbox. A second returns
|
||
<code>waiter_exists</code>; it never races to consume the batch.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Crash safety</td>
|
||
<td>
|
||
Receiving a batch never marks it consumed. Unacknowledged mail survives client,
|
||
mailbox-consumer, and runtime restart.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Atomic continuation</td>
|
||
<td>
|
||
<code>check --ack delivery_81 --wait</code> commits ack, checks queued mail,
|
||
then registers the waiter as one runtime operation.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3>History modes do not consume</h3>
|
||
<p>
|
||
<code>check --peek</code>, <code>--all</code>, and type-filtered history reads are
|
||
read-only debugging surfaces. Legacy consume-on-check behavior is deprecated.
|
||
Rename local formatting flag <code>check --inject</code> so it cannot imply delivery.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Timeouts are typed checkpoints</h3>
|
||
<p>
|
||
Wait returns <code>timedOut</code>, <code>cancelled</code>, or
|
||
<code>connectionLost</code> distinctly. None means worker failure, none consumes
|
||
mail, and transport keepalive output is not a worker heartbeat.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
Actionable <code>check</code>, acknowledgment, and wait never create separate filtered
|
||
deliveries. A type filter may decide when a waiter wakes, but the returned Delivery is
|
||
always the oldest full FIFO batch, including earlier nonmatching mail. History modes
|
||
may filter freely because they do not consume.
|
||
</p>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Lifecycle input</th>
|
||
<th>Atomic state effect at message acceptance</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Authenticated active Dispatch reports <code>worker_done outcome=succeeded</code></td>
|
||
<td>Set Dispatch settled/succeeded and Task completed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Authenticated active Dispatch reports <code>worker_done outcome=failed</code></td>
|
||
<td>Set Dispatch settled/failed and Task failed. Coordinator chooses recovery.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Stale or foreign Dispatch report</td>
|
||
<td>Persist as stale history; do not change current Task or Dispatch state.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Malformed lifecycle report</td>
|
||
<td>Reject the transition and return the missing or invalid field.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>worker-start</code> returns <code>failed</code></td>
|
||
<td>Set Dispatch and Task failed with an explicit recovery reason.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Confirmed <code>worker-stop</code></td>
|
||
<td>Set Dispatch stopped and Task blocked; never claim task completion.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>worker-stop</code> accepted, termination unknown</td>
|
||
<td>
|
||
Fence lifecycle authority, set Dispatch <code>stop_unknown</code> and Task
|
||
blocked, and retain the process/terminal in <code>residualResources</code> as
|
||
possibly live. A new start remains unsafe until inspection confirms termination
|
||
or the coordinator explicitly abandons with the concurrent-worker warning.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Confirmed <code>worker-abandon</code></td>
|
||
<td>
|
||
Set Dispatch abandoned and Task blocked, fence its later reports, and retain
|
||
possibly-live resource IDs; never claim process termination.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
Inbox acknowledgment confirms recipient consumption only. Lifecycle reconciliation
|
||
happens once, atomically, when the Run home imports an authenticated message. Every
|
||
terminal Dispatch transition is a home-side transactional compare-and-set: the first
|
||
committed completion, stop fence, or abandon wins; later conflicting input is retained
|
||
only as stale history.
|
||
</p>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Question state</th>
|
||
<th>Ask/reply behavior</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>pending</code></td>
|
||
<td>
|
||
<code>ask</code> from an active Dispatch defaults to its owning Run mailbox. The
|
||
first reply from the current authenticated Run consumer generation records the
|
||
answer at the Run home, relays it to the exact worker server, and wakes the
|
||
local asking call.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>answered</code></td>
|
||
<td>
|
||
The pending <code>ask</code> or an explicit resume by the original Dispatch
|
||
returns the recorded answer. Repeating the same reply is harmless; a later
|
||
different answer conflicts.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Wait timed out or client disconnected</td>
|
||
<td>
|
||
Return the original question message ID and an exact
|
||
<code>ask --resume msg_question_7</code> command without closing or duplicating
|
||
the question. Resume is allowed only for the original Dispatch. There is no
|
||
separate Question ID or durable expiry/deadline state machine.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Acceptance response was lost</td>
|
||
<td>
|
||
Retry the identical <code>ask</code> with its returned transport retry receipt
|
||
to recover the original message ID. A changed question conflicts; a blind new
|
||
ask is never the recovery path.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Dispatch stopped or abandoned</td>
|
||
<td>
|
||
The Run home atomically closes its pending questions, wakes local or resumed
|
||
waits with <code>dispatch_inactive</code>, and rejects later replies.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
Question threads are message primitives, not task gates. Use message type
|
||
<code>question</code>; its target-side delivery follows normal inbox acknowledgment,
|
||
while the answer lives only on durable thread state. Keep separately managed task
|
||
gates outside this proposal.
|
||
</p>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<pre><code># Worker: target defaults to the owning Run mailbox.
|
||
orca orchestration ask --question "Should I preserve the legacy format?" --json
|
||
# → question message msg_question_7
|
||
# After a disconnect/timeout: orca orchestration ask --resume msg_question_7 --json</code></pre>
|
||
<pre><code># Coordinator: reply to the returned message ID.
|
||
orca orchestration reply --id msg_question_7 --body "Yes; preserve it." --json</code></pre>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
Blocking is a coordinator decision. The runtime must make waiting race-free, but it
|
||
must not decide that the agent has exhausted all parallelizable work.
|
||
</p>
|
||
</section>
|
||
|
||
<section id="output">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Worker observation</p>
|
||
<h2>Read a supervised worker by Dispatch, regardless of server.</h2>
|
||
<p>
|
||
<code>worker-read --dispatch</code> resolves the worker server and exact process from
|
||
the Dispatch receipt. Its default <code>auto</code> source returns the exact
|
||
hook-reported Codex, Claude, OpenClaude, or Grok transcript when Orca can prove that
|
||
association;
|
||
otherwise it returns bounded, explicitly labeled terminal output. Agents never
|
||
choose a server, provider session ID, or transcript path, and task authority never
|
||
comes from transcript prose.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="grid-2">
|
||
<div class="card">
|
||
<p class="eyebrow">Default path</p>
|
||
<h3>Automatic exact selection</h3>
|
||
<p>
|
||
<code>--source auto</code> uses a proven supported transcript and falls back to
|
||
the existing bounded terminal reader with a typed reason such as
|
||
<code>session_not_reported</code> or
|
||
<code>remote_capability_unavailable</code>.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<p class="eyebrow">Explicit policy</p>
|
||
<h3>Transcript or terminal</h3>
|
||
<p>
|
||
<code>--source transcript</code> requires exact structured output and returns a
|
||
typed error rather than falling back. <code>--source terminal</code> always uses
|
||
the retained terminal snapshot.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<pre style="margin-top: 20px"><code>orca orchestration worker-read --dispatch dispatch_7 --source auto --limit 100 --json
|
||
|
||
# Exact transcript result for a worker on the saved environment named windows
|
||
{
|
||
"dispatchId": "dispatch_7",
|
||
"source": "transcript",
|
||
"sourceIdentity": "opaque-source-fingerprint",
|
||
"provider": "codex",
|
||
"server": { "environmentId": "env_windows", "name": "windows" },
|
||
"remoteRuntimeEpoch": "runtime_epoch_2",
|
||
"transcript": {
|
||
"messages": [ ... ],
|
||
"nextCursor": "opaque-next-cursor",
|
||
"limited": false,
|
||
"returnedMessageCount": 12
|
||
},
|
||
"cursor": "opaque-next-cursor",
|
||
"status": { "worker": "ready", "terminal": "running" },
|
||
"fallbackReason": null,
|
||
"warnings": []
|
||
}
|
||
|
||
# Continue from the returned top-level opaque cursor.
|
||
orca orchestration worker-read --dispatch dispatch_7 \
|
||
--cursor opaque-next-cursor --limit 100 --json</code></pre>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3>Source-pinned continuation</h3>
|
||
<p>
|
||
The returned cursor pins the Dispatch, process, source kind, and opaque source
|
||
identity. <code>auto</code> selects only on the first page. If the process or
|
||
provider session changes, Orca returns
|
||
<code>worker_identity_changed</code> or <code>source_changed</code>.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Narrow provider readers</h3>
|
||
<p>
|
||
Structured reading reuses the existing bounded native transcript decoders only
|
||
for exact Codex, Claude, OpenClaude, and Grok associations. Other providers and
|
||
mixed-version peers retain terminal fallback; no resume, live-stream control, or
|
||
universal transcript framework is added.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
Every response labels <code>source</code>, <code>sourceIdentity</code>,
|
||
<code>cursor</code>, status, fallback reason, and bounded warnings. Terminal fallback
|
||
preserves the existing terminal fields and accepts legacy numeric cursors; new cursors
|
||
are opaque and never expose a transcript path. The worker-owning server performs the
|
||
read, and neither local nor federated selection may guess “latest session in this
|
||
directory.”
|
||
</p>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Orca can say</th>
|
||
<th>Orca cannot infer</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>The active dispatch sent a completion report.</td>
|
||
<td>The implementation is correct.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>The managed process exited with a particular code.</td>
|
||
<td>The reported tests actually passed unless Orca ran them itself.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>A later exact-session adapter resolved these structured entries.</td>
|
||
<td>The transcript describes the complete repository state.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>The worker reported files, summary, and report path.</td>
|
||
<td>Those files are exhaustive or the work has been integrated.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</section>
|
||
|
||
<section id="safety">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Implementation appendix · agents may skip this section</p>
|
||
<h2>Hidden guarantees for one Run home and many worker servers.</h2>
|
||
<p>
|
||
A coordinator on one Orca server must be able to supervise workers on another—for
|
||
example, a Run on a Mac with Dispatches on both that Mac and a connected Windows
|
||
server. The minimum federation contract routes commands and durably relays messages;
|
||
it does not replicate the Run or add scheduling policy.
|
||
</p>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
Agent rule: choose a remote worker once with <code>--on</code>. After that, keep the
|
||
Dispatch ID and follow the returned inspection commands. Reuse
|
||
<code>mutation.requestId</code> only to recover the same request after a lost response.
|
||
Peer identity, sequencing, capabilities, and relay acknowledgments below are Orca
|
||
implementation details—not fields agents choose or copy.
|
||
</p>
|
||
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Internal fact</th>
|
||
<th>V1 contract</th>
|
||
<th>What agents see</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Run home</td>
|
||
<td>
|
||
The server where <code>run-create</code> executes owns the only authoritative
|
||
Run database: tasks, Dispatch state, inbox order, dedupe receipts, and consumer
|
||
generation.
|
||
</td>
|
||
<td>The terminal binding routes ordinary commands home; no Run-home ID is typed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Connected environment</td>
|
||
<td>
|
||
The Run home stores its existing saved environment ID/name and authenticated
|
||
pairing for each worker server. Each Dispatch pins the authenticated peer
|
||
fingerprint captured at attachment, so re-pairing the saved environment to a
|
||
different server cannot retarget existing work. That relationship survives the
|
||
same remote server process restarting; the observed <code>runtimeId</code>
|
||
remains only an epoch.
|
||
</td>
|
||
<td><code>--on windows</code> when placement is explicit; receipts echo the name.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Remote Dispatch attachment</td>
|
||
<td>
|
||
Before prompt injection, the worker server persists a verifier for the opaque
|
||
Dispatch capability, pinned Run-home peer identity, stable local pane and
|
||
process incarnation, effect receipts, and relay cursors. Credential material
|
||
is stored through current-user protected storage, not plaintext in a general
|
||
Run row. The worker server does not receive a copy of the Run DAG.
|
||
</td>
|
||
<td>Nothing extra; the worker receives only Task and Dispatch IDs.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Caller pane</td>
|
||
<td>
|
||
Each server's native, WSL, or SSH CLI bridge attaches the minted Dispatch
|
||
capability outside user parameters. The worker server verifies capability,
|
||
pane, and process incarnation; the Run home verifies the pinned authenticated
|
||
peer and Dispatch on relay import.
|
||
</td>
|
||
<td>Orca authenticates lifecycle reports automatically.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="grid-3" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3>Home-bound coordination</h3>
|
||
<p>
|
||
<code>run-use/current</code>, Task changes, check/ack, and replies go to the Run
|
||
home. Workers never choose or mutate the home, and there is no automatic home
|
||
failover.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Server-owned resources</h3>
|
||
<p>
|
||
The selected worker server owns its worktree, terminal, process, and any nested
|
||
native/WSL/SSH/relay host. The Run home stores opaque receipts and routes show,
|
||
read, stop, and retry back to that owner.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Durable relay, not replication</h3>
|
||
<p>
|
||
Worker-to-home lifecycle mail and home-to-worker replies remain queued at their
|
||
source until the destination imports and acknowledges them. Each item has a stable
|
||
ID, so reconnects are at-least-once on the wire and once in each inbox.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Home-initiated connection</h3>
|
||
<p>
|
||
The Run home uses the same saved, authenticated environment connection already
|
||
used for remote RPC. It subscribes or pulls by cursor; the Windows server does not
|
||
need a separate pairing back to the Mac or a publicly reachable callback.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Dispatch generations</h3>
|
||
<p>
|
||
Replacing a worker creates a new Dispatch ID; that ID is the generation. A report
|
||
from an older Dispatch or different pane remains history and cannot change current
|
||
Task state. There is no second agent-visible generation number.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Idempotent control operations</h3>
|
||
<p>
|
||
Before effects, both home and worker server durably record authenticated peer,
|
||
request ID, canonical payload hash, operation state, and receipt. Identical
|
||
concurrent or later attempts join or return that record; a changed payload returns
|
||
<code>request_mismatch</code>. Receipts expose the opaque retry ID needed after an
|
||
unknown outcome.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Typed unknown outcome</h3>
|
||
<p>
|
||
If a remote effect may have happened but Orca cannot prove it, return one
|
||
<code>outcome_unknown</code> shape with stage, mutation request ID, durable
|
||
effects/residuals, and exact inspection commands.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Stop and replace</h3>
|
||
<p>
|
||
Stop first commits one home-side compare-and-set that fences new lifecycle changes,
|
||
blocks the Task, and closes pending questions, then best-effort stops only the
|
||
supervised agent process/terminal. If completion already won, stop returns
|
||
<code>already_settled</code>; if stop won, later completion is stale history. Orca
|
||
never deletes the worktree, setup output, or unrelated configured tabs.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
The durable request receipt applies to every mutating control-plane call—Run and Task
|
||
creation, send, ask, reply, acknowledgment, start, stop, and abandon—not only remote
|
||
worker start. Read-only show, list, and output paging do not need mutation dedupe.
|
||
</p>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Federated relay rule</th>
|
||
<th>Exact contract</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Worker send acceptance</td>
|
||
<td>
|
||
Success means the worker server durably stored the authenticated message in
|
||
that Dispatch's outbound relay. The worker may finish even while the Run home
|
||
is offline.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Home import and lifecycle</td>
|
||
<td>
|
||
The Run home stores the message and applies any valid lifecycle transition in
|
||
one transaction before acknowledging it to the worker server. Until import,
|
||
the authoritative Task honestly remains dispatched.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Replies and control mail</td>
|
||
<td>
|
||
The Run home durably queues them for the exact remote Dispatch; the worker
|
||
server stores them before acknowledging the home and waking a local waiter.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Ordering and duplicates</td>
|
||
<td>
|
||
Each direction uses a scoped key of pinned peer, Dispatch ID, direction, and a
|
||
monotonic source sequence, plus a 128-bit-or-stronger message ID. A receiver
|
||
imports only the next contiguous sequence, buffers gaps, and acknowledges only
|
||
the highest contiguous commit. The home assigns normal inbox order at import,
|
||
without pretending simultaneous servers have a global clock.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Bounded storage</td>
|
||
<td>
|
||
Enforce per-message byte limits and per-Dispatch pending item/byte quotas,
|
||
coalesce heartbeats, and reserve space for one terminal lifecycle report. A
|
||
full relay returns <code>relay_quota_exceeded</code>; V1 adds no dead-letter or
|
||
retention workflow.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Remote edge</th>
|
||
<th>V1 behavior</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Worker server unavailable before send</td>
|
||
<td>
|
||
Return <code>remote_runtime_unavailable</code> before creating a Dispatch or any
|
||
remote effect. No remote Dispatch attachment exists, so the caller may retry
|
||
normally after reconnecting.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Connection lost after send</td>
|
||
<td>
|
||
Return <code>outcome_unknown</code>, <code>mutation.requestId</code>, last durable
|
||
stage, and exact inspection commands. Repeating the request ID returns the
|
||
worker server's original receipt or accepts it once; it never duplicates an
|
||
effect.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Run-home restart</td>
|
||
<td>
|
||
Run state, dedupe receipts, and unacknowledged mail survive. The process runtime
|
||
ID is only an epoch. Reconnect resumes relay cursors for every active remote
|
||
Dispatch; if the coordinator pane cannot be safely reminted,
|
||
<code>run-use</code> explicitly rebinds it.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Saved environment re-paired or removed</td>
|
||
<td>
|
||
If its authenticated peer fingerprint differs from the Dispatch attachment,
|
||
return <code>peer_changed</code> with no effect; never adopt the replacement
|
||
server. Removing an environment with a nonterminal Dispatch retains a routing
|
||
tombstone for inspection and abandon rather than erasing ownership evidence.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Servers disconnected after start</td>
|
||
<td>
|
||
The worker may continue. Its server retains lifecycle mail and questions while
|
||
replies remain queued at the home. Silence is not failure, no worker is
|
||
automatically replaced, and other servers continue delivering normally.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Worker-server restart</td>
|
||
<td>
|
||
Remote Dispatch attachments, effect receipts, and unacknowledged relay items
|
||
survive. The process runtime ID may change; the Run home routes by its saved
|
||
environment relationship and pinned peer. <code>worker-show</code> reports
|
||
running only when the stable pane and process incarnation match; it never
|
||
adopts a same-looking pane or newly launched process.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Mixed server versions</td>
|
||
<td>
|
||
Before effects, both servers must advertise one aggregate
|
||
<code>orchestrationFederationV1</code> contract. Missing support returns
|
||
<code>capability_unsupported</code>;
|
||
it never silently degrades to prompt injection, terminal scraping, or
|
||
consume-on-read mail. The worker-side mutation revalidates the pinned peer and
|
||
advertised protocol recorded for the operation, closing the probe-to-effect
|
||
race.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Structured worker output</td>
|
||
<td>
|
||
The worker-owning server reads an exact hook-reported Codex, Claude,
|
||
OpenClaude, or Grok transcript when supported. If the additive federated read
|
||
method is absent, <code>auto</code> returns bounded terminal output labeled with
|
||
<code>remote_capability_unavailable</code>;
|
||
<code>transcript</code> returns <code>transcript_required</code>.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
Capability checks cover only the new federation contracts, not every platform or host
|
||
feature. Existing worktree, setup, terminal, Git, WSL, SSH, and relay primitives keep
|
||
their proven compatibility behavior; optional, truthfully labeled observation may
|
||
degrade.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
In this proposal, “durable” means committed state survives a client or Orca process
|
||
crash and ordinary restart. Power-loss durability depends on the receiving database's
|
||
documented SQLite synchronization policy; lifecycle import and acknowledgment must use
|
||
the stronger policy if Orca promises survival across sudden host power loss.
|
||
</p>
|
||
|
||
<div class="table-wrap" style="margin-top: 20px">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Mechanism</th>
|
||
<th>Why it stays</th>
|
||
<th>Why it is not a scheduler</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Server ownership</td>
|
||
<td>Prevents commands from acting on a same-looking resource on the wrong host.</td>
|
||
<td>The agent chooses <code>--on</code>; the owner only determines routing.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Dispatch identity</td>
|
||
<td>Prevents stale workers from overwriting current task state.</td>
|
||
<td>It does not retry, replace, or start anything automatically.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Unknown outcome</td>
|
||
<td>Prevents duplicate remote effects after a disconnect.</td>
|
||
<td>
|
||
The receipt gives last durable stage and inspection command; the coordinator
|
||
chooses inspect, reconcile, retry, or abandon.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p class="principle">
|
||
Safety may reject stale, wrong-pane, or wrong-server control-plane mutations. It does
|
||
not police worker filesystem access, invent new work, choose a worker, or decide that
|
||
waiting is the coordinator's best next action.
|
||
</p>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
This federation is deliberately hub-and-spoke per Run: one home, explicit worker
|
||
servers, and per-Dispatch relay queues. It does not create a global cluster, replicate
|
||
Run state, elect leaders, fail over the home, schedule placement, or require agents to
|
||
carry server IDs after start.
|
||
</p>
|
||
</section>
|
||
|
||
<section id="skill">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Agent ergonomics</p>
|
||
<h2>The skill should be a cookbook, not a second help page.</h2>
|
||
<p>
|
||
<code>orca --help</code> already owns syntax and exhaustive flags. The skill should
|
||
teach judgment: which topology to choose, how to preserve parallelism, what the
|
||
command returns, and what not to create afterward.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="grid-3">
|
||
<div class="card">
|
||
<h3>Parallel fan-out</h3>
|
||
<p>Start every independent task first. Only then call <code>check --wait</code>.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Shared-worktree review</h3>
|
||
<p>Use the current worktree when sharing its exact state is useful.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Independent writers</h3>
|
||
<p>Create separate worktrees when a concrete checkout conflict calls for isolation.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Ask and reply</h3>
|
||
<p>Use a threaded question; continue other work while only that worker is blocked.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Read a full-screen agent</h3>
|
||
<p>Use <code>worker-read --dispatch</code>; Orca routes to the owning server.</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Replace safely</h3>
|
||
<p>Inspect the stop result before deciding where to start a replacement.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<p class="eyebrow">Move out of the skill</p>
|
||
<ul class="plain-list">
|
||
<li>Complete command and flag catalogs</li>
|
||
<li>Internal database and delivery terminology</li>
|
||
<li>Provider-specific internals before the common path</li>
|
||
<li>Large decision trees for features Orca does not implement</li>
|
||
</ul>
|
||
</div>
|
||
<div class="card">
|
||
<p class="eyebrow">Every recipe must say</p>
|
||
<ul class="plain-list">
|
||
<li>When the pattern is appropriate</li>
|
||
<li>What the command creates or reuses</li>
|
||
<li>Whether setup runs; if not, the concrete reason</li>
|
||
<li>How and when results return</li>
|
||
<li>The common misuse to avoid</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<details open style="margin-top: 20px">
|
||
<summary>Current Orca · parallel workers in the current worktree</summary>
|
||
<div>
|
||
<p>
|
||
Creates two fresh agent terminals; setup does not run. Create both tasks and both
|
||
terminals before waiting for readiness, then dispatch both before blocking. The
|
||
coordinator keeps checking until both expected Dispatches settle; one batch is not
|
||
assumed to contain both completions. Misuse: waiting for worker A before starting B.
|
||
</p>
|
||
<pre><code>orca orchestration task-create --spec "Audit message semantics" --json
|
||
orca orchestration task-create --spec "Audit transcript adapters" --json
|
||
orca terminal create --worktree active --title message-audit --command codex --json
|
||
orca terminal create --worktree active --title transcript-audit --command codex --json
|
||
orca terminal wait --terminal term_a --for tui-idle --timeout-ms 60000 --json
|
||
orca terminal wait --terminal term_b --for tui-idle --timeout-ms 60000 --json
|
||
orca orchestration dispatch --task task_a --to term_a --inject --json
|
||
orca orchestration dispatch --task task_b --to term_b --inject --json
|
||
|
||
# Repeat until task_a and task_b are both settled; process every returned message.
|
||
orca orchestration check --wait --timeout-ms 60000 --json</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Proposed Orca · same fan-out with composed worker start</summary>
|
||
<div>
|
||
<p>
|
||
Creates one bound Run and two fresh terminals in the existing worktree. Setup is
|
||
<code>not_applicable</code>. Each start returns ready, failed, or
|
||
<code>outcome_unknown</code>; independent calls may be issued in parallel. Worker
|
||
results arrive through the inbox. Misuse: creating another terminal after start.
|
||
</p>
|
||
<pre><code>orca orchestration run-create --objective "Improve orchestration ergonomics" --json
|
||
orca orchestration task-create --spec "Audit message semantics" --json
|
||
orca orchestration task-create --spec "Audit transcript adapters" --json</code></pre>
|
||
|
||
<div class="grid-2" style="margin-top: 14px">
|
||
<pre><code># Concurrent tool call A
|
||
orca orchestration worker-start --task task_a --worktree current --agent codex --json</code></pre>
|
||
<pre><code># Concurrent tool call B
|
||
orca orchestration worker-start --task task_b --worktree current --agent codex --json</code></pre>
|
||
</div>
|
||
|
||
<pre style="margin-top: 14px"><code># After both start calls return, loop; do not assume two waits or one batch is enough.
|
||
# Repeat process → ack → wait until both Dispatches are settled.
|
||
orca orchestration check --wait --timeout-ms 60000 --json
|
||
orca orchestration check --ack delivery_81 --wait --timeout-ms 60000 --json</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Mac coordinator + Windows worker · one Run across connected servers</summary>
|
||
<div>
|
||
<p>
|
||
The Run and inbox stay on the Mac. The first worker uses the Mac's current
|
||
worktree; the second creates a top-level worktree on the saved
|
||
<code>windows</code> Orca environment. Both report into the same inbox, including
|
||
after a temporary disconnect. Misuse: creating a second Run on Windows or asking
|
||
the worker to carry server/Run-home IDs.
|
||
</p>
|
||
<pre><code># On the Mac coordinator
|
||
orca orchestration run-create --objective "Audit both platforms" --json
|
||
orca orchestration task-create --spec "Audit macOS behavior" --json
|
||
orca orchestration task-create --spec "Audit Windows behavior" --json
|
||
|
||
# Read-only discovery happens against Windows; copy the opaque repo/worktree IDs returned.
|
||
orca --environment windows worktree list --json
|
||
|
||
# Issue these as independent concurrent tool calls, not as one sequential shell script.
|
||
orca orchestration worker-start --task task_mac --worktree current --agent codex --json
|
||
orca orchestration worker-start --task task_windows --on windows --worktree new-top-level --repo id:<windows-repo-id> --name windows-audit --agent codex --setup run --json
|
||
|
||
# One home wait fans in local and Windows messages. Repeat until both Dispatches settle.
|
||
orca orchestration check --wait --timeout-ms 60000 --json
|
||
orca orchestration check --ack delivery_81 --wait --timeout-ms 60000 --json
|
||
|
||
# Attempt-specific guidance uses the stable Dispatch, never the remote terminal handle.
|
||
orca orchestration send --to dispatch:dispatch_windows --subject "Follow-up" \
|
||
--body "Run the additional Windows-only check." --json</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Worker completion · success and failure are explicit</summary>
|
||
<div>
|
||
<p>
|
||
The injected preamble supplies the only Task and Dispatch IDs a worker copies.
|
||
Orca supplies its Dispatch capability automatically; the worker never supplies Run,
|
||
runtime, host, terminal, capability, or attestation IDs. Misuse: reporting failure as a
|
||
successful completion or inventing IDs from terminal history.
|
||
</p>
|
||
<pre><code># Success
|
||
orca orchestration send --type worker_done --subject "Review complete" \
|
||
--body "Audited the requested behavior. Found two issues and changed no files. Nothing remains." \
|
||
--task-id "<taskId from current preamble>" \
|
||
--dispatch-id "<dispatchId from current preamble>" \
|
||
--outcome succeeded --json
|
||
|
||
# Failure
|
||
orca orchestration send --type worker_done --subject "Review failed" \
|
||
--body "Could not read the required fixture. No findings are reliable. The fixture must be restored before retrying." \
|
||
--task-id "<taskId from current preamble>" \
|
||
--dispatch-id "<dispatchId from current preamble>" \
|
||
--outcome failed --json</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Worker question · ask defaults to its Run</summary>
|
||
<div>
|
||
<p>
|
||
An active worker asks its owning coordinator without carrying a Run ID. The
|
||
coordinator replies to the returned message ID while other work continues. Misuse:
|
||
creating a task gate or a second Question ID for a simple reply.
|
||
</p>
|
||
<pre><code># Worker
|
||
orca orchestration ask --question "Should I preserve the legacy format?" --json
|
||
|
||
# If acceptance may have happened but the response was lost, repeat the identical command with
|
||
# the orchestrationRequestId reported by the CLI as --retry-request.
|
||
orca orchestration ask --question "Should I preserve the legacy format?" --retry-request req_ask7 --json
|
||
|
||
# If a server disconnect timed out the wait, resume with the returned message ID.
|
||
orca orchestration ask --resume msg_question_7 --json
|
||
|
||
# Coordinator, after receiving msg_question_7
|
||
orca orchestration reply --id msg_question_7 --body "Yes; preserve it." --json</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>New child or top-level worktree · reuse the returned agent terminal</summary>
|
||
<div>
|
||
<p>
|
||
New worktrees run configured setup by default. Agent-first creation returns the
|
||
only worker terminal; configured extra tabs remain intentional. Use
|
||
<code>skip</code> or <code>inherit</code> only for a concrete stated reason. Misuse:
|
||
adding a second agent terminal because the startup receipt was not inspected.
|
||
</p>
|
||
<pre><code>orca orchestration worker-start --task task_a --worktree new-child --name message-audit --agent codex --setup run --json
|
||
orca orchestration worker-show --dispatch dispatch_7 --json
|
||
|
||
orca orchestration worker-start --task task_b --worktree new-top-level --name transcript-audit --agent claude --setup run --json
|
||
|
||
# Escape hatch: this task audits the pristine fixture, and setup would mutate that fixture.
|
||
orca orchestration worker-start --task task_fixture --worktree new-top-level --name fixture-only --agent codex --setup skip --json</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Intentional existing-terminal reuse</summary>
|
||
<div>
|
||
<p>
|
||
Reuses exactly the selected terminal and runs no setup. The terminal must belong to
|
||
the chosen worktree. Misuse: treating “an idle terminal somewhere” as equivalent.
|
||
</p>
|
||
<pre><code># Local existing worktree; copy the exact opaque IDs from worktree/terminal list.
|
||
orca orchestration worker-start --task task_a --worktree 'id:<full-worktree-id>' --terminal term_12 --json
|
||
|
||
# Remote existing worktree; --on is mandatory because V1 IDs are server-scoped.
|
||
orca --environment windows worktree list --json
|
||
orca orchestration worker-start --task task_b --on windows --worktree 'id:<full-windows-worktree-id>' --agent codex --json</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Remote uncertainty · branch on what inspection proves</summary>
|
||
<div>
|
||
<p>
|
||
An unknown start or stop is inspected by Dispatch ID; nothing is replayed merely
|
||
because a connection failed. Misuse: treating show → stop → abandon → retry as an
|
||
unconditional recovery sequence.
|
||
</p>
|
||
<pre><code># First recover the receipt for the exact request; this cannot create a second effect.
|
||
orca orchestration worker-start --task task_a --worktree new-child --name message-audit --agent codex --setup run --retry-request req_7 --json
|
||
|
||
# Then inspect the Dispatch if the outcome is still unknown.
|
||
orca orchestration worker-show --dispatch dispatch_7 --json
|
||
|
||
# If ready: keep the worker and wait for its result.
|
||
# If failed or stopped: start an explicit replacement, repeating the intended placement.
|
||
orca orchestration worker-start --task task_a --retry-of dispatch_7 --worktree current --agent codex --json
|
||
|
||
# If still unknown: stop and inspect again, or explicitly accept the warning and abandon.
|
||
orca orchestration worker-stop --dispatch dispatch_7 --json
|
||
orca orchestration worker-show --dispatch dispatch_7 --json
|
||
orca orchestration worker-abandon --dispatch dispatch_7 --json</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Restart recovery · home and worker server are independent</summary>
|
||
<div>
|
||
<p>
|
||
A Run-home restart preserves the Run, retry receipts, and the same unacknowledged
|
||
Delivery; <code>run-use</code> is needed only when Orca cannot safely remint the
|
||
previous coordinator pane. A worker-server restart preserves its Dispatch
|
||
attachment and relay queue but does not pretend the agent process survived.
|
||
Misuse: starting a replacement merely because a runtime ID changed.
|
||
</p>
|
||
<pre><code># Home restart: rebind only if run-current says this pane is unbound.
|
||
orca orchestration run-current --json
|
||
orca orchestration run-use --id run_123 --json
|
||
orca orchestration check --wait --timeout-ms 60000 --json
|
||
# → returns the same outstanding delivery_81 until it is acknowledged
|
||
|
||
# Worker-server restart: inspect the persisted attachment and exact process incarnation.
|
||
orca orchestration worker-show --dispatch dispatch_7 --json
|
||
# running/ready → keep waiting; gone/failed → explicit retry-of; unknown → inspect or stop/abandon.</code></pre>
|
||
</div>
|
||
</details>
|
||
|
||
<p class="principle">
|
||
The skill must say that <code>check --wait</code> returns a batch. Process every message
|
||
before acknowledging it.
|
||
</p>
|
||
|
||
<div class="card" style="margin-top: 20px">
|
||
<h3>Scenario tests matter more than keyword checks</h3>
|
||
<div class="grid-2" style="margin-top: 14px">
|
||
<ul class="plain-list" style="margin-top: 0">
|
||
<li>Reuse the terminal returned by worktree creation.</li>
|
||
<li>Start three independent workers before waiting.</li>
|
||
<li>Omit <code>runId</code> only when the coordinator terminal is explicitly bound.</li>
|
||
<li>Use current-worktree collaborators without unnecessary worktrees.</li>
|
||
<li>Fence an old consumer's acknowledgment after <code>run-use</code> rebinds.</li>
|
||
<li>Import duplicated and out-of-order relay frames only in contiguous order.</li>
|
||
</ul>
|
||
<ul class="plain-list" style="margin-top: 0">
|
||
<li>Never treat a worker report as verified integration.</li>
|
||
<li>Never replay terminal input after unknown acceptance.</li>
|
||
<li>Page terminal output by Dispatch; use a session source only when exact.</li>
|
||
<li>Inspect an ambiguous remote stop before choosing the next action.</li>
|
||
<li>Let the first committed stop/completion transition win transactionally.</li>
|
||
<li>Reject a re-paired peer and never adopt a same-looking restarted process.</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section id="scope-discipline">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Complexity audit</p>
|
||
<h2>Keep only the machinery required by Orca's concrete failure modes.</h2>
|
||
<p>
|
||
Every retained primitive below addresses a failure Orca can reproduce today. Broader
|
||
policy and product layers remain out of scope until a simpler primitive proves
|
||
insufficient in real use.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Observed Orca need</th>
|
||
<th>Keep</th>
|
||
<th>Deliberately defer</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Lifecycle messages can be lost, injected into prompts, or consumed before a caller receives them.</td>
|
||
<td>Durable typed mail, explicit acknowledgment, and race-free blocking waits.</td>
|
||
<td>Dead-letter workflows, priority schedulers, watchdog policy, or a second queue product.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Terminal scrollback is not always the best available source, but session identity can be ambiguous.</td>
|
||
<td>Terminal output as the baseline and an optional exact, source-pinned adapter.</td>
|
||
<td>A universal session ontology, resume layer, or global provider exclusivity.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Remote acceptance, process exit, and worker claims provide different levels of evidence.</td>
|
||
<td>Explicit lifecycle, fenced replacement, and typed unknown-outcome handling.</td>
|
||
<td>Automatic retry, inferred success, rollback, or generalized recovery policy.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>A Run home must coordinate workers across restarts and connected Orca servers.</td>
|
||
<td>Stable Run, Task, and Dispatch identity with authenticated server relay.</td>
|
||
<td>Role simulation, worker scoring, organization models, or integration queues.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3>Tests prove the contract</h3>
|
||
<p>
|
||
Scenario tests must demonstrate durable messages, authenticated relay, lifecycle
|
||
fencing, and truthful recovery. Design analogy is never a substitute for an
|
||
Orca-local executable contract.
|
||
</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Complexity requires local evidence</h3>
|
||
<p>
|
||
A generalized scheduler, fairness policy, dead-letter workflow, or integration
|
||
system should be proposed only after Orca users demonstrate that the simpler
|
||
primitives cannot solve a recurring problem.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<p class="footer-note" style="margin-top: 16px">
|
||
Blocking wait, crash-safe acknowledgment, and connected-server relay require
|
||
Orca-local implementation and tests. Structured output reuses Orca's exact
|
||
pane/process-to-provider-session association and existing bounded transcript decoders;
|
||
it does not introduce provider-session control or a universal transcript model.
|
||
</p>
|
||
</section>
|
||
|
||
<section id="roadmap">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Implementation order</p>
|
||
<h2>Each phase should remove one concrete source of agent confusion.</h2>
|
||
<p>
|
||
There is no UI phase. Each runtime change ships with a version-matched example and a
|
||
misuse test so the skill and behavior cannot drift apart.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="roadmap">
|
||
<div class="roadmap-item">
|
||
<div class="roadmap-meta">Phase 0</div>
|
||
<div>
|
||
<h3>Rewrite the orchestration skill as recipes</h3>
|
||
<p>
|
||
Teach correct fan-out, current versus new worktree selection, startup terminal
|
||
reuse, <code>--setup run</code> for new worktrees unless the agent states a
|
||
concrete reason to skip or inherit, while preserving the existing
|
||
<code>start-immediately</code> default, current batch behavior, and blocking only
|
||
after useful parallel work is exhausted. Correct the one-message claim and
|
||
document today's delivery limits.
|
||
Rename or remove the existing scheduler-like <code>orchestration run --spec</code>
|
||
command before the lightweight <code>run-*</code> vocabulary can ship.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="roadmap-item">
|
||
<div class="roadmap-meta">Phase 1</div>
|
||
<div>
|
||
<h3>Run mailbox, truthful completion, and crash-safe consumption</h3>
|
||
<p>
|
||
Add explicit Run-home binding, stable logical recipients, strict
|
||
inbox-only structured mail, succeeded/failed worker outcomes, one outstanding
|
||
FIFO batch, explicit acknowledgment, typed timeout results, ask/reply state,
|
||
a narrow runtime-minted Dispatch capability carried by the CLI bridge, and
|
||
resume-by-message-ID after a disconnected ask. Migrate existing global rows to
|
||
one unbound inspect-only legacy Run; do not infer bindings. Do not add separate
|
||
Question IDs or expiry policy.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="roadmap-item">
|
||
<div class="roadmap-meta">Phase 2</div>
|
||
<div>
|
||
<h3>Local synchronous worker start and control</h3>
|
||
<p>
|
||
On the Run home, compose existing worktree, setup, terminal, and dispatch
|
||
primitives with setup-run as the new-worktree default, a durable request/stage
|
||
receipt, side-by-side setup/agent startup by default, startup-terminal reuse,
|
||
exact readiness, and Dispatch-routed
|
||
show/read/stop/abandon. Prove current, existing,
|
||
child, top-level, failure, restart, and unknown-outcome behavior before adding a
|
||
network boundary. Do not add a background provisioning executor.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="roadmap-item">
|
||
<div class="roadmap-meta">Phase 3</div>
|
||
<div>
|
||
<h3>Connected-server Dispatch and relay</h3>
|
||
<p>
|
||
Extend the same primitives with saved-environment placement, pinned peer identity,
|
||
remote Dispatch attachments, paired-server calls, and bounded bidirectional relay
|
||
with contiguous cursors and idempotent acknowledgment. Validate Mac-home/Windows-
|
||
worker and Windows-home/Mac-worker completion, question/reply, read, stop,
|
||
either-side restart, re-pairing, disconnect, and mixed versions—without Run
|
||
replication, failover, or scheduling.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="roadmap-item">
|
||
<div class="roadmap-meta">Phase 4</div>
|
||
<div>
|
||
<h3>Exact structured worker output</h3>
|
||
<p>
|
||
Reuse Orca's existing pane-scoped hook association and bounded
|
||
Codex/Claude/OpenClaude/Grok transcript decoders. Add
|
||
<code>auto|transcript|terminal</code> selection,
|
||
path-free source identity, opaque source-pinned paging, and labeled terminal
|
||
fallback without adding provider control or a universal transcript layer.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="grid-2" style="margin-top: 20px">
|
||
<div class="card">
|
||
<h3>Success looks like</h3>
|
||
<ul class="plain-list">
|
||
<li>Agents start all independent work before waiting.</li>
|
||
<li>Lifecycle messages never flood editable coordinator input.</li>
|
||
<li>One Run can supervise Mac and Windows workers through one home inbox.</li>
|
||
<li>Remote completion and replies survive either server temporarily disconnecting.</li>
|
||
<li>No delivery is consumed before explicit acknowledgment.</li>
|
||
<li>Failed worker reports set failed—not completed—and remain worker assertions.</li>
|
||
<li>Worker start never reports a resource created before it exists.</li>
|
||
<li>Full-screen agent output remains readable when an adapter supports it.</li>
|
||
<li>Stale, wrong-pane, or wrong-server workers cannot mutate current task state.</li>
|
||
</ul>
|
||
</div>
|
||
<div class="card">
|
||
<h3>Complexity budget</h3>
|
||
<ul class="plain-list">
|
||
<li>No new concept without a common recipe that needs it.</li>
|
||
<li>No automatic action whose trigger an agent cannot explain.</li>
|
||
<li>No provider field that an adapter cannot actually observe.</li>
|
||
<li>No hidden default omitted from the operation receipt.</li>
|
||
<li>No control-plane fact derived from untrusted transcript prose.</li>
|
||
<li>No future feature included merely to keep the architecture open-ended.</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section id="non-goals">
|
||
<div class="section-heading">
|
||
<p class="eyebrow">Explicit boundaries</p>
|
||
<h2>What this proposal intentionally does not build.</h2>
|
||
<p>
|
||
These are not hidden later phases. They require separate evidence and a separate
|
||
proposal if Orca eventually needs them.
|
||
</p>
|
||
</div>
|
||
|
||
<div class="grid-2">
|
||
<div class="card">
|
||
<h3>No product UI</h3>
|
||
<ul class="plain-list">
|
||
<li>No dashboard or run/task view</li>
|
||
<li>No global inbox, badges, or queue screen</li>
|
||
<li>No coordinator chat surface</li>
|
||
<li>No task DAG visualization</li>
|
||
<li>No changes to existing Orca UI behavior</li>
|
||
</ul>
|
||
</div>
|
||
<div class="card">
|
||
<h3>No scheduler</h3>
|
||
<ul class="plain-list">
|
||
<li>No automatic task dispatch or placement</li>
|
||
<li>No capacity vectors or resource classes</li>
|
||
<li>No fairness, priority aging, or global queue</li>
|
||
<li>No pause, resume, or drain controls</li>
|
||
<li>No automatic retry based on silence</li>
|
||
</ul>
|
||
</div>
|
||
<div class="card">
|
||
<h3>No integration subsystem</h3>
|
||
<ul class="plain-list">
|
||
<li>No commit or branch tracking</li>
|
||
<li>No automatic merge or landing</li>
|
||
<li>No target-ref locking</li>
|
||
<li>No independent verification of worker claims</li>
|
||
<li>No cross-run work lineage model</li>
|
||
</ul>
|
||
</div>
|
||
<div class="card">
|
||
<h3>No speculative framework</h3>
|
||
<ul class="plain-list">
|
||
<li>No organization charts, roles, or worker profiles</li>
|
||
<li>No universal provider transcript schema</li>
|
||
<li>No dead-letter or poison-message workflow</li>
|
||
<li>No generalized continuation/checkpoint protocol</li>
|
||
<li>No project hierarchy above lightweight runs</li>
|
||
<li>No replicated Run database, leader election, or automatic home failover</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<details open style="margin-top: 20px">
|
||
<summary>Could Orca add these things later?</summary>
|
||
<div>
|
||
Yes, but strong primitives do not need speculative abstractions for them today. A
|
||
future feature should compose the same start, message, wait, read, stop, identity,
|
||
and ownership contracts. It should justify its own concepts from observed Orca use.
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Does removing commit tracking make worker results less trustworthy?</summary>
|
||
<div>
|
||
It makes the contract more honest. Today Orca verifies who is authorized to report a
|
||
result, not that every claim inside the result is true. A coordinator may explicitly
|
||
ask another worker to review or run validation. That is agent-directed orchestration,
|
||
not an implicit integration subsystem.
|
||
</div>
|
||
</details>
|
||
|
||
<details>
|
||
<summary>What about connecting multiple Orca runtime servers?</summary>
|
||
<div>
|
||
It is a core requirement. A Run stays authoritative on one home server while remote
|
||
Dispatches execute on saved connected environments such as a Windows machine.
|
||
Authenticated routing plus a small durable relay carries lifecycle mail and replies
|
||
across disconnects. This intentionally stops short of a global cluster: no Run
|
||
replication, leader election, automatic failover, distributed scheduler, or lease
|
||
manager is required.
|
||
</div>
|
||
</details>
|
||
|
||
<p class="footer-note" style="margin-top: 28px">
|
||
Phases 0–4 of this contract are implemented. Structured output is verified locally,
|
||
through a mixed-version terminal fallback, and across a Windows-home to Mac-worker
|
||
Dispatch; the remaining physical symmetry checks stay in the acceptance ledger. The
|
||
proposal makes no Orca product UI changes.
|
||
</p>
|
||
</section>
|
||
</div>
|
||
</main>
|
||
</div>
|
||
|
||
<script>
|
||
const root = document.documentElement
|
||
const themeButton = document.getElementById('theme-toggle')
|
||
const preferredDark = window.matchMedia('(prefers-color-scheme: dark)').matches
|
||
const storedTheme = window.localStorage.getItem('orca-orchestration-primitives-theme')
|
||
|
||
function applyTheme(theme) {
|
||
const dark = theme === 'dark'
|
||
root.classList.toggle('dark', dark)
|
||
themeButton.textContent = dark ? 'Use light theme' : 'Use dark theme'
|
||
}
|
||
|
||
applyTheme(storedTheme || (preferredDark ? 'dark' : 'light'))
|
||
|
||
themeButton.addEventListener('click', () => {
|
||
const nextTheme = root.classList.contains('dark') ? 'light' : 'dark'
|
||
window.localStorage.setItem('orca-orchestration-primitives-theme', nextTheme)
|
||
applyTheme(nextTheme)
|
||
})
|
||
|
||
const links = Array.from(document.querySelectorAll('.nav a'))
|
||
const sections = links
|
||
.map((link) => document.querySelector(link.getAttribute('href')))
|
||
.filter(Boolean)
|
||
|
||
const observer = new IntersectionObserver(
|
||
(entries) => {
|
||
const visible = entries
|
||
.filter((entry) => entry.isIntersecting)
|
||
.sort((a, b) => b.intersectionRatio - a.intersectionRatio)[0]
|
||
|
||
if (!visible) return
|
||
|
||
links.forEach((link) => {
|
||
const active = link.getAttribute('href') === '#' + visible.target.id
|
||
if (active) {
|
||
link.setAttribute('aria-current', 'true')
|
||
} else {
|
||
link.removeAttribute('aria-current')
|
||
}
|
||
})
|
||
},
|
||
{ rootMargin: '-15% 0px -70% 0px', threshold: [0, 0.1, 0.5] }
|
||
)
|
||
|
||
sections.forEach((section) => observer.observe(section))
|
||
</script>
|
||
</body>
|
||
</html>
|