SDK 1.0.4 default session persistence can fail with SQLite "database is locked" in one-shot hosted sessions

[hahahahahaiyiwen]

Summary

After upgrading from GitHub.Copilot.SDK 0.3.0 to 1.0.4, our hosted one-shot runtime intermittently failed during Copilot agent execution with a SQLite lock error from the bundled Copilot CLI.

Disabling infinite sessions and session store avoided the issue.

Environment

• SDK package: GitHub.Copilot.SDK 1.0.4
• Bundled Copilot CLI: 1.0.65
• Runtime OS: Linux container on AKS
• Runtime mode: one request per container/sandbox
• Container env:
  • HOME=/workspace
  • XDG_CACHE_HOME=/workspace/.cache

SDK usage

await using var client = new CopilotClient(new CopilotClientOptions
{
    WorkingDirectory = workspacePath
});

await client.StartAsync(cancellationToken);

await using var session = await client.CreateSessionAsync(
    new SessionConfig
    {
        Model = model,
        OnPermissionRequest = PermissionHandler.ApproveAll,
        Streaming = streamEvents,
        SkillDirectories = skillDirectories
    });

await session.SendAsync(new MessageOptions { Prompt = prompt });

Error

Execution failed: Error: database is locked

Stack trace from the Copilot CLI:

Error: database is locked
    at zde (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:108:22936)
    at XNe (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:112:2212)
    at Qde.executeByType (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:112:3036)
    at Qde.sqlite (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:112:2544)
    at async _J.ensureInitialized (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:112:4942)
    at async _J.execute (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:112:3677)
    at async jye.doLoad (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:823:2329)
    at async jye.getUnreadUnnotifiedEntries (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:823:1500)
    at async QTe.flushPendingNotifications (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:3314:280)
    at async t.runAgenticLoop (file:///workspace/.cache/copilot/pkg/linux-x64/1.0.65/app.js:3346:5502)

Observed behavior

A newly provisioned Linux container starts a Copilot SDK session and sends a single prompt. During agent execution, the  CLI attempts to flush pending inbox notifications and reads  inbox_entries  from a SQLite-backed session database. That  query sometimes fails with  database is locked , causing the session to fail.

The relevant stack path appears to be:

Qde.sqlite
_J.ensureInitialized
_J.execute
jye.doLoad
jye.getUnreadUnnotifiedEntries
QTe.flushPendingNotifications
runAgenticLoop

Expected behavior

A default SDK session should not fail because internal CLI session persistence is temporarily locked. At minimum, SQLite  access should use an appropriate busy timeout/retry strategy, or sidekick/inbox/session-store persistence should not be  enabled by default for SDK-created one-shot sessions.

Workaround

We avoided the failure by explicitly disabling persisted session features:

await using var session = await client.CreateSessionAsync(
    new SessionConfig
    {
        Model = model,
        EnableSessionStore = false,
        InfiniteSessions = new InfiniteSessionConfig { Enabled = false },
        OnPermissionRequest = PermissionHandler.ApproveAll,
        Streaming = streamEvents,
        SkillDirectories = skillDirectories
    });

Our runtime is one-shot and does not need persistent Copilot session workspace, shared session store, or background  compaction, so this workaround is acceptable.

Questions

1. Is  InfiniteSessions  expected to be enabled by default for SDK-created sessions?
2. Is sidekick/inbox persistence expected to run for non-interactive SDK sessions?
3. Should SDK-hosted one-shot sessions have an easier preset for disabling persistent session DB features?
4. Should the CLI SQLite layer use a busy timeout/retry to avoid failing the whole session on transient locks?

[github-actions]

Investigation findings

Thanks for the detailed report. I investigated this by looking at the relevant source code in dotnet/src/Types.cs, dotnet/src/Client.cs, and dotnet/README.md.

What I found

The behavior is working as designed, but there is a meaningful documentation gap that would have prevented this issue.

InfiniteSessions (enabled by default): This is intentional and documented. The XML doc comment on InfiniteSessionConfig.Enabled explicitly says Default: true, and dotnet/README.md states: "By default, sessions use infinite sessions which automatically manage context window limits through background compaction and persist state to a workspace directory."

EnableSessionStore (enabled by default in normal mode): This is also intentional — but EnableSessionStore is not documented anywhere in the README. The SessionConfig property list in the README (dotnet/README.md, lines 118–130) documents properties like Streaming, InfiniteSessions, Tools, etc., but EnableSessionStore is completely absent. In dotnet/src/Client.cs (ApplyConfigDefaultsForMode, line 750–764), the SDK only defaults EnableSessionStore = false when CopilotClientMode.Empty is used; in the default CopilotCli mode, the field is left null, which tells the CLI to use its own default (enabled). This means for standard SDK sessions, both infinite sessions and the cross-session SQLite store are active.

The SQLite lock error: The database is locked error originates inside the bundled CLI's SQLite layer (flushPendingNotifications → getUnreadUnnotifiedEntries → doLoad). Adding a busy-timeout/retry strategy in the CLI would be a valid improvement, but that's outside the SDK's direct control.

Root cause

The user had no way to know they should set EnableSessionStore = false for one-shot environments because this property is not listed in the README, and there is no documentation section for one-shot / hosted session environments with recommended configuration. If either of those existed, the issue would have been avoidable.

Documentation gaps to address

The following content is missing or needs improvement in dotnet/README.md (and should be mirrored in the other language SDKs' READMEs):

1. EnableSessionStore must be added to the SessionConfig property list — describe what it does (enables the cross-session SQLite store for search and retrieval across sessions) and note its default behavior (enabled in CopilotCli mode, disabled in Empty mode).

2. A new "One-shot / Hosted Environments" guidance section should be added explaining that the default configuration enables SQLite-backed session persistence (InfiniteSessions + EnableSessionStore), and recommending that one-shot containers explicitly disable both:

   new SessionConfig
   {
       EnableSessionStore = false,
       InfiniteSessions = new InfiniteSessionConfig { Enabled = false },
       // ...
   }

Label applied: documentation

The current behavior is intentional; the issue is that the docs do not surface EnableSessionStore or provide guidance for one-shot/hosted environments, which is what led to the unexpected failure.

Generated by Bug Handler for issue #1814 · sonnet46 1.5M · ◷