`59d7d7a`

docs: record actions timeout behavior

Authored by mfwolffe <wolffemf@dukes.jmu.edu> yesterday

Status	File	+	-
M	`docs/internal/actions-runner-api.md`	7	0
M	`docs/internal/actions-schema.md`	18	0
M	`docs/internal/runbooks/actions-runner.md`	22	1

docs/internal/actions-runner-api.mdmodified

  `workflow_jobs`, rolls up `workflow_runs`, and best-effort updates the
  matching `check_runs` row created by the trigger pipeline.
 +`timeout-minutes` is enforced by `shithubd-runner` as a whole-job
 +deadline. When it expires, the runner kills the active container,
 +reports the current step as `completed/timed_out`, and reports the job
 +as `completed/timed_out`. The server treats that conclusion as terminal
 +failure for the workflow run rollup.
++
  When a runner reports `status:"cancelled"`, any still-open steps in the
  job are marked cancelled too. This keeps a killed job from leaving queued
  step rows that the UI would otherwise treat as live.
  - `shithub_actions_jobs_cancelled_total{reason="user|concurrency|timeout"}`
  - `shithub_actions_log_scrub_replacements_total{location="server"}`
  - `shithub_actions_runs_pruned_total{kind="chunks|blobs|runs|jwt_used"}`
 +- `shithub_actions_step_timeouts_total`

docs/internal/actions-schema.mdmodified

    `shithubd-cron.service`. Operators can run it manually with
    `shithubd admin run-job workflow:cleanup`.
 +## Runner timeouts (S41g)
++
 +`jobs.<key>.timeout-minutes` is enforced by `shithubd-runner` as a
 +whole-job deadline. The parser stores the value in
 +`workflow_jobs.timeout_minutes` with the GitHub-compatible default of
 +360 minutes and a 1..4320 cap.
++
 +When the deadline expires, the Docker engine explicitly kills the
 +active step container, emits a terminal step update with
 +`status=completed` and `conclusion=timed_out`, and the runner reports
 +the job itself as `completed/timed_out`. The server rolls the parent
 +workflow run up to `timed_out` when all jobs are terminal. A timed-out
 +step is not masked by `continue-on-error`; the job deadline always wins.
++
 +The runner API increments `shithub_actions_step_timeouts_total` the
 +first time a step reaches `conclusion=timed_out`. Duplicate terminal
 +step-status retries do not increment the counter again.
++
  ## Retention cleanup (S41g)
  `workflow:cleanup` applies the durable Actions retention contract in

docs/internal/runbooks/actions-runner.mdmodified

  `parent_run_id` equal to the source run. Confirm the new row has the
  same `head_sha` as the source run.
 +Timeout smoke: create a workflow with a short deadline and a long-running
 +step:
++
 +```yaml
 +jobs:
 +  timeout_probe:
 +    runs-on: ubuntu-latest
 +    timeout-minutes: 1
 +    steps:
 +      - run: sleep 600
 +```
++
 +Expected results:
++
 +- The runner kills the active container shortly after the one-minute
 +  deadline.
 +- The step row becomes `status=completed`,
 +  `conclusion=timed_out`.
 +- The job row becomes `status=completed`, `conclusion=timed_out`.
 +- `/metrics` increments `shithub_actions_step_timeouts_total`.
++
  Replay check: reusing the log token after the log call must fail with
 because its `jti` is already present in `runner_jwt_used`.
    jobs are terminal.
  - The PR Checks tab shows the matching check run as success.
  - `/metrics` includes runner registration, heartbeat, JWT, job
 -  cancellation, log-scrub, and retention counters.
 +  cancellation, log-scrub, step-timeout, and retention counters.
  ## Retention Sweep