agcoord 0.1.0__tar.gz

agcoord-0.1.0/AGENTS.md

@@ -0,0 +1,59 @@
+# AGCoord contributor instructions
+
+Keep this file compact and broadly applicable. Component contracts and procedures belong in
+the canonical documents listed by [docs/index.md](docs/index.md).
+
+## Track and isolate changes
+
+- Create a descriptive issue before changing code, tests, documentation, packaging, or live
+  state. Pair every issue number with a sentence explaining the work it tracks.
+- Make and validate the change in a ticket-specific Git worktree branched from `main`.
+  Preserve unrelated edits and do not develop in the primary checkout.
+- Keep the core coordinator forge-neutral. Forge-specific metadata and publication behavior
+  belongs in an optional adapter.
+
+## Test behavior and document contracts
+
+- Reproduce a bug with a failing behavioral test before changing runtime code. Exercise
+  public APIs, commands, subprocesses, Git repositories, and the real TUI; do not inspect
+  source or documentation text to prove behavior.
+- Every runtime change includes focused tests and updates affected canonical documentation.
+  Register new documents in `docs/index.md` and record published user-facing changes in
+  `CHANGELOG.md`.
+- Tests own and stop every broker, worker, repository, and temporary state they start. Never
+  inspect or clean another agent's state.
+
+## Coordinate checks and publication
+
+Once AGCoord is installed, every check and publication uses the local coordinator:
+
+```bash
+agcoord run --label "focused tests" --resource cpu=1 -- python -m pytest -q tests/test_area.py
+agcoord full --label "standalone full validation" --resource cpu=4 -- python -m pytest -q
+agcoord land <request> --label "gate and publish" --resource cpu=4 -- python -m pytest -q
+```
+
+- Declare every scarce resource a command consumes. A full gate is a barrier for its
+  repository, not an undeclared machine-global lock.
+- Use `agcoord full` from a clean checkout when an exact-head validation is useful without
+  publication. It remains a repository barrier, but a separate full row followed by a merge
+  is not the normal landing workflow.
+- Push/open the publication request, then use one `agcoord land` request whose gate command
+  validates that exact clean 40-character head and publishes it without releasing the lane
+  or declared resources. Do not use direct target-branch pushes, forge merge commands, a
+  full-plus-merge gap, or an equivalent path that separates the landing verdict from its
+  publication.
+- A stale-target or changed-head refusal hands the work back to the agent: update the branch
+  explicitly, push, and submit a fresh `agcoord land` request. AGCoord never refreshes,
+  rebases, or rewrites the worktree for you, and never reuses the previous gate result after
+  either reference moves.
+- Do not invoke `agcoord`, a gate wrapper, or publication from inside an admitted AGCoord
+  job; nested submissions are rejected to prevent self-deadlock.
+- Remove the merged ticket worktree and branch only after publication succeeds.
+
+Bootstrap exception: before AGCoord is installed in a fresh AGCoord development environment,
+direct package installation and focused tests are allowed only long enough to make
+`agcoord run` available; direct full gates and publication are never bootstrap shortcuts.
+
+See [docs/coordinator.md](docs/coordinator.md) for scheduling, receipts, recovery, cleanup,
+TUI, and migration details, and [docs/releasing.md](docs/releasing.md) for the release gate.

agcoord-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable user-facing changes to AGCoord are recorded here. Versions follow semantic
+versioning; dates use ISO 8601.
+
+## 0.1.0 — 2026-08-30
+
+- Publish the standalone `agcoord` distribution, import package, module entry point, and
+  console command for Python 3.10 and newer.
+- Coordinate multiple agents, Git worktrees, and repositories through one detached,
+  user-scoped broker with durable job IDs, logs, resource capacities, repository barriers,
+  cancellation, history clearing, recovery, and private scratch reclamation.
+- Add `land`, one durable repository-barrier request that preflights an exact clean head,
+  runs its captured gate, and immediately publishes a green result without releasing its
+  lane or resources; red gates and stale target/head observations publish nothing.
+- Expose land phases, gate exit status, one combined transcript, safe cancellation
+  boundaries, and crash recovery that never reruns a gate. Keep `full` as a standalone
+  exact-head validation command instead of a full-plus-publication landing sequence.
+- Provide GitHub metadata and exact ref-publication adapters without making `gh` a core
+  import dependency.
+- Add `run`, `full`, `land`, `list`, `show`, `log`, `cancel`, `tui`, `migrate`, and `clear`
+  workflows, including a compact live multi-repository terminal view.
+- Give admitted workers immutable run ID, exact kind, and resolved state-directory context
+  so internal repository gate wrappers can verify the correct full or land admission even
+  with an explicit state directory, without exposing environment values or credentials in
+  public job rows.
+- Promote the exact successful TestPyPI wheel and source archive from the tagged commit to
+  PyPI instead of rebuilding production artifacts after the release-candidate smoke.

agcoord-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGCoord contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agcoord-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include AGENTS.md
+include CHANGELOG.md
+recursive-include docs *.md *.png
+recursive-include tests *.py

