lab/distribution
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Baseline: distribution workspace before observability redesign

Browse Source
This commit is contained in:
agra
2026-06-02 16:08:17 +03:00
commit 055c8ced15
38 changed files with 6001 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
.agents/runs/2026-06-02-observability-redesign/agents.json Normal file
View File

@@ -0,0 +1,23 @@
{
"schema": 1,
"agents": [
{
"role": "codex-manager",
"status": "running",
"started_at": "2026-06-02T12:05:10Z",
"heartbeat_at": "2026-06-02T12:49:58Z",
"lease_expires_at": "2026-06-02T13:04:58Z",
"thread_id": "current-codex-thread",
"last_error": null
},
{
"role": "opus",
"status": "running",
"started_at": "2026-06-02T12:49:58Z",
"heartbeat_at": "2026-06-02T12:49:58Z",
"lease_expires_at": "2026-06-02T13:19:58Z",
"tool_call_id": "claude-cli-observability-implementation-1",
"last_error": null
}
]
}

75
.agents/runs/2026-06-02-observability-redesign/brief.md Normal file
View File

@@ -0,0 +1,75 @@
# Observability Redesign Brief
## Request
Ask Opus to redesign the local agent observability dashboard before any
implementation starts.
## Context
The dashboard lives under `.agents/observability/` and is served by
`.agents/scripts/observe.mjs` at `http://127.0.0.1:4317`.
Current files:
- `.agents/observability/index.html`
- `.agents/observability/styles.css`
- `.agents/observability/app.js`
- `.agents/scripts/observe.mjs`
The dashboard currently shows:
- Summary cards for active run, phase, branch, and blockers.
- A runs list with run metadata and agent rows.
- Checkpoint next action, workspace, blockers, and active progress tail.
- Tail length selector, refresh button, and live/error status.
Known design problem:
- The current layout feels generic and visually weak.
- It does not make agent liveness, leases, progress, blockers, or next action
feel operationally obvious enough.
- It should feel like a focused orchestration cockpit, not a landing page.
## Product Requirements
- First viewport should immediately answer:
- What is active?
- Is anything dead or blocked?
- Who is working?
- What happened most recently?
- What should the manager do next?
- Preserve the data source and static app constraint.
- Keep the UI dense, calm, and operational.
- Avoid marketing layout, decorative cards inside cards, and hero-style copy.
- Make liveness and lease expiry visually obvious.
- Make progress tail readable without dominating the whole page.
- Support desktop and mobile layouts without text overlap.
- Prefer familiar controls and icons if implementation later adds an icon
library or inline symbols.
- Keep the design implementable in plain HTML, CSS, and vanilla JS.
## Current Constraints
- This is a read-only Opus design proposal request.
- Do not edit application files yet.
- The distribution workspace is not a git repository yet, so branch-based Opus
implementation is still blocked.
- If implementation is later approved, the likely write scope is:
- `.agents/observability/index.html`
- `.agents/observability/styles.css`
- `.agents/observability/app.js`
- possibly `.agents/scripts/observe.mjs` if Opus needs small API fields for
better status grouping.
## Opus Output Requested
Write `opus-proposal.md` with:
1. The proposed information architecture.
2. The exact visual layout direction.
3. The key interactions and states.
4. Any small API/data-shape changes requested from `observe.mjs`.
5. Mobile behavior.
6. Implementation notes for the eventual Opus coding pass.
7. Concerns or blockers, if any.

135
.agents/runs/2026-06-02-observability-redesign/implementation-instructions.md Normal file
View File

@@ -0,0 +1,135 @@
# Observability Redesign Implementation Instructions
## Role
You are Opus in the distribution platform orchestration flow. Codex is the
manager. Snarky owns product acceptance. You own layout and visual design
decisions and are the only role allowed to edit code during this phase.
## User Direction
The user clarified that the git setup required for the Opus implementation
branch is Opus responsibility.
If `/Users/agra/projects/distribution` is not yet a git repository, initialize a
local git repository, create a clean baseline commit from the current workspace,
and then create or switch to branch:
```txt
opus/observability-redesign
```
Use branches only. Do not create a worktree.
## Primary Task
Implement the observability dashboard redesign from:
```txt
.agents/runs/2026-06-02-observability-redesign/opus-proposal.md
```
The dashboard lives at:
```txt
.agents/observability/
```
It is served by:
```txt
.agents/scripts/observe.mjs
```
## Allowed Edit Scope
Application/dashboard edits are limited to:
- `.agents/observability/index.html`
- `.agents/observability/styles.css`
- `.agents/observability/app.js`
- `.agents/scripts/observe.mjs`
- `.agents/runs/2026-06-02-observability-redesign/implementation-log.md`
Creating `.git/` and committing/switching branches is allowed as setup for this
phase. Do not edit root mock files such as `index.html`, `styles.css`, or
`app.js`.
## Required Product Shape
Implement the proposal's operational cockpit direction:
- Replace the four metric cards with a compact sticky status bar and a "Now"
command band.
- Make the first viewport answer what is active, whether anything is blocked or
stalled, who is working, what happened recently, and what the manager should do
next.
- Pin active-agent liveness with status, lease countdown, heartbeat age, and
clear warning/dead states.
- Keep progress readable but bounded; it must not dominate the whole page.
- Keep the UI dense, calm, and operational. Avoid marketing layout, hero copy,
decorative nesting, and generic dashboard fluff.
- Support desktop and mobile without text overlap.
## Required Interactions
- Keep the existing `/api/status` polling model and static vanilla app.
- Add a one-second local ticker for freshness, heartbeat age, and lease
countdown text.
- Add pause/resume for auto-refresh.
- Keep the last good render on fetch error; do not replace the progress log with
an error message.
- Add progress expand/collapse.
- Preserve progress bottom-stick behavior and show a jump control when new lines
arrive while the user is scrolled up.
- Make run rows selectable. If the API supports `?run=`, use it to refocus
progress for the selected run; otherwise degrade gracefully.
- Add click-to-copy for run id, branch, and progress path with a short copied
state.
## Required Server/API Additions
Make only additive, optional changes:
- Per-agent liveness fields:
- `lease_remaining_ms`
- `heartbeat_age_ms`
- `lease_expired`
- `is_active`
- Summary fields:
- `active_role`
- `health`
- Active progress fields:
- `modified_at`
- `total_lines`
- `truncated`
- Support `/api/status?tail=N&run=<id>` so selected runs can show their own
progress.
- In progress selection, prefer the newest candidate progress artifact by mtime.
The frontend must remain missing-field safe.
## Validation Expectations
Before finishing, run:
```sh
node --check .agents/scripts/observe.mjs
node --check .agents/observability/app.js
node .agents/scripts/status.mjs --tail 20
```
If possible, start or reuse the local server and verify:
```sh
curl http://127.0.0.1:4317/api/status?tail=5
```
Write a short final implementation report to:
```txt
.agents/runs/2026-06-02-observability-redesign/implementation-log.md
```
Include changed files, validation commands/results, unresolved risks, and the
current git branch/status.

46
.agents/runs/2026-06-02-observability-redesign/opus-prompt.md Normal file
View File

