镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/role-pool.md ↗

Role-Pool and task coordination

Tasks retain goals, criteria, candidates and final delivery authority. New work always uses the project Manager without changing its existing queue, GitHub event entry points, policy validation or publisher. Saved coordination switches no longer select the route for new work; QA always runs as a recorded role with a fresh evaluation context.

Configuration and execution

GET/PUT /api/repositories/:repository/roles uses existing project administration grants; the console Roles page and later management entry points call the same service. A PUT carries expected_revision (the current revision, 0 before the first save) and the full RoleDefinitionV2 configuration:

{"expected_revision":3,
 "controller":{"role":"manager"},
 "skills":[{"id":"review-kit","source":{"type":"repository","commit":"<40-hex sha>","paths":[".agents/skills/review/SKILL.md"]}}],
 "roles":[{"role_id":"reviewer","harness_ref":{"id":"process"},"model_profile_ref":{"model_id":"<model id>"},"skill_bundle_ref":{"id":"review-kit"},"persona_prompt":"Focus on input boundaries."}]}

Each role has role_id, revision, name, responsibility, the complete editable persona prompt, flat permissions and fixed-version references: model_profile_ref, skill_bundle_ref, harness_ref, environment_profile_ref, budget_policy_ref and output_schema_ref. Omitted roles keep their saved definitions; new roles receive individual default permissions and an editable prompt template. deleted_roles explicitly removes roles, including Dev, Test, Reviewer and UX; Manager, Coordinator and QA cannot be deleted or disabled. Deleted roles are not recreated by later saves. Stage requirements referencing a deleted role must be adjusted in the same save. A save is validated field by field; an error returns its code and the failing field, for example roles.reviewer.harness_ref.id. A stale expected_revision returns 409. Each save becomes an immutable revision; ?revision=N returns an older one. A role's own revision moves only when its definition changes.

Existing builtin / source.playbooks bindings reopen as console files using the exact stored bodies, paths, file hashes and bundle revision/hash; source.origin records the original source, revision and hash. Reopening does not rewrite immutable revisions or audit snapshots. Saving creates an ordinary inline revision with that provenance; unchanged later saves reuse it. Old clients can resave only the same already-bound names from their saved files; new or changed built-in sources return retired_skill_source and must use repository or inline files. No historical catalog is consulted. Frozen task configurations retain their original files and hashes; new role runs project their source as inline. Sessions whose old snapshots advertised retired tools rebuild the same role instance from task facts, leaving old snapshots readable. A surviving old Pi request advertising those tools is stopped before provider access and follows normal workspace/checkpoint recovery. Legacy selections and read events remain historical facts, never live runtime guidance.

Models resolve in order: the role's explicit profile, then the work type's model (task_models), then the project default. POST .../roles/resolve previews the exact run snapshot without storing anything or creating a task. A run stores its snapshot by content hash (role_snapshots, also readable as task source role_snapshots:<hash>): actual model id/version/name and its source, skill files and hashes, harness id/version and runtime package, effective permissions and tools, environment, budget and output schema. Old stored policy references convert to editable permissions and complete prompt templates on read; historical revisions and execution snapshots are not rewritten.

The role detail's Agent/model section can check a selected work type against the saved role configuration, including custom types already present in the project model map. It shows the model's source and record version, backend, role/configuration versions and resolution identifier; selecting reserved subscription mode reports subscription_mode_not_implemented without substituting another model. This read does not submit the editable draft, persist a snapshot or start a task. Switching work type clears the previous result, and failures show an unknown result instead of substituting another model. A changed configuration revision requires refreshing/comparing the shared draft. Existing runs remain explained by their stored snapshots; the preview of a legacy developer role also distinguishes its role definition from the Pi override still used by development entry points until its backend selection changes.

New development, ordinary request, review and Actions analysis tasks run under the project controller with its selected backend. Development and ordinary requests use Manager → selected role runs → nominated delivery → independent QA → existing delivery/publisher. Review and Actions failure analysis retain their entry-specific tools, workspace and completion as the dev assignment, using that role's configured backend subject to the old-V2 compatibility rule below; the controller delegates it, reads its result by reference and nominates it, and the existing publication and QA follow. Each attempt records a controller_entry event with the configuration revision. Historical execution snapshots retain their original route, id, contract, candidate and history; other work types keep their established executor.

