@junghanacs/entwurf 0.18.2 → 0.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +179 -0
- package/README.md +3 -3
- package/VERIFY.md +1 -1
- package/docs/external-mcp-host.md +2 -2
- package/mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js +18 -7
- package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-fresh-call.js +76 -9
- package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-placement.js +54 -6
- package/mcp/entwurf-bridge/dist/pi-extensions/lib/resolve-tmux-session.js +114 -0
- package/mcp/entwurf-bridge/src/index.ts +22 -7
- package/package.json +1 -1
- package/pi-extensions/entwurf-control.ts +27 -3
- package/pi-extensions/lib/mux-fresh-call.ts +98 -11
- package/pi-extensions/lib/mux-placement.ts +65 -10
- package/pi-extensions/lib/resolve-tmux-session.ts +137 -0
- package/scripts/check-fresh-cut-gate.sh +54 -2
- package/scripts/check-gate-qualification.ts +4 -4
- package/scripts/check-mux-launch-tmux.ts +77 -2
- package/scripts/check-mux-launch.ts +17 -0
- package/scripts/check-mux-placement-tmux.ts +61 -1
- package/scripts/check-mux-placement.ts +33 -0
- package/scripts/mutants/fresh-cut.json +26 -0
- package/scripts/mutants/mux-boundary.json +24 -0
- package/scripts/mutants/mux-fresh-call.json +81 -0
- package/scripts/mutants/omp-birth.json +16 -3
- package/scripts/omp-bridge-doctor.sh +11 -1
- package/scripts/smoke-mux-fresh-call-live.ts +175 -3
- package/scripts/smoke-omp-bridge-state.sh +5 -2
package/AGENTS.md
CHANGED
|
@@ -30,7 +30,7 @@ For agents that own this repo: invariant principles and reproducible verificatio
|
|
|
30
30
|
- **pi adapter** attaches a pi session to a record at `session_start`, hosts the record-keyed control socket, and exposes the native pi tool surface.
|
|
31
31
|
- **Native bridges** register already-running native sessions without taking over their transcript or auth: Claude Code and Copilot CLI are mailbox/self-fetch (a Claude hook arms the watch; a forked Copilot extension holds it); Antigravity is probe-backed native-push. Codex has archived probe evidence, but its managed native lane was declined because pi already supplies the official GPT provider path; do not duplicate it as a native citizen or ACP backend.
|
|
32
32
|
- **ACP plugin** registers provider `entwurf` inside a pi host session and drives a backend under an isolated overlay. The host pi session is already a record-backed socket citizen; the plugin does not mint another citizen/socket/peer layer.
|
|
33
|
-
- **mux is launch-only and deliberately small.** Shipped: the tmux placement leaf (`mux-placement.ts` — inspect/append
|
|
33
|
+
- **mux is launch-only and deliberately small.** Shipped: the tmux placement leaf (`mux-placement.ts` — inspect/append in the caller's own session, close on its whole SERVER), the visible runtime launch composition (`mux-launch.ts`), the fresh-call composition (`mux-fresh-call.ts`), the cwd-aware resume placement composition (`mux-resume-call.ts`), and the import-free leaves they inject (`classify-tmux-cwd.ts`, `resolve-tmux-session.ts`). Fresh call is exposed as `entwurf_fresh_call`; visible same-id resume is `entwurf_resume_call`, composed at the two public surfaces by injecting `mux-resume-call` into the v2-side `entwurf-v2-visible-resume.ts`. The exact import graph is enumerated in [docs/mux-launch-rail.md](./docs/mux-launch-rail.md) §11. `entwurf_v2` behavior is unchanged and delivery still never imports launch. Fresh call learns a new sibling's garden id from the CALLBACK it makes, never from a lookup — so the pre-injected-token → identity-lookup design (rail §6) is **closed, not paused**. Do not reopen it without new evidence and explicit GLG re-approval. Fresh-call requires one explicit model and passes it in each runtime's measured CLI dialect (Pi `--model <provider/model>`, Claude Code `--model=<id-or-alias>`, Copilot `--model <name>` beside `--interactive <prompt>` and the explicit `--yolo` policy — a GLG width decision, 2026-08-25, after a callback-only `--allow-tool` grant stopped the sibling at every task tool); the Copilot backend opens through entwurf's OWN managed invocation (`entwurf copilot`), never the bare vendor, and its four required capabilities — birth, MCP hand, receiver, visible footer — are decided by `copilot-fresh-preflight.ts` BEFORE the tmux mutation, so a missing unit is a named refusal instead of a dead window; it also takes ONE optional literal absolute `cwd` (#73 — omitted/`""` means the caller's own directory; no trim, no realpath, no project-name resolver; classified by the shared `classify-tmux-cwd.ts` leaf; the receipt echoes the REQUEST only), so a cross-repo fresh sibling is a fresh-call fact and never a reason to resume a dormant record. It also takes ONE optional project seat, `placement.tmuxSession` (#105 — the exact name of an EXISTING session on the caller's OWN server, turned into a `$id` by `resolve-tmux-session.ts` before anything reaches `-t`). **It creates nothing** — `tmux-session-missing`/`tmux-session-name-invalid` are named refusals, no `ifMissing`/`new-session` axis exists (GLG, 2026-09-07), seat and cwd never infer each other, and close binds to the SERVER half since a placed window may sit outside the caller's session. Resume takes only an existing target id and gets transcript/model/provider/cwd from its record. Do not grow either narrow carrier into a generic driver, harness profile, arbitrary command/env selection, or a second creation API. Ownership and import prohibitions: [docs/mux-launch-rail.md](./docs/mux-launch-rail.md) §11.
|
|
34
34
|
- **One delivery verb:** `entwurf_v2` addresses an existing garden id. Current routes are live control-socket send, active self-fetch mailbox enqueue, and probe-alive native-push. NO route starts a process: the hidden background resume for a dormant citizen was withdrawn under the visible-first rule, so a dormant in-domain citizen rejects as `dormant-fire-forget-unsupported` and the intent axis is single-valued. Every other complementary state pair rejects honestly too. Fresh creation is a separate verb — `entwurf_fresh_call` — and it returns a launch receipt only; the new sibling's address arrives asynchronously as the sender envelope of its nonce callback.
|
|
35
35
|
|
|
36
36
|
## Hard Rules
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,185 @@ All notable changes to this project will be documented here. Format follows [Kee
|
|
|
4
4
|
|
|
5
5
|
## Unreleased
|
|
6
6
|
|
|
7
|
+
## 0.19.0 - 2026-09-07
|
|
8
|
+
|
|
9
|
+
One lane: #105 slice ①, the project seat. `entwurf_fresh_call` gains an optional
|
|
10
|
+
`placement.tmuxSession` so a fresh sibling can open in the operator's project session instead of the
|
|
11
|
+
caller's own, and `closeWindow` binds to the server half so a window placed elsewhere can still be
|
|
12
|
+
closed by its handle. Minor rather than patch: an optional input appears on all three public
|
|
13
|
+
surfaces at once and a shipped contract moves. Slices ② (no-turn retirement) and ③ (remote routing)
|
|
14
|
+
did not ship and were carried out of the issue intact before it closed, so nothing about them is
|
|
15
|
+
inferred from what landed here.
|
|
16
|
+
|
|
17
|
+
It also carries two repairs that were not planned: verifying this release ran the deterministic floor
|
|
18
|
+
often enough to expose a defect class the repo had already written down and not finished applying —
|
|
19
|
+
an early-exiting `grep -q` whose producer dies of SIGPIPE, which `pipefail` then promotes into the
|
|
20
|
+
CLEAN branch of an `if`. One instance was a shipped operator doctor; the other was a credential
|
|
21
|
+
tripwire that had been dead since it was written.
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- **One project seat: `placement: { tmuxSession }` (#105).** The exact name of an EXISTING session
|
|
26
|
+
on the caller's own tmux server. **It creates nothing** — an absent session is
|
|
27
|
+
`tmux-session-missing`, a name outside `[A-Za-z0-9][A-Za-z0-9_-]*` is `tmux-session-name-invalid`,
|
|
28
|
+
and both leave no window and no session behind. There is no `ifMissing`/`create` axis and no
|
|
29
|
+
`new-session` verb anywhere in the product (GLG, 2026-09-07: "없으면 reject … 다 자동화하면
|
|
30
|
+
테스트·검증 비용이 커진다"). The operator makes the seat and calls again. Omitting `placement`
|
|
31
|
+
keeps today's behaviour exactly.
|
|
32
|
+
- **`pi-extensions/lib/resolve-tmux-session.ts`** — an import-free leaf owning the name grammar and
|
|
33
|
+
the name → native `$id` lookup, with its tmux runner injected so it cannot run tmux itself. The
|
|
34
|
+
engine is `list-windows -t '=NAME' -F '#{session_id}'` with absence read from the exit code, and
|
|
35
|
+
every rule in its header is a measured tmux 3.6a behaviour: the `-f` filter engine matched **every**
|
|
36
|
+
session when a name contained `}` (6/6), `display-message -p -t '=NAME'` answers rc=0 with empty
|
|
37
|
+
output for a name that does not exist, `#` is format-expanded when the name is stored, `.` and `:`
|
|
38
|
+
are tmux's own pane/window separators inside a target, and a session NAMED `$0` loses to the id
|
|
39
|
+
`$0`. Only the resolved id ever reaches `-t`.
|
|
40
|
+
- **Nine kill-qualified claims and their exact-once replants, inventory 373 → 382:**
|
|
41
|
+
`TMUXSESSION-LOOKUP-ENGINE`, `TMUXSESSION-NAME-GRAMMAR`, `RESOLVE-TMUX-SESSION-IMPORT-FREE`,
|
|
42
|
+
`FRESHCALL-PLACEMENT-MISSING-REJECTS`, `FRESHCALL-PLACEMENT-TARGET-ARGV`,
|
|
43
|
+
`FRESHCALL-PLACEMENT-RECEIPT-TARGET`, `FRESHCALL-PLACEMENT-SURFACE-PARITY`,
|
|
44
|
+
`FRESHCALL-PLACEMENT-BACKEND-PARITY` and `MUX-CLOSE-SERVER-BOUND`.
|
|
45
|
+
|
|
46
|
+
### Changed
|
|
47
|
+
|
|
48
|
+
- **`closeWindow` binds to the SERVER half (`requireSameServer`), not the session.** A placed window
|
|
49
|
+
may legitimately live outside the caller's session, so the old handle↔now context check would have
|
|
50
|
+
refused a normal close. The session half was measured to add no protection and real harm: window
|
|
51
|
+
ids are never reused within one server's lifetime (`@1` killed → next is `@2`; a whole session
|
|
52
|
+
killed → the counter still moves), so a vanished session's handle already reaches the existing
|
|
53
|
+
`already-gone` outcome, and a session clause would have turned that into a throw. `isSameContext` /
|
|
54
|
+
`requireSameContext` are untouched and still guard `appendWindow` / `launchPi`.
|
|
55
|
+
- **The seat is stated the same way on every surface an operator reads.** A documentation review
|
|
56
|
+
(pi `grok-4.6`) read README, the skill and the tool schema as three independent readers and found
|
|
57
|
+
five places where each was correct alone but a caller reading only one got the seat wrong — the
|
|
58
|
+
README's v2 section did not mention the seat at all, `docs/external-mcp-host.md` advertised the
|
|
59
|
+
verb as `{backend, model, task, cwd?}`, "an absent one is refused" read equally as an absent
|
|
60
|
+
session and an omitted placement, and the grammar lived only inside a schema `describe`. The most
|
|
61
|
+
expensive misreading had no positive statement anywhere: **naming the `org` seat does not put the
|
|
62
|
+
sibling in the `org` directory.** That is now said as a fact, not as a prohibition.
|
|
63
|
+
- **A symlinked `cwd` shows two spellings of one place, and the docs now say so.** entwurf never
|
|
64
|
+
resolves the path — it hands the literal string to tmux — so the launch receipt echoes what was
|
|
65
|
+
requested while the record, the transcript path, the callback envelope and `pane_current_path` all
|
|
66
|
+
carry what the OS resolved it to. The resolved one is what `entwurf_resume_call` later reopens,
|
|
67
|
+
which is why recording it that way is load-bearing rather than incidental.
|
|
68
|
+
|
|
69
|
+
### Fixed
|
|
70
|
+
|
|
71
|
+
- **`entwurf doctor-omp-bridge` could report a contaminated omp process as clean.** Its carrier scan
|
|
72
|
+
read `/proc/<pid>/environ` through `tr '\0' '\n' | grep -qE …` under `set -o pipefail`. `grep -q`
|
|
73
|
+
exits at the FIRST match and closes the pipe; `tr` — still writing the rest of a ~12 KB environ —
|
|
74
|
+
dies of SIGPIPE (141); `pipefail` makes that the pipeline's status, and the `if` takes the clean
|
|
75
|
+
branch. So a live omp session whose MCP children would speak under a PARENT pi citizen's garden id
|
|
76
|
+
was reported as no contamination, and the doctor printed PASS. It is a race on how far `tr` got, so
|
|
77
|
+
it read as flakiness rather than a defect: measured on one live fixture at 5–15% of reads depending
|
|
78
|
+
on load (6/40 and 1/40 in two independent measurements; 0/40 with `pipefail` off, and the shipped
|
|
79
|
+
doctor answered PASS on 3 of 60 runs against a genuinely contaminated fixture). The scan now counts
|
|
80
|
+
with `grep -c`, which consumes all of stdin, so there is no early close and nothing to race. The
|
|
81
|
+
predicate itself is unchanged byte-for-byte — `grep -qz` would have removed the pipeline entirely
|
|
82
|
+
but also quietly changes what counts as a carrier in both directions (a `PI_SESSION_ID=` inside
|
|
83
|
+
another variable's value; a value containing a newline), so transport was fixed and contract left
|
|
84
|
+
alone. `smoke-omp-bridge-state`'s own `wait_carrier` carried the same shape, where it cost only a
|
|
85
|
+
retry, and was fixed with it.
|
|
86
|
+
- **The `sync_auth` credential tripwire had never been able to fire (`check-fresh-cut-gate` D4b).**
|
|
87
|
+
Same cause, deterministic rather than racy: the producer is `awk` over a 433 KB `run.sh` emitting
|
|
88
|
+
~229 KB, so an early-exiting `grep -q` guarantees SIGPIPE. Measured with one `sync_auth` line
|
|
89
|
+
injected as code into a copy of `run.sh`: the pipeline exited 141 on **100 of 100** runs and the
|
|
90
|
+
gate printed `ok — no sync_auth credential surface remains`, while a clean `run.sh` exits 1 and is
|
|
91
|
+
correctly green. The tripwire was blind exactly when it had something to catch, which is why a
|
|
92
|
+
green floor never revealed it. After the repair the injected copy fires 50/50 and the clean copy
|
|
93
|
+
stays silent. D7 — the cell that forbids an install from cutting a generation by itself — carried
|
|
94
|
+
the same shape and is under one pipe buffer today, so it had no SIGPIPE window; that is a size
|
|
95
|
+
coincidence rather than a property, and it was counted too.
|
|
96
|
+
|
|
97
|
+
### Verification
|
|
98
|
+
|
|
99
|
+
All on oracle (Linux, node 24.18.1, pi 0.85.1, tmux 3.6a).
|
|
100
|
+
|
|
101
|
+
- **`LIVE=1 ./run.sh release-gate /tmp/entwurf-release-gate-0.19.0.0HsnIq --cut` → `cut: OK`.**
|
|
102
|
+
**MUST: PASS=23 FAIL=0 SKIP=0**, BEHAVIOR: PASS=1 FAIL=0 SKIP=0, exit 0, 06:06:31→07:05:45
|
|
103
|
+
(59m14s). `check-gate-qualification` as its MUST step: **385/385 KILLED**. `pnpm run check:full`
|
|
104
|
+
inside it: exit 0, 507s.
|
|
105
|
+
- **`check-gate-qualification` 381/381 KILLED** on the frozen `a39b637` candidate;
|
|
106
|
+
`pnpm run check:full` exit 0 (554s).
|
|
107
|
+
- **`LIVE=1 ./run.sh smoke-mux-fresh-call-live` 39/39** — four launches covering the
|
|
108
|
+
{cwd omitted, cwd requested} × {caller session, seat} matrix, reading `pane_current_path` by stable
|
|
109
|
+
pane id after a settle delay, with the seat session's own `session_path` a fourth directory no cell
|
|
110
|
+
may land in. On-demand, not a release MUST (VERIFY.md).
|
|
111
|
+
- **`check-mux-launch-tmux` 36** including a real-tmux seat cell that calls production
|
|
112
|
+
`freshCall`/`closeWindow` against a second session on a private server; `check-mux-fresh-call`
|
|
113
|
+
186/186; `check-gate-manifests` 383 mutants across 40 lanes.
|
|
114
|
+
- **For the two repairs above:** `smoke-omp-bridge-state` 20 consecutive green runs (it was 1 red in
|
|
115
|
+
5 before) and `check-fresh-cut-gate` 169/169 with its two new self-test cells. Three replants,
|
|
116
|
+
inventory 383 → 385, each KILLED 3/3 deterministically at its own signature:
|
|
117
|
+
`OMP-DOCTOR-CARRIER-NONBLANK-IS-RED`, `FRESHCUT-SYNCAUTH-TRIPWIRE-FIRES` and
|
|
118
|
+
`FRESHCUT-PREFLIGHT-CUT-DETECTED`. The middle one replants the ACTUAL defect — `grep -c` back to
|
|
119
|
+
`grep -q` — and that is only a valid replant because the self-test plants its surface early in a
|
|
120
|
+
file far larger than the pipe buffer, which makes the SIGPIPE deterministic. The omp one cannot be
|
|
121
|
+
written that way: there the same restoration fails only ~15% of runs and would SURVIVE
|
|
122
|
+
qualification, so it makes the identical false-clean deterministic by another route. Same defect,
|
|
123
|
+
two replant strategies, and the difference is recorded in the manifests rather than smoothed over.
|
|
124
|
+
|
|
125
|
+
### Notes
|
|
126
|
+
|
|
127
|
+
- **The seat's first pass over the real MCP wire was the operator's, not a gate's.** Both mux LIVE
|
|
128
|
+
smokes were blind to that seam by construction: `smoke-mux-fresh-call-live` imports `freshCall` and
|
|
129
|
+
calls it directly, and `smoke-mux-lifecycle-live` does enter through `tools/call` but passes no
|
|
130
|
+
`placement`. Between them the bridge handler's pass-through was proven by a tools/list schema and a
|
|
131
|
+
source regex — by construction, never by execution. GLG's hand-driven review on 2026-09-07 closed
|
|
132
|
+
that: four `tools/call entwurf_fresh_call` invocations (seat, seat + cwd, absent session, off-grammar
|
|
133
|
+
name), receipts read as receipts, with the whole-server `list-windows -a` byte-identical across both
|
|
134
|
+
refusals and exactly one added line across the successes.
|
|
135
|
+
- **Every seat assertion this repo owned was written against `pi`.** The unit block, the real-tmux
|
|
136
|
+
seat cell and both LIVE seat cells all passed `backend: "pi"`, so a later branch making the seat a
|
|
137
|
+
pi-only input would have gone unnoticed — while the cwd axis (#73) had carried four-backend parity
|
|
138
|
+
since it landed. The production path was already uniform (the seat becomes `targetSessionId`, the
|
|
139
|
+
backend becomes `backendArgs`, and `buildFreshCallArgs` takes them as separate parameters); what was
|
|
140
|
+
missing was an oracle saying so. `FRESHCALL-PLACEMENT-BACKEND-PARITY` is that oracle, and
|
|
141
|
+
`check-gate-manifests` caught the omission that came with it — a manifest set that drifted from its
|
|
142
|
+
declared inventory is red before any mutant runs.
|
|
143
|
+
- **Two ceilings are close enough to name.** The composed ACP first-user augment sits **311 bytes**
|
|
144
|
+
under its 50 KB cap (measured: 50,889 / 51,200 with the shipped repo AGENTS.md plus a 12 KB global
|
|
145
|
+
baseline), and the MCP `entwurf_fresh_call` description sits **28 chars** under the 2048-char host
|
|
146
|
+
cap (measured: 2020). The first already bit once during this lane: the initial qualification run
|
|
147
|
+
went CONTROL-RED on `check-acp-carrier-augment` because the feature's +1207 B to AGENTS.md breached
|
|
148
|
+
a cap that had 932 B of headroom, and the text was compressed to +616 B rather than the cap moved.
|
|
149
|
+
Neither number is a gate threshold to tune; both are room that the next lane has to spend
|
|
150
|
+
deliberately.
|
|
151
|
+
- **Independent review is where the second defect came from.** A `zai/glm-5.3` sibling was asked to
|
|
152
|
+
review the doctor repair and to try to disprove it, reproducing everything in an isolated snapshot
|
|
153
|
+
rather than trusting the implementer's summary. It confirmed the mechanism, corrected two claims —
|
|
154
|
+
the measured miss rate is load-dependent rather than a fixed 15%, and Copilot's immunity comes from
|
|
155
|
+
a TypeScript `readFileSync` reader rather than the Python one that was asserted — rejected the
|
|
156
|
+
`grep -qz` alternative on evidence the implementer did not have, and then found the dead credential
|
|
157
|
+
tripwire, which is the more severe of the two and was in a different lane entirely.
|
|
158
|
+
- **A forbidding cell that is green on a clean tree cannot tell blindness from compliance.** That is
|
|
159
|
+
why D4b was dead for as long as it was: it printed `ok` on every run this repo ever took, and it
|
|
160
|
+
would have printed `ok` on the run that mattered. Both cells now carry a self-test that plants the
|
|
161
|
+
thing they forbid and requires the SAME predicate — factored into a function precisely so a
|
|
162
|
+
re-typed copy cannot keep passing while the real one goes blind — to see it. The `sync_auth` plant
|
|
163
|
+
goes near the TOP of the real 433 KB `run.sh` rather than into a small synthetic fixture, because
|
|
164
|
+
the defect only exists when the consumer can exit while the producer still has bulk to write; a
|
|
165
|
+
tidy fixture would pass under the very mutant that must kill it.
|
|
166
|
+
- **A MUST gate can fail with the wiring intact.** `smoke-mux-lifecycle-live` is release-blocking on
|
|
167
|
+
the stated ground that a gate which TELLS the model which tool to call owns its own failures. This
|
|
168
|
+
cut met the case that rule does not describe: the wiring delivered perfectly — launch receipt, a
|
|
169
|
+
born citizen with its own garden id, the mandated first-action prompt verbatim on the visible pane —
|
|
170
|
+
and the model spent its one turn advising the operator to go to bed instead of calling back. Twice,
|
|
171
|
+
at 00:00 and 01:04, with the same cause and different wording, then green on the first daytime run.
|
|
172
|
+
Nothing was changed to make it pass: adjusting a shipped prompt to a current model's habit would
|
|
173
|
+
outlive the habit. Recorded because "MUST because failure is ours" now has a measured exception.
|
|
174
|
+
- **The long-command discipline earned its receipt.** The harness low-memory watchdog killed a
|
|
175
|
+
background tool call mid-cut while `free` reported 7 GB available and the kernel logged no OOM —
|
|
176
|
+
the lead recorded in 0.18.0's notes, met directly on a release lane for the first time. The gate
|
|
177
|
+
itself, running under tmux, was untouched every time. "Long commands go in tmux" stops being a
|
|
178
|
+
preference at that point.
|
|
179
|
+
- **An agent asking tmux where it is will answer wrong from a seat.** A seated sibling is opened
|
|
180
|
+
detached, so `tmux display-message -p` without `-t "$TMUX_PANE"` resolves to the target session's
|
|
181
|
+
ACTIVE window, not the sibling's own — measured, while the carrier itself was correct
|
|
182
|
+
(`TMUX_PANE=%181` in the process env). entwurf's own facts are unaffected: the launch receipt and
|
|
183
|
+
`list-windows` both name the right window. This is an agent-instruction gap and is tracked outside
|
|
184
|
+
this repo (junghan0611/sorge#7).
|
|
185
|
+
|
|
7
186
|
## 0.18.2 - 2026-09-07
|
|
8
187
|
|
|
9
188
|
One lane: #103, the second stage of the CI evidence budget (#99). The mutant body — 373 replants,
|
package/README.md
CHANGED
|
@@ -19,7 +19,7 @@ Claude Code / Copilot / Codex / agy / omp / pi
|
|
|
19
19
|
→ control-socket | meta-mailbox | native-push
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
[`entwurf_v2`](#entwurf_v2--canonical-dispatch-verb) is the canonical dispatch surface over *existing* garden citizens — live control-socket send, meta-mailbox enqueue, and native-push into a live Antigravity conversation. It starts no process on any rail: the hidden background resume that used to answer a dormant target was withdrawn under the visible-first rule, so a dormant citizen rejects honestly here and is reopened by a separate lifecycle verb, `entwurf_resume_call`. The meta-record is the sole address authority (#50 C4): a record-less control socket is refused as a `record-less-socket` diagnostic, never dispatched. The v1 entwurf verbs are gone. Fresh siblings and resumes are separate verbs — `entwurf_fresh_call` opens a NEW sibling in the operator's own
|
|
22
|
+
[`entwurf_v2`](#entwurf_v2--canonical-dispatch-verb) is the canonical dispatch surface over *existing* garden citizens — live control-socket send, meta-mailbox enqueue, and native-push into a live Antigravity conversation. It starts no process on any rail: the hidden background resume that used to answer a dormant target was withdrawn under the visible-first rule, so a dormant citizen rejects honestly here and is reopened by a separate lifecycle verb, `entwurf_resume_call`. The meta-record is the sole address authority (#50 C4): a record-less control socket is refused as a `record-less-socket` diagnostic, never dispatched. The v1 entwurf verbs are gone. Fresh siblings and resumes are separate verbs — `entwurf_fresh_call` opens a NEW sibling in the operator's tmux — the caller's own session, or one existing named session on the same server — and learns its garden id from the callback it makes, while `entwurf_resume_call` reopens a DORMANT pi citizen under its own garden id in a visible window without running a turn; the non-Claude ACP lane landed earlier — Snowflake Cortex Code became the second backend in 0.13.0.
|
|
23
23
|
|
|
24
24
|
**Garden id is deliberate vocabulary.** It is not a decorative synonym for session id, worker, delegate, or subagent. The unfamiliar word is a guard: each harness keeps its own identity and transcript, while `entwurf` supplies a narrow addressable surface between siblings.
|
|
25
25
|
|
|
@@ -513,7 +513,7 @@ A two-pane recording covers the pre-0.12 v1 surface end-to-end — sibling resum
|
|
|
513
513
|
|
|
514
514
|
Live peer messaging carries a sender envelope `{ sessionId, agentId, cwd, timestamp, origin?, replyable? }`; `entwurf_self` returns that authoritative envelope for the current pi session or trusted meta-session. Plain external MCP hosts are non-replyable. A garden-native meta-session carries a trusted `meta-session` envelope, but **`replyable` is a fact its own rail decides, not a consequence of being trusted** — a self-fetch citizen needs a live armed receiver, a native-push citizen needs an alive adapter probe, and a pi session needs its control socket. `entwurf_self` also reports which rail a meta-session reply would ride, because a native-push citizen has no mailbox to name. `wants_reply` is an etiquette marker rendered as a `(wants reply)` badge — not a transport contract, no wait, no polling. **v2 never gates on it:** a `wants_reply` from an external/non-replyable caller is passed through and surfaced honestly beside that sender's `replyable: false`, not rejected — the decider routes on target + intent, never on sender replyability. (The retired v1 `entwurf_send` did reject it; that behaviour went with the verb.)
|
|
515
515
|
|
|
516
|
-
In ACP-backed and external native-harness sessions, `entwurf-bridge` exposes seven tools: `entwurf_v2`, `entwurf_peers`, `entwurf_fresh_call`, `entwurf_resume_call`, `entwurf_self`, `entwurf_inbox_read`, and the explicit/manual `entwurf_register_native` fallback. Native pi exposes the shared capability directly through the extension surface (`entwurf_v2`, `entwurf_peers`, `entwurf_fresh_call`, `entwurf_resume_call` tools; the socket-scan `/entwurf-sessions` command is gone — #50 C4). **For garden-id delivery/reply use `entwurf_v2`** — the canonical surface that classifies the target and routes to live-pi / self-fetch meta-mailbox (Claude Code, Copilot, OMP) / Antigravity-native-push, and refuses a dormant target instead of waking it. **To open a sibling that does not exist yet use `entwurf_fresh_call`** — it launches one fixed backend (`pi`, `claude-code`, `copilot`, or `omp`) as a visible window
|
|
516
|
+
In ACP-backed and external native-harness sessions, `entwurf-bridge` exposes seven tools: `entwurf_v2`, `entwurf_peers`, `entwurf_fresh_call`, `entwurf_resume_call`, `entwurf_self`, `entwurf_inbox_read`, and the explicit/manual `entwurf_register_native` fallback. Native pi exposes the shared capability directly through the extension surface (`entwurf_v2`, `entwurf_peers`, `entwurf_fresh_call`, `entwurf_resume_call` tools; the socket-scan `/entwurf-sessions` command is gone — #50 C4). **For garden-id delivery/reply use `entwurf_v2`** — the canonical surface that classifies the target and routes to live-pi / self-fetch meta-mailbox (Claude Code, Copilot, OMP) / Antigravity-native-push, and refuses a dormant target instead of waking it. **To open a sibling that does not exist yet use `entwurf_fresh_call`** — it launches one fixed backend (`pi`, `claude-code`, `copilot`, or `omp`) as a visible window on the operator's own tmux server, requires an explicit model, accepts one optional literal absolute `cwd` (omit it or pass `""` to use the caller's cwd) and one optional `placement.tmuxSession` naming an EXISTING session on that server to open the sibling in instead of the caller's own (the operator's project seat — nothing is ever created: an absent session is `tmux-session-missing` and a name outside the addressed grammar `[A-Za-z0-9][A-Za-z0-9_-]*` is `tmux-session-name-invalid`, with no window and no session left behind. The two inputs never infer each other, and the positive form of that matters more than the prohibition: **with `cwd` omitted, a seated sibling starts in THIS agent's own working directory**, measured — it does not inherit the target session's path or its active pane, so naming the `org` seat does not put the sibling in the `org` project. Pass `cwd` when you want a different directory. entwurf never resolves that path: it hands the literal string to tmux, so with a SYMLINKED directory the receipt echoes what you asked for while the record, the transcript path, the callback envelope and `pane_current_path` all show the path the OS resolved it to — two spellings of one place, and the resolved one is what `entwurf_resume_call` later reopens), passes the model and selected directory through the runtime's visible launch path, and hands it a first task; a `copilot` launch goes through entwurf's own managed invocation and is refused before any window opens if this host lacks the Copilot birth, MCP, receiver or visible-footer units, and an `omp` launch carries its task in the `--entwurf-bootstrap` payload instead of an argv prompt because that vendor connects its MCP tools after the session has already started. The sibling's first action is a nonce callback whose sender envelope carries its garden id. The launch receipt records the requested model/cwd/seat plus tmux coordinates — including the RESOLVED target session id, which is where the window actually is — and never claims that the runtime accepted them or completed delivery. (The v1 verbs `entwurf` / `entwurf_resume` / `entwurf_send` are gone.) Garden-native operator commands require `--entwurf-control`. There is no spawn target allowlist — the target registry is gone (#50 C3): `entwurf_v2` and `entwurf_resume_call` address an existing record-backed citizen, while `entwurf_fresh_call` takes its explicit backend/model/task and optional cwd directly rather than resolving a model tuple from a registry file. **To reopen a DORMANT pi citizen use `entwurf_resume_call {target}`** — the record supplies transcript, model, provider and cwd, so it takes no prompt, no task and no model override; it runs no turn, returns a LAUNCH receipt and a separate OBSERVATION receipt (only the second says the citizen is back), refuses a non-pi target as `target-not-pi`, and on an unobserved socket leaves the visible window open and releases its lock rather than retrying.
|
|
517
517
|
|
|
518
518
|
### `entwurf_v2` — canonical dispatch verb
|
|
519
519
|
|
|
@@ -532,7 +532,7 @@ In ACP-backed and external native-harness sessions, `entwurf-bridge` exposes sev
|
|
|
532
532
|
|
|
533
533
|
**`entwurf_v2` is the canonical surface for garden-id delivery.** When you have a garden id and want to reach whoever it names — message, reply, or hand-off — `entwurf_v2` is the one surface that reads whether the target is live pi, dormant pi, mailbox-backed Claude Code, Copilot or OMP, or native-push Antigravity and routes correctly; *when unsure which transport, use `entwurf_v2`*. This prevents callers from guessing a rail from the shape of an id.
|
|
534
534
|
|
|
535
|
-
What v2 provides is a **deterministic dispatch substrate** that moves the "which transport?" decision out of the fallible caller/model and into the decider, with transport-appropriate locking and an honest reject (no `✓ delivered`, no `.msg` garbage) when a target cannot receive. It still does **not** mint siblings, and it does not relaunch one either: every row above either reaches a citizen that is already running or refuses. Reopening a dormant pi citizen is `entwurf_resume_call`, a separate lifecycle verb that never routes through this decider. Fresh creation is the separate `entwurf_fresh_call` verb. It opens one fixed Pi, Claude Code, Copilot or OMP runtime visibly
|
|
535
|
+
What v2 provides is a **deterministic dispatch substrate** that moves the "which transport?" decision out of the fallible caller/model and into the decider, with transport-appropriate locking and an honest reject (no `✓ delivered`, no `.msg` garbage) when a target cannot receive. It still does **not** mint siblings, and it does not relaunch one either: every row above either reaches a citizen that is already running or refuses. Reopening a dormant pi citizen is `entwurf_resume_call`, a separate lifecycle verb that never routes through this decider. Fresh creation is the separate `entwurf_fresh_call` verb. It opens one fixed Pi, Claude Code, Copilot or OMP runtime visibly on the caller's tmux server — its own session by default, or one EXISTING named session via the optional `placement.tmuxSession` — with a required explicit model passed in that runtime's measured CLI dialect and one optional literal absolute `cwd`; omitted or `""` means the caller's cwd. Copilot opens through `entwurf copilot`, never the bare vendor; OMP is the opposite — the bare `omp` runtime with no positional prompt at all, because that vendor connects its MCP tools after the session has started, so the task rides a two-stage `--entwurf-bootstrap` payload the installed birth extension releases once the callback tool has actually answered. It returns only a synchronous launch receipt and lets the sibling report its new address asynchronously through the sender envelope of a nonce callback. Use this cwd input for a new cross-repository sibling; do not resume a dormant citizen as a cwd substitute. The meta-mailbox row requires an **active** self-fetch receiver; native-push requires a record-backed, probe-alive native conversation and never borrows mailbox state. The [mux launch lane](./docs/mux-launch-rail.md) owns placement, fixed-runtime launch, and the two narrow compositions above it (fresh-call and resume-call placement); delivery does not import launch, and mux is not a delivery transport.
|
|
536
536
|
|
|
537
537
|
A live pi target is *reached* over its control socket, but the socket is dispatch-internal transport, never identity (#50 C4). A control socket that no meta-record claims — a pre-record-era resident, an unreadable store, or a stale/planted file — is refused for **every** intent as `record-less-socket`, and the reject names the fix (restart the resident so `session_start` births its record, or quiesce and run the fresh-cut). `entwurf_peers` reports the same state as an aggregated `record-less-socket` diagnostic rather than a peer row.
|
|
538
538
|
|
package/VERIFY.md
CHANGED
|
@@ -58,7 +58,7 @@ Verification here is not a benchmark. In production we exchange short turns and
|
|
|
58
58
|
>
|
|
59
59
|
> Be honest about its cost, because it is a MUST: it spends real model turns on the operator's configured runtimes (two pi siblings, each resumed once, plus one Claude Code sibling), it READS the operator's real runtime config, and the siblings' native session transcripts stay in the real pi agent dir — they are not cleaned up, and they are part of the evidence a resume was real. The fence is per-axis rather than absolute: the four meta roots (records, mailbox, receivers, senders) are fixture for every cell, so no garden record is ever minted outside it; the native pi cell's control socket and v2 lock are fixture too; the ACP pi cell's are REAL and transient (see the paragraph above); and the Claude cell runs its runtime under the real HOME while its mailbox and meta stay fixture. The run ends by proving the operator's SIX real roots — the four meta roots plus `~/.pi/entwurf-control` and `~/.pi/entwurf-v2-locks` — hold the entry sets they started with, with no fixture garden id anywhere, and that proof now runs on the failure path as well as the green one. Missing prerequisites decline with the protocol SKIP (97), which `release-gate --cut` refuses rather than rounding up.
|
|
60
60
|
>
|
|
61
|
-
> **Fresh-call LIVE is on-demand, not part of `release-gate`.** `LIVE=1 ./run.sh smoke-mux-fresh-call-live` opens configured Pi and Claude Code siblings, spends
|
|
61
|
+
> **Fresh-call LIVE is on-demand, not part of `release-gate`.** `LIVE=1 ./run.sh smoke-mux-fresh-call-live` opens configured Pi and Claude Code siblings, spends four model turns (two in the caller's own session, two in a second SEAT session on the same private server — the #105 seat x cwd matrix), and preserves their native transcripts; run it directly whenever a cut changes mux fresh-call/launch behavior. Its private tmux servers and fixture-bound entwurf write axes make it deterministic about garden-record/socket residue, but those real native turns should not appear unexpectedly in every aggregate cut. **Both this smoke and `smoke-mux-lifecycle-live` enumerate `pi` and `claude-code` only — that exclusion is intentional.** A Copilot visible-fresh (step 9 clause 7) was accepted on 2026-08-25 as an operator-metered LIVE (receipts in `DELIVERY.md`'s Copilot matrix row and the issue #82 thread). It still spends Copilot premium quota, still needs its own grant to re-run, and is never folded into those loops or into the release-gate MUST tier.
|
|
62
62
|
|
|
63
63
|
> **A visible-fresh receipt outside the MUST tier is no longer the general rule — it is Copilot's preserved exception.** #87 measured what that wording permitted: because clause 7 sat outside every aggregate, a harness could be admitted as a full D6 citizen that `entwurf_fresh_call` cannot open, carry an honest "not a supported harness" sentence in the delivery matrix, and still pass the whole floor toward a cut. From OMP onward, the FIRST release of a harness admitted under the #82 contract owes its clause 7 receipt as a release-gate MUST step (`smoke-omp-fresh-live`), and the deterministic half of the same rule (`check-harness-admission-parity`, inside `check:full`) makes a citizen backend missing from `FRESH_CALL_BACKENDS` a red floor rather than a documented one. Forward-only by decision: Copilot's row is not reopened. The contract lives in `docs/adding-a-harness.md` step 9, "The release stop"; this note exists so the cost discipline above is not read as permission.
|
|
64
64
|
>
|
|
@@ -11,7 +11,7 @@ the one-line registration; everything an operator needs to actually wire a host
|
|
|
11
11
|
|
|
12
12
|
**Being garden-native is not the same as being replyable, and Copilot is the case that separates them.** Its hook writes a sender marker, so an `entwurf_v2` send carries its own garden id and the receiver learns who wrote — measured 2026-08-21 on Copilot CLI 1.0.80, where a live send arrived under its own garden id with `origin: "meta-session"` and `replyable: false`. Replyability arrived later and through a different process: a first-party extension (`run.sh install-copilot-receive`) that the CLI forks, which binds to the same V3 record and writes a receiver marker owned by its own pid (#82 RAIL 5). So a Copilot citizen is `replyable: true` exactly while that extension is armed for it, and `replyable: false` — honestly, with a real garden identity — when it is not installed, not launched with `COPILOT_CLI_ENABLED_FEATURE_FLAGS=EXTENSIONS` (which is what `entwurf copilot` sets for one invocation), not yet born, or gone. Read the two facts off different rails: the sender marker answers *who sent this*; the receiver marker answers *can a reply land*. The onboarding obligations are in [`adding-a-harness.md`](./adding-a-harness.md) step 7, and the evidence boundary — the managed LIVE acceptance that moved receive to D6, and what D7-partial / D3-pending still exclude — is in [`DELIVERY.md`](../DELIVERY.md).
|
|
13
13
|
|
|
14
|
-
**Which verb an external agent should reach for:** to deliver to / reply to a garden id, use **`entwurf_v2`** — it is the canonical delivery surface and the only one that reads whether the target is live pi, dormant pi, a mailbox-backed self-fetch citizen (Claude Code, Copilot, OMP), or native-push Antigravity and routes correctly. Discover targets with `entwurf_peers`, confirm your own identity with `entwurf_self`, drain a mailbox with `entwurf_inbox_read`, and use `entwurf_register_native` only as the explicit/manual fallback for binding an already-running agy conversation (normal agy birth is automatic through the installed hook). Open a NEW sibling with **`entwurf_fresh_call {backend, model, task, cwd?}`**, and reopen a DORMANT pi citizen under its own garden id with **`entwurf_resume_call {target}`**. Fresh call accepts one optional literal absolute `cwd`: omit it or pass `""` for the caller's cwd; otherwise it must name an existing directory and may not contain `#`. Use that input for a new cross-repository sibling — resume preserves a dormant Pi citizen's recorded continuity and is not a cwd substitute. Fresh call needs its selected runtime on the server's PATH (`pi`, `claude`, `entwurf` or `omp` — Copilot opens through the managed `entwurf copilot` invocation, never the bare vendor, while OMP is opened as the bare `omp` runtime); resume call always needs `pi`. Both start a runtime, while delivery does not. (The old v1 verbs `entwurf` / `entwurf_resume` / `entwurf_send` are gone.)
|
|
14
|
+
**Which verb an external agent should reach for:** to deliver to / reply to a garden id, use **`entwurf_v2`** — it is the canonical delivery surface and the only one that reads whether the target is live pi, dormant pi, a mailbox-backed self-fetch citizen (Claude Code, Copilot, OMP), or native-push Antigravity and routes correctly. Discover targets with `entwurf_peers`, confirm your own identity with `entwurf_self`, drain a mailbox with `entwurf_inbox_read`, and use `entwurf_register_native` only as the explicit/manual fallback for binding an already-running agy conversation (normal agy birth is automatic through the installed hook). Open a NEW sibling with **`entwurf_fresh_call {backend, model, task, cwd?, placement?}`**, and reopen a DORMANT pi citizen under its own garden id with **`entwurf_resume_call {target}`**. Fresh call accepts one optional literal absolute `cwd`: omit it or pass `""` for the caller's cwd; otherwise it must name an existing directory and may not contain `#`. Use that input for a new cross-repository sibling — resume preserves a dormant Pi citizen's recorded continuity and is not a cwd substitute. Fresh call also accepts one optional `placement.tmuxSession`: the exact name of an EXISTING session on the caller's own tmux server, so the sibling opens in the operator's project seat rather than beside the caller. It creates nothing — an absent session is refused as `tmux-session-missing`, a name outside `[A-Za-z0-9][A-Za-z0-9_-]*` as `tmux-session-name-invalid`, and no window and no session are left behind either way. The seat and the `cwd` never infer each other: with `cwd` omitted a seated sibling starts in the CALLING agent's own directory, not the target session's path. Fresh call needs its selected runtime on the server's PATH (`pi`, `claude`, `entwurf` or `omp` — Copilot opens through the managed `entwurf copilot` invocation, never the bare vendor, while OMP is opened as the bare `omp` runtime); resume call always needs `pi`. Both start a runtime, while delivery does not. (The old v1 verbs `entwurf` / `entwurf_resume` / `entwurf_send` are gone.)
|
|
15
15
|
|
|
16
16
|
Observed: Claude Code, Codex CLI, Antigravity CLI, GitHub Copilot CLI and OMP all reach the read surfaces through this MCP bridge from a plain external host — `entwurf_peers` is a pure fact projection, while `entwurf_inbox_read` is a **mutating drain** (it archives the messages and stamps the read-receipt), so "read" here does not mean side-effect-free; **sending** needs an identity lane. Claude, Copilot and OMP become symmetric/replyable through a mailbox-backed meta-session — Claude's watch armed by its own hook, Copilot's by the forked extension it installs, OMP's by an extension running inside the operator's own TUI process; agy becomes symmetric/replyable through its record-backed sender marker plus live native-push probe. Codex has no managed citizen lifecycle yet, so a Codex host cannot send without the explicit anonymous hatch below.
|
|
17
17
|
|
|
@@ -151,7 +151,7 @@ entwurf doctor-agy-hooks
|
|
|
151
151
|
|
|
152
152
|
The three adapters deliberately own different atoms:
|
|
153
153
|
|
|
154
|
-
- bridge: one `entwurf-bridge` server in `~/.gemini/config/mcp_config.json`, plus one narrow permission string per tool the normal agy workflow calls — `mcp(entwurf-bridge/entwurf_v2)`, `mcp(entwurf-bridge/entwurf_peers)`, `mcp(entwurf-bridge/entwurf_self)` — in `~/.gemini/antigravity-cli/settings.json`. agy defaults every `mcp` action to Ask, so a tool that ships without its own rule stops for a y/n on every call; `entwurf_inbox_read` is deliberately not granted (native-push has no inbox), neither is the manual `entwurf_register_native` fallback, and neither are `entwurf_fresh_call` / `entwurf_resume_call` (both launch into the caller's own tmux
|
|
154
|
+
- bridge: one `entwurf-bridge` server in `~/.gemini/config/mcp_config.json`, plus one narrow permission string per tool the normal agy workflow calls — `mcp(entwurf-bridge/entwurf_v2)`, `mcp(entwurf-bridge/entwurf_peers)`, `mcp(entwurf-bridge/entwurf_self)` — in `~/.gemini/antigravity-cli/settings.json`. agy defaults every `mcp` action to Ask, so a tool that ships without its own rule stops for a y/n on every call; `entwurf_inbox_read` is deliberately not granted (native-push has no inbox), neither is the manual `entwurf_register_native` fallback, and neither are `entwurf_fresh_call` / `entwurf_resume_call` (both launch into the caller's own tmux server, which an agy conversation has none of);
|
|
155
155
|
- statusline: the complete `statusLine` subtree pointing at the bare stable bin `entwurf-agy-statusline`;
|
|
156
156
|
- hooks: one named `PreInvocation` hook pointing at the bare stable bin `entwurf-agy-imprint`.
|
|
157
157
|
|
|
@@ -26,10 +26,11 @@
|
|
|
26
26
|
* this read is the receipt.
|
|
27
27
|
* - entwurf_register_native — explicit/manual fallback binding an ALREADY-RUNNING native
|
|
28
28
|
* conversation (antigravity) to a garden id. Never a spawn.
|
|
29
|
-
* - entwurf_fresh_call — open ONE fresh visible sibling in the operator's
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
29
|
+
* - entwurf_fresh_call — open ONE fresh visible sibling in the operator's tmux — the caller's own
|
|
30
|
+
* session, or ONE EXISTING named session on the same server (the project
|
|
31
|
+
* seat, #105; nothing is ever created), optionally at ONE literal requested
|
|
32
|
+
* cwd (cross-repo fresh, #73); returns a LAUNCH receipt only, and the new
|
|
33
|
+
* address arrives later as the sender envelope of the sibling's nonce callback.
|
|
33
34
|
* - entwurf_resume_call — reopen ONE DORMANT pi citizen under its OWN garden id in a visible
|
|
34
35
|
* window; target-only, runs no turn, LAUNCH and OBSERVATION receipts stay
|
|
35
36
|
* apart.
|
|
@@ -609,7 +610,7 @@ server.tool("entwurf_register_native", "Register an ALREADY-RUNNING native conve
|
|
|
609
610
|
// its own garden id, a fresh cell answered with its uuidv7 `PI_SESSION_ID` value read out of the
|
|
610
611
|
// environment by an MCP server it had spawned itself — confidently, and wrong. A sibling launched
|
|
611
612
|
// against that answer would call home to a garden id nobody holds.
|
|
612
|
-
server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling in the operator's
|
|
613
|
+
server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling in the operator's tmux and hand it a first task. Four fixed " +
|
|
613
614
|
"backends only: pi, claude-code, copilot, omp. The sibling's FIRST action is a callback to you carrying a nonce, and the " +
|
|
614
615
|
"sender envelope of that callback is its garden id — that is how you learn the address of something that " +
|
|
615
616
|
"did not exist a moment ago. This returns a LAUNCH receipt (tmux window/pane plus that nonce) and nothing " +
|
|
@@ -624,6 +625,8 @@ server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling in the operato
|
|
|
624
625
|
"prompt, so the sibling could not call you back at all). An optional " +
|
|
625
626
|
"cwd starts the sibling in ONE literal absolute existing directory (cross-repo fresh) — never pick resume " +
|
|
626
627
|
"for a dormant record's cwd; resume is continuity-only. Omitted/empty cwd means the caller's own directory. " +
|
|
628
|
+
"An optional placement.tmuxSession opens it in ONE EXISTING session of this agent's own tmux server; an " +
|
|
629
|
+
"absent SESSION is tmux-session-missing and NOTHING is created. Omit placement for the caller's own session. " +
|
|
627
630
|
"There are no arbitrary command/env knobs. Do not put secrets in the task — model and task argv are visible to " +
|
|
628
631
|
"same-user processes on this host. Requires that this agent itself runs " +
|
|
629
632
|
"inside tmux: without a pane anchor there is no session to open a sibling beside.", {
|
|
@@ -653,7 +656,15 @@ server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling in the operato
|
|
|
653
656
|
.string()
|
|
654
657
|
.optional()
|
|
655
658
|
.describe("Optional literal ABSOLUTE path of an existing directory to start the sibling in (cross-repo fresh). Omit or pass \"\" to start in this agent's own cwd. Taken exactly as given — no trim, no realpath, no project-name resolution; '#' is refused (tmux format expansion). The receipt echoes what was REQUESTED, never an observation."),
|
|
656
|
-
|
|
659
|
+
placement: z
|
|
660
|
+
.object({
|
|
661
|
+
tmuxSession: z
|
|
662
|
+
.string()
|
|
663
|
+
.describe("EXACT name of an EXISTING session on this agent's own tmux server. Nothing is created: an absent session is refused as tmux-session-missing, and a name outside [A-Za-z0-9][A-Za-z0-9_-]* as tmux-session-name-invalid."),
|
|
664
|
+
})
|
|
665
|
+
.optional()
|
|
666
|
+
.describe("Optional project seat: open the sibling in ONE EXISTING tmux session of this agent's own server instead of the caller's session. Nothing is ever created — an absent session is a refusal, not a new session. Independent of cwd; neither is inferred from the other. The receipt echoes the REQUESTED name and reports the resolved target session id."),
|
|
667
|
+
}, async ({ backend, model, task, cwd, placement }) => {
|
|
657
668
|
let callerGardenId = null;
|
|
658
669
|
try {
|
|
659
670
|
const self = await buildAuthoritativeSelfEnvelope();
|
|
@@ -672,7 +683,7 @@ server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling in the operato
|
|
|
672
683
|
callerGardenId = null;
|
|
673
684
|
}
|
|
674
685
|
try {
|
|
675
|
-
const rendered = renderFreshCall(freshCall({ backend, model, task, cwd, callerGardenId }));
|
|
686
|
+
const rendered = renderFreshCall(freshCall({ backend, model, task, cwd, placement, callerGardenId }));
|
|
676
687
|
return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
|
|
677
688
|
}
|
|
678
689
|
catch (err) {
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* mux-fresh-call — open ONE visible sibling in the caller's own tmux
|
|
3
|
-
*
|
|
2
|
+
* mux-fresh-call — open ONE visible sibling in the caller's own tmux server (its own session by
|
|
3
|
+
* default, or one named existing session on that server since #105), hand it its first task in
|
|
4
|
+
* the launch argv, and let it name itself back to the caller.
|
|
4
5
|
*
|
|
5
6
|
* ── Why this is a third module and not a parameter on the leaf ──
|
|
6
7
|
*
|
|
@@ -43,6 +44,36 @@
|
|
|
43
44
|
* - the receipt echoes what was REQUESTED, exactly as `runtimePath` does. It never reports
|
|
44
45
|
* `pane_current_path`: proving where the pane actually landed belongs to acceptance, not
|
|
45
46
|
* to the launch receipt.
|
|
47
|
+
*
|
|
48
|
+
* ── The optional project seat (issue #105) ──
|
|
49
|
+
*
|
|
50
|
+
* A fresh sibling opens in the caller's own tmux session — unless the caller names ONE session
|
|
51
|
+
* on the SAME server. That input exists because the operator's seats are per-project: a sibling
|
|
52
|
+
* opened for the `org` project belongs in the `org` session, and before this the only way to
|
|
53
|
+
* put it there was for the operator to move the window by hand. The rules are as narrow as the
|
|
54
|
+
* cwd input's, and for the same reason:
|
|
55
|
+
*
|
|
56
|
+
* - `undefined` means the caller's own session, and the argv is byte-identical to the
|
|
57
|
+
* pre-#105 shape. A named session is resolved to its native `$id` by the shared
|
|
58
|
+
* `resolve-tmux-session.ts` leaf and ONLY that id ever reaches `-t`.
|
|
59
|
+
* - a session that does not exist is `tmux-session-missing` and NOTHING is created — not the
|
|
60
|
+
* window, not the session. There is no `ifMissing` axis and no `new-session` verb anywhere
|
|
61
|
+
* in this product (GLG, 2026-09-07): the operator creates the seat and calls again. A name
|
|
62
|
+
* outside the leaf's grammar is the separate `tmux-session-name-invalid` — a different
|
|
63
|
+
* repair, because that name is a shape this rail does not address rather than a session
|
|
64
|
+
* that is absent. The leaf owns which shapes and why; part of that set tmux genuinely
|
|
65
|
+
* cannot resolve and part is a narrowing this rail chose, and it says which is which.
|
|
66
|
+
* - `-d` is what makes this safe to do to a session someone is looking at. `[측정]` without
|
|
67
|
+
* it, a `new-window` into another session changes THAT session's active window and steals
|
|
68
|
+
* the operator's focus. It was already fixed in this argv; #105 is where it became
|
|
69
|
+
* load-bearing.
|
|
70
|
+
* - the seat is ORTHOGONAL to the cwd. `[측정 ×2]` with `-c` omitted, a window opened into
|
|
71
|
+
* another session lands in the cwd of the process that ran `new-window` — not the target
|
|
72
|
+
* session's `session_path` and not its active pane. Neither input is ever inferred from
|
|
73
|
+
* the other.
|
|
74
|
+
* - the receipt echoes the REQUESTED name and carries the OBSERVED target `$id`, which is
|
|
75
|
+
* the session the window is actually in. It still reports no `pane_current_path`, and
|
|
76
|
+
* there is no "session created" field because nothing here creates one.
|
|
46
77
|
*/
|
|
47
78
|
import { randomBytes } from "node:crypto";
|
|
48
79
|
import { classifyTmuxCwd } from "./classify-tmux-cwd.js";
|
|
@@ -50,6 +81,7 @@ import { COPILOT_PREFLIGHT_HINT, copilotFreshPreflight, } from "./copilot-fresh-
|
|
|
50
81
|
import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, } from "./mux-launch.js";
|
|
51
82
|
import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
|
|
52
83
|
import { OMP_PREFLIGHT_HINT, ompFreshPreflight } from "./omp-fresh-preflight.js";
|
|
84
|
+
import { classifyTmuxSessionName, resolveTmuxSessionId } from "./resolve-tmux-session.js";
|
|
53
85
|
/** The backends this rail can open. Fixed set, not a profile — a further one is a decision,
|
|
54
86
|
* not a config entry. `copilot` was added by #82 RAIL 9 under the step 9 admission contract, and
|
|
55
87
|
* `omp` by #87 Bundle C under the same one. The set is joined to the citizen backends by
|
|
@@ -316,9 +348,16 @@ function defaultRandomHex() {
|
|
|
316
348
|
const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="];
|
|
317
349
|
/** Launch argv: the leaf's detached-append shape, the identity scrub, optionally `-c` at the
|
|
318
350
|
* resume-symmetric token position (after `-t`, before `-P -F`), the runtime, then the backend's
|
|
319
|
-
* dialect. An omitted cwd adds no `-c` carrier at all.
|
|
320
|
-
|
|
321
|
-
|
|
351
|
+
* dialect. An omitted cwd adds no `-c` carrier at all.
|
|
352
|
+
*
|
|
353
|
+
* The first parameter is the TARGET session id, not the caller's placement. Since #105 those
|
|
354
|
+
* are not always the same session, and taking a `Placement` here would invite exactly the
|
|
355
|
+
* defect this signature prevents: copying the caller's own id into a cross-session launch. A
|
|
356
|
+
* name never reaches this function — the seat is resolved to a native `$id` before it is
|
|
357
|
+
* called, and `assertSelector` refuses anything that is not one. `-d` is not optional: without
|
|
358
|
+
* it a window opened into another session steals that session's focus (measured). */
|
|
359
|
+
export function buildFreshCallArgs(targetSessionId, runtimePath, backendArgs, cwd) {
|
|
360
|
+
assertSelector("session", targetSessionId);
|
|
322
361
|
assertLaunchTarget(runtimePath);
|
|
323
362
|
if (cwd !== undefined) {
|
|
324
363
|
const bad = classifyTmuxCwd(cwd);
|
|
@@ -331,7 +370,7 @@ export function buildFreshCallArgs(placement, runtimePath, backendArgs, cwd) {
|
|
|
331
370
|
"-a",
|
|
332
371
|
...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
|
|
333
372
|
"-t",
|
|
334
|
-
`${
|
|
373
|
+
`${targetSessionId}:{end}`,
|
|
335
374
|
...(cwd === undefined ? [] : ["-c", cwd]),
|
|
336
375
|
"-P",
|
|
337
376
|
"-F",
|
|
@@ -373,6 +412,17 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
|
|
|
373
412
|
if (badCwd)
|
|
374
413
|
return { ok: false, reason: badCwd };
|
|
375
414
|
}
|
|
415
|
+
// The seat's NAME is classified here, beside the cwd and for the same reason: it is decidable
|
|
416
|
+
// without tmux, so an unresolvable name is answered before anything else runs. Whether that
|
|
417
|
+
// session EXISTS is a tmux question and is asked below, after the caller's own context is
|
|
418
|
+
// proven — a name check that needed a live server would refuse for the wrong reason on a
|
|
419
|
+
// host with no tmux at all.
|
|
420
|
+
const seat = params.placement?.tmuxSession;
|
|
421
|
+
if (seat !== undefined) {
|
|
422
|
+
const badSeat = classifyTmuxSessionName(seat);
|
|
423
|
+
if (badSeat)
|
|
424
|
+
return { ok: false, reason: badSeat };
|
|
425
|
+
}
|
|
376
426
|
let runtimePath;
|
|
377
427
|
try {
|
|
378
428
|
runtimePath = resolveRuntimeOnPath(FRESH_CALL_RUNTIME[params.backend], env);
|
|
@@ -403,6 +453,17 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
|
|
|
403
453
|
return { ok: false, reason: inspected.reason };
|
|
404
454
|
const placement = inspected.placement;
|
|
405
455
|
requireSameContext("freshCall", placement, env);
|
|
456
|
+
// The caller's own context is now proven, which is what makes the next lookup's exit code
|
|
457
|
+
// readable as "that session is not here" rather than "there is no server". Only the resolved
|
|
458
|
+
// native id continues; the name does not travel past this line. STILL PRE-MUTATION: an
|
|
459
|
+
// absent seat refuses with no window anywhere.
|
|
460
|
+
let targetSessionId = placement.sessionId;
|
|
461
|
+
if (seat !== undefined) {
|
|
462
|
+
const resolved = resolveTmuxSessionId(seat, (args) => runTmux(args, env));
|
|
463
|
+
if (!resolved.ok)
|
|
464
|
+
return { ok: false, reason: resolved.reason };
|
|
465
|
+
targetSessionId = resolved.sessionId;
|
|
466
|
+
}
|
|
406
467
|
const composition = {
|
|
407
468
|
prompt: buildFreshCallPrompt({
|
|
408
469
|
backend: params.backend,
|
|
@@ -412,7 +473,7 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
|
|
|
412
473
|
}),
|
|
413
474
|
bootstrapPayload: buildOmpBootstrapPayload({ callerGardenId: params.callerGardenId, nonce, task }),
|
|
414
475
|
};
|
|
415
|
-
const run = runTmux(buildFreshCallArgs(
|
|
476
|
+
const run = runTmux(buildFreshCallArgs(targetSessionId, runtimePath, buildBackendArgs(params.backend, composition, model), cwd), env);
|
|
416
477
|
assertTmuxOk("new-window", run);
|
|
417
478
|
let fields;
|
|
418
479
|
try {
|
|
@@ -422,17 +483,18 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
|
|
|
422
483
|
// The window exists and its id is precisely what could not be read. Diffing the inventory
|
|
423
484
|
// to find "the new one" is the guess this rail forbids everywhere else, so name the orphan.
|
|
424
485
|
throw new Error(`mux-fresh-call: launched ${runtimePath} but could not read the window handle tmux printed — a window may ` +
|
|
425
|
-
`be open in session ${
|
|
486
|
+
`be open in session ${targetSessionId} that this call cannot identify or close: ${err instanceof Error ? err.message : String(err)}`);
|
|
426
487
|
}
|
|
427
488
|
return {
|
|
428
489
|
ok: true,
|
|
429
490
|
receipt: {
|
|
430
491
|
serverPid: placement.serverPid,
|
|
431
|
-
sessionId:
|
|
492
|
+
sessionId: targetSessionId,
|
|
432
493
|
...fields,
|
|
433
494
|
backend: params.backend,
|
|
434
495
|
model,
|
|
435
496
|
...(cwd === undefined ? {} : { cwd }),
|
|
497
|
+
...(seat === undefined ? {} : { tmuxSession: seat }),
|
|
436
498
|
runtimePath,
|
|
437
499
|
nonce,
|
|
438
500
|
},
|
|
@@ -454,6 +516,8 @@ const REJECT_HINT = {
|
|
|
454
516
|
"cwd-format-token": "the requested cwd contains '#', which tmux expands as a format inside -c — it would silently rewrite the path or run a command",
|
|
455
517
|
"cwd-missing": "the requested cwd does not exist; tmux would not report this, it would open the window in $HOME and look successful",
|
|
456
518
|
"cwd-not-directory": "the requested cwd exists but is not a directory",
|
|
519
|
+
"tmux-session-name-invalid": "the requested tmux session name is outside the shape this rail addresses (start with a letter or digit, then letters, digits, '_' or '-') — some other shapes tmux cannot resolve at all ('#' is expanded when the name is stored; '.' and ':' are its own pane/window separators inside a target; a name like '$0' loses to the session id '$0'), and the rest are declined to keep one narrow grammar, so rename the session or open one whose name fits",
|
|
520
|
+
"tmux-session-missing": "no session with that exact name answers on this agent's tmux server (or that server stopped answering) — nothing was created, so open the session yourself and call again",
|
|
457
521
|
"model-empty": "model is empty after trimming; fresh calls require an explicit model",
|
|
458
522
|
"model-invalid": `model must be one ${MODEL_MAX_CHARS}-character argv-safe id/alias without whitespace or tmux syntax`,
|
|
459
523
|
"task-empty": "task is empty after trimming",
|
|
@@ -487,6 +551,9 @@ export function renderFreshCall(result) {
|
|
|
487
551
|
` backend: ${r.backend} (${r.runtimePath})\n` +
|
|
488
552
|
` model: ${r.model} (requested on the runtime CLI)\n` +
|
|
489
553
|
(r.cwd === undefined ? "" : ` cwd: ${r.cwd} (requested start directory — not an observation)\n`) +
|
|
554
|
+
(r.tmuxSession === undefined
|
|
555
|
+
? ""
|
|
556
|
+
: ` seat: ${r.tmuxSession} (requested tmux session, resolved to ${r.sessionId})\n`) +
|
|
490
557
|
` window: ${r.windowId} (index ${r.windowIndex}) in session ${r.sessionId}\n` +
|
|
491
558
|
` pane: ${r.paneId} pid ${r.panePid}\n` +
|
|
492
559
|
` nonce: ${r.nonce}\n` +
|