Skip to content

tracking(harness): reduce readiness, tool, archive, browser, and research friction #4267

Open
3 of 3 issues completed

Description

@liugddx

Current status (2026-09-02)

This issue remains the umbrella record for a real extended-session harness audit. It is now a status and routing index, not one implementation specification and not a second acceptance list for every linked issue. The historical English and Chinese narratives below remain evidence; this section is the current authority.

The current status is based on the issue/PR graph and source verification against upstream/main@07f5cb537.

Status dashboard

# Area Current status Tracking / disposition
1 PATH present but executable unusable in managed Bash Open; confirmed #4279 was closed unmerged after security and Git-semantics review. Current task-submission readiness checks Runtime/model/workspace, not an arbitrary selected Bash executable or its dependency closure. A replacement must use a bounded, validated Runtime-owned executable substrate rather than accumulated path exceptions.
2 macOS /tmp capability mismatch Resolved #4234 canonicalizes Seatbelt roots and includes real /tmp / $TMPDIR smoke coverage. Do not reopen without a current-main reproduction.
3 ArchiveRead retrieval ergonomics Resolved for the requested interface #4355 / #4380 shipped archive search, line reads, decoded paging, previews, and bounded responses. Internal canonical-document and response-budget convergence continues in #4452.
3b Shell output lost before archiving Open; separate upstream contract Current Bash capture keeps a bounded tail before model shaping and archive persistence. #615 already tracks write-path loss and replay/source-of-truth implications. Deliver this as a focused bounded redacted-output artifact slice; ArchiveRead cannot recover bytes dropped before the archive.
4 Structured public GitHub research Open; no focused delivery issue yet Current repo surfaces remain generic Web/Search plus local CLI paths. Prefer an unauthenticated-first GitHub research skill/plugin before promoting a forge adapter into core.
5 Bypass and Client Capability boundary truth Open; tracked #3349 tracks Auto→Bypass not being observed by the next turn. #4012 tracks session-scoped admission for Browser, Computer Use, Desktop MCP, and safe settings in Auto mode without weakening the Host sandbox.
6 Browser visible-lease / login handoff Runtime/source conformance investigation Source requires every browser action to target the shown conversation, but the recorded session observed viewport: 0x0 and no user-visible browser. Create a focused telemetry/reproduction issue before proposing a new ownership model.
7 WriteStdin provider/validator conformance Resolved #4354 / #4378 merged with derivable schemas, documented minimal calls, internal raw-input positioning, and provider-visible schema coverage.
8 High-frequency tool schema boilerplate Withdrawn The relevant execution fields are optional/defaulted or host-pruned. Do not restore without a current provider-visible schema reproduction.
9 Deferred native-tool capability families Resolved #4353 / #4376 merged categoryHint-backed Tool Search grouping while preserving fallback and permission behavior. Catalog→invocation identity mismatches remain a separate issue only if independently reproduced.
10 Response completion versus actual delivery Investigation remains Backend terminal and retry authorities exist. #4284 and #4502 cover adjacent retry/diagnostic gaps but do not by themselves prove persisted terminal output was fully delivered and rendered. Require a current reproducible delivery boundary before opening another authority.
11 Repeated environment metadata Withdrawn The per-turn tail is intentional for volatile state and prompt-prefix stability. Only bounded serialization improvements are in scope.
12 Task-level progress legibility Moved to product presentation Reuse existing Runtime/Agent Graph facts. #2469 owns the product direction; #3878 is a concrete liveness-presentation example. Do not create a second progress authority here.

Priority order

  1. Authority truth first: finish Permission mode switch (Auto→Bypass) is not honored by the next turn #3349 and open the Browser visible-lease conformance investigation. A UI-selected permission mode or visible-session invariant must match the boundary actually used.
  2. Effective command execution: replace fix(runtime): admit macOS Bash toolchain dependencies #4279 with a narrowly specified managed-Bash executable-substrate issue. Validate canonical admitted roots and real Apple/Homebrew startup without changing Git configuration semantics or granting broad package-manager roots.
  3. Shell output preservation: split a delivery issue from fix(runtime): RuntimeEvent ledger is recovery-grade (WAL), not source-of-truth — write-path truncation blocks counterfactual replay #615 that persists a redacted output artifact before the 50 KiB model projection, with an explicit storage quota and produced/captured/dropped byte counts. Do not promise unbounded “lossless” capture.
  4. Structured GitHub research: define an anonymous-first skill/plugin with canonical redirects, Issues/PRs/Discussions, comments/timeline, pagination, and rate-limit evidence.
  5. ArchiveRead internals: continue refactor(runtime): unify ArchiveRead canonical document and response-budget ownership #4452 without reopening the already-delivered harness: ArchiveRead search / line reads / section index ergonomics (item 3 of #4267) #4355 interface scope.

Scope discipline and closure rule

  • Do not combine command readiness and Shell capture into one issue: one is pre-dispatch admission/substrate, the other is post-dispatch data persistence.
  • Do not claim Maka can pre-probe an arbitrary shell command completely. Pipelines, child processes, plugins, runtime dlopen, network, and side effects make that equivalent to executing the command. Probe the bounded capability that Runtime owns; classify first-dispatch failures actionably.
  • Do not add another readiness, progress, archive, or permission authority. Reuse the existing Runtime Host, task-submission readiness, execution boundary, ShellRun, Artifact, and projection owners.
  • Keep this umbrella open until every confirmed item is resolved, explicitly withdrawn, or routed to a focused issue with a current owner and acceptance criteria. It need not remain open until every routed implementation merges.

