mesh

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, reduction, 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. 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. 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 . 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. 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 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/reducer/fixer/prover/integrator rows over the same scope without a blocker-triggered reason 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.