bounded retrying multi-repo push and publish (knit)

docs/reference.md

@@ -607,7 +607,7 @@ knit pull --rebase frontend
 
 Single-bundle pulls still default to the original repo path on the recorded base branch with `git pull --ff-only`, updating the recorded `baseSha`, and refuse on uncommitted changes unless `--force` (use `--rebase` for `git pull --rebase`). Use `knit pull --feature` to pull the tracked Knit feature checkout instead; feature pulls are recorded as `git.observed` nodes when the feature branch head moves.
 
-`knit push` pushes tracked feature branches to `origin`. It does not create PRs, update GitHub metadata, or change bundle state. Selected repo pushes run in parallel; bundle artifact and history sync wait until every Git push succeeds. By default it pushes the current feature branch to `origin/<branch>` without setting upstream; use `--set-upstream` when you want git's upstream tracking configured:
+`knit push` is the branch-only path: it pushes tracked feature branches to `origin` and nothing else — no PRs, no GitHub metadata, no bundle state change. For the review path, go straight from `knit commit` to `knit publish create`, which pushes the branches itself. Selected repo pushes run in parallel, at most `KNIT_GIT_JOBS` (default 8) at a time; bundle artifact and history sync wait until every Git push succeeds. By default it pushes the current feature branch to `origin/<branch>` without setting upstream; use `--set-upstream` when you want git's upstream tracking configured:
 
 ```sh
 knit push
@@ -616,6 +616,10 @@ knit push --all
 knit push --set-upstream frontend
 ```
 
+Each `git push` is bounded: it is killed after `KNIT_GIT_PUSH_TIMEOUT` seconds (default 300), so a stalled connection cannot hold the command open, and a push that lost its connection is retried up to three times. A push the remote answered — rejected, non-fast-forward, stale lease, refused credentials — fails immediately, because repeating it only earns the same answer. Repos that fail are listed at the end and the command exits non-zero; the run keeps going for the other repos, and re-running pushes only what is still missing.
+
+Fan-out limits and retries are tunable through the environment: `KNIT_GIT_JOBS` (concurrent git pushes, default 8), `KNIT_FORGE_JOBS` (concurrent forge writes, default 4), `KNIT_GIT_PUSH_TIMEOUT` (seconds per push, default 300), and `KNIT_RETRY_BASE_MS` (backoff step, default 1000). Each must be a positive whole number; a value that is not is an error rather than a silently ignored setting.
+
 `knit publish` publishes tracked feature branches to a code host. Knit is host-independent: it detects each repo's host from its git remote. GitHub uses `gh`, GitLab uses `glab`, Codeberg/Forgejo uses `tea` plus REST for richer metadata, and Bitbucket Cloud uses its REST API. Unrecognized remotes retain the historical GitHub fallback.
 
 ```sh
@@ -632,7 +636,7 @@ knit publish status
 
 `knit publish create` auto-detects each repo's host (GitHub, GitLab, Forgejo/Codeberg, or Bitbucket) and publishes to all of them. Pass `--provider <id>` (or the `--github` shorthand) to restrict a run to repos on a single host. `knit request` is an alias for `knit publish`.
 
-`knit publish create` is a best-effort two-phase operation. It pushes every selected tracked feature branch, creates missing review objects (PRs/MRs) or reuses an existing one for the same feature/base branch, stores publishing metadata in the bundle's `publications`, then rewrites the managed Knit block in every selected review body with the complete cross-repo list. The base defaults to each repo's bundle `baseBranch`; pass `--base release` to use the same base for every selected repo, or repeat `--base repo=branch` for per-repo bases. That target is recorded with the publication. A later native `knit land --target <branch>` can deliberately replace those recorded review bases as part of its landing contract. Body sync is on by default; `--sync` is accepted for explicitness, and `--no-sync` skips that second phase. If body sync fails after review objects were created, run `knit publish sync` after fixing auth or network issues.
+`knit publish create` is a best-effort two-phase operation and the whole review path after `knit commit`; it does its own branch push, so no separate `knit push` is needed. Repos are published at most `KNIT_FORGE_JOBS` (default 4) at a time, forge calls that fail because the host was momentarily unavailable (5xx, a rate limit honoring `Retry-After`, a dropped connection) are retried up to four times with 1s/2s/4s backoff, and calls the host answered (bad credentials, 404, 422) fail at once. A repo whose publish fails does not stop the others: every repo is reported, the command exits non-zero listing the failures, and re-running creates only what is missing — a repo whose review object already exists is adopted rather than duplicated. It pushes every selected tracked feature branch, creates missing review objects (PRs/MRs) or reuses an existing one for the same feature/base branch, stores publishing metadata in the bundle's `publications`, then rewrites the managed Knit block in every selected review body with the complete cross-repo list. The base defaults to each repo's bundle `baseBranch`; pass `--base release` to use the same base for every selected repo, or repeat `--base repo=branch` for per-repo bases. That target is recorded with the publication. A later native `knit land --target <branch>` can deliberately replace those recorded review bases as part of its landing contract. Body sync is on by default; `--sync` is accepted for explicitness, and `--no-sync` skips that second phase. If body sync fails after review objects were created, run `knit publish sync` after fixing auth or network issues.
 
 For a named lane, select it through Knit itself. The generated plan records `lane`, immutable `targetBranches`, and whether the lane is `terminal`; apply retargets each open review object to its mapped branch, refreshes readiness, merges, and runs that lane's deployments. An intermediate lane like `staging` leaves the bundle open afterwards:
 
@@ -866,7 +870,7 @@ Sparse advice is enabled by default for new workspaces. It prints a `Next:` line
 - Worktree creation relies on `git worktree add` and inherits its constraints, including branch checkout conflicts.
 - `knit fetch` fetches the `origin` remote for each selected repo. Repos without `origin` are reported as failures.
 - `knit pull` coordinates ordinary git pulls but does not resolve merge/rebase conflicts across repos. If git stops for a conflict, resolve that repo's git state before retrying.
-- `knit push` pushes feature branches to `origin` and, when sync remotes are configured and `push-sync` is enabled, the bundle artifact to those remotes; use `knit publish create` to publish review objects.
+- `knit push` pushes feature branches to `origin` and, when sync remotes are configured and `push-sync` is enabled, the bundle artifact to those remotes; it opens no review objects, so use `knit publish create` (which pushes the branches itself) for the PR path.
 - `knit publish` detects GitHub, GitLab, Codeberg/Forgejo, and Bitbucket Cloud from each repo remote; unrecognized remotes default to GitHub for compatibility. GitLab and Forgejo keep their CLI paths for the basic workspace loop and use REST for granular CI, review state, mergeability, SHA guards, and retargeting. Without a Forgejo REST token, those richer fields degrade to empty/unknown and the basic `tea` loop remains available. Bitbucket does not expose pre-merge conflict state, so conflicts surface as merge API errors. Bitbucket and Forgejo have no provider-native revert-PR API; GitHub and GitLab do.
 - `knit publish create` is not perfectly transactional. Branch pushes, review creation, and body updates happen sequentially. If phase two fails after review objects are created, run `knit publish sync`.
 - `knit land` resolves the host adapter per repo from its remote. A merge lands into the recorded base branch. Remote merges cannot be automatically unmerged by Knit, so failed land runs are recorded in `.knit/land-runs/`; fix the failed step and use `knit land resume`, or use `knit land rollback` to open revert PRs for the steps that already merged.

src/commands/agents.rs

@@ -104,9 +104,14 @@ Bundle-scoped Knit commands resolve this bundle automatically from this cwd:
 knit status
 knit add
 knit commit --all -m "Describe the feature change"
-knit push --set-upstream
+knit publish create
 ```
 