Ordinary task workers receive read_managed_task, but not create_task, manage_task or list_managed_tasks. The Manager and entries explicitly granted delegation: allow retain those management tools; QA and Coordinator task entries do not offer them. A live worker run may read its own assignment and related parent, child or sibling task evidence, but the assignment alone never grants writes to that task, even if the worker has delegation permission. Writes require task ownership or the live controller's own assignment. The trusted legacy employee-conversation adapter retains its owner-scoped API compatibility; task runs always carry their source task and cannot use that entry. Existing task origins, frozen role snapshots and audit records are not rewritten. On reuse, a worker session that advertised the retired default management tools is rebuilt from retained task facts, including retiring any surviving Pi mailbox.

The controller runs on its configured backend. Pi sessions use an empty workspace on the project computer and forward only the offered tools to the control plane. Native/Process use the same controller tools and result validators through their own runtime. Each run is bounded; a role backend cannot grant itself product or publication tools. It only has task record, progress, bound Skill and delegation tools, and, while the task holds no worktree, the workspace choice tools (list_workspaces, use_workspace, create_workspace; see task workspace cleanup), all executed by the control plane through the runner's control mailbox. It cannot edit product files, run commands, publish, accept, complete, override QA, merge or grant permissions. A call to any other tool, delegation to QA, the controller itself or an unoffered role, and a delegation carrying extra fields (tools, models, permissions) are refused and recorded as capability_denied. Prompts, repository content and CLI output cannot change these checks. nominate_delivery selects the latest dev output for QA; it does not change task status to completed. Custom roles follow the observer result contract. Dev is the only writable role; observers receive separate disposable checkouts of a fixed dev snapshot. Their command side effects do not become the delivery tree. Each formal QA evaluation is fresh, even though its role instance and previous evidence remain queryable.

Console presentation

The project navigation places 「角色」 immediately after 「机器配置」. Its secondary navigation starts with an editable overview, then lists every role. The overview edits role names, enabled state, Agent backend, model, skills and individual permissions; each role page adds responsibility, persona instructions, model protocol, environment, budget and output settings. Skill bundles, custom observer roles and required stages also have forms. There is no JSON configuration editor. Switching role pages preserves the draft; saving checks the configuration revision and keeps the draft on a conflict. Saved backend choices are preserved, while an unsaved project shows the recommended Pi defaults. The Manager role page edits the complete event-dispatch prompt and its model, and lists recent decisions and task rule sources. Project-wide event subscriptions and review/development admission belong to the separate 「监听与触发」 settings page; the Manager role page links there without duplicating its controls. Each role page shows the common read-only system prompt (service background, environment and basic conduct) and one fully editable role prompt. Existing fixed duties and task-record rules migrate into that prompt once, preserving project instructions. Saving or clearing it replaces the complete role guidance; runtime entry code does not append hidden duties. Editable project rule files, output language and work prompts remain available as task context. A role can be added, deleted or restored from a template using forms; only Manager, Coordinator and QA are protected. The Manager event-dispatch call uses the same role prompt and its editable event instructions.

