Przejdź do treści
Biblioteka skilli
DevOps i chmura · Automatyzacja

syncyard

/syncyard

Zleca i obserwuje zadania na maszynach operatora przez bramkę Syncyard, z pasami wykonawczymi i dzielonym budżetem API.

Repozytorium
syncyard ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

95/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
1
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 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

  1. The security invariant
  2. Commands
  3. Periodic status-check duty
  4. Lane routing
  5. Marker verdicts
  6. API discipline
  7. Watermarks and escalation etiquette
  8. Windowless supervision
  9. Board (hardware) scenario jobs
  10. Failsafe backchannel
Sekcje z nagłówków SKILL.md, w oryginale · 441 linii, 3 383 słów
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

RepozytoriumWynikLicencja
Ta strona · electrohire/syncyard95Apache-2.0
electrohire/syncyard95Apache-2.0
electrohire/syncyard95Apache-2.0
electrohire/syncyard95Apache-2.0
electrohire/syncyard95Apache-2.0
electrohire/syncyard95Apache-2.0
electrohire/syncyard93Apache-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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.