agcoord-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: agcoord
+Version: 0.1.0
+Summary: Machine-local gate and publication coordinator for development agents
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xu-hao/agcoord
+Project-URL: Changelog, https://github.com/xu-hao/agcoord/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/xu-hao/agcoord/tree/main/docs
+Project-URL: Issues, https://github.com/xu-hao/agcoord/issues
+Project-URL: Repository, https://github.com/xu-hao/agcoord
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=1
+Provides-Extra: test
+Requires-Dist: build>=1.2; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: twine>=5; extra == "test"
+Dynamic: license-file
+
+# AGCoord
+
+![AGCoord gourd mascot](https://raw.githubusercontent.com/xu-hao/agcoord/main/docs/assets/agcoord-gourd-mascot.png)
+
+AGCoord is a machine-local coordinator for developers and coding agents that share a
+workstation. It gives every check, standalone full gate, and atomic gate-and-publication
+request one durable job ID, then schedules compatible work across repositories without
+letting two agents accidentally publish stale or untested code.
+
+The coordinator is local infrastructure: one detached broker per OS user, a private durable
+spool, per-job logs, and an optional terminal UI. It does not require a hosted service. The
+core package is forge-neutral; GitHub support is an optional adapter.
+
+## Install and start
+
+Install the published package in a tool environment:
+
+```bash
+python -m pip install agcoord
+```
+
+There is no separate service-install step. The first command starts the detached broker on
+demand; later shells and repositories join the same user-scoped coordinator:
+
+```bash
+agcoord list
+agcoord tui
+```
+
+State defaults to `${XDG_STATE_HOME:-~/.local/state}/agcoord`. Set
+`AGCOORD_STATE_DIR` or pass `--state-dir` to use a deliberate alternate spool.
+Machine capacity defaults to two concurrent job slots. Configure named resources before the
+broker starts with either `AGCOORD_CAPACITIES='jobs=4,cpu=8,browser=1'` or an equivalent JSON
+object.
+
+## Run work
+
+Submit focused checks with the resources they consume:
+
+```bash
+agcoord run --label "unit tests" --resource cpu=2 -- python -m pytest -q
+```
+
+Every job implicitly holds one `jobs` slot. Repeatable `--resource` options add only named,
+configured resources; unknown or impossible requests fail instead of waiting forever.
+
+Run a standalone full validation for an exact clean Git head when publication is not part of
+the request:
+
+```bash
+agcoord full --label "release gate" --resource cpu=4 -- ./scripts/test.sh
+```
+
+`full` records the checkout's full 40-character `HEAD`, checks that the worktree is clean,
+and establishes a barrier in that repository's lane. It remains useful for validation and
+release preparation, but normal landing does not compose a full row with a later publication
+row. It is not a machine-global lock: compatible work in other repositories can overlap when
+configured resource capacities allow it.
+
+After pushing the exact clean head and opening a pull request, gate and publish it as one
+indivisible request:
+
+```bash
+agcoord land 123 \
+  --label "gate and publish PR 123" \
+  --resource cpu=4 \
+  -- ./scripts/test.sh
+# GitHub is the convenience default and may also be named explicitly.
+agcoord land 123 --adapter github -- ./scripts/test.sh
+```
+
+`land` stores the adapter, request, exact checkout/head, gate command, caller environment,
+and resource claim in one durable repository barrier. The core record keeps adapter and
+request separate even though the current installed adapter uses GitHub pull-request numbers.
+It rejects a stale target before the gate, runs the gate once, and publishes immediately
+after a green result without releasing the lane or resources. A red gate publishes nothing.
+`--adapter github` is the default when the option is omitted; the core request remains
+forge-neutral.
+
+AGCoord never refreshes, rebases, or rewrites the checkout. If the source head or target
+branch moves before or during the gate, the same job ends with a named handback and does not
+publish. Update the branch yourself, push it, and submit a fresh `agcoord land` request; a
+separate full-plus-merge sequence is not a landing substitute.
+
+Inspect or manage jobs from any terminal:
+
+```bash
+agcoord list
+agcoord show land-0123456789ab
+agcoord log land-0123456789ab --follow
+agcoord cancel land-0123456789ab
+agcoord clear
+```
+
+`clear` removes terminal history and its logs only. It refuses while queued or running work
+exists and never removes the spool, broker ownership, or migration history.
+
+The full operating contract, recovery behavior, TUI keys, and resource model are in
+[the coordinator guide](docs/coordinator.md). Package maintainers should also read
+[the release guide](docs/releasing.md), and published user-facing changes are recorded in
+[the changelog](CHANGELOG.md). Contributors follow the repository workflow in
+[AGENTS.md](AGENTS.md).
+
+## Project status
+
+AGCoord targets distribution as the `agcoord` project on PyPI, with import package `agcoord`
+and both `agcoord` and `python -m agcoord` command forms. Until a release is published, build
+and install the checkout into an isolated environment rather than copying modules into
+another project.
+
+The gourd mascot and its asset notes live under [docs/assets](docs/assets/README.md).

agcoord-0.1.0/README.md

@@ -0,0 +1,111 @@
+# AGCoord
+
+![AGCoord gourd mascot](https://raw.githubusercontent.com/xu-hao/agcoord/main/docs/assets/agcoord-gourd-mascot.png)
+
+AGCoord is a machine-local coordinator for developers and coding agents that share a
+workstation. It gives every check, standalone full gate, and atomic gate-and-publication
+request one durable job ID, then schedules compatible work across repositories without
+letting two agents accidentally publish stale or untested code.
+
+The coordinator is local infrastructure: one detached broker per OS user, a private durable
+spool, per-job logs, and an optional terminal UI. It does not require a hosted service. The
+core package is forge-neutral; GitHub support is an optional adapter.
+
+## Install and start
+
+Install the published package in a tool environment:
+
+```bash
+python -m pip install agcoord
+```
+
+There is no separate service-install step. The first command starts the detached broker on
+demand; later shells and repositories join the same user-scoped coordinator:
+
+```bash
+agcoord list
+agcoord tui
+```
+
+State defaults to `${XDG_STATE_HOME:-~/.local/state}/agcoord`. Set
+`AGCOORD_STATE_DIR` or pass `--state-dir` to use a deliberate alternate spool.
+Machine capacity defaults to two concurrent job slots. Configure named resources before the
+broker starts with either `AGCOORD_CAPACITIES='jobs=4,cpu=8,browser=1'` or an equivalent JSON
+object.
+
+## Run work
+
+Submit focused checks with the resources they consume:
+
+```bash
+agcoord run --label "unit tests" --resource cpu=2 -- python -m pytest -q
+```
+
+Every job implicitly holds one `jobs` slot. Repeatable `--resource` options add only named,
+configured resources; unknown or impossible requests fail instead of waiting forever.
+
+Run a standalone full validation for an exact clean Git head when publication is not part of
+the request:
+
+```bash
+agcoord full --label "release gate" --resource cpu=4 -- ./scripts/test.sh
+```
+
+`full` records the checkout's full 40-character `HEAD`, checks that the worktree is clean,
+and establishes a barrier in that repository's lane. It remains useful for validation and
+release preparation, but normal landing does not compose a full row with a later publication
+row. It is not a machine-global lock: compatible work in other repositories can overlap when
+configured resource capacities allow it.
+
+After pushing the exact clean head and opening a pull request, gate and publish it as one
+indivisible request:
+
+```bash
+agcoord land 123 \
+  --label "gate and publish PR 123" \
+  --resource cpu=4 \
+  -- ./scripts/test.sh
+# GitHub is the convenience default and may also be named explicitly.
+agcoord land 123 --adapter github -- ./scripts/test.sh
+```
+
+`land` stores the adapter, request, exact checkout/head, gate command, caller environment,
+and resource claim in one durable repository barrier. The core record keeps adapter and
+request separate even though the current installed adapter uses GitHub pull-request numbers.
+It rejects a stale target before the gate, runs the gate once, and publishes immediately
+after a green result without releasing the lane or resources. A red gate publishes nothing.
+`--adapter github` is the default when the option is omitted; the core request remains
+forge-neutral.
+
+AGCoord never refreshes, rebases, or rewrites the checkout. If the source head or target
+branch moves before or during the gate, the same job ends with a named handback and does not
+publish. Update the branch yourself, push it, and submit a fresh `agcoord land` request; a
+separate full-plus-merge sequence is not a landing substitute.
+
+Inspect or manage jobs from any terminal:
+
+```bash
+agcoord list
+agcoord show land-0123456789ab
+agcoord log land-0123456789ab --follow
+agcoord cancel land-0123456789ab
+agcoord clear
+```
+
+`clear` removes terminal history and its logs only. It refuses while queued or running work
+exists and never removes the spool, broker ownership, or migration history.
+
+The full operating contract, recovery behavior, TUI keys, and resource model are in
+[the coordinator guide](docs/coordinator.md). Package maintainers should also read
+[the release guide](docs/releasing.md), and published user-facing changes are recorded in
+[the changelog](CHANGELOG.md). Contributors follow the repository workflow in
+[AGENTS.md](AGENTS.md).
+
+## Project status
+
+AGCoord targets distribution as the `agcoord` project on PyPI, with import package `agcoord`
+and both `agcoord` and `python -m agcoord` command forms. Until a release is published, build
+and install the checkout into an isolated environment rather than copying modules into
+another project.
+
+The gourd mascot and its asset notes live under [docs/assets](docs/assets/README.md).

agcoord-0.1.0/docs/assets/README.md

@@ -0,0 +1,6 @@
+# Asset sources
+
+[`agcoord-gourd-mascot.png`](agcoord-gourd-mascot.png) is the selected transparent RGBA gourd
+mascot used by the root README. Keep that canonical path stable. Any replacement must retain
+its editable source or generation record, license/provenance, and accessible description
+here rather than silently overwriting the published identity.