@@ -0,0 +1,46 @@
# Role
You are Opus in the distribution platform orchestration flow.
Codex is the manager. Snarky owns product acceptance. You own layout and visual
design decisions, and you are consulted for technical problems until consensus.
This is a read-only design proposal. Do not write code. Do not assume
implementation has started.
# Repositories
You have read-only context for:
- `/Users/agra/projects/distribution`
- `/Users/agra/projects/sx`
For this request, focus on the distribution repo only.
# Task
Redesign the local agent observability dashboard.
Read these files:
- `/Users/agra/projects/distribution/.agents/runs/2026-06-02-observability-redesign/brief.md`
- `/Users/agra/projects/distribution/.agents/observability/index.html`
- `/Users/agra/projects/distribution/.agents/observability/styles.css`
- `/Users/agra/projects/distribution/.agents/observability/app.js`
- `/Users/agra/projects/distribution/.agents/scripts/observe.mjs`
- `/Users/agra/projects/distribution/.agents/ORCHESTRATION.md`
Return a proposal in Markdown with these sections:
1. Verdict
2. Information Architecture
3. Visual Layout Direction
4. Interactions And States
5. API Or Data Shape Changes
6. Mobile Behavior
7. Implementation Notes
8. Concerns
Be specific enough that an implementation pass can follow it without another
layout brainstorm. Keep the design operational, dense, and calm. Avoid a hero
page, marketing copy, decorative nesting, or generic SaaS fluff.

309
.agents/runs/2026-06-02-observability-redesign/opus-proposal.md Normal file
View File

@@ -0,0 +1,309 @@
# Opus Proposal - Local Agent Observability Dashboard Redesign
## 1. Verdict
Redesign is warranted, and the problem is structural, not cosmetic. The current
page is a symmetric four-metric grid feeding two equal-weight panels. That
layout treats every fact as equally important, which is wrong for a sequential,
single-active orchestration model.
Keep the hard constraints: static HTML/CSS/vanilla JS, single `/api/status`
poll, no build step, and no dependencies. The redesign needs no breaking API
changes, only small additive, server-computed fields to make liveness and lease
expiry honest rather than guessed client-side.
The reorientation:
- Replace the equal metric grid with a "Now" command band that answers active
run, phase, branch, and next action in one strip.
- Anchor the band with one system-health token.
- Make agent liveness a live ticking signal: lease countdown plus heartbeat age.
- Demote the progress tail from page-dominator to bounded, auto-sticking log.
- Remove landing-page tells: heavy shadows, shouting weights, eyebrow plus large
heading, and cards-inside-cards.
Implementation is blocked until the workspace is a git repo. This proposal is
approvable now and implementable once `git init` and a baseline commit exist.
## 2. Information Architecture
Three tiers, in strict priority order. Tiers 0 through 2 should sit above the
fold on desktop.
Tier 0 - Chrome/status bar:
- Workspace basename.
- Connection state.
- Freshness, ticking as "updated 3s ago".
- Tail selector.
- Refresh.
- Auto-refresh pause/play.
Tier 1 - Now band:
- System token: `WORKING`, `BLOCKED`, `STALLED`, `STALE`, or `IDLE`.
- Active run: run id, phase stepper, branch chip.
- Next action: prominent prose label.
Tier 2 - Operational split:
- Left rail around 340px:
- Active agent pinned at the top with status dot, role, lease countdown, and
heartbeat age.
- Agents for the active run.
- Compact runs list with active run highlighted.
- Right column:
- Conditional blockers strip at the top when blockers exist.
- Progress tail with path, "last N of M", and last-modified age.
Remove the standalone workspace metric and the four-up summary grid. Workspace
moves to the status bar; the grid is absorbed into the Now band and health
token.
## 3. Visual Layout Direction
Desktop layout:
```txt
+--------------------------------------------------------------------+
| distribution updated 3s ago Tail [80] refresh pause |
+--------------------------------------------------------------------+
| WORKING | run 2026-06-02-obs... 4/10 Opus proposal | NEXT ACTION |
| | branch none Wait on ... |
+----------------------------+---------------------------------------+
| ACTIVE AGENT | BLOCKERS, if any |
| opus running +---------------------------------------+
| lease 28:14 heartbeat 4s | PROGRESS runs/.../progress.log |
| | +-----------------------------------+ |
| AGENTS | | 14:02:11 proposal requested | |
| codex running | | 14:02:48 reading brief.md | |
| snarky completed | | ... | |
| | +-----------------------------------+ |
| RUNS | expand new |
| active run | |
+----------------------------+---------------------------------------+
```
Grid and sizing:
- Shell: `width: min(1440px, 100%)`, padding `20px`.
- Status bar: sticky, top `0`, about `44px`, hairline bottom border.
- Now band: single panel with
`grid-template-columns: 150px minmax(0, 1fr) minmax(300px, 1fr)`.
- Main split: `grid-template-columns: minmax(300px, 340px) minmax(0, 1fr)`.
- Progress body: `max-height: clamp(320px, 52vh, 720px); overflow: auto`.
- Expanded progress body: about `80vh`.
Visual language:
- Use one elevation level. Prefer hairline borders over heavy shadows.
- Delete nested bordered boxes; internal sections use dividers and spacing.
- Reduce blanket `font-weight: 800`. Labels around 600, values 400, system
token 700.
- Use monospace for machine facts: run ids, branches, paths, timestamps, counts,
lease values, heartbeat values.
- Keep prose in the sans stack.
- Keep the warm-paper base and the current semantic colors, but assign strict
meaning:
- green: healthy, live, completed
- blue: working or active focus
- amber: warning, expiring lease, aging heartbeat, stale data
- red: blocked, expired, dead, fetch error
- muted grey: idle, recorded, none, absent
- Use 8px status dots for rows. Reserve pills for the system token and active
or recorded run status.
- Keep the progress log dark as the one large terminal-like surface.
Phase stepper:
- Render the ten canonical sequential-flow steps as a segmented bar.
- Filled segments are done, current segment is ringed, future segments are
hollow.
- Show `N / 10 - <label>`.
- If phase text is unknown, degrade to label-only text.
## 4. Interactions And States
System health token priority:
```txt
BLOCKED red blocker_count > 0
STALLED red active agent lease_expired and not blocked
STALE amber data age is stale or active heartbeat is stale
WORKING blue active-run agent is running with healthy unexpired lease
IDLE grey no active run or no leased agent
```
Use `aria-live="polite"` for health transitions.
Liveness:
- Add a 1-second local ticker independent from the 5-second poll.
- Lease countdown displays `mm:ss` remaining.
- Lease at or below two minutes becomes amber.
- Expired lease becomes red and displays elapsed expiry age.
- Heartbeat age displays as `heartbeat 4s`.
- Heartbeat over 60 seconds becomes amber.
- Heartbeat over 180 seconds becomes red.
- Data freshness in the status bar ticks locally.
- The ticker only updates timestamp text nodes and never re-renders lists.
Polling and errors:
- Keep the last good render on fetch error.
- Flip the status bar to red error/stale state.
- Do not replace the progress tail with an error string.
- Pause timers while the tab is hidden and resume with an immediate refetch on
focus.
Selection and affordances:
- Run rows should be selectable.
- Selecting a run refocuses progress and agent details if the API supports
`?run=`.
- Progress auto-sticks to bottom only if the user was already at bottom.
- If new content arrives while scrolled up, show a "new" jump button.
- Add expand/collapse for the progress log.
- Add click-to-copy for run id, branch, and progress path with a brief copied
state.
Empty and degraded states:
- No runs.
- No active run.
- No progress file.
- No lease recorded: show `lease -`, muted.
- No heartbeat recorded: show `heartbeat -`, muted.
- Unknown phase: label-only stepper.
- Checkpoint parse error: surface it in the blockers strip.
## 5. API Or Data Shape Changes
All requests are additive and optional. The dashboard must render correctly if
any are absent.
Per agent:
```json
{
"lease_remaining_ms": 1694000,
"heartbeat_age_ms": 4000,
"lease_expired": true,
"is_active": true
}
```
Summary:
```json
{
"active_role": "opus",
"health": "working"
}
```
Active progress:
```json
{
"modified_at": "2026-06-02T14:05:03Z",
"total_lines": 342,
"truncated": true
}
```
New optional query parameter:
```txt
/api/status?tail=N&run=<id>
```
When `run` is supplied, `active_progress` reflects that run instead of the
active one. Default behavior remains unchanged.
Optional manager-written fields in `state.json`:
```json
{
"phase_index": 4,
"phase_total": 10,
"updated_at": "2026-06-02T14:05:03Z"
}
```
Suggested server tweak: in `readProgress`, pick the newest candidate file by
mtime rather than the first file in a fixed list.
## 6. Mobile Behavior
At widths up to 980px, switch to one column.
Stacking order:
1. Sticky status bar, compressed to workspace basename.
2. Now band, collapsed to rows: token, run plus stepper, next action.
3. Blockers, if any.
4. Active agent.
5. Progress tail, collapsed by default to about `42vh`.
6. Runs accordion, collapsed.
At widths up to 560px:
- Toolbar becomes a compact wrapping row: tail selector, refresh, pause.
- Tap targets stay at least 44px.
- The segmented phase bar degrades to text.
- Mono ids and paths ellipsize.
- Prose wraps.
- No text overlap.
## 7. Implementation Notes
Likely write scope:
- `.agents/observability/index.html`
- `.agents/observability/styles.css`
- `.agents/observability/app.js`
- `.agents/scripts/observe.mjs` for additive API fields
Implementation guidance:
- No frameworks and no build step.
- Use a small inline SVG sprite or simple text/icon fallbacks.
- Keep two timers:
- `setInterval(poll, 5000)` rebuilds data.
- `setInterval(tick, 1000)` updates timestamp/countdown text only.
- Centralize constants:
- `POLL_MS`
- `DATA_STALE_MS`
- `LEASE_WARN_MS`
- `HEARTBEAT_WARN_MS`
- `HEARTBEAT_DEAD_MS`
- Add one pure `computeHealth(data)` helper.
- Add `formatAge(ms)` and `formatCountdown(ms)` helpers.
- Prefer `document.createElement` and `textContent` for rows instead of
template-literal `innerHTML`.
- Preserve progress scroll position and bottom-stick behavior across renders.
- Remember selected run id.
- Treat every optional API field as missing-safe.
- Add `role="status"` to freshness and `aria-live="polite"` to health and
blocker changes.
- Gate any pulse animation behind `prefers-reduced-motion`.
- Keep the CSS token approach and add a mono font token.
## 8. Concerns
1. Implementation is currently blocked by process. The workspace is not a git
repository, and Opus implementation must happen on a named branch from a
clean baseline.
2. Liveness is only honest if the manager writes `lease_expires_at` and
`heartbeat_at`. Missing values must render as unknown, not healthy.
3. Heartbeat cadence is unspecified. Proposed defaults are warning at 60 seconds
and dead at 180 seconds, but the manager should pick a real cadence.
4. Phase stepper depends on canonical phase strings. Unknown phases must degrade
gracefully.
5. Server-computed millisecond deltas are preferred to avoid client clock drift.
6. Polling cannot show sub-5-second events, which is acceptable for
human-paced orchestration.
7. Avoid adding timelines, charts, or history graphs in the first pass.
8. Non-active run progress depends on the optional `?run=` parameter. Without
it, run selection degrades to metadata-only.

