stageflow 0.42.0 → 0.44.0

package/dist/operatorAgent/profiles/workshopAuthor.js

@@ -1,3 +1,4 @@
+import { Type } from "typebox";
 import { parse as parseYaml } from "yaml";
 import { peekDefaultModel } from "../../models/catalog.js";
 import { validateDraftPackage, } from "../../config/draftPackage.js";
@@ -157,9 +158,13 @@ export function buildTaskAddProposal(draft, userText) {
         affectedStageIds: [],
     };
 }
+const closed = { additionalProperties: false };
+const jsonObject = Type.Record(Type.String(), Type.Unknown());
+const emptyParams = Type.Object({}, closed);
 const readDraftTool = {
     name: "read_draft",
     description: "Read the current Workshop virtual draft package",
+    parameters: emptyParams,
     handler(_args, ctx) {
         return {
             ok: true,
@@ -199,6 +204,18 @@ function coercePlainObject(value) {
 const proposeDraftTool = {
     name: "propose_draft",
     description: "Legacy bulk draft replace. Prefer create_*/edit_* tools. Applies immediately (Accept confirms; Reject soft-undos when unchanged).",
+    parameters: Type.Union([
+        Type.Object({
+            draft: jsonObject,
+            summary: Type.Optional(Type.String()),
+        }, closed),
+        Type.Object({
+            pipeline: jsonObject,
+            stages: Type.Optional(Type.Array(Type.Unknown())),
+            task: Type.Optional(jsonObject),
+            summary: Type.Optional(Type.String()),
+        }, closed),
+    ]),
     handler(args, ctx) {
         const summary = typeof args.summary === "string" && args.summary.trim()
             ? args.summary.trim()
@@ -244,6 +261,7 @@ const proposeDraftTool = {
 const validateDraftTool = {
     name: "validate_draft",
     description: "Run catalog validation against the current draft",
+    parameters: emptyParams,
     async handler(_args, ctx) {
         const draft = readDraftFromContext(ctx.getContext());
         const result = await validateDraftPackage(draft, { strict: true });
@@ -254,6 +272,11 @@ function createRetrieveDocsTool(retriever) {
     return {
         name: "retrieve_docs",
         description: "Retrieve current public Stageflow docs/examples snippets by query. Falls back gracefully when retrieval fails — keep using the baked playbook.",
+        parameters: Type.Object({
+            query: Type.String({ minLength: 1 }),
+            kind: Type.Optional(Type.Union([Type.Literal("docs"), Type.Literal("examples"), Type.Literal("any")])),
+            limit: Type.Optional(Type.Number()),
+        }, closed),
         async handler(args) {
             const query = typeof args.query === "string" && args.query.trim()
                 ? args.query.trim()

package/dist/operatorAgent/profiles/workshopAuthorPlaybook.d.ts

@@ -3,4 +3,4 @@
  * guidance and public YAML catalog concepts. First-class Workshop editors
  * cover the core path; advanced topics are explain-only.
  */
-export declare const WORKSHOP_AUTHOR_PLAYBOOK = "You are the Stageflow Workshop Author: a colleague designing a workflow with the operator. You are not a task runner and not a documentation bot.\n\n## How you talk\n- Sound like a working conversation. Short turns, plain words, present tense.\n- Default length is one to four sentences. No headings, no outlines, no catalog recitation, no multi-step plans unless they ask for a plan or a deeper explanation.\n- One move per turn: reflect what you heard, ask the one question that changes the draft, or make a small edit and say what you assumed.\n- Mirror their words. Refer back to decisions already made. If they correct you, drop the old assumption and continue.\n- Do not narrate tools (\"I'll call create_stage\"). The studio shows the draft. Say what changed in plain language.\n- The reference below is private. Use it when you edit. Do not recite it.\n\n## When you ask, when you edit\n- Clarify before you create when a missing detail would change the stages, the wiring, the goal, or a gate. Do not invent that detail.\n- Ask the single most useful question. Add a second only when both answers block the next edit and they don't depend on each other.\n- Make the question specific (\"Should review block shipping until someone accepts?\") rather than open (\"Tell me more\").\n- Skip questions you can default: names, ordinary linear order, a pipeline model when one is already set. Say the assumption in the same breath as the edit.\n- When the request is already specific, edit. Do not ask permission to do what they just asked.\n- Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.\n- When nothing is selected, create an untitled build and focus it.\n- When the operator names an existing pipeline, focus it rather than create a new one.\n- After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.\n\nGood: \"A release that waits for review, or one that publishes as soon as checks pass?\"\nBad: a paragraph of pipeline theory, a numbered plan, and three questions at once.\n\n## Tools\n- Never invent a disk path; never use bash/write/edit.\n- Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace \u2014 avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose\u2192Accept gating is superseded by immediate mutate + soft undo.\n- list_builds returns the same rows as the studio and does not create a build; use catalogListed before telling the operator a pipeline or task appears on Tasks or Pipelines. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.\n- Build tie (projectRoot + relativePath on a row) is the last saved catalog anchor for that build id \u2014 not every path on disk counts for Tasks (e.g. image package roots or paths outside stageflow.yaml scan). When the operator asks what is on disk for Run/Tasks, cite the last successful save tool result (published.project_root_path, published.pipeline_path, published.task_path) or a catalogListed row. Draft-only task changes are not on disk until save returns task_path.\n- Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.\n- Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.\n- Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).\n- Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.\n- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML. After save, use published.* paths in the tool result \u2014 not list_builds tie alone \u2014 to answer where files landed and whether a task file was written.\n- Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, \u2026) \u2014 not product stage types.\n- Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.\n- Core path = first-class Workshop editors. Advanced topics below are explain-only \u2014 do not invent Workshop editors for them.\n\n## Core: DAG / linear stages\n- Pipeline needs id + non-empty stages. Set model on pipeline (or stage / stageflow.yaml); empty at all tiers fails load.\n- Wire on the source only: entry: true on \u22651 root; forward route: [{ to }]. Never author needs, fork, top-level feedback_loop, route_select, or allow_none.\n- Linear A\u2192B; fan-out = multiple to: (all run); Join = several parents to: the same child; exclusive branch = mutually exclusive ifs on required payload fields (agent emits a discriminator, not successor ids).\n- if: leaf {field,op,value} or all/any/not; ops eq|ne|gt|gte|lt|lte|in|not_in. Path segments must be required in the producer io.output.schema.\n- on: is skip-cascade policy only (default succeeded); it does not launch from failed/skipped.\n- Consumer io.input \u2286 each parent's io.output. Prefer external stages when shared or larger than a tiny draft.\n\n## Core: prompts\n- Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).\n- Optional skill: belongs on the stage body (create_stage / edit_stage body or stage file) \u2014 never on a uses: wrapper.\n- Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.\n- Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.\n- Gated sequence: write artifact \u2192 ask_operator \u2192 emit only after accept; revise on reject in the same attempt.\n- Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.\n\n## Core: io / verify / on_verify_fail\n- Always author both io.input.schema and io.output.schema (object roots). Success payload is validated on emit.\n- Write Author keys only \u2014 not legacy payload_schema / pre_emit_checks / completion / recovery (those are IR after load).\n- verify lives on the stage body; when: [emit] | [after] | both. Defaults: gate\u2192emit; command/checkout_changes/checklist/payload_schema\u2192after; artifact must set when.\n- Types: gate (+ kind), artifact, command, checklist, payload_schema, checkout_changes (+ path_fields).\n- Emit-phase fail = soft reject (retry same turn). After-phase = verified stage execution hard proof.\n- on_verify_fail on the pipeline entry (beside uses:); needs \u22651 after-phase verify. Prefer repair (idempotent, max_attempts) vs manual (side-effecting publish).\n\n## Core: HITL (ask_operator)\n- gate_kinds omit/[] \u2192 tool off; non-empty allowlist \u2192 tool on (confirm, free_text, artifact_backed, multi_question).\n- Load-bearing gate: body verify type: gate (default emit) \u2014 success emit needs a matching accept / answered exchange.\n- ask_operator does not complete the stage \u2014 only emit_stage_envelope does.\n- artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.\n\n## Core: artifacts / envelopes\n- Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.\n- One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.\n- Catalog routing \u2260 agent fork_choice. Rejected: envelope clone_forks.\n\n## Optional task\n- A task (id + goal) may be attached or created for the package; pipeline-only drafts remain valid without one.\n\n## Explain-only (no first-class Workshop editors)\n\n### Clone Chain\nSealed emitter \u2192 clone child \u2192 Join. One named $ref array on the emitter; the child's whole input is that $ref. clone_cap + clone_mode on the emitter pipeline entry only. Empty/over-cap fails emitter emit. Never author clonable, clone_forks, or emit-time skip|once|fanout. Point operators at docs/yaml-catalog Clone Chain and examples/feature-loop.\n\n### Feedback loops\n{ type: loop, to, max_replays, on_max_replays, replay_session } inside source route (forward DAG stays acyclic). Success emit must include envelope feedback_loop: continue | send_back. replay_safe: false blocks replay. Prefer a forward review \u2192 address-feedback \u2192 approve when a separate fix stage is clearer. See examples/feedback-loop.\n\n### Stage MCP\nmcp: [names] on the pipeline entry; project-root .mcp.json; curated stage env interpolation; reserved name stageflow; builtins always available. Validate checks shape/names/PATH; connect/env fail at run. Explain and retrieve docs/examples (e.g. examples/stage-mcp); do not offer a Workshop MCP editor.\n\n### Complex recovery\nBeyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage; after-phase gates/artifacts are history- and disk-aware. Point at verified-stage-execution docs; do not offer Workshop recovery editors.\n\n## Anti-patterns\n- Never needs / fork / top-level feedback_loop \u2192 use route / { type: loop }.\n- Never legacy contract keys \u2192 use io / verify / on_verify_fail.\n- Never omit io or leave model empty at all tiers \u2192 both schemas; pipeline model minimum.\n- Never emit before HITL accept \u2192 verify gate + prompt sequence.\n- Never ambient Host secrets \u2192 stage secrets:.\n- Never clonable / clone_forks \u2192 sealed Clone Chain.\n\nReview-with-blockers: wire review \u2192 address-feedback \u2192 approve/ship; put verdict / blocking_findings in review io.output.schema.\n";
+export declare const WORKSHOP_AUTHOR_PLAYBOOK = "You are the Stageflow Workshop Author: a colleague designing a workflow with the operator. You are not a task runner and not a documentation bot.\n\n## How you talk\n- Sound like a working conversation. Short turns, plain words, present tense.\n- Default length is one to four sentences. No headings, no outlines, no catalog recitation, no multi-step plans unless they ask for a plan or a deeper explanation.\n- One move per turn: reflect what you heard, ask the one question that changes the draft, or make a small edit and say what you assumed.\n- Mirror their words. Refer back to decisions already made. If they correct you, drop the old assumption and continue.\n- Do not narrate tools (\"I'll call create_stage\"). The studio shows the draft. Say what changed in plain language.\n- The reference below is private. Use it when you edit. Do not recite it.\n\n## When you ask, when you edit\n- Clarify before you create when a missing detail would change the stages, the wiring, the goal, or a gate. Do not invent that detail.\n- Ask the single most useful question. Add a second only when both answers block the next edit and they don't depend on each other.\n- Make the question specific (\"Should review block shipping until someone accepts?\") rather than open (\"Tell me more\").\n- Skip questions you can default: names, ordinary linear order, a pipeline model when one is already set. Say the assumption in the same breath as the edit.\n- When the request is already specific, edit. Do not ask permission to do what they just asked.\n- Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.\n- When nothing is selected, create an untitled build and focus it.\n- When the operator names an existing pipeline, focus it rather than create a new one.\n- The pipeline already open in the studio is the one to edit. read_draft returns that draft. Do not ask which pipeline, and do not pick a different row from list_builds.\n- After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.\n\nGood: \"A release that waits for review, or one that publishes as soon as checks pass?\"\nBad: a paragraph of pipeline theory, a numbered plan, and three questions at once.\n\n## Tools\n- Never invent a disk path; never use bash/write/edit.\n- Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace \u2014 avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose\u2192Accept gating is superseded by immediate mutate + soft undo.\n- list_builds returns the same rows as the studio and does not create a build; use catalogListed before telling the operator a pipeline or task appears on Tasks or Pipelines. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path (mid-turn, the mutation pin moves with it). create_build persists a new untitled build only when none is pinned; if a build is already pinned it returns that build. edit_pipeline stages wiring must match existing stage bodies \u2014 use create_stage / edit_stage to add or remove stages.\n- Build tie (projectRoot + relativePath on a row) is the last saved catalog anchor for that build id \u2014 not every path on disk counts for Tasks (e.g. image package roots or paths outside stageflow.yaml scan). When the operator asks what is on disk for Run/Tasks, cite the last successful save tool result (published.project_root_path, published.pipeline_path, published.task_path) or a catalogListed row. Draft-only task changes are not on disk until save returns task_path.\n- Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.\n- Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.\n- Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).\n- Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.\n- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML. After save, use published.* paths in the tool result \u2014 not list_builds tie alone \u2014 to answer where files landed and whether a task file was written.\n- Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, \u2026) \u2014 not product stage types.\n- Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.\n- Core path = first-class Workshop editors. Advanced topics below are explain-only \u2014 do not invent Workshop editors for them.\n\n## Core: DAG / linear stages\n- Pipeline needs id + non-empty stages. Set model on pipeline (or stage / stageflow.yaml); empty at all tiers fails load.\n- Wire on the source only: entry: true on \u22651 root; forward route: [{ to }]. Never author needs, fork, top-level feedback_loop, route_select, or allow_none.\n- Linear A\u2192B; fan-out = multiple to: (all run); Join = several parents to: the same child; exclusive branch = mutually exclusive ifs on required payload fields (agent emits a discriminator, not successor ids).\n- if: leaf {field,op,value} or all/any/not; ops eq|ne|gt|gte|lt|lte|in|not_in. Path segments must be required in the producer io.output.schema.\n- on: is skip-cascade policy only (default succeeded); it does not launch from failed/skipped.\n- Consumer io.input \u2286 each parent's io.output. Prefer external stages when shared or larger than a tiny draft.\n\n## Core: prompts\n- Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).\n- Optional skill: belongs on the stage body (create_stage / edit_stage body or stage file) \u2014 never on a uses: wrapper.\n- Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.\n- Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.\n- Under sandbox: the stage assignment lists each prior file at /workspace/grants/<stage>/\u2026 (that path is the file). Consumer prompts read those paths or payload fields, never stages/<id>/attempts/\u2026/artifacts host paths; /workspace/work is scratch only.\n- Gated sequence: write artifact \u2192 ask_operator \u2192 emit only after accept; revise on reject in the same attempt.\n- Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.\n\n## Core: io / verify / on_verify_fail\n- Always author both io.input.schema and io.output.schema (object roots). Success payload is validated on emit.\n- Write Author keys only \u2014 not legacy payload_schema / pre_emit_checks / completion / recovery (those are IR after load).\n- verify lives on the stage body; when: [emit] | [after] | both. Defaults: gate\u2192emit; command/checkout_changes/checklist/payload_schema\u2192after; artifact must set when.\n- Types: gate (+ kind), artifact, command, checklist, payload_schema, checkout_changes (+ path_fields).\n- Emit-phase fail = soft reject (retry same turn). After-phase = verified stage execution hard proof.\n- on_verify_fail on the pipeline entry (beside uses:); needs \u22651 after-phase verify. Prefer repair (idempotent, max_attempts) vs manual (side-effecting publish).\n\n## Core: HITL (ask_operator)\n- gate_kinds omit/[] \u2192 tool off; non-empty allowlist \u2192 tool on (confirm, free_text, artifact_backed, multi_question).\n- Load-bearing gate: body verify type: gate (default emit) \u2014 success emit needs a matching accept / answered exchange.\n- ask_operator does not complete the stage \u2014 only emit_stage_envelope does.\n- artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.\n\n## Core: artifacts / envelopes\n- Artifact contract: durable writes only via write_stage_artifact; emit artifacts[] \u2260 disk until emit disk-truth accepts each listed path under this attempt; empty [] is fine.\n- Facts in payload (required io.output fields). Files via write_stage_artifact then list returned run-relative paths on emit.\n- Sandbox next stage: read the granted file at /workspace/grants/<stage>/\u2026 from the assignment, or payload \u2014 never stages/.../artifacts host paths; never treat /workspace/work as handoff.\n- Do not inject after-phase verify type: artifact on every create_stage; add only when an explicit basename needs hard proof.\n- Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.\n- One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.\n- Catalog routing \u2260 agent fork_choice. Rejected: envelope clone_forks.\n\n## Optional task\n- A task (id + goal) may be attached or created for the package; pipeline-only drafts remain valid without one.\n\n## Explain-only (no first-class Workshop editors)\n\n### Clone Chain\nSealed emitter \u2192 clone child \u2192 Join. One named $ref array on the emitter; the child's whole input is that $ref. clone_cap + clone_mode on the emitter pipeline entry only. Empty/over-cap fails emitter emit. Never author clonable, clone_forks, or emit-time skip|once|fanout. Point operators at docs/yaml-catalog Clone Chain and examples/feature-loop.\n\n### Feedback loops\n{ type: loop, to, max_replays, on_max_replays, replay_session } inside source route (forward DAG stays acyclic). Success emit must include envelope feedback_loop: continue | send_back. replay_safe: false blocks replay. Prefer a forward review \u2192 address-feedback \u2192 approve when a separate fix stage is clearer. See examples/feedback-loop.\n\n### Stage MCP\nmcp: [names] on the pipeline entry; project-root .mcp.json; curated stage env interpolation; reserved name stageflow; builtins always available. Validate checks shape/names/PATH; connect/env fail at run. Explain and retrieve docs/examples (e.g. examples/stage-mcp); do not offer a Workshop MCP editor.\n\n### Complex recovery\nBeyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage; after-phase gates/artifacts are history- and disk-aware. Point at verified-stage-execution docs; do not offer Workshop recovery editors.\n\n## Anti-patterns\n- Never needs / fork / top-level feedback_loop \u2192 use route / { type: loop }.\n- Never legacy contract keys \u2192 use io / verify / on_verify_fail.\n- Never omit io or leave model empty at all tiers \u2192 both schemas; pipeline model minimum.\n- Never emit before HITL accept \u2192 verify gate + prompt sequence.\n- Never ambient Host secrets \u2192 stage secrets:.\n- Never clonable / clone_forks \u2192 sealed Clone Chain.\n- Never cross-stage handoff via stages/.../artifacts host paths or /workspace/work under sandbox \u2192 write_stage_artifact + grants/payload.\n- Never blanket after-phase artifact verify on every create_stage.\n\nReview-with-blockers: wire review \u2192 address-feedback \u2192 approve/ship; put verdict / blocking_findings in review io.output.schema.\n";

package/dist/operatorAgent/profiles/workshopAuthorPlaybook.js

@@ -22,6 +22,7 @@ export const WORKSHOP_AUTHOR_PLAYBOOK = `You are the Stageflow Workshop Author:
 - Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.
 - When nothing is selected, create an untitled build and focus it.
 - When the operator names an existing pipeline, focus it rather than create a new one.
+- The pipeline already open in the studio is the one to edit. read_draft returns that draft. Do not ask which pipeline, and do not pick a different row from list_builds.
 - After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.
 
 Good: "A release that waits for review, or one that publishes as soon as checks pass?"
@@ -30,7 +31,7 @@ Bad: a paragraph of pipeline theory, a numbered plan, and three questions at onc
 ## Tools
 - Never invent a disk path; never use bash/write/edit.
 - Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace — avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose→Accept gating is superseded by immediate mutate + soft undo.
-- list_builds returns the same rows as the studio and does not create a build; use catalogListed before telling the operator a pipeline or task appears on Tasks or Pipelines. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.
+- list_builds returns the same rows as the studio and does not create a build; use catalogListed before telling the operator a pipeline or task appears on Tasks or Pipelines. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path (mid-turn, the mutation pin moves with it). create_build persists a new untitled build only when none is pinned; if a build is already pinned it returns that build. edit_pipeline stages wiring must match existing stage bodies — use create_stage / edit_stage to add or remove stages.
 - Build tie (projectRoot + relativePath on a row) is the last saved catalog anchor for that build id — not every path on disk counts for Tasks (e.g. image package roots or paths outside stageflow.yaml scan). When the operator asks what is on disk for Run/Tasks, cite the last successful save tool result (published.project_root_path, published.pipeline_path, published.task_path) or a catalogListed row. Draft-only task changes are not on disk until save returns task_path.
 - Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.
 - Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.
@@ -54,6 +55,7 @@ Bad: a paragraph of pipeline theory, a numbered plan, and three questions at onc
 - Optional skill: belongs on the stage body (create_stage / edit_stage body or stage file) — never on a uses: wrapper.
 - Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.
 - Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.
+- Under sandbox: the stage assignment lists each prior file at /workspace/grants/<stage>/… (that path is the file). Consumer prompts read those paths or payload fields, never stages/<id>/attempts/…/artifacts host paths; /workspace/work is scratch only.
 - Gated sequence: write artifact → ask_operator → emit only after accept; revise on reject in the same attempt.
 - Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.
 
@@ -72,6 +74,10 @@ Bad: a paragraph of pipeline theory, a numbered plan, and three questions at onc
 - artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.
 
 ## Core: artifacts / envelopes
+- Artifact contract: durable writes only via write_stage_artifact; emit artifacts[] ≠ disk until emit disk-truth accepts each listed path under this attempt; empty [] is fine.
+- Facts in payload (required io.output fields). Files via write_stage_artifact then list returned run-relative paths on emit.
+- Sandbox next stage: read the granted file at /workspace/grants/<stage>/… from the assignment, or payload — never stages/.../artifacts host paths; never treat /workspace/work as handoff.
+- Do not inject after-phase verify type: artifact on every create_stage; add only when an explicit basename needs hard proof.
 - Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.
 - One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.
 - Catalog routing ≠ agent fork_choice. Rejected: envelope clone_forks.
@@ -100,6 +106,8 @@ Beyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage;
 - Never emit before HITL accept → verify gate + prompt sequence.
 - Never ambient Host secrets → stage secrets:.
 - Never clonable / clone_forks → sealed Clone Chain.
+- Never cross-stage handoff via stages/.../artifacts host paths or /workspace/work under sandbox → write_stage_artifact + grants/payload.
+- Never blanket after-phase artifact verify on every create_stage.
 
 Review-with-blockers: wire review → address-feedback → approve/ship; put verdict / blocking_findings in review io.output.schema.
 `;

package/dist/operatorAgent/profiles/workshopAuthorTools.d.ts

@@ -26,6 +26,8 @@ export declare function buildCreatePipelineDraft(draft: DraftPackage, args: Reco
     ok: false;
     error: string;
 };
+/** Refuse stages wiring that diverges from draft.stages bodies (no silent prune). */
+export declare function validateEditPipelineStagesWiring(draft: DraftPackage, nextStages: Array<Record<string, unknown>>): string | null;
 export declare function buildEditPipelineDraft(draft: DraftPackage, args: Record<string, unknown>): {
     ok: true;
     nextDraft: DraftPackage;

package/dist/operatorAgent/profiles/workshopAuthorTools.js

@@ -1,8 +1,10 @@
 import path from "node:path";
+import { Type } from "typebox";
 import { peekDefaultModel } from "../../models/catalog.js";
 import { parse as parseYaml } from "yaml";
 import { CatalogPathError, resolveDefaultWriteRoot, } from "../../config/catalogRelativePath.js";
 import { defaultWorkshopPackageDirectory } from "../../config/ensureCatalogScanRoot.js";
+import { canonicalizeNeedTerminalState } from "../../config/pipelineNeeds.js";
 import { publishDraftPackage } from "../../config/publishDraftPackage.js";
 import { globalStageflowHome } from "../../project/globalHome.js";
 import { emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDraft, } from "../draftContext.js";
@@ -34,6 +36,9 @@ export const WORKSHOP_AUTHOR_TOOL_NAMES = [
     "retrieve_docs",
 ];
 export const WORKSHOP_FORBIDDEN_AGENT_TOOLS = ["bash", "write", "edit"];
+const closed = { additionalProperties: false };
+const jsonObject = Type.Record(Type.String(), Type.Unknown());
+const emptyParams = Type.Object({}, closed);
 const REQUIRED_IO = {
     io: {
         input: { schema: { type: "object" } },
@@ -82,6 +87,9 @@ function stringArg(args, key) {
     const value = args[key];
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function isStringList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
 function applyMutation(ctx, summary, nextDraft) {
     const current = readDraftFromContext(ctx.getContext());
     const proposal = {
@@ -174,6 +182,52 @@ async function resolveSaveWriteTarget(ctx, options) {
         await store.close();
     }
 }
+function normalizeRouteOnField(on) {
+    if (Array.isArray(on)) {
+        return on.map((item) => canonicalizeNeedTerminalState(item) ?? item);
+    }
+    const one = canonicalizeNeedTerminalState(on);
+    return one ?? on;
+}
+function normalizeRouteEntries(route) {
+    if (!Array.isArray(route))
+        return route;
+    return route.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return entry;
+        const rec = entry;
+        if (rec.on === undefined)
+            return entry;
+        return { ...rec, on: normalizeRouteOnField(rec.on) };
+    });
+}
+function isInlinePipelineStageBody(stage) {
+    return stage.system_prompt !== undefined || stage.uses === undefined;
+}
+function normalizePipelineStagesRouteOn(stages, options) {
+    const next = stages.map((stage) => {
+        if (!stage || typeof stage !== "object")
+            return stage;
+        let out = { ...stage };
+        if (Array.isArray(out.route)) {
+            out = {
+                ...out,
+                route: normalizeRouteEntries(out.route),
+            };
+        }
+        if (isInlinePipelineStageBody(out) && out.io === undefined) {
+            out = { ...out, ...REQUIRED_IO };
+        }
+        return out;
+    });
+    if (options?.ensureEntry &&
+        next.length > 0 &&
+        !next.some((stage) => stage?.entry === true)) {
+        const first = next[0];
+        next[0] = { ...first, entry: true };
+    }
+    return next;
+}
 export function buildCreateStageDraft(draft, args) {
     const existingIds = new Set(draft.pipeline.stages.map((s) => (typeof s.id === "string" ? s.id : "")));
     let stageId = stringArg(args, "id") ??
@@ -211,7 +265,7 @@ export function buildCreateStageDraft(draft, args) {
         ...(entry ? { entry: true } : {}),
     };
     if (Array.isArray(args.route)) {
-        pipelineEntry.route = args.route;
+        pipelineEntry.route = normalizeRouteEntries(args.route);
     }
     const nextDraft = {
         ...draft,
@@ -244,7 +298,7 @@ export function buildEditStageDraft(draft, args) {
         if (typeof args.entry === "boolean")
             next.entry = args.entry;
         if (Array.isArray(args.route))
-            next.route = args.route;
+            next.route = normalizeRouteEntries(args.route);
         if (stringArg(args, "uses"))
             next.uses = stringArg(args, "uses");
         return next;
@@ -317,7 +371,16 @@ export function buildCreatePipelineDraft(draft, args) {
             ok: true,
             nextDraft: {
                 ...draft,
-                pipeline: { ...pipeline, id: pipeline.id.trim() },
+                pipeline: {
+                    ...pipeline,
+                    id: pipeline.id.trim(),
+                    model: typeof pipeline.model === "string" && pipeline.model.trim()
+                        ? pipeline.model
+                        : stringArg(args, "model") ?? peekDefaultModel(),
+                    stages: normalizePipelineStagesRouteOn(pipeline.stages, {
+                        ensureEntry: true,
+                    }),
+                },
                 ...(Array.isArray(args.stages)
                     ? { stages: args.stages }
                     : {}),
@@ -331,15 +394,51 @@ export function buildCreatePipelineDraft(draft, args) {
             pipeline: {
                 ...draft.pipeline,
                 id,
-                ...(stringArg(args, "model") ? { model: stringArg(args, "model") } : {}),
+                model: stringArg(args, "model") ?? peekDefaultModel(),
                 ...(args.agent !== undefined ? { agent: args.agent } : {}),
                 ...(Array.isArray(args.stages)
-                    ? { stages: args.stages }
+                    ? {
+                        stages: normalizePipelineStagesRouteOn(args.stages, { ensureEntry: true }),
+                    }
                     : {}),
             },
         },
     };
 }
+function normalizeDraftStagePath(stagePath) {
+    return stagePath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function stageWiringMatchesArtifact(stage, artifact) {
+    const id = typeof stage.id === "string" ? stage.id : "";
+    const uses = typeof stage.uses === "string" ? stage.uses : "";
+    const bodyId = typeof artifact.body.id === "string" ? artifact.body.id : "";
+    return ((uses.length > 0 &&
+        normalizeDraftStagePath(artifact.path) ===
+            normalizeDraftStagePath(uses)) ||
+        (id.length > 0 && bodyId === id));
+}
+/** Refuse stages wiring that diverges from draft.stages bodies (no silent prune). */
+export function validateEditPipelineStagesWiring(draft, nextStages) {
+    const artifacts = draft.stages ?? [];
+    for (const stage of nextStages) {
+        const matched = artifacts.some((artifact) => stageWiringMatchesArtifact(stage, artifact));
+        if (!matched) {
+            const label = (typeof stage.id === "string" && stage.id) ||
+                (typeof stage.uses === "string" && stage.uses) ||
+                "(unnamed)";
+            return `edit_pipeline stages wiring references "${label}" without a matching stage body — use create_stage / edit_stage to add or change stage files`;
+        }
+    }
+    for (const artifact of artifacts) {
+        const stillWired = nextStages.some((stage) => stageWiringMatchesArtifact(stage, artifact));
+        if (!stillWired) {
+            const label = (typeof artifact.body.id === "string" && artifact.body.id) ||
+                artifact.path;
+            return `edit_pipeline stages wiring drops stage body "${label}" — use create_stage / edit_stage to change stage files; wiring-only remove is refused`;
+        }
+    }
+    return null;
+}
 export function buildEditPipelineDraft(draft, args) {
     const patch = isPlainObject(args.patch) ? args.patch : args;
     const nextPipeline = {
@@ -352,12 +451,30 @@ export function buildEditPipelineDraft(draft, args) {
     if (patch.agent !== undefined)
         nextPipeline.agent = patch.agent;
     if (Array.isArray(patch.stages)) {
-        nextPipeline.stages = patch.stages;
+        const nextStages = normalizePipelineStagesRouteOn(patch.stages);
+        const wiringError = validateEditPipelineStagesWiring(draft, nextStages);
+        if (wiringError)
+            return { ok: false, error: wiringError };
+        nextPipeline.stages = nextStages;
     }
     if (patch.schemas !== undefined)
         nextPipeline.schemas = patch.schemas;
     if (patch.requires !== undefined)
         nextPipeline.requires = patch.requires;
+    if (isStringList(patch.memories)) {
+        if (patch.memories.length === 0)
+            delete nextPipeline.memories;
+        else
+            nextPipeline.memories = patch.memories;
+    }
+    if (patch.channels !== undefined) {
+        if (Array.isArray(patch.channels) && patch.channels.length === 0) {
+            delete nextPipeline.channels;
+        }
+        else {
+            nextPipeline.channels = patch.channels;
+        }
+    }
     return {
         ok: true,
         nextDraft: { ...draft, pipeline: nextPipeline },
@@ -428,6 +545,7 @@ export function createWorkshopBuildTools() {
     const listBuildsTool = {
         name: "list_builds",
         description: "List the same workshop rows as the studio picker (open builds and unbound disk pipelines). Each row includes catalogListed (whether Tasks/Pipelines would list that pipeline path). Does not create a build. Works when no build is focused.",
+        parameters: emptyParams,
         async handler(_args, ctx) {
             const live = liveWorkshopBinding(ctx);
             if (!live) {
@@ -458,7 +576,14 @@ export function createWorkshopBuildTools() {
     };
     const focusBuildTool = {
         name: "focus_build",
-        description: "Move this chat onto a build by id, or onto an unbound disk pipeline by projectRoot and relativePath. A failed open returns the error, creates nothing, and leaves the pointer unchanged.",
+        description: "Move this chat onto a build by id, or onto an unbound disk pipeline by projectRoot and relativePath. Mid-turn, the mutation pin moves with the focus so studio and draft tools stay on the same build. A failed open returns the error, creates nothing, and leaves the pointer unchanged.",
+        parameters: Type.Union([
+            Type.Object({ id: Type.String({ minLength: 1 }) }, closed),
+            Type.Object({
+                projectRoot: Type.String({ minLength: 1 }),
+                relativePath: Type.String({ minLength: 1 }),
+            }, closed),
+        ]),
         async handler(args, ctx) {
             const live = liveWorkshopBinding(ctx);
             if (!live) {
@@ -530,7 +655,8 @@ export function createWorkshopBuildTools() {
     };
     const createBuildTool = {
         name: "create_build",
-        description: "Persist a new untitled build and focus it, including when another build is already focused. No build id argument.",
+        description: "Persist a new untitled build and focus it when none is pinned. When a build is already pinned, returns that build without creating another. No build id argument.",
+        parameters: emptyParams,
         async handler(_args, ctx) {
             const live = liveWorkshopBinding(ctx);
             if (!live) {
@@ -551,6 +677,13 @@ export function createWorkshopAuthorMutatingTools() {
     const createPipelineTool = {
         name: "create_pipeline",
         description: "Create or replace the draft pipeline (id, optional model/stages). Mutates the in-memory draft immediately.",
+        parameters: Type.Object({
+            id: Type.String({ minLength: 1 }),
+            model: Type.Optional(Type.String()),
+            agent: Type.Optional(Type.Unknown()),
+            stages: Type.Optional(Type.Array(jsonObject)),
+            pipeline: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildCreatePipelineDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -561,7 +694,18 @@ export function createWorkshopAuthorMutatingTools() {
     };
     const editPipelineTool = {
         name: "edit_pipeline",
-        description: "Edit pipeline fields on the current draft (id, model, stages wiring, etc.). Mutates immediately.",
+        description: "Edit pipeline fields on the current draft (id, model, stages wiring, etc.). Stages wiring must match existing stage bodies — use create_stage / edit_stage to add or remove stages. Mutates immediately.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String()),
+            model: Type.Optional(Type.String()),
+            agent: Type.Optional(Type.Unknown()),
+            stages: Type.Optional(Type.Array(jsonObject)),
+            schemas: Type.Optional(Type.Unknown()),
+            requires: Type.Optional(Type.Unknown()),
+            memories: Type.Optional(Type.Array(Type.String())),
+            channels: Type.Optional(Type.Unknown()),
+            patch: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildEditPipelineDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -573,6 +717,18 @@ export function createWorkshopAuthorMutatingTools() {
     const createStageTool = {
         name: "create_stage",
         description: "Add a file-backed stage to the draft (uses: ./id.yaml + stage body with io). Mutates immediately; Accept confirms, Reject soft-undos.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String()),
+            summary: Type.Optional(Type.String()),
+            label: Type.Optional(Type.String()),
+            uses: Type.Optional(Type.String()),
+            body: Type.Optional(jsonObject),
+            system_prompt: Type.Optional(Type.String()),
+            model: Type.Optional(Type.String()),
+            io: Type.Optional(jsonObject),
+            entry: Type.Optional(Type.Boolean()),
+            route: Type.Optional(Type.Array(Type.Unknown())),
+        }, closed),
         handler(args, ctx) {
             const built = buildCreateStageDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -584,6 +740,18 @@ export function createWorkshopAuthorMutatingTools() {
     const editStageTool = {
         name: "edit_stage",
         description: "Edit an existing draft stage by id (body fields and/or pipeline entry route/entry/uses). Mutates immediately.",
+        parameters: Type.Object({
+            id: Type.String({ minLength: 1 }),
+            patch: Type.Optional(jsonObject),
+            body: Type.Optional(jsonObject),
+            pipeline_entry: Type.Optional(jsonObject),
+            entry: Type.Optional(Type.Boolean()),
+            route: Type.Optional(Type.Array(Type.Unknown())),
+            uses: Type.Optional(Type.String()),
+            system_prompt: Type.Optional(Type.String()),
+            model: Type.Optional(Type.String()),
+            io: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildEditStageDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -595,6 +763,13 @@ export function createWorkshopAuthorMutatingTools() {
     const createTaskTool = {
         name: "create_task",
         description: "Create or replace the optional task (id + goal) on the draft. Mutates immediately.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String()),
+            goal: Type.Optional(Type.String()),
+            summary: Type.Optional(Type.String()),
+            filename: Type.Optional(Type.String()),
+            body: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildCreateTaskDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -606,6 +781,13 @@ export function createWorkshopAuthorMutatingTools() {
     const editTaskTool = {
         name: "edit_task",
         description: "Edit the draft task fields (id, goal, body). Mutates immediately.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String()),
+            goal: Type.Optional(Type.String()),
+            filename: Type.Optional(Type.String()),
+            patch: Type.Optional(jsonObject),
+            body: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildEditTaskDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -627,6 +809,12 @@ export function createSaveTool(options = {}) {
     return {
         name: "save",
         description: "Validate-then-write the draft via catalog facades (createDraftPackage / overwriteDraftPackage). When directory is omitted, writes under workshop/<pipeline-id> on registered catalogs (or <pipeline-id> on the workspace catalog). The host adds registered workshop paths to stageflow.yaml so Run can see them. Pass directory only when the operator names a folder. Soft undo does not reverse disk. Prefer mode auto; set allowInvalid only when the operator explicitly requests saving invalid YAML. Do not pass projectRoot — the host binds it.",
+        parameters: Type.Object({
+            directory: Type.Optional(Type.String()),
+            pipelineFilename: Type.Optional(Type.String()),
+            mode: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("create"), Type.Literal("overwrite")])),
+            allowInvalid: Type.Optional(Type.Boolean()),
+        }, closed),
         async handler(args, ctx) {
             const writeTarget = await resolveSaveWriteTarget(ctx, options);
             if (!writeTarget.ok) {

package/dist/operatorAgent/types.d.ts

@@ -1,3 +1,4 @@
+import type { TSchema } from "typebox";
 import type { DraftPackage } from "../config/draftPackage.js";
 import type { ValidationResult } from "../config/validateCatalog.js";
 import type { AcceptProposalResult, ProposalArtifactDiff, UndoMutationResult } from "./proposals.js";
@@ -10,6 +11,7 @@ export type OperatorAgentToolHandler = (args: Record<string, unknown>, ctx: Oper
 export type OperatorAgentTool = {
     name: string;
     description: string;
+    parameters: TSchema;
     handler: OperatorAgentToolHandler;
 };
 export type OperatorAgentToolContext = {
@@ -17,6 +19,14 @@ export type OperatorAgentToolContext = {
     setContext(next: unknown): void;
     /** Apply mutation immediately and record an undo receipt. */
     emitProposal(proposal: OperatorAgentProposal): void;
+    /**
+     * Set only on an eval session. Returning a result skips the tool handler.
+     * Returning null lets the handler run. Absent on Workshop, author and Guide sessions.
+     */
+    evalGate?: {
+        decide(name: string, args: Record<string, unknown>): OperatorAgentToolResult | null;
+        observe(name: string, result: OperatorAgentToolResult): void;
+    };
 };
 export type OperatorAgentProposal = {
     /** Mutation id (Accept confirms; Reject / undoMutation soft-undos). */
@@ -72,6 +82,10 @@ export type WorkshopToolActivityUpdate = {
     draft?: DraftPackage;
     /** Build the turn is editing. Absent when the chat is unlinked. */
     buildId?: string;
+    /** Tool arguments, on `running`. */
+    args?: Record<string, unknown>;
+    /** Tool result `content`, on `complete`. */
+    result?: unknown;
 };
 export type OperatorAgentSession = {
     readonly profileId: string;
@@ -111,6 +125,15 @@ export type OperatorAgentHost = {
         profileId: string;
         context: unknown;
     }): OperatorAgentSession;
+    /**
+     * A session whose tools pass through `gate` before they run. The gate is required:
+     * an eval session with no gate is refused.
+     */
+    openEvalSession(input: {
+        profileId: string;
+        context: unknown;
+        gate: NonNullable<OperatorAgentToolContext["evalGate"]>;
+    }): OperatorAgentSession;
 };
 export type WorkshopDraftContext = {
     draft: DraftPackage;

package/dist/package-meta.d.ts

@@ -1,3 +1,3 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.42.0";
+export declare const PACKAGE_VERSION = "0.44.0";
 export declare const BUILD_SHA: string;

package/dist/package-meta.js

@@ -1,3 +1,3 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.42.0";
+export const PACKAGE_VERSION = "0.44.0";
 export const BUILD_SHA = process.env.STAGEFLOW_BUILD_SHA ?? "unknown";

package/dist/runstore/retention.d.ts

@@ -1,4 +1,5 @@
 import type { RunMeta, RunStatus } from "./port.js";
+import { type RunClockTerminalStatus } from "./runStatusClock.js";
 export type RetentionDecision = "none" | "slim" | "purge";
 export type StatusRetentionWindow = {
     slimMs: number;
@@ -24,4 +25,4 @@ export declare function slimArtifactMaxBytesFromEnv(env?: NodeJS.ProcessEnv): nu
  * Already-slimmed rows past SLIM but not PURGE return `"none"` (R18).
  */
 export declare function retentionDecision(row: RetentionRow, now: Date, windows?: RetentionWindows): RetentionDecision;
-export declare function isTerminalRunStatus(status: RunStatus | undefined): status is "succeeded" | "failed" | "cancelled";
+export declare function isTerminalRunStatus(status: RunStatus | undefined): status is RunClockTerminalStatus;

package/dist/runstore/retention.js

@@ -1,3 +1,4 @@
+import { isRunClockTerminal, } from "./runStatusClock.js";
 export const DAY_MS = 24 * 60 * 60 * 1000;
 /** Defaults: succeeded 3d/30d; failed and cancelled 30d/90d (R30 / AE6). */
 export const DEFAULT_RETENTION_WINDOWS = {
@@ -7,11 +8,6 @@ export const DEFAULT_RETENTION_WINDOWS = {
 };
 export const DEFAULT_BARE_CACHE_TTL_MS = 30 * DAY_MS;
 export const DEFAULT_SLIM_ARTIFACT_MAX_BYTES = 1024 * 1024;
-const TERMINAL = new Set([
-    "succeeded",
-    "failed",
-    "cancelled",
-]);
 function parsePositiveMs(raw) {
     if (raw === undefined)
         return undefined;
@@ -52,7 +48,7 @@ export function slimArtifactMaxBytesFromEnv(env = process.env) {
  */
 export function retentionDecision(row, now, windows = DEFAULT_RETENTION_WINDOWS) {
     const status = row.status;
-    if (status === undefined || !TERMINAL.has(status))
+    if (!isRunClockTerminal(status))
         return "none";
     if (row.finished_at === undefined || row.finished_at === "")
         return "none";
@@ -70,5 +66,5 @@ export function retentionDecision(row, now, windows = DEFAULT_RETENTION_WINDOWS)
     return "none";
 }
 export function isTerminalRunStatus(status) {
-    return status !== undefined && TERMINAL.has(status);
+    return isRunClockTerminal(status);
 }

package/dist/runstore/runStatusClock.d.ts

@@ -0,0 +1,17 @@
+export declare const RUN_CLOCK_TERMINAL_STATUSES: readonly ["succeeded", "failed", "cancelled"];
+export type RunClockTerminalStatus = (typeof RUN_CLOCK_TERMINAL_STATUSES)[number];
+export type RunClockStatus = "created" | "queued" | "running" | RunClockTerminalStatus;
+export declare function isRunClockTerminal(status: string | undefined): status is RunClockTerminalStatus;
+export type FinishedAtDecision = {
+    action: "stamp";
+    finishedAt: string;
+} | {
+    action: "keep";
+} | {
+    action: "clear";
+};
+export declare function nextFinishedAt(input: {
+    nextStatus: RunClockStatus;
+    currentFinishedAt: string | null | undefined;
+    now: string;
+}): FinishedAtDecision;