syncyard
/syncyard
Zleca i obserwuje zadania na maszynach operatora przez bramkę Syncyard, z pasami wykonawczymi i dzielonym budżetem API.
- Autor
- electrohire ↗
- Repozytorium
- syncyard ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 12.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 1
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
Co robi i kiedy
Zleca i obserwuje zadania na maszynach operatora przez bramkę Syncyard, z pasami wykonawczymi i dzielonym budżetem API.
Oryginalny opis (EN)
Dispatch and watch jobs on the operator's own machines through the Syncyard gatekeeper (self-hosted GitHub Actions runner lanes, shared API budget). Use for any work that must run on the operator's machines.
Jak działa
- The security invariant
- Commands
- Periodic status-check duty
- Lane routing
- Marker verdicts
- API discipline
- Watermarks and escalation etiquette
- Windowless supervision
- Board (hardware) scenario jobs
- Failsafe backchannel
Podgląd SKILL.md
---
name: syncyard
description: Dispatch and watch jobs on the operator's own machines through the Syncyard gatekeeper (self-hosted GitHub Actions runner lanes, shared API budget). Use for any work that must run on the operator's machines.
version: 0.4.0
---
<!-- Generated from skills/_source/contract.md by skills/build_skills.py - do not edit this file directly. -->
**Edition: generic-agent** (Syncyard 0.4.0). Generic-agent edition: plain Markdown with minimal YAML front matter, for any agent host that loads skill or instruction files. If your host loads neither, keep this file in the working context for any task that touches the operator's machines.
# Syncyard — agent skill
Syncyard is the one door between agents and the operator's own machines.
Programs do not dispatch GitHub Actions workflows directly, and they
never poll runs on their own. They submit job requests to the
**gatekeeper** (`gatekeeper/gk.py`, also reachable as `gh syncyard …`
when the gh extension is installed, or as the `syncyard` command
when the standalone package is installed — `pipx install syncyard`),
which dispatches within the
shared API budget, assigns lanes, watches every run in one batched
sweep, and records verdicts. If you are an agent with work for the
operator's machines, work through the gatekeeper.
This skill tracks Syncyard version 0.4.0.
## The security invariant
Runners are reachable only via `workflow_dispatch` from the gatekeeper; no workflow may bind self-hosted labels to `pull_request`, `pull_request_target`, or issue events; the door repository is private; the backchannel repository is private.
Everything below is shaped by that invariant. Never propose, write,
or merge a workflow that weakens it. CI runs on GitHub-hosted
runners only. Never commit a token or credential anywhere.
Registration tokens are fetched at setup time and used once.
Runners register to the door repository only, never
organization-wide.
## Commands
```bash
GK="python3 gatekeeper/gk.py" # or: gh syncyard # or: syncyard (standalone)
# Submit a Windows PowerShell job
$GK submit --program <your-program> --workflow run.yml \
--lane <quick|normal|long|gpu> --script <script.ps1> \
--cwd '<windows cwd>' [--expected-min N] --key <unique-key>
# Submit a WSL2 / Linux / macOS bash job
$GK submit --program <your-program> --workflow wsl.yml \
--lane <lane> --script <script.sh> --cwd '<cwd>' \
[--expected-min N] --key <unique-key>
# Return one file from the machine as an artifact (no script; path only)
$GK submit --program <your-program> --workflow grab.yml \
--lane quick --grab-path '<path on the machine>' --key <unique-key>
# Register a run dispatched outside the gatekeeper (watch only)
$GK adopt --run-id <id> --program <your-program> --workflow <wf> \
--lane <lane> --key <unique-key>
# The board: every tracked job, its state, flags, and verdict
# markers, plus queued/running counts and an ISSUES section
$GK status
# Hold ALL program dispatch (the watch pass keeps running;
# already-dispatched jobs are untouched — the gatekeeper
# never cancels). Maintenance jobs (--maintenance) still dispatch.
$GK pause --reason "operator working on the machines"
$GK resume
# Focus: dispatch only the selected jobs — repeatable
# selectors (key or key-prefix, program, notify endpoint).
# `gk resume` clears pause and focus together. Add --drain to
# pause or focus to let executing work finish before the
# pipeline settles.
$GK focus --except-program <program> [--except-key <key-or-prefix>]
$GK pause --drain
# Priorities: set at submit or live while waiting;
# unset priorities are auto-optimized (see below) and any
# explicit value pins the job against the optimizer.
$GK submit ... [--priority N]
$GK priority <job-id-or-key> <N>
# Checkpoint hold: signal one job to stop itself at
# its next checkpoint; release with resume --job. Continuation
# is a fresh submission by the job's owner.
$GK hold <job-id-or-key>
$GK resume --job <job-id-or-key>
# Lane priority lock: hold a lane for your program
# so no other program's jobs dispatch on it — priority never
# trumps a lock. Non-holder jobs wait (not refused, not
# reordered); re-running lock renews the TTL; --suspend keeps
# the claim but lets the lane flow; every lock expires on its
# TTL exactly like a release. Maintenance jobs bypass locks.
$GK lock --lane <lane> --program <your-program> [--ttl-min N]
$GK lock --lane <lane> --program <your-program> --suspend|--resume
$GK unlock --lane <lane> --program <your-program>
$GK lock --list
# Lane profiles + auto routing: lanes live in named
# config profiles (fleet-default = today's four lanes); render
# them with profile. Submit with --lane auto to let the sweep
# pick the lane from your resource hints, your program's
# recorded history, queue load, and the host capability
# snapshot — the decision and its inputs land on the job
# record. A hard hint no lane can meet waits with the reason
# recorded; it is never silently downgraded.
$GK profile --list
$GK profile --show [name]
$GK submit ... --lane auto [--needs-cpu N] [--needs-ram-mb N] [--needs-gpu [VRAM_MB]] [--needs-storage-mb N] [--venue auto|native|wsl|docker]
$GK probe-host --host <host> [--ingest <report-file>]
# The hard halt: sweeps no-op entirely until started again.
$GK stop --reason "fleet maintenance"
$GK start
# Push notifications instead of polling: register once with
# --notify-chat <endpoint> on submit/adopt; the coordinator
# delivers start / completion / escalation pushes from the outbox.
$GK outbox
```
- Every job carries a **unique `--key`**. Submitting a key that is
already active is refused and prints the existing job — that
refusal is the duplicate-dispatch pre-check working. Never work
around it by changing the key for the same work; check
`gk status` instead.
- `--expected-min` matters for `long` and `gpu` jobs: health
watermarks are judged against the declared expectation before
lane defaults.
- `gk cancel <id-or-key>` is local bookkeeping for jobs that were
never dispatched. It never cancels a GitHub run. No command in
this system cancels a running job — see escalation below.
- The status board's **ISSUES** section is the operator's problem
list: watermark breaches and escalations, failed or pending log
harvests, a dispatch stuck needing a human, and completions with
no marker verdict. Read it before concluding the fleet is healthy.
- Every gatekeeper state write is write-verify-retry: a record's file is only ever replaced by renaming
a fully verified temp file over it, so a failed save can never
destroy the standing record. Never treat a 0-byte state file as
real, and never trust an unverified write.
- **Priorities.** Within the waiting set, higher
effective priority dispatches first. A priority you set
(`--priority`, `gk priority`) is human-set and pinned: the
optimizer never changes it, it wins ties against auto values,
and a value above 100 outranks every auto job permanently.
Jobs with no explicit priority are auto-optimized by the sweep:
shorter declared expectations first, a small bonus for fitting
the lane, and +1 per 10 minutes waited (capped at 100), so
nothing starves. `gk status` shows the waiting set in
effective order with each job's priority and source. Admission
(pause/focus/drain/host holds) outranks priority absolutely.
- **Checkpoint holds are cooperative.** The
gatekeeper cannot stop a running script from outside; it can
only signal. The signal file may be created by any actor that
can write the venue path — including a host-local process
acting without any gatekeeper round-trip (the host
guard raises it directly when a shutdown is imminent) — and
the harvest is identical whichever side raised it. A job
that wants to be holdable polls the path
in `$SYNCYARD_HOLD_FILE` between steps (PowerShell:
`Test-Path $env:SYNCYARD_HOLD_FILE`; bash: `[ -e "$SYNCYARD_HOLD_FILE" ]`).
When the file exists, the job prints the marker
`CHECKPOINT_PAUSED` and exits with code 86; the sweep records
the job `held_at_checkpoint` — not a failure, whatever the
run's conclusion says — and the outbox reports
HELD_AT_CHECKPOINT. A fully-held job's key frees up: the
owner continues the work with a fresh submission (the old
job's checkpoints are the resume state), after the operator
clears the signal with `gk resume --job <id>`.
- **Host drains and the shutdown guard.**
`gk drain --host <host>` is the polite prelude to restarting
or shutting down one host: it signals the host's running
checkpoint-capable jobs, sets the host's drain hold, waits
out the checkpoint window, and prints a per-job verdict
(exit 0 = CLEAN, 1 = INTERRUPTING with the uncheckpointed
jobs named). It is host-scoped and active — distinct from
`gk pause --drain`, which is global and passive — and
neither clears the other's state; `gk host-resume <host>`
clears that host's holds (drain and going-down alike). On a
guarded host the guard does the same drain automatically
when a shutdown, restart, or logoff is imminent: it blocks
the session end with a reason string, writes the going-down
record first, raises the running jobs' hold files locally
(no gatekeeper round-trip), and releases the block and
re-issues the pending action when every job has settled or
the window expires — delay, never prevent. The guard's
heartbeat rides the host liveness record; a stale guard
beat in `gk status` means the protection is down — report
it, never work around it.
- **Lane priority locks.** One program can hold a
lane (`gk lock --lane … --program …`): while the lock is
ACTIVE, only the holder's jobs dispatch on that lane, and no
priority — human or optimizer — admits anyone else; waiting
jobs are never refused or reordered, they simply wait.
Release what you take with `gk unlock`; renew by re-running
`gk lock` (the TTL extends, a suspended lock stays
suspended); `--suspend` / `--resume` pause and restore
enforcement without surrendering the claim — a suspended
lock still refuses new acquires by others. Every lock
expires on its TTL (config `lock.default_ttl_min`, default
240; `lock.max_ttl_min`, default 1440) exactly like a
release, with an outbox notice to the holder's chat, as on
an operator-override release or an override suspend/resume
— your own actions are never self-notified. Fleet pause
and focus never mutate lock state, and admission is a
conjunction: focus admission AND, on a locked lane, being
the holder. `gk status` renders a LOCKS section in all
modes and marks lock-held waiting jobs.
- **Profiles and auto routing.** Lanes are defined
by the active config profile; profiles may define lanes
from scratch (resource class cpu|gpu|any, duration band,
optional workflow pin), and switching profiles is an
operator config edit, never a runtime verb. `--lane auto`
is opt-in placement: the sweep resolves the lane once, from
declared hints, your program's median actuals, load, locks,
holds, and the probed capability of the hosts — a locked
lane is a candidate only for its holder, and focus binds
auto jobs as it binds explicit ones. The scorer is
deterministic and its full input snapshot is recorded on
the job (`auto_routed` in the ledger), so a placement can
always be re-derived. Estimates are advisory forever: an
overrunning job is never killed, cancelled, or moved — its
actuals feed the next estimate. Capability snapshots come
from `gk probe-host` (probe scripts ship in
`gatekeeper/probes/` for Windows, Linux, macOS); a stale
snapshot (older than `lanes.capability_max_age_min`,
default 60 minutes) degrades routing to bands and load,
ledgered, and unknown fields count as neutral, never zero.
## Periodic status-check duty
**Every agent that uses Syncyard checks Syncyard status before
submitting work for the machines, and at least once per hour during
an active campaign on them.** Use `gk status` when the gatekeeper
is reachable; otherwise use the failsafe backchannel's read-only
status (`backchannel/bc.py heartbeat` / `bc.py status`). A stale
backchannel heartbeat (older than 5 minutes), a down supervisor
tray, or a down runner is **reported to the operator's Syncyard
coordination point** — never worked around, never routed around
silently, and never a reason to improvise an alternate route to
the machines.
## Lane routing
Every dispatch declares a lane. **No lane declared = not dispatched.**
| Lane | Expected duration | Use for |
|---|---|---|
| `quick` | under ~2 min | probes, status checks, small transfers |
| `normal` | ~2–30 min | builds, installs, packaging |
| `long` | over ~30 min, or unknown | batch stages, scoring runs, renders |
| `gpu` | any duration | any job that needs a GPU |
- **GPU overrides duration.** A 30-second GPU probe goes to `gpu`,
never to `quick`. A long GPU render goes to `gpu`, never to `long`.
- **Unknown duration goes to `long`.**
- A job that overruns its lane's norm twice gets re-laned in its
program's briefs (quick → normal, normal → long), and the overrun
is reported.
- Detached background processes on a machine are not Actions jobs
and do not take a lane; the status checks *about* them are
`quick` jobs.
- Jobs expected to exceed 60 minutes are announced to the
coordination point before dispatch, with their expected duration.
- GitHub's job execution limit is exactly 360 minutes; longer work
is designed as chunked/resume-safe stages or a detached,
checkpointed process the gatekeeper probes — never one long run.
## Marker verdicts
**A job's verdict comes from the marker lines it prints in its own
log — never from the GitHub Actions success color alone.** Platform
run status has been observed frozen at "queued" long after a job's
log held its complete result; the log is the record.
- Write every job script to print unambiguous marker lines with its
results, for example `PROBE_DONE gpus=2 free_gb=212` or
`BUILD_VERDICT: PASS`. Markers are lines that begin with an
`ALL_CAPS_` token; the gatekeeper harvests exactly those.
- Read verdicts from `gk status` or from the job record the
gatekeeper keeps, not from the Actions web UI.
- A run that "failed" according to a client printout but whose
markers say otherwise gets cross-checked against the actual job
log before anyone believes either.
## API discipline
The GitHub REST quota (5,000 calls/hour) is one account-wide bucket
shared by every program. The gatekeeper exists so the fleet spends
it once, centrally. Your obligations:
- **Never poll a run yourself.** The gatekeeper's sweep (every
5 minutes) is the only watcher. If you truly must look, one
batched `gh run list` covering all your runs, no faster than
every 3–5 minutes — never a per-run loop, never `gh run watch`
left running (its default interval is ~3 seconds).
- **Before any burst of API calls** (more than ~10), run
`gh api rate_limit` — the endpoint is free. Core remaining
**below 1,000**: stand down to minimum cadence and say so in
your report. **Below 500**: completion-critical calls only, at
most one per 5 minutes.
- **A 403 rate-limit response is a hard stop** for that scope.
Stop, do not retry through it, report the rate-limit snapshot
and reset time. Resume only after the reset *and* a fresh
headroom check.
- Dispatch only needed jobs. No speculative duplicates; cancel your
own superseded queued work through your coordinator.
## Watermarks and escalation etiquette
Each lane has warning watermarks for queue wait and execution time
(defined in the gatekeeper's config). The gatekeeper records
breaches; it **never cancels anything**. Your conduct when a breach
involves your job:
- **Queued breach = starvation.** Your job is the victim, not the
problem. Never cancel it. The lane ahead of it is what gets
escalated.
- **Executing breach = stall suspect.** Check step progression in
the record: a job whose step advanced is slow, not stalled — say
so and stand down to second-warning watch.
- If machine state is needed to tell slow from wedged, that takes a
quick-lane probe job (process list, GPU state, disk, venue log
tail). A probe that never returns reclassifies the event as a
machine-level problem.
- Escalate to the coordination point at the second warning, with
the evidence: run id, lane, dispatch time, watermark breached,
signals observed, probe result.
- **Cancellation authority is narrow:** only your own program's
coordinator, after a recorded check — or the owner. Never another
program's watcher, never automatically, never for a queued
breach.
## Windowless supervision
The runners run under a supervisor (the Syncyard Tray on Windows;
systemd units on Linux/WSL targets), never as hand-started console
windows:
- The Windows tray icon also shows whether the host is
connected to the fleet: a link mark — solid when
connected, hollow amber when stale, broken and desaturated
when disconnected — judged only from host-local signals
(the backchannel agent's heartbeat file, and the fleet
snapshot's stamp when a publisher exists). Runner health
(the slash) and connection (the link) are separate
dimensions. The indicator is display-only: no network
probe, no writes to the signal files, no gating of
supervision; transitions are logged with their signal age.
- Runners stay in the owner's interactive session on purpose: jobs
need the owner's WSL distro, GPU, audio, and bench devices, which
a Windows service in session 0 cannot reliably reach. Do not
register the runners as services.
- Runner directories live under the owner's profile — never in a
drive root.
- A job script that starts a program starts it hidden or headless
and cleans it up when the job ends; a visible window or a
lingering process after a job is a defect in that script.
## Board (hardware) scenario jobs
Jobs that touch physical hardware (development boards on a bench
station) follow an extra discipline on top of everything above:
- They run **one at a time under a claim**: the job registers its
claim before its first hardware step and releases it with actual
times when done. Claims are never silently stacked.
- The first step is always a **reachability and identity proof** in
the execution context that can actually reach the hardware.
Failure aborts before any claimed act.
- Safety gates that protect the hardware are **hard steps inside
the job**: a failed gate aborts before any step that depends on
it.
- Physical acts are **exactly-once**: jobs are idempotent or check
a consumed-marker before repeating an act.
- Steps only a human can do (power cycles, cable moves) are
terminal states: the job stops and reports "human step required".
No retry loops against physical hardware.
- The job **harvests before it exits**: all logs and captures are
copied off the device before the job ends; results left only on
the device mean the job failed.
## Failsafe backchannel
Syncyard has a failsafe backchannel for the case where Syncyard
itself — the runners, the tray, or gatekeeper dispatch — is down
or blocked. It is deliberately narrow:
- **Channel**: `syncyard-dev` in the **private** backchannel
repository — `channels/syncyard-dev/cmd.json`, `out.json`, and
`heartbeat.json`.
- **Owner**: the operator's Syncyard coordination point only. It is
the sole poster to the channel. No other chat or agent may post
to it.
- **No program job traffic, ever.** The backchannel carries only
Syncyard development and recovery work (for example: restart the
runner supervisor in the owner's session, read its log, restart
a runner lane, run read-only network diagnostics). Programs keep
using the gatekeeper in all circumstances.
- **Desktop side**: `backchannel/agent.sh` runs as a systemd user
service under the owner's WSL/Linux user, independent of the
runners, tray, and gatekeeper. It syncs over git (no REST quota),
executes only a command whose id is new and whose sha256 matches
its body's exact bytes (verified and run from a file, never a
shell variable — so multi-line `send --file` bodies execute, and
only genuine mismatches are refused), writes `out.json` matched
by id, and heartbeats every
poll cycle (~60 s). A `channels/syncyard-dev/STOP` file halts
execution while the heartbeat continues. It never writes
gatekeeper queue records. Execution is bounded by the
envelope's `timeout_s` plus a SIGKILL escalation for bodies
that ignore SIGTERM, and `out.json` records the body's real
exit status (65 = agent sha refusal, 124/137 = wrapper
timeout kill).
- **Client**: `backchannel/bc.py heartbeat|status|send|wait`
(Python stdlib only). `send` refuses to overwrite an
unacknowledged pending command unless `--force`, stamps a unique
id + the sha256 of the body, and verifies by reading `cmd.json`
back.
- **Your part**: read-only. Use `bc.py heartbeat` / `status` for
the status check when the gatekeeper is unreachable, and
report a stale heartbeat (>5 min) or a down tray/runner to the
coordination point. Recovery procedures live in
`backchannel/RUNBOOK.md`.
## Break-glass
The operator keeps a separate, frozen emergency admin path outside
Syncyard, for the case where the Actions route itself is broken.
It carries **no job traffic, ever** — not for convenience, not for
speed, not because the queue is long. If you believe the emergency
path is genuinely needed (the gatekeeper cannot dispatch and the
runners cannot be reached), stop, say exactly that, and let the
owner decide. Do not improvise alternate routes to the machines.
## Keeping this skill current (standing rule)
**This skill is updated in the same change as any change to
Syncyard behavior, commands, lanes, workflows, or operations.** A
change that leaves the skill stale is incomplete. All editions of
this skill are generated from one shared source
(`skills/_source/contract.md`) so their content cannot drift; the
repository's CI verifies every edition against that source, the
release VERSION, and the security invariant above.
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · electrohire/syncyard | 95 | Apache-2.0 |
| electrohire/syncyard | 95 | Apache-2.0 |
| electrohire/syncyard | 95 | Apache-2.0 |
| electrohire/syncyard | 95 | Apache-2.0 |
| electrohire/syncyard | 95 | Apache-2.0 |
| electrohire/syncyard | 95 | Apache-2.0 |
| electrohire/syncyard | 93 | Apache-2.0 |
Migawka bazy z 13.11.2026 · wersja paczki d42328ed1747 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100watch-github-actions
Obserwuje i monitoruje przebiegi workflow GitHub Actions przez gh CLI: status, zadania, postęp budowania i stan CI/CD. - 100relayrunner-route-jobs
Przenosi zadania GitHub Actions na RelayRunner, z runnerami GitHub-hosted jako zapasowym wykonawcą. - 100github-actions-silent-failures
Diagnozuje workflow GitHub Actions kończące się po cichu: reużywalne workflow bez jobów i logów, błędne importy gh-aw oraz pułapki self-hosted runnerów.