Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

fix(dsh): stage sandboxed hook events in a workspace spool and drain them on sync

Tactile-Taco71b81985e86d
diff --git a/cli/beacon-hooks/internal/logging/endpoint_write_failure_test.go b/cli/beacon-hooks/internal/logging/endpoint_write_failure_test.go
index 727bc0dd..55a5abac 100644
--- a/cli/beacon-hooks/internal/logging/endpoint_write_failure_test.go
+++ b/cli/beacon-hooks/internal/logging/endpoint_write_failure_test.go
@@ -11,9 +11,12 @@ import (
// A hook that cannot write the runtime log records nothing, and on DeepSeek Harness that is the
// normal state of a sandboxed session rather than a fault (#605): the harness confines hook
-// commands to the session workspace, so ~/.beacon is unreachable. The hook still exits 0 -- a
-// telemetry failure must never become a block -- which makes stderr the only channel that reaches
-// anyone at the time. These tests pin what goes there.
+// commands to the session workspace, so ~/.beacon is unreachable. A session-scoped dsh logger
+// would stage the event in the workspace spool instead (see spool_test.go); these cases run
+// without a session id, where no spool applies, so the loss is reported -- which is also the
+// shape every non-workspace-write sandbox ends up in when the spool write fails too. The hook
+// still exits 0 -- a telemetry failure must never become a block -- which makes stderr the only
+// channel that reaches anyone at the time. These tests pin what goes there.
// unwritableEndpointLog returns a runtime log path that cannot be created on any platform: its
// parent is a regular file. That stands in for the read-only file system a sandbox presents
diff --git a/cli/beacon-hooks/internal/logging/logging.go b/cli/beacon-hooks/internal/logging/logging.go
index 4cfbedbd..daaa2da8 100644
--- a/cli/beacon-hooks/internal/logging/logging.go
+++ b/cli/beacon-hooks/internal/logging/logging.go
@@ -153,6 +153,20 @@ func (l *Logger) EndpointEventWithFidelity(action, category, severity, message,
normalizeEventModel(event)
attachDerivedTrace(event)
if err := writeEndpointJSON(path, event); err != nil {
+ // DeepSeek Harness runs hook commands inside the session sandbox, which cannot reach
+ // ~/.beacon but CAN write the session workspace in workspace-write mode (#605).
+ // Staging the event there keeps capture live; `beacon endpoint dsh sync` drains the
+ // spool from outside the sandbox. A staged event is deliberately silent: one process
+ // per event would print a note on every event into the runtime's hook stderr stream,
+ // so the staged state surfaces through `dsh status`, `dsh sync` and `doctor` instead.
+ // When the spool write fails too -- read-only mode, no workspace, unsafe ids -- the
+ // NOT-recorded explanation below fires unchanged, which is the honest report for an
+ // event nothing captured.
+ if spoolPath := l.dshSpoolPath(event); spoolPath != "" {
+ if spoolErr := writeEndpointJSON(spoolPath, event); spoolErr == nil {
+ return nil
+ }
+ }
fmt.Fprintf(os.Stderr, "logging: failed to write endpoint event to %s: %v\n", path, err)
reportEndpointWriteFailure(os.Stderr, l.platform, path, err)
return err
@@ -241,6 +255,44 @@ func recordActiveSession(event map[string]interface{}) {
_ = activesession.Record(activesession.DefaultPath(), name, id, dir, time.Now())
}
+// dshSpoolPath resolves the workspace spool file a sandboxed DeepSeek Harness hook should
+// stage one event in when the runtime log cannot be written, or "" when no spool applies.
+//
+// Spooling is dsh-only: its sandbox is the reason the log write fails (#605), and staging
+// another runtime's events into a project checkout would be new pollution with no drain
+// path. The session id must be a safe filename component on BOTH the writing and the
+// draining side (ValidDSHSessionIDForSpool is what they share), and the workspace comes
+// from the event's own session.working_directory -- the envelope value the bridge stamped
+// from session.header.cwd, the same directory the sandbox confines writes to -- with the
+// process cwd as the fallback for callers that did not carry the field.
+func (l *Logger) dshSpoolPath(event map[string]interface{}) string {
+ if l == nil || asymptoteobserve.NormalizeHarnessName(l.platform) != dshHarnessName {
+ return ""
+ }
+ if !asymptoteobserve.ValidDSHSessionIDForSpool(l.sessionID) {
+ return ""
+ }
+ cwd := ""
+ if session, ok := event["session"].(map[string]interface{}); ok {
+ cwd, _ = session["working_directory"].(string)
+ }
+ cwd = strings.TrimSpace(cwd)
+ if cwd == "" {
+ cwd, _ = os.Getwd()
+ }
+ path, ok := asymptoteobserve.DSHSpoolPath(cwd, l.sessionID)
+ if !ok {
+ return ""
+ }
+ // Creating the directory here doubles as the eligibility probe: if the workspace itself
+ // is not writable (read-only mode), there is no spool and the caller reports the loss.
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ return ""
+ }
+ ensureSpoolGitExclude(filepath.Dir(path))
+ return path
+}
+
// reportedWriteFailures remembers which runtime log paths this process has already explained a
// write failure for, so the explanation is printed once per path rather than once per event. One
// hook invocation can emit several events -- a post-tool hook records the tool result, the file
diff --git a/cli/beacon-hooks/internal/logging/spool_git.go b/cli/beacon-hooks/internal/logging/spool_git.go
new file mode 100644
index 00000000..261b1dba
--- /dev/null
+++ b/cli/beacon-hooks/internal/logging/spool_git.go
@@ -0,0 +1,93 @@
+package logging
+
+import (
+ "bytes"
+ "os"
+ "path/filepath"
+ "strings"
+)
+
+// ensureSpoolGitExclude hides a freshly created spool directory from `git status` by adding
+// its workspace-relative path to the repository's .git/info/exclude.
+//
+// The spool is telemetry that exists only while a sandboxed session is being captured, so an
+// untracked `.beacon/dsh-spool/` showing up in an operator's status output for the duration
+// is exactly the repository pollution the spool design has to avoid. .git/info/exclude (not
+// .gitignore) is the mechanism git reserves for local, unshared ignores, and it is the same
+// one Beacon's cloud setup script already uses for its repo-local files -- add-only, never
+// removed, because an entry naming a path that no longer exists is inert.
+//
+// Everything here is best-effort: a missing or unwritable exclude file means the directory
+// stays visible in git status, which costs a line of noise and no correctness. A linked
+// worktree (.git is a file, not a directory) is skipped rather than resolved -- writing into
+// a worktree's shared git dir from a telemetry hook is a step too far for a hint.
+func ensureSpoolGitExclude(spoolDir string) {
+ root := gitRootAbove(spoolDir)
+ if root == "" {
+ return
+ }
+ rel, err := filepath.Rel(root, spoolDir)
+ if err != nil || rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+ return
+ }
+ entry := filepath.ToSlash(rel) + "/"
+ exclude := filepath.Join(root, ".git", "info", "exclude")
+ data, err := os.ReadFile(exclude)
+ if err != nil && !os.IsNotExist(err) {
+ return
+ }
+ if excludeHasEntry(data, entry) {
+ return
+ }
+ var out bytes.Buffer
+ // A file that does not end in a newline would otherwise have the entry glued onto its
+ // last line, silently ignoring it.
+ if len(data) > 0 && data[len(data)-1] != '\n' {
+ out.WriteByte('\n')
+ }
+ out.WriteString(entry)
+ out.WriteByte('\n')
+ if err := os.MkdirAll(filepath.Dir(exclude), 0o755); err != nil {
+ return
+ }
+ f, err := os.OpenFile(exclude, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+ if err != nil {
+ return
+ }
+ defer func() { _ = f.Close() }()
+ _, _ = f.Write(out.Bytes())
+}
+
+// excludeHasEntry reports whether data already lists entry as one of its pattern lines.
+// Comments and blank lines never match because the entry always ends in a slash.
+func excludeHasEntry(data []byte, entry string) bool {
+ for _, line := range bytes.Split(data, []byte("\n")) {
+ if strings.TrimSpace(string(line)) == entry {
+ return true
+ }
+ }
+ return false
+}
+
+// gitRootAbove walks up from dir looking for the working tree that contains it, and returns
+// the tree root, or "" when there is none above a directory whose .git is a file (a linked
+// worktree: the shared git dir lives elsewhere and is not ours to edit).
+func gitRootAbove(dir string) string {
+ for {
+ info, err := os.Lstat(filepath.Join(dir, ".git"))
+ if err == nil {
+ if info.IsDir() {
+ return dir
+ }
+ return ""
+ }
+ if !os.IsNotExist(err) {
+ return ""
+ }
+ parent := filepath.Dir(dir)
+ if parent == dir {
+ return ""
+ }
+ dir = parent
+ }
+}
diff --git a/cli/beacon-hooks/internal/logging/spool_test.go b/cli/beacon-hooks/internal/logging/spool_test.go
new file mode 100644
index 00000000..49ec830b
--- /dev/null
+++ b/cli/beacon-hooks/internal/logging/spool_test.go
@@ -0,0 +1,222 @@
+package logging
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+// When the runtime log is unreachable but the workspace is writable -- the normal
+// workspace-write sandbox DeepSeek Harness runs hooks in (#605) -- a dsh hook stages the
+// event in the session workspace instead of losing it. `beacon endpoint dsh sync` drains
+// that spool later; at capture time the event is recorded, so nothing is reported as lost
+// and stderr stays silent (one process per event: a note here would be a note on every
+// event).
+
+func TestDshSandboxedWriteStagesEventInWorkspaceSpool(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ workspace := t.TempDir()
+
+ var writeErr error
+ stderr := captureStderr(t, func() {
+ logger := NewSessionLogger("session-start", "dsh", "sess-stage-1")
+ writeErr = logger.EndpointEvent("session.started", "session", "info", "Agent started",
+ map[string]interface{}{
+ "session": map[string]interface{}{"id": "sess-stage-1", "working_directory": workspace},
+ })
+ })
+ if writeErr != nil {
+ t.Fatalf("EndpointEvent returned an error although the event was staged: %v", writeErr)
+ }
+ if stderr != "" {
+ t.Fatalf("a staged event printed to stderr:\n%s", stderr)
+ }
+ spool := filepath.Join(workspace, ".beacon", "dsh-spool", "sess-stage-1.jsonl")
+ data, err := os.ReadFile(spool)
+ if err != nil {
+ t.Fatalf("staged event not in spool: %v", err)
+ }
+ var event map[string]interface{}
+ if err := json.Unmarshal([]byte(strings.TrimSpace(string(data))), &event); err != nil {
+ t.Fatalf("spool line is not JSON: %v", err)
+ }
+ harness := event["harness"].(map[string]interface{})
+ if harness["collection_method"] != "hook" {
+ t.Errorf("collection_method = %v, want hook (the spool holds deferred hook events)", harness["collection_method"])
+ }
+ info := event["event"].(map[string]interface{})
+ if info["id"] == nil || info["id"] == "" {
+ t.Error("staged event has no event.id; a drain redelivery could not be deduplicated")
+ }
+ session := event["session"].(map[string]interface{})
+ if session["working_directory"] != workspace {
+ t.Errorf("working_directory = %v, want %v", session["working_directory"], workspace)
+ }
+}
+
+// Only DeepSeek Harness gets a spool. Staging another runtime's events into a project
+// checkout would be new repository pollution with nothing to drain it, so a claude or cursor
+// hook that cannot write the log reports the loss exactly as before.
+func TestNonDshWriteFailureDoesNotStageASpool(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ workspace := t.TempDir()
+ t.Chdir(workspace)
+
+ var writeErr error
+ stderr := captureStderr(t, func() {
+ logger := NewSessionLogger("session-start", "cursor", "sess-notdsh")
+ writeErr = logger.EndpointEvent("session.started", "session", "info", "Agent started",
+ map[string]interface{}{
+ "session": map[string]interface{}{"id": "sess-notdsh", "working_directory": workspace},
+ })
+ })
+ if writeErr == nil {
+ t.Fatal("EndpointEvent returned nil; the caller could not tell the event was lost")
+ }
+ if !strings.Contains(stderr, "this event was NOT recorded") {
+ t.Fatalf("stderr lacks the NOT-recorded explanation:\n%s", stderr)
+ }
+ if _, err := os.Stat(filepath.Join(workspace, ".beacon")); !os.IsNotExist(err) {
+ t.Errorf("a non-dsp hook created a spool directory in the workspace: %v", err)
+ }
+}
+
+// An unsafe session id must not produce a spool file anywhere: writer and drainer agree via
+// ValidDSHSessionIDForSpool that such ids get no spool, so a path-shaped id can neither
+// escape the spool directory nor strand events where no drain will ever look.
+func TestUnsafeSessionIDFallsBackToReportedLoss(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ workspace := t.TempDir()
+ outside := filepath.Join(t.TempDir(), "outside")
+ if err := os.Mkdir(outside, 0o755); err != nil {
+ t.Fatal(err)
+ }
+
+ var writeErr error
+ stderr := captureStderr(t, func() {
+ logger := NewSessionLogger("session-start", "dsh", "../escaped")
+ writeErr = logger.EndpointEvent("session.started", "session", "info", "Agent started",
+ map[string]interface{}{
+ "session": map[string]interface{}{"id": "../escaped", "working_directory": workspace},
+ })
+ })
+ if writeErr == nil {
+ t.Fatal("EndpointEvent returned nil for an event that reached no log")
+ }
+ if !strings.Contains(stderr, "this event was NOT recorded") {
+ t.Fatalf("stderr lacks the NOT-recorded explanation:\n%s", stderr)
+ }
+ if _, err := os.Stat(filepath.Join(workspace, ".beacon")); !os.IsNotExist(err) {
+ t.Errorf("unsafe session id created a spool directory: %v", err)
+ }
+ if _, err := os.Stat(filepath.Dir(workspace) + string(filepath.Separator) + "escaped"); !os.IsNotExist(err) {
+ t.Error("unsafe session id escaped the workspace")
+ }
+}
+
+// When the workspace is unwritable too -- the read-only sandbox mode -- there is no spool
+// and the loss is reported exactly as it was before the spool existed: NOT recorded, with
+// the dsh sandbox explanation and the sync/doctor remedies.
+func TestUnwritableLogAndWorkspaceReportsLossAsBefore(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ // The workspace's parent is a file, so MkdirAll of any path under it fails the way a
+ // read-only sandbox makes every write fail.
+ blocker := filepath.Join(t.TempDir(), "not-a-directory")
+ if err := os.WriteFile(blocker, []byte("x"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ workspace := filepath.Join(blocker, "workspace")
+
+ var writeErr error
+ stderr := captureStderr(t, func() {
+ logger := NewSessionLogger("session-start", "dsh", "sess-ro-1")
+ writeErr = logger.EndpointEvent("session.started", "session", "info", "Agent started",
+ map[string]interface{}{
+ "session": map[string]interface{}{"id": "sess-ro-1", "working_directory": workspace},
+ })
+ })
+ if writeErr == nil {
+ t.Fatal("EndpointEvent returned nil; the caller could not tell the event was lost")
+ }
+ for _, want := range []string{"this event was NOT recorded", logPath, "DeepSeek Harness", "beacon endpoint dsh sync"} {
+ if !strings.Contains(stderr, want) {
+ t.Fatalf("stderr does not mention %q:\n%s", want, stderr)
+ }
+ }
+}
+
+// First spool use hides the directory from git status via .git/info/exclude (the local,
+// unshared mechanism -- never .gitignore), exactly once, relative to the worktree root even
+// when the session cwd sits below it.
+func TestFirstSpoolUseExcludesTheDirectoryFromGitStatus(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ root := t.TempDir()
+ if err := os.Mkdir(filepath.Join(root, ".git"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ sub := filepath.Join(root, "pkg", "app")
+ if err := os.MkdirAll(sub, 0o755); err != nil {
+ t.Fatal(err)
+ }
+
+ stage := func() {
+ logger := NewSessionLogger("session-start", "dsh", "sess-git-1")
+ _ = logger.EndpointEvent("session.started", "session", "info", "Agent started",
+ map[string]interface{}{
+ "session": map[string]interface{}{"id": "sess-git-1", "working_directory": sub},
+ })
+ }
+ stage() // second call proves the entry is not appended twice
+ stage()
+
+ exclude := filepath.Join(root, ".git", "info", "exclude")
+ data, err := os.ReadFile(exclude)
+ if err != nil {
+ t.Fatalf("exclude file not written: %v", err)
+ }
+ want := "pkg/app/.beacon/dsh-spool/"
+ if got := strings.Count(string(data), want); got != 1 {
+ t.Fatalf("exclude lists %q %d times, want once:\n%s", want, got, data)
+ }
+ if strings.Contains(string(data), ".gitignore") {
+ t.Errorf("spool containment must use .git/info/exclude, not .gitignore:\n%s", data)
+ }
+}
+
+// A workspace that is not a git worktree is the common non-repo case: staging must work and
+// simply skip containment without erroring or walking anywhere odd.
+func TestSpoolOutsideAGitWorktreeSkipsContainment(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ workspace := t.TempDir()
+
+ logger := NewSessionLogger("session-start", "dsh", "sess-nogit-1")
+ if err := logger.EndpointEvent("session.started", "session", "info", "Agent started",
+ map[string]interface{}{
+ "session": map[string]interface{}{"id": "sess-nogit-1", "working_directory": workspace},
+ }); err != nil {
+ t.Fatalf("staged write outside a repo: %v", err)
+ }
+ spool := filepath.Join(workspace, ".beacon", "dsh-spool", "sess-nogit-1.jsonl")
+ if _, err := os.Stat(spool); err != nil {
+ t.Fatalf("spool file missing outside a repo: %v", err)
+ }
+ for _, up := range []string{".git", "info"} {
+ if _, err := os.Stat(filepath.Join(workspace, up)); !os.IsNotExist(err) {
+ t.Errorf("%s appeared in a non-repo workspace: %v", up, err)
+ }
+ }
+}
diff --git a/cli/beacon/cmd/endpoint_dsh.go b/cli/beacon/cmd/endpoint_dsh.go
index 56052422..4e39966c 100644
--- a/cli/beacon/cmd/endpoint_dsh.go
+++ b/cli/beacon/cmd/endpoint_dsh.go
@@ -10,6 +10,7 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/dshsession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
"github.com/spf13/cobra"
)
@@ -137,6 +138,9 @@ func reportDshSweep(cmd *cobra.Command, summary dshsession.Summary) {
fmt.Fprintf(cmd.OutOrStdout(), "dsh sync: %d sessions, %d changed, %d events, %d errors\n",
summary.Sessions, summary.SessionsChanged, summary.EventsEmitted, summary.Errors)
reportSyncRetention(cmd.OutOrStdout(), summary.Retention)
+ if summary.SpoolEvents > 0 {
+ fmt.Fprintf(cmd.OutOrStdout(), " %d spooled hook event(s) drained from workspace spools\n", summary.SpoolEvents)
+ }
if summary.MalformedLines > 0 {
fmt.Fprintf(cmd.OutOrStdout(), " %d unreadable line(s) in DeepSeek session logs\n", summary.MalformedLines)
}
@@ -156,6 +160,10 @@ type dshSessionStatus struct {
LastLine int `json:"last_line"`
Collected bool `json:"collected"`
SizeBytes int64 `json:"size_bytes"`
+ // SpoolBytes is hook-captured event data staged in the session's workspace spool,
+ // waiting for a sweep to drain it into the runtime log (#605). Zero is the healthy
+ // steady state; anything else means capture worked but the last sync has not run yet.
+ SpoolBytes int64 `json:"spool_bytes,omitempty"`
}
type dshStatusReport struct {
@@ -201,6 +209,7 @@ func runEndpointDshStatus(cmd *cobra.Command, args []string) error {
status.ParentSession = ref.Meta.ParentSessionID
status.Model = ref.Meta.Model
status.Title = ref.Meta.Title
+ status.SpoolBytes = asymptoteobserve.DSHSpoolPendingBytes(ref.Meta.CWD, ref.ID)
}
if cursor := state.Sources[ref.Path]; cursor != nil {
status.CollectedLine = cursor.LastLine
@@ -222,8 +231,12 @@ func runEndpointDshStatus(cmd *cobra.Command, args []string) error {
if session.Collected {
state = "collected"
}
- fmt.Fprintf(out, " %s %s line %d/%d %s\n",
+ fmt.Fprintf(out, " %s %s line %d/%d %s",
session.SessionID, state, session.CollectedLine, session.LastLine, strings.TrimSpace(session.Workspace))
+ if session.SpoolBytes > 0 {
+ fmt.Fprintf(out, " (spool %dB awaiting drain)", session.SpoolBytes)
+ }
+ fmt.Fprintln(out)
}
return nil
}
diff --git a/cli/beacon/cmd/endpoint_dsh_doctor.go b/cli/beacon/cmd/endpoint_dsh_doctor.go
index 00274adb..5867318f 100644
--- a/cli/beacon/cmd/endpoint_dsh_doctor.go
+++ b/cli/beacon/cmd/endpoint_dsh_doctor.go
@@ -3,6 +3,7 @@ package cmd
import (
"fmt"
"os"
+ "strings"
"time"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/dshsession"
@@ -40,7 +41,9 @@ var doctorDshHookCaptureCheck = dshHookCaptureCheck
// the hooks were installed, set against the last event whose harness.collection_method is `hook`.
// Sessions with no live hook event near them are sessions the hooks did not capture, whatever the
// cause; the sandbox is the common one and the message leads with it, and a dsh that was already
-// running when the hooks were installed is the other.
+// running when the hooks were installed is the other. A session whose workspace spool still holds
+// staged hook events is neither: capture worked and only the sweep is missing, so it gets its own
+// finding (`dsh_spool_pending_drain`) with the sync as its remedy instead of counting as a miss.
func dshHookCaptureCheck(logPath string) (diagnostics.Check, bool) {
status := endpointhooks.DshHookStatus(endpointhooks.DshOptions{Level: endpointhooks.LevelUser})
if !status.Installed || status.HooksPath == "" {
@@ -183,19 +186,37 @@ func dshHookCaptureCheckAt(logPath, hooksPath, dshHome string) diagnostics.Check
// A session is missed when it was written after the hooks took effect and after the last live
// hook event, by more than the commit gap. Taking the later of the two lets a machine that
// captured fine and later moved to a sandboxed mode be flagged too, not only a fresh install.
+ //
+ // A session whose workspace still holds a spool is not a miss: its hook events exist, staged
+ // where the sandbox allowed the hook to write them (#605), and the next `beacon endpoint dsh
+ // sync` drains them into the log. Reporting it as uncaptured would call working capture broken
+ // and send the operator to change the sandbox mode for nothing; the pending drain is its own
+ // finding, with the same remedy.
cutoff := installedAt
if hookSeen && lastHook.After(cutoff) {
cutoff = lastHook.Add(dshHookCaptureGrace)
}
sinceInstall := 0
missed := 0
+ pendingDrain := 0
var newest time.Time
for _, ref := range refs {
modified := time.UnixMilli(ref.ModTimeUnixMS)
- if modified.Before(installedAt) || modified.Before(oldestRetained) {
+ if modified.Before(installedAt) {
+ // Sessions before the current hooks took effect were never going to be captured
+ // live, spool or no spool; they are not evidence of anything.
+ continue
+ }
+ pending := ref.Meta != nil && strings.TrimSpace(ref.Meta.CWD) != "" &&
+ asymptoteobserve.DSHSpoolPendingBytes(ref.Meta.CWD, ref.ID) > 0
+ if !pending && modified.Before(oldestRetained) {
continue
}
sinceInstall++
+ if pending {
+ pendingDrain++
+ continue
+ }
if modified.After(cutoff) {
missed++
if modified.After(newest) {
@@ -208,6 +229,14 @@ func dshHookCaptureCheckAt(logPath, hooksPath, dshHome string) diagnostics.Check
case sinceInstall == 0:
check.Message = "no DeepSeek Harness session has run since the hooks were installed"
check.Evidence = "dsh_no_sessions_since_install"
+ case missed == 0 && pendingDrain > 0:
+ check.Status = diagnostics.StatusWarn
+ check.Severity = diagnostics.SeverityLow
+ check.Evidence = "dsh_spool_pending_drain"
+ check.Message = fmt.Sprintf(
+ "%d DeepSeek Harness session(s) have hook events staged in their workspace spool; capture is working, but the events are not in %s yet",
+ pendingDrain, logPath)
+ check.Action = "run `beacon endpoint dsh sync` to drain the staged events into the runtime log"
case missed == 0:
check.Message = "live DeepSeek Harness hook events are being recorded"
check.Evidence = "dsh_hook_events_observed"
diff --git a/cli/beacon/cmd/endpoint_dsh_doctor_test.go b/cli/beacon/cmd/endpoint_dsh_doctor_test.go
index f7d9d068..6ed207dd 100644
--- a/cli/beacon/cmd/endpoint_dsh_doctor_test.go
+++ b/cli/beacon/cmd/endpoint_dsh_doctor_test.go
@@ -18,9 +18,11 @@ import (
)
// DeepSeek Harness runs hook commands sandboxed to the session workspace unless the sandbox mode is
-// danger-full-access, so a hook commonly cannot write the runtime log and records nothing while
-// exiting 0 (#605). `beacon endpoint dsh sync` still fills the log with poll events under the same
-// harness name, so harness_observed stays green. dsh_hook_capture is the check that notices.
+// danger-full-access, so a hook commonly cannot write the runtime log while exiting 0 (#605). In
+// workspace-write it stages the event in a workspace spool instead (dsh_spool_pending_drain until a
+// sweep drains it); with nothing writable it records nothing at all. `beacon endpoint dsh sync` still
+// fills the log with poll events under the same harness name, so harness_observed stays green.
+// dsh_hook_capture is the check that notices.
// dshDoctorFixture is a Harness home with a hooks file installed at installedAt, and a runtime log.
type dshDoctorFixture struct {
diff --git a/cli/beacon/cmd/endpoint_dsh_spool_test.go b/cli/beacon/cmd/endpoint_dsh_spool_test.go
new file mode 100644
index 00000000..da291f5f
--- /dev/null
+++ b/cli/beacon/cmd/endpoint_dsh_spool_test.go
@@ -0,0 +1,233 @@
+package cmd
+
+import (
+ "bytes"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/dshsession"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/diagnostics"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+ "github.com/spf13/cobra"
+)
+
+// Staged-but-undrained hook events are a distinct state from "the hooks captured nothing":
+// the capture worked (the event exists in the workspace spool) and only the sweep is missing.
+// Doctor must say that, with the sync remedy, instead of sending the operator to change the
+// sandbox mode for a session that was captured fine.
+
+// sessionInWorkspace writes a native session record whose cwd points at workspace, last
+// modified at modified. The stock fixture's records carry no cwd, and a spool is only
+// locatable through one.
+func sessionInWorkspace(t *testing.T, f dshDoctorFixture, id, workspace string, modified time.Time) {
+ t.Helper()
+ dir := filepath.Join(f.home, "sessions", id)
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ path := filepath.Join(dir, "session.jsonl")
+ line := `{"type":"session","time":"` + modified.UTC().Format(time.RFC3339) + `","data":{"id":"` + id + `","cwd":` + jsonString(workspace) + `}}` + "\n"
+ if err := os.WriteFile(path, []byte(line), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.Chtimes(path, modified, modified); err != nil {
+ t.Fatal(err)
+ }
+}
+
+func jsonString(s string) string {
+ data, err := json.Marshal(s)
+ if err != nil {
+ panic(err)
+ }
+ return string(data)
+}
+
+// plantSpool stages hook-event bytes in the workspace spool for id, the way a sandboxed hook
+// would, and returns the staged byte count.
+func plantSpool(t *testing.T, workspace, id string) int {
+ t.Helper()
+ path, ok := asymptoteobserve.DSHSpoolPath(workspace, id)
+ if !ok {
+ t.Fatalf("unsafe test session id %q", id)
+ }
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ body := `{"timestamp":"2026-09-23T12:00:00Z","vendor":"beacon","product":"endpoint-agent",` +
+ `"schema_version":"1.0","event":{"kind":"agent_runtime","action":"prompt.submitted"},` +
+ `"severity":"info","harness":{"name":"deepseek_harness","collection_method":"hook"}}` + "\n"
+ if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ return len(body)
+}
+
+// A session with staged events and no hook event in the runtime log is capture working,
+// drain missing: dsh_spool_pending_drain, not dsh_sessions_without_hook_events.
+func TestDshHookCaptureReportsPendingSpoolInsteadOfMissedSessions(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ workspace := t.TempDir()
+ sessionInWorkspace(t, f, "pending-1", workspace, f.installedAt.Add(time.Hour))
+ plantSpool(t, workspace, "pending-1")
+ // Poll backfill has run, as it would before the operator ever noticed the drain.
+ f.event(t, "poll", f.installedAt.Add(2*time.Hour))
+
+ got := f.check()
+ if got.Status != diagnostics.StatusWarn || got.Evidence != "dsh_spool_pending_drain" {
+ t.Fatalf("status/evidence = %s/%s, want warn/dsh_spool_pending_drain (%s)", got.Status, got.Evidence, got.Message)
+ }
+ if got.Severity != diagnostics.SeverityLow {
+ t.Errorf("severity = %s, want low: the events exist, only the drain is missing", got.Severity)
+ }
+ for _, want := range []string{"staged", "workspace spool", f.logPath} {
+ if !strings.Contains(got.Message, want) {
+ t.Errorf("message does not mention %q: %s", want, got.Message)
+ }
+ }
+ if !strings.Contains(got.Action, "beacon endpoint dsh sync") {
+ t.Errorf("action does not name the drain: %s", got.Action)
+ }
+ if strings.Contains(got.Message, "danger-full-access") {
+ t.Errorf("a pending drain must not blame the sandbox mode: %s", got.Message)
+ }
+}
+
+// A genuine miss outranks a pending drain: sessions the hooks captured nothing for are the
+// more urgent finding, and their message must not be softened by a healthy sibling session.
+func TestDshHookCaptureMissedSessionsOutrankAPendingDrain(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ workspace := t.TempDir()
+ sessionInWorkspace(t, f, "pending-1", workspace, f.installedAt.Add(time.Hour))
+ plantSpool(t, workspace, "pending-1")
+ f.session(t, "missed-1", f.installedAt.Add(2*time.Hour))
+
+ got := f.check()
+ if got.Evidence != "dsh_sessions_without_hook_events" {
+ t.Fatalf("evidence = %s, want dsh_sessions_without_hook_events (%s)", got.Evidence, got.Message)
+ }
+ if !strings.Contains(got.Message, "1 DeepSeek Harness session(s)") {
+ t.Fatalf("the pending session must not be counted as missed: %s", got.Message)
+ }
+}
+
+// Draining is the fix for a pending spool, and the drain empties the file; the next check
+// then falls back to the log-based evidence like any other install.
+func TestDshHookCapturePendingDrainClearsOnceTheSpoolIsEmpty(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ workspace := t.TempDir()
+ sessionInWorkspace(t, f, "pending-1", workspace, f.installedAt.Add(time.Hour))
+ plantSpool(t, workspace, "pending-1")
+ if f.check().Evidence != "dsh_spool_pending_drain" {
+ t.Fatal("precondition: planted spool must report as pending drain")
+ }
+
+ // Drain: the events land in the log as hook events and the spool file goes away.
+ f.event(t, "hook", f.installedAt.Add(2*time.Hour))
+ path, _ := asymptoteobserve.DSHSpoolPath(workspace, "pending-1")
+ if err := os.Remove(path); err != nil {
+ t.Fatal(err)
+ }
+
+ got := f.check()
+ if got.Status != diagnostics.StatusOK || got.Evidence != "dsh_hook_events_observed" {
+ t.Fatalf("status/evidence = %s/%s, want ok/dsh_hook_events_observed after the drain (%s)",
+ got.Status, got.Evidence, got.Message)
+ }
+}
+
+// dsh status is the surface an operator (and the installed skill) reads between sweeps, so
+// staged bytes must show up in both the JSON report and the text line.
+func TestDshStatusReportsPendingSpoolBytes(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ workspace := t.TempDir()
+ sessionInWorkspace(t, f, "staged-1", workspace, time.Now().Add(-time.Hour))
+ staged := plantSpool(t, workspace, "staged-1")
+
+ restore := stashDshOpts(t)
+ endpointDshOpts.dshHome = f.home
+ endpointDshOpts.statePath = filepath.Join(t.TempDir(), "state.json")
+ endpointDshOpts.workspace = ""
+ endpointDshOpts.sessionID = ""
+
+ endpointOpts.jsonOutput = true
+ jsonOut := &bytes.Buffer{}
+ cmd := &cobra.Command{}
+ cmd.SetOut(jsonOut)
+ cmd.SetErr(jsonOut)
+ if err := runEndpointDshStatus(cmd, nil); err != nil {
+ t.Fatalf("dsh status --json: %v", err)
+ }
+ var report dshStatusReport
+ if err := json.Unmarshal(jsonOut.Bytes(), &report); err != nil {
+ t.Fatalf("status JSON: %v\n%s", err, jsonOut.String())
+ }
+ if len(report.Sessions) != 1 || report.Sessions[0].SessionID != "staged-1" {
+ t.Fatalf("sessions = %+v, want staged-1", report.Sessions)
+ }
+ if got := report.Sessions[0].SpoolBytes; got != int64(staged) {
+ t.Errorf("spool_bytes = %d, want %d", got, staged)
+ }
+
+ endpointOpts.jsonOutput = false
+ textOut := &bytes.Buffer{}
+ cmd = &cobra.Command{}
+ cmd.SetOut(textOut)
+ cmd.SetErr(textOut)
+ if err := runEndpointDshStatus(cmd, nil); err != nil {
+ t.Fatalf("dsh status: %v", err)
+ }
+ if !strings.Contains(textOut.String(), "awaiting drain") {
+ t.Errorf("text status does not flag the staged spool:\n%s", textOut.String())
+ }
+ restore()
+}
+
+// The sweep report is how `dsh sync --watch` and one-shot runs show their work; a run that
+// drained staged events says so, separately from the poll event count.
+func TestReportDshSweepCountsDrainedSpoolEvents(t *testing.T) {
+ restore := stashDshOpts(t)
+ endpointDshOpts.print = false
+ endpointOpts.jsonOutput = false
+
+ cmd := &cobra.Command{}
+ out := &bytes.Buffer{}
+ cmd.SetOut(out)
+ reportDshSweep(cmd, dshsession.Summary{Sessions: 1, SpoolEvents: 3})
+ if !strings.Contains(out.String(), "3 spooled hook event(s) drained") {
+ t.Fatalf("sweep report does not mention the drain:\n%s", out.String())
+ }
+
+ out.Reset()
+ endpointOpts.jsonOutput = true
+ reportDshSweep(cmd, dshsession.Summary{Sessions: 1, SpoolEvents: 3})
+ var decoded struct {
+ SpoolEvents int `json:"spool_events"`
+ }
+ if err := json.Unmarshal(out.Bytes(), &decoded); err != nil {
+ t.Fatalf("sweep JSON: %v\n%s", err, out.String())
+ }
+ if decoded.SpoolEvents != 3 {
+ t.Errorf("sweep JSON spool_events = %d, want 3", decoded.SpoolEvents)
+ }
+ restore()
+}
+
+// stashDshOpts snapshots the package globals these command tests drive and restores them.
+func stashDshOpts(t *testing.T) func() {
+ t.Helper()
+ opts := endpointDshOpts
+ endpointOptsState := endpointOpts
+ t.Cleanup(func() {
+ endpointDshOpts = opts
+ endpointOpts = endpointOptsState
+ })
+ return func() {
+ endpointDshOpts = opts
+ endpointOpts = endpointOptsState
+ }
+}
diff --git a/cli/beacon/internal/dshsession/collect.go b/cli/beacon/internal/dshsession/collect.go
index a2dc6621..7fc6b9e4 100644
--- a/cli/beacon/internal/dshsession/collect.go
+++ b/cli/beacon/internal/dshsession/collect.go
@@ -59,6 +59,7 @@ type Summary struct {
Sessions int `json:"sessions"`
SessionsChanged int `json:"sessions_changed"`
EventsEmitted int `json:"events_emitted"`
+ SpoolEvents int `json:"spool_events,omitempty"`
Errors int `json:"errors"`
MalformedLines int `json:"malformed_lines"`
PartialSessions int `json:"partial_sessions"`
@@ -123,7 +124,21 @@ func CollectOnce(opts CollectOptions) (summary Summary, err error) {
var errs []error
opts.guard = sessionsync.NewRetentionGuard(opts.Print, opts.Write)
var stopErr error
+ // The redelivery guard is loaded once per sweep, from the log as it stands before any
+ // drain appends: every id found there is already recorded.
+ seen := loadDrainedIDs(opts.LogPath)
for _, ref := range refs {
+ // Drain before the store mapping so the live hook copy of an event lands first.
+ // The writer keeps the line it saw and skips a matching candidate, so wherever the
+ // two capture paths describe one event identically (same key, same call id), the
+ // surviving copy is the collection_method=hook line doctor's capture check counts,
+ // not the poll backfill of the same moment.
+ if drained, drainErr := drainSessionSpool(ref, opts, seen); drainErr != nil {
+ summary.Errors++
+ errs = append(errs, fmt.Errorf("DeepSeek session %s spool: %w", ref.ID, drainErr))
+ } else if drained > 0 {
+ summary.SpoolEvents += drained
+ }
changed, collectErr := collectSession(store, ref, state, opts, &summary)
if sessionsync.Stopped(collectErr) {
// Not a failed session: this one and the rest are left for a later sync, with cursors
diff --git a/cli/beacon/internal/dshsession/spool.go b/cli/beacon/internal/dshsession/spool.go
new file mode 100644
index 00000000..3b548bb0
--- /dev/null
+++ b/cli/beacon/internal/dshsession/spool.go
@@ -0,0 +1,173 @@
+package dshsession
+
+import (
+ "bufio"
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "io"
+ "os"
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/filelock"
+)
+
+// drainSpoolTailBytes is how much of the end of the runtime log loadDrainedIDs scans. It
+// matches pkg/asymptoteobserve's dedupe tail window so the redelivery guard and the writer's
+// own duplicate suppression cover the same history: beyond it, a crash-redrained spool can
+// re-append an event whose first copy rotated out of the window, which the log tolerates the
+// same way it tolerates any other late backfill.
+const drainSpoolTailBytes = 256 * 1024
+
+// drainSpoolMaxLineBytes bounds one spool line while scanning. Spool lines are hook-writer
+// output, capped at 64 KiB like every endpoint event; 1 MiB is headroom, not a contract.
+const drainSpoolMaxLineBytes = 1024 * 1024
+
+// loadDrainedIDs collects the event.ids present in the last drainSpoolTailBytes of the
+// runtime log.
+//
+// It is the guard that makes a redrain safe. The drain protocol is append-then-delete under
+// the spool lock, so the only way the same file is seen twice is a crash between the two
+// steps; on redelivery every already-appended id is skipped. This matters most for the
+// lifecycle events -- session.started, prompt.submitted, subagent.* -- which sit outside the
+// writer's call-id dedupe allowlist and would otherwise land twice, and it is safe in both
+// directions: an id found in the tail means that exact event is already recorded, so
+// skipping it is correct no matter which copy arrived first.
+func loadDrainedIDs(logPath string) map[string]struct{} {
+ seen := map[string]struct{}{}
+ if strings.TrimSpace(logPath) == "" {
+ return seen
+ }
+ f, err := os.Open(logPath)
+ if err != nil {
+ return seen
+ }
+ defer func() { _ = f.Close() }()
+ var start int64
+ if info, err := f.Stat(); err == nil && info.Size() > drainSpoolTailBytes {
+ start = info.Size() - drainSpoolTailBytes
+ }
+ if _, err := f.Seek(start, io.SeekStart); err != nil {
+ return seen
+ }
+ scanner := bufio.NewScanner(f)
+ scanner.Buffer(make([]byte, 0, 64*1024), drainSpoolMaxLineBytes)
+ // A window that starts mid-line leaves a partial first line; it cannot parse and must
+ // not be mistaken for anything.
+ partial := start > 0
+ for scanner.Scan() {
+ line := scanner.Bytes()
+ if partial {
+ partial = false
+ continue
+ }
+ var event schema.Event
+ if err := json.Unmarshal(line, &event); err != nil {
+ continue
+ }
+ if event.Event.ID != "" {
+ seen[event.Event.ID] = struct{}{}
+ }
+ }
+ return seen
+}
+
+// drainSessionSpool moves one session's staged hook events out of its workspace spool and
+// into the runtime log, then deletes each file it emptied. Returns how many events landed.
+//
+// Why a spool exists: DeepSeek Harness runs hook commands inside the session sandbox
+// (#605), which cannot write ~/.beacon but can write the session workspace in
+// workspace-write mode. The hook stages events at <cwd>/.beacon/dsh-spool/<id>.jsonl;
+// nothing inside the sandbox can hand them to the runtime log, so the drain happens here,
+// outside the harness, on the sweep an operator or the watch loop already runs.
+//
+// The whole sweep holds the spool's own <file>.lock -- the same lock every hook append and
+// every rotation of these files takes -- so the file set cannot change under it and a hook
+// firing during the drain blocks rather than drops (filelock.Exclusive blocks by design).
+// Delete-after-append plus loadDrainedIDs makes a crash mid-drain re-deliverable without
+// double-counting.
+func drainSessionSpool(ref SessionRef, opts CollectOptions, seen map[string]struct{}) (int, error) {
+ if !opts.Write || opts.Print {
+ return 0, nil
+ }
+ if ref.Meta == nil || strings.TrimSpace(ref.Meta.CWD) == "" {
+ return 0, nil
+ }
+ base, ok := asymptoteobserve.DSHSpoolPath(ref.Meta.CWD, ref.ID)
+ if !ok {
+ return 0, nil
+ }
+ if files := asymptoteobserve.DSHSpoolFiles(ref.Meta.CWD, ref.ID); len(files) == 0 {
+ return 0, nil
+ }
+ lock, err := os.OpenFile(base+".lock", os.O_CREATE|os.O_RDWR, 0o666)
+ if err != nil {
+ return 0, fmt.Errorf("open spool lock %s: %w", base+".lock", err)
+ }
+ held, err := filelock.Exclusive(lock)
+ if err != nil {
+ _ = lock.Close()
+ return 0, fmt.Errorf("lock spool %s: %w", base, err)
+ }
+ // Unlock before closing: the close listed first runs last.
+ defer lock.Close()
+ defer held.Release()
+
+ // Re-enumerate under the lock: a hook staged or rotated a file between the first stat
+ // and here, and rotation runs under this same lock, so the set is now stable.
+ files := asymptoteobserve.DSHSpoolFiles(ref.Meta.CWD, ref.ID)
+ drained := 0
+ for _, path := range files {
+ n, err := drainSpoolFile(path, opts, seen)
+ drained += n
+ if err != nil {
+ return drained, err
+ }
+ }
+ return drained, nil
+}
+
+// drainSpoolFile appends one spool file's events to the runtime log and removes the file.
+// An append failure returns early with the file left in place: the events already appended
+// carry ids into seen, so the next sweep redelivers only what is left.
+func drainSpoolFile(path string, opts CollectOptions, seen map[string]struct{}) (int, error) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return 0, nil
+ }
+ return 0, fmt.Errorf("read spool %s: %w", path, err)
+ }
+ drained := 0
+ for _, line := range bytes.Split(data, []byte("\n")) {
+ if len(bytes.TrimSpace(line)) == 0 {
+ continue
+ }
+ var event schema.Event
+ if err := json.Unmarshal(line, &event); err != nil {
+ // Not an event: a torn tail line from a killed hook, or corrupt bytes nothing
+ // downstream could parse either. It is dropped with the file rather than
+ // blocking the drain of the valid events around it.
+ continue
+ }
+ if event.Event.ID != "" {
+ if _, duplicate := seen[event.Event.ID]; duplicate {
+ continue
+ }
+ }
+ if _, err := writer.AppendEvent(event, writer.Options{Path: opts.LogPath, UserMode: opts.UserMode}); err != nil {
+ return drained, fmt.Errorf("append spooled event from %s: %w", path, err)
+ }
+ if event.Event.ID != "" {
+ seen[event.Event.ID] = struct{}{}
+ }
+ drained++
+ }
+ if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+ return drained, fmt.Errorf("remove drained spool %s: %w", path, err)
+ }
+ return drained, nil
+}
diff --git a/cli/beacon/internal/dshsession/spool_test.go b/cli/beacon/internal/dshsession/spool_test.go
new file mode 100644
index 00000000..b2370b0f
--- /dev/null
+++ b/cli/beacon/internal/dshsession/spool_test.go
@@ -0,0 +1,396 @@
+package dshsession
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/filelock"
+)
+
+// The spool is how a sandboxed DeepSeek Harness hook's events reach the runtime log (#605):
+// the hook stages them in the session workspace because the sandbox cannot write ~/.beacon,
+// and `beacon endpoint dsh sync` drains them from outside the harness. These tests pin the
+// drain contract: events land verbatim as hook events, files are deleted once emptied, a
+// crash between append and delete cannot double-deliver, and a hook mid-append blocks
+// instead of losing its event.
+
+func spoolTestEvent(t *testing.T, sessionID, action, id string) schema.Event {
+ t.Helper()
+ event := asymptoteobserve.NewEvent(asymptoteobserve.NewEventOptions{
+ Action: action,
+ Category: "session",
+ Severity: schema.SeverityInfo,
+ Harness: schema.HarnessInfo{
+ Name: dshsessionHarnessForTest,
+ CollectionMethod: asymptoteobserve.CollectionMethodHook,
+ },
+ Message: action + " for " + sessionID,
+ })
+ event.Session = &schema.SessionInfo{ID: sessionID}
+ event.Event.ID = id
+ return event
+}
+
+// dshsessionHarnessForTest is the canonical harness name the drain must preserve.
+const dshsessionHarnessForTest = "deepseek_harness"
+
+func writeSpoolFile(t *testing.T, path string, events ...schema.Event) {
+ t.Helper()
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ var out strings.Builder
+ for _, event := range events {
+ data, err := json.Marshal(event)
+ if err != nil {
+ t.Fatal(err)
+ }
+ out.Write(data)
+ out.WriteByte('\n')
+ }
+ if err := os.WriteFile(path, []byte(out.String()), 0o644); err != nil {
+ t.Fatal(err)
+ }
+}
+
+func spoolTestOpts(t *testing.T) CollectOptions {
+ t.Helper()
+ return CollectOptions{
+ Write: true,
+ LogPath: filepath.Join(t.TempDir(), "runtime.jsonl"),
+ UserMode: true,
+ }
+}
+
+func readLogLines(t *testing.T, path string) []schema.Event {
+ t.Helper()
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return nil
+ }
+ t.Fatal(err)
+ }
+ var out []schema.Event
+ for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {
+ if strings.TrimSpace(line) == "" {
+ continue
+ }
+ var event schema.Event
+ if err := json.Unmarshal([]byte(line), &event); err != nil {
+ t.Fatalf("log line is not an event: %v\n%s", err, line)
+ }
+ out = append(out, event)
+ }
+ return out
+}
+
+func TestDrainSessionSpoolMovesEventsAsHookEventsAndDeletesTheFile(t *testing.T) {
+ workspace := t.TempDir()
+ opts := spoolTestOpts(t)
+ ref := SessionRef{ID: "sess-drain-1", Meta: &SessionMeta{ID: "sess-drain-1", CWD: workspace}}
+ base, ok := asymptoteobserve.DSHSpoolPath(workspace, ref.ID)
+ if !ok {
+ t.Fatal("safe id produced no spool path")
+ }
+ writeSpoolFile(t, base,
+ spoolTestEvent(t, ref.ID, "session.started", "id-start"),
+ spoolTestEvent(t, ref.ID, "prompt.submitted", "id-prompt"),
+ )
+
+ drained, err := drainSessionSpool(ref, opts, loadDrainedIDs(opts.LogPath))
+ if err != nil {
+ t.Fatalf("drain: %v", err)
+ }
+ if drained != 2 {
+ t.Fatalf("drained = %d, want 2", drained)
+ }
+ events := readLogLines(t, opts.LogPath)
+ if len(events) != 2 {
+ t.Fatalf("log has %d events, want 2", len(events))
+ }
+ for _, event := range events {
+ if event.Harness.CollectionMethod != asymptoteobserve.CollectionMethodHook {
+ t.Errorf("action %s landed with collection_method=%q, want hook: a drained spool holds deferred hook events",
+ event.Event.Action, event.Harness.CollectionMethod)
+ }
+ if event.Harness.Name != dshsessionHarnessForTest {
+ t.Errorf("harness.name = %q, want %s", event.Harness.Name, dshsessionHarnessForTest)
+ }
+ }
+ if pending := asymptoteobserve.DSHSpoolPendingBytes(workspace, ref.ID); pending != 0 {
+ t.Errorf("spool still holds %d bytes after drain", pending)
+ }
+ if _, err := os.Stat(base); !os.IsNotExist(err) {
+ t.Errorf("drained spool file still exists: %v", err)
+ }
+}
+
+// A crash between "appended" and "deleted" leaves the file in place; the next drain
+// redelivers it. The id guard keeps that from landing the same events twice -- most
+// importantly the lifecycle events (session.started, prompt.submitted), which sit outside
+// the writer's own call-id dedupe allowlist and would otherwise always double-count.
+func TestDrainSessionSpoolRedeliveryAfterCrashDoesNotDoubleCount(t *testing.T) {
+ workspace := t.TempDir()
+ opts := spoolTestOpts(t)
+ ref := SessionRef{ID: "sess-redrain", Meta: &SessionMeta{ID: "sess-redrain", CWD: workspace}}
+ base, _ := asymptoteobserve.DSHSpoolPath(workspace, ref.ID)
+ events := []schema.Event{
+ spoolTestEvent(t, ref.ID, "session.started", "id-a"),
+ spoolTestEvent(t, ref.ID, "prompt.submitted", "id-b"),
+ }
+ writeSpoolFile(t, base, events...)
+
+ // Simulate the crash: both events reached the log, the delete never ran.
+ for _, event := range events {
+ if _, err := writer.AppendEvent(event, writer.Options{Path: opts.LogPath, UserMode: opts.UserMode}); err != nil {
+ t.Fatal(err)
+ }
+ }
+ seen := loadDrainedIDs(opts.LogPath)
+ drained, err := drainSessionSpool(ref, opts, seen)
+ if err != nil {
+ t.Fatalf("redrain: %v", err)
+ }
+ if drained != 0 {
+ t.Fatalf("redrain appended %d events, want 0 (ids already in the log)", drained)
+ }
+ if got := len(readLogLines(t, opts.LogPath)); got != 2 {
+ t.Fatalf("log has %d events after redrain, want 2", got)
+ }
+ if _, err := os.Stat(base); !os.IsNotExist(err) {
+ t.Fatalf("redrain did not delete the drained file: %v", err)
+ }
+}
+
+// --print promises no writes and no side effects; the drain honors the same promise.
+func TestDrainSessionSpoolIsInertInPrintMode(t *testing.T) {
+ workspace := t.TempDir()
+ opts := spoolTestOpts(t)
+ opts.Print = true
+ opts.Write = false
+ ref := SessionRef{ID: "sess-print", Meta: &SessionMeta{ID: "sess-print", CWD: workspace}}
+ base, _ := asymptoteobserve.DSHSpoolPath(workspace, ref.ID)
+ writeSpoolFile(t, base, spoolTestEvent(t, ref.ID, "session.started", "id-p"))
+
+ drained, err := drainSessionSpool(ref, opts, nil)
+ if err != nil {
+ t.Fatalf("drain in print mode: %v", err)
+ }
+ if drained != 0 {
+ t.Fatalf("print mode drained %d events, want 0", drained)
+ }
+ if pending := asymptoteobserve.DSHSpoolPendingBytes(workspace, ref.ID); pending == 0 {
+ t.Fatal("print mode consumed the spool file")
+ }
+}
+
+// Rotated archives hold older events than the live file; the drain empties them oldest
+// first so the runtime log receives the session's history in order.
+func TestDrainSessionSpoolEmptiesRotatedArchivesBeforeTheLiveFile(t *testing.T) {
+ workspace := t.TempDir()
+ opts := spoolTestOpts(t)
+ ref := SessionRef{ID: "sess-arch", Meta: &SessionMeta{ID: "sess-arch", CWD: workspace}}
+ base, _ := asymptoteobserve.DSHSpoolPath(workspace, ref.ID)
+ writeSpoolFile(t, base+".1", spoolTestEvent(t, ref.ID, "session.started", "id-old"))
+ writeSpoolFile(t, base, spoolTestEvent(t, ref.ID, "prompt.submitted", "id-new"))
+
+ drained, err := drainSessionSpool(ref, opts, loadDrainedIDs(opts.LogPath))
+ if err != nil {
+ t.Fatalf("drain: %v", err)
+ }
+ if drained != 2 {
+ t.Fatalf("drained = %d, want 2", drained)
+ }
+ events := readLogLines(t, opts.LogPath)
+ if len(events) != 2 || events[0].Event.Action != "session.started" || events[1].Event.Action != "prompt.submitted" {
+ t.Fatalf("order in log = %+v, want the archive's event first", actionsOf(events))
+ }
+ for _, path := range []string{base, base + ".1"} {
+ if _, err := os.Stat(path); !os.IsNotExist(err) {
+ t.Errorf("%s survived the drain: %v", path, err)
+ }
+ }
+}
+
+// A hook killed mid-append leaves a torn tail line. It is not an event and must not block
+// the valid events around it from draining.
+func TestDrainSessionSpoolDropsTornTailWithoutBlocking(t *testing.T) {
+ workspace := t.TempDir()
+ opts := spoolTestOpts(t)
+ ref := SessionRef{ID: "sess-torn", Meta: &SessionMeta{ID: "sess-torn", CWD: workspace}}
+ base, _ := asymptoteobserve.DSHSpoolPath(workspace, ref.ID)
+ writeSpoolFile(t, base, spoolTestEvent(t, ref.ID, "session.started", "id-ok"))
+ f, err := os.OpenFile(base, os.O_APPEND|os.O_WRONLY, 0o644)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if _, err := f.WriteString(`{"timestamp":"2026-09-23T0`); err != nil { // torn, no newline
+ t.Fatal(err)
+ }
+ if err := f.Close(); err != nil {
+ t.Fatal(err)
+ }
+
+ drained, err := drainSessionSpool(ref, opts, loadDrainedIDs(opts.LogPath))
+ if err != nil {
+ t.Fatalf("drain with a torn tail: %v", err)
+ }
+ if drained != 1 {
+ t.Fatalf("drained = %d, want 1 valid event", drained)
+ }
+ if _, err := os.Stat(base); !os.IsNotExist(err) {
+ t.Fatalf("file with a torn tail survived: %v", err)
+ }
+}
+
+// The drain takes the same lock every hook append takes. A hook firing mid-drain waits for
+// the sweep and then writes its event -- blocking is the filelock contract, dropping is
+// the bug #605 exists to prevent.
+func TestDrainSessionSpoolBlocksWhileAHookHoldsTheSpoolLock(t *testing.T) {
+ workspace := t.TempDir()
+ opts := spoolTestOpts(t)
+ ref := SessionRef{ID: "sess-lock", Meta: &SessionMeta{ID: "sess-lock", CWD: workspace}}
+ base, _ := asymptoteobserve.DSHSpoolPath(workspace, ref.ID)
+ writeSpoolFile(t, base, spoolTestEvent(t, ref.ID, "session.started", "id-l"))
+
+ hookLock, err := os.OpenFile(base+".lock", os.O_CREATE|os.O_RDWR, 0o666)
+ if err != nil {
+ t.Fatal(err)
+ }
+ held, err := filelock.Exclusive(hookLock)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ done := make(chan struct{})
+ var drained int
+ var drainErr error
+ var wg sync.WaitGroup
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ drained, drainErr = drainSessionSpool(ref, opts, loadDrainedIDs(opts.LogPath))
+ close(done)
+ }()
+
+ select {
+ case <-done:
+ t.Fatal("drain completed while a hook held the spool lock; it must block")
+ case <-time.After(100 * time.Millisecond):
+ }
+ if err := held.Release(); err != nil {
+ t.Fatal(err)
+ }
+ if err := hookLock.Close(); err != nil {
+ t.Fatal(err)
+ }
+ wg.Wait()
+ if drainErr != nil {
+ t.Fatalf("drain after lock release: %v", drainErr)
+ }
+ if drained != 1 {
+ t.Fatalf("drained = %d, want 1", drained)
+ }
+}
+
+// End to end through CollectOnce: a store session whose workspace holds a spool comes out
+// with the staged hook events AND the poll mapping in the log, the spool is gone, and the
+// sweep report counts the drained events separately so an operator can see the drain work.
+func TestCollectOnceDrainsTheWorkspaceSpoolAlongsideTheStore(t *testing.T) {
+ root := t.TempDir()
+ workspace := t.TempDir()
+ writeSession(t, filepath.Join(root, "sessions", "s-collect"), SessionFileJSON,
+ record("session", map[string]interface{}{"id": "s-collect", "cwd": workspace}),
+ record("user/message", map[string]interface{}{"message": map[string]interface{}{"content": "hello"}}),
+ )
+ base, _ := asymptoteobserve.DSHSpoolPath(workspace, "s-collect")
+ writeSpoolFile(t, base,
+ spoolTestEvent(t, "s-collect", "session.started", "id-spooled-start"),
+ spoolTestEvent(t, "s-collect", "prompt.submitted", "id-spooled-prompt"),
+ )
+
+ opts := CollectOptions{
+ DSHHome: root,
+ StatePath: filepath.Join(t.TempDir(), "state.json"),
+ Write: true,
+ LogPath: filepath.Join(t.TempDir(), "runtime.jsonl"),
+ UserMode: true,
+ }
+ summary, err := CollectOnce(opts)
+ if err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ if summary.SpoolEvents != 2 {
+ t.Fatalf("SpoolEvents = %d, want 2", summary.SpoolEvents)
+ }
+ if summary.EventsEmitted == 0 {
+ t.Fatal("poll mapping emitted nothing; the fixture session was not collected")
+ }
+ if pending := asymptoteobserve.DSHSpoolPendingBytes(workspace, "s-collect"); pending != 0 {
+ t.Fatalf("spool still holds %d bytes after the sweep", pending)
+ }
+ var hookEvents, pollEvents int
+ for _, event := range readLogLines(t, opts.LogPath) {
+ switch event.Harness.CollectionMethod {
+ case asymptoteobserve.CollectionMethodHook:
+ hookEvents++
+ case asymptoteobserve.CollectionMethodPoll:
+ pollEvents++
+ }
+ }
+ if hookEvents != 2 {
+ t.Errorf("hook events in log = %d, want 2 (the drained spool)", hookEvents)
+ }
+ if pollEvents == 0 {
+ t.Errorf("poll events in log = 0, want the store mapping too")
+ }
+}
+
+// The --workspace / --session-id filters decide which sessions are considered at all; a
+// filtered-out session's spool is left untouched rather than half-drained behind the
+// operator's filter.
+func TestCollectOnceLeavesASpoolWhenItsSessionIsFilteredOut(t *testing.T) {
+ root := t.TempDir()
+ workspace := t.TempDir()
+ writeSession(t, filepath.Join(root, "sessions", "s-filtered"), SessionFileJSON,
+ record("session", map[string]interface{}{"id": "s-filtered", "cwd": workspace}),
+ )
+ base, _ := asymptoteobserve.DSHSpoolPath(workspace, "s-filtered")
+ writeSpoolFile(t, base, spoolTestEvent(t, "s-filtered", "session.started", "id-f"))
+
+ opts := CollectOptions{
+ DSHHome: root,
+ StatePath: filepath.Join(t.TempDir(), "state.json"),
+ Write: true,
+ LogPath: filepath.Join(t.TempDir(), "runtime.jsonl"),
+ UserMode: true,
+ SessionID: "someone-else",
+ }
+ summary, err := CollectOnce(opts)
+ if err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ if summary.SpoolEvents != 0 {
+ t.Fatalf("filtered sweep drained %d events, want 0", summary.SpoolEvents)
+ }
+ if pending := asymptoteobserve.DSHSpoolPendingBytes(workspace, "s-filtered"); pending == 0 {
+ t.Fatal("filtered session's spool was consumed")
+ }
+}
+
+func actionsOf(events []schema.Event) []string {
+ out := make([]string, 0, len(events))
+ for _, event := range events {
+ out = append(out, event.Event.Action)
+ }
+ return out
+}
diff --git a/cli/beacon/internal/endpoint/hooks/dsh.go b/cli/beacon/internal/endpoint/hooks/dsh.go
index b6aaab2f..55fecf0c 100644
--- a/cli/beacon/internal/endpoint/hooks/dsh.go
+++ b/cli/beacon/internal/endpoint/hooks/dsh.go
@@ -553,7 +553,8 @@ Run this first:
beacon endpoint dsh status --workspace "$PWD" --json
` + "```" + `
-Summarize whether the current workspace has pending DeepSeek session records.
+Summarize whether the current workspace has pending DeepSeek session records or staged
+hook events (spool_bytes, waiting for the next sync to drain them).
## Sync Current Workspace
@@ -565,6 +566,7 @@ beacon endpoint dsh sync --workspace "$PWD"
` + "```" + `
Use ` + "`--print`" + ` only when the user wants to preview mapped events without writing Beacon's
-runtime log.
+runtime log. A sync also drains staged hook events from the workspace spool into the runtime
+log, which ` + "`--print`" + ` does not do.
`
}
diff --git a/docs/cli/endpoint-doctor.mdx b/docs/cli/endpoint-doctor.mdx
index a5d36512..88ce0e5b 100644
--- a/docs/cli/endpoint-doctor.mdx
+++ b/docs/cli/endpoint-doctor.mdx
@@ -90,7 +90,7 @@ It is a warning, not a failure: installing packages into a `dsh` profile is the
### `dsh_hook_capture`
-This check runs only when DeepSeek Harness is detected and Beacon's hooks for it are installed. It catches a failure no other check sees: the hooks are loaded, but they cannot write the runtime log because `dsh` runs them inside its session sandbox. `harness_observed` stays green in this state, because `beacon endpoint dsh sync` fills the log with poll events under the same harness name.
+This check runs only when DeepSeek Harness is detected and Beacon's hooks for it are installed. It catches a failure no other check sees: the hooks are loaded, but they cannot write the runtime log because `dsh` runs them inside its session sandbox. In `workspace-write` the hook stages the event in the session workspace instead; in `read-only` nothing is writable and nothing is captured. `harness_observed` stays green in either state, because `beacon endpoint dsh sync` fills the log with poll events under the same harness name.
```
dsh_hook_capture: warn target=deepseek_harness (2 DeepSeek Harness session(s) ran without a live
@@ -99,6 +99,15 @@ dsh_hook_capture: warn target=deepseek_harness (2 DeepSeek Harness session(s) ra
action="run `beacon endpoint dsh sync` to backfill those sessions from DeepSeek's session store; ..."
```
+Sessions with staged events count differently. When a session's workspace spool still holds hook events, the check reports `dsh_spool_pending_drain` — capture is working, the sweep has not run — with the action `run beacon endpoint dsh sync`. Those sessions are not counted as missed, and once drained their events land as `harness.collection_method=hook` and satisfy the check like any other live capture.
+
+```
+dsh_spool_pending_drain: warn target=deepseek_harness (1 DeepSeek Harness session(s) have hook
+ events staged in their workspace spool; capture is working, but the events are not in
+ ~/.beacon/endpoint/logs/runtime.jsonl yet)
+ action="run `beacon endpoint dsh sync` to drain the staged events into the runtime log"
+```
+
Doctor cannot reproduce the sandbox, because running the hook command from doctor runs it outside `dsh`, where it succeeds. So the check compares evidence instead. It counts native sessions that DeepSeek wrote after the hooks were installed and more than a few minutes after the last event with `harness.collection_method=hook`. The live log and every rotated archive are searched for that event. Each of those sessions is one the live hooks did not capture. Once rotation has started discarding history, sessions older than the oldest retained event are not counted, because their hook events may have rotated out. Evidence doctor cannot read, such as a missing hooks file, is reported as a warning rather than a pass. The other cause is a `dsh` process that was already running when the hooks were installed and has not been restarted.
This is a warning, not a failure. The sandbox mode is the operator's choice in `dsh`, and Beacon does not change it. `--fix` lists the check as a manual skip. See [Live hooks and the DeepSeek Harness sandbox](/runtimes/deepseek-harness#live-hooks-and-the-deepseek-harness-sandbox).
diff --git a/docs/cli/endpoint-dsh.mdx b/docs/cli/endpoint-dsh.mdx
index 3606c12f..fc304fb4 100644
--- a/docs/cli/endpoint-dsh.mdx
+++ b/docs/cli/endpoint-dsh.mdx
@@ -20,10 +20,12 @@ command/file/MCP detail, and token usage that the hook bridge does not expose.
See [Reading the session store](/runtimes/deepseek-harness#reading-the-session-store)
for how each record maps.
-Every event from this command is marked
-`harness.collection_method=poll`. Beacon reads committed records after the fact,
-so this path cannot hold, approve, deny, or delay a tool call and does not
-synthesize approval events. Reading is local and offline.
+Every event mapped from a session record is marked `harness.collection_method=poll`. Beacon
+reads committed records after the fact, so this path cannot hold, approve, deny, or delay
+a tool call and does not synthesize approval events. Reading is local and offline. A sweep
+also drains workspace spools: hook events that a sandboxed DeepSeek session staged in
+`<workspace>/.beacon/dsh-spool/` are appended with the `harness.collection_method=hook`
+label they were captured under, so the two sources stay distinguishable in the log.
## Commands
@@ -75,6 +77,19 @@ the endpoint, or leave `--watch` running in the account that owns `$DSH_HOME`.
A partly written trailing record is left for the next sweep rather than treated
as corruption.
+Each sweep also drains workspace spools. When DeepSeek Harness runs hooks
+inside its session sandbox, a hook that cannot write the runtime log stages the
+event at `<workspace>/.beacon/dsh-spool/<session>.jsonl`; the sweep appends
+those events to the runtime log and deletes the staged files. The report says
+how many landed:
+
+```text
+dsh sync: 3 sessions, 1 changed, 12 events, 0 errors
+ 2 spooled hook event(s) drained from workspace spools
+```
+
+Draining runs only in write mode: `--print` leaves spools untouched.
+
## Status
```bash title="Show sessions and collection progress"
@@ -85,6 +100,12 @@ The cursor prevents scheduled sweeps from re-appending a session's complete
history. Re-reading is safe: the same source record maps to the same deterministic
event id.
+Status also reports `spool_bytes` per session — hook events staged in that
+session's workspace spool, waiting for the next sweep to drain them into the
+runtime log. Zero is the steady state; anything else means live capture worked
+and the last sweep has not run yet. The text form shows it as
+`(spool N B awaiting drain)`.
+
## Related
<Columns cols={2}>
diff --git a/docs/runtimes/deepseek-harness.mdx b/docs/runtimes/deepseek-harness.mdx
index a68ad2e6..e2cacc41 100644
--- a/docs/runtimes/deepseek-harness.mdx
+++ b/docs/runtimes/deepseek-harness.mdx
@@ -116,18 +116,24 @@ Records Beacon does not map are left out deliberately: retried or failed model a
**In every sandbox mode except `danger-full-access`, live hooks cannot write Beacon's runtime log.** `dsh` runs hook commands inside the same sandbox as the session, confined to the session's working directory. Its sandbox policy is a mode plus a workspace root, with no list of extra writable paths, so a hook cannot reach `~/.beacon/endpoint/logs/runtime.jsonl` or any other path outside the workspace. The default mode is `read-only`, and `workspace-write` is the common working mode, so this is the usual case rather than an unusual one.
</Warning>
-When this happens, each hook still exits `0`. That is deliberate: on this hook contract, exit code `2` is a **block**. It would refuse the tool call, erase the prompt, or stop a turn from ending, on every event, for as long as the log stays unwritable, and a telemetry write that failed must never become a control decision. Instead, the hook prints on stderr that the event was **not recorded**, names the log path and the error, and points at the remedies. The explanation is printed once per hook invocation, not once per event, so it stays readable wherever `dsh` shows or logs hook output.
+When this happens, each hook still exits `0`. That is deliberate: on this hook contract, exit code `2` is a **block**. It would refuse the tool call, erase the prompt, or stop a turn from ending, on every event, for as long as the log stays unwritable, and a telemetry write that failed must never become a control decision.
-The poll half is unaffected. `beacon endpoint dsh sync` runs outside the harness and reads DeepSeek's own session store, so sessions the hooks missed can still be backfilled with assistant text, tool calls, commands, file activity, and token usage. What is lost is the **live** path: poll events arrive after the fact, carry `harness.collection_method=poll`, and cannot hold or deny a tool call.
+What the hook does next depends on the sandbox mode:
-`beacon endpoint doctor` reports this as `dsh_hook_capture: warn` when DeepSeek sessions have run since the hooks were installed but no live hook event has been recorded. The regular `harness_observed` check cannot catch it, because synced poll events satisfy it. See [`dsh_hook_capture`](/cli/endpoint-doctor#dsh_hook_capture).
+- **`workspace-write`: the event is staged in the workspace.** The hook writes it to `<workspace>/.beacon/dsh-spool/<session>.jsonl` — the one path both sides can reach: the sandbox confines hook writes to the session's working directory, and `beacon endpoint dsh sync` runs outside the harness. Staging is silent on stderr (one process per event, so a note here would be a note on every event); the staged state shows up as `spool_bytes` in `beacon endpoint dsh status` instead. On first spool use in a repository, the hook also adds the directory to `.git/info/exclude` — the local, unshared ignore file, never `.gitignore` — so it stays out of `git status`.
+- **`read-only` (the default): nothing is writable, including the workspace.** The spool write fails too. The hook then prints on stderr that the event was **not recorded**, names the log path and the error, and points at the remedies. The explanation is printed once per hook invocation, not once per event, so it stays readable wherever `dsh` shows or logs hook output.
+
+The poll half is unaffected. `beacon endpoint dsh sync` runs outside the harness and reads DeepSeek's own session store, so sessions the hooks missed can still be backfilled with assistant text, tool calls, commands, file activity, and token usage. What is lost without live capture is immediacy: poll events arrive after the fact, carry `harness.collection_method=poll`, and cannot hold or deny a tool call. Drained spool events are the opposite: they were captured live and keep `harness.collection_method=hook` when the sweep appends them, so they count as live capture everywhere it is measured.
+
+`beacon endpoint doctor` reports this as `dsh_hook_capture: warn` when DeepSeek sessions have run since the hooks were installed but no live hook event has been recorded. Sessions whose events are staged but not yet swept get their own evidence, `dsh_spool_pending_drain`: capture is working, the sweep has not run yet. The regular `harness_observed` check cannot catch either state, because synced poll events satisfy it. See [`dsh_hook_capture`](/cli/endpoint-doctor#dsh_hook_capture).
Your options:
- **Rely on the poll path.** Keep the sandbox and run `beacon endpoint dsh sync`, or ask `dsh` to run it through the Beacon skill. You get everything the store holds, without live capture or the policy seam.
-- **Run `dsh` in `danger-full-access` mode** for sessions that need live capture. This removes the sandbox for the whole session, not just for the hooks, so it is a security decision to make on its own merits. Beacon does not change the sandbox mode for you.
+- **Run in `workspace-write` and sweep on a schedule.** Hooks capture live and stage into the workspace spool; a scheduled `beacon endpoint dsh sync` (or `--watch`) drains staged events into the runtime log as hook events. Until the sweep runs they are counted in `dsh status` as `spool_bytes`, not in the log.
+- **Run `dsh` in `danger-full-access` mode** for sessions that need direct live capture. This removes the sandbox for the whole session, not just for the hooks, so it is a security decision to make on its own merits. Beacon does not change the sandbox mode for you.
-Beacon does not yet have a runtime log location a sandboxed hook can write to. The only writable path is the session's own workspace, which changes from session to session and is usually a repository.
+The spool is the runtime-log-adjacent location a sandboxed hook can write: the session's own workspace, which changes from session to session and is usually a repository. That is why it holds nothing but telemetry, is emptied on every sweep, and is kept out of `git status` through `.git/info/exclude` rather than by touching the repository's `.gitignore`.
<Warning>
**There is no project scope.** The bridge's `configPath` is process-level — read once at startup — and per-session discovery of a project-local hooks file is unimplemented in the bridge itself. A repository has nowhere to mount a hook bridge from, so `--level project` is **refused with that explanation** rather than quietly becoming a machine-wide install. DeepSeek Harness is also left out of the project-level `--all` sweep for the same reason.
@@ -292,7 +298,7 @@ Unlike [Kiro](/runtimes/kiro) and [OpenHands](/runtimes/openhands), Beacon **doe
- **No transcript path on hooks.** The bridge always sends `transcript_path` as the empty string. Use `beacon endpoint dsh sync` for the native session-store path.
- **No compaction events.** `PreCompact` and `PostCompact` are among the events the bridge does not support.
- **Subagent detail is thin.** The bridge reports a constant `agent_type` of `general-purpose` and uses the child's session id where Claude Code reports the parent's, so a subagent event cannot be joined to the session that spawned it.
-- **Live hooks need `danger-full-access`.** In the `read-only` (default) and `workspace-write` sandbox modes, hooks cannot write the runtime log, so live capture records nothing and `beacon endpoint dsh sync` is the collection path. See [Live hooks and the DeepSeek Harness sandbox](#live-hooks-and-the-deepseek-harness-sandbox).
+- **Live capture needs a writable workspace, or `danger-full-access` for a direct write.** In `workspace-write`, hooks stage events in the session workspace and `beacon endpoint dsh sync` drains them into the runtime log — staged events are not in the log until a sweep runs. In `read-only` (the default) nothing is writable, so hooks record nothing and sync from DeepSeek's session store is the collection path. Only `danger-full-access` writes the runtime log directly. See [Live hooks and the DeepSeek Harness sandbox](#live-hooks-and-the-deepseek-harness-sandbox).
- **No project scope.** See the warning under [Collection path](#collection-path).
- **Only command hooks run.** The bridge runs shell-form `command` handlers only, which is what Beacon writes. It has no bearing on Beacon's install and is noted because it bounds what else you can put in the same file.
diff --git a/pkg/asymptoteobserve/spool.go b/pkg/asymptoteobserve/spool.go
new file mode 100644
index 00000000..6ea8bb38
--- /dev/null
+++ b/pkg/asymptoteobserve/spool.go
@@ -0,0 +1,102 @@
+package asymptoteobserve
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+)
+
+// DSHSpoolDirRel is the workspace-relative directory where sandboxed DeepSeek Harness hook
+// events are staged when the runtime log under ~/.beacon is unreachable from inside the
+// session sandbox (#605). It is the only file Beacon ever writes into a DSH workspace: the
+// sandbox policy confines hook writes to the session cwd, so this is the one durable
+// location both the hook (inside the sandbox) and `beacon endpoint dsh sync` (outside it)
+// can reach. Sync drains each file and deletes it; the directory itself is left in place,
+// covered by a best-effort .git/info/exclude entry the hook writes on first use.
+var DSHSpoolDirRel = filepath.Join(".beacon", "dsh-spool")
+
+// dshSpoolMaxSessionID bounds the filename component so a hostile or malformed session id
+// cannot produce an unwieldy path. Real ids are UUID-shaped; 128 is far above any of them.
+const dshSpoolMaxSessionID = 128
+
+// ValidDSHSessionIDForSpool reports whether a session id is safe to use as a spool filename
+// component. The id arrives from the runtime's hook payload and from the session store, so
+// both the writer and the drainer must agree on exactly which ids get a spool file: an id
+// containing a path separator, a dot-only component, or anything outside the portable
+// filename alphabet gets no spool at all, on both sides, rather than a sanitized name the
+// other side would never look for.
+func ValidDSHSessionIDForSpool(id string) bool {
+ if id == "" || len(id) > dshSpoolMaxSessionID {
+ return false
+ }
+ if id == "." || id == ".." || strings.HasPrefix(id, ".") {
+ return false
+ }
+ for _, r := range id {
+ switch {
+ case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9':
+ case r == '-' || r == '_' || r == '.':
+ default:
+ return false
+ }
+ }
+ return true
+}
+
+// DSHSpoolDir returns the spool directory for a workspace, with no validity implied about
+// any session id.
+func DSHSpoolDir(workspace string) string {
+ return filepath.Join(workspace, DSHSpoolDirRel)
+}
+
+// DSHSpoolPath returns the spool file for one session in one workspace. ok is false when
+// the session id is not a safe filename component; the writer then records nothing to a
+// spool and the drainer looks for nothing, which is the agreement ValidDSHSessionIDForSpool
+// exists to keep.
+func DSHSpoolPath(workspace, sessionID string) (path string, ok bool) {
+ if workspace == "" || !ValidDSHSessionIDForSpool(sessionID) {
+ return "", false
+ }
+ return filepath.Join(DSHSpoolDir(workspace), sessionID+".jsonl"), true
+}
+
+// DSHSpoolFiles lists the spool data files that exist for one session, oldest first: the
+// rotated archives the hook writer may have produced (.5 down to .1) before the live file.
+// Lock files are not data and are never listed; they persist in the directory by design.
+func DSHSpoolFiles(workspace, sessionID string) []string {
+ base, ok := DSHSpoolPath(workspace, sessionID)
+ if !ok {
+ return nil
+ }
+ var out []string
+ for i := defaultEndpointRotateArchives; i >= 1; i-- {
+ candidate := base + "." + fmt.Sprintf("%d", i)
+ if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+ out = append(out, candidate)
+ }
+ }
+ if info, err := os.Stat(base); err == nil && !info.IsDir() {
+ out = append(out, base)
+ }
+ return out
+}
+
+// DSHSpoolPendingBytes reports how many bytes of undrained spool a workspace holds for one
+// session: zero when the id is invalid or nothing was ever staged. Status and doctor use it
+// as the "captured, not yet in the runtime log" signal.
+func DSHSpoolPendingBytes(workspace, sessionID string) int64 {
+ var total int64
+ for _, path := range DSHSpoolFiles(workspace, sessionID) {
+ if info, err := os.Stat(path); err == nil {
+ total += info.Size()
+ }
+ }
+ return total
+}
+
+// defaultEndpointRotateArchives mirrors the hook writer's archive count (5) so the file
+// enumeration here names the same set the writer rotates through. Kept local to avoid
+// exporting a rotation knob from this package; the hook writer's constant is pinned by its
+// own tests against this list.
+const defaultEndpointRotateArchives = 5
diff --git a/pkg/asymptoteobserve/spool_test.go b/pkg/asymptoteobserve/spool_test.go
new file mode 100644
index 00000000..4d6eba87
--- /dev/null
+++ b/pkg/asymptoteobserve/spool_test.go
@@ -0,0 +1,90 @@
+package asymptoteobserve
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+func TestValidDSHSessionIDForSpool(t *testing.T) {
+ cases := []struct {
+ id string
+ want bool
+ }{
+ {"60fdb1c1-0000-5000-8000-000000000000", true},
+ {"session-abc_123.v2", true},
+ {"", false},
+ {".", false},
+ {"..", false},
+ {".hidden", false},
+ {"a/b", false},
+ {"a\\b", false},
+ {"../escape", false},
+ {"has space", false},
+ {"line\nbreak", false},
+ {string(make([]byte, 129)), false},
+ }
+ for _, tc := range cases {
+ if got := ValidDSHSessionIDForSpool(tc.id); got != tc.want {
+ t.Errorf("ValidDSHSessionIDForSpool(%q) = %v, want %v", tc.id, got, tc.want)
+ }
+ }
+}
+
+// The writer and the drainer must derive the same path from the same inputs, and an unsafe
+// id must yield no path on BOTH sides rather than one side's sanitized guess.
+func TestDSHSpoolPathAgreesOnSafeAndUnsafeIDs(t *testing.T) {
+ workspace := t.TempDir()
+ path, ok := DSHSpoolPath(workspace, "sess-1")
+ if !ok {
+ t.Fatal("safe id produced no path")
+ }
+ want := filepath.Join(workspace, ".beacon", "dsh-spool", "sess-1.jsonl")
+ if path != want {
+ t.Errorf("DSHSpoolPath = %q, want %q", path, want)
+ }
+ if _, ok := DSHSpoolPath(workspace, "../evil"); ok {
+ t.Error("unsafe id produced a path")
+ }
+ if _, ok := DSHSpoolPath("", "sess-1"); ok {
+ t.Error("empty workspace produced a path")
+ }
+}
+
+// Pending bytes count data files oldest-first (rotated archives before the live file) and
+// never count lock files, which live in the same directory by design.
+func TestDSHSpoolFilesAndPendingBytes(t *testing.T) {
+ workspace := t.TempDir()
+ dir := DSHSpoolDir(workspace)
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if got := DSHSpoolPendingBytes(workspace, "sess-1"); got != 0 {
+ t.Errorf("PendingBytes with no files = %d, want 0", got)
+ }
+ base, _ := DSHSpoolPath(workspace, "sess-1")
+ files := map[string]string{
+ base + ".1": "aaaaa",
+ base: "bb",
+ base + ".lock": "notdata", // lock file: must never be listed or counted
+ "other.jsonl": "ccc", // another session's spool: not ours
+ }
+ for name, content := range files {
+ if err := os.WriteFile(name, []byte(content), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ }
+ got := DSHSpoolFiles(workspace, "sess-1")
+ want := []string{base + ".1", base} // archive first, live file last
+ if len(got) != len(want) {
+ t.Fatalf("DSHSpoolFiles = %v, want %v", got, want)
+ }
+ for i := range want {
+ if got[i] != want[i] {
+ t.Errorf("DSHSpoolFiles[%d] = %q, want %q", i, got[i], want[i])
+ }
+ }
+ if pending := DSHSpoolPendingBytes(workspace, "sess-1"); pending != 7 {
+ t.Errorf("PendingBytes = %d, want 7 (5+2; lock and other-session files excluded)", pending)
+ }
+}