ctrlrelay 0.2.1__tar.gz → 0.3.0__tar.gz

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/.github/workflows/pages.yml

@@ -47,7 +47,7 @@ jobs:
             --destination ./_site
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: docs/_site
 

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/.gitignore

@@ -37,3 +37,6 @@ repos.manifest
 
 # Lock file — not committed per AInvirion Python-SDK convention.
 uv.lock
+
+# Operator-private notes (runbooks, personal cheatsheets).
+notes/

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/CHANGELOG.md

@@ -7,6 +7,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-08
+
+Minor release. Three additive features: cross-machine **personalization
+sync** of operator state through a private GitHub repo, **portability
+fixes** that let one `orchestrator.yaml` work unmodified across machines,
+and **label-driven issue matching** for the dev pipeline. One install
+fix (`PYTHONUNBUFFERED`) and a docs page covering the new
+personalization flow.
+
+### Added
+
+- **Personalization sync** (#123, #124). New `personalization:` config
+  block + `ctrlrelay personalization init/status/push/pull`
+  subcommands sync the operator's Claude Code state — global config,
+  per-project memory, spec/superpower outputs — across machines
+  through a separate (typically private) GitHub repo. Per-machine
+  branches (`personalization/<node_id>`) rebase onto `main` and FF
+  the integration branch, so two machines pushing concurrently never
+  overwrite each other; `--force-with-lease` is reserved for the
+  per-machine branch, never used on `main`. Source/target paths
+  support `${HOME}`, `${PROJECT}` (slug `<owner>--<repo>`),
+  `${PROJECT_ENCODED}` (matches Claude's path encoding),
+  `${PROJECT_LOCAL}`, and `${PROJECT_PARENT}` placeholders. An
+  allowlist limits commits to declared entries — random files in the
+  checkout aren't staged. **Adopt-flow** is on by default: `init`
+  moves pre-existing real targets (e.g. `~/.claude/CLAUDE.md` that
+  predates the sync setup) into the synced repo and lays a symlink in
+  their place; `--no-adopt` opts out. Both-real-content collisions
+  surface as `skipped-conflict-both-exist` for manual reconciliation.
+  See the new [Personalization sync](docs/personalization.md) page.
+- **Auto-pull on cron** (#124). New optional
+  `schedules.personalization_cron` runs `personalization pull` on the
+  poller daemon, with two safety rails: skip-on-dirty (never rebases
+  under uncommitted operator edits) and `adopt=False` on the re-wire
+  (a background sync never silently moves files; adoption stays
+  init-only). Auto-push is intentionally not scheduled — daemon-side
+  commits surprise people. Dispatched via `asyncio.to_thread` so a
+  slow remote can't stall the poller's event loop (Telegram dispatch,
+  pending-resume sweeper, secops cron).
+- **`paths.repo_root` + `paths.owner_aliases`** (#121). When set,
+  `repos[].local_path` is derived as
+  `${repo_root}/${owner_aliases.get(owner, owner)}/${repo}`. Per-repo
+  `local_path` still wins as an override. Without `repo_root`, the
+  legacy "local_path required per repo" behaviour is preserved.
+  Collapses 69 explicit `local_path` values to 20 in the maintainer's
+  config.
+- **`node_id` defaults to hostname** (#121). Falls back to
+  `socket.gethostname()` when missing, null, or blank. Heartbeats and
+  session logs still get a meaningful per-node label without forcing
+  every operator to edit the file.
+- **`ctrlrelay install launchd|systemd`** (#121). Renders
+  bridge/poller service unit files from in-package templates,
+  substituting `USER`, `HOME`, `CTRLRELAY_BIN`, `WORKDIR`,
+  `LABEL_PREFIX`, `POLLER_INTERVAL`, and (when set)
+  `CTRLRELAY_TELEGRAM_TOKEN`. Writes to the conventional locations
+  (`~/Library/LaunchAgents` on macOS, `~/.config/systemd/user` on
+  Linux) and refuses to clobber existing files unless `--force`.
+  Replaces the docs.operations.md copy-paste flow where every
+  operator hand-edited `/Users/$ME/...` strings — a tax on
+  portability and a common source of broken plists.
+- **Label-driven issue matching** (#115, closes #80). Two new
+  per-repo lists govern which issues the poller hands to the dev
+  pipeline:
+  - `repos[].automation.exclude_labels` (default `["manual",
+    "operator", "instruction"]`) — issues carrying any of these
+    labels are skipped, marked seen, logged as
+    `poll.issue.excluded_by_label`, and never trigger code changes.
+    For operator tasks and pure instruction issues.
+  - `repos[].automation.include_labels` (default `[]`) — when
+    non-empty, issues carrying any of these labels opt **in** to the
+    dev pipeline regardless of who is (or isn't) assigned. For repos
+    that drive the pipeline by triage label rather than assignment.
+  Matching is case-insensitive. Trust model documented in
+  [configuration.md](docs/configuration.md#repos-automation): anyone
+  with triage permission on a repo can apply a label, which matches
+  ctrlrelay's existing trust model.
+
+### Fixed
+
+- **`PYTHONUNBUFFERED=1` in launchd plists and systemd units** (#122).
+  Without it, daemon stdout/stderr buffered up to 4–8 KB before
+  flushing to the log file — so `tail -f` on a poller log looked
+  frozen for minutes during quiet periods, and crash diagnostics were
+  clipped at the last buffer boundary instead of the actual failure
+  point. Templates now set the env var and `ctrlrelay install
+  launchd|systemd` re-emits both unit files on next run.
+
+### Docs
+
+- **[Personalization sync](docs/personalization.md)** (#125). New
+  page (nav order 8) covering setup, the dotclaude repo layout, the
+  init/status/push/pull lifecycle, `--no-adopt`, auto-pull cron,
+  multi-machine bootstrap, and the gotchas (worktrees, edit-through-
+  symlink semantics, allowlist enforcement, conflict handling, strict
+  origin URL match). Pairs with new `schedules` and `personalization`
+  sections in [configuration.md](docs/configuration.md) and a new
+  `ctrlrelay personalization` block in [cli.md](docs/cli.md).
+
 ## [0.2.1] - 2026-04-28
 
 Patch release. Fixes a long-standing UX bug where `ctrlrelay` could

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrlrelay
-Version: 0.2.1
+Version: 0.3.0
 Summary: Local-first orchestrator for headless coding agents across multiple GitHub repos
 Project-URL: Homepage, https://github.com/AInvirion/ctrlrelay
 Project-URL: Documentation, https://ainvirion.github.io/ctrlrelay/
@@ -84,9 +84,12 @@ are on the roadmap (see [Roadmap](#roadmap)).
 
 ## Features
 
-- **Issue poller.** Detects issues assigned to you across every
-  configured repo, spawns a dev session in a dedicated git worktree,
-  and opens a PR.
+- **Issue poller.** Detects issues across every configured repo
+  (either assigned to you, or carrying a configurable opt-in label like
+  `ctrlrelay:auto`), spawns a dev session in a dedicated git worktree,
+  and opens a PR. Label triggers let a teammate without rights on your
+  account flag an issue as safe for the bot to pick up —
+  see [`include_labels`][docs-config].
 - **Telegram bridge.** When a session hits a blocking question, the
   bridge relays it to you as a DM and resumes the session once you
   reply.

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/README.md

@@ -45,9 +45,12 @@ are on the roadmap (see [Roadmap](#roadmap)).
 
 ## Features
 
-- **Issue poller.** Detects issues assigned to you across every
-  configured repo, spawns a dev session in a dedicated git worktree,
-  and opens a PR.
+- **Issue poller.** Detects issues across every configured repo
+  (either assigned to you, or carrying a configurable opt-in label like
+  `ctrlrelay:auto`), spawns a dev session in a dedicated git worktree,
+  and opens a PR. Label triggers let a teammate without rights on your
+  account flag an issue as safe for the bot to pick up —
+  see [`include_labels`][docs-config].
 - **Telegram bridge.** When a session hits a blocking question, the
   bridge relays it to you as a DM and resumes the session once you
   reply.

ctrlrelay-0.3.0/config/orchestrator.yaml.example

@@ -0,0 +1,141 @@
+# ctrlrelay orchestrator configuration
+# Copy to orchestrator.yaml and customize
+
+version: "1"
+# node_id defaults to socket.gethostname() when omitted. Set explicitly
+# only if the hostname is meaningless (CI runners, containers).
+# node_id: "studio-mac"
+timezone: "America/Santiago"
+
+paths:
+  state_db: "~/.ctrlrelay/state.db"
+  worktrees: "~/.ctrlrelay/worktrees"
+  bare_repos: "~/.ctrlrelay/repos"
+  contexts: "~/.ctrlrelay/contexts"
+  skills: "~/.ctrlrelay/claude-config/skills"
+  # Optional. When set, repo entries below can omit local_path and have
+  # it derived as ${repo_root}/${owner_aliases.get(owner, owner)}/${repo}.
+  # Per-repo local_path always wins as override.
+  # repo_root: "~/Projects"
+  # owner_aliases:
+  #   AInvirion: AINVIRION       # GitHub owner -> on-disk folder name
+  #   SemClone: SEMCL.ONE
+
+# Headless coding agent. `type` selects the adapter (currently only
+# "claude" is implemented; other backends — codex, opencode, hermes,
+# kiro — are planned). Legacy `claude:` key is still accepted as an
+# alias for backwards compatibility but is deprecated.
+agent:
+  type: "claude"
+  binary: "claude"
+  default_timeout_seconds: 1800
+  output_format: "json"
+
+transport:
+  type: "file_mock"  # Use "telegram" for production
+  telegram:
+    bot_token_env: "CTRLRELAY_TELEGRAM_TOKEN"
+    chat_id: 123456789
+    socket_path: "~/.ctrlrelay/ctrlrelay.sock"
+  file_mock:
+    inbox: "~/.ctrlrelay/inbox.txt"
+    outbox: "~/.ctrlrelay/outbox.txt"
+
+dashboard:
+  enabled: false
+  url: "https://ctrlrelay-dashboard.example.com"
+  auth_token_env: "CTRLRELAY_DASHBOARD_TOKEN"
+
+# Scheduled jobs run in-process by the poller daemon. Cron expressions are
+# standard 5-field (minute hour dom month dow) and evaluate in the `timezone`
+# set above. Change `secops_cron` to e.g. "0 6 * * 1" for weekly (Mondays).
+schedules:
+  secops_cron: "0 6 * * *"
+  # Optional. When personalization is configured AND this is set, the
+  # poller daemon runs `ctrlrelay personalization pull` on this cron
+  # so machines converge without manual sync. Skip-on-dirty: never
+  # rebases under uncommitted operator edits. Defaults to None
+  # (manual sync only).
+  # personalization_cron: "*/15 * * * *"
+
+# Optional: cross-machine personalization sync.
+#
+# A separate (typically PRIVATE) GitHub repo holds the operator's Claude
+# config, per-project memory, spec/superpower outputs, and workspace
+# planning notes — anything that survives across sessions and computers
+# but doesn't belong inside any project's source tree. ctrlrelay clones
+# the repo to `checkout_path` and wires the symlinks in `paths`.
+#
+# Per-machine work happens on a `personalization/<node_id>` branch; push
+# rebases onto `main` (no force-push, ever), so two machines pushing
+# concurrently never overwrite each other's deltas.
+#
+# Slice 1: manual `ctrlrelay personalization init/status/push/pull`.
+# Daemon scheduling, Telegram conflict escalation, and adopt-flow for
+# pre-existing target files are deferred to Slice 2+.
+#
+# Placeholders allowed in `source` and `target`:
+#   ${HOME}             -- current user's home
+#   ${PROJECT}          -- <owner>--<repo> flat slug (project_scoped only;
+#                          double hyphen avoids collisions like a-b/c vs a/b-c)
+#   ${PROJECT_ENCODED}  -- Claude's path encoding (project_scoped only)
+#   ${PROJECT_LOCAL}    -- absolute path of the repo's local checkout
+#   ${PROJECT_PARENT}   -- parent dir of ${PROJECT_LOCAL}
+#
+# personalization:
+#   repo: "oscarvalenzuelab/dotclaude"
+#   # checkout_path: "~/.ctrlrelay/personalization"   # default
+#   # main_branch: "main"                              # default
+#   # node_id: "macbook"   # default: top-level node_id (i.e. hostname)
+#   paths:
+#     # Global Claude config — fixed paths, one entry each so individual
+#     # files can come and go without ripping a whole `~/.claude/` symlink.
+#     - source: "global/CLAUDE.md"
+#       target: "~/.claude/CLAUDE.md"
+#     - source: "global/skills/"
+#       target: "~/.claude/skills/"
+#     - source: "global/agents/"
+#       target: "~/.claude/agents/"
+#     - source: "global/commands/"
+#       target: "~/.claude/commands/"
+#     - source: "global/keybindings.json"
+#       target: "~/.claude/keybindings.json"
+#
+#     # Per-project Claude memory. ${PROJECT_ENCODED} resolves at
+#     # link-time from the repo's local_path, so the same config works
+#     # on machines with different home directories or repo layouts.
+#     - source: "claude-memory/${PROJECT}/"
+#       target: "~/.claude/projects/${PROJECT_ENCODED}/memory/"
+#       project_scoped: true
+#
+#     # Spec / superpower outputs Claude writes per the convention
+#     # documented in templates/global-CLAUDE.md.snippet. Lives next to
+#     # the repo (NOT inside it) so the project's own git history stays
+#     # uncontaminated.
+#     - source: "specs/${PROJECT}/"
+#       target: "${PROJECT_PARENT}/specs/${PROJECT}/"
+#       project_scoped: true
+#
+#     # Workspace-level planning docs (multi-repo workspace, e.g. a
+#     # research project that spans 3 repos under a single parent dir).
+#     # Use one entry per workspace; if you accumulate many, this will
+#     # be promoted to a first-class `workspaces:` config block.
+#     # - source: "workspaces/RESEARCH-DMP/"
+#     #   target: "~/Projects/RESEARCH/DMP/notes/"
+
+repos: []
+  # Example repo configuration:
+  # - name: "owner/repo"
+  #   # Optional when paths.repo_root is set; otherwise required.
+  #   local_path: "~/Projects/repo"
+  #   automation:
+  #     dependabot_patch: auto
+  #     dependabot_minor: ask
+  #     dependabot_major: never
+  #     # Issues carrying any of these labels are skipped by the poller:
+  #     # marked seen, logged as poll.issue.excluded_by_label, and never
+  #     # handed to the dev pipeline. Intended for operator tasks and
+  #     # pure instruction issues that should not trigger code changes.
+  #     # Matching is case-insensitive. Defaults to ["manual", "operator",
+  #     # "instruction"]; override with an empty list to disable.
+  #     exclude_labels: ["manual", "operator", "instruction"]

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/docs/architecture.md

@@ -1,7 +1,7 @@
 ---
 title: Architecture
 layout: default
-nav_order: 8
+nav_order: 9
 description: "Layer diagram, dispatcher / Claude interaction, state-DB shape, and worktree lifecycle for contributors."
 permalink: /architecture/
 ---

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/docs/cli.md

@@ -232,6 +232,85 @@ ctrlrelay poller status [-c PATH]
 
 Reports running / not-running.
 
+## `ctrlrelay personalization`
+
+See [Personalization sync]({{ '/personalization/' | relative_url }})
+for the conceptual walkthrough. All subcommands require a
+`personalization:` block in `orchestrator.yaml` and operate on the
+checkout at `personalization.checkout_path` (default
+`~/.ctrlrelay/personalization`).
+
+### `personalization init`
+
+```bash
+ctrlrelay personalization init [-c PATH] [--no-adopt]
+```
+
+Clones the personalization repo into `checkout_path`, creates the
+per-machine working branch (`personalization/<node_id>`), and lays
+down the symlinks declared in `personalization.paths`.
+
+By default, **adopt-flow** is on: a target that exists as a real file
+or directory while its corresponding source slot in the repo is empty
+is moved into the repo and replaced with a symlink. Your existing
+content is preserved and immediately under sync. Run `personalization
+push` after `init` to send the adopted content to GitHub.
+
+Pass `--no-adopt` to opt out of adoption — pre-existing real targets
+surface as `skipped-real-file-at-target` instead, and you back them up
++ remove them manually before re-running.
+
+If both the repo source and the on-disk target have real content,
+`init` refuses with `skipped-conflict-both-exist` regardless of
+`--no-adopt`. Reconcile manually before re-running.
+
+### `personalization status`
+
+```bash
+ctrlrelay personalization status [-c PATH]
+```
+
+Prints the working branch, repo URL, ahead/behind counts vs. origin,
+and per-symlink state — `correct`, `wrong-target`, `missing`,
+`source-missing`, etc. Read-only; doesn't touch the filesystem.
+
+### `personalization push`
+
+```bash
+ctrlrelay personalization push [-c PATH] -m "MESSAGE"
+```
+
+Stages the entries declared in `paths` (allowlist — random files in
+the checkout are not committed), commits with `MESSAGE`, rebases the
+per-machine branch onto `origin/<main_branch>`, and pushes. Retries
+the fast-forward of `origin/main` up to three times if another
+machine's push lands between fetch and push. Uses
+`--force-with-lease` on the per-machine branch only when the local
+working branch has diverged from the remote (after a rebase) — never
+on `main`.
+
+Conflicts during the rebase abort and list the unmerged files for you
+to resolve.
+
+### `personalization pull`
+
+```bash
+ctrlrelay personalization pull [-c PATH]
+```
+
+Fetches, rebases the per-machine branch onto `origin/<main_branch>`,
+fast-forwards local `main` if it's an ancestor of the remote, and
+re-wires symlinks (the config-as-code shipped in the repo may have
+changed). Uses `adopt=True` like `init` so newly-declared paths can
+adopt local content during a `pull`. Conflicts abort cleanly and list
+the unmerged files.
+
+The daemon-driven auto-pull (under
+[`schedules.personalization_cron`]({{ '/configuration/#schedules' | relative_url }}))
+calls the same code with two extra rails: skip when the working tree
+is dirty, and re-wire with `adopt=False` so a background sync never
+silently moves files.
+
 ## `ctrlrelay status`
 
 ```bash

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/docs/configuration.md

@@ -32,13 +32,15 @@ repos:        [ ... ]
 | Key | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `version` | string | no | `"1"` | Config schema version. Currently always `"1"`. |
-| `node_id` | string | **yes** | — | Free-form identifier for this machine. Surfaces in dashboard heartbeats and session logs. |
+| `node_id` | string | no | `socket.gethostname()` | Free-form identifier for this machine. Surfaces in dashboard heartbeats and session logs. Defaults to the OS hostname when omitted, null, or blank — set explicitly only if the hostname is meaningless (CI runners, ephemeral containers). |
 | `timezone` | string | no | `"UTC"` | IANA timezone (e.g. `America/Santiago`). Used for scheduling. |
 | `paths` | object | **yes** | — | See [paths](#paths). |
 | `claude` | object | no | (defaults) | See [claude](#claude). |
 | `transport` | object | **yes** | — | See [transport](#transport). |
 | `dashboard` | object | no | (defaults) | See [dashboard](#dashboard). |
 | `repos` | list | no | `[]` | See [repos](#repos). |
+| `schedules` | object | no | (defaults) | See [schedules](#schedules). |
+| `personalization` | object | no | unset | Cross-machine sync of Claude state. See [personalization](#personalization) and [Personalization sync]({{ '/personalization/' | relative_url }}). |
 
 ## paths
 
@@ -51,6 +53,11 @@ paths:
   bare_repos:  "~/.ctrlrelay/repos"
   contexts:    "~/.ctrlrelay/contexts"
   skills:      "~/.claude/skills"
+  # Optional convention for repos[].local_path:
+  repo_root:   "~/Projects"
+  owner_aliases:
+    AInvirion: AINVIRION       # GitHub owner -> on-disk folder name
+    SemClone: SEMCL.ONE
 ```
 
 | Key | Type | Required | Description |
@@ -60,6 +67,8 @@ paths:
 | `bare_repos` | path | **yes** | Where ctrlrelay clones bare mirrors of each configured repo. |
 | `contexts` | path | **yes** | Per-repo context directory (looked up as `<contexts>/<owner-repo>/CLAUDE.md`). If a `CLAUDE.md` exists, it is symlinked into the worktree at session start. |
 | `skills` | path | **yes** | Claude Code skills directory used by `ctrlrelay skills audit` and `ctrlrelay skills list`. |
+| `repo_root` | path | no | Convention root for repo clones. When set, `repos[].local_path` may be omitted and is derived as `${repo_root}/${owner_aliases.get(owner, owner)}/${repo}`. Without `repo_root`, every repo entry must declare its own `local_path` (legacy behaviour). |
+| `owner_aliases` | object | no | Map of GitHub owner -> on-disk folder name. Lets the convention work when local folders use a vanity name (`SemClone` repos under `~/Projects/SEMCL.ONE/`). Lookup falls through to the literal owner if not present. |
 
 ## claude
 
@@ -172,7 +181,7 @@ repos:
 | Key | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `name` | string | **yes** | — | GitHub `owner/repo` slug. Used for `gh` calls and bare-repo / worktree naming. |
-| `local_path` | path | **yes** | — | Where the repo is checked out on disk for human use. ctrlrelay itself uses bare mirrors under `paths.bare_repos`. |
+| `local_path` | path | conditional | derived | Where the repo is checked out on disk for human use. Optional when `paths.repo_root` is set (then derived as `${repo_root}/${owner_aliases.get(owner, owner)}/${repo}`); required otherwise. An explicit value always wins as override. ctrlrelay itself uses bare mirrors under `paths.bare_repos`. |
 | `dev_branch_template` | string | no | `"fix/issue-{n}"` | Branch-name template for dev-pipeline runs. `{n}` is replaced by the issue number. |
 | `automation` | object | no | (defaults) | See [automation](#repos-automation). |
 | `code_review` | object | no | (defaults) | Reserved for code-review policy. Currently unused by the bundled pipelines. |
@@ -193,6 +202,7 @@ and ask the operator), or `never` (skip).
 | `deploy_after_merge` | `auto` | Whether to deploy after a merged PR. |
 | `accept_foreign_assignments` | `false` | When `true`, the poller also picks up issues assigned to you by someone else. Default (`false`) runs the dev pipeline only on issues you self-assigned. |
 | `exclude_labels` | `["manual", "operator", "instruction"]` | Issue labels that tell the poller "this isn't for the agent". See [exclude_labels](#reposautomationexclude_labels) below. |
+| `include_labels` | `[]` | Issue labels that opt an issue **into** the dev pipeline regardless of who is (or isn't) assigned. See [include_labels](#reposautomationinclude_labels) below. |
 
 The current secops and dev pipelines read these settings to bias their prompts
 to Claude — they're not enforced by hard-coded checks.
@@ -228,6 +238,150 @@ label on GitHub **and** delete the issue number from
 other mechanism — the poller treats "seen" as sticky per design, so operator
 input is the source of truth).
 
+### repos[].automation.include_labels
+
+Out of the box, an issue enters the dev pipeline only when it's assigned to
+the configured GitHub user (and, with the pre-#79 self-assignment filter, only
+when *you* were the one who assigned it). That works for a personal to-do
+list; it doesn't cover the "team-coordinated" workflow where a teammate without
+rights on your account wants to say "this issue is safe for the agent to take
+a shot at."
+
+`include_labels` is the opt-in complement to `exclude_labels`. Any issue
+carrying one of the configured labels is handed to the dev pipeline,
+**regardless of assignment**. The label itself is the trust signal — you opt
+in by configuring the label; anyone with triage permission on the repo can
+then flag an issue for the bot.
+
+```yaml
+repos:
+  - name: "your-org/your-repo"
+    local_path: "~/Projects/your-repo"
+    automation:
+      include_labels: ["ctrlrelay:auto"]
+```
+
+- Default: `[]`. An empty list preserves the pre-#80 assignment-only trigger
+  — no behavior change for operators who haven't opted in.
+- Matching is **case-insensitive** (`CtrlRelay:Auto` matches `ctrlrelay:auto`).
+- An issue is accepted when **either** (a) it's assigned to the configured
+  user (subject to the self-assignment filter from #79 and
+  `accept_foreign_assignments`) **or** (b) it carries any label in
+  `include_labels`. A label match **skips** the self-assignment check — the
+  operator's config choice is the trust boundary.
+- Dedup: an issue that is **both** labeled and assigned is picked up exactly
+  once per poll cycle — no duplicate entries in `seen_issues` and no double
+  pipeline spawn.
+- `exclude_labels` always wins over `include_labels` on the same issue: an
+  explicit "not for the agent" opt-OUT beats the generic label opt-IN.
+- When a repo configures `include_labels`, the poller runs **targeted**
+  queries per cycle: the existing `gh issue list --assignee <user>` plus
+  one `gh issue list --label <L>` call per configured label. Results merge
+  by issue number. This keeps the label path scale-safe on busy repos
+  where an unfiltered fetch would silently cap at gh's `--limit` and miss
+  labeled issues on later pages. Repos without `include_labels` run only
+  the cheap `--assignee` query, so enabling the feature on one repo does
+  not add API calls on the others.
+- The event log entry for a label-triggered acceptance is
+  `poll.issue.included_by_label`, alongside the existing
+  `poll.issue.excluded_by_label` for exclusions.
+- **Interaction with `task_labels`**: `include_labels` opts an issue
+  into the poller's consideration set. Once surfaced, the usual
+  routing still applies — if the same issue also carries a
+  `task_labels` label, it runs through the **task** pipeline (report-
+  only, no PR), not the dev pipeline. If you want label-triggered
+  issues to always run dev, make sure `include_labels` and
+  `task_labels` are disjoint (e.g. label opt-ins with
+  `ctrlrelay:auto` and task runs with `task:<topic>`).
+- **Upgrade path**: enabling `include_labels` on a repo that was
+  already running the poller does NOT retroactively re-evaluate
+  issues already in `poller_state.json`. Any foreign-assigned issue
+  that pre-dates the config change won't be picked up via a later
+  label addition. Only brand-new issues (after the config change) or
+  issues you re-open will go through the label trigger. If you need
+  to re-evaluate pre-existing issues on a specific repo, stop the
+  poller, remove that repo's entry from `poller_state.json` under
+  `seen_issues`, and restart. (A fully automatic migration would
+  risk re-running pipelines for issues the bot had already handled.)
+
+Trust model: anyone with triage permission on a repo can apply a label. That
+matches the trust model ctrlrelay already uses — the operator configures which
+repos and which labels trigger the pipeline; a hostile collaborator with
+triage access was already able to push branches and trigger CI, so allowing
+them to opt an issue into the dev pipeline is a narrower extension, not a new
+vector.
+
+## schedules
+
+In-process cron jobs run by the poller daemon. All expressions are
+standard 5-field (minute hour dom month dow) and evaluate in the
+top-level `timezone`. Malformed expressions fail at config load — they
+won't silently disable the job at runtime.
+
+```yaml
+schedules:
+  secops_cron: "0 6 * * *"          # daily 06:00 sweep across repos
+  personalization_cron: "*/15 * * * *"  # optional auto-pull
+```
+
+| Key | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `secops_cron` | string | no | `"0 6 * * *"` | When to run the secops sweep (`ctrlrelay secops run` equivalent) across all configured repos. Set to e.g. `"0 6 * * 1"` for weekly Mondays. |
+| `personalization_cron` | string | no | unset | When to auto-pull the personalization repo on this machine. Only effective when [`personalization`](#personalization) is also set. Skip-on-dirty: never rebases under uncommitted operator edits. Adoption is never performed by auto-pull — that stays an init-time concern. |
+
+## personalization
+
+Optional. Configures cross-machine sync of operator state (Claude
+config, per-project memory, spec/superpower outputs) through a
+separate (typically private) GitHub repo. See [Personalization
+sync]({{ '/personalization/' | relative_url }}) for the full
+walkthrough; this section documents the schema.
+
+```yaml
+personalization:
+  repo: "your-handle/dotclaude"
+  # checkout_path: "~/.ctrlrelay/personalization"   # default
+  # main_branch: "main"                              # default
+  # node_id: "studio-mac"                            # default: top-level node_id
+  paths:
+    - source: "global/CLAUDE.md"
+      target: "~/.claude/CLAUDE.md"
+    - source: "global/skills/"
+      target: "~/.claude/skills/"
+    - source: "claude-memory/${PROJECT}/"
+      target: "~/.claude/projects/${PROJECT_ENCODED}/memory/"
+      project_scoped: true
+    - source: "specs/${PROJECT}/"
+      target: "${PROJECT_PARENT}/specs/${PROJECT}/"
+      project_scoped: true
+```
+
+| Key | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `repo` | string | **yes** | — | `<owner>/<repo>` slug for the personalization repo on github.com. |
+| `checkout_path` | string | no | `~/.ctrlrelay/personalization` | Where ctrlrelay clones the repo on this machine. |
+| `main_branch` | string | no | `"main"` | Long-lived integration branch. Per-machine branches rebase onto this. |
+| `node_id` | string | no | top-level `node_id` | Identifies this machine's working branch (`personalization/<node_id>`). Override only if the top-level value isn't safe as a git branch component. |
+| `paths` | list | **yes** | — | One entry per file/dir to sync. See [personalization.paths](#personalizationpaths). |
+
+### personalization.paths
+
+Each entry declares one source-to-target wiring. Trailing slashes
+distinguish files from directories — `source: "global/CLAUDE.md"` is
+a file, `source: "global/skills/"` is a directory; the target must
+agree.
+
+| Key | Type | Required | Description |
+|---|---|---|---|
+| `source` | string | **yes** | Path inside the personalization repo. Trailing slash means directory. |
+| `target` | string | **yes** | On-disk path the symlink will be created at. Supports `${HOME}` and (when `project_scoped`) `${PROJECT}`, `${PROJECT_ENCODED}`, `${PROJECT_LOCAL}`, `${PROJECT_PARENT}`. |
+| `project_scoped` | bool | no (default `false`) | When `true`, the entry expands once per repo in `repos:`, with the `${PROJECT_*}` placeholders resolved against that repo's `local_path`. |
+
+The `${PROJECT}` slug uses **`<owner>--<repo>`** with a double
+hyphen so `a-b/c` and `a/b-c` produce different slugs. `${PROJECT_ENCODED}`
+matches Claude Code's own path encoding rule (`/Users/foo/Projects/bar`
+→ `-Users-foo-Projects-bar`).
+
 ## Example: telegram-enabled config
 
 ```yaml

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/docs/development.md

@@ -1,7 +1,7 @@
 ---
 title: Development
 layout: default
-nav_order: 9
+nav_order: 10
 description: "Local development setup, running tests, linting, and contributing."
 permalink: /development/
 ---

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/docs/getting-started.md

@@ -57,16 +57,20 @@ cp config/orchestrator.yaml.example config/orchestrator.yaml
 
 Open `config/orchestrator.yaml` and edit at least:
 
-- `node_id` — a label for this machine (free-form string).
 - `timezone` — your local IANA timezone.
 - `repos[].name` — the `owner/repo` slug of a repository you can push to.
 - `repos[].local_path` — where the local clone lives (or will live) on disk.
+  *Or* set `paths.repo_root` to a workspace root and let the path be
+  derived as `${repo_root}/${owner}/${repo}` (recommended for >1 repo).
+
+`node_id` is optional — when omitted it defaults to your machine's
+hostname (`socket.gethostname()`). Set it explicitly only if the
+hostname is meaningless (CI runners, containers).
 
 A minimal working config:
 
 ```yaml
 version: "1"
-node_id: "my-laptop"
 timezone: "America/New_York"
 
 paths:
@@ -102,7 +106,7 @@ You should see something like:
 
 ```
 ✓ Config valid: config/orchestrator.yaml
-  Node ID: my-laptop
+  Node ID: your-hostname.local
   Timezone: America/New_York
   Transport: file_mock
   Repos: 1
@@ -166,3 +170,4 @@ To run the poller as a long-lived background service, see [Operations]({{ '/oper
 - [Feedback loop]({{ '/feedback-loop/' | relative_url }}) — what `BLOCKED_NEEDS_INPUT` actually does end-to-end.
 - [CLI reference]({{ '/cli/' | relative_url }}) — every subcommand and flag.
 - [Operations]({{ '/operations/' | relative_url }}) — running ctrlrelay as a service.
+- [Personalization sync]({{ '/personalization/' | relative_url }}) — sync your Claude config, per-project memory, and spec outputs across machines.

{ctrlrelay-0.2.1 → ctrlrelay-0.3.0}/docs/index.md

@@ -36,6 +36,9 @@ isolated git worktree, opens a PR, and asks you on Telegram when it gets stuck.
 - **[Operations]({{ '/operations/' | relative_url }})** — running the bridge
   and poller under launchd (macOS) or systemd (Linux), tailing logs, reading
   the state DB.
+- **[Personalization sync]({{ '/personalization/' | relative_url }})** —
+  cross-machine sync of Claude config, per-project memory, and spec
+  outputs through a private GitHub repo.
 
 ## Build on it