ags-cli

ags-cli 是 AGS 的本地 git / filtered gh 启动器。普通 Human 与 Multica Agent 只面向 AGS；Forgejo/GitLab credential、repository/PR mapping、CI observation 与 merge execution 由 AGS 服务端 provider adapter 拥有。Human 另有一个有界的仓库初始化入口；它不进入 Multica workload 命令面。

普通使用面

Human / Agent -> ags-cli git / ags-cli pr -> AGS -> server-owned provider adapter
Human         -> ags-cli repo create    -> AGS repo + configured Forgejo projection

公开 root 只保留：

ags-cli --version
ags-cli git <git argv...>
ags-cli pr <accepted pr argv...>
ags-cli gh <accepted gh argv...>
ags-cli repo create <owner/repo> [--description <text>] [--json]

ags-cli pr 与 ags-cli gh pr 共用同一 registry / native REST / effect 路径。repo create只读取当前Context拥有的Human credential，创建私有、main、带初始README的AGS仓，并等待配置好的Forgejo exact-SHA投影；检测到Multica task token时在credential和network I/O前拒绝。维护面需显式进入 ags-cli ctl ...，不属于普通 Agent 心智。旧 ci|review|profile|grant|session|access|principal-session public roots已hard-cut。

当前 gh-core-v1 接受：

pr create/view/checks/list/status/comment/edit/review/close/reopen/update-branch/merge
run list/view

未知命令、flag 或 JSON field 在 engine、credential 与 provider I/O 前拒绝；不回退系统 gh。

Caller 与 credential

Human

repo 内命令从 credential-free AGS origin 解析唯一 Context。目标状态每个 AGS instance 只需要：

~/.ags-cli/contexts/<context>.yaml   # secret-free route
~/.ags-cli/secrets/<context>.token  # personal Human AGS token; regular file, non-symlink, mode 0600
~/.ags-cli/config.yaml              # optional machine preferences; regular file, non-symlink, mode 0600

config.yaml当前只接受以下schema；文件可不存在，旧config/current-context不会读取或隐式迁移：

schema: ags.cli-config.v1
default_context: mini-local

Human repo命令按以下规则路由：不传--repo时由credential-free origin唯一解析Context，单独传--context只断言该origin结果；显式--repo不传--context时使用default_context；显式--repo + --context时直接选择命名Context，因此同名repo也可在多个AGS之间切换。repo外命令必须传--repo，可再用--context覆盖default。Multica workload不接受Human --context，仍只由workspace + endpoint匹配Context，且不读取config.yaml。

ags-cli pr list --repo jackie/agent-kit --context mini-imile-win
ags-cli pr list --repo ux/merdi-express-shipping --context imile-win-local

Human ordinary Git/PR 不创建 Access Grant 或 transport Session。每次 PR write/merge 前都向 AGS /api/v3/user 回读并要求 user_kind=human；repository permission、protected branch 与 effect gate 仍由 AGS 校验。

安全路由诊断不读 credential 文件，也不发网络请求：

ags-cli context current --json name,serverUrl,route,repository,identity

该命令只报告 Context endpoint、origin/current 路由、repository、Context-owned canonical human-facing URLs 和 caller identity mode；Human 与 workload 都明确输出 credentialRead=false，不声称已验证 live login、权限或网络可达性。

Human在repo外可用当前Context创建团队仓库：

ags-cli repo create ux/repo-flow \
  --description "RepoFlow CLI and workflow assets" \
  --json

命令只提交一次AGS create请求；已存在或响应不确定时先做exact readback，不盲重试。--json输出ags.repo-create.v1嵌套事实：repository/git/forgejo/readback，含正整数IDs、secret-free URL、private/main/40位SHA、forgejo.state=linked|pending|failed和projection drift。AGS clone/html URL必须属于当前Context endpoint或已声明alias，且不得携带query/fragment。linked还要求投影target等于请求仓、投影双SHA等于branch readback、以及必要URL。缺少仓库ID或默认分支SHA时fail-closed。Forgejo由AGS当前integration配置自动创建和投影，CLI只等待并验证main同SHA；超时返回已创建但未linked的部分结果及非零退出码。

