session-persistence抢占session.lock导致插件无法resume

[xfangbo]

我有一个DSH插件，触发运行后会dispose；
然后如果在DSH里打开这个session，只是打开，什么都不做；
然后插件触发resume就会报错：session "dsh-xxxxxx-032b77e23bc41872" is already owned by an active write handle

分析了下是DSH打开session时就占了写锁session.lock，感觉这个不合理，打开session只是看看，应该是发送prompt时再去占session.lock比较合理点。

:deepseek-harness $ find . -type f | xargs grep -ni "is already owned by an active write handle" 
./packages/session/session-persistence/tests/storage-contract.spec.ts:297:    expect(owned.message).toBe('session "errored" is already owned by an active write handle')
./packages/session/session-persistence/src/errors.ts:34:    super(`session "${sessionId}" is already owned by an active write handle`)
:deepseek-harness $ git log -1
commit ddefc45fbc7f8e46dd73185e68295696d1297887 (HEAD -> master, tag: dsh-v0.1.6-alpha.2, origin/master, origin/HEAD)
Merge: 8dfc6fe1ec 6b1808f432
Author: CreatixChu <142372241+CreatixChu@users.noreply.github.com>
Date:   Thu Sep 17 21:19:19 2026 +0800

    Merge pull request #4469 from deepseek-harness/worktree/release-dsh-0.1.6-alpha.2
    
    release(dsh): 0.1.6-alpha.2
:deepseek-harness $ 

以下是codex的分析：

结论：我按远端 master 的最新源码核对后，DSH 仍是之前的逻辑。
正常打开 session 的链路是：

1. 客户端打开 live event stream。
2. history.follow() 先返回 snapshot。
3. 对 prepared session，返回 snapshot 后立即后台调用 promote()。history.ts
4. promote() 会尝试 agents.resume()；如果没有现存 Agent，就进入 Agent resume 流程。session-controller、agent.ts
5. Agent loop 最终执行 persistence.open(id, 'write')，JSONL persistence 原子地抢占写锁。agent-loop、session-persistence
   所以：

• “打开但不执行模型”不等于“不占写锁”；Agent 激活本身就会占写锁。
• 切换到其他 session 也不一定释放锁。当前客户端设计会让 session 常驻，off-screen 的 Remote source 继续运行。client Session
• 最新代码主要只是把冲突错误规范化为 session/writer-held，没有取消自动 promote/resume 的行为。
• page() 等只读路径不会激活 Agent，但普通 UI 打开走的是 live follow 路径。
  因此，之前判断仍成立：插件持有 reservation 时，DSH 可以先显示 session snapshot，但后台激活会失败并提示 session/writer-held；要让 DSH 真正“只读打开”，仍需要 DSH 提供或使用 read-only open 模式。

[argszero]

I hit this same wall from the plugin side while building out-of-tree plugins, so here is what the mechanism actually is — read out of the tree at the commit you quoted (ddefc45f, dsh-v0.1.6-alpha.2), not inferred.

One writer per session, enforced in two layers

• in-process: tracker.claimWrite(id) — packages/session/session-persistence-jsonl/src/storage.ts:429
• cross-process: the kernel lease on <session dir>/session.lock — packages/session/session-persistence-jsonl/src/lease.ts:71-115 (POSIX exclusive lock; a Win32 sharing violation on the other path)

Both raise the same SessionAlreadyOwnedError carrying exactly the message you saw (packages/session/session-persistence/src/errors.ts:34), and the API path normalizes it to the stable code session/writer-held (packages/api/session-controller/src/agent.ts:218-219).

Only a write open claims. The read branch of open() never touches ownership (session-persistence-jsonl/src/index.ts:344-364); the write branch claims as its first action (:365). And the agent loop takes the write handle before it reads or repairs anything — deliberately:

// Taking write ownership FIRST excludes a concurrent resume of the
// same id (in this process, a live agent's handle holds the claim).
handle = await raceAbortCall(() => persistence.open(id, 'write', { signal: fused }), ...)

(packages/core/agent-loop/src/index.ts:891-895)

