Add validated agent-stack configuration and optional multi-machine sync

Why

agent-stack currently hard-codes repository membership, repository URLs, paths, host defaults, and installation behavior. Personal wrappers must duplicate the local sync, host install sequence, doctor, dashboard restart, and SSH peer orchestration. That makes the supported team setup difficult to explain and lets private machine details drift away from the open-source workflow.

The open-source repository should publish a validated stack configuration contract and sanitized examples. Actual machine topology, SSH aliases, credentials, and private paths remain user-local.

Depends on the component setup orchestration in shakacode/agent-workflows#851.

Requirements

• R1: Add a versioned, fail-closed stack configuration schema and a sanitized bundled ShakaCode default/example.
• R2: Resolve configuration in documented precedence order: explicit --config, AGENT_STACK_CONFIG, the private runtime configuration under ~/.agent-workflows, then the bundled default.
• R3: Represent repository identity, trusted URL, setup participation, install participation, selected agent hosts, verification, and optional dashboard lifecycle as typed fields rather than arbitrary shell command strings.
• R4: Preserve current CLI flags and environment variables as compatible explicit overrides where practical; reject contradictory or malformed values before cloning, pulling, setup, installation, SSH, or restart mutations.
• R5: Support the common one-machine workflow without requiring a machines section.
• R6: Support an optional local machine topology that names the local machine and SSH peers without publishing personal hostnames, credentials, tokens, or dotfiles paths in the bundled configuration.
• R7: For each configured peer, execute the same installed agent-stack operation on that machine, continue independent peers after one failure, and return a combined per-machine result.
• R8: Bound remote execution, avoid secrets in process arguments or logs, and require an explicit trusted SSH target/configuration. Do not copy runtime secrets between machines.
• R9: Keep repository setup component-owned through the contract introduced by #851.
• R10: Document initial team setup, configuration examples, single-machine sync, optional multi-machine sync, failure recovery, and migration from the existing hard-coded defaults.

Acceptance criteria

• With no user configuration, the current three-repository single-machine behavior remains available through the bundled default.
• A user can select a different source root, compatibility root, runtime root, install target, and host set from one validated configuration file.
• A sanitized two-machine fixture proves local-plus-peer sequencing, continue-on-peer-failure behavior, aggregate exit status, and per-machine diagnostics without real SSH or credentials.
• Invalid schema, unsafe repository URL/path, unknown operation, duplicate machine/repository identity, or contradictory local-machine selection fails before mutations.
• Existing direct flags and environment overrides have regression coverage.
• Documentation contains copyable one-machine team setup and an explicitly optional multi-machine section.

Proposed shape for design validation

version: 1
repositories:
  - name: agent-workflows
    url: https://github.com/shakacode/agent-workflows.git
    setup: true
    install: workflows
  - name: agent-coordination
    url: https://github.com/shakacode/agent-coordination.git
    setup: true
    install: coordination
  - name: agent-coordination-dashboard
    url: https://github.com/shakacode/agent-coordination-dashboard.git
    setup: true
    install: dashboard
hosts: [codex, claude, cursor]
dashboard:
  restart_after_sync: true

A private user-local layer may add machine names and SSH aliases. The final schema may differ, but it must retain typed operations and the privacy boundary above.

Non-goals

• General-purpose fleet management or configuration management.
• Distributing SSH keys, API tokens, or agent credentials.
• Executing configuration-provided arbitrary shell.
• Automatically restarting active Codex, Claude, or Cursor sessions.

Validation

Use the repository validation policy resolved through AGENTS.md and .agents/agent-workflow.yml, focused parser/orchestration tests, shell portability checks, and a mocked multi-machine integration harness.

Start with AGENTS.md and .agents/agent-workflow.yml, then inspect the component setup contract from #851 and the existing CLI entry points. Run focused parser/orchestration tests and the mocked multi-machine harness described in the issue. Done means validated configuration, regression coverage for overrides, sanitized examples and documentation, with safe aggregated peer results and no mutation on invalid input.