现有 interactive_default profile 只作为有界迁移兼容：仅当 Context-owned token 不存在且该 Context 恰有一个兼容 profile 时读取。新安装不得创建 Human profile；repo 内 authority 不依赖 global current-context。

Multica workload

存在 MULTICA_TOKEN 时强制 profile-free：

required  MULTICA_TOKEN + origin/Context + workspace/agent/task binding
optional  MULTICA_RUN_ID
forbidden Human token/profile、provider token/profile、mixed durable selector

内部 Access Grant / Session 只负责短时 AGS transport，不进入 Agent 命令面。Task在worktree外启动clone时，以MULTICA_WORKSPACE_ID + MULTICA_SERVER_URL只读匹配唯一受信Context，不读取或切换Human current-context；零匹配或多匹配均fail closed。普通 Access Grant HTTP请求只对HTTP 503或Node transport exception做一次有界、无状态重试；pr.merge effect 的transport失败保持outcome-unknown并只走invocation readback，绝不自动重发POST。401/403/422、invalid response与authority denial不重试，也不切换endpoint或credential。standard operation 与association分离：纯External PR/link association unavailable不改写已完成operation；但Task的request-level AGS transport未绑定时，任何broker error都必须在stock-gh engine前停止，禁止无凭据落到Provider默认路由。Invalid credential、wrong target/repo/operation、identity binding missing/conflict、revoked/expired authority与protected/effect denial均fail closed。

Git credential helper

ags-cli ctl runtime bootstrap 安装薄 git/gh shim 与generic credential helper。git shim对Human单次命令先清空system/keychain helper链，再绑定!ags-cli ctl git-credential和credential.useHttpPath=true；存在MULTICA_TOKEN时则改走exact repo/operation的Access Grant transport，clone从credential-free AGS URL解析repo，其他命令从origin解析。Task transport取得失败立即停止，不再执行plain system Git，也不读取Human helper。

Human workstation若绕过shim直接调用system Git，必须按每个Context endpoint做URL-scoped reset，避免系统keychain先返回同host旧凭据，同时不影响GitHub等其他host：

git config --global credential.useHttpPath true
git config --global --replace-all 'credential.http://127.0.0.1:6666.helper' ''
git config --global --add 'credential.http://127.0.0.1:6666.helper' '!ags-cli ctl git-credential'

helper 按 Git protocol + host + owner/repo path匹配唯一Context。Context 以 endpoint 为权威 AGS 基址，可选 endpoint_aliases 接纳短名等同 host（例如 MagicDNS 权威地址加 http://mini:6666）；匹配到后仍用 endpoint 访问 AGS API。不持久化store，也不使用global current-context。别名必须写在 Context 里，且跨 Context 必须唯一。Context还可在ags.context-bundle.v2中用secret-free provider_public_urls.<provider>固定人类可见provider origin；CLI优先使用该值，缺失时才用所选Context的稳定instance_id精确选择target registry中的provider publicUrl，缺失或歧义时保留服务端URL。Provider origin不从AGS主机名猜测。

Multica daemon在Task process tree内检查完整shim pair：~/.ags-cli/shims/git与gh（Windows可为.exe/.cmd/.bat launcher）都存在才前置PATH；若~/.local/bin/ags-cli存在，managed bin紧随shims进入PATH，避免shim解析到陈旧Volta等tool-manager link；缺任一个shim则保持原PATH，避免Git与PR使用不同身份。该注入属于Task环境边界，不依赖Pi/Codex/Claude插件，也不永久替换普通Human shell的官方gh。

PR write 与 provider effect