So the error means: an activation for that session already exists and is holding the handle. Your sequence — DSH opened the session, then your plugin resumed — is precisely the case that comment names.

Why "just opening" claims it. history.follow() yields the snapshot and then, when the observed source is prepared, calls promote(...) (packages/api/session-controller/src/history.ts:203-206), which resolves/activates the agent in the background (session-controller/src/index.ts:173-184). Activation = agent loop = write claim, held for as long as the handle lives.

The asymmetry that bites plugin authors. The Host API's resolve path returns an already-live agent before it attempts anything (liveAgent(sessionId) at agent.ts:187-188), so the same session that fails from your plugin works fine from the UI. ctx.agents.resume() has no such pre-check — it goes straight to the factory and the write open.

What a plugin can do today (first-party precedents, all in-tree)

const live = ctx.agents.get(id)                  // public: AgentRegistry.get
if (live !== undefined) live.followup(message)   // deliver to the live agent — no write claim
else await ctx.agents.resume(ctx, { resumeSessionId: id, ... })   // safe: nobody holds it

• packages/api/session-controller/src/commands.ts:359-361 does exactly this shape for user prompts: guard "the agent I hold is still the registered one", then agent.steer(message) / agent.followup(message).
• packages/subagent/subagent/src/inbox.ts:54 and packages/schedule/schedule/src/index.ts:50 + runtime.ts:161,273 do the same: attach to live agents, re-check liveness (ctx.agents.get(agent.id) === agent && ctx.agents.roots().includes(agent)) before acting, deliver with followup, and never resume.

That is your "claim only when you actually run" — it already exists at the agent-object level; what does not exist is a resumeIfLive() helper on the service.

Which of the two layers you are on (they produce the same message): at the moment of failure, is ctx.agents.get(id) non-undefined?

• non-undefined → a same-process live agent; the pattern above removes the collision entirely.
• undefined → another process holds the kernel lease. Note the POSIX session.lock file is never removed when a lease is released (lease.ts), so the file's existence proves nothing — the holder is identified by the exclusive lock on it, not by the file.

Boundary on the core side. There is no read-only live-open path: every activation claims write up front, by design, and nothing today lets a plugin make the UI release it. Your proposal — claim on prompt rather than on open — is therefore a core change (either a lazily-claimed write, or a genuinely read-only follow path), and that is worth stating explicitly as the ask if this becomes an upstream report. The plugin-side pattern only protects the plugin's own resume; it cannot make "just looking" free.

On the observability half: session/writer-held is handled in exactly one client path (packages/client/ui-model-selection/src/client/index.ts:169); everywhere else it surfaces raw or is swallowed, which is why the experience is "it just fails".

One fact would sharpen this a lot: does your trigger run inside the dsh host process or in a separate one? That single answer decides which of the two locks you are hitting — and whether the fix can live in your plugin at all.

[argszero]

Two corrections to what I wrote above, and a plugin that removes the wall.

Correction 1 — ctx.agents.resume() takes ONE argument, not two. The two-argument (ownerCtx, options) form is AgentFactory.resume, which a plugin never calls. The registry wrapper is:

await ctx.agents.resume({                                  // packages/core/agent/src/index.ts:407
  resumeSessionId: id,
  agentOptions: ctx.agentDefaultModel.currentSelection(),   // optional; this is what the Host API passes
  setup: composition.setup,                                  // optional
})

Checked against the canonical call site (packages/api/session-controller/src/agent.ts:437, packages/bundle/headless/src/index.ts:279) and the field list in ResumeAgentOptions — resumeSessionId is the only required field. The snippet in my previous reply would not have compiled as written.

Correction 2 — the diagnostic sentence about "which layer" needed a sharper form, now that I have read lease.ts end to end: the POSIX session.lock file is left in place when a lease is released, so the file's presence is not evidence of a holder at all. The runtime discriminator stays ctx.agents.get(id) at failure time.

A plugin now exists for this gap. @argszero/cordis-plugin-session-trigger — resume-or-deliver:

