Skip to content

Runner core: spec, store, engine, shell stages, scheduler, CLI, status #3

Closed

Description

@jerryfane

Parent: #2

Part of the epic (see the parent issue). Owner: gitmoot-pipe.

Change

  • Repo scaffold
    • Go module github.com/gitmoot/stagehand, cmd/stagehand, internal/....
    • CI: go build, go vet, go test -race, CGO_ENABLED=0 build.
    • README.
  • internal/spec
    • YAML Load with unknown keys rejected, plus Validate and Hash.
    • Keys: name, description, schedule.{interval,jitter}, env_file, env, stages[].
    • Stage keys: id, needs, cmd, cwd, timeout, retry, env_keys.
    • Agent keys (validated here, executed in a later step): agent, model, effort, prompt/prompt_file, inputs, output, tools, max_cost.
    • Validation: DAG with no cycles, unique ids, needs refer to stages that exist, exactly one executor per stage, safe file names.
    • Semantics follow gitmoot internal/pipeline/spec.go / validate.go at 1b124f60.
  • internal/store
    • SQLite (modernc.org/sqlite) with migrations.
    • Tables: pipelines, runs (spec snapshot), run_stages, stage_attempts.
  • internal/engine
    • Advance: start the ready stages, record results, retry, park, settle.
    • resume --from, cancel, one active run per pipeline.
    • Interval and jitter scheduling, with missed intervals collapsing into one run.
    • Restart recovery: stages still running become interrupted and park the run.
    • An Executor interface, so agent executors can be added later.
  • Shell executor
    • sh -c in cwd, with an exact environment (env_keys plus STAGEHAND_*) and its own process group.
    • Timeout and cancel kill the group.
    • Log file per attempt.
    • Exit code decides the result. An optional $STAGEHAND_RESULT JSON can return blocked.
  • CLI: add, list, show, runs, run [--wait], resume, cancel, enable, disable, remove, status --json, serve (optional loopback GET /status), tick.
    • An exclusive lock on the home directory makes sure one process executes stages.

Acceptance

  • A real 3-stage shell pipeline runs end to end under serve from a temp home.
  • Records show exit codes and log paths.
  • A failing stage parks the run, and resume --from finishes it.
  • Killing serve mid-stage, then restarting it, parks the run as interrupted.
  • status --json shows the last run and next_due_at.
  • Tests cover: DAG validation, the park/resume/skip transitions, retry, recovery, and the exact environment (no inherited variables).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions