Skip to content

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

Surface dsh hook runtime-log write failures and detect them in doctor

Claudedd22a89760b5
diff --git a/cli/beacon-hooks/cmd/dsh_hooks_test.go b/cli/beacon-hooks/cmd/dsh_hooks_test.go
index 221dc60d..abe1145e 100644
--- a/cli/beacon-hooks/cmd/dsh_hooks_test.go
+++ b/cli/beacon-hooks/cmd/dsh_hooks_test.go
@@ -1,9 +1,13 @@
package cmd
import (
+ "os"
+ "path/filepath"
"strings"
"testing"
+ "github.com/spf13/cobra"
+
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/policycontract"
)
@@ -836,3 +840,82 @@ func leafString(input map[string]interface{}, key string) string {
value, _ := input[key].(string)
return value
}
+
+// ---------------------------------------------------------------------------
+// Unwritable runtime log (#605)
+// ---------------------------------------------------------------------------
+
+// DeepSeek Harness runs hook commands sandboxed to the session workspace in every sandbox mode but
+// danger-full-access, so a hook commonly cannot write ~/.beacon at all. The hook must stay what it
+// is on every other path -- non-blocking, exit 0, a no-opinion `{}` for the bridge's decoder --
+// because on this Claude-shaped contract exit 2 is a block: it would refuse the tool, erase the
+// prompt, or keep a Stop from ending the turn, on every event. What changes is that the loss is
+// said out loud on stderr instead of in a single terse line.
+func TestDshUnwritableRuntimeLogStaysNonBlockingAndSaysWhy(t *testing.T) {
+ origPlatform := platformFlag
+ t.Cleanup(func() { platformFlag = origPlatform })
+
+ cases := []struct {
+ name string
+ run func(cmd *cobra.Command, args []string)
+ input map[string]interface{}
+ }{
+ {"session-start", runSessionStart, dshEvent("SessionStart", "d-ro-start", map[string]interface{}{"source": "startup"})},
+ {"prompt-submit", runPromptSubmit, dshEvent("UserPromptSubmit", "d-ro-prompt", map[string]interface{}{"prompt": "hello"})},
+ {"pre-tool", runPreTool, dshEvent("PreToolUse", "d-ro-pre", map[string]interface{}{
+ "tool_name": "bash", "tool_input": map[string]interface{}{"command": "ls"}, "tool_use_id": "call-ro-1",
+ })},
+ // stop is deliberately absent: runStop ends with os.Exit(0) after writing its response,
+ // which cannot run in-process. It takes the same emitHookEvent path as the three above.
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ dshTestSetup(t)
+ dir := t.TempDir()
+ blocker := filepath.Join(dir, "read-only")
+ if err := os.WriteFile(blocker, []byte("x"), 0o644); err != nil {
+ t.Fatalf("write blocker: %v", err)
+ }
+ // The parent is a regular file, so the log cannot be created on any platform: the
+ // portable stand-in for the read-only file system the sandbox presents.
+ logPath := filepath.Join(blocker, "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ var out map[string]interface{}
+ stderr := captureHookStderr(t, func() {
+ out = runHookWithInput(t, tc.run, tc.input)
+ })
+ if len(out) != 0 {
+ t.Fatalf("stdout = %#v, want the empty no-opinion object; a write failure must not become a decision", out)
+ }
+ for _, want := range []string{"NOT recorded", logPath, "danger-full-access", "beacon endpoint dsh sync"} {
+ if !strings.Contains(stderr, want) {
+ t.Fatalf("stderr does not mention %q:\n%s", want, stderr)
+ }
+ }
+ })
+ }
+}
+
+// captureHookStderr runs fn with os.Stderr redirected to a file and returns what was written.
+func captureHookStderr(t *testing.T, fn func()) string {
+ t.Helper()
+ f, err := os.CreateTemp(t.TempDir(), "stderr")
+ if err != nil {
+ t.Fatalf("create stderr capture: %v", err)
+ }
+ orig := os.Stderr
+ os.Stderr = f
+ func() {
+ defer func() { os.Stderr = orig }()
+ fn()
+ }()
+ if err := f.Close(); err != nil {
+ t.Fatalf("close stderr capture: %v", err)
+ }
+ data, err := os.ReadFile(f.Name())
+ if err != nil {
+ t.Fatalf("read stderr capture: %v", err)
+ }
+ return string(data)
+}
diff --git a/cli/beacon-hooks/internal/logging/endpoint_write_failure_test.go b/cli/beacon-hooks/internal/logging/endpoint_write_failure_test.go
new file mode 100644
index 00000000..727bc0dd
--- /dev/null
+++ b/cli/beacon-hooks/internal/logging/endpoint_write_failure_test.go
@@ -0,0 +1,155 @@
+package logging
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/config"
+)
+
+// 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.
+
+// 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
+// without needing root, a real sandbox, or a permission model that differs between Unix and
+// Windows.
+func unwritableEndpointLog(t *testing.T) string {
+ t.Helper()
+ dir := t.TempDir()
+ blocker := filepath.Join(dir, "not-a-directory")
+ if err := os.WriteFile(blocker, []byte("x"), 0o644); err != nil {
+ t.Fatalf("write blocker: %v", err)
+ }
+ return filepath.Join(blocker, "runtime.jsonl")
+}
+
+// captureStderr runs fn with os.Stderr redirected to a file and returns what was written.
+func captureStderr(t *testing.T, fn func()) string {
+ t.Helper()
+ f, err := os.CreateTemp(t.TempDir(), "stderr")
+ if err != nil {
+ t.Fatalf("create stderr capture: %v", err)
+ }
+ orig := os.Stderr
+ os.Stderr = f
+ func() {
+ defer func() { os.Stderr = orig }()
+ fn()
+ }()
+ if err := f.Close(); err != nil {
+ t.Fatalf("close stderr capture: %v", err)
+ }
+ data, err := os.ReadFile(f.Name())
+ if err != nil {
+ t.Fatalf("read stderr capture: %v", err)
+ }
+ return string(data)
+}
+
+// isolateHookHome keeps the per-runtime state directories NewLoggerForPlatform creates out of the
+// real home. They are resolved once at package init, so setting HOME alone would not move them.
+func isolateHookHome(t *testing.T) {
+ t.Helper()
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ origDsh, origCursor := config.DshDir, config.CursorDir
+ config.DshDir = filepath.Join(home, ".beacon", "dsh")
+ config.CursorDir = filepath.Join(home, ".beacon", "cursor")
+ t.Cleanup(func() { config.DshDir, config.CursorDir = origDsh, origCursor })
+}
+
+func TestEndpointWriteFailureExplainsTheDshSandbox(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ var writeErr error
+ stderr := captureStderr(t, func() {
+ logger := NewLoggerForPlatform("session-start", "dsh")
+ writeErr = logger.EndpointEvent("session.started", "session", "info", "Agent session started", nil)
+ })
+ if writeErr == nil {
+ t.Fatalf("EndpointEvent returned nil for an unwritable log; the caller could not tell the event was lost")
+ }
+ for _, want := range []string{
+ "this event was NOT recorded",
+ logPath,
+ "DeepSeek Harness",
+ "danger-full-access",
+ "beacon endpoint dsh sync",
+ "beacon endpoint doctor",
+ } {
+ if !strings.Contains(stderr, want) {
+ t.Fatalf("stderr does not mention %q:\n%s", want, stderr)
+ }
+ }
+}
+
+// The explanation is a paragraph, and one hook invocation can emit several events. It is printed
+// once per path per process so a runtime that shows hook stderr does not repeat it per event.
+func TestEndpointWriteFailureIsExplainedOncePerPath(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ stderr := captureStderr(t, func() {
+ logger := NewLoggerForPlatform("post-tool", "dsh")
+ for i := 0; i < 3; i++ {
+ _ = logger.EndpointEvent("tool.completed", "tool", "info", "Tool completed", nil)
+ }
+ })
+ if got := strings.Count(stderr, "this event was NOT recorded"); got != 1 {
+ t.Fatalf("explanation printed %d times, want once:\n%s", got, stderr)
+ }
+ // The terse per-event line is kept: it is what a log reader greps for, and it is one line.
+ if got := strings.Count(stderr, "failed to write endpoint event"); got != 3 {
+ t.Fatalf("per-event error line printed %d times, want 3:\n%s", got, stderr)
+ }
+}
+
+// Other runtimes get the generic explanation. Naming DeepSeek Harness's sandbox on a Cursor hook
+// would send an operator looking for a setting that does not exist there.
+func TestEndpointWriteFailureOnOtherRuntimesDoesNotBlameDsh(t *testing.T) {
+ isolateHookHome(t)
+ logPath := unwritableEndpointLog(t)
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ stderr := captureStderr(t, func() {
+ logger := NewLoggerForPlatform("session-start", "cursor")
+ _ = logger.EndpointEvent("session.started", "session", "info", "Agent session started", nil)
+ })
+ if !strings.Contains(stderr, "this event was NOT recorded") || !strings.Contains(stderr, "beacon endpoint doctor") {
+ t.Fatalf("stderr lacks the generic explanation:\n%s", stderr)
+ }
+ if strings.Contains(stderr, "DeepSeek") || strings.Contains(stderr, "dsh sync") {
+ t.Fatalf("a non-dsh hook blamed the DeepSeek Harness sandbox:\n%s", stderr)
+ }
+}
+
+// A write that succeeds says nothing. Several runtimes surface any hook stderr to the person at the
+// keyboard, so noise on the happy path would be a regression of its own.
+func TestEndpointWriteSuccessIsSilentOnStderr(t *testing.T) {
+ isolateHookHome(t)
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ stderr := captureStderr(t, func() {
+ logger := NewLoggerForPlatform("session-start", "dsh")
+ if err := logger.EndpointEvent("session.started", "session", "info", "Agent session started", nil); err != nil {
+ t.Errorf("EndpointEvent: %v", err)
+ }
+ })
+ if stderr != "" {
+ t.Fatalf("a successful write printed to stderr:\n%s", stderr)
+ }
+ if _, err := os.Stat(logPath); err != nil {
+ t.Fatalf("runtime log was not written: %v", err)
+ }
+}
diff --git a/cli/beacon-hooks/internal/logging/logging.go b/cli/beacon-hooks/internal/logging/logging.go
index 28714b37..1bef5977 100644
--- a/cli/beacon-hooks/internal/logging/logging.go
+++ b/cli/beacon-hooks/internal/logging/logging.go
@@ -3,12 +3,14 @@ package logging
import (
"encoding/json"
"fmt"
+ "io"
"os"
osuser "os/user"
"path/filepath"
"runtime"
"strconv"
"strings"
+ "sync"
"time"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/config"
@@ -131,11 +133,55 @@ func (l *Logger) EndpointEventWithFidelity(action, category, severity, message,
attachDerivedTrace(event)
if err := writeEndpointJSON(path, event); err != 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
}
return nil
}
+// 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
+// edit and the command in turn -- and a runtime that shows hook stderr to the person at the
+// keyboard would otherwise repeat the same paragraph for each.
+var reportedWriteFailures sync.Map
+
+// reportEndpointWriteFailure explains, on stderr, that an endpoint event was not recorded and what
+// to do about it.
+//
+// The one-line error above it names the path and the errno, which is enough for someone reading a
+// log and not enough for someone watching a hook fail: "read-only file system" from inside an
+// agent's sandbox reads like a broken disk, not like a runtime that confines its hooks.
+//
+// The exit status is deliberately not changed. Every hook path exits 0 (see the policy seam and
+// the per-runtime deny notes in cmd/policy.go), and on the Claude-shaped hook contract DeepSeek
+// Harness and several others reproduce, exit 2 is a *block*: it would refuse the tool call, erase
+// the prompt, or -- on Stop -- keep the agent running, on every event, for as long as the log stays
+// unwritable. A telemetry write that failed must never become a control decision, so the failure is
+// made loud here, on the stream a runtime shows or logs for a hook, and detectable from outside by
+// `beacon endpoint doctor`, which is where an operator can act on it.
+func reportEndpointWriteFailure(w io.Writer, platform, path string, err error) {
+ if w == nil || err == nil {
+ return
+ }
+ if _, already := reportedWriteFailures.LoadOrStore(path, true); already {
+ return
+ }
+ fmt.Fprintf(w, "beacon-hooks: this event was NOT recorded: cannot write the Beacon runtime log %s (%v).\n", path, err)
+ if asymptoteobserve.NormalizeHarnessName(platform) == dshHarnessName {
+ // DeepSeek Harness runs hook commands sandboxed to the session's working directory in
+ // every sandbox mode except danger-full-access, and its sandbox policy has no writable-path
+ // allow-list, so a log under the user's home is unreachable from a hook by design (#605).
+ fmt.Fprintln(w, "beacon-hooks: DeepSeek Harness runs hooks inside the session sandbox, which can write only the session workspace unless the sandbox mode is danger-full-access; if this session is sandboxed, that is the cause and live hook capture is off for it.")
+ fmt.Fprintln(w, "beacon-hooks: run `beacon endpoint dsh sync` outside the harness to backfill this session from DeepSeek's own session store, and `beacon endpoint doctor` to check hook capture.")
+ return
+ }
+ fmt.Fprintln(w, "beacon-hooks: check that this user can write that path (the hook may be running in a sandbox that confines writes), then run `beacon endpoint doctor`.")
+}
+
+// dshHarnessName is DeepSeek Harness's canonical harness.name.
+const dshHarnessName = "deepseek_harness"
+
// normalizeEventModel canonicalizes event["model"] in place, the way the harness name is
// canonicalized in baseEndpointEvent and for the same reason: every token report groups by this
// field, so one model reported under two spellings is two rows in the BY MODEL rollup.
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.go
index 0cf23317..03b20e78 100644
--- a/cli/beacon/cmd/endpoint_diagnostics.go
+++ b/cli/beacon/cmd/endpoint_diagnostics.go
@@ -14,6 +14,7 @@ import (
"github.com/spf13/cobra"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/dshsession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/embedded"
endpointcollector "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/collector"
@@ -154,15 +155,24 @@ func buildDoctorResult(status lifecycle.Status, generatedAt time.Time) doctorRes
checks = append(checks, consoleUserConfigCheck())
}
codexDetected := false
+ dshDetected := false
for _, h := range status.Harnesses {
checks = append(checks, harnessCheck(h, status.LogPath, status.RuntimeLog.EffectiveUserMode))
if h.Detected && h.Name == "codex_cli" {
codexDetected = true
}
+ if h.Detected && h.Name == dshsession.Harness {
+ dshDetected = true
+ }
}
if codexDetected {
checks = append(checks, codexTokenAttributionCheck(status.LogPath, status.RuntimeLog.EffectiveUserMode))
}
+ if dshDetected {
+ if check, ok := doctorDshHookCaptureCheck(status.LogPath); ok {
+ checks = append(checks, check)
+ }
+ }
result := doctorResult{
Status: aggregateCheckStatus(checks),
Checks: checks,
@@ -1543,6 +1553,11 @@ func planDoctorFixes(result doctorResult, status lifecycle.Status) doctorFixPlan
addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: message})
case "runtime_log_source":
addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: check.Action})
+ // Nothing here is Beacon's to repair: the sandbox mode is the operator's choice in dsh, and
+ // widening it on their behalf would be the wrong fix even if doctor could. Reported as a
+ // skip so --fix does not read as having found nothing.
+ case "dsh_hook_capture":
+ addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: check.Action})
}
}
return plan
diff --git a/cli/beacon/cmd/endpoint_dsh_doctor.go b/cli/beacon/cmd/endpoint_dsh_doctor.go
new file mode 100644
index 00000000..a8be1929
--- /dev/null
+++ b/cli/beacon/cmd/endpoint_dsh_doctor.go
@@ -0,0 +1,150 @@
+package cmd
+
+import (
+ "fmt"
+ "os"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/dshsession"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/diagnostics"
+ endpointhooks "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
+ endpointintegrations "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/integrations"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// dshHookCaptureGrace is how far a native session's last write may run past the last live hook
+// event before the session counts as one the hooks missed.
+//
+// DeepSeek Harness appends to its session store when a turn's records are committed, which can be
+// after the Stop hook for that turn has already run, so a session whose file is a little newer than
+// the last hook event is the normal shape of a working install. Five minutes is far longer than
+// that gap and far shorter than the time between two sessions an operator would notice missing.
+const dshHookCaptureGrace = 5 * time.Minute
+
+// doctorDshHookCaptureCheck is the check doctor runs, indirected so a doctor test can supply a
+// result without resolving the real Harness home.
+var doctorDshHookCaptureCheck = dshHookCaptureCheck
+
+// dshHookCaptureCheck reports whether DeepSeek Harness hooks are actually writing events.
+//
+// It exists because nothing else can see the failure (#605). dsh runs hook commands sandboxed to
+// the session workspace in every sandbox mode except danger-full-access, and its sandbox policy has
+// no writable-path allow-list, so beacon-hooks cannot write the runtime log under ~/.beacon. The
+// hook exits 0 on purpose (a non-zero exit is a block on this contract), the harness reports
+// nothing, and `harness_observed` stays green because `beacon endpoint dsh sync` fills the same log
+// with poll events under the same harness name.
+//
+// Doctor cannot reproduce the sandbox -- running the hook command from here runs it outside dsh,
+// where it succeeds -- so the check reads the evidence instead: native sessions DeepSeek wrote after
+// 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.
+func dshHookCaptureCheck(logPath string) (diagnostics.Check, bool) {
+ status := endpointhooks.DshHookStatus(endpointhooks.DshOptions{Level: endpointhooks.LevelUser})
+ if !status.Installed || status.HooksPath == "" {
+ return diagnostics.Check{}, false
+ }
+ store, err := dshsession.NewStore("")
+ if err != nil {
+ return diagnostics.Check{}, false
+ }
+ return dshHookCaptureCheckAt(logPath, status.HooksPath, store.DSHHome), true
+}
+
+// dshHookCaptureCheckAt is dshHookCaptureCheck with its inputs resolved, so it can be tested
+// against a temporary Harness home and runtime log.
+func dshHookCaptureCheckAt(logPath, hooksPath, dshHome string) diagnostics.Check {
+ check := diagnostics.Check{
+ Name: "dsh_hook_capture",
+ Target: dshsession.Harness,
+ Status: diagnostics.StatusOK,
+ Severity: diagnostics.SeverityInfo,
+ }
+
+ // The hooks file is rewritten wholesale by every install and repair, so its modification time
+ // is when the current hook commands took effect. Sessions before it were never going to be
+ // captured live and are not evidence of anything.
+ hooksInfo, err := os.Stat(hooksPath)
+ if err != nil {
+ check.Message = "DeepSeek Harness hooks file could not be read: " + err.Error()
+ check.Evidence = "dsh_hooks_unreadable"
+ return check
+ }
+ installedAt := hooksInfo.ModTime()
+
+ store, err := dshsession.NewStore(dshHome)
+ if err != nil {
+ check.Message = "DeepSeek Harness session store could not be resolved: " + err.Error()
+ check.Evidence = "dsh_sessions_unreadable"
+ return check
+ }
+ refs, err := store.List()
+ if err != nil {
+ check.Message = "DeepSeek Harness session store could not be read: " + err.Error()
+ check.Evidence = "dsh_sessions_unreadable"
+ return check
+ }
+
+ // The newest archive is read as well as the live log: a busy machine rotates at 10 MiB, and
+ // hook events that moved to runtime.jsonl.1 would otherwise make captured sessions read as
+ // missed.
+ var lastHook time.Time
+ hookSeen := false
+ for _, path := range []string{logPath, logPath + ".1"} {
+ if ts, ok := endpointintegrations.LastHarnessEventByCollectionMethod(path, dshsession.Harness, asymptoteobserve.CollectionMethodHook); ok {
+ hookSeen = true
+ if ts.After(lastHook) {
+ lastHook = ts
+ }
+ }
+ }
+ // 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.
+ cutoff := installedAt
+ if hookSeen && lastHook.After(cutoff) {
+ cutoff = lastHook.Add(dshHookCaptureGrace)
+ }
+ sinceInstall := 0
+ missed := 0
+ var newest time.Time
+ for _, ref := range refs {
+ modified := time.UnixMilli(ref.ModTimeUnixMS)
+ if modified.Before(installedAt) {
+ continue
+ }
+ sinceInstall++
+ if modified.After(cutoff) {
+ missed++
+ if modified.After(newest) {
+ newest = modified
+ }
+ }
+ }
+
+ switch {
+ 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:
+ check.Message = "live DeepSeek Harness hook events are being recorded"
+ check.Evidence = "dsh_hook_events_observed"
+ default:
+ since := "since the hooks were installed"
+ if hookSeen && lastHook.After(installedAt) {
+ since = "since " + lastHook.UTC().Format(time.RFC3339)
+ }
+ check.Status = diagnostics.StatusWarn
+ check.Severity = diagnostics.SeverityMedium
+ check.Evidence = "dsh_sessions_without_hook_events"
+ check.Message = fmt.Sprintf(
+ "%d DeepSeek Harness session(s) ran without a live hook event (newest %s; no hook event %s). "+
+ "The usual cause is dsh's sandbox: it runs hooks confined to the session workspace unless the sandbox "+
+ "mode is danger-full-access, so beacon-hooks cannot write %s and records nothing while still exiting 0",
+ missed, newest.UTC().Format(time.RFC3339), since, logPath)
+ check.Action = "run `beacon endpoint dsh sync` to backfill those sessions from DeepSeek's session store; " +
+ "for live hook capture, run dsh in danger-full-access mode, or restart dsh if it was already running when the hooks were installed"
+ }
+ return check
+}
diff --git a/cli/beacon/cmd/endpoint_dsh_doctor_test.go b/cli/beacon/cmd/endpoint_dsh_doctor_test.go
new file mode 100644
index 00000000..371914dd
--- /dev/null
+++ b/cli/beacon/cmd/endpoint_dsh_doctor_test.go
@@ -0,0 +1,277 @@
+package cmd
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/dshsession"
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/diagnostics"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/harness"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
+)
+
+// 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.
+
+// dshDoctorFixture is a Harness home with a hooks file installed at installedAt, and a runtime log.
+type dshDoctorFixture struct {
+ home string
+ hooksPath string
+ logPath string
+ installedAt time.Time
+}
+
+func newDshDoctorFixture(t *testing.T) dshDoctorFixture {
+ t.Helper()
+ root := t.TempDir()
+ f := dshDoctorFixture{
+ home: filepath.Join(root, "dsh-home"),
+ logPath: filepath.Join(root, "runtime.jsonl"),
+ installedAt: time.Date(2026, 9, 21, 9, 0, 0, 0, time.UTC),
+ }
+ f.hooksPath = filepath.Join(f.home, "beacon-endpoint-hooks.json")
+ if err := os.MkdirAll(f.home, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(f.hooksPath, []byte("{}"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.Chtimes(f.hooksPath, f.installedAt, f.installedAt); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(f.logPath, nil, 0o644); err != nil {
+ t.Fatal(err)
+ }
+ return f
+}
+
+// session writes a native session record last modified at modified.
+func (f dshDoctorFixture) session(t *testing.T, id 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")
+ if err := os.WriteFile(path, []byte(`{"type":"session","id":"`+id+`"}`+"\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.Chtimes(path, modified, modified); err != nil {
+ t.Fatal(err)
+ }
+}
+
+// event appends a deepseek_harness event collected by method at ts.
+func (f dshDoctorFixture) event(t *testing.T, method string, ts time.Time) {
+ t.Helper()
+ file, err := os.OpenFile(f.logPath, os.O_APPEND|os.O_WRONLY, 0o644)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer file.Close()
+ line := `{"timestamp":"` + ts.UTC().Format(time.RFC3339Nano) + `","harness":{"name":"deepseek_harness","collection_method":"` + method + `"}}` + "\n"
+ if _, err := file.WriteString(line); err != nil {
+ t.Fatal(err)
+ }
+}
+
+func (f dshDoctorFixture) check() diagnostics.Check {
+ return dshHookCaptureCheckAt(f.logPath, f.hooksPath, f.home)
+}
+
+// The reported case: sessions ran after install, `dsh sync` backfilled them as poll events, and no
+// live hook event exists. That must be a warning that names the sandbox and the remedies.
+func TestDshHookCaptureWarnsWhenSessionsRanWithoutHookEvents(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ f.session(t, "sess-a", f.installedAt.Add(time.Hour))
+ f.session(t, "sess-b", f.installedAt.Add(2*time.Hour))
+ f.event(t, "poll", f.installedAt.Add(3*time.Hour))
+
+ got := f.check()
+ if got.Name != "dsh_hook_capture" || got.Target != dshsession.Harness {
+ t.Fatalf("check identity = %s/%s, want dsh_hook_capture/%s", got.Name, got.Target, dshsession.Harness)
+ }
+ if got.Status != diagnostics.StatusWarn || got.Evidence != "dsh_sessions_without_hook_events" {
+ t.Fatalf("status/evidence = %s/%s, want warn/dsh_sessions_without_hook_events (%s)", got.Status, got.Evidence, got.Message)
+ }
+ for _, want := range []string{"2 DeepSeek Harness session(s)", "danger-full-access", f.logPath} {
+ if !strings.Contains(got.Message, want) {
+ t.Fatalf("message does not mention %q: %s", want, got.Message)
+ }
+ }
+ if !strings.Contains(got.Action, "beacon endpoint dsh sync") {
+ t.Fatalf("action does not name the backfill: %s", got.Action)
+ }
+}
+
+// A working install: hook events land in the same turns the session store records, a little before
+// the store's final write. That must not be flagged.
+func TestDshHookCaptureIsOKWhenHookEventsAccompanySessions(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ f.event(t, "hook", f.installedAt.Add(time.Hour))
+ // The store commits after the Stop hook, so its file is slightly newer than the last hook event.
+ f.session(t, "sess-a", f.installedAt.Add(time.Hour+time.Minute))
+
+ 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 (%s)", got.Status, got.Evidence, got.Message)
+ }
+}
+
+// A fresh install with only older sessions is not evidence of anything: those sessions ran before
+// the hooks existed. It must not warn.
+func TestDshHookCaptureIsOKBeforeAnySessionHasRunSinceInstall(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ f.session(t, "old", f.installedAt.Add(-24*time.Hour))
+
+ got := f.check()
+ if got.Status != diagnostics.StatusOK || got.Evidence != "dsh_no_sessions_since_install" {
+ t.Fatalf("status/evidence = %s/%s, want ok/dsh_no_sessions_since_install (%s)", got.Status, got.Evidence, got.Message)
+ }
+}
+
+// Capture that worked and then stopped -- a later session run in a sandboxed mode -- is flagged too,
+// and the message says since when.
+func TestDshHookCaptureWarnsWhenLiveCaptureStopsLater(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ lastHook := f.installedAt.Add(time.Hour)
+ f.event(t, "hook", lastHook)
+ f.session(t, "worked", lastHook.Add(time.Minute))
+ f.session(t, "sandboxed", lastHook.Add(3*time.Hour))
+
+ got := f.check()
+ if got.Status != diagnostics.StatusWarn {
+ t.Fatalf("status = %s, want warn (%s)", got.Status, got.Message)
+ }
+ if !strings.Contains(got.Message, "1 DeepSeek Harness session(s)") {
+ t.Fatalf("message should count only the session after the last hook event: %s", got.Message)
+ }
+ if !strings.Contains(got.Message, "since "+lastHook.UTC().Format(time.RFC3339)) {
+ t.Fatalf("message does not say when live capture stopped: %s", got.Message)
+ }
+}
+
+// Without an installed hook there is nothing to check; the harness check already reports that the
+// hooks are missing, and a second finding saying the same thing would be noise.
+func TestDshHookCaptureCheckIsSkippedWhenHooksAreNotInstalled(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv("DSH_HOME", filepath.Join(home, "dsh"))
+
+ if check, ok := dshHookCaptureCheck(filepath.Join(home, "runtime.jsonl")); ok {
+ t.Fatalf("dshHookCaptureCheck ran without installed hooks: %+v", check)
+ }
+}
+
+// End to end through a real install: the check resolves the hooks file and Harness home itself.
+func TestDshHookCaptureCheckFindsARealInstall(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ dshHome := filepath.Join(home, "dsh")
+ t.Setenv("DSH_HOME", dshHome)
+ origLevel := endpointOpts.hookLevel
+ t.Cleanup(func() { endpointOpts.hookLevel = origLevel })
+ endpointOpts.hookLevel = "user"
+
+ logPath := filepath.Join(home, "runtime.jsonl")
+ if err := installEndpointHookTarget("dsh", endpointconfig.Config{LogPath: logPath, UserMode: true}); err != nil {
+ t.Fatalf("install dsh hooks: %v", err)
+ }
+ f := dshDoctorFixture{home: dshHome, logPath: logPath}
+ f.session(t, "after-install", time.Now().Add(time.Minute))
+
+ check, ok := dshHookCaptureCheck(logPath)
+ if !ok {
+ t.Fatal("dshHookCaptureCheck skipped an installed dsh")
+ }
+ if check.Status != diagnostics.StatusWarn {
+ t.Fatalf("status = %s, want warn for a session with no hook events (%s)", check.Status, check.Message)
+ }
+}
+
+// Doctor runs the check when DeepSeek Harness is detected, reports it as a warning rather than a
+// failure (the sandbox mode is the operator's choice, and rollout automation keys on doctor's exit
+// status), and --fix lists it as a manual skip rather than silently repairing nothing.
+func TestDoctorRunsDshHookCaptureOnlyWhenDshIsDetected(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+
+ want := diagnostics.Check{
+ Name: "dsh_hook_capture", Target: dshsession.Harness, Status: diagnostics.StatusWarn,
+ Severity: diagnostics.SeverityMedium, Evidence: "dsh_sessions_without_hook_events",
+ Action: "run `beacon endpoint dsh sync`",
+ }
+ orig := doctorDshHookCaptureCheck
+ t.Cleanup(func() { doctorDshHookCaptureCheck = orig })
+ calls := 0
+ doctorDshHookCaptureCheck = func(string) (diagnostics.Check, bool) {
+ calls++
+ return want, true
+ }
+
+ status := lifecycle.Status{
+ LogPath: filepath.Join(home, "runtime.jsonl"),
+ RuntimeLog: lifecycle.RuntimeLogSource{EffectiveUserMode: true},
+ Harnesses: []harness.Harness{{Name: dshsession.Harness, Detected: true, TelemetryStatus: harness.TelemetryEnabled}},
+ }
+ result := buildDoctorResult(status, time.Now())
+ var found *diagnostics.Check
+ for i := range result.Checks {
+ if result.Checks[i].Name == "dsh_hook_capture" {
+ found = &result.Checks[i]
+ }
+ }
+ if found == nil || found.Status != diagnostics.StatusWarn {
+ t.Fatalf("doctor did not report dsh_hook_capture as a warning: %+v", result.Checks)
+ }
+
+ plan := planDoctorFixes(result, status)
+ skipped := false
+ for _, s := range plan.Skipped {
+ if s.Target == dshsession.Harness && s.Action == "manual_fix" {
+ skipped = true
+ }
+ }
+ if !skipped {
+ t.Fatalf("--fix did not list dsh_hook_capture as a manual skip: %+v", plan.Skipped)
+ }
+
+ status.Harnesses[0].Detected = false
+ calls = 0
+ result = buildDoctorResult(status, time.Now())
+ if calls != 0 {
+ t.Fatal("doctor ran dsh_hook_capture for an undetected DeepSeek Harness")
+ }
+ for _, c := range result.Checks {
+ if c.Name == "dsh_hook_capture" {
+ t.Fatalf("dsh_hook_capture reported without DeepSeek Harness: %+v", c)
+ }
+ }
+}
+
+// Hook events that rotated into runtime.jsonl.1 still count; otherwise a busy machine would report
+// captured sessions as missed after every rotation.
+func TestDshHookCaptureReadsTheRotatedArchive(t *testing.T) {
+ f := newDshDoctorFixture(t)
+ f.event(t, "hook", f.installedAt.Add(time.Hour))
+ if err := os.Rename(f.logPath, f.logPath+".1"); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(f.logPath, nil, 0o644); err != nil {
+ t.Fatal(err)
+ }
+ f.session(t, "sess-a", f.installedAt.Add(time.Hour+time.Minute))
+
+ if got := f.check(); got.Status != diagnostics.StatusOK {
+ t.Fatalf("status = %s, want ok when the hook event is in the rotated archive (%s)", got.Status, got.Message)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/integrations/logscan.go b/cli/beacon/internal/endpoint/integrations/logscan.go
index 3f985289..a3b59076 100644
--- a/cli/beacon/internal/endpoint/integrations/logscan.go
+++ b/cli/beacon/internal/endpoint/integrations/logscan.go
@@ -73,6 +73,25 @@ func HasHarnessEventSince(logPath, harnessName string, since time.Time) bool {
}
func LastHarnessEvent(logPath, harnessName string) (time.Time, bool) {
+ return lastHarnessEvent(logPath, harnessName, "")
+}
+
+// LastHarnessEventByCollectionMethod is LastHarnessEvent restricted to events whose
+// harness.collection_method is method.
+//
+// The distinction matters for a runtime with two capture paths. DeepSeek Harness has live hooks
+// and an offline poll of its session store, and both write events named deepseek_harness, so a
+// log full of backfilled poll events answers "has this harness been observed?" with yes while
+// every live hook is failing to write (#605). Asking for hook events alone is what separates the
+// two.
+func LastHarnessEventByCollectionMethod(logPath, harnessName, method string) (time.Time, bool) {
+ if strings.TrimSpace(method) == "" {
+ return time.Time{}, false
+ }
+ return lastHarnessEvent(logPath, harnessName, method)
+}
+
+func lastHarnessEvent(logPath, harnessName, method string) (time.Time, bool) {
if logPath == "" || strings.TrimSpace(harnessName) == "" {
return time.Time{}, false
}
@@ -104,6 +123,11 @@ func LastHarnessEvent(logPath, harnessName string) (time.Time, bool) {
}
if harness, ok := event["harness"].(map[string]interface{}); ok {
if name, _ := harness["name"].(string); asymptoteobserve.NormalizeHarnessName(name) == want {
+ if method != "" {
+ if got, _ := harness["collection_method"].(string); got != method {
+ continue
+ }
+ }
found = true
if ts, ok := event["timestamp"].(string); ok {
if parsed, err := time.Parse(time.RFC3339Nano, ts); err == nil && parsed.After(last) {
diff --git a/cli/beacon/internal/endpoint/integrations/logscan_harness_test.go b/cli/beacon/internal/endpoint/integrations/logscan_harness_test.go
index 6311dc3a..4974ccb7 100644
--- a/cli/beacon/internal/endpoint/integrations/logscan_harness_test.go
+++ b/cli/beacon/internal/endpoint/integrations/logscan_harness_test.go
@@ -80,3 +80,33 @@ func TestScanCodexUsageSignalsSeparatesAttributionSources(t *testing.T) {
t.Fatalf("signals = %#v, want one of each Codex source", got)
}
}
+
+// DeepSeek Harness writes deepseek_harness events from two paths: live hooks and the offline poll
+// of its session store. A log holding only poll events must not read as live hook capture, because
+// that is exactly the log a sandboxed dsh produces: every hook fails to write and `dsh sync` fills
+// the log anyway (#605).
+func TestLastHarnessEventByCollectionMethodIgnoresOtherPaths(t *testing.T) {
+ log := writeLog(t,
+ `{"timestamp":"2026-09-21T10:00:00Z","harness":{"name":"deepseek_harness","collection_method":"hook"}}`,
+ `{"timestamp":"2026-09-21T12:00:00Z","harness":{"name":"deepseek_harness","collection_method":"poll"}}`,
+ `{"timestamp":"2026-09-21T13:00:00Z","harness":{"name":"claude","collection_method":"hook"}}`,
+ )
+ got, ok := LastHarnessEventByCollectionMethod(log, "dsh", "hook")
+ if !ok {
+ t.Fatal("no hook event found, want the 10:00 one")
+ }
+ if want := "2026-09-21T10:00:00Z"; got.UTC().Format("2006-01-02T15:04:05Z") != want {
+ t.Fatalf("last hook event = %s, want %s: a poll event or another harness's hook was counted", got, want)
+ }
+
+ pollOnly := writeLog(t, `{"timestamp":"2026-09-21T12:00:00Z","harness":{"name":"deepseek_harness","collection_method":"poll"}}`)
+ if _, ok := LastHarnessEventByCollectionMethod(pollOnly, "deepseek_harness", "hook"); ok {
+ t.Fatal("a poll-only log reported a hook event")
+ }
+ if !HasRecentHarnessEvent(pollOnly, "deepseek_harness") {
+ t.Fatal("the unfiltered lookup must still count poll events")
+ }
+ if _, ok := LastHarnessEventByCollectionMethod(log, "deepseek_harness", ""); ok {
+ t.Fatal("an empty method must not match everything; callers use LastHarnessEvent for that")
+ }
+}
diff --git a/docs/cli/endpoint-doctor.mdx b/docs/cli/endpoint-doctor.mdx
index 66b9d118..6e343ba9 100644
--- a/docs/cli/endpoint-doctor.mdx
+++ b/docs/cli/endpoint-doctor.mdx
@@ -26,6 +26,7 @@ Doctor verifies:
- Runtime log permissions
- Service definition: launchd plist on macOS, systemd unit on Linux
- Configured harness telemetry and recent observed events
+- Whether DeepSeek Harness hooks are actually recording live events (`dsh_hook_capture`)
- Whether a real user's agent runtime points at the collector (system mode only)
The runtime log itself can be missing before the first event is written. In that case, doctor reports a warning instead of a hard failure.
@@ -46,6 +47,21 @@ Everything else can be green when this fails. The collector is running, the serv
If no logged-in user can be identified at all, this reports a warning rather than a failure: an unattended host legitimately has nobody to configure, and that is not something an operator can act on.
+### `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.
+
+```
+dsh_hook_capture: warn target=deepseek_harness (2 DeepSeek Harness session(s) ran without a live
+ hook event (newest 2026-09-21T11:00:00Z; no hook event since the hooks were installed). The usual
+ cause is dsh's sandbox: ...)
+ action="run `beacon endpoint dsh sync` to backfill those sessions from DeepSeek's session store; ..."
+```
+
+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`. Each of those is a session the live hooks did not capture. 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).
+
## Fix mode
`beacon endpoint doctor --fix` plans and applies safe remediations for supported findings. It can create a missing runtime log, and recreate managed collector configuration and the service definition (a launchd plist or a systemd unit) when the endpoint configuration is valid.
diff --git a/docs/runtimes/deepseek-harness.mdx b/docs/runtimes/deepseek-harness.mdx
index b11b01b2..59d88a61 100644
--- a/docs/runtimes/deepseek-harness.mdx
+++ b/docs/runtimes/deepseek-harness.mdx
@@ -62,6 +62,25 @@ beacon endpoint dsh status
The poll path is local and offline. It complements hooks by backfilling persisted assistant text, reasoning, structured tool failures, and token usage that the hook bridge does not expose. Poll events are marked `harness.collection_method=poll`, so they are historical observation only: they cannot approve, deny, hold, or delay a tool call.
+### Live hooks and the DeepSeek Harness sandbox
+
+<Warning>
+**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.
+
+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.
+
+`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).
+
+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.
+
+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.
+
<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.
</Warning>
@@ -223,6 +242,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).
- **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.
@@ -242,6 +262,7 @@ grep '"name":"deepseek_harness"' ~/.beacon/endpoint/logs/runtime.jsonl | tail -3
If DeepSeek Harness telemetry is missing:
+- Run `beacon endpoint doctor`. If it reports `dsh_hook_capture: warn`, the hooks are loaded but cannot write the log, which is almost always the session sandbox. See [Live hooks and the DeepSeek Harness sandbox](#live-hooks-and-the-deepseek-harness-sandbox). Hook stderr, and `dsh`'s own hook output, will show `beacon-hooks: this event was NOT recorded`.
- Confirm **both** files exist. `beacon endpoint hooks status --harness dsh` prints both paths; either one alone is inert.
- Check `$DSH_HOME`: if it is set, both files are under that directory, not `~/.dsh`.
- Confirm the mount's `configPath` points at the hooks file that is actually there. A reinstall repoints it.