10
.agents/runs/2026-06-02-observability-redesign/progress.log Normal file
View File

@@ -0,0 +1,10 @@
2026-06-02 15:05:10 EEST - User asked Codex manager to ask Opus to redesign the observability dashboard.
2026-06-02 15:05:10 EEST - Created observability redesign run directory and brief.
2026-06-02 15:06:20 EEST - Opus design proposal requested through Claude CLI.
2026-06-02 15:08:55 EEST - First Opus CLI invocation produced no output and was stopped; retrying with explicit read-only tools.
2026-06-02 15:10:50 EEST - User clarified Opus timeout must never be less than 30 minutes.
2026-06-02 15:10:50 EEST - Retry 1 exited with empty output; retrying with a 30-minute Opus timeout and lease.
2026-06-02 15:17:03 EEST - Opus returned observability redesign proposal; saved to opus-proposal.md.
2026-06-02 15:48:02 EEST - Manager attempted to initialize git baseline; sandbox blocked .git creation and escalation was rejected.
2026-06-02 15:49:58 EEST - User clarified git setup is Opus responsibility.
2026-06-02 15:49:58 EEST - Saved implementation instructions and requested Opus implementation on branch opus/observability-redesign.

12
.agents/runs/2026-06-02-observability-redesign/state.json Normal file
View File

@@ -0,0 +1,12 @@
{
"schema": 1,
"run_id": "2026-06-02-observability-redesign",
"current_phase": "opus-implementation-requested",
"current_branch": "opus/observability-redesign",
"input_artifact": ".agents/runs/2026-06-02-observability-redesign/implementation-instructions.md",
"input_hash": "manual-observability-implementation-2026-06-02",
"expected_output_artifact": ".agents/runs/2026-06-02-observability-redesign/implementation-log.md",
"retry_count": 0,
"next_action": "Wait for Opus to initialize the git baseline and implement the observability redesign on branch opus/observability-redesign.",
"blocker": null
}

32
.agents/runs/2026-06-02-orchestration-planning/agents.json Normal file
View File

@@ -0,0 +1,32 @@
{
"schema": 1,
"agents": [
{
"role": "codex-manager",
"status": "running",
"started_at": "2026-06-02T11:28:30Z",
"heartbeat_at": "2026-06-02T11:50:10Z",
"lease_expires_at": "2026-06-02T12:05:10Z",
"thread_id": "current-codex-thread",
"last_error": null
},
{
"role": "snarky",
"status": "completed",
"started_at": "2026-06-02T11:33:00Z",
"heartbeat_at": "2026-06-02T11:57:20Z",
"lease_expires_at": "2026-06-02T12:06:58Z",
"thread_id": "019e8831-eab0-7f20-9536-fb10f0f906f0",
"last_error": null
},
{
"role": "opus",
"status": "completed",
"started_at": "2026-06-02T11:33:00Z",
"heartbeat_at": "2026-06-02T12:02:05Z",
"lease_expires_at": "2026-06-02T12:21:27Z",
"tool_call_id": "claude-cli-session-54314",
"last_error": null
}
]
}