• Human pr create/comment/edit/review/close/reopen：origin-bound Context personal token只请求 AGS REST。pr create 成功后 stdout 先打 Forgejo PR URL（给人看），再打 AGS locator；--json 另有 forgejo_url / forgejo_number。Agent 日常仍以 AGS PR 号做事，但要把 Forgejo URL 报给 Human。
• Workload 同一命令：exact standard operation通过内部 Access Grant transport请求 AGS。
• pr view <ags-pr> --json ...：精确编号 JSON read 走 AGS-native REST；缺失 -R 且当前目录没有 credential-free AGS origin 时，在 credential/network I/O 前失败。--json 接受 externalProjections。Human与workload路由的顶层url都按本次选中的Context endpoint规范化；externalProjections[].externalUrl优先使用该Context的provider_public_urls，再按Context instance_id精确绑定target registry中的provider publicUrl。该策略只改写human-facing URL，不改变请求所用Context endpoint、Access Grant route或authority；它不读取global default target、不接受ambient URL覆盖，也不猜测跨主机projection。externalProjections[] 暴露 Forgejo 投影 status=pending|projected|failed|conflict、jobId、attempt、稳定 public URL 和 lastError。0 条 Forgejo mapping 是 pending，不是缺失 mapping；2+ 条是 conflict。statusCheckRollup与pr checks在投影已 projected 后复用同一份 exact-head provider evidence；投影 pending 时 pr checks 返回 projection_pending（exit 8），冲突返回 mapping_conflict（exit 1），都不把 0 行和 2 行收成同一句 exception。externalProjections还为每个投影附加consistency=consistent|stale|optional、requiredForMerge和affectsMergeReadiness。Forgejo是当前merge projection；其它provider mismatch标成optional，不由客户端臆测为merge blocker。Merge 在投影 required 且尚未 projected 时继续 fail-closed。
• pr checks / run list / run view：从 AGS provider-evidence 读 Forgejo CI。check JSON显式提供required和requirementSource；--required仅在所有run都有服务端required事实时过滤，事实缺失或不完整时fail closed，绝不把全部checks当required。run view <run-id> --pr <ags-pr> --log / --log-failed再读.../provider/ci/runs/{id}/logs。客户端不直连Forgejo、不猜AGS/Forgejo号相同。
• Human pr merge --match-head-commit <sha> [--merge-method <method>]：请求 AGS provider merge endpoint；AGS解析provider coordinate并使用server-owned executor。method完整覆盖merge|rebase|rebase-merge|squash|fast-forward-only；既有--merge/--rebase/--squash保持兼容，但不得与--merge-method混用。省略时保持merge默认值。非法、重复或冲突选择在credential/network I/O前拒绝。
• Workload merge：必须有服务端返回的effective pr.merge maintainer authority，走独立effect endpoint；generic Session transport禁止merge。

AGS source write成功与provider projection状态分开。provider pending/drift不得回滚已成功的AGS branch/PR，也不得伪装为caller permission denial。

Engine 与发布 pin

生产 package 只从 <packageRoot>/libexec/ags-gh 定位 engine，并用同包 release-manifest.json 同时校验：

• platform launcher SHA-256；
• launcher内固定的darwin-arm64与linux-amd64 engine SHA-256；
• registry/gh-core-v1.registry.json SHA-256。

当前平台不受支持或任一drift都在authority broker或engine执行前fail closed。仅测试/源码集成可同时设置 AGS_GH_ALLOW_MANIFEST_OVERRIDE=1 与显式 engine/manifest override；生产不得设置。

当前 package 版本与 source commit 以同目录 package.json 和 dist/build-info.json 为准，不在 README 再写易漂移的 current version。远端 ctl repo 委派以调用方本机已验证的 full build-info identity 与 CLI 实际 SHA-256 为信任根；AGS_CLI_EXPECTED_SOURCE_COMMIT 只能附加校验该本机 identity，不能单独授权委派。0.2.8已修复live F01/F12发现的带端口GH_HOST、fresh bootstrap目录权限与ambient system/keychain helper问题，并在mini完成published-package验证；随后F10在imile-win发现单一Mach-O engine无法在Linux执行。0.2.9保留受pin的platform launcher，打包并逐次校验darwin-arm64与linux-amd64 engine，并给单次隔离GH配置写入当前schema version，阻止Linux误探测ambient keyring。0.2.10进一步把Task的broker denial/conflict/target mismatch收紧为engine前hard failure，同时保留typed unavailable的无ambient credential association语义。source_verified只证明本仓测试与package assembly；在clean source publish、目标Runtime安装和完整live matrix evidence完成前，不声明ags-single-frontdoor-ready。

