feat(shared): add owner-bound resource references

[testikun]

Problem

Direct Subagent, Workflow, and Background Terminal artifacts currently expose unrelated paths and ids with different completeness and lifetime semantics. Cross-capability consumers cannot tell what value a file is complete relative to, who owns it, whether its generation is stale, or whether receiving the path grants any authority.

Closes #157.

Value

Result details can now carry one compact, versioned reference shape while each producer keeps storage, cleanup, canonical state, and authorization. Consumers get explicit owner/generation/revision/lifetime/completeness metadata without adding a global router or another read tool.

Approach

• add a shared owner-bound file-reference contract for Subagent, Workflow, and Background owners;
• publish only after a regular, non-symlink file exists beneath the producer root;
• distinguish complete owner values from partial projections and name the source-coverage boundary;
• classify invalid, owner mismatch, stale generation, owner lost, unauthorized, traversal, symlink, missing, and stale-revision failures;
• attach references to Direct Subagent CAS results, terminal Workflow result/transcript/agent-result artifacts, and settled Background Terminal spill streams;
• preserve owner-specific lifetimes and Pi-native read/Trust enforcement; add no URI router, global store, index, or model-facing recovery tool.

Validation

• bun run check — passed.
• focused shared reference and three-producer adapter tests — 59 passed, 0 failed.
• full Node 22 suite — 1,248 passed, 1 skipped, 0 failed.
• Vitest suite — 30 passed, 0 failed.

Impact

• User-visible behavior: artifact-bearing result details gain optional resource metadata; no UI changes.
• Model-visible context/tools: no new tools or resident prompt; existing Pi-readable paths remain.
• Runtime/lifecycle: publication is post-write and owner-scoped; references do not extend producer retention.
• Persisted config/data: no config change; terminal Workflow manifests may persist bounded resource-ref metadata.
• Compatibility/risk: additive fields only; legacy details/artifacts remain readable. Revision uses owner generation plus path/file metadata and is rechecked by the owner resolver; it is not advertised as a content hash.

[tt-a1i]

合同是对的；和 #386/#382 叠文件时要注意

占有 ≠ 权限、symlink/穿越/generation fail-closed、Workflow final-result 标 partial-owner-value、没有新的 child tool，这些都对。

两点：

1. publish 失败时 catch { return [] } 是对的（缺 refs 不是完成）。不要把「没有 refs」读成完整性。
2. 和 #386 抢 artifacts.ts / workflow.json。#386 用整份 manifest 字节判断 already-committed；这份若把 resourceRefs 写进同一文件，必须等 #386 改成 run id + 终态 + artifact digest，否则 leftover 收据会把更新后的 refs 盖掉。resolveOwnerFileResourceRef 有测试但还没接到消费路径，保持这样就好，不要先当通用读工具。

可以跟在 #386 收据身份修好之后合。

[tt-a1i]

Exact-head review: 3949855

[P1] A resource reference can resolve successfully after its bytes have changed. extensions/shared/resource-reference.ts:161-171 computes revision from owner, path, byte length, and mtime only; resolveOwnerFileResourceRef() at lines 286-304 rechecks the same metadata. Replacing a file with different same-length bytes and restoring its original mtime therefore returns ok: true for a stale reference. I reproduced this with a four-byte file changed from aaaa to bbbb while preserving mtime.

The contract is meant to let consumers distinguish stale generation/revision and exact terminal evidence; filesystem timestamps are not an immutable byte identity. Please bind the reference to a content digest, or to an owner-provided immutable artifact revision whose write/publication lifecycle guarantees byte identity, and verify it on resolution. Add a same-size/same-mtime replacement regression.

Verification boundary: exact-head code review plus focused local reproduction; no production files were modified.

[testikun]

@tt-a1i 已按依赖顺序处理：#386 先固定 runId/status/artifact digest 身份，#379 再校验 resourceRefs；publish 失败继续 fail-closed，resolveOwnerFileResourceRef 保持独立边界。

[testikun]

@tt-a1i 已修复 P1：resource revision 改用 SHA-256 内容摘要并在 resolve 时重算；同尺寸同 mtime 替换回归已覆盖。

[tt-a1i]

2026-09-09 附件对照（未安装、未运行、未 pi install）。不把本 tip 当成已落地。

#441 Web staging 不要变成第四个 OpenPiResourceOwner。tip 441a37d717c71ff3d2a54b5253dc3bdf19e189d5 的枚举停在 subagent | workflow | background 是对的；resource-reference.ts 里也没有 attachment 字符串。

附件是用户在 Composer 里、按 Send 之前交给 当前 prompt command 的字节：Host 私有、workspace+sessionId+commandId 绑定、单次 consume，然后变成父 Session 的 Pi ImageContent。寿命、授权、cleanup 都不是 execution artifact。占有 staging id 不得授权 child 读取，也不得延长 Host 寿命。

不要为附件加 scheme、第二目录、或模型恢复工具。#379 合入条件不变：无路由器、无新工具、无 child 自动授权。#441 与本 PR 不要互相阻塞。

本地研究稿：docs/research/EXPERIMENT_ATTACHMENTS_2026-09-09.md（未提交）。不重做 #157 已有 taxonomy。

[testikun]

已推送 5b745c6，同步最新 main。当前 PR 已包含内容摘要 SHA-256 绑定及同长度、恢复原 mtime 的替换回归，解析时会重新计算 digest，评审中的 stale-resource 问题已覆盖；resource-reference 专项测试 5/5 通过。