120
.agents/runs/2026-06-02-orchestration-planning/discussion-round-1-opus.md Normal file
View File

@@ -0,0 +1,120 @@
# Discussion Round 1 - Opus
## Agreements
Opus accepts Snarky's eight decisions:
- Ship the NAS release console first.
- Drop `pub`/alias/namespace re-export from the critical path.
- Replace Milestone 1 with a walking skeleton.
- Make Linux/NAS the first runtime target.
- Allow FFI as a thin, named, replaceable boundary.
- Keep orchestration sequential and artifact-driven.
- Remove `Release.channel`, add release state, and use promotion history for
rollback.
- Use the v1 access model with app visibility, roles, scoped tokens, and signed
install links.
Opus also accepts Snarky's challenges: temporary boundaries must be named, M1
can be small but the product model cannot be vague, FFI must be Linux-first, and
the mock redesign must preserve iOS install truth.
## Remaining Technical Objections
1. **The cross-repo sx governance stop is still unresolved.**
FFI reduces compiler-bug surface but does not remove it. `#foreign` and
comptime are themselves active sx risk areas. If an M1 slice trips an sx bug,
`sx/CLAUDE.md` requires filing an issue, marking blocked, ending the session,
and not working around it. The distribution orchestration needs an explicit
`sx-blocked` state and handoff.
2. **M1 std signatures must pin to landed sx error handling.**
Do not implement against planned error semantics. Pin to the current landed
shape and record the checkpoint/commit.
3. **M1 APK inspection must not become an AXML decoder.**
For M1, artifact inspection means opening the zip central directory and
confirming `AndroidManifest.xml` exists with size/offset. Decoding binary
Android XML is M2.
4. **Enterprise install readiness depends on proxy HTTPS.**
`distd` cannot self-satisfy the Enterprise HTTPS requirement if TLS is behind
a reverse proxy. `dist doctor` can validate config/reachability, not TLS
termination by `distd`.
5. **Public visibility needs an iOS artifact-only carve-out.**
An iOS artifact-only IPA should never be anonymously downloadable, even on a
public app.
## Refinements To Snarky
- M1 JSON output should be the same shape later used by HTTP and remote
`dist ci publish`.
- M1 artifact inspection is zip-entry presence/size only.
- FFI boundaries should be named:
- miniz/libzip or zlib for zip reads
- libsqlite3 deferred to M2
- HMAC for signed links in M2
- SHA-256 remains a compiler-risk choice, not a portability mandate
- `rejected` is terminal.
- M1 releases can go `draft -> published` with `validation=not_run`.
- Signed install links are HMAC over `(artifact_id, expiry)` with a server key.
- Download auth should be a table across actor/auth mode, visibility, and
platform.
## Minimal Plan Patch Order
1. `git init` and baseline commit.
2. Patch Subplan 01:
- remove dangling references
- park `pub` as language-track work
- pin error model to landed sx state
- mark FFI-first/Linux boundaries
3. Patch `PLAN.md`:
- replace the first milestone with the walking skeleton
- demote HTTP/SQLite/UI/Docker to later milestones
4. Patch Subplan 02:
- remove `Release.channel`
- add `Release.state`
- add validation outcome
- add `ChannelPromotion`
5. Patch Subplan 03:
- local publish first
- add `dist.json` schema and example
- add idempotency key and rerun behavior
6. Patch Subplan 05:
- label validation checks as `required`, `warning`, `informational`, or
`not_supported`
- scope M1 APK to zip-entry presence
7. Patch Subplan 04:
- split Enterprise and MDM
- add TLS-by-proxy caveat
- define concrete routes and JSON shapes
8. Add access-policy section:
- roles
- visibility
- token scopes
- signed-link HMAC
- download authorization table
- iOS artifact-only never public
9. Patch orchestration:
- add `sx-blocked` state
- split Opus read-only consultation approval from write implementation
approval
## What Opus Needs Before Any Code
1. Answer the sx governance question: on an M1 compiler bug, does the
distribution run hard-stop and file in `sx/issues`, or is there a sanctioned
narrow-workaround budget?
2. Pin the current landed sx error-handling shape.
3. Approve the `dist.json` schema and idempotency key.
4. Approve the download authorization table.
5. Confirm libsqlite3 is M2 and M1 is DB-free.
6. For the mock branch, provide a Snarky `brief.md` with seed data and required
UI states.

138
.agents/runs/2026-06-02-orchestration-planning/discussion-round-1-snarky.md Normal file
View File

@@ -0,0 +1,138 @@
# Discussion Round 1 - Snarky
## Decisions
1. **Accept: ship the NAS release console first.**
The goal is to ship a working distribution platform in `sx`, not to mature
`sx` for its own sake. `sx` work is justified only when it directly unblocks
`dist`.
2. **Accept with narrowing: drop `pub` from the critical path.**
`pub`, alias imports, and `pub print :: core.print` remain desirable
language work, but they are no longer Phase 0 blockers for the product. They
move to a parallel/future language track unless a concrete implementation
blocker appears.
3. **Accept: replace Milestone 1 with a walking skeleton.**
M1 should be:
- `dist ci publish --local-store .dist`
- file-backed or JSON-backed domain model
- content-addressed artifact storage
- manifest parsing
- stable JSON output
- at least one simple artifact inspection path
No HTTP, SQLite, admin UI, Docker, or full IPA/APK validation in M1.
4. **Accept: Linux/NAS-first runtime.**
`distd` targets Linux Docker on UGREEN NAS first. macOS support is useful for
dev, but Linux correctness wins for server primitives.
5. **Accept: FFI is allowed as a thin boundary.**
For v1, FFI/system libs are acceptable for SQLite, hashing, archive
inspection, TLS boundary, and platform APIs. The product still lives in `sx`;
the wrappers must be explicit and replaceable.
6. **Accept: sequential orchestration stays.**
We are not doing parallel agents. Codex manages one visible workflow, Snarky
and Opus communicate through run artifacts, and Opus implements only on
branches.
7. **Decide release/channel model.**
`Release.channel` is removed. Releases have state. Channels point to
releases. Rollback uses promotion history, not magic memory.
Minimum states:
- `draft`
- `validating`
- `published`
- `rejected`
- `withdrawn`
`superseded` is derived from channel history, not a release state.
8. **Decide v1 access model.**
V1 supports:
- app visibility: `private`, `link`, `public`
- human roles: `admin`, `release_manager`, `viewer`
- CI tokens scoped by app and allowed actions
- downloads allowed by public visibility, signed install link,
authenticated user, or scoped token
## Challenges To Opus
1. "Build against sx as-is" is acceptable only if it does not create a junk
drawer of one-off shims. Opus needs to name every temporary boundary clearly.
2. "APK zip entry only" is fine for the walking skeleton, but the product plan
must still model iOS modes, access policy, release states, and validation
outcomes. M1 can be small; the product model cannot be vague.
3. FFI-first must be Linux-first. CommonCrypto-only, macOS-only sockets, or
host-specific assumptions are not acceptable for `distd`.
4. The UI mock redesign can proceed independently from the sx backend, but Opus
must preserve product truth: especially iOS TestFlight vs Enterprise vs MDM
vs artifact-only.
## Required Plan Patches
1. Fix Subplan 01 dangling references to removed `PLAN.md` sections.
2. Re-sequence language work:
- move `pub` and namespace re-export out of the blocker path
- keep actual required std primitives tied to product slices
3. Rewrite Milestone 1 as the walking skeleton.
4. Patch domain model:
- remove `Release.channel`
- add `Release.state`
- add `ChannelPromotion` / channel history
- define rollback semantics
5. Patch access policy:
- roles
- app visibility
- token scopes
- signed install links
- download authorization rules
6. Patch CI contract:
- concrete `dist.json` schema
- example manifest
- idempotency key
- rerun behavior
- duplicate version/build behavior
7. Patch HTTP API with concrete routes and JSON response shapes before HTTP
implementation.
8. Patch validation policy so every check is marked:
- `required`
- `warning`
- `informational`
- `not_supported`
9. Split iOS Enterprise and MDM. They are related, not identical.
10. Patch orchestration docs to make read-only Opus consultation and
write-capable Opus implementation separate approval modes.
## Implementation Gate
No implementation until:
- distribution repo has a clean git baseline
- plan patches above are applied
- active run has `brief.md`, `state.json`, and `agents.json`
- Opus has produced a design/technical proposal for the relevant slice
- Snarky has accepted product coverage
- allowed write paths are explicit
- branch is clean before Opus writes
For the website mock specifically: once those gates are satisfied, Opus may
redesign only the allowed UI files, and Snarky reviews product coverage
afterward.