Immediate maintenance actions

  1. Keep completed sub-issues harness: wire native tool categoryHint/ToolCategory into deferred tool-search groups (item 9 of #4267) #4353, harness: WriteStdin provider schema and strict validator conformance (item 7 of #4267) #4354, and harness: ArchiveRead search / line reads / section index ergonomics (item 3 of #4267) #4355 closed and reflected as delivered.
  2. Track Permission mode switch (Auto→Bypass) is not honored by the next turn #3349, enhancement(runtime): allow Auto mode to use tools currently restricted to Full Access on macOS #4012, fix(runtime): RuntimeEvent ledger is recovery-grade (WAL), not source-of-truth — write-path truncation blocks counterfactual replay #615, refactor(runtime): unify ArchiveRead canonical document and response-budget ownership #4452, roadmap(product): evolve Maka into a durable Agent workspace #2469, and fix(desktop): agent graph appears frozen while 0/7 operators are running (no heartbeat) #3878 here rather than opening duplicates.
  3. Create focused issues only for: managed-Bash executable substrate, bounded durable Shell capture, Browser visible-lease conformance, and structured GitHub research.
  4. Revisit item 10 only after a current-main reproduction identifies the persisted-versus-delivered boundary.

The original friction narrative below is retained as historical session evidence. It is useful for conformance work, but it is not a second acceptance list; the verdict table and tracking map above define current scope.


Problem

Maka's harness has strong foundations: explicit execution boundaries, durable Runtime Host ownership, structured filesystem tools, reconnectable execution, and bounded tool-result archiving. In a real, extended Maka session, however, several harness-level frictions compounded and made ordinary development and research work substantially harder than necessary.

The recurring pattern was not that the work was impossible. The harness usually provided a workaround. The problem was that the model and user had to spend too much effort discovering the effective capability boundary, navigating archived results, recovering from missing research primitives, and bridging user-mediated actions that the harness presented but could not complete.

This umbrella tracks those cross-cutting harness issues as one product and architecture problem:

A task should fail early and actionably when the environment cannot support it, remain observable while it runs, and require the minimum possible harness plumbing from either the user or the model.

This is based on observed behavior in one real Maka session, not a claim that every environment reproduces every symptom.

Observed friction

1. A command may be present on PATH but unusable inside the effective sandbox

Ordinary commands failed after launch because their runtime dependencies were outside the readable boundary:

  • git remote -v reached Apple's xcrun, but loading libxcrun.dylib under Command Line Tools was blocked;
  • Homebrew python3 was present, but its framework library under the Homebrew Cellar was blocked;
  • the working directory was a Git repository and workspace access was available, yet basic Git inspection could not run.

This creates a misleading capability state:

binary is discoverable
  != binary can start
  != binary can load its runtime dependencies
  != binary can perform the requested operation

The user and model currently discover this only after beginning the task.

2. Declared temporary-directory capability did not match observed behavior

A command that attempted to write a fetched response under /tmp failed with a destination error, despite the boundary summary indicating temporary-directory write support. Writing the same data into the workspace succeeded.

Whether this was path resolution, process sandboxing, or another environment issue, the important product problem is that the effective capability was not predictable from the readiness information presented to the model.

3. Tool-result archiving protects context but imposes excessive retrieval plumbing

Large results were correctly moved behind maka://archive/... references, but ordinary investigation repeatedly required:

ArchiveRead.inspect
  -> ArchiveRead.read(offset=0)
  -> ArchiveRead.read(next offset)
  -> repeat

Observed costs included:

  • small or immediately needed results also becoming indirect;
  • inspect frequently exposing only generic keys such as content or matches;
  • character-offset pagination being awkward for line-oriented terminal output;
  • terminal output being wrapped inside archive JSON;
  • already-truncated stdout being archived, requiring the command to be rerun into a workspace file before it could be searched or paged reliably;
  • no direct search within an archive;
  • the model spending material context and reasoning on archive mechanics rather than the user's task.

The archive is valuable. Its current retrieval interface is the problem.

4. Public GitHub research required a fragile chain of unrelated tools

To inspect public Issues and Discussions, the session had to:

  1. try gh search;
  2. discover that the existing GitHub CLI authentication returned 401;
  3. fall back to anonymous REST search;
  4. discover a repository redirect from Maka-Agent/maka-agent to apache/maka;
  5. fetch Issues through REST;
  6. discover that Discussions search through GraphQL required authentication;
  7. scrape GitHub HTML search pages;
  8. extract Discussion links;
  9. fetch each page separately;
  10. use additional REST calls for metadata such as author, state, labels, and comments.

WebFetch was useful for main content, but it did not consistently provide canonical URL, author, state, labels, comments, or linked work. Some Discussion fetches also timed out.

Public repository research should not require local CLI credentials, HTML scraping, and several custom parsers.

5. Boundary-choice UX implied a state change that did not occur

A Client Capability failed with requires_bypass. The assistant then used AskUserQuestion with an option labelled effectively as “Switch to Bypass.” The user selected that option, but the Session boundary did not change. Retrying the Client Capability returned the same requires_bypass error.

The actual sequence was:

Client Capability reports requires_bypass
  -> assistant presents “Switch to Bypass” choice
  -> user selects it
  -> AskUserQuestion returns only the selected text
  -> Session remains sandboxed
  -> Client Capability fails again
  -> user must manually change the mode in Maka UI
  -> the new boundary becomes visible only in a later turn

This is partly a model wording problem, but the harness makes the mistake easy: a choice can look like a native action even though it has no authority to mutate Client state.

6. The automated browser was not visible or transferable to the user

After Bypass became active, the browser Client Capability successfully navigated to GitHub, but it used an automation context that the user could not see. GitHub required login. The assistant asked the user to log in “in that browser,” but the user had no visible browser window to interact with.

The automation surface exposed no clear way to:

  • show the automated browser to the user;
  • hand the current page to the user's default browser;
  • let the user temporarily take control;
  • complete a passkey, password, or OAuth flow in a user-visible window;
  • return control to the agent after authentication.

The working fallback was to run GitHub's device-code login and explicitly open https://github.com/login/device in the user's system browser. That handoff should be a supported interaction, not an improvised shell workflow.

7. Terminal-input schema and runtime validation disagreed

While interacting with a background PTY, the visible WriteStdin schema required a broad action object, including fields such as pointer/event metadata. Supplying those fields for a key action was then rejected by runtime validation as containing unsupported fields.

This produced a tool contract that was not satisfiable as advertised. The operation had to be cancelled and replaced with a pipe-based workaround.

Tool schemas and runtime validators must describe the same accepted union, especially for terminal input where recovery often depends on sending one key or a short text response.

8. High-frequency tool schemas require unnecessary boilerplate

A normal foreground shell call repeatedly required explicit values for fields that almost always had the same defaults:

{
  "timeout_ms": 120000,
  "run_in_background": false,
  "pty": false,
  "boundary_intent": "current"
}

Explicit authority declarations are important, but non-authority execution defaults need not be repeated on every call. The extra schema surface increases token use and parameter-error risk without adding meaningful control.

9. Deferred tool discovery saves context but hides the capability map

maka_tool_search reduces the always-visible tool catalog, which is useful. However, the model initially has little indication of which capability families exist. A poorly phrased search can miss a native tool and send the task through Shell or Web scraping instead.

The session also exposed a skill/catalog naming mismatch: the closest agent-management skill was named and documented as paseo, while the active product and repository were Maka and the actual deferred tool names differed from those documented by the skill. This increases the risk of stale or incorrect orchestration assumptions.

10. Long-response completion and retry state were not obvious

One long assistant response appeared to end mid-structure. The same user request was then sent again. It was not possible to tell from the conversation whether the response hit an output limit, the stream was interrupted, the renderer lost the terminal event, or the user intentionally retried.

The UI should distinguish:

  • model completed normally;
  • output limit reached;
  • connection interrupted;
  • renderer failed to settle;
  • user requested continuation.

A repeated identical user message after an incomplete assistant stream should not force the model to regenerate the entire answer without knowing what the user received.

11. Repeated environment metadata consumes attention and context

Full environment and sandbox summaries are useful, but injecting substantially identical blocks on every user turn adds noise. Most turns need only the current structured state and any delta since the previous turn.

Repeated metadata can cause the model to over-focus on execution context even for conversational questions, while also consuming context that should remain available for the user's work.

12. Low-level tool activity is visible, but task-level progress is weak

The user may see many tool calls, archive reads, retries, and permission operations without a compact explanation of task progress. Raw auditability is valuable, but it is not a substitute for a projection such as:

Researching Runtime Host roadmap

✓ Located the canonical repository
✓ Searched Issues and Discussions
✓ Identified the active tracking issues
● Comparing implementation status and non-goals

This is the same broader product gap described by the durable Agent workspace roadmap: execution facts exist, but the primary task state is harder to understand than it should be.

Desired outcome

Maka should provide a harness in which:

  1. task readiness reflects observed executable capability, not only configured paths and grants;
  2. common development tools either work with their runtime dependency closure or fail before task execution with an actionable reason;
  3. archived results remain bounded without forcing the model to manually manage archive plumbing;
  4. public repository research has a structured, unauthenticated-first path;
  5. a user-facing choice never implies a Client state mutation that it cannot perform;
  6. user-mediated authentication has a visible and explicit handoff;
  7. every advertised tool schema is accepted by its runtime validator;
  8. common tool calls can rely on safe defaults;
  9. deferred tools remain discoverable at the capability-family level;
  10. incomplete responses and repeated requests have explicit continuation semantics;
  11. environment context is delivered as structured state plus deltas;
  12. task-level progress is legible without reading raw tool traffic.

Proposed workstreams

Workstream 1 — Effective task readiness

Add a bounded readiness projection based on real probes rather than presence alone.

Possible shape:

interface EffectiveToolCapability {
  tool: string;
  present: boolean;
  executable: boolean;
  dependencyReadable?: boolean;
  usableForCurrentTask?: boolean;
  reasonCode?: string;
  repairAction?: string;
}

Initial probes should cover common development paths:

  • Git;
  • configured shell;
  • Node/package manager;
  • Python where advertised;
  • compiler/toolchain where required by the project;
  • workspace and temp writes;
  • network when needed;
  • Runtime Host/model/workspace/provider readiness.

A failed probe should produce a stable reason such as dependency_blocked, binary_missing, write_denied, or credential_unavailable, plus a direct repair or fallback action.

Do not silently broaden the sandbox merely because a binary exists.

Workstream 2 — Executable dependency closure

Evaluate one or more of:

  • read-only admission of the dynamic-library dependency closure for an approved executable;
  • hermetic Maka-provided versions of essential utilities;
  • a platform capability registry that knows when a PATH entry is unusable under the current boundary;
  • pre-dispatch failure before starting work that depends on an unusable tool.

Acceptance should include real macOS Git/Command Line Tools and Homebrew runtime cases, not only mocked path checks.

Workstream 3 — Archive retrieval ergonomics

Keep bounded archiving, but add:

  • a direct-result threshold for small outputs;
  • archive section/line indexes;
  • line-based reads for terminal and text artifacts;
  • search within an archive;
  • automatic bounded summaries and likely-relevant sections;
  • consistent access to the complete captured output rather than an already-truncated terminal tail;
  • simpler handling of structured archive items without an extra generic JSON wrapper.

A model should normally be able to understand a large search result with one summary call and one targeted read.

Workstream 4 — Structured public repository research

Provide structured tools or adapters for common public research:

RepositorySearch
IssueSearch
DiscussionSearch
IssueRead
DiscussionRead

Responses should include:

  • canonical repository and URL after redirects;
  • number, title, author, state, labels, timestamps;
  • body and bounded comments;
  • linked Issues/PRs;
  • pagination and rate-limit state.

Public reads should prefer unauthenticated access and request login only for operations that truly require it.

Workstream 5 — Honest Client-action UX

Do not render a multiple-choice answer as though it performs an unavailable Client action.

Possible solutions:

  • introduce a real RequestBypass/boundary-change Client action with a native confirmation surface;
  • have requires_bypass errors carry an actionable UI control;
  • label ordinary choices as “I will switch manually,” not “Switch”;
  • emit a Session event when the boundary actually changes;
  • require the agent to observe the new boundary before retrying;
  • if the boundary remains unchanged, report that immediately.

The authority decision must remain explicit and user-controlled.

Workstream 6 — Visible browser and authentication handoff

Add an explicit browser ownership model:

agent-controlled hidden browser
user-visible browser
user-takeover requested
user controlling
agent control restored

At minimum, support:

  • “Show browser”;
  • “Open this URL in my browser”;
  • a device-code/OAuth handoff primitive;
  • a user-completed callback/event;
  • no model access to passwords, passkeys, or unrelated browser state;
  • clear indication when the automated browser is not user-visible.

The harness must never instruct the user to interact with a browser they cannot see.

Workstream 7 — Tool schema conformance

Generate tool schemas and runtime validators from the same discriminated union where possible. Add conformance tests that submit one minimal valid payload for every advertised action variant.

For terminal input, separate action shapes explicitly, for example:

type TerminalInputAction =
  | { type: "text"; text: string }
  | { type: "key"; key: string; modifiers?: string[] }
  | { type: "resize"; cols: number; rows: number }
  | { type: "pointer"; event: ...; x: number; y: number };

A key action should not require pointer fields that its validator rejects.

Workstream 8 — Safe schema defaults and approved-boundary references

Allow concise foreground calls with documented defaults:

{"command": "..."}

Default non-authority fields may include foreground execution, no PTY, and a standard timeout. Filesystem/network expansion must remain explicit.

After a boundary is approved, consider returning an opaque boundary reference that later calls can reuse instead of repeating the complete declaration.

Workstream 9 — Capability-family discovery and skill consistency

Advertise a compact taxonomy without loading every schema:

filesystem
shell
web research
browser automation
agent orchestration
scheduled work
desktop settings

Also validate at startup that:

  • a skill's declared or documented tools exist;
  • product names, CLI names, and state directories are current;
  • stale skills are marked incompatible instead of silently presented;
  • Maka/Paseo terminology is intentional and explained if both remain supported.

Workstream 10 — Response completion and continuation

Persist and expose a terminal response state:

completed
output_limit
connection_interrupted
renderer_unsettled
cancelled

When incomplete, present a native Continue action and inject the confirmed received boundary into the next model turn. Detect likely duplicate user retries and ask whether to continue or restart rather than assuming either.

Workstream 11 — Structured environment deltas

Keep environment authority independent from prompt text, but deliver repetitive state internally as structured metadata. Inject a human-readable delta only when something changes, for example:

Execution boundary changed:
- profile: workspace-write -> danger-full-access
- network: disabled -> enabled

Security-relevant facts must remain available to the model; the goal is to avoid repeated unchanged prose, not hide authority.

Workstream 12 — Task-level progress projection

Project existing execution facts into a compact task status with:

  • current phase;
  • completed milestones;
  • active operation;
  • waiting reason;
  • required user action;
  • retries/fallbacks;
  • recovery state;
  • elapsed time.

Raw tool calls remain available for audit and debugging, but are not the only primary progress surface.

Suggested delivery order

Phase 1 — Contract correctness and readiness

  1. Tool schema/runtime validator conformance, including terminal input.
  2. Effective Git/runtime/temp-write probes.
  3. Actionable pre-dispatch readiness failures.
  4. Honest boundary-change UX.

Phase 2 — Reduce model plumbing

  1. Archive search, line reads, and summaries.
  2. Safe tool-call defaults.
  3. Capability-family discovery.
  4. Structured environment deltas.

Phase 3 — Complete user-mediated flows

  1. Visible browser/takeover contract.
  2. Device-code/OAuth handoff.
  3. Structured public repository research.
  4. Response continuation and duplicate-retry handling.

Phase 4 — Product comprehension

  1. Task-level progress projection.
  2. Recovery and fallback explanation.
  3. Real-journey coverage for research, code modification, remote login, and interrupted response flows.

Each slice should be independently reviewable and should reuse existing Runtime, Task, Artifact, readiness, and Client Capability authorities rather than adding a second source of truth.

Acceptance criteria

  • A Git repository task on macOS reports whether Git is actually executable under the current boundary before relying on it.
  • An advertised temporary-directory write capability is proven by a real bounded probe or reported unavailable.
  • A large terminal/search result can be summarized, searched, and line-read without rerunning the command into a workspace file.
  • Public GitHub Issues and Discussions can be searched and read without local authentication where GitHub permits it.
  • Selecting an ordinary question option never falsely appears to mutate the Session boundary.
  • A requires_bypass flow either performs a native user-confirmed transition or explicitly instructs the user to switch manually and verifies the result.
  • A browser login flow can be handed to a user-visible browser without exposing credentials to the model.
  • Every advertised terminal-input variant passes schema/validator conformance tests.
  • A normal foreground shell command can omit non-authority default fields.
  • The model can discover capability families before loading full tool schemas.
  • An interrupted or output-limited assistant response is visibly distinct from normal completion and can continue without regenerating received content.
  • Unchanged environment metadata is not repeatedly injected as large prose blocks.
  • A user can understand the current task phase and required action without inspecting raw tool cards.

Non-goals

This umbrella does not propose:

  • weakening sandbox or boundary enforcement;
  • silently granting filesystem, network, Bypass, or browser authority;
  • exposing user passwords, passkeys, cookies, or unrelated browser state to the model;
  • removing tool-result archiving;
  • replacing Runtime Host, Task, Artifact, or readiness authorities with a second harness database;
  • requiring every public research task to authenticate;
  • adding decorative progress UI without authoritative execution facts;
  • a big-bang rewrite of the tool system;
  • treating every external failure as a Maka defect.

Related work


简体中文

问题

Maka harness 的基础方向很好:明确的执行边界、持久 Runtime Host authority、结构化文件工具、可恢复执行,以及有界 Tool Result archive。但在一次真实的长会话中,多项 harness 摩擦相互叠加,使普通开发和调研工作比必要程度困难很多。

核心问题不是“做不到”。多数情况下最终都有 workaround。问题是用户和模型需要花费过多精力去发现真实有效的能力边界、翻阅归档结果、补足缺失的外部调研能力,以及处理 harness 看起来提供、实际上却无法完成的用户动作。

本 Umbrella 跟踪以下统一目标:

当环境不支持任务时,应尽早、准确、可操作地失败;任务运行时应保持可观察;用户和模型都不应承担不必要的 harness plumbing。

以下结论来自一次真实 Maka Session 的观察,不表示所有环境都会复现所有症状。

已观察到的问题

1. PATH 中存在的命令不等于在真实 sandbox 中可用

  • git remote -v 启动后因为 Command Line Tools 的 libxcrun.dylib 无法读取而失败;
  • Homebrew python3 存在,但其 Cellar framework library 被阻止;
  • 当前目录是 Git repo,workspace 也可读写,但基础 Git 检查仍然无法执行。

需要区分:

binary 可发现
  != binary 可启动
  != runtime dependency 可读取
  != 能完成当前操作

2. 临时目录声明能力与实际行为不一致

Boundary summary 表示临时目录可写,但将 fetch 结果写到 /tmp 时失败;改写 workspace 后成功。无论根因属于路径、process sandbox 还是其他环境问题,readiness 都没有准确反映实际能力。

3. Archive 保护上下文,但取回成本过高

大量结果需要反复执行:

inspect -> read(offset) -> read(next offset) -> repeat

问题包括:小结果也可能间接化、inspect 索引信息不足、字符 offset 不适合行文本、terminal JSON 多层包装、归档的可能已经是截断 stdout、无法直接搜索 archive,最终不得不重新执行命令并写入 workspace 文件。

4. 公共 GitHub 调研需要拼接太多无关工具

实际流程包含 gh、认证失败、匿名 REST、仓库重定向、HTML Discussion 搜索、正则提取、逐页 WebFetch,以及额外 REST metadata 查询。公共 Issues/Discussions 调研不应依赖本地 CLI credential 和 HTML scraping。

5. Boundary 选择看起来执行了状态变更,实际没有

Client Capability 返回 requires_bypass 后,assistant 用 AskUserQuestion 提供了类似“切换到 Bypass”的选项。用户选择后,Session boundary 没有变化,重试仍然失败。最终必须由用户在 Maka UI 手动切换,并等待下一轮环境状态更新。

普通问题选项不应伪装成自己无权执行的 Client action。

6. 自动化浏览器对用户不可见,也无法接管

Bypass 生效后,Browser Capability 能导航到 GitHub,但使用的是用户看不到的 automation context。GitHub 要求登录时,用户无法在“那个浏览器”里操作。最终只能改用 device-code,并显式在用户系统浏览器打开登录页面。

Harness 应支持显示浏览器、打开到用户浏览器、临时用户接管、完成认证后归还控制权等明确流程。

7. Terminal input schema 与 runtime validator 不一致

可见的 WriteStdin schema 要求宽泛 action 字段,但 runtime 对 key action 又拒绝其中部分字段,形成无法按 advertised contract 构造的 payload。最终只能取消 PTY,改用 pipe workaround。

8. 高频工具 schema 包含过多重复字段

普通前台 Shell 调用反复要求显式提供 timeout、background、PTY 和 current boundary 等固定默认值。Authority 扩张仍应明确,但非 authority 默认值可以省略。

9. Deferred tool discovery 节省上下文,但能力地图不透明

模型不知道有哪些 capability family,搜索措辞不佳就可能错过 native tool,转而使用 Shell 或 scraping。会话中还出现了 paseo Skill 与 Maka 产品、实际 tool 名称之间的命名和文档错位。

10. 长回答是否完整结束不明确

一条长回答看起来在结构中途结束,随后用户重复发送同一问题。会话无法明确区分 normal completion、output limit、stream interruption、renderer 未 settle 或用户主动重试。

11. 重复环境 metadata 消耗上下文和注意力

完整 env/sandbox 文本每轮重复注入,虽然安全信息有价值,但未变化内容更适合以 structured state 保存,仅在变化时注入 delta。

12. 底层工具活动很多,但任务级进度不清晰

用户可能看到大量 tool call、archive read、retry 和 permission operation,却无法快速知道任务处于哪个阶段、已完成什么、正在等待什么。

期望结果

Maka 应做到:

  1. readiness 反映真实 probe 结果,而不只是 PATH 和配置;
  2. 常见开发工具能读取必要 runtime dependency,或在任务开始前给出可操作失败;
  3. Archive 保持有界,但无需模型手工管理大量分页 plumbing;
  4. 公共代码仓库调研有结构化、匿名优先路径;
  5. 普通问题选项不暗示自己能执行 Client 状态变更;
  6. 用户认证具备可见、明确的 handoff;
  7. Tool schema 与 runtime validator 完全一致;
  8. 常规 Tool call 使用安全默认值;
  9. Deferred tool 在 capability-family 层面可发现;
  10. 不完整回答和重复请求具备明确 continuation 语义;
  11. 环境信息使用 structured state + delta;
  12. 用户无需阅读原始 Tool traffic 即可理解任务进度。

建议工作流

Workstream 1:真实 Task Readiness

为 Git、Shell、Node、Python、编译器、workspace/temp write、network、Runtime Host、model、provider 等提供真实有界 probe,并返回稳定 reason code 和 repair action。

Workstream 2:Executable Dependency Closure

评估:允许 approved executable 只读访问动态库依赖闭包、提供 hermetic 基础工具,或在 pre-dispatch 阶段识别 PATH 中存在但不可用的工具。不能因为 binary 存在就静默扩大 sandbox。

Workstream 3:Archive 取回体验

增加小结果直返阈值、section/line index、按行读取、archive 内搜索、自动摘要、完整 captured output,以及更简单的结构化 item 读取。

Workstream 4:结构化公共仓库调研

提供 Repository/Issue/Discussion Search 和 Read,返回 canonical URL、author、state、labels、body、bounded comments、linked work、pagination 和 rate-limit。公共读取默认匿名。

Workstream 5:诚实的 Client Action UX

为 boundary change 提供真实原生 action,或者明确标记“我会手动切换”。Boundary 真正变化后注入事件,Agent 重试前必须验证新状态。

Workstream 6:可见浏览器与认证 Handoff

支持 Show Browser、Open in My Browser、device-code/OAuth handoff、用户完成事件和控制权归还。模型不得访问密码、passkey 或无关浏览器状态。

Workstream 7:Tool Schema Conformance

Schema 与 validator 尽量由同一 discriminated union 生成,并为每个 advertised action variant 增加最小有效 payload 测试。

Workstream 8:安全默认值和 Boundary Ref

普通前台命令可省略非 authority 默认字段。Boundary 批准后可返回 opaque ref,避免后续重复完整声明;filesystem/network 扩张仍然必须明确。

Workstream 9:Capability Family 和 Skill 一致性

初始只广告 filesystem、shell、web research、browser、agent orchestration、scheduled work 等小型分类。启动时校验 Skill 文档的 Tool 是否存在,并明确 Maka/Paseo 命名关系。

Workstream 10:回答完成与续写

公开 completed、output_limit、connection_interrupted、renderer_unsettled、cancelled 等 terminal 状态。不完整时提供 Continue,并避免重复生成用户已收到的内容。

Workstream 11:结构化环境 Delta

保持 authority 独立于 prompt 文本,但只在环境变化时注入人类可读 delta;未变化安全事实继续作为 structured metadata 可用。

Workstream 12:Task-level Progress Projection

从已有 execution facts 投影 phase、milestone、active operation、waiting reason、required action、retry/fallback、recovery 和 elapsed time。原始 Tool call 保留供审计。

建议交付顺序

Phase 1:Contract correctness 和 readiness

  1. Tool schema/validator conformance;
  2. Git/runtime/temp-write probe;
  3. Actionable pre-dispatch failure;
  4. Honest boundary-change UX。

Phase 2:减少模型 plumbing

  1. Archive search/line read/summary;
  2. 安全 Tool 默认值;
  3. Capability-family discovery;
  4. Environment delta。

Phase 3:补齐用户参与流程

  1. Visible browser/takeover;
  2. Device-code/OAuth handoff;
  3. Structured repository research;
  4. Response continuation 和 duplicate retry。

Phase 4:产品可理解性

  1. Task progress projection;
  2. Recovery/fallback explanation;
  3. 覆盖调研、代码修改、远程登录和响应中断的真实 journey 测试。

每个切片应独立可审查、可回滚,并复用现有 Runtime、Task、Artifact、readiness 和 Client Capability authority,不增加第二 source of truth。

非目标

本 Umbrella 不建议:

  • 弱化 sandbox 或 boundary enforcement;
  • 静默授予 filesystem、network、Bypass 或 browser authority;
  • 向模型暴露用户密码、passkey、cookie 或无关浏览器状态;
  • 删除 Tool Result archive;
  • 用第二 harness database 替代 Runtime Host、Task、Artifact 或 readiness authority;
  • 要求所有公共调研都先认证;
  • 添加没有 execution facts 支撑的装饰性进度 UI;
  • 大爆炸重写 Tool system;
  • 把所有外部失败都归因于 Maka。

Activity

  1. liugddx commented on Aug 30, 2026

    @liugddx
    MemberAuthor

    Source audit + verdict revision

    I ran a source-level audit of main against all 12 friction areas. Summary: the umbrella holds up as a record of real session friction, but ~70–80% of the individual items need to be narrowed, reclassified, or withdrawn before they become an engineering worklist. I've added a post-audit status block and a verdict table to the issue body; details and the reasoning per item are below.

    Methodological correction (applies to #6 and #10 especially)

    A source audit proves what the code on main should do. It does not prove that the observed friction was absent in the actual build / Runtime composition / Client Capability path that produced this report. Where a source invariant contradicts a runtime observation, the honest verdict is "conformance investigation needed," not "refuted by source." I over-stated two items on the first pass and have corrected them below.

    Withdrawn

    • Land Runtime v2 architecture and AgentRun wiring #8 (tool-schema boilerplate) — timeout_ms, run_in_background, pty are .optional(); boundary_intent has a .default('current'); required_boundary is optional and boundary fields are dropped from the schema entirely when the host has no sandbox boundary (shell-tools.ts). Only command/ref are required. The per-call verbosity in the session was conservative model behavior, not a server requirement. At most this is a "does the provider-visible schema express optional/default clearly" question.
    • Prefer RuntimeEvent model history when complete #11 (env once+deltas) — the per-turn env tail is deliberate: it's kept out of the durable/cached system prefix precisely to avoid prefix-hash churn, and the model must see the current date/branch/boundary each turn (session-environment-prompt.ts). It's already budgeted and capped. "Send once + deltas" would regress the prompt-cache design. Only compaction of the per-turn serialization is on the table.

    Narrowed (real, but smaller than stated)

    • Extract runtime kernel boundaries and durable AgentRun recovery #3 (archive) — a direct-return threshold already exists (payloads ≤~2048 est. tokens are not archived; superseded ≤256 kept verbatim). The "small/immediately-needed results also become indirect" framing is over-stated and should be dropped. The genuine gaps are: search-within-archive, line-oriented reads, a section/positional index, decoded (un-escaped) paging, and previews. Separately: Shell stdout is tail-truncated at capture time (head dropped), so "recover the complete output" is an upstream Shell capture/preservation contract, not something ArchiveRead can deliver alone. Split into two problems.
    • Add Runtime v2 implementation skeleton #5 (bypass) — AskUserQuestion genuinely has no permission authority (it returns selected text only), and there is intentionally no model-invokable switch-to-bypass (bypass is a user privilege). But the remedial control already ships: RequiresBypassBanner → setPermissionMode('bypass') → regenerate, with a fresh boundary read on the next call. So "add an actionable control / re-read boundary on retry" is already done. The remaining real gaps are (a) steering the model away from presenting an AskUserQuestion option that looks like it switches modes, and (b) an observable permission_mode_changed event so the change is visible without a blind retry. Retitle to "Align requires_bypass model guidance, native banner handling, and observable boundary-transition state."
    • Wire RuntimeRunner through SessionManager #7 (WriteStdin) — confirmed: the provider-visible schema and the strict validator diverge (payloads the loose schema accepts are rejected after normalization; the validator also accepts an input field the schema doesn't advertise). This is intentional provider tolerance (providers inject null/0 placeholders) and is already backstopped by a normalizer + a conformance test. But the contract is still model-hostile: from the published schema the model can't derive a reliable minimal key payload. Fix = an end-to-end conformance pipeline (loose provider schema → normalizer → discriminated union → strict validate) with at least one minimal legal example per action type, plus a minimal example in the tool description. Keep both layers; don't collapse to one union.

    Reclassified: existing mechanism, investigate presentation — do not build a second authority

    • Persist RuntimeEvents per AgentRun #10 (completion/retry state) — the backend already has terminal-state events (run_completed|failed|cancelled), continuation admission, provider-retry events, and a durability latch (agent-run.ts). So: no second terminal-state authority. But the session's actual problem — user/model couldn't tell whether the previous response was fully delivered — may live in streaming delivery / renderer / remount / persistence, not the state model. Mark investigate: given a persisted terminal AgentRun, does Desktop distinguish fully-rendered / persisted-but-partially-delivered / output-limited / interrupted-before-terminal? If the projection already answers, it's UI-only; if not, add projection fields.
    • Add RuntimeEvent read model projection #12 (task progress) — Agent Graph projection, timeline rollup, task-ledger ownership (child→main), and a desktop progress panel already exist. Not a missing model. If ordinary tool-heavy turns feel opaque, that's whether such turns enter these projections and how prominently the UI shows them — a product-presentation/scope discussion, better tracked under the desktop-UX umbrella than here.

    Confirmed as real gaps

    • Add Rive workflow Maka tool #1 (PATH/dylib) — confirmed and, if anything, sharpened. Readiness probes a fixed /bin/sh -c true and renders Command sandbox: available; it does not prove the selected executable can load its dylib closure. A full Mach-O dependency resolver already exists but only serves Maka's own Node/ripgrep helpers — ordinary Bash commands don't reuse it. Retitle to: "Command-sandbox availability proves shell construction, not that the selected executable can load its runtime dependency closure." Fix should stay cautious — resolving the initial Mach-O closure does not cover runtime dlopen, plugins, or child processes using different executables, and boundary expansion must be bounded and logged (explicit executable → bounded dependency resolution → read-only expansion → record actual expansion). At minimum, report dependency_blocked accurately in readiness.
    • Harden runtime, storage, gateway, credentials, and IPC inputs #2 (/tmp) — confirmed code inconsistency: the Bash path passes literal /tmp while every other path (diagnostics, fs-worker) canonicalizes to /private/tmp; on macOS /tmp is a symlink, so a writable subpath "/tmp" can miss a write the kernel resolves under /private/tmp. Status: confirmed inconsistency + runtime hypothesis + needs macOS reproduction. Split into a small bug ("canonicalize /tmp consistently before building the macOS Bash sandbox") with an acceptance test that actually writes to a real mktemp /tmp/... file, not just asserts a policy string.
    • Document Runtime v2 architecture evolution #4 (GitHub research) — confirmed: no native structured GitHub tools exist; the only surface is generic WebFetch/WebSearch (+ shell gh), and WebFetch returns truncated page text with no canonical URL/author/state/labels/comments. Open question is placement: a GitHub Research skill/plugin (anonymous-first REST + Discussions fallback, lazy-loaded via tool-search) is the lower-risk near-term option; promote to a core forge adapter once usage justifies it. Note there is no GitHub credential path in the repo today, so "unauthenticated-first" must handle 401 and the Maka-Agent/maka-agent → apache/maka redirect internally.
    • Fix Runtime v2 runner and flow contracts #6 (browser visibility) — this is the one I initially mis-called "refuted by source," and I'm retracting that. Source enforces a strong visible-lease invariant ("every action must target the conversation on screen; the agent can never drive or read a view the user can't see"). But the session observed: browser_navigate succeeded to a GitHub login page, browser_snapshot read content, snapshot reported viewport: 0x0, and the user explicitly said they couldn't see the browser; the working fallback was open https://github.com/login/device. A source invariant cannot overrule a first-hand "I can't see it." Correct verdict: runtime/source contradiction — identify the active browser provider/build/composition and add conformance telemetry (tool provider id, Runtime Host revision, desktop build revision, browser session id, visible-lease state, actual viewport dims, panel mounted/selected). The independent gaps the audit did confirm still stand: open-in-system-browser, a device-code/OAuth handoff primitive, a hard credential-entry boundary, and post-auth session-reuse policy.
    • Wire AiSdkFlow into SessionManager runtime path #9 (capability groups) — confirmed and likely the best effort/value ratio: native tools currently collapse into a synthetic other group, while a real taxonomy (categoryHint/ToolCategory) already classifies every tool for permissions. Wiring that into tool-search groups needs no schema loading. Confirm first: permission-category vs discovery-category semantics match, a tool may need multiple discovery tags, other stays as fallback, and grouping never changes permissions. The Paseo skill naming/tool mismatch (create_agent vs agent_spawn, product/CLI/state-dir divergence) is real but originates from an external, user-global skill — so any "validate a skill's declared tools exist" work is about hardening against externally-installed skills and should warn, not hard-fail.

    Recommendation

    Keep the issue — it records real experience and the audit found nothing fabricated. But drive follow-up from the verdict table, and split sub-issues only for the highest-confidence items first: macOS Bash dependency/canonicalization, tool-search native groups, GitHub research capability, ArchiveRead search/line reads, browser-visibility conformance, and the WriteStdin schema-pipeline conformance.

  2. Astro-Han commented on Aug 30, 2026

    @Astro-Han
    Contributor

    The sandbox findings here appear to share one architectural cause and should not be addressed through separate path exceptions or additional model-side negotiation state.

    I suggest converging the sandbox design through #3629:

    • one revisioned, Session-scoped SandboxPolicy: auto | full_access | external;
    • Runtime evaluates ordinary tool calls before first dispatch;
    • approval and policy changes are owned by Runtime, not the model;
    • remove request_sandbox_boundary, boundary_intent, required_boundary, and negotiation counters;
    • Bash runs under the current policy without per-command escalation;
    • platform toolchain dependencies are provided by a fixed, read/execute-only backend substrate rather than an expanding path allowlist.

    #4234 has already addressed /tmp canonicalization. The remaining Command Line Tools/Homebrew failures should help define and test the backend substrate, while #3629 owns the cross-platform architecture decision.

    Concrete reproducible failures can remain scoped sub-issues, but they should converge on this shared Runtime-owned model rather than introduce independent fixes.

    中文

    这里的多项 sandbox 问题具有共同的架构根因,不应分别通过路径特例或新的模型侧协商状态解决。

    建议统一通过 #3629 收敛:

    • 使用唯一、Session 级、带 revision 的 SandboxPolicy;
    • Runtime 在工具首次执行前完成判定和审批;
    • 删除模型侧提权工具、声明参数和 negotiation counters;
    • Bash 只在当前 policy 下执行,不支持逐命令提权;
    • 系统工具链依赖由 backend 提供固定的只读/执行 substrate,不再不断扩张路径白名单。

    #4234 已解决 /tmp canonicalization。剩余 Command Line Tools/Homebrew 问题应作为 backend substrate 的真实验收场景。具体故障可以拆分子 Issue,但最终都应收敛到同一个 Runtime-owned 架构。

    AI assistance disclosure: OpenAI Codex, Claude, and K3-256K assisted with the architecture and naming analysis. I reviewed this proposal and take responsibility for it.

  3. liugddx commented on Aug 31, 2026

    @liugddx
    MemberAuthor

    Follow-up tracking review (2026-08-31)

    A review of the current public issue/PR graph shows that implementation has started, but the post-audit work has not yet been split into native GitHub sub-issues.

    Direct implementation underway

    • fix(runtime): admit macOS Bash toolchain dependencies #4279 — open, non-draft, unmerged: fix(runtime): admit macOS Bash toolchain dependencies (Refs #4267). It adds a fixed read/execute-only substrate for Homebrew package roots and Apple developer roots, treats inaccessible Git global/system config as absent, and adds real Seatbelt regression coverage for Homebrew and Apple Git startup.
    • This directly addresses the reported macOS dylib/toolchain failure in item 1, but it is not yet a general executable dependency-readiness probe and does not state that it fixes the /tmp ↔ /private/tmp inconsistency in item 2.

    Existing related tracking

    These issues/PRs overlap with parts of the umbrella but are not replacements for the narrowed post-audit gaps:

    The archive work above fixes registration/composition and storage concerns. It does not cover the remaining item 3 requirements: search within an archive, line-based reads, section indexes, and decoded paging.

    High-confidence work not yet found as dedicated tracking

    No dedicated public issue/PR was found for the following narrowed work items:

    • item 2: macOS /tmp → /private/tmp canonicalization repro/test and remaining fix;
    • item 3: ArchiveRead search, line reads, section index, and decoded paging;
    • item 4: structured, unauthenticated-first GitHub Issue/Discussion research tools;
    • item 5: requires_bypass model guidance plus an observable boundary-change event;
    • item 6: browser visible-lease/provider/build conformance investigation for the observed viewport: 0x0 drive;
    • item 7: WriteStdin provider-loose-schema → normalizer → discriminated union → strict-validator conformance and minimal per-action examples;
    • item 9: wiring categoryHint / ToolCategory into deferred native-tool search groups;
    • item 10: persisted terminal response state versus actual Desktop delivery/render conformance.

    Items 8 and 11 were withdrawn by the audit. Item 12 should remain a product-presentation/scope discussion over the existing projection rather than create another progress authority.

    Suggested issue split

    To make this umbrella actionable and independently reviewable, create dedicated issues in this order:

    1. macOS temp-root canonicalization conformance (item 2);
    2. deferred-tool native category groups (item 9);
    3. WriteStdin schema-pipeline conformance (item 7);
    4. ArchiveRead search/line-read/index ergonomics (item 3);
    5. structured public GitHub research capability (item 4);
    6. browser visible-lease conformance telemetry/investigation (item 6);
    7. requires_bypass guidance and boundary-change observability (item 5);
    8. terminal-state persistence versus Desktop delivery/render investigation (item 10).

    At the time of this review, #4267 remains open with no assignee or milestone, and GitHub reports sub_issues_summary.total = 0. #4279 is the only direct implementation PR found that explicitly references #4267.

  4. liugddx commented on Sep 1, 2026

    @liugddx
    MemberAuthor

    Additional live-session conformance evidence

    A second extended session exercising this umbrella reproduced several of the original friction areas and exposed one narrower catalog/invocation defect that should be tracked separately.

    Directly reproduced

    • Item 3 — ArchiveRead ergonomics: large GitHub/API/shell results repeatedly required inspect -> read(offset) -> read(next offset). There was no archive-local search or line coordinate space, and locating later objects in archived JSON required guessing character offsets. This materially increased tool calls and made selecting/copying the correct archive ref error-prone.
    • Item 4 — GitHub research: reconstructing Issue/PR status required WebFetch, GitHub REST Search, direct REST endpoints, browser capability, authenticated gh, GraphQL review-thread queries, and local Git refs. Direct comments/timeline calls sometimes returned 403 while Search remained usable. Search also produced lexical false positives that had to be manually distinguished from explicit Refs/Closes relationships.
    • Item 5 — boundary UX: browser and Windows shell work reported requires_bypass / sandbox unavailable. The Session boundary could not be changed by an ordinary question response; the user had to switch to Bypass manually and send another turn before work could continue.
    • Item 6 — browser visibility conformance: the automated browser snapshot again reported viewport: 0x0. Its GitHub context was logged out while the local gh CLI was authenticated through the keyring. This is fresh runtime evidence for the visible-lease/provider/build investigation and for the missing user-authentication handoff.
    • Item 9 — capability discovery: deferred capability discovery remained difficult enough that shell/browser fallbacks were needed before the effective capability map was clear.
    • Item 12 — progress presentation: during long PR review work, raw tool/archive traffic was visible but task-level phase/completion was not sufficiently legible; the user had to send “continue” more than once. This supports treating the remaining gap as projection delivery/presentation rather than creating another progress authority.

    Runtime/source mismatch evidence

    The current Client-visible Bash invocation schema still required explicit values for:

    {
      "timeout_ms": 120000,
      "run_in_background": false,
      "pty": false,
      "boundary_intent": "current"
    }

    Item 8 was withdrawn after the source audit because these fields are optional/defaulted in main. The observed required schema should therefore be investigated as Client/provider-schema/runtime-composition conformance evidence, not as a reason to restore the withdrawn design proposal unchanged.

    Newly narrowed defect: Agent catalog → invocation conformance

    The session attempted to delegate three read-only PR reviews. agent_list advertised:

    agent_id: local-read
    profile: local_read
    status: available
    

    but three subsequent agent_spawn calls using that advertised identity all failed with:

    Unknown subagent_id "local-read". Call agent_list first.
    

    agent_list had just been called. This is adjacent to item 9, but more specific than capability-family grouping: the discovery surface and invocation surface expose incompatible identity/profile namespaces and the repair text is not actionable. It should be split into a dedicated catalog/invocation conformance issue with an acceptance test of:

    list available agent/profile
    -> select the returned callable identity
    -> spawn succeeds, or list marks it non-callable and provides the exact supported selector
    

    Adjacent observations, not yet claimed as #4267 defects

    • A dirty workspace with extensive tracked deletions was discovered only after repository work began. A scoped readiness projection could surface branch/dirty-state facts earlier, but the workspace condition itself is not necessarily a Maka defect.
    • Several malformed/poorly composed PowerShell Git commands timed out with no output. Those calls were corrected by the agent; richer timeout/pager/process-state diagnostics would help, but the command error itself should not be attributed to Maka.
    • GitHub 403 responses may originate from upstream rate limits/auth policy. The Maka concern is the lack of one structured fallback path, not that every external failure is a harness defect.

    No P0 authority violation or data-loss behavior was observed. The dominant cost remained plumbing between mechanisms that individually exist but are not yet easy to discover, compose, or hand off.

  5. liugddx commented on Sep 4, 2026

    @liugddx
    MemberAuthor

    Follow-up audit evidence: Windows sandbox, child-run provenance, and long-operation continuity

    This is a follow-up from another real extended Maka session on Windows. The task was a long desktop release flow involving repository inspection, an isolated release worktree, deterministic tests, packaging, artifact upload, and online verification.

    This comment does not propose reopening the ArchiveRead interface work already marked resolved. It records new reproductions and suggests routing them into focused issues.

    Summary

    The session exposed six distinct problems:

    1. An approved Windows execution boundary still could not instantiate managed Bash.
    2. The same sandbox failure also blocked structured filesystem tools through an ACL-ledger mutex.
    3. Agent discovery returned identifiers that agent_spawn did not accept.
    4. Jans/worktree child execution rejected a dirty parent even though the requested child was commit-isolated.
    5. A completed scheduled agent_run did not expose a durable child result or receipt to the parent session.
    6. Long-running operation, Goal, Agent Graph, and response terminal states were not reconciled into one understandable execution lineage.

    The final external state changed successfully, but the parent session could not retrieve enough evidence to independently prove all requested quality gates and Git operations. This is precisely the type of authority/provenance gap that becomes visible only in a real extended task.


    A. Approved Windows boundary, but managed Bash remained unavailable

    Reproduction

    The parent session requested:

    • write access to the repository subtree;
    • process network access.

    The boundary request returned an approved managed profile.

    The immediately following PowerShell invocation still failed with:

    Command sandbox is required but unavailable on platform win32.
    

    Retrying with an explicit expanded boundary produced the same error.

    Expected

    Before accepting or applying the boundary, Runtime should know whether the Windows command sandbox can actually be instantiated.

    After approval, a bounded readiness probe should distinguish:

    boundary approved
    command sandbox instantiated
    shell executable launched
    workspace read/write usable
    network usable
    

    Actual

    The UI/API reported a successfully approved boundary, while the effective command capability remained unusable.

    Suggested acceptance criteria

    • On Windows, task readiness includes a real bounded command-sandbox startup probe.

    • An approved boundary cannot be presented as executable until sandbox instantiation succeeds.

    • Failure uses an actionable reason code such as:

      command_sandbox_unavailable
      
    • The failure explains whether retry, Runtime restart, Client restart, or another execution surface is required.

    • An unsuccessful sandbox application does not leave an unnecessarily broad effective grant behind.

    This is related to dashboard item 1, but it is a concrete Windows sandbox-instantiation reproduction rather than another PATH/dependency-closure example.


    B. Sandbox failure also blocked structured filesystem tools

    After the managed Bash failure, ordinary structured file operations such as Read and Glob repeatedly failed with:

    maka-windows-sandbox: acquire ACL ledger mutex timed out
    

    and:

    Filesystem worker failed: worker_io_incomplete
    

    The same error occurred in a read-only child Agent.

    Impact

    This converted one unavailable capability into a session-wide repository outage:

    managed Bash unavailable
      -> filesystem worker cannot acquire ACL ledger
      -> Read/Glob also unavailable
      -> parent and child Agents cannot inspect repository state
      -> no local recovery or diagnosis path remains
    

    The parent session had already received boundary approval, but could neither execute commands nor read files.

    Suggested acceptance criteria

    • A failed command-sandbox initialization must not permanently block structured filesystem tools.
    • ACL-ledger acquisition must have bounded recovery rather than repeated opaque timeouts.
    • Diagnostics should identify:
      • the ledger owner;
      • acquisition start time;
      • stale-lock status;
      • whether automatic recovery was attempted.
    • Runtime should expose a safe session-scoped sandbox reset/reinitialize action.
    • A read-only child should not inherit an unrelated stale write-boundary mutex.

    Suggested focused issue:

    fix(windows-sandbox): approved boundary can leave Bash unavailable and filesystem workers blocked on the ACL ledger
    

    C. agent_list identifiers were not accepted by agent_spawn

    Reproduction

    agent_list advertised legacy profiles including:

    local-read
    implementation
    

    The parent then called agent_spawn with the advertised identifier:

    subagent_id = "local-read"
    

    Runtime rejected it with:

    Unknown subagent_id "local-read". Call agent_list first.
    

    agent_list had already been called.

    Expected

    Every identifier advertised as spawnable should either:

    1. be directly accepted by agent_spawn; or
    2. include an explicit invocation mapping, for example:
    {
      "id": "local-read",
      "invocationKind": "legacy_profile",
      "spawnField": "profile"
    }

    Actual

    Discovery and invocation used incompatible identity namespaces, and the recovery message incorrectly asked the caller to repeat an operation it had already performed.

    This is a current independent reproduction of the catalog-to-invocation identity mismatch mentioned under dashboard item 9. It should not reopen capability-family discovery itself.

    Suggested acceptance criteria

    • Add a conformance test that invokes every item returned by agent_list using its advertised invocation shape.
    • Distinguish agent_id, subagent_id, and legacy profile in the schema.
    • Do not return “call agent_list first” when the current session has already done so.
    • Unsupported legacy profiles should be marked non-spawnable rather than advertised as available.

    Suggested focused issue:

    fix(agent-orchestration): identifiers returned by agent_list must have a valid agent_spawn invocation
    

    D. Commit-isolated worktree child was blocked by a dirty parent

    A requested implementation child failed during topology provisioning with:

    Worktree child execution requires the source Git worktree to have no uncommitted changes
    

    The task explicitly requested an isolated release worktree based only on the latest committed source and explicitly prohibited including or overwriting parent uncommitted changes.

    Why this is surprising

    A Git worktree created from a named commit does not need to include parent working-tree changes. Requiring a clean parent removes much of the value of commit-isolated child execution:

    parent has unrelated untracked/modified files
      -> child should start from parent HEAD
      -> child receives no uncommitted parent content
      -> parent remains untouched
    

    Suggested acceptance criteria

    • Worktree child execution can start from an explicit commit while the parent working tree is dirty.
    • The UI clearly states that uncommitted parent changes are excluded.
    • If the user requests inclusion of uncommitted changes, Runtime can:
      • create an explicit patch/snapshot;
      • request confirmation;
      • or reject that different operation.
    • Unrelated untracked files do not block a commit-based isolated child.
    • Failure diagnostics identify the exact policy and available alternatives.

    Suggested focused issue:

    fix(agent-worktree): allow commit-based isolated child execution from a dirty parent worktree
    

    E. Completed scheduled Agent had no durable result link

    As a fallback, the session created a one-shot scheduled task with an agent_run effect.

    The scheduled-task list later reported:

    <task title> | completed | effect=agent_run
    

    However, the completed task did not expose:

    • child session ID;
    • child run ID;
    • result record ID;
    • terminal response;
    • artifact references;
    • command/test receipts;
    • start and finish timestamps.

    The parent could verify that the external stable manifest changed from one version to the next, but could not retrieve the child execution evidence needed to prove:

    • complete quality gates passed;
    • packaged smoke passed;
    • the expected release branch was pushed;
    • the expected Git tag was pushed;
    • each online binary was independently downloaded and hashed.

    Expected result shape

    A completed agent_run should expose something similar to:

    {
      "taskId": "...",
      "status": "completed",
      "sessionId": "...",
      "runId": "...",
      "resultRecordId": "...",
      "startedAt": "...",
      "finishedAt": "...",
      "artifacts": [],
      "terminalState": "completed"
    }

    The parent should be able to call a direct operation such as:

    ScheduledTask get-result <task-id>
    

    Scope note

    This is not an ArchiveRead retrieval-ergonomics problem. ArchiveRead cannot retrieve a result that ScheduledTask never links into the parent-visible execution lineage.

    Suggested focused issue:

    fix(scheduled-agent): completed agent_run must expose its child run and durable result receipt
    

    F. SearchHistory first-page cursor appeared impossible to construct

    The parent attempted to locate the scheduled child through history search.

    The visible invocation required a cursor. Candidate initial values such as "0" and "/" were rejected with:

    Search cursor is invalid or belongs to another query.
    

    If the backend only accepts a continuation cursor produced by an earlier query, the first query has no valid cursor source.

    Suggested acceptance criteria

    • The first search request allows the cursor to be omitted or set to null.
    • Only continuation requests require a server-issued cursor.
    • The schema documents the first-page call separately from pagination.
    • A minimal provider-visible first-page payload has a conformance test.

    Suggested focused issue:

    fix(history): allow first-page SearchHistory calls without a continuation cursor
    

    This is a new schema/runtime-contract reproduction, not a reopening of the resolved WriteStdin case.


    G. Agent Graph repeatedly emitted a terminal checkpoint with no usable result

    The Agent Graph entered a terminal state containing:

    • one superseded work item;
    • one topology failure;
    • zero running operators;
    • no selected result.

    The same durable supervisor checkpoint was injected repeatedly with the same snapshot hash, asking the parent to inspect the graph and read child results even though no child result existed.

    Expected

    • A given terminal snapshot is surfaced once unless its state changes.
    • A fully terminal graph closes or presents one explicit recovery action.
    • The supervisor does not request agent_output view=result when no result record exists.
    • Topology failures are rendered as terminal failures with actionable alternatives.

    Actual impact

    The repeated checkpoint messages consumed turns and context without changing the graph or enabling recovery.

    Suggested focused issue:

    fix(agent-graph): deduplicate terminal supervisor checkpoints and do not request nonexistent child results
    

    H. Goal continuation did not share evidence with child execution

    The parent created a Goal with explicit acceptance conditions covering:

    • isolated release worktree;
    • quality gates;
    • packaged smoke;
    • branch/tag push;
    • online artifact verification.

    The continuation layer later reported:

    Evaluator call failed (continuing)
    

    Meanwhile, the scheduled child independently completed, but its result was not attached to the Goal evidence.

    Expected

    Goal evaluation should consume the structured receipts of foreground, graph, and scheduled child operations.

    Suggested acceptance criteria

    • Goal evidence can reference child run/result IDs.
    • An evaluator failure exposes a bounded reason code and retry state.
    • A Goal does not keep iterating solely because completed child evidence is unreachable.
    • External-state verification and child receipts remain distinguishable:
      • “online version changed” is evidence;
      • it is not by itself proof that all quality gates passed.

    I. Current reproduction of the invisible-browser handoff problem

    During this follow-up, browser navigation to a public GitHub issue succeeded, but the snapshot reported:

    viewport: 0x0
    

    The automation context was not authenticated and exposed only a login link. The user could not be asked to authenticate in that invisible browser safely.

    This is current evidence for dashboard item 6. It does not establish a new ownership model, but it supports opening the focused telemetry/reproduction issue requested by the current dashboard.

    Useful telemetry would include:

    • browser context/lease ID;
    • visibility state;
    • viewport;
    • owning conversation;
    • whether user takeover is supported;
    • whether “Open in my browser” is available;
    • authentication handoff state.

    J. Intent-only terminal replies were indistinguishable from started work

    In the same session, the assistant twice produced terminal responses equivalent to:

    I will now open the issue and submit the comment.

    No browser or write operation had started before those terminal responses. The user had to ask:

    Did you do it?

    and then:

    What are you doing?

    This is partly model behavior, but the harness provided no authoritative operation state next to the terminal response:

    declared action: submit issue comment
    actual operation: none started
    assistant terminal state: completed response
    task state: unclear
    

    This is additional evidence for dashboard items 10 and 12:

    • response completion is not task completion;
    • natural-language future intent must not be the only task progress signal;
    • the user needs an authoritative projection showing whether an operation actually started.

    A product-level progress projection should derive from Runtime facts such as:

    not started
    running
    waiting for user/authentication
    completed
    failed
    interrupted
    

    It should not infer completion from assistant prose.


    Suggested routing against the current #4267 dashboard

    Evidence Route
    Windows command sandbox unavailable after approved boundary New focused Windows reproduction under item 1
    ACL-ledger mutex blocking filesystem workers New focused Windows sandbox issue
    agent_list/agent_spawn identity mismatch Separate issue permitted by item 9's current disposition
    Dirty parent blocking commit-isolated child worktree New Agent orchestration/workspace issue
    Scheduled child result not linked to parent New scheduled-execution provenance issue
    Impossible first-page SearchHistory cursor New schema/runtime conformance issue
    Repeated terminal Agent Graph checkpoint New Agent Graph supervisor issue
    Goal evaluator unable to consume child evidence Goal/evidence integration issue
    Invisible unauthenticated 0x0 browser Current reproduction for item 6
    Intent-only terminal replies with no operation Additional evidence for items 10 and 12

    Priority recommendation

    1. Windows sandbox/ACL-ledger recovery.
    2. Durable child-run result/provenance across ScheduledTask, Agent Graph, and Goal.
    3. Catalog-to-invocation and SearchHistory schema conformance.
    4. Commit-isolated child worktree semantics.
    5. Browser visible-lease telemetry.
    6. Response/task terminal-state projection.

    The central new finding is that the harness can now discover tools and archive bounded results, but it still cannot reliably answer, across execution surfaces:

    Which run performed this work, what is its authoritative terminal state, where is its durable result, and which acceptance evidence belongs to it?

  6. added
    staleNo qualifying activity within the lifecycle policy window
    on Oct 4, 2026
  7. github-actions commented on Oct 4, 2026

    @github-actions

    This issue has had no human activity for 30 days and has been marked stale. It will be closed in 30 days unless someone comments.

    If the issue is still current, please confirm it against the latest main and add any information that would help move it forward. Assigned issues and issues labelled pinned are exempt from this policy.

  8. liugddx commented on Oct 8, 2026

    @liugddx
    MemberAuthor

    Status refresh against main@49e01b157. Keeping this open, because five rows still have no completed delivery:

    #4452 (ArchiveRead convergence, referenced in row 3) closed as not planned, so row 3 has no remaining follow-up here. Once rows 1, 3b and 4 have their own issues or merged fixes, I'll close this tracker.

  9. removed
    staleNo qualifying activity within the lifecycle policy window
    on Oct 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesttrackingTracking or umbrella issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions