mesh

Intent

$mesh is the high-fanout batch-execution path for Codex once repeated leaf work has been shaped.

It is for already-shaped leaf work, not for planning or decomposition.

Use it when:

• the user explicitly asks for $mesh , or repeated leaf work is already clearly row-shaped

• the workload is row-shaped and homogeneous

• each row can be processed independently

• each row represents one substantive unit with a unique scope and acceptance target

• you want structured per-row results exported to CSV

• planning is complete and the remaining work is leaf execution

Do not use it when:

• the work is research, review, debate, or design

• the task still needs decomposition or shared judgment

• tasks share context or depend on one another

• multiple workers would touch the same mutable scope

• direct spawn_agent delegation or local execution is clearer

Native Architecture Fit

• $mesh maps to spawn_agents_on_csv , not a separate runtime protocol.

• The batch job spawns one worker sub-agent per CSV row.

• The main call blocks until the batch finishes.

• Each worker must call report_agent_job_result exactly once.

• Results are exported to output_csv_path or a default output CSV.

• Planning happens before the batch starts; $mesh executes the already-shaped rows.

Recommended Uses

• audit one file per row

• classify one ticket, log chunk, or document per row

• extract structured fields from many inputs

• run the same bounded transformation over a file list with disjoint outputs

• execute one disjoint implementation unit per row after $select or $teams has already shaped the wave

If the work is heterogeneous, use $teams or direct spawn_agent instead.

Composite vs Leaf Fit

Use $mesh only when every row is already a leaf task:

• clear inputs from CSV columns

• one instruction template for every row

• no cross-row coordination

• one structured result per row

If you still need to decide the row schema, challenge the approach, or compare strategies, do that work before $mesh , usually with $teams or locally.

Substantive-unit rule

• One row should represent one unique work unit with one unique write or read scope and one acceptance target.

• Do not multiply rows over the same scope merely to create more lanes, more evidence, or a higher concurrency number.

• Treat a clean primary row as sufficient evidence for that unit.

• Only add secondary review, coder, fixer, prover, or integration rows when a prior row reports a concrete blocker, a failed proof, or a non-trivial diff that needs another pass.

• Deprecated shims (reducer , mentor , locksmith , applier ) are never valid fresh rows.

Recommended Flow

• Confirm planning is complete and the rows are truly homogeneous and independent.

• Build a CSV with stable headers and, when useful, a stable id_column ; keep one row per substantive unit.

• Prefer task_id as the stable row id when the batch came from an OrchPlan or $st claim set.

• Write one instruction template using {column} placeholders and one primary deliverable per row.

• Choose only the controls you need: output_schema , output_csv_path , max_concurrency , max_runtime_seconds ; set max_concurrency to the safe row count unless a lower cap is required.

• Run spawn_agents_on_csv .

• Only queue secondary rows for units that reported a concrete blocker, a failed proof, or a non-trivial diff needing another pass.

• Review the exported CSV and do any integration or follow-up work locally or with $teams .

• If $st owns execution state, reconcile the export with st import-mesh-results --input <output.csv> before closing the wave.

Concrete Examples

Example 1: Audit one file per row

Goal:

Check every markdown file for required frontmatter keys and export one result row per file.

Example CSV:

id,path 1,docs/intro.md 2,docs/setup.md

Example instruction template:

Inspect {path}. Report whether the required frontmatter keys exist and list any missing keys.

Why $mesh :

• every row uses the same template

• every row is independent

• the result can be captured as one structured object per file

Example 2: Classify support tickets

Goal:

Classify 2,000 support tickets by product area and urgency, then export the labels to CSV.

Example CSV:

ticket_id,text T-1001,"Billing page shows a 500 error" T-1002,"How do I rotate an API key?"

Example output schema:

{ "type": "object", "properties": { "area": { "type": "string" }, "urgency": { "type": "string" }, "needs_human": { "type": "boolean" } }, "required": ["area", "urgency", "needs_human"] }

Why $mesh :

• this is repeated, read-only classification work

• the schema makes the per-row output easy to compare and post-process

Example 3: Disjoint file transformation

Goal:

Rewrite a large set of generated summaries, one output file per input file, with no shared destinations.

Good $mesh setup:

• CSV columns such as id,input_path,output_path

• one instruction template that reads {input_path} and writes only {output_path}

• one JSON result confirming whether the row succeeded

Why $mesh :

• the write scopes are disjoint

• the same bounded transformation repeats for every row

Example 4: Disjoint implementation units

Goal:

Execute the first safe implementation wave from an OrchPlan where each task already owns a disjoint scope.

Good $mesh setup:

• CSV columns such as id,objective,write_scope,proof_command

• one primary row per implementation unit, not one row per reviewer lane

• max_concurrency set to the number of safe disjoint units

• follow-up prover or fixer rows added only for units that failed proof or reported blockers

Why $mesh :

• the work is repeated leaf execution after planning is complete

• each row owns a unique scope and has a concrete acceptance target

• the batch gets real fanout without inventing synthetic evidence lanes

Counterexample: one feature across shared code

Do not use $mesh for:

Add a feature that changes shared parser logic, server behavior, and the UI.

Why not:

• the work still needs decomposition and coordination

• the rows would not be independent

• shared mutable files make $teams or local execution the safer path

Row Design Rules

• Keep each row objective concrete and bounded.

• Make each row one substantive unit with a unique scope and acceptance target.

• Keep write_scope aligned with the canonical lock-root contract in codex/skills/select/references/lock-roots.md .

• Prefer read-only work or disjoint write scopes.

• Keep result objects structured and comparable across rows.

• Use stable row ids when you will reconcile outputs later.

• Do not multiply rows by role or lane on the same scope unless a blocker or failed proof justifies the follow-up.

• If you need reduction thinking, keep it inside coder by setting approach=reduce ; do not resurrect reducer as a new row type.

• If rows need shared mutable state, stop and switch away from $mesh .

• If a row still needs planning, stop and finish decomposition before running the batch.

Result Contract

• Every worker must report exactly one JSON result via report_agent_job_result .

• Missing reports are failures.

• Narrative text is non-authoritative; the structured result is what matters.

• If you provide an output_schema , keep it minimal and aligned with the fields you actually need.

See references/output-contract.md .

Anti-patterns

• using $mesh as a general replacement for $teams

• doing recursive planning or debate inside the batch workers

• splitting one tightly coupled implementation across dependent rows

• overlapping write scopes across rows

• launching a synthetic evidence wave after the substantive work is already done

• multiplying coder/fixer/prover/integrator rows over the same scope without a blocker-triggered reason

• routing fresh work through deprecated shims instead of the live core roles

• relying on free-form text instead of structured result fields

• reusing the same path for csv_path and output_csv_path

See references/orchestration-anti-patterns.md .

Final Response

When mesh actually ran, include a short Orchestration Ledger in prose.

Good fields:

• Skills used

• Subagents

• Artifacts produced

• Cleanup status

Omit the section entirely when no orchestration ran.

Handoff From $teams

If $teams hands work to $mesh , the handoff should include:

• confirmation that planning is complete and only leaf execution remains

• the CSV or row schema

• the instruction template

• the expected output fields

• any concurrency or timeout assumptions

Do not add extra lane, quorum, or state-machine protocols unless the runtime actually provides them.