93
.agents/runs/2026-06-02-orchestration-planning/discussion-round-2-opus.md Normal file
View File

@@ -0,0 +1,93 @@
# Discussion Round 2 - Opus
## Final Opus Position
Opus accepts all six of Snarky's final decisions and accepted refinements:
- `sx-blocked` is a hard governance state.
- Error model is pinned to landed sx with real examples.
- M1 APK inspection is ZIP container plus `AndroidManifest.xml` presence only.
- Enterprise, MDM, proxy HTTPS readiness, and artifact-only are distinct states.
- Public visibility does not imply public IPA download.
- M1 is DB-free and SQLite moves to M2.
No open contest remains on product scope or sequencing.
## Any Remaining Blockers
1. **Cross-repo sx-authoring ownership is undefined.**
`sx-blocked` handles bugs, but not normal sx work. The DB-free skeleton still
requires new sx modules such as JSON, CLI, hash, and archive wrappers. Decide
whether distribution M1 consumes sx strictly as-is, or whether there is a
sanctioned sx-repo authoring lane under `sx/CLAUDE.md`.
2. **Repo/module-resolution boundary is undefined.**
Decide where `dist`/`distd` product code lives and how it imports sx stdlib
across the two repos.
3. **Subagent machinery versus single-thread rule is still unresolved.**
Either explicitly waive the no-fan-out rule for this project or drop the
machinery and keep only run-dir artifacts.
## Exact First Patch Set To Apply
1. `git init` and baseline commit in `/Users/agra/projects/distribution`.
2. Patch `PLAN.md` to:
- replace First Milestone with DB-free walking skeleton
- demote HTTP, SQLite, admin UI, Docker to M2+
- move `pub`/alias/re-export off the critical path
3. Patch orchestration docs:
- add `sx-blocked`
- add cross-repo handoff
- split Opus read-only approval from write approval
- record subagent/single-thread decision
4. Patch Subplan 01:
- remove dead `PLAN.md` references
- park `pub`
- pin landed sx commit and error examples
- mark FFI-first/Linux-first boundaries
5. Patch Subplan 02:
- remove `Release.channel`
- add `Release.state`
- add validation outcome
- add `ChannelPromotion`
- mark SQLite as M2
6. Patch Subplan 03:
- local publish becomes M1
- add concrete `dist.json` schema and example
- add idempotency and rerun semantics
- clarify `dist doctor` TLS/proxy checks
7. Patch Subplan 05:
- classify every validation check
- scope M1 APK to zip-entry metadata
- move full IPA/APK checks post-M1
8. Patch Subplan 04:
- split Enterprise, MDM, artifact-only
- add TLS caveat
- add concrete routes and JSON shapes
- mark HTTP as M2+
9. Add access policy section:
- roles
- visibility
- token scopes
- signed-link HMAC
- download authorization table
- iOS artifact-only never public
10. Author the real implementation run directory for the chosen first slice.
## Whether Implementation Can Start After Those Patches
Product/sx track:
- No, not after plan patches alone.
- Still needs sx authoring lane, module resolution boundary, pinned sx commit
and error examples, accepted Opus proposal, clean branch, and write-paths.
Mock-redesign track:
- Yes, after git baseline plus a Snarky `brief.md`.
- It has no sx/backend dependency and can run independently under the UI
allowed paths.

82
.agents/runs/2026-06-02-orchestration-planning/discussion-round-2-snarky.md Normal file
View File

@@ -0,0 +1,82 @@
# Discussion Round 2 - Snarky
## Final Decisions
1. **`sx-blocked` is a hard governance state.**
If an M1 slice hits an `sx` compiler/runtime/FFI bug, that slice stops. File
or link the `sx` issue, record it in the distribution run, mark
`sx-blocked`, and do not invent local workarounds unless Snarky explicitly
approves a narrow boundary change.
2. **Error model is pinned to landed `sx`, not imagined `sx`.**
No `!T` folklore, no planned syntax, no aspirational std signatures. Before
std work starts, pin the exact `sx` commit and include tiny real examples of
current error handling.
3. **M1 APK inspection is deliberately tiny.**
M1 only proves ZIP container access and confirms `AndroidManifest.xml` exists
with basic entry metadata. No AXML decoder, no package/version parsing, no
signature validation.
4. **Enterprise, MDM, and proxy readiness must be separate.**
Enterprise install, MDM install, and artifact-only IPA access are distinct
product states. `distd` behind a reverse proxy may validate configured HTTPS
reachability, but it must not claim to terminate or own TLS.
5. **Public visibility has iOS carve-outs.**
Public app visibility does not mean public IPA download. iOS artifact-only
IPAs require authenticated access, scoped token access, or signed install
link access.
6. **M1 is DB-free.**
M1 uses file-backed or JSON-backed state only. SQLite is M2.
## Accepted Opus Refinements
- M1 JSON output should become the shape later reused by HTTP and remote CI.
- `rejected` is terminal.
- M1 release path may be `draft -> published` with `validation=not_run`.
- Signed install links are HMAC over artifact/link identity plus expiry, with a
server secret.
- Download authorization must be a table, not prose soup.
- FFI is acceptable when named, Linux-first, thin, and replaceable.
## Rejected Or Deferred Items
- `pub`, alias imports, and namespace re-export are deferred from the product
critical path.
- Pure-`sx` crypto/archive/SQLite is deferred.
- HTTP, SQLite, admin UI, Docker/NAS deployment, full APK validation, and IPA
validation are not M1.
- Any layout redesign before product coverage is pinned is rejected.
## Plan Patch Backlog
1. Add `sx-blocked` state and cross-repo handoff rules.
2. Patch Subplan 01 to remove dangling `PLAN.md` references and pin landed
error handling.
3. Rewrite M1 as the DB-free walking skeleton.
4. Patch domain model: release states, validation outcome, channel promotion
history.
5. Patch CI manifest schema, example, idempotency key, rerun behavior.
6. Patch access policy with roles, visibility, token scopes, signed links, and
download table.
7. Patch validation policy with `required`, `warning`, `informational`,
`not_supported`.
8. Split Enterprise, MDM, proxy HTTPS readiness, and iOS artifact-only behavior.
## Implementation Still Blocked Until
- Distribution repo has a clean git baseline.
- Plan patches above are applied.
- Active run has `brief.md`, `state.json`, and `agents.json`.
- Current `sx` commit and error model are pinned.
- Opus produces a proposal for the exact slice.
- Snarky accepts product coverage.
- Allowed write paths and branch are explicit and clean.