• ask the registry first, so the live case never attempts a resume;
• resume only when nobody holds the session;
• adopt a losing race instead of failing it — if the claim is lost to an activation that registered meanwhile, the message is delivered to that agent;
• when the session really is held, fail with a diagnostic that names both layers (this process's write claim, or another dsh process holding session.lock) and what to do about each.

import { deliverToSession } from '@argszero/cordis-plugin-session-trigger'

const { path } = await deliverToSession({ agents: ctx.agents }, { sessionId, message })
// 'live' | 'live-after-race' | 'resumed'

• npm: https://www.npmjs.com/package/@argszero/cordis-plugin-session-trigger
• source: https://github.com/argszero/cordis-plugin-session-trigger

Mounted (cordis.patch.yml insert, config mode: followup|steer, retain: true|false) it registers ctx.sessionTrigger, keeps every agent it resumed — the queued turn needs the handle alive — and disposes all of them on unload, which is what frees the claim again.

The package imports no @deepseek-ai/dsh-* module at runtime: it programs against the documented ctx.agents (get, resume) and optional ctx.agentDefaultModel (currentSelection) shapes and matches the refusal by error name with the message as a fallback, so one build serves the 0.1.2 / 0.1.3 / 0.1.5 / 0.1.6 lines.

Its suite runs against a real @deepseek-ai/cordis context and the real SessionAlreadyOwnedError exported by the published dsh-session-persistence — not a lookalike — and it carries a control arm, which is the part I would check first: the naive ctx.agents.resume() this plugin replaces must fail on a live session inside the same fixture where the plugin succeeds. 15 tests, and 6 mutations of the plugin's own logic were each confirmed to turn the suite red.

The boundary, stated plainly: this makes your plugin's delivery robust. It does not make "just looking" free. Nothing in the harness today releases the claim an activation takes on open, so if the ask is "the UI should not claim a session merely because it is displayed", that is still a core change — the plugin only stops plugin authors from being the casualty of it.

[argszero]

A correction to my own announcement above, and a fix: 0.1.0 could not be installed.

If you followed the link and ran npm i @argszero/cordis-plugin-session-trigger, you got this instead of a working plugin:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@deepseek-ai/schemastery'
imported from .../node_modules/@argszero/cordis-plugin-session-trigger/lib/index.js

The built lib/index.js imports @deepseek-ai/schemastery (the schema layer behind Config), but 0.1.0 declared it only under devDependencies. In my repo the specifier resolves — pretest builds, and the workspace tree has the package — so the test suite could not see it. The only thing that can see it is a clean project installing the published tarball, and I checked the artifact by installing the tarball I had just packed rather than by name from the registry. Same bytes, different resolution: the tarball install had the dependency available in the tree, the by-name install did not. That is the whole gap, and it is the same defect I had already fixed twice in this package family (search-budget 0.1.0, credential-rotate 0.1.1) — which means the lesson I had written down did not survive contact with a new package.

Fixed in 0.1.1 (npm latest, repo 936559d):

• @deepseek-ai/schemastery is declared in dependencies, which is what in-repo consumers do (packages/core/tools, packages/llm/llm-deepseek both declare it there rather than as a peer).

• Added test/packaging.spec.mjs, which scans the built lib/ and the src/ for bare specifiers and asserts each one appears in the manifest — and asserts the reverse too, that nothing declared goes unimported. The guard is not decoration: with the dependencies block removed it fails with

  lib/ imports @deepseek-ai/schemastery but package.json declares only @deepseek-ai/cordis —
  a clean install of the published tarball will fail with ERR_MODULE_NOT_FOUND
  

  which is the exact diagnostic I would have wanted an hour earlier.

Verified on 0.1.1: 18/18 tests (15 behaviour + 3 guard); the guard fails on the real 0.1.0 defect and passes on the fix; the packed tarball installs and imports cleanly; and the 15 behaviour tests pass against the installed artifact, with the import resolving to @argszero/cordis-plugin-session-trigger through node_modules rather than to a local lib/.

The by-name install is now the leading check, not the tarball: npm i @argszero/cordis-plugin-session-trigger in an empty directory, then import it. Nothing else witnesses an undeclared dependency.

The plugin's behaviour is unchanged from what I described above — this was a packaging defect, not a logic one. Apologies for the broken first version.

(If you would like the same check for your own package before publishing: the scan is ~80 lines and depends on nothing but node:fs and node:test — happy to paste it.)

[xfangbo]

@argszero My plugin runs inside the dsh host process.

const live = ctx.agents.get(id)                  // public: AgentRegistry.get
if (live !== undefined) live.followup(message)   // deliver to the live agent — no write claim
else await ctx.agents.resume(ctx, { resumeSessionId: id, ... })   // safe: nobody holds it

This is really helpful, thanks a lot!

[xfangbo]

Update: ctx.agents.get()拿到的agent不一定完成初始化并可安全 followup

---

结论：get(agent.id) 确实可能拿到一个已经进入 registry、但尚未完成 announce() 的 Agent；但 get() 只代表“registry 中存在”，不代表“已经可以安全驱动”。

生命周期应区分为：

状态 | get(id) | agent/created | create/resume() -- | -- | -- | -- setup 中 | 拿不到 | 未触发 | pending ENTERED，已 store.set | 能拿到 | 未触发 | pending ANNOUNCING | 能拿到 | 正在分发 | pending 完成启动 | 能拿到 | 已触发 | resolved

当前 DSH 的 enter() 直接把 Agent 放进 registry，get() 直接读取 registry；announce() 才分发 agent/created。因此 get() 本身不是 readiness 判断。官方实现

不过有两个重要细节：

1. 正常 factory 流程中，setup 完成后会连续执行 publication；普通异步消息处理通常很难插入 enter → announce 之间的极短窗口。
2. announce() 会先把内部状态标记为 announced，再分发 agent/created。而且事件监听器返回的 Promise 并不会成为 announce() 的等待条件。真正更强的 ready 边界是 await agents.create() / await agents.resume()：官方契约是返回 handle 时，setup、发布和 loop 启动都已完成。

所以之前那句话需要修正为：

get(id) 表示 Agent 已经“注册可见”，不等于 Agent 已经“完成初始化并可安全 followup”。

结论：get(agent.id) 确实可能拿到一个已经进入 registry、但尚未完成 announce() 的 Agent；但 get() 只代表“registry 中存在”，不代表“已经可以安全驱动”。 生命周期应区分为： 状态 get(id) agent/created create/resume() setup 中 拿不到 未触发 pending ENTERED，已 store.set 能拿到 未触发 pending ANNOUNCING 能拿到 正在分发 pending 完成启动 能拿到 已触发 resolved

当前 DSH 的 enter() 直接把 Agent 放进 registry，get() 直接读取 registry；announce() 才分发 agent/created。因此 get() 本身不是 readiness 判断。官方实现
不过有两个重要细节：

1. 正常 factory 流程中，setup 完成后会连续执行 publication；普通异步消息处理通常很难插入 enter → announce 之间的极短窗口。
2. announce() 会先把内部状态标记为 announced，再分发 agent/created。而且事件监听器返回的 Promise 并不会成为 announce() 的等待条件。真正更强的 ready 边界是 await agents.create() / await agents.resume()：官方契约是返回 handle 时，setup、发布和 loop 启动都已完成。
   所以之前那句话需要修正为：
   get(id) 表示 Agent 已经“注册可见”，不等于 Agent 已经“完成初始化并可安全 followup”。

当前实现的正确判断应是：
get(id) != undefined
只能说明 Agent 已注册可见

agent/created / 更强的 ready 信号
才能说明它已经完成发布

create/resume Promise resolved
才能说明创建方确认 loop 已启动
因此后续最好让 DSH 提供 whenReady(id)、getReady(id) 或直接提供“已有 Agent 的 acquire/borrow”接口。插件侧如果暂时只能用现有 API，就应监听并缓存 agent/created，至少不要把裸 get() 结果直接当成完全 ready 的 Agent；同时等待期间不要再次调用 resume()