+`knit publish create` pushes every tracked feature branch itself and then opens
+one review object (PR/MR) per repo, so committing and publishing is the whole
+path to review. Use `knit push --set-upstream` only when you want the branches
+on `origin` without review objects.
+
 {teamwork_section}
 Before editing a path that may have cross-repo coupling, ask Knit which prior bundle work touched it:
 

src/commands/init.rs

@@ -633,7 +633,8 @@ For a one-step stage and commit:
 knit --bundle feature-a commit --all -m "Describe the feature change"
 ```
 
-Push the bundle's feature branches after committing:
+Push the bundle's feature branches without opening review objects (the PR path
+below pushes them itself, so this is only for branch-only work):
 
 ```sh
 knit --bundle feature-a push --set-upstream
@@ -649,8 +650,10 @@ knit --bundle feature-a sync pull --history
 ```
 
 Publish review objects (PRs/MRs) against their intended base branch. `create`
-auto-detects each repo's host; pass `--github` (or `--provider <id>`) to limit
-to one host. `knit request` is an alias for `knit publish`:
+pushes each feature branch itself, so the review path is commit then publish —
+no separate `knit push` step. It auto-detects each repo's host; pass `--github`
+(or `--provider <id>`) to limit to one host. `knit request` is an alias for
+`knit publish`:
 
 ```sh
 knit publish create
@@ -770,7 +773,7 @@ knit cherrypick --from feature-a --repo backend abc123
 - `knit sync push [--bundles|--history|--views|--architecture|--kg|--all] [--remote <name>]...` is the one verb family for moving artifacts to the sync remotes; with no target flag it pushes bundle, history, views, and architecture. The often-large knowledge-graph slice moves only with explicit `--kg`. Bundle push is project-wide: every local bundle artifact — open, landed, archived — is swept so remote lifecycle state converges on the local ledger. Pushing an open bundle always means branches + artifact: missing or stale feature branches are pushed to git `origin` first, and a bundle whose branches cannot be pushed or verified is skipped with a warning.
 - `knit sync pull [--bundles|--history|--views|--architecture|--kg|--all] [--remote <name>]...` pulls those same artifacts from the sync remotes. Bundle pull is project-wide: open bundles created on other machines (and their recorded PRs) are localized into `.knit/bundles/`, and stale local artifacts fast-forward whatever their state; materialize checkouts for a discovered bundle with `knit --bundle <slug> bundle worktree`.
 - `knit pull --merge` union-merges the bundle ledger when the local and remote artifacts have diverged (two users recorded work concurrently); diverged feature branches still need a git merge in the worktree afterwards.
-- `knit push --set-upstream` pushes every tracked feature branch in the resolved bundle to `origin` and sets upstream tracking.
+- `knit push --set-upstream` pushes every tracked feature branch in the resolved bundle to `origin` and sets upstream tracking; it opens no review objects, so use `knit publish create` (which pushes too) for the PR path.
 - `knit push --remote hosted` pushes the resolved bundle's branches and artifact to the configured sync remote so it is visible in hosted dashboards.
 - `knit git --all status --short` runs Git across tracked checkouts.
 - `knit clean --archived --worktrees` removes generated worktrees left behind by archived or landed bundles whose normal cleanup did not remove them.