267
.agents/runs/2026-06-02-orchestration-planning/opus-review.md Normal file
View File

@@ -0,0 +1,267 @@
# Opus Consultation - Distribution Platform Plan Review
## Context
Read-only review of the distribution platform plan package (`PLAN.md`,
`.agents/ORCHESTRATION.md`, `.agents/subplans/*.md`, checkpoints) against the
real state of the `sx` repository, from four lenses: design, technical
sequencing, implementation feasibility, and platform risk.
Verdict in one line: **the plan is well-written and the product model is mostly
right, but it is sequenced as if `sx` were a mature systems language. It is
not.** `sx` is self-described "highly experimental" with ~37 open compiler
issues and five active fix-streams, and its own governance forbids working
around compiler bugs. The plan's Phase 0-1 (build a full HTTP/TLS/SQLite/
crypto/JSON/archive stdlib in `sx` first) is the single largest risk and is
underestimated by roughly an order of magnitude.
This file is a consultation report, not an implementation plan. Findings are
severity-ordered with file references. The last sections are where Opus would
overrule/refine/ask, and the layout read on the rejected mock (Opus's authority
domain).
---
## Findings (severity-ordered)
### P0 - The two repos have incompatible governance; nobody owns the sx changes
- Distribution `ORCHESTRATION.md:24` makes Opus the *only* code writer, on
named git branches, under lease timeouts. But the work in subplan 01 is
**`sx` compiler + stdlib work**, and `sx/CLAUDE.md:5-65` ("IMPASSIBLE RULES")
mandates: the moment you hit a compiler bug, **STOP, file an issue, end the
session, wait for a fix in another session - do not work around it.**
- Building HTTP/TLS/SQLite/zip/crypto on an experimental compiler with 37 open
issues *will* hit unimplemented/buggy paths repeatedly (FFI itself is an
active, buggy stream: see `sx/issues/0043,0052,0057`). Under sx's own rules,
the distribution "Opus implementation" phase will keep hard-stopping.
- The two checkpoint systems (distribution `.agents/runs/*` vs sx
`current/CHECKPOINT-*.md`) have **no defined handoff**. There is no answer to
"who advances sx, in which repo's process, under whose lease."
- **This is the gating decision for the whole program** and it is not addressed
anywhere in the plan.
### P0 - Distribution workspace is not a git repo (already flagged, still true)
- `subplan 08:194-198`, `CHECKPOINT.md:48-53`, `checkpoint.json:8-11`. The
entire orchestration is branch-based; it cannot start. Snarky P0 is correct.
Trivial to fix (`git init` + baseline commit) but it blocks everything, so
it should be the literal first action.
### P1 - Phase 0 "language prerequisites" are largely gold-plating, not prerequisites
- `PLAN.md:159-190`, `subplan 01:23-52` require `pub` exports, alias imports,
and `pub print :: core.print` namespace re-export **before product code**.
- `pub`/module-member visibility **does not exist** in `sx` (specs.md:550 only
has import-scoped `impl` visibility) and is **on no active sx workstream**.
So the plan's first "blocking" slice is net-new parser/AST/resolver/
module-graph compiler work that nobody is scheduled to do.
- But `sx` already has namespaced imports (`math :: #import "..."`) and
import-scoped impl visibility. **The product can be built without `pub`.**
Treating it as a prerequisite front-loads hard compiler work and delays any
product signal. (See "Opus would overrule," below.)
### P1 - The server substrate that Phase 1 assumes does not exist, and the one primitive that does is wrong-platform
- Confirmed absent in `library/modules/`: HTTP, TLS, SQLite, JSON, SHA-256/
crypto, base64/hex, RFC3339/time, CLI parser, config, zip/tar/gzip. Subplan
01 Slices 6-8 (`subplan 01:104-145`) describe all of these as if they are
small deliverables. Each is a real subsystem.
- `library/modules/socket.sx:1-2,23-29` is the only networking code: raw POSIX,
**macOS-only** (`sin_len`, macOS `SO_REUSEADDR=0x4`), blocking `read`/`write`,
no event loop. The deployment target is **Linux Docker on UGREEN NAS**
(`PLAN.md:147-158`), where `sockaddr_in` has no `sin_len` and constants
differ. The HTTP foundation must be (re)written Linux-correct before `distd`
can run where it ships.
- Implication: every Phase-1 "slice" is actually a from-scratch systems library
on an unstable compiler. This is the bulk of the project, mislabeled as
foundation.
### P1 - `IPA`/`APK` validation needs a ZIP reader that does not exist
- `subplan 05:19-48` requires reading the zip structure of IPA (Info.plist) and
APK (AndroidManifest) to validate bundle id / version / signature. IPA and
APK are ZIP containers. There is no `std.archive`/zip reader (`subplan
01:137`), and `AndroidManifest.xml` inside an APK is *binary* XML (AXML), not
text - a non-trivial parser on its own. This is materially harder than the
one-line "manifest package id" bullet implies.
### P1 - Release/Channel model is internally contradictory and cannot support rollback as specified
- Snarky already flagged the redundancy (`Release.channel` at `subplan
02:43-54` vs `Channel.current_release_id` at `subplan 02:56-61`). Concur.
- Beyond that: `Channel` stores only `current_release_id` with **no promotion
history**. `dist release rollback` "moves a channel pointer to the previous
valid release" (`subplan 03:45-47`) - but "previous" is unknowable from a
single pointer. Rollback requires a promotion/channel-history table (or
deriving it from audit events). The data model as drawn cannot do what the
CLI promises.
- No release state machine is defined (`draft/validating/published/rejected/
superseded`). Snarky P1 #3 is correct and should block domain implementation.
### P1 - The multi-agent orchestration conflicts with the operator's own standing rules
- `ORCHESTRATION.md` + `subplan 08` are built on multiple named subagents
(Codex/Snarky/Opus) invoked through an `opus-runner` MCP plugin
(`ORCHESTRATION.md:136-146`), which is **unbootstrapped** ("may need Codex
reload before MCP tools are available," `CHECKPOINT.md:52-53`).
- The operator's global rules forbid subagent fan-out and require work in a
single visible thread. The orchestration design is therefore in direct
tension with how the operator actually wants work done. Either the global
rule is waived for this project, or the multi-agent machinery should be
dropped in favor of sequential single-thread phases with the same run-dir
artifacts. This needs an explicit decision before more tooling is built.
### P2 - Milestone 1 is the whole project, not a milestone
- `PLAN.md:259-272` bundles: sx language work + full stdlib + server + SQLite +
APK *and* IPA validators + channels + install pages + admin UI + Docker/NAS.
On an experimental language. Snarky P2 #8 is correct; I'd escalate it to P1
for scheduling purposes. Replace with a "walking skeleton" (below).
### P2 - Validation policy mixes requirements with wishful tooling
- `subplan 05` is full of "if tool support exists," "when provided," "malware
scan placeholder" (`05:55-89`). Concur with Snarky P2 #7: for v1 mark each
check `required | warning | informational | not-supported` and delete the
rest. Notarization/authenticode/malware-scan are out of reach for v1 and
should be `not-supported`, not aspirational statuses.
### P2 - iOS Enterprise vs MDM are conflated
- `subplan 04:50-52` / `05:24-28` treat "Enterprise/MDM" as one mode serving "a
signed HTTPS manifest plist for enrolled devices." Those are two different
mechanisms: `itms-services://` in-house (Apple Enterprise Program, cert-trust
on device) vs MDM-managed `InstallApplication`. The plist/host requirements
differ. The *product intent* (don't imply a normal iPhone can sideload) is
correct and is the strongest part of the plan - just split the two modes.
- Also: `distd` cannot self-satisfy the HTTPS requirement (no TLS); it relies on
the reverse proxy. `dist doctor`'s "HTTPS base URL" check (`subplan 03:14-16`)
can therefore only validate config/reachability, not terminate TLS itself.
State that explicitly so Enterprise mode isn't marked "ready" when it isn't.
### P2 - Subplan 01 still points implementers at deleted PLAN sections
- `subplan 01:18-21` tells implementers to read `Standard Library API Surface`
and `Detailed Std Struct And Method Sketches`, removed from `PLAN.md`. Snarky
P1 #4 confirmed; fix or the first sx session starts by chasing ghosts.
### P3 - CI manifest schema / idempotency undefined
- `subplan 03:48-63` lists fields but no JSON schema, example, idempotency key,
or rerun semantics. "CI is the primary writer" and "releases are immutable"
(`PLAN.md:38-42`) make rerun-of-same-build behavior a v1 correctness concern,
not a later detail. Define an idempotency key (app+version+build digest) now.
---
## Where Opus would overrule, refine, or ask Snarky
**Overrule - drop Phase 0 language work from the critical path.**
`pub`/alias-imports/namespace-re-export (`PLAN.md:194-196`, `subplan 01:23-52`)
are ergonomics, not blockers. sx already has namespaced imports and impl
visibility. Building net-new compiler features before the product compiles once
is exactly backwards on an unstable compiler. Opus would build the product
against the language as-is and only add `pub` if a concrete name-leak actually
bites. This reorders the whole plan and Opus would hold this line against a
"do it properly first" push.
**Overrule - Milestone 1 is replaced by a walking skeleton.** Opus's M1:
`dist ci publish --local-store` writes a content-addressed artifact to disk +
an in-memory/JSON-file domain model + one platform's metadata read (APK zip
entry only) + a JSON output contract. No HTTP, no SQLite, no TLS, no UI. This
exercises the real sx pain (fs, zip, hashing, JSON, CLI) on the smallest
surface and produces a runnable artifact in days, not a quarter. SQLite/HTTP/
admin-UI become M2+, each gated on the prior actually running on Linux.
**Refine - make the SHA-256 and zip decisions explicitly FFI-first.** Pure-sx
streaming SHA-256 and inflate are real projects and will trip compiler bugs.
Bind libsqlite3, a crypto lib (CommonCrypto on mac / OpenSSL on Linux), and
miniz/libzip via `#foreign` first; only reimplement in sx if FFI proves worse.
This trades "pure sx" purity for actually shipping, and keeps bug-surface on the
linker, not the comptime evaluator.
**Refine - model promotion history, not just a channel pointer.** Add a
`channel_release` history (or derive rollback from audit). Without it, rollback
is undefined.
**Ask Snarky to decide before any code:**
1. Is the goal to *ship a NAS release console* or to *mature sx*? They imply
opposite sequencing. If shipping is the goal, the sx-first framing is wrong.
2. Is the multi-agent/opus-runner machinery actually required, given the
operator's single-thread rule? If not, delete it and keep only run-dir
artifacts.
3. Linux-first or macOS-first for `distd` runtime? The only socket code is
macOS-only; the deploy target is Linux. Pick one and make the socket layer
match it before "server skeleton."
4. For v1, is FFI-to-system-libs acceptable, or is "pure sx stdlib" a hard
product constraint? This single answer changes the size of the project by
months.
---
## Layout read on the rejected mock (Opus authority domain)
The mock (`index.html`, `styles.css`) is **not** weak at the system level: warm
off-white token palette, semantic green/amber/red with soft fills, Inter, a real
shadow token, a clean CSS-grid shell (224px sidebar + 64px topbar,
`styles.css:49-69`). The information architecture (apps list + detail, release,
install, tokens, audit, settings) matches the brief. So the rejection is almost
certainly about *finish and tone*, not structure:
1. **Placeholder iconography reads as a wireframe.** Single letters as icons
everywhere: brand "d," nav glyphs `A/R/I/T/L/S` (`index.html:41-64`), top
actions literally rendering "R" for sync and "!" for notifications
(`index.html:26-31`), 2-letter app monograms, and a QR faked as empty
`<span>`s (`index.html:439-446`). Nothing signals "unfinished" harder than
letter-in-a-box icons. A minimal real stroke-icon set would lift perceived
quality more than any layout change.
2. **Tone fights the brief.** The brief wants "operational SaaS density, quiet,
no oversized marketing hero" (`subplan 06:64-72`). The mock leans airy/
card-y with big metric numbers and a phone-mockup hero on the Install tab
(`index.html:362-382`) - that's the marketing-flavored hero the brief warns
against. A release console likely wants a denser, cooler, more devtools/
terminal register than warm paper.
3. **Six fake views via class-toggle** inflate surface area that all has to look
finished at once; it spreads the polish too thin.
Opus's design direction for `opus/redesign-distribution-mock`: keep the 3-zone
shell and IA; (a) replace every letter-glyph with a real minimal icon set; (b)
shift to a cooler, denser operator palette and a tighter type/spacing scale; (c)
demote the Install phone-hero to an inline preview, not a centerpiece; (d) make
the first viewport land on real working content (apps + latest release), per
`subplan 06:94-99`; (e) keep the iOS TestFlight/Enterprise/Artifact distinction
loud - it's the one thing the current mock gets exactly right
(`index.html:384-437`).
---
## Recommended re-sequencing (concise)
1. `git init` the distribution workspace; baseline commit. (Unblocks
everything.)
2. Snarky decides the four questions above (ship-vs-mature, agents-yes/no,
Linux-vs-mac, FFI-vs-pure-sx). These are gating.
3. Drop Phase 0 language work from the critical path.
4. Build the walking-skeleton M1 (`dist ci publish --local-store`, content-
addressed fs store, JSON contract, APK zip-entry read) against sx as-is,
FFI-first for hash/zip.
5. Only then add SQLite (FFI), then the HTTP server (Linux-correct sockets),
then install pages, then admin UI - each gated on the prior running on the
actual Linux/NAS target.
6. In parallel and independently: the mock redesign (no backend dependency),
under Opus design direction above.
## Verification (how to sanity-check the re-scope, read-only)
- Confirm `pub` truly absent: `sx ir` / compile a probe with `pub x :: 1` and
observe parser rejection (don't land it - just confirm scope of work).
- Confirm Linux socket gap: attempt `sx build --target linux` of a trivial
`socket.sx` consumer and observe `sin_len` mismatch.
- Confirm error model present (it is): `sx/CHECKPOINT-ERR.md:15`, plus the
`examples/10xx-errors-*` suite passing (341 tests, `CHECKPOINT-ERR.md:42-43`).
- For the redesign: build the static mock and screenshot the first viewport on
desktop + mobile widths to validate the "working content first, no hero"
acceptance (`subplan 06:94-99`).
</content>
</invoke>

20
.agents/runs/2026-06-02-orchestration-planning/progress.log Normal file
View File

@@ -0,0 +1,20 @@
2026-06-02 14:28:30 EEST - Created active planning run after noticing the observability dashboard only showed durable run records.
2026-06-02 14:28:30 EEST - Registered Codex manager as the active planning agent.
2026-06-02 14:28:30 EEST - Next action: explain that planning sessions must create .agents/runs records to be visible.
2026-06-02 14:30:39 EEST - Reviewing PLAN.md and .agents/subplans for gaps.
2026-06-02 14:31:38 EEST - User asked to introduce Snarky and Opus to review the plan gaps.
2026-06-02 14:33:00 EEST - Snarky and Opus marked running for plan-gap consultation.
2026-06-02 14:33:00 EEST - Snarky spawned as sub-agent Locke / 019e881c-6aa7-7901-8069-22411d955e06.
2026-06-02 14:34:22 EEST - Opus CLI consultation blocked pending explicit approval for external plan-file disclosure.
2026-06-02 14:34:22 EEST - Snarky completed plan review; saved to snarky-review.md.
2026-06-02 14:36:22 EEST - User asked how to give Opus access; waiting for explicit approval scope.
2026-06-02 14:37:39 EEST - User approved Opus access to the entire distribution and sx repos for consultation.
2026-06-02 14:39:33 EEST - Opus Claude CLI review running with read-only tools and access to distribution plus sx repos.
2026-06-02 14:45:10 EEST - Opus completed review; saved to opus-review.md.
2026-06-02 14:50:05 EEST - User requested a few more Snarky/Opus discussion rounds before implementation.
2026-06-02 14:50:05 EEST - Snarky round 1 spawned as sub-agent Linnaeus / 019e882b-f0a8-7ed1-ab9d-fa32caf8d5ad.
2026-06-02 14:50:05 EEST - Snarky round 1 completed and saved to discussion-round-1-snarky.md.
2026-06-02 14:56:10 EEST - Opus round 1 completed and saved to discussion-round-1-opus.md.
2026-06-02 14:56:58 EEST - Snarky round 2 spawned as sub-agent Fermat / 019e8831-eab0-7f20-9536-fb10f0f906f0.
2026-06-02 14:57:20 EEST - Snarky round 2 completed and saved to discussion-round-2-snarky.md.
2026-06-02 15:02:05 EEST - Opus round 2 completed and saved to discussion-round-2-opus.md.

63
.agents/runs/2026-06-02-orchestration-planning/snarky-review.md Normal file
View File

@@ -0,0 +1,63 @@
# Snarky Review
Findings first, because vibes are not a roadmap.
1. **P0: Opus cannot implement yet because the workspace has no git baseline.**
Branch-based implementation is mandatory, but the plan admits this workspace
is not a git repo. Snarky will not approve an Opus implementation phase until
git is initialized or attached and the current baseline is committed.
2. **P1: Access policy is hand-waved, and this product lives or dies there.**
The plan names actors and says access policy decides install/download, but
does not define auth modes, human sessions, public links, private apps, app
ownership, RBAC, or scoped install access. "Authenticated and public modes"
is not a model.
3. **P1: Release lifecycle is internally muddy.**
Releases are supposed to be immutable and channels mutable. But `Release`
still has `channel`, while `Channel` separately points to
`current_release_id`. Also the CLI creates a draft release, validates,
publishes, and maybe promotes, but no state machine is defined. Define
`draft`, `validating`, `published`, `rejected`, `superseded`, etc.
4. **P1: The std subplan references sections that no longer exist.**
Subplan 01 tells implementers to read `Standard Library API Surface` and
`Detailed Std Struct And Method Sketches`. Those were removed from
`PLAN.md`.
5. **P1: CI manifest and idempotency are underspecified.**
The CLI plan gives required fields, but not a schema, examples, retry
semantics, duplicate release behavior, idempotency keys, or what happens
when CI reruns the same build.
6. **P1: HTTP API is too abstract to build against.**
The API plan lists slices but no concrete routes, request bodies, response
schemas, pagination/filtering, auth errors, upload protocol, or download
authorization rules.
7. **P2: Validation policy mixes product requirements with wishful tooling.**
"If tool support exists," "provided or checked," and "malware scan
placeholder" are not acceptance criteria. For v1, mark each check as
`required`, `warning`, `informational`, or `not supported`.
8. **P2: Milestone 1 is too large to be a milestone.**
It includes sx primitives, local server, APK and IPA publishing, SQLite,
channels, install pages, admin UI, and NAS Docker deployment.
## Required Before Opus Implements
- Create a clean git baseline.
- Write a Snarky `brief.md` for the redesign run with hard acceptance criteria.
- Resolve the minimum product model for the mock: release states, channel
behavior, access modes, token scopes, and iOS install modes.
- Provide seed data and required UI states Opus must represent.
- Let Opus produce a design proposal first. No code until Snarky accepts the
product coverage.

12
.agents/runs/2026-06-02-orchestration-planning/state.json Normal file
View File

@@ -0,0 +1,12 @@
{
"schema": 1,
"run_id": "2026-06-02-orchestration-planning",
"current_phase": "snarky-opus-discussion",
"current_branch": null,
"input_artifact": "user request: why is the current planning session not visible in observability",
"input_hash": "manual-current-turn",
"expected_output_artifact": ".agents/runs/2026-06-02-orchestration-planning/progress.log",
"retry_count": 0,
"next_action": "Apply consensus plan patches, then create a git baseline before implementation.",
"blocker": null
}