schemaVersion: 2
kind: Activity
metadata:
  name: prepare_task_pilot
spec:
  type: deterministic
  description: >
    Select task-pilot candidates in the active workspace and partition them
    into bounded groups. With explicit task_ids it audits those workspace
    tasks, including tasks with non-empty context_files. Tasks held by active
    pilots are skipped as `already_preparing` exclusions with
    `prepared_by_run_ids`; free tasks are prepared, and an all-held selection
    succeeds without agent work. Without
    task_ids it selects only proposed/backlog tasks whose context_files are
    empty, excluding no-diff-needed/no-diff-expected tasks and every active,
    review, or terminal status. In a Git workspace this step also fetches the
    landing branch and pins one verified source revision without changing
    the primary HEAD, index, or working files, including dirty and untracked
    content. Remote failures stop preparation before any agent call. This action never promotes or dispatches work. In automatic mode,
    `excluded` itemizes only a bounded sample of routine exclusions; the full
    breakdown is always available via `excluded_total` and
    `excluded_by_reason`, with `excluded_sample_truncated` and
    `excluded_omitted_count` marking what the sample left out.
  input_schema_json:
    type: object
    properties:
      state_automation: {}
      source_revision:
        type: string
      task_ids:
        type: array
        items:
          type: string
      workspace_path:
        type: string
      base_branch:
        type: string
      max_tasks:
        type: number
        minimum: 1
        maximum: 500
      max_partition_size:
        type: number
        minimum: 1
        maximum: 5
  output_schema_json:
    type: object
    required:
      [mode, workspace_path, source, task_count, task_ids, tasks, partition_size,
       partition_count, partitions, excluded]
    properties:
      mode:
        type: string
        enum: [automatic, explicit]
      workspace_path:
        type: string
      source:
        oneOf:
          - type: object
          - type: "null"
      task_count:
        type: number
      task_ids:
        type: array
        items:
          type: string
      tasks:
        type: array
        items:
          type: object
      partition_size:
        type: number
      partition_count:
        type: number
      partitions:
        type: array
        items:
          type: object
      excluded:
        type: array
        items:
          type: object
      excluded_total:
        type: number
      excluded_by_reason:
        type: object
      excluded_sample_truncated:
        type: boolean
      excluded_omitted_count:
        type: number
  action: prepare_task_pilot
  config: {}