Each work type's row on the same page names who executes it from the same configuration, with the roles its entry actually offers. A task's detail opens with one sentence on who is doing what now, directly under its title on every screen width; a running QA run (role: qa, status: running in the task's runs) is named as such whatever the task's phase, since development and review start QA from inside their executor; the acceptance phase alone is not taken as QA running. The side panel then shows the goal, candidate, evidence, acceptance and publication from the task record, and the delegations actually recorded: GET /api/tasks/:id/roles is read until next_after is null, purposes come from role_handoff events, and each delegation shows the harness of every run that executed it and, for a project's own role, the name and responsibility from the snapshot its latest run started with, so a later rebinding or redefinition of the role does not rewrite the past. Only a delegation that has not run yet uses the instance's current snapshot; when its run has no readable snapshot (role_snapshot may be null), the historical definition is marked unavailable instead of being filled from today's. If a page cursor stops advancing, the next step says the records are incomplete and how many were read, and names no role, controller, executor or QA unless a running QA run was read; the delegations read so far are listed under the same warning. Nothing there is inferred from the Manager prompt; a task that did not run under the controller says it ran on the original executor.

Revisions of running roles

A running run keeps the snapshot it started with. The next assignment of an instance resolves the current revision first and records role_revision_applied (reason: delegation). To move a running role, POST /api/tasks/:id/roles/apply with role and expected_revision marks the instance: at its next safe checkpoint (a turn boundary where every tool result is recorded) the run ends with role_revision_checkpoint, and the same task, instance and assignment continue on the new revision (reason: checkpoint, naming the ended run). Old runs remain explainable through their snapshot and the stored configuration revision. Revocation is live: disabling a role or narrowing its permissions stops the next capability call with role_authority_revoked; project disablement and model withdrawal stop runs as before.

Shared handoff and continuing context

The default editable role templates recommend task-first collaboration: query the contract, candidate and relevant records before starting/resuming; record factual results and next actions; prefer references to duplicated prose; distinguish claims from observations and decisions; keep unknowns explicit; never persist private reasoning.

delegate_role carries purpose and record references. It returns a role result source, not a copied report. read_task_record supports paged original task-history sources, task:<this task id>, and the current contract:revision:<n>. Invalid references return correctable tool errors. History, source and run routes remain the common query surface. GET /api/tasks/:id/roles exposes instances and assignments, excluding conversation bodies.

One (task, role) instance persists its conversation and sequence. Review findings return to the same dev instance. RoleInstance is the role identity within a task, assignment_id one delegation, and each task_runs row one actual execution attempt with its recovery_mode: checkpoint_transcript (native/process transcript restore), native_resume (the Pi controller reattached to its session still living in its workspace after a control-plane crash, or a container Claude Code / Codex agent that restored its persisted CLI session), rebuilt_from_task_records (a fresh session from task records when the previous one is gone, was cancelled or already ended), new_session or fresh_evaluation (QA). A container CLI run starts as external_session_pending until the agent binds its session. Interrupted tool batches are marked as missing observations; the role must query durable facts before repeating actions. Native/Process restore transcript checkpoints without automatic compaction. Pi enables SDK compaction and can reattach a surviving session after a control-plane interruption; ended sessions rebuild from durable task records. Backend recovery modes are recorded as observed, never inferred from a role name.

role_instances stores the pinned snapshot, revision, harness and redacted transcripts; role_assignments links delegation and result records; task_runs adds role, definition version, instance, assignment, harness/version, recovery mode and snapshot. GET /api/tasks/:id/roles returns instances, assignments, role runs and their snapshots. Role input/output, handoff, record reads and candidate snapshots are factual task history events. Existing tracing and model accounting remain authoritative for actual requests and tools.

Shared role permissions

Project work roles, the management assistant and Feishu group bindings (whose levels are fixed sets of these items, see message channels) use the same catalog and operation checks in src/roles/permissions.ts. The console presents two groups; it does not present basic own-task actions as permissions. An entry supplies tools only when it actually supports them. A role setting cannot create an API or a GitHub installation grant.

Group Setting Levels Actual operations
Platform computer deny / allow Read and write the assigned workspace, run commands/tests. Fixed-candidate and environment isolation still apply.
Platform delegation deny / allow Assign another enabled role; a group hands work to the project Manager. Own tasks need no delegation.
Platform project_tasks none / read / write Inspect other tasks; write also modifies tasks and sends coordination/scheduling changes. Received notices and own task progress are basic.
Platform project_memory none / read / write Read shared knowledge or propose knowledge changes through the existing validation.
Platform project_configuration none / read / write Assistants only (the management assistant and group bindings): query or change supported project settings and role definitions through the management service.
Platform schedules none / read / write Assistants only: query or change project schedules and notification subscriptions. Destination checks still apply.
GitHub github_issues none / read / write View Issues; write offers github_write on Issue routes: create, edit and close Issues, comment, labels, assignees, milestones.
GitHub github_pull_requests none / read / write View PRs/diffs; write offers github_write on pull request routes: open and edit PRs, comment, reviews (including approval), review requests.
GitHub github_actions none / read View workflows, runs, jobs and logs. The failure-analysis rerun is a delivery governed by the work type.
GitHub github_contents none / read / write Read code; write offers github_write on Contents routes: files, Git objects and refs, merging PRs.
GitHub github_checks, github_statuses none / read Read check runs/suites and commit statuses, including nested commit routes. No status/check write tool.

project_configuration and schedules govern the management tools, which only assistants have, so a project role's editor does not offer them (#850); values saved earlier stay and still do nothing. The project role editor lists the items that differ from the role's defaults and folds the rest under 「与默认相同」. GitHub write items are bounded by the project's capability ceiling: Issues and Pull requests need comment, Contents develop (see workflows).

Workflow YAML reads belong to Contents. Changing .github/workflows/ is never a role permission: github_write refuses those paths and its tokens never carry Workflows, so GitHub also refuses ref updates that would change them. Only a development task a project administrator confirmed as a CI change (workflow_changes) pushes its own bot branch with workflows: write, and only where the installation grants it; the pull request still goes through the candidate and publication gates and is merged by people.

The management assistant has a fixed explicit full policy from this catalog. The group assistant is configurable, defaulting to GitHub reads and no computer, delegation or shared-platform writes. Effective authority intersects the role policy, caller/grantor authority, project or group repository scope, entry/task contract and GitHub App installation permission. Group speakers do not gain the grantor's personal permissions; the binding service principal carries only capabilities used by its role, and every operation rechecks the grantor's live project authority.

GitHub levels govern additional remote reads and publication; they do not erase already authorized task input or the local checkout governed by the computer and task contract. Read tokens contain only permitted resource read scopes plus Metadata. Resource checks also cover search, shared Issue/PR comment routes and nested commit CI routes. Framework deliveries (review results, tested PRs, Actions reruns and failure reports, release notes, gate plans) follow the project work type's writes and need no role GitHub write (#381); direct writes go through github_write, see Agent runtime. By default only the Manager writes (Issues, Pull requests, Contents); every other built-in role reads all GitHub resources. Read access never supplies a write token to shell commands. Partial resource policies use the checked repository gateway without putting a raw read token into command environments, because GitHub shares some Issue/PR API routes. Removing resource access blocks subsequent calls; a new grant cannot enlarge a pinned run or task source ceiling.

Legacy rows and snapshots remain historical facts. Reads normalize old fields without rewriting stored history. Mixed file/command settings and narrow legacy action sets appear as pending migration, with their original allowed operations listed. Identical saves preserve those masks; choosing a new level intentionally replaces the subset and clears its masks. For example, Issue-create-only keeps no Issue read/comment permission, and coordination-only does not become permission to modify other tasks. The old delegation controls of group assistants remain a displayed transitional subset. Obsolete own-operation switches are accepted for compatibility but no longer deny basic own operations. Ordinary saves keep revision conflict checks and audit trails; revoked external access applies to the next call.

Harnesses and memory

pi (src/agent/pi.ts) is the Pi SDK session in a project computer workspace, driven through the runner mailbox; before a session starts the runner reports its installed Pi version, which must equal the pinned harness version (harness_version_mismatch otherwise), and harness_started records both. Model requests still go through the control plane's provider boundary, and every tool the session did not natively own is a control-plane tool. native uses the control-plane tool loop. process launches an independent Node worker which owns its conversation loop and uses JSON-line RPC for model requests, tool observations and checkpoints. The worker receives no provider/GitHub credential or inherited control-plane environment; the parent validates offered tools and retains the provider/accounting boundary. Both use the project's configured model; these are different running implementations, not model-name aliases. This process boundary is not an OS security sandbox.

Role memory reuses project memory tables and versions with scope.role. Default project search excludes role-scoped entries; GET .../memories?role=dev queries the role namespace. Roles receive a bounded index and can use search_role_memory, read_project_memory and, where otherwise allowed, remember_role_memory. Actual reads remain recorded; context inclusion is not proof of reading. Agent notes remain unverified and cannot overwrite human facts. Tasks in different projects remain isolated.

Authorized merge

POST /api/tasks/:id/merge accepts expected_sha and merge_method (merge, squash, rebase). This is the checked merge path for people: an explicit authorized operator action, not an agent tool. The framework requires an accepted current candidate, completed PR delivery, unchanged verification policy, the exact owned PR head and default target. It inspects remote check runs/statuses, rejects failures/incomplete checks and lets GitHub enforce repository rules. Required merge queues are not bypassed; a GitHub refusal is surfaced. Repeated/uncertain writes reuse the existing publication effect ledger and reconcile the actual merged PR.

Repositories with no remote checks are marked no_remote_checks; this is not CI success. Their task's required local policy and QA must still have passed. A confirmed merge produces a repository_evolved event with the merge SHA; later tasks prepare from the updated default branch. This endpoint does not deploy, release or confer future merge authority on a role.

Merging is also a Contents write on GitHub, so a role that holds Contents write can merge a pull request (PUT /pulls/{n}/merge) and write branches, including the default branch (PUT /contents/..., POST /git/refs, PATCH /git/refs/...), through github_write. By default the Manager holds it; other roles, group assistants and the management assistant follow their own Contents write (the management assistant only in repositories where the person may write tasks). There is no separate merge permission. Such a write does not go through this endpoint's candidate, QA and check validation, and github_write does not restrict the target branch; the repository's branch protection or rulesets and required checks decide what can be merged, so repositories the bot manages should turn them on (see the onboarding guide). Task prompts tell agents not to approve, merge or push unless the task asks for it; the Manager's fixed dispatch rules name comments and labels as examples, and the project's Manager prompt decides the rest. Setting the Manager's Contents to read in Roles → Manager removes its merge and branch writes.

Provider reasoning/thinking fields are excluded from worker messages and persisted role transcripts, matching the native loop; existing role transcripts are scrubbed on storage initialization. The shared provider boundary retries interrupted/malformed streams, stalls, 408, 429 and 5xx up to five times (waits of 1, 3, 9, 27 and 60 seconds) before returning retry_wait; see Agent runtime. This does not turn invalid business output into a pass or repeat an already acknowledged role tool operation.

Trusted integrations can add a driver through registerRoleHarness(metadata, adapterFactory), declaring version, session recovery and event visibility. Project configuration can only select registered IDs; it cannot upload arbitrary executable code. Built-in drivers cannot be replaced by registration. Runtime rows record the selected driver's version independently of the pinned role prompt. A registered driver can declare session: task_records when it cannot continue a transcript. The framework supplies task references, starts a fresh driver context and records rebuilt_from_task_records on subsequent calls. It does not label that path a continued conversation. Native process/PID resumption is not part of this first adapter contract.

Role observations tolerate an evidence string by wrapping the unchanged text in a one-element evidence array, with a normalization event. Other submission-format errors get at most two local corrections in either harness, reusing existing observations. No acceptance verdict or completion boolean is weakened. Failed/interrupted assignments are marked accordingly; a resumed role is offered its prior failed submission source so it can repair packaging without repeating unchanged checks.

See Harness Runtime for session lifecycle and container CLI executors, and RoleRun protocol for per-run protocol, admission, isolated environment profiles (isolated-workspace, isolated-candidate) and the cumulative metered budget. Native, Process, Pi, Claude Code and Codex are supported, and independent QA still evaluates role results.

Parallel integration and durable merge requests (#183)

A changed default-branch SHA no longer prevents an accepted development candidate from opening a PR. SHA identifies evidence; it does not serialize development. Each task retains its workspace and claim. Local execution accepts the same 1–32 task concurrency setting as the task scheduler (host-user isolation, no new OS sandbox or per-task quotas).

POST /api/tasks/:id/merge now persists explicit operator intent. A response may be {merged:false,status:"integrating"} or status:"queued"; only merged:true/repository_evolved confirms repository evolution. GET on the same route queries its state, expected head, contract revision, wait/error and next poll; DELETE withdraws the intent and dequeues an outstanding queue entry. A merge already completed cannot be undone by cancellation. The task controller has no merge tool; a worker, the Manager or an assistant merges only through github_write where its role holds Contents write (see Authorized merge), which neither creates nor uses this intent. Permission/policy changes, an unexpected PR head or contract revision prevent automatic merge.

A default-branch advance alone does not require another task attempt, rebase or fresh QA. The accepted PR head may be merged directly when GitHub and the repository checks allow it; the final write still validates the authorized head. Version tools expose baseline/current-main/publication refs and PR mergeability; read_version_context(compare_main=true) optionally includes bounded changed-path/stat facts without granting shell access to Manager. Manager decides whether additional inspection, verification or integration is useful. An explicit manage_task(action="integrate", base_ref, reason) (or POST /api/tasks/:id/integrate) prepares current main while preserving the candidate; it neither grants merge authority nor revives withdrawn merge intent. A known Git conflict or actual failed CI can still enter the existing repair path. When integration is requested, the framework preserves the original candidate as a source snapshot and three-way integrates it in a separate workspace. A clean combination runs the project's required verification and independent fresh QA without calling Dev again. A textual conflict or failed combined test returns the integrated checkout and exact event references to the same Dev instance; new delivery is checked again. The branch update retains the previous PR head as a parent and uses a versioned effect key, so it is fast-forward and does not replay a previous publication. Existing checks and GitHub protections still apply. Short merge decisions for a repository are serialized; development and integration remain parallel. External actors can advance a branch during a final GitHub API request; repositories needing atomic combined CI must enforce it through their GitHub queue/rules.

With a required merge queue, Bot enqueues the approved owned head and records GitHub's reported base/combined commits. Queue reordering or a changing combined SHA does not redevelop the feature. Failed combination checks return evidence to integration/repair; unexplained removal is surfaced for operator attention rather than silently undoing a person's dequeue. Empty remote checks remain no_remote_checks, never fabricated CI success.

task_merge_requests is coordination metadata, not another completion authority. Intent, integration source/target/tree, policy observations, candidate/QA and actual merge retain their task-history links. Pending work resumes through TaskEngine after a restart; legacy base_branch_changed tasks with retained snapshots are recovered automatically. Checkpoints preserve partial integration repairs. New code/memory observations use the execution baseline separately from the owned PR head. Old QA cannot certify a new integrated candidate; contract changes or unowned head updates cannot inherit merge intent. The OpenToday experiment's original long stall and manual recovery remain historical facts.

The default-branch ref is read directly before deciding whether integration is needed and before a direct merge. A PR's base.sha is metadata and may lag the live branch; it must not trigger repeated verification against an already integrated base. The candidate retains its source workspace independently of later execution workspaces. Stale background poll results cannot overwrite a newer integration or cancellation state.

Planning scope differences

contract.scope is a planning expectation, not a file allowlist. Existing records retain this meaning without migration. Explicit user prohibitions (contract.constraints when provided), the goal/criteria and framework tool permissions remain binding. The Dev can use record_scope_difference to retain paths, necessity, relation to the goal, risk/impact, verification references and the actual tree/artifact source_version. Review checks the explanation against the diff; fresh QA independently judges it. Missing explanations or product defects normally return to execution; exceeding a planned file list alone does not justify needs_human. No extra approval gate is added. QA receives explanations with an explicit version-match flag; a match is not proof and an old explanation cannot certify a new candidate.

On-demand Task Coordinator

Concrete cross-task issues use a persistent request, not a synchronous wait on an occupied task slot. The restricted Coordinator sends advice for the affected Task Managers to acknowledge; it cannot execute code, change acceptance criteria, override QA or merge. Requests survive restart and only explicit requests wake the worker. See coordination lifecycle and query API. Planning scope differences alone still use the normal Dev → Review → QA path.

Retired coordination switches

The current project configuration resolves enabled and every controller.entries value to true. These fields are deprecated compatibility output: older PUT clients may still send boolean values, which are validated but ignored. New clients omit them. This effective projection does not rewrite stored revisions or historical task snapshots, nor change role permissions, budgets, backends, event subscriptions or work-type writes. An explicit historical configuration, including a frozen task snapshot, retains its original flags. Saving a role configuration writes the next revision with Manager execution enabled; ordinary event/prompt saves do not write role settings. Stop a project/task or revoke the relevant role permission to halt work.

Unified Agent backend selection

GET .../roles returns backends and recommended_backend alongside the existing harnesses capability matrix. Each role has a backend selector; advanced JSON retains harness_ref for compatibility. New configurations default to pi; stored legacy/V2 choices and active snapshots are not silently migrated. An omitted backend on an existing V2 role retains its current choice. All remaining role fields keep the configuration API's full-replacement semantics.

Older V2 configurations used Pi for the controller-managed review and Actions dev assignments, even when the saved writer default was native. These entries keep Pi and snapshot source entry_executor until a save changes the dev harness id. Reading configuration never writes a migration, and resubmitting the same id (including a normal console save) or omitting it does not opt in. A role without a previously saved V2 harness, including a new configuration or the first save of a legacy configuration, adopts its selected backend immediately. The server persists entry_harness_source: "role" on dev once adopted; subsequent unchanged saves retain it. The console explains when these entries still use Pi despite the saved role backend. This compatibility rule does not affect development teams, ordinary RoleRuns, QA or Coordinator. Fixed task configurations and active snapshots retain their backend until the existing explicit configuration/role-apply mechanism adopts a newer revision.

Native and Pi review/Actions dev assignments can write project notes at ../notes/<name> through the runner's note protocol. Invalid note names return tool errors, and repository writes remain forbidden unless the work type's project writes grant them. In this entry, a TaskError from a tool callback is returned as a tool error; completion validation and other run stop conditions retain their existing behavior.

Pi worker tools are executed by the same control-plane callbacks as Native: Dev writes its task workspace, observers inspect a disposable fixed candidate, and QA always gets a fresh session and the acceptance checkout. The SDK session itself has a separate empty workspace; no implicit shell, extensions or host skills are added. Coordinator uses the same role configuration and prepares a project-computer session only when Pi is selected.

claude_code and codex are registered container worker backends for writer, observer and evaluator roles; they cannot run controller roles, including Manager and Coordinator (see Claude Code and Harness Runtime). On the Roles overview and role detail pages, backends[].runtime_status displays the /opt/agent-tools read-only volume status, installed/selected CLI versions, compatible semver range, model relay readiness and any unavailability reason, together with a model source selector (平台网关 vs reserved 供应商订阅(预留)). Retired backend IDs such as acp and opencode are rejected with unknown_role_harness at roles.<id>.harness_ref.id.

See persistent role scheduling for task stage plans, project gates, parallel inspection, recovery and acceptance.

控制台编辑与版本比较

项目的「角色」页在概览与详情之间共用一份内存草稿。详情按基本信息、Agent 与模型、提示词、技能、权限、环境与输出、预算分区;分区跳转不新建表单副本,也不丢弃已输入内容。保存操作与错误提示保留在可见的顶部操作区;明确请求比较后,比较面板进入视口。解析说明来自读取时的已保存配置,下面的选择属于待保存草稿;修改草稿不会重写运行中任务的历史模型或角色快照。

保存携带读取时的 expected_revision。遇到版本冲突后保留草稿,通过「读取最新版本并比较」重新读取服务器配置;未重叠的修改会合并,重叠字段必须逐项选择使用草稿或最新值。角色、技能、阶段按各自标识比较;删除与他人修改同一记录也会形成冲突。应用比较结果只更新草稿及其版本基线,还须明确保存,服务器仍会重新校验权限、角色和阶段约束。

读取失败时显示未知状态与只读重试入口。权限失效会清空本页草稿;切换项目后,旧页面的迟到响应不能替换新的编辑器。草稿仅保留在当前登录页面的内存中,整页重新加载后不恢复。

技能包目录

「角色 → 技能包目录」提供按标识或来源搜索的列表和单包编辑。桌面并列展示,手机上下排列;同一角色草稿继续在概览、角色详情和技能目录之间共享。草稿来源、文件与绑定角色需要通过共同的「保存角色配置」提交,保存失败和版本冲突保留输入。技能只提供工作材料,不增加权限、工具或必需阶段。

每个包单独显示已保存来源、版本、内容哈希、文件路径/字节数/SHA-256,以及已保存的绑定角色;草稿绑定与已保存记录分开。新包或改名后的标识显示尚未保存,不把草稿字节数或当前分支当作历史快照。仓库来源固定完整提交和路径,当前规则缓存前进不会自动修改已固定内容。未改变来源的现有仓库包可以使用它当前保存版本的文件重新保存;改变标识、提交或路径时仍要求匹配的仓库缓存。编辑其他技能包或角色不需要先把未变包升级到最新分支。