Bootstrap

ags-cli ctl runtime bootstrap --plan --json
ags-cli ctl runtime bootstrap --json
ags-cli ctl runtime inspect --json

Bootstrap只创建本地目录、薄git/gh shim和generic helper，不创建config.yaml、身份、不签发credential、不配置provider，也不检测或推荐任何coding-agent插件。不创建~/.ags-cli/bin/ags-cli第二 command path。ctl install在安装manifest Context后原子写入config.yaml的default_context。Task PATH由Multica等Runtime统一管理。

Command launcher

全局ags-cli唯一 PATH 入口是~/.local/bin/ags-cli（ags-cli.launcher.v1）。默认 exec 本机 single-active npm release：~/.local/share/ags-cli/current/bin/ags-cli。调试源码用环境变量，不要换第二命令名：

export AGS_CLI_DEV=1
export AGS_CLI_SOURCE_ROOT=/path/to/agent-kit   # bun run $AGS_CLI_SOURCE_ROOT/packages/ags-cli/src/cli.ts
# 或
export AGS_CLI_ENTRY=/path/to/agent-kit/packages/ags-cli/src/cli.ts

未设置AGS_CLI_DEV/AGS_CLI_ENTRY时必须走 npm 字节。AGS_CLI_DEV已开但缺 source root/entry 时 fail closed，不得静默落到陈旧 checkout。

Endpoint installer使用隐藏维护面，不恢复已经hard-cut的旧top-level命令：

ags-cli ctl release inspect --json
ags-cli ctl release install-current --user --json
ags-cli ctl release capabilities --json
ags-cli ctl context provision --mode plan --name <name> --file <bundle> --source-sha <sha> --json
ags-cli ctl context doctor --name <name> --json

ctl release install-current只安装当前exact npm package，写入single-active/previous状态并保持~/.local/bin/ags-cli为稳定launcher；endpoint rollout不得用浮动tag或普通npm -g安装替代。Context迁移仍要求显式--expected-current-hash。

Maintainer Forgejo authority

隐藏维护面正式入口是 ags-cli ctl repo onboard-forgejo 与 ags-cli ctl repo verify。公开 ordinary root 仍只有 repo create、git、pr、gh。operator credential 继续来自 target file paths，命令不接受也不打印 token 值。

维护面 onboarding 若收敛 Forgejo base protection，当前 desired 是 enable_push=true、enable_force_push=false，push/merge whitelist 全关（空名单、apply_to_admins=false）。不把 Human 从已有名单剥掉，也不再要求 exact-only-bot。反例 enable_push=false 仍会围栏 AGS projection writer。未显式覆盖时，apply/verify 保留已观察的全部 non-authority review/security gates。书面裁决见 ../../docs/adr/practice-alignment/2026-09-03-forgejo-open-whitelists.md。本段不把该能力提升为普通 Agent 命令面。AGS /readyz 仍用 runtime 自己的谓词。

Release

不要在功能 PR 里改 package.json 的 version。先写 pending changeset，release 分支再 prepare：

bun run --filter @yoyooyoooyoooo/ags-cli release add -- --kind patch --summary "..."
bun run --filter @yoyooyoooyoooo/ags-cli release prepare
bun run --filter @yoyooyoooyoooo/ags-cli release pack
bun run --filter @yoyooyoooyoooo/ags-cli release publish
bun run --filter @yoyooyoooyoooo/ags-cli release verify

只发 https://registry.npmjs.org/。已存在的 version 不得覆盖。publish 仍要本机 TTY + 浏览器 web auth，不是 GitHub Actions trusted publishing。约定见 ../../.changesets/README.md。

Claim limit

本README声明当前source contract：Context-owned Human credential、profile compatibility boundary、workload isolation、accepted filtered surface与server-owned provider execution。它不声明任意AGS/provider自动可用，也不把source tests冒充mini/imile runtime、clean release、provider health或完整cross-runtime claim。