pi-claude-supervisor 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented here.
 
+## [0.9.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.8.1...v0.9.0) (2026-09-20)
+
+
+### Features
+
+* **supervisor:** publish a verified candidate under a narrow, one-shot remote grant ([5e117cc](https://github.com/btnalit/pi-claude-supervisor/commit/5e117cc5695492d03684270ea25cac224f1fe41e))
+
 ## [0.8.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.8.0...v0.8.1) (2026-09-20)
 
 

package/README.cn.md

@@ -208,6 +208,66 @@ stream-json` 的方式运行 Claude,完全没有终端界面;一旦设置
   不必等待完整的命令或模型超时。
 - 每个任务只持有一个 cwd 租约;并发任务需要各自独立的 worktree。
 
+## 发布已验证的候选
+
+默认情况下任务止于**已验证的本地候选**:验收与独立 Reviewer 通过,而 Worker 全程
+没有任何远程权限。设 `REMOTE_AUTHORITY=push`(或 `--remote push`)会在该判定之后
+加一个**发布阶段**:Supervisor 记下已验证的 commit,发放一次性的窄授权,并让
+Worker 推自己的分支;`pr` 还允许它开 PR。**push 由 Worker 自己执行**——Supervisor
+从不代劳——之后 Supervisor 以只读方式核实(`git ls-remote`,`pr` 还查 `gh pr list`)
+才把任务标记完成,候选通知里带上 PR 链接。核实不到则把候选标为 blocked,本地候选
+依然可交付。
+
+这个授权刻意严苛,而且两条命令都按字面匹配——没被审过的选项一律拒绝,而不是默认
+无害。它只认 `git -C '<任务目录>' -c core.hooksPath=/dev/null -c push.followTags=false push <remote> <已验证 commit>:refs/heads/<branch>`,
+不带其他任何选项。refspec 写的是**已验证的 commit** 而不是分支:git 只会推送这一个对象,
+Worker 在发布轮里再提交的内容会留在本地("Everything up-to-date"),搭不上这次授权。
+**`-C` 是必需的、必须是绝对路径、且必须与任务目录逐字节相同**——不做规范化、不做 realpath——因为 Claude 的 Bash 工具
+会在多次调用之间保留工作目录,而 `cd` 属于普通本地操作,没有 `-C` 的话授权可能被花在
+任何别的克隆上;任何更宽松的比较都出现过 Supervisor 与 git 解析不一致的写法(相对路径 `.` 按 Supervisor 的目录解析、`/proc/self/cwd`,以及 `<cwd>/link/..`——Node 自己的 realpath 会按字面折叠而内核会跟随 symlink)。指令写的就是精确目录,不需要接受任何别的写法。
+这条命令上**钉死了 hooks 路径**,所以 Worker 通过任何途径(`git init --template=`、
+解压归档、`chmod`)装进去的 `pre-push` hook 都不会在授权的 push 里以 Worker 的凭据执行;也钉死了
+`push.followTags=false`,所以通过策略看不见的任何文件设的 `followTags=true` 都不能让这一次 push
+顺带推上授权没点名的 tag(tag 正是发布自动化的触发点)。两者都是 ref/hook 选择而非传输层,不会
+覆盖任何合理的仓库级设置。
+`pr` 下另加 `gh pr create --repo <钉住的 remote URL> --head <候选分支> …`(只允许
+title / body / base / draft / assignee / label):PR 只会开在授权 remote 对应的仓库里——
+不带 `--repo` 的话,gh 会从 remotes 里自己挑一个 base 仓库(fork 上是 `upstream`),
+那不是授权点名的仓库,核实也不会去查它。仓库取 remote URL 背后的 `host/owner/repo`
+(SSH config 里的 host 别名会像 gh 那样经 `ssh -G` 翻译);URL 不是仓库的 remote(本地路径、
+翻译不了的别名)不会拿到 `pr` 授权。授权提供的每个词都做了 shell 引用,分支叫 `feat/$ticket`
+也能原样通过策略。
+
+授权只会发给"就是已验证工作树"的那个 commit:工作树必须干净(含未跟踪文件——新文件也可能
+是被验证行为的一部分),且 HEAD 自 Reviewer 评审的证据被读取以来没有移动过。仓库的 Git 目录必须是自己的 `.git` 或 linked worktree 的 `.git/worktrees/<name>`(不能是 `--separate-git-dir` 指针)。工作树不干净
+会先花一轮修复让 Worker 把属于候选的内容提交掉;只有修复轮用尽或 HEAD 移动过,任务才以本地
+候选结束并在通知里写明 `not published:` 原因,而不是发授权。核实时 remote 连不上,发布只是
+"未确认"(候选仍可交付),绝不会被说成"没推上去"。
+
+有没有授权都拒绝:任何 push 选项(`-u`、`--force`、`--force-with-lease`、`--delete`、
+`--mirror`、`--all`、`--tags`、`--no-verify`、`--push-option`、`--receive-pack` 等)、
+除这两个钉死项(且顺序固定)以外的任何 `-c`、以分支或 `HEAD` 作为 refspec 来源、裸 `git push`、
+别的 remote、分支或 commit、保护分支、被 shell 包装(含 heredoc 管进 shell)、带动态参数、
+第二条语句、不带 `-C` 的 `git push`、`-C` 与任务目录不逐字节相同(别的目录、相对路径、`/proc/self/cwd`、其中的 symlink 或 `..`)、不带
+`--repo <钉住的 URL>` 或不带 `--head <候选分支>` 的 `gh pr create`(被别的选项当作值吞掉的
+`--head` 不算)、`gh pr create --body-file/-F/--template`(会把任意本地文件内容发到 PR 上)、
+`--web`、别的 `--repo`、`gh pr merge`、`gh api`、`gh release`、`npm publish`。改动仓库
+remote(`git remote set-url|add|rename|…`,藏在 git 自己的 `--git-dir`/`--work-tree` 选项
+或 `remote` 自己的 `-v` 后面也一样)一律拒绝;改动 push 去向或 push 期间会执行什么也一律
+拒绝——`git config` 写 `remote.*`、`url.*.insteadOf`、`push.*`、`credential.*`、`http.*`、
+`include.path`/`includeIf.*`、`init.*`、`core.sshCommand`、`core.hooksPath`,`git config --edit`、
+`git init --template=…`、`git init|clone --separate-git-dir=…`,以及任何提到 `.git/config` 或 `.git/hooks` 的语句(除非它显然只读:
+`cat`、`grep`、`ls` 等)——否则授权认的 remote 会被偷换,连 Supervisor 的核实也会被骗过;
+核实同时钉住 fetch 和 push 两个 URL,并从自己的环境里剔除 `GIT_DIR`/`GIT_CONFIG_*`。这些文本规则之下还有一条不依赖它们的规则:remote 解析后的**全部** fetch/push URL(`git remote get-url --all` / `--push --all`;git 会推到每一个 `pushurl`,而不只是它打印的第一个;已应用改写)在任务**开始**、Worker 还没跑任何命令时记录,并在发放授权时和授权的 push 被批准的那一刻都要求原样不变。任务期间用任何手段(`~/.gitconfig`、脚本、策略看不见的 include)、哪怕在发布轮的第一条命令里加进来的 `pushInsteadOf`、`pushurl` 或额外目的地,都会让 push 被拒、授权作废;操作者原本就有的改写已在基线里,不受影响。恢复的任务沿用记录的基线、绝不重新采集;首次启动时解析不到的 remote 会被记录下来,永不授权。这是一层
+作用于命令文本的策略:Worker 自己写一个脚本再运行,策略看不见——如
+[autonomy-target.md](docs/autonomy-target.md) 对所有文本级规则所说,绝对隔离是 host 边界的事。
+
+授权是**一次性**的:发布轮一结束就收回(不等下一个决策),并且同时绑定 remote 的 URL
+而不只是名字。Worker 若在该轮里改动了工作树(未提交的修改同样算改动),授权立即作废并重新完整验收;因为授权写的是
+commit,通知能说清已验证的 commit 是否在工作树变动之前就已经推上去了。验证之前
+被拒的 push 会说明授权稍后会来,而不是让 Worker 去猜;没能确认发布的任务会在候选
+通知里写明原因,而不是只报一句 "ready"。
+
 ## 任务 spec
 
 `--spec file.json` 接受如下格式:
@@ -263,6 +323,8 @@ stream-json` 的方式运行 Claude,完全没有终端界面;一旦设置
 | `REQUIRE_LOCAL_COMMIT` | `true` | 完成前要求在候选所在分支上有本地 commit |
 | `MAX_DECISION_RETRIES` | `2`(0–10) | Decision Worker 调用超时或失败(429/529、网络、鉴权)时的重试次数 |
 | `PERMISSION_AUTHORITY` | `hybrid` | `policy` \| `hybrid` \| `decision-worker` |
+| `REMOTE_AUTHORITY` | `none` | `none` \| `push` \| `pr`;验收通过后开启发布阶段。`--remote` 可按任务覆盖 |
+| `REMOTE_NAME` | `origin` | 发布授权唯一允许的 remote 名 |
 | `WORKER_MAX_BUDGET_USD` | 未设置 | 作为 `--max-budget-usd` 传入的硬上限;交互式 tmux 下不可用 |
 | `WORKER_MODEL` | 未设置(Claude 自身默认值) | Claude Worker 的 `--model` |
 | `WORKER_AUTOCOMPACT_TOKENS` | 自动模式默认 `200000` | 每轮上下文上限;`0` 保留 Claude 自身默认值 |

package/README.md

@@ -255,6 +255,108 @@ Supervisor being able to see it, or when you don't need to attach.
 - Only one cwd lease is held per task; concurrent tasks need separate
   worktrees.
 
+## Publishing a verified candidate
+
+By default a task ends at a **verified local candidate**: acceptance and the
+independent Reviewer pass, and the Worker never had remote authority at any
+point. `REMOTE_AUTHORITY=push` (or `--remote push`) adds a **publish phase**
+after that verdict: the Supervisor records the verified commit, grants a narrow
+one-shot authority, and asks the Worker to push its own branch. `pr` also lets
+it open a pull request. The Worker performs the push — the Supervisor never
+does — and the Supervisor then confirms it read-only (`git ls-remote`, and
+`gh pr list` for `pr`) before completing the task; the candidate notice carries
+the pull request URL. A publish that cannot be confirmed blocks the candidate,
+which stays deliverable locally.
+
+The grant is deliberately unforgiving, and both commands are matched literally —
+an option nobody reviewed is refused rather than assumed harmless. It admits
+exactly `git -C '<task directory>' -c core.hooksPath=/dev/null -c push.followTags=false push <remote> <verified commit>:refs/heads/<branch>`,
+with no other option. The refspec names the **verified commit**, not the branch:
+git pushes exactly that object, so a commit the Worker makes during the publish
+turn stays local ("Everything up-to-date") instead of riding the grant. `-C` is
+**required, absolute and byte for byte the task directory** — no normalization,
+no realpath — because Claude's Bash tool keeps its working directory between
+calls and `cd` is ordinary local work, so without it the grant could be spent
+in any other clone, and every looser comparison had a spelling the Supervisor
+resolved one way and git another (`.` against the Supervisor's cwd,
+`/proc/self/cwd`, and `<cwd>/link/..`, which Node's own realpath collapses
+lexically while the kernel follows the link). The instruction spells the exact
+directory, so no other spelling is needed. The hooks path is **pinned** on that one command so no
+`pre-push` hook a Worker could have installed (by any door: `git init
+--template=`, an archive, a `chmod`) runs inside the granted push with the
+Worker's credentials, and `push.followTags=false` is pinned so a
+`followTags=true` set through any file the policy never sees cannot make the
+one push also plant a tag the grant never named (a tag is what release
+automation keys on). Both are ref and hook selection, not transport, so they
+override no legitimate per-repository setting. For `pr` a `gh pr create --repo <pinned remote URL>
+--head <candidate branch> …` limited to title, body, base, draft, assignee and
+label: the pull request opens in the granted remote's repository, full stop —
+without `--repo`, gh picks a base repository from the remotes (`upstream` on a
+fork) that the grant never named and the confirmation never reads. The
+repository is the `host/owner/repo` behind the remote's URL (an SSH-config host
+alias is translated through `ssh -G`, as gh does); a remote whose URL is not
+one — a local path, an alias with no translation — gets no `pr` grant. Every
+word the grant supplies is shell-quoted, so a branch named `feat/$ticket` still
+round-trips through the policy.
+
+The grant is only issued for a commit that *is* the verified tree: the working
+tree must be clean (untracked files included — a new file may be part of the
+verified behavior), and HEAD must not have moved since the evidence the Reviewer
+judged was read. The repository's Git directory must be its own `.git` or a linked worktree's
+`.git/worktrees/<name>` (not a `--separate-git-dir` pointer). A dirty tree first costs a repair round asking the Worker to
+commit what belongs to the candidate; only when none is left, or when HEAD
+moved, does the task end at the local candidate with a `not published:` reason
+instead of a grant. A remote that cannot be reached at confirmation time leaves
+the publish *unconfirmed* (the candidate stays deliverable), never "refuted".
+
+Refused with or without a grant: every push option (`-u`, `--force`,
+`--force-with-lease`, `--delete`, `--mirror`, `--all`, `--tags`, `--no-verify`,
+`--push-option`, `--receive-pack`, …), any `-c` but the two pins (in that order), a
+branch or `HEAD` as the refspec source, a bare `git push`, another remote,
+branch or commit, a protected branch, a shell wrapper (`sh -c`, and a heredoc
+piped into a shell), a dynamic word, a second statement, `git push` without
+`-C`, a `-C` that is not the task directory byte for byte (another directory, a
+relative path, `/proc/self/cwd`, a symlink or `..` inside it),
+`gh pr create` without `--repo <pinned URL>` or without `--head <candidate
+branch>` (a `--head` swallowed as another option's value does not count),
+`gh pr create --body-file/-F/--template` (which would post the contents of an
+arbitrary local file), `--web`, another `--repo`, `gh pr merge`, `gh api`,
+`gh release` and `npm publish`. Changing the repository's remotes (`git remote
+set-url|add|rename|…`, behind git's own `--git-dir`/`--work-tree` options or
+`remote`'s own `-v` too) is denied outright, and so is reconfiguring where a
+push goes or what runs during it — `git config` writes to `remote.*`,
+`url.*.insteadOf`, `push.*`, `credential.*`, `http.*`, `include.path`/
+`includeIf.*`, `init.*`, `core.sshCommand` or `core.hooksPath`, `git config
+--edit`, `git init --template=…`, `git init|clone --separate-git-dir=…`, and any statement that names `.git/config` or
+`.git/hooks` unless it plainly only reads (`cat`, `grep`, `ls`, …) — so the
+granted remote cannot be repointed underneath the confirmation, which pins both
+the fetch and the push URL and scrubs `GIT_DIR`/`GIT_CONFIG_*` from its own
+environment. Behind all of that sits one rule the text guards do not need:
+the remote's resolved fetch and push URLs — **every** one of them
+(`git remote get-url --all` / `--push --all`; git pushes to each `pushurl`,
+not only the first it prints), rewrites applied — are recorded when the task
+**starts**, before the Worker runs a command, and required unchanged both
+when the grant is issued *and* at the moment the granted push is authorized.
+So a `pushInsteadOf`, `pushurl` or extra destination added during the task by
+*any* means (`~/.gitconfig`, a script, an include the policy never saw), even
+as the first command of the publish turn, refuses the push and revokes the
+grant, while an operator's pre-existing rewrite, already in the baseline, is
+not. A recovered task keeps its recorded baseline and never takes a new one;
+a remote that could not be resolved at the first start is recorded as such and
+never granted. This is a policy over the command text: a script the Worker writes
+and runs is outside what it can see, as [autonomy-target.md](docs/autonomy-target.md)
+says of every text-level rule; absolute isolation is the host boundary's job.
+
+The grant is **one-shot**: it is revoked the moment the publish turn completes,
+not when the next decision arrives, and it is pinned to the remote's URL as well
+as its name. A Worker that changes the tree during that turn voids it and is
+re-verified in full — an edit left uncommitted counts as a change, exactly like a new
+commit; because the grant named the commit, the notice can say whether the
+verified commit landed before the tree moved on. Before verification a refused push says the grant is coming
+rather than leaving the Worker to guess, and a task that ends without a
+confirmed publish says so in its candidate notice instead of reporting a bare
+"ready".
+
 ## Task specs
 
 `--spec file.json` accepts:
@@ -311,6 +413,8 @@ Environment variables (or `~/.config/pi-claude-supervisor/env`), all prefixed
 | `REQUIRE_LOCAL_COMMIT` | `true` | Require a local commit on the candidate's branch before completion |
 | `MAX_DECISION_RETRIES` | `2` (0–10) | Retries of a Decision Worker call that times out or fails (429/529, network, auth) |
 | `PERMISSION_AUTHORITY` | `hybrid` | `policy` \| `hybrid` \| `decision-worker` |
+| `REMOTE_AUTHORITY` | `none` | `none` \| `push` \| `pr`; grants the publish phase after verification passes. `--remote` overrides it per task |
+| `REMOTE_NAME` | `origin` | The single remote a publish grant may name |
 | `WORKER_MAX_BUDGET_USD` | unset | Hard cap passed as `--max-budget-usd`; unavailable to interactive tmux |
 | `WORKER_MODEL` | unset (Claude's own default) | `--model` for the Claude Worker |
 | `WORKER_AUTOCOMPACT_TOKENS` | `200000` in automatic mode | Per-turn context bound; `0` keeps Claude's own default |

package/docs/architecture.md

@@ -440,6 +440,51 @@ derives from this task's cwd, which rejects a subagent transcript and any path
 naming another project. A root is honored before it exists (Claude creates the
 memory directory on first write) and through a symlinked ancestor.
 
+When a task is granted remote authority (`autonomy.remoteAuthority`, default
+`none`), verification does not end it. `#requestPublish` first checks that
+HEAD *is* the verified tree — the evidence the Reviewer judged shows a clean
+working tree and carries the same `head` — then issues a `RemoteGrant` naming
+that commit, the candidate's own branch, the remote, the task directory and the
+remote's repository (`host/owner/repo` from its fetch URL, an SSH alias
+translated through `ssh -G`), and asks the Worker to publish: the Worker runs
+the push and any `gh pr create`, the Supervisor never does. A dirty tree costs a
+repair round first, the remote's resolved URL lists (`get-url --all`, both sides) must equal the baseline recorded at task start (`TaskContext.remoteBaseline`, persisted with the decision session, restored on recovery, never re-taken) — checked again by `#grantedRemoteChanged` at the moment a granted command is authorized, in both the PreToolUse and prompt-phase paths — the Git directory must be the task's own `.git` or a linked worktree's, and the reviewed evidence must carry a
+HEAD (fail-closed); the grant is armed before the instruction is sent and
+revoked only if the send failed before delivery (the turn counter tells). The instruction is built
+by `publishCommand`/`pullRequestCommand` in `policy.ts`, beside the parser that
+admits it, and a test round-trips one through the other. Under every permission
+authority the granted command is answered by the policy (`PolicyResult.granted`)
+rather than escalated to the Decision Worker. The returning turn skips
+acceptance and the Reviewer when HEAD is unchanged — they already passed on that
+tree — and `#settlePublish` confirms the result read-only (`#confirmPublish`:
+both pinned remote URLs unchanged, `git ls-remote` carrying the verified commit,
+plus `gh pr list` for `pr`) before completing, or blocks the candidate when it
+cannot; that candidate keeps `deliverable: true`, since it passed and is intact
+on its branch, and an unreachable remote is reported as *unconfirmed*
+(`RemoteBranchLookup` tells `absent` from `unreachable`), never as a missing
+commit or a repointed remote. A tree that changed during the publish turn — an uncommitted edit included — voids
+the grant and is re-verified in full, with the same confirmation deciding whether the notice
+says the verified commit landed first. The grant is cleared on every terminal
+path, so it never outlives the turn it was issued for, and
+`permittedRemoteCommand` admits a single literal shape —
+`git -C '<task dir>' -c core.hooksPath=/dev/null -c push.followTags=false push <remote> <commit>:refs/heads/<branch>`
+with no other option, and `gh pr create --repo <pinned URL> --head <branch> …`
+— so no force, delete, mirror, tags, push-options, other `-c`, branch or `HEAD`
+source, other remote, branch or repository, relative `-C`, shell wrapper,
+dynamic word or second statement; the pinned hooks path keeps any installed
+`pre-push` out of the granted command and the pinned `push.followTags=false` keeps any tag out of it. `git config` writes to
+transport-affecting keys (including `include.*` and `init.*`), `git config
+--edit`, `git init --template`, and any statement naming `.git/config` or
+`.git/hooks` in any spelling (`namesGitMetadata` normalizes the path and matches a glob segment by segment, so only a
+segment that could expand to `.git` counts — a project's own `src/hooks/` is ordinary work) that does not plainly only read are refused alongside `git remote`
+mutations; git's own `--git-dir`/`--work-tree` options and `remote`'s own `-v`
+cannot hide either, nor can `-C /proc/self/cwd` or `-C <cwd>/link/..` (the directory must be the granted one byte for byte; every realpath comparison elsewhere uses the native implementation, since Node's JavaScript `realpathSync` collapses `link/..` lexically) or `--separate-git-dir`. The publish
+hint keys on `PolicyResult.boundary`, not on the reason text, and promises a publish turn
+only where `#requestPublish` will start one. For an adopted tmux session the memory write root is
+located under the *adopted process's* configuration directory, read from
+`/proc/<pid>/environ` at adoption, so a Claude started with another
+`CLAUDE_CONFIG_DIR` keeps its memory.
+
 A record left behind by the outright
 stop (`recoverable_failure`, so `active/interrupted`) is not a dead end either:
 `recover --extend <duration>` re-persists a deadline measured from now

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {

package/src/acceptance.ts

@@ -1,10 +1,11 @@
+import { isPlainRemoteName } from "./policy.ts";
 import type { AcceptanceCheck, TaskSpec } from "./types.ts";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_MAX_REPAIR_ROUNDS = 3;
 
 /** Normalize legacy plain-text tasks into the structured acceptance model. */
-export function normalizeTaskSpec(value: unknown, fallbackGoal: string): TaskSpec {
+export function normalizeTaskSpec(value: unknown, fallbackGoal: string, autonomyDefaults?: Partial<TaskSpec["autonomy"]>): TaskSpec {
   if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
     throw new Error("task spec must be a JSON object");
   }
@@ -18,7 +19,7 @@ export function normalizeTaskSpec(value: unknown, fallbackGoal: string): TaskSpe
     forbidden: stringList(source.forbidden, "forbidden"),
     acceptance: normalizeChecks(source.acceptance),
     maxRepairRounds: normalizeRepairRounds(source.maxRepairRounds),
-    autonomy: normalizeAutonomy(source.autonomy),
+    autonomy: normalizeAutonomy(source.autonomy, autonomyDefaults),
   };
 }
 
@@ -84,23 +85,32 @@ function normalizeRepairRounds(value: unknown): number {
   return value;
 }
 
-function normalizeAutonomy(value: unknown): TaskSpec["autonomy"] {
-  if (value === undefined) return { unattended: true, requireLocalCommit: true, maxDecisionRetries: 2, permissionAuthority: "hybrid" };
+function normalizeAutonomy(value: unknown, defaults?: Partial<TaskSpec["autonomy"]>): TaskSpec["autonomy"] {
+  // A spec file that omits a key — or the whole block — must not silently
+  // override the operator's environment defaults with hardcoded ones;
+  // `defaults` carries them in and every key falls back to it.
+  if (value === undefined) return normalizeAutonomy({}, defaults);
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("task spec autonomy must be an object");
   const source = value as Record<string, unknown>;
   if (source.unattended !== undefined && typeof source.unattended !== "boolean") throw new Error("task spec autonomy.unattended must be boolean");
   if (source.requireLocalCommit !== undefined && typeof source.requireLocalCommit !== "boolean") throw new Error("task spec autonomy.requireLocalCommit must be boolean");
-  const retries = source.maxDecisionRetries ?? 2;
+  const retries = source.maxDecisionRetries ?? defaults?.maxDecisionRetries ?? 2;
   if (typeof retries !== "number" || !Number.isSafeInteger(retries) || retries < 0 || retries > 10) throw new Error("task spec autonomy.maxDecisionRetries must be between 0 and 10");
-  const authority = source.permissionAuthority ?? "hybrid";
+  const authority = source.permissionAuthority ?? defaults?.permissionAuthority ?? "hybrid";
   if (authority !== "policy" && authority !== "hybrid" && authority !== "decision-worker") throw new Error("task spec autonomy.permissionAuthority must be policy, hybrid or decision-worker");
-  const maxWorkerCostUsd = source.maxWorkerCostUsd;
+  const remoteAuthority = source.remoteAuthority ?? defaults?.remoteAuthority ?? "none";
+  if (remoteAuthority !== "none" && remoteAuthority !== "push" && remoteAuthority !== "pr") throw new Error("task spec autonomy.remoteAuthority must be none, push or pr");
+  const remoteName = source.remoteName ?? defaults?.remoteName ?? "origin";
+  if (!isPlainRemoteName(remoteName)) throw new Error("task spec autonomy.remoteName must be a plain remote name");
+  const maxWorkerCostUsd = source.maxWorkerCostUsd ?? defaults?.maxWorkerCostUsd;
   if (maxWorkerCostUsd !== undefined && (typeof maxWorkerCostUsd !== "number" || !Number.isFinite(maxWorkerCostUsd) || maxWorkerCostUsd <= 0)) throw new Error("task spec autonomy.maxWorkerCostUsd must be a positive number");
   return {
-    unattended: source.unattended !== false,
-    requireLocalCommit: source.requireLocalCommit !== false,
+    unattended: (source.unattended ?? defaults?.unattended) !== false,
+    requireLocalCommit: (source.requireLocalCommit ?? defaults?.requireLocalCommit) !== false,
     maxDecisionRetries: retries,
     permissionAuthority: authority,
+    remoteAuthority,
+    remoteName,
     ...(maxWorkerCostUsd !== undefined ? { maxWorkerCostUsd } : {}),
   };
 }

package/src/config.ts

@@ -1,8 +1,9 @@
 import { chmodSync, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { isPlainRemoteName } from "./policy.ts";
 import { redactSensitive } from "./redaction.ts";
-import type { PermissionAuthority } from "./types.ts";
+import type { PermissionAuthority, RemoteAuthority } from "./types.ts";
 
 const allowed = new Set([
   "PI_CLAUDE_SUPERVISOR_MODE",
@@ -43,6 +44,8 @@ const allowed = new Set([
   "PI_CLAUDE_SUPERVISOR_DEADLINE_GRACE_MS",
   "PI_CLAUDE_SUPERVISOR_DEADLINE_WARNING_MS",
   "PI_CLAUDE_SUPERVISOR_NO_OUTPUT_TIMEOUT_MS",
+  "PI_CLAUDE_SUPERVISOR_REMOTE_AUTHORITY",
+  "PI_CLAUDE_SUPERVISOR_REMOTE_NAME",
 ]);
 
 export interface AutonomyDefaults {
@@ -50,6 +53,8 @@ export interface AutonomyDefaults {
   requireLocalCommit: boolean;
   maxDecisionRetries: number;
   permissionAuthority: PermissionAuthority;
+  remoteAuthority: RemoteAuthority;
+  remoteName: string;
   maxWorkerCostUsd?: number;
 }
 
@@ -59,6 +64,8 @@ export function autonomyDefaults(env: NodeJS.ProcessEnv = process.env): Autonomy
     requireLocalCommit: readBoolean(env.PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT, true),
     maxDecisionRetries: readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES, 2, 0, 10),
     permissionAuthority: readPermissionAuthority(env.PI_CLAUDE_SUPERVISOR_PERMISSION_AUTHORITY),
+    remoteAuthority: readRemoteAuthority(env.PI_CLAUDE_SUPERVISOR_REMOTE_AUTHORITY),
+    remoteName: readRemoteName(env.PI_CLAUDE_SUPERVISOR_REMOTE_NAME),
     ...(readPositiveNumber(env.PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD) !== undefined ? { maxWorkerCostUsd: readPositiveNumber(env.PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD) } : {}),
   };
 }
@@ -231,6 +238,25 @@ function readTrimmedString(value: string | undefined): string | undefined {
   return trimmed ? trimmed : undefined;
 }
 
+/** Remote authority never defaults on: an unset or unrecognised value keeps the Worker local. */
+function readRemoteAuthority(value: string | undefined): RemoteAuthority {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === undefined || normalized === "" || normalized === "none") return "none";
+  if (normalized === "push" || normalized === "pr") return normalized;
+  // A typo must not silently switch the publish phase off: a task would then
+  // end at a bare "candidate is ready" with no shortfall to explain it.
+  throw new Error(`PI_CLAUDE_SUPERVISOR_REMOTE_AUTHORITY must be none, push or pr: ${value?.trim()}`);
+}
+
+function readRemoteName(value: string | undefined): string {
+  const trimmed = value?.trim();
+  if (trimmed === undefined || trimmed === "") return "origin";
+  // A typo must not silently redirect where a publish goes; the spec validator
+  // throws for the same input, so this fails the same way instead of guessing.
+  if (!isPlainRemoteName(trimmed)) throw new Error(`PI_CLAUDE_SUPERVISOR_REMOTE_NAME must be a plain remote name: ${trimmed}`);
+  return trimmed;
+}
+
 function readPermissionAuthority(value: string | undefined): PermissionAuthority {
   const normalized = value?.trim().toLowerCase();
   return normalized === "policy" || normalized === "decision-worker" ? normalized : "hybrid";

package/src/decision-session-store.ts

@@ -5,6 +5,17 @@ import { redactSensitive } from "./redaction.ts";
 import { normalizeTaskSpec } from "./acceptance.ts";
 import type { TaskSpec } from "./types.ts";
 
+/**
+ * Two lists of URL strings and nothing else; a persisted baseline is data the
+ * grant trusts, so its shape is checked. Empty lists are valid: they record
+ * that the remote had no URL when the task started, which refuses a grant.
+ */
+function isRemoteBaseline(value: unknown): value is { fetch: string[]; push: string[] } {
+  const urls = (list: unknown): list is string[] => Array.isArray(list) && list.length <= 32 && list.every((entry) => typeof entry === "string" && entry.length > 0 && entry.length <= 4_096);
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    && urls((value as { fetch?: unknown }).fetch) && urls((value as { push?: unknown }).push);
+}
+
 export type DecisionRecoveryState = "ready" | "starting" | "registered" | "recovered_idle" | "interrupted";
 
 export interface DecisionRecoveryWorker {
@@ -29,6 +40,8 @@ export interface DecisionSessionRecord {
   startedAt: string;
   baseCommit?: string;
   baseBranch?: string;
+  /** The granted remote's resolved URLs when the task first started; the publish grant requires the same two. */
+  remoteBaseline?: { fetch: string[]; push: string[] };
   /** Real executable identity pinned by automatic startup and recovery. */
   resolvedExecutable?: string;
   turn: number;
@@ -408,6 +421,7 @@ function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: strin
     || (value.workerCostUsd !== undefined && (typeof value.workerCostUsd !== "number" || !Number.isFinite(value.workerCostUsd) || value.workerCostUsd < 0))
     || (value.baseCommit !== undefined && (typeof value.baseCommit !== "string" || !/^[0-9a-f]{40,64}$/iu.test(value.baseCommit)))
     || (value.baseBranch !== undefined && (typeof value.baseBranch !== "string" || !/^[A-Za-z0-9._/-]+$/u.test(value.baseBranch)))
+    || (value.remoteBaseline !== undefined && !isRemoteBaseline(value.remoteBaseline))
     || (value.resolvedExecutable !== undefined && (typeof value.resolvedExecutable !== "string" || !isAbsolute(value.resolvedExecutable) || value.resolvedExecutable.length > 4_096))
     || (value.startedAt !== undefined && (typeof value.startedAt !== "string" || !Number.isFinite(Date.parse(value.startedAt))))
     || (value.recoveryWorker !== undefined && !isRecoveryWorker(value.recoveryWorker))) {
@@ -439,6 +453,7 @@ function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: strin
     startedAt: value.startedAt ?? value.updatedAt,
     ...(typeof value.baseCommit === "string" ? { baseCommit: value.baseCommit } : {}),
     ...(typeof value.baseBranch === "string" ? { baseBranch: value.baseBranch } : {}),
+    ...(isRemoteBaseline(value.remoteBaseline) ? { remoteBaseline: { fetch: [...value.remoteBaseline.fetch], push: [...value.remoteBaseline.push] } } : {}),
     ...(typeof value.resolvedExecutable === "string" ? { resolvedExecutable: value.resolvedExecutable } : {}),
     turn: value.turn ?? 0,
     repairRound: value.repairRound ?? 0,

package/src/decision-worker.ts

@@ -294,12 +294,13 @@ Maximum automatic turns: ${context.maxTurns}
 Current repair round: ${context.repairRound ?? 0}
 ${deadlineInstructions(context.deadline)}Task specification: ${boundedJson(context.spec ?? { goal: context.task })}
 
-Return exactly one JSON object and no markdown:
+${remoteAuthorityInstructions(context.spec)}Return exactly one JSON object and no markdown:
 {"action":"continue|redirect|answer|allow_permission|deny_permission|verify|retry|stop|park|wait|noop",...}
 For continue/redirect/answer include message and reason. For permission actions include
 requestId and toolUseId. Retry may include a corrective message. Never choose allow_permission
-for a command that crosses the remote push or main/integration merge boundary; the deterministic
-policy will deny it.
+for a command that crosses the remote push or main/integration merge boundary unless the task's
+publish phase has granted it; the deterministic policy is the authority either way and will deny
+anything outside the grant.
 For AskUserQuestion, choose deny_permission when the question can be converted into ordinary
 Claude text, then use answer on the resulting turn. For product ambiguity or an architecture
 choice, inspect the repository and task evidence, select the best task-compatible option, state
@@ -321,6 +322,18 @@ interrupt it, and the Supervisor asks you again if the Worker has not resumed wi
 timeout. A completed turn or a permission request always requires a concrete action.${deadlinePolicy(context.deadline)}`;
 }
 
+/**
+ * The publish phase exists only when the task was given remote authority. The
+ * Decision Worker has to know it is coming, or it reads the Supervisor's own
+ * publish instruction as an unexplained extra turn.
+ */
+function remoteAuthorityInstructions(spec: TaskSpec | undefined): string {
+  const authority = spec?.autonomy.remoteAuthority ?? "none";
+  if (authority === "none") return "";
+  const what = authority === "pr" ? "push the candidate branch and open a pull request" : "push the candidate branch";
+  return `Publish phase: this task may ${what} once its acceptance checks and the independent Reviewer have passed. The Supervisor issues that grant itself and asks the Worker to publish; you do not need to request it. When the Worker reports back from that turn, choose verify — the Supervisor confirms the remote rather than re-running the checks. Remote authority never extends to a merge, a force-push, a tag or a release.\n\n`;
+}
+
 function deadlineInstructions(deadline: DecisionDeadlineContext | undefined): string {
   if (!deadline) return "";
   const closeOut = deadline.graceMs > 0

package/src/hooks/relay.ts

@@ -1,5 +1,6 @@
 import { BLOCKING_HOOK_EVENTS, HOOK_TIMEOUT_SECONDS } from "./types.ts";
 import { nodeScriptCommand } from "../worker/runtime.ts";
+import { shellQuote } from "../policy.ts";
 
 /**
  * Plain JavaScript (no TypeScript syntax), executed by Claude Code as a hook
@@ -185,7 +186,3 @@ export function hookRelayCommand(relayPath: string): string {
   return `${shellQuote(nodeScriptCommand())} ${shellQuote(relayPath)}`;
 }
 
-function shellQuote(value: string): string {
-  if (/^[A-Za-z0-9_.\/-]+$/u.test(value)) return value;
-  return `'${value.replace(/'/gu, "'\\''")}'`;
-}

package/src/index.ts

@@ -7,7 +7,7 @@ import { chmod, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs
 import { EventLog } from "./events.ts";
 import { redactSensitive } from "./redaction.ts";
 import { ProcessWorkerAdapter } from "./worker/process-adapter.ts";
-import { automaticWorkerEnvironment } from "./worker/environment.ts";
+import { automaticWorkerEnvironment, claudeConfigDir } from "./worker/environment.ts";
 import { TmuxWorkerAdapter, attachCommand, sweepDeadTmuxSockets } from "./worker/tmux-adapter.ts";
 import { Supervisor, extendedDeadlineMs, type DecisionSessionClosedInfo, type HumanInterventionNotice, type SupervisorProgress, type SupervisorTokenUsage } from "./supervisor.ts";
 import { evaluateCommand } from "./policy.ts";
@@ -29,7 +29,7 @@ import type { TaskSpec, WorkerHandle } from "./types.ts";
 const RELAY_HOOK_MARKER = "/hooks/relay.js";
 
 function claudeUserSettingsPath(): string {
-  return join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"), "settings.json");
+  return join(claudeConfigDir(), "settings.json");
 }
 
 /** `src/hooks/install.ts` does not export its relay-script writer; this mirrors it for an owned launch's static relay path. */
@@ -371,11 +371,15 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
         if (operation === "start" || operation === "adopt-tmux") {
           const specPath = takeOption(rest, "--spec");
           const deadlineOption = takeOption(rest, "--deadline");
+          const remoteOption = takeOption(rest, "--remote");
+          if (remoteOption !== undefined && !["none", "push", "pr"].includes(remoteOption)) throw new Error(`--remote expects none, push or pr: ${remoteOption}`);
           const taskDeadlineMs = deadlineOption === undefined ? deadlineMs() : parseTaskDeadline(deadlineOption);
           const tmuxSession = operation === "adopt-tmux" ? rest.shift() : undefined;
           const task = rest.join(" ").trim();
           const fileSpec = specPath ? await readTaskSpecFile(specPath, ctx.cwd) : undefined;
           const spec = fileSpec ?? { autonomy: autonomyDefaults() };
+          // An explicit --remote overrides both the spec file and the env default.
+          if (remoteOption) spec.autonomy = { ...spec.autonomy, remoteAuthority: remoteOption as "none" | "push" | "pr" };
           const goal = fileSpec?.goal ?? task;
           // Adopted sessions are explicit manual compatibility controls; they
           // never enter the automatic Reviewer/decision loop, even when the
@@ -384,7 +388,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           // own events through hooks exactly like an owned one.
           const taskAutomation = (operation !== "adopt-tmux" || tmuxMode() === "interactive") && automation && spec.autonomy.unattended;
           const interactive = taskAutomation && adapter.capabilities().transport === "tmux" && tmuxMode() === "interactive";
-          if (!goal) throw new Error(operation === "adopt-tmux" ? "Usage: /supervise adopt-tmux [--spec <file>] [--deadline <duration>] <tmux-session> <task>" : "Usage: /supervise start [--spec <file>] [--deadline <duration>] <task>");
+          if (!goal) throw new Error(operation === "adopt-tmux" ? "Usage: /supervise adopt-tmux [--spec <file>] [--deadline <duration>] [--remote none|push|pr] <tmux-session> <task>" : "Usage: /supervise start [--spec <file>] [--deadline <duration>] [--remote none|push|pr] <task>");
           if (operation === "adopt-tmux" && adapter.capabilities().transport !== "tmux") throw new Error("/supervise adopt-tmux requires PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux");
           if (operation === "adopt-tmux" && interactive && !await userHooksInstalled(claudeUserSettingsPath())) {
             await hookServerReady?.catch(() => {});
@@ -530,6 +534,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                     startedAt: info.startedAt,
                     ...(info.baseCommit ? { baseCommit: info.baseCommit } : {}),
                     ...(info.baseBranch ? { baseBranch: info.baseBranch } : {}),
+                    ...(info.remoteBaseline ? { remoteBaseline: info.remoteBaseline } : {}),
                     ...(info.resolvedExecutable ? { resolvedExecutable: info.resolvedExecutable } : {}),
                     turn: info.turn,
                     repairRound: info.repairRound,
@@ -808,6 +813,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 startedAt: record.startedAt,
                 baseCommit: record.baseCommit,
                 baseBranch: record.baseBranch,
+                remoteBaseline: record.remoteBaseline,
                 initialTurn: record.turn,
                 initialRepairRound: record.repairRound,
                 initialFindingSignature: record.lastFindingSignature,
@@ -832,6 +838,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                     startedAt: info.startedAt,
                     ...(info.baseCommit ? { baseCommit: info.baseCommit } : {}),
                     ...(info.baseBranch ? { baseBranch: info.baseBranch } : {}),
+                    ...(info.remoteBaseline ? { remoteBaseline: info.remoteBaseline } : {}),
                     ...(info.resolvedExecutable ? { resolvedExecutable: info.resolvedExecutable } : {}),
                     turn: info.turn,
                     repairRound: info.repairRound,
@@ -1010,7 +1017,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           } else if (operation === "resume-auto") {
             await session.resumeAutomation(); message = `Automatic decisions resumed: ${sessionId}.`;
           } else {
-            throw new Error("Usage: /supervise start [--spec <file>] [--deadline <duration>]|adopt-tmux [--spec <file>] [--deadline <duration>]|recover [--takeover] [--extend <duration>]|discard <task-id>|sessions|status|poll [all|taskId]|send [taskId]|pause [taskId]|resume [taskId]|stop [taskId]|verify [taskId]|approve [taskId] <allow|deny>|takeover [taskId]|resume-auto [taskId]|capabilities|install-hooks|uninstall-hooks");
+            throw new Error("Usage: /supervise start [--spec <file>] [--deadline <duration>] [--remote none|push|pr]|adopt-tmux [--spec <file>] [--deadline <duration>] [--remote none|push|pr]|recover [--takeover] [--extend <duration>]|discard <task-id>|sessions|status|poll [all|taskId]|send [taskId]|pause [taskId]|resume [taskId]|stop [taskId]|verify [taskId]|approve [taskId] <allow|deny>|takeover [taskId]|resume-auto [taskId]|capabilities|install-hooks|uninstall-hooks");
           }
         }
         if (hookInstallNotice) { notify(ctx, hookInstallNotice); hookInstallNotice = undefined; }
@@ -1184,7 +1191,9 @@ function selectedWorkerEnvironment(automatic = false): NodeJS.ProcessEnv {
 async function readTaskSpecFile(path: string, cwd: string): Promise<TaskSpec> {
   const file = resolve(cwd, path.replace(/^['"]|['"]$/gu, ""));
   const value = JSON.parse(await readFile(file, "utf8")) as unknown;
-  return normalizeTaskSpec(value, "");
+  // A spec that omits an autonomy key inherits the operator's environment
+  // default for it, the way a plain-text task does.
+  return normalizeTaskSpec(value, "", autonomyDefaults());
 }
 
 function parseCommand(value: string): string[] {

package/src/notifications.ts

@@ -99,7 +99,7 @@ function toGeneric(notice: HumanInterventionNotice | CandidateNotice): Record<st
     question: sanitize(notice.question),
     permission: notice.permission ? sanitize(notice.permission) : undefined,
     ...(notice.attach ? { attach: sanitize(notice.attach) } : {}),
-    ...(candidate ? { status: notice.status, deliverable: notice.deliverable, ...(notice.usage ? { usage: usageSummary(notice.usage) } : {}) } : { actions: ["approve_or_deny_permission", "send_instruction", "stop_worker", "takeover"] }),
+    ...(candidate ? { status: notice.status, deliverable: notice.deliverable, ...(notice.prUrl ? { prUrl: sanitize(notice.prUrl) } : {}), ...(notice.usage ? { usage: usageSummary(notice.usage) } : {}) } : { actions: ["approve_or_deny_permission", "send_instruction", "stop_worker", "takeover"] }),
     note: candidate
       ? "This is an optional candidate notification. It does not grant remote push or main/integration merge permission."
       : "This is an outbound notification. Use the Pi session or a separately authenticated callback service to approve actions.",
@@ -111,6 +111,9 @@ function toWeCom(notice: HumanInterventionNotice | CandidateNotice): Record<stri
   const permission = notice.permission ? `\n工具: ${safeText(notice.permission.toolName)}\n请求 ID: ${safeText(notice.permission.requestId)}` : "";
   const question = notice.question ? `\n问题: ${safeText(notice.question)}` : "";
   const attach = notice.attach ? `\n接入: ${safeText(notice.attach)}` : "";
+  // Not Markdown-escaped: `escapeMarkdown` would turn an `_` in the org or
+  // repository name into `\_` and break the link. The URL is already sanitized.
+  const pullRequest = "status" in notice && notice.prUrl ? `\nPR: ${safeText(notice.prUrl)}` : "";
   const title = candidate ? "Claude Supervisor 候选状态" : "Claude Supervisor 需要人工介入";
   const usage = candidate && notice.usage ? `\n> Worker 费用: $${notice.usage.workerCostUsd.toFixed(2)} (${notice.usage.workerTurns} turns)\n> Pi tokens: ${usageSummary(notice.usage).piTokens}` : "";
   const suffix = candidate
@@ -119,7 +122,7 @@ function toWeCom(notice: HumanInterventionNotice | CandidateNotice): Record<stri
   return {
     msgtype: "markdown",
     markdown: {
-      content: `### ${title}\n> 任务: ${safeText(notice.task)}\n> Task ID: ${safeText(notice.taskId)}\n> 原因: ${safeText(notice.reason)}${escapeMarkdown(question)}${escapeMarkdown(permission)}${escapeMarkdown(attach)}${suffix}`,
+      content: `### ${title}\n> 任务: ${safeText(notice.task)}\n> Task ID: ${safeText(notice.taskId)}\n> 原因: ${safeText(notice.reason)}${escapeMarkdown(question)}${escapeMarkdown(permission)}${escapeMarkdown(attach)}${pullRequest}${suffix}`,
     },
   };
 }