roboshed 0.1.1.dev3__tar.gz → 0.1.1.dev4__tar.gz

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.1.1.dev4 - 2026-09-20
+
+- Migrate the Librarian and capability examples to Roboz's explicit
+  `mode=AgentMode.DETERMINISTIC` configuration. Breaking: remove
+  `interaction_mode` arguments from `orchestrator` and `robosprawl` calls;
+  invocation uses a bound host channel, defaulting to CLI. Registering a
+  `UserIO` adapter selects `Output.API` for the binding's lifetime.
+
+- Keep the Librarian active for a final maintenance sweep after watched runs become
+  idle, so terminal conversation facts reach snapshots and memory before it stops.
+  Snapshot coverage now relies only on persisted message sequences, and maintenance
+  artifacts are published atomically.
+
 ## 0.1.1.dev3 - 2026-09-13
 
 - Migrate capability bindings to the central typed contexts. Existing capability

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roboshed
-Version: 0.1.1.dev3
+Version: 0.1.1.dev4
 Import-Name: roboshed
 Summary: roboshed: optional building blocks for Roboz
 Project-URL: Repository, https://github.com/Tachion-Oy/roboz
@@ -11,7 +11,7 @@ Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: pydantic>=2.12.4
-Requires-Dist: roboz<0.2.0,>=0.1.2.dev5
+Requires-Dist: roboz<0.2.0,>=0.1.2.dev7
 Description-Content-Type: text/markdown
 
 # roboshed
@@ -25,7 +25,7 @@ install any model SDK, Proton, document SDK, web service, or backend framework.
 
 ```python
 from pathlib import Path
-from roboz import stop
+from roboz.tools import stop
 from roboz.deployment import DeployableAgent, Capability
 from roboz.llm import MockLLMEndpoint
 from roboshed.capabilities import FileCommands, FileEditing
@@ -81,7 +81,7 @@ migrated. The description below records the recipe behavior to preserve.
 `roboshed.deployments.robosprawl.robosprawl` is the concrete lazy persistent
 orchestrator and Librarian recipe. Call it with an already-scoped sandbox,
 `endpoint_getter`, `memory_endpoint`, `additional_capabilities`, `specialists`,
-`interaction_mode`, and optional `event_sinks`. It returns a fresh root and
+and optional `event_sinks`. It returns a fresh root and
 background-agent tuple.
 
 The recipe loads project memory and supplies project locations through initial
@@ -168,10 +168,12 @@ agent configuration. Each build creates fresh runtime state; applications can
 supply an agent-specific sink factory for persistence.
 
 The Librarian constructor declares its standard maintenance sequence:
-snapshots, consolidation, retention, then cadence. Pass its sandbox and the
-recursive foreground names directly to the constructor before attaching it as
-a background agent. The orchestrator also takes the configured sandbox and
-captures its permission policy when constructed.
+snapshots, consolidation, retention, an idle check, then cadence. The first idle
+observation schedules one complete final sweep without sleeping; the second idle
+observation stops the Librarian. Pass its sandbox and the recursive foreground
+names directly to the constructor before attaching it as a background agent. The
+orchestrator also takes the configured sandbox and captures its permission policy
+when constructed.
 
 Invoke the returned agent directly and retain the background agents for control.
 Repeated builds create fresh runtimes and bindings, but supplied endpoints,

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/README.md

@@ -9,7 +9,7 @@ install any model SDK, Proton, document SDK, web service, or backend framework.
 
 ```python
 from pathlib import Path
-from roboz import stop
+from roboz.tools import stop
 from roboz.deployment import DeployableAgent, Capability
 from roboz.llm import MockLLMEndpoint
 from roboshed.capabilities import FileCommands, FileEditing
@@ -65,7 +65,7 @@ migrated. The description below records the recipe behavior to preserve.
 `roboshed.deployments.robosprawl.robosprawl` is the concrete lazy persistent
 orchestrator and Librarian recipe. Call it with an already-scoped sandbox,
 `endpoint_getter`, `memory_endpoint`, `additional_capabilities`, `specialists`,
-`interaction_mode`, and optional `event_sinks`. It returns a fresh root and
+and optional `event_sinks`. It returns a fresh root and
 background-agent tuple.
 
 The recipe loads project memory and supplies project locations through initial
@@ -152,10 +152,12 @@ agent configuration. Each build creates fresh runtime state; applications can
 supply an agent-specific sink factory for persistence.
 
 The Librarian constructor declares its standard maintenance sequence:
-snapshots, consolidation, retention, then cadence. Pass its sandbox and the
-recursive foreground names directly to the constructor before attaching it as
-a background agent. The orchestrator also takes the configured sandbox and
-captures its permission policy when constructed.
+snapshots, consolidation, retention, an idle check, then cadence. The first idle
+observation schedules one complete final sweep without sleeping; the second idle
+observation stops the Librarian. Pass its sandbox and the recursive foreground
+names directly to the constructor before attaching it as a background agent. The
+orchestrator also takes the configured sandbox and captures its permission policy
+when constructed.
 
 Invoke the returned agent directly and retain the background agents for control.
 Repeated builds create fresh runtimes and bindings, but supplied endpoints,

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roboshed"
-version = "0.1.1.dev3"
+version = "0.1.1.dev4"
 description = "roboshed: optional building blocks for Roboz"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -9,7 +9,7 @@ license = "Apache-2.0"
 license-files = ["LICENSE"]
 import-names = ["roboshed"]
 classifiers = ["Development Status :: 2 - Pre-Alpha", "Typing :: Typed"]
-dependencies = ["roboz>=0.1.2.dev5,<0.2.0","pydantic>=2.12.4"]
+dependencies = ["roboz>=0.1.2.dev7,<0.2.0","pydantic>=2.12.4"]
 
 [build-system]
 requires = ["hatchling>=1.32"]

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/agents/librarian.py

@@ -13,6 +13,7 @@ from roboshed.identifiers import LIBRARIAN_AGENT_NAME
 from roboshed.sandbox import Sandbox
 from roboz.deployment import DeployableAgent
 from roboz.llm import EndpointLike
+from roboz.models import AgentMode
 
 LIBRARIAN_AGENT_DESCRIPTION: Final[str] = (
     "Runs deterministic maintenance cycles using the configured capabilities."
@@ -29,7 +30,7 @@ def librarian(
     agent = DeployableAgent(
         name=LIBRARIAN_AGENT_NAME,
         description=LIBRARIAN_AGENT_DESCRIPTION,
-        is_agentic=False,
+        mode=AgentMode.DETERMINISTIC,
         automatic_tool_prompt=False,
         default_capabilities=(
             ConversationSnapshots(),
@@ -39,7 +40,6 @@ def librarian(
         ),
     )
     agent.set_agent_endpoint(agent_endpoint)
-    agent.set_interaction_mode(None)
     agent.set_attributes(
         sandbox=sandbox,
         watched_agent_names=frozenset(watched_agent_names),

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/agents/orchestrator.py

@@ -7,7 +7,6 @@ from roboshed.capabilities import FileCommands, FileEditing
 from roboshed.sandbox import Sandbox
 from roboz.deployment import Capability, DeployableAgent
 from roboz.llm import EndpointLike
-from roboz.runtime import Output
 from roboz.tools import stop
 
 ORCHESTRATOR_PROMPT = """You are the user's persistent collaborator. Help them reach their
@@ -26,7 +25,6 @@ def orchestrator(
     agent_endpoint: EndpointLike,
     subagents: Sequence[DeployableAgent] = (),
     background_agents: Sequence[DeployableAgent] = (),
-    interaction_mode: Output | None = Output.CLI,
     initial_messages: Sequence[Path | str] = (),
 ) -> DeployableAgent:
     """Configure the orchestrator for an already-configured sandbox."""
@@ -43,7 +41,6 @@ def orchestrator(
         background_agents=tuple(background_agents),
     )
     agent.set_agent_endpoint(agent_endpoint)
-    agent.set_interaction_mode(interaction_mode)
     agent.set_initial_messages(initial_messages)
     agent.set_attributes(permissions=sandbox.permissions())
     return agent

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/capabilities.py

@@ -12,6 +12,7 @@ from roboshed.identifiers import (
     PURGE_SNAPSHOTS_TOOL_NAME,
     SLEEP_BETWEEN_RUNS_TOOL_NAME,
     SNAPSHOT_CONVERSATIONS_TOOL_NAME,
+    STOP_WHEN_WATCHED_AGENTS_INACTIVE_TOOL_NAME,
 )
 from roboshed.skills import cli_skill, file_editing
 from roboshed.tools import (
@@ -30,9 +31,13 @@ from roboshed.tools.contexts import (
     PurgeFilesContext,
     SleepBetweenRunsContext,
     SnapshotConversationsContext,
+    StopWhenWatchedAgentsInactiveContext,
 )
 from roboshed.tools.purge_files import purge_files
 from roboshed.tools.sleep_between_runs import sleep_between_runs
+from roboshed.tools.stop_when_watched_agents_inactive import (
+    stop_when_watched_agents_inactive,
+)
 from roboshed.tools.snapshot_conversations import snapshot_conversations
 from roboshed.sandbox import PermissionPolicy, Sandbox
 from roboz.deployment import (
@@ -326,11 +331,17 @@ class MaintenanceCadence(AgentCapability):
         }
 
     def build(self, agent: DeployableAgent, pipe: EventPipe) -> Capability:
-        """Bind cadence and idle stopping to this agent's cancellation state."""
+        """Bind cadence and inactive-agent stopping to cancellation state."""
         sandbox = cast(Sandbox, agent.sandbox)
         watched_agent_names = cast(Collection[str], agent.watched_agent_names)
         return Capability(
             default_tools=(
+                stop_when_watched_agents_inactive(
+                    StopWhenWatchedAgentsInactiveContext(
+                        conversation_root=sandbox.project_logs_dir(),
+                        agent_names=set(watched_agent_names),
+                    )
+                ).copy(name=STOP_WHEN_WATCHED_AGENTS_INACTIVE_TOOL_NAME),
                 sleep_between_runs(
                     SleepBetweenRunsContext(
                         seconds=self.seconds,

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/deployments/robosprawl.py

@@ -8,7 +8,7 @@ from roboshed.sandbox import Sandbox
 from roboz.agent import Agent
 from roboz.deployment import AgentCapability, DeployableAgent
 from roboz.llm import EndpointLike, LLMEndpoint, LLMEndpointRoute
-from roboz.runtime import EventSink, Output, default_event_sinks
+from roboz.runtime import EventSink, default_event_sinks
 
 
 def robosprawl(
@@ -19,7 +19,6 @@ def robosprawl(
     memory_endpoint: EndpointLike,
     additional_capabilities: Sequence[AgentCapability],
     specialists: Sequence[DeployableAgent],
-    interaction_mode: Output | None,
     event_sinks: Sequence[EventSink] = (),
 ) -> tuple[Agent, tuple[Agent, ...]]:
     """Build a fresh fixed orchestrator and Librarian for a scoped project.
@@ -39,7 +38,6 @@ def robosprawl(
         sandbox,
         agent_endpoint=LLMEndpointRoute(endpoint_getter),
         subagents=tuple(specialists),
-        interaction_mode=interaction_mode,
     )
     root.add_capabilities(*additional_capabilities)
     watched_agent_names = root.agent_names(include_background=False)

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/identifiers.py

@@ -23,5 +23,8 @@ PURGE_FILES_TOOL_NAME: Final[str] = "purge_files"
 PURGE_LOGS_TOOL_NAME: Final[str] = "purge_logs"
 PURGE_SNAPSHOTS_TOOL_NAME: Final[str] = "purge_snapshots"
 PURGE_MEMORY_TOOL_NAME: Final[str] = "purge_memory"
+STOP_WHEN_WATCHED_AGENTS_INACTIVE_TOOL_NAME: Final[str] = (
+    "stop_when_watched_agents_inactive"
+)
 SLEEP_BETWEEN_RUNS_TOOL_NAME: Final[str] = "sleep_between_runs"
 LIBRARIAN_AGENT_NAME: Final[str] = "librarian"

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/skills/robosprawl.py

@@ -56,8 +56,10 @@ project directory. Use the supplied paths instead of guessing folder names.
 
 The Librarian is a deterministic background pipeline. It snapshots conversations,
 consolidates memory, applies retention limits, and waits between maintenance cycles.
-The root starts it through its background-start tool; the host owns cancellation
-and shutdown. Maintenance is asynchronous, so a new conversation may not yet have
+After watched work becomes idle, it performs one complete final sweep without
+sleeping and stops only after confirming that the project remains idle. The root
+starts it through its background-start tool; the host owns cancellation and
+shutdown. Maintenance is asynchronous, so a new conversation may not yet have
 appeared in memory. Conversation logs are written by the runtime.
 
 Do not duplicate that maintenance by writing your own session summaries or memory

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/tools/__init__.py

@@ -12,6 +12,7 @@ from .contexts import (
     PurgeFilesContext,
     SleepBetweenRunsContext,
     SnapshotConversationsContext,
+    StopWhenWatchedAgentsInactiveContext,
 )
 from .runner import ExecutableCommandCatalog
 from .cli_commands.run_file_command import get_run_file_command
@@ -19,6 +20,7 @@ from .compactification import get_compactify_messages_when_needed_tool
 from .consolidate_memory import consolidate_memory
 from .purge_files import purge_files, purge_files_by_threshold
 from .sleep_between_runs import sleep_between_runs
+from .stop_when_watched_agents_inactive import stop_when_watched_agents_inactive
 from .snapshot_conversations import (
     SnapshotMode,
     snapshot_conversations,
@@ -36,6 +38,7 @@ __all__ = [
     "SnapshotConversationsContext",
     "PurgeFilesContext",
     "SleepBetweenRunsContext",
+    "StopWhenWatchedAgentsInactiveContext",
     "SnapshotMode",
     "consolidate_memory",
     "get_apply_patch",
@@ -44,5 +47,6 @@ __all__ = [
     "purge_files",
     "purge_files_by_threshold",
     "sleep_between_runs",
+    "stop_when_watched_agents_inactive",
     "snapshot_conversations",
 ]

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/tools/contexts.py

@@ -137,9 +137,17 @@ class PurgeFilesContext:
     prune_empty_directories: bool = False
 
 
+@dataclass(frozen=True, kw_only=True)
+class StopWhenWatchedAgentsInactiveContext:
+    """Watched conversations used to decide when maintenance may stop."""
+
+    conversation_root: Path
+    agent_names: set[str]
+
+
 @dataclass(frozen=True, kw_only=True)
 class SleepBetweenRunsContext:
-    """Wait duration, cancellation callback, and watched conversations."""
+    """Wait settings for observing activity between maintenance cycles."""
 
     seconds: float
     is_cancelled: Callable[[], bool] | None = None

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/tools/memory_files.py

@@ -1,8 +1,11 @@
 """Filesystem helpers shared by snapshot and consolidation tools."""
 
-from datetime import UTC, datetime
+import os
+from datetime import UTC, datetime, timedelta
+from itertools import count
 from pathlib import Path
 from typing import Final
+from uuid import uuid4
 
 from pydantic import ValidationError
 
@@ -67,15 +70,37 @@ def write_timestamped_file(
     replace: Path | None,
     pipe: EventPipe | None = None,
 ) -> Path:
-    """Write a new timestamp-named artifact, then optionally delete ``replace``."""
-    path = folder / f"{utc_now().strftime(TIMESTAMP_STEM_FORMAT)}{suffix}"
-    path.parent.mkdir(parents=True, exist_ok=True)
-    if pipe is not None:
-        pipe.raise_if_cancelled()
-    path.write_text(body, encoding=UTF8_ENCODING)
+    """Atomically publish a complete timestamped artifact, then remove ``replace``."""
+    folder.mkdir(parents=True, exist_ok=True)
+    temporary_path = folder / f".librarian-{uuid4().hex}.tmp"
+    published_path: Path | None = None
+    try:
+        with temporary_path.open("x", encoding=UTF8_ENCODING) as temporary:
+            temporary.write(body)
+            temporary.flush()
+            os.fsync(temporary.fileno())
+
+        if pipe is not None:
+            pipe.raise_if_cancelled()
+
+        base_time = utc_now()
+        for offset in count():
+            stamp = base_time + timedelta(microseconds=offset)
+            path = folder / f"{stamp.strftime(TIMESTAMP_STEM_FORMAT)}{suffix}"
+            try:
+                os.link(temporary_path, path)
+            except FileExistsError:
+                continue
+            published_path = path
+            break
+    finally:
+        temporary_path.unlink(missing_ok=True)
+
+    if published_path is None:
+        raise RuntimeError("timestamp candidate generation exhausted")
     if replace is not None:
         replace.unlink(missing_ok=True)
-    return path
+    return published_path
 
 
 __all__ = [

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/tools/sleep_between_runs.py

@@ -1,23 +1,18 @@
 """Cancellable wait between deterministic Librarian maintenance cycles."""
 
 from collections.abc import Callable
-from pathlib import Path
 from time import sleep
 from typing import Final
 
 from roboshed.identifiers import SLEEP_BETWEEN_RUNS_TOOL_NAME
+from roboshed.tools.contexts import SleepBetweenRunsContext
 from roboz.exceptions import ExternalCallCancelledError
-from roboz.models import NO_MESSAGE, All, Message, Stop, Str
+from roboz.models import NO_MESSAGE, All, Message, Str
 from roboz.runtime.persistence import active_marker_paths
-from roboshed.tools.contexts import SleepBetweenRunsContext
 from roboz.tooling.decorators import factory
 
 SLEEP_POLL_SECONDS: Final[float] = 1.0
 
-_PROJECT_IDLE_STATUS: Final[str] = "project idle"
-_ACTIVE_RUN_ENDED_STATUS: Final[str] = "active run ended"
-_MIN_SLEEP_SECONDS: Final[float] = 0.0
-
 
 def _raise_if_cancelled(is_cancelled: Callable[[], bool] | None) -> None:
     if is_cancelled is not None and is_cancelled():
@@ -27,19 +22,27 @@ def _raise_if_cancelled(is_cancelled: Callable[[], bool] | None) -> None:
 @factory
 def sleep_between_runs(
     input: All, messages: list[Message], ctx: SleepBetweenRunsContext
-) -> Str | Stop:
-    """Wait for the next cycle, or stop once the watched project becomes idle."""
+) -> Str:
+    """Wait between maintenance cycles, waking promptly when a watched run ends.
+
+    Return immediately when the watched agents are inactive. This tool never
+    decides whether maintenance is complete; use ``stop_when_watched_agents_inactive`` for that.
+    """
     del input, messages
-    seconds = max(_MIN_SLEEP_SECONDS, float(ctx.seconds))
     _raise_if_cancelled(ctx.is_cancelled)
-
-    active_markers: tuple[Path, ...] = ()
-    if ctx.conversation_root is not None:
-        active_markers = active_marker_paths(ctx.conversation_root, ctx.agent_names)
-        if not active_markers:
-            return Stop(value=f"{SLEEP_BETWEEN_RUNS_TOOL_NAME}: {_PROJECT_IDLE_STATUS}")
-
-    slept = _MIN_SLEEP_SECONDS
+    active_markers = (
+        active_marker_paths(ctx.conversation_root, ctx.agent_names)
+        if ctx.conversation_root is not None
+        else ()
+    )
+    if ctx.conversation_root is not None and not active_markers:
+        return Str(
+            value=f"{SLEEP_BETWEEN_RUNS_TOOL_NAME}: watched agents inactive",
+            truncation=NO_MESSAGE,
+        )
+
+    seconds = max(0.0, float(ctx.seconds))
+    slept = 0.0
     while slept < seconds:
         _raise_if_cancelled(ctx.is_cancelled)
         chunk = min(SLEEP_POLL_SECONDS, seconds - slept)
@@ -48,7 +51,7 @@ def sleep_between_runs(
         _raise_if_cancelled(ctx.is_cancelled)
         if any(not marker.exists() for marker in active_markers):
             return Str(
-                value=(f"{SLEEP_BETWEEN_RUNS_TOOL_NAME}: {_ACTIVE_RUN_ENDED_STATUS}"),
+                value=f"{SLEEP_BETWEEN_RUNS_TOOL_NAME}: active run ended",
                 truncation=NO_MESSAGE,
             )
     return Str(

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/tools/snapshot_conversation_example.py

@@ -3,7 +3,7 @@
 from typing import Final
 
 SNAPSHOT_CONVERSATION_EXAMPLE: Final[str] = """## Goals and intent
-- User wants a non-agentic Librarian that runs in the background and maintains conversation memory without user involvement.
+- User wants a deterministic Librarian that runs in the background and maintains conversation memory without user involvement.
 - User stated the snapshots exist to feed a later consolidation step, "the initial raw phase of information gathering".
 
 ## State of work

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/tools/snapshot_conversations.py

@@ -3,6 +3,7 @@
 import logging
 from datetime import datetime
 from enum import StrEnum
+from pathlib import Path
 from typing import Final
 
 from roboshed.identifiers import SNAPSHOT_CONVERSATIONS_TOOL_NAME
@@ -47,8 +48,6 @@ TERMINAL_SYNCABLE_STATUSES: Final[frozenset[RunStatus]] = frozenset(
     {RunStatus.COMPLETED, RunStatus.FAILED}
 )
 
-_ISO_Z_SUFFIX: Final[str] = "Z"
-_ISO_UTC_OFFSET: Final[str] = "+00:00"
 _NOT_ENDED: Final[str] = "not ended"
 _UNKNOWN_TIME: Final[str] = "unknown"
 _SOURCE_AGENT_KEY: Final[str] = "source_agent"
@@ -69,29 +68,28 @@ class SnapshotMode(StrEnum):
 
 def _uncovered_rows(
     rows: list[LoggedMessageRow],
-    latest_snapshot_time: datetime | None,
     snapshot_document: SnapshotDocument | None,
 ) -> list[LoggedMessageRow]:
-    """Return rows beyond the stored cursor, with timestamp fallback for legacy files."""
+    """Return rows beyond valid stored coverage, reprocessing legacy artifacts."""
     if snapshot_document is not None and snapshot_document.coverage_marker_present:
         covered_sequence = snapshot_document.covered_through_sequence
         if covered_sequence is None:
             return rows
         return [row for row in rows if row.sequence > covered_sequence]
-    if latest_snapshot_time is None:
-        return rows
-    for index, row in enumerate(rows):
-        try:
-            created_at = datetime.fromisoformat(
-                row.created_at.replace(_ISO_Z_SUFFIX, _ISO_UTC_OFFSET)
-            )
-        except ValueError:
-            return rows[index:]
-        if created_at.tzinfo is None:
-            return rows[index:]
-        if created_at > latest_snapshot_time:
-            return rows[index:]
-    return []
+    return rows
+
+
+def _persisted_snapshot_covers(path: Path, *, sequence: int) -> bool:
+    """Return whether a competing snapshot has valid sufficient coverage."""
+    try:
+        document = parse_snapshot_document(path.read_text(encoding=UTF8_ENCODING))
+    except OSError:
+        return False
+    return (
+        document.coverage_marker_present
+        and document.covered_through_sequence is not None
+        and document.covered_through_sequence >= sequence
+    )
 
 
 def _normalize_temporal_messages(
@@ -191,9 +189,7 @@ def _snapshot_one_run(
         if snapshot_location is not None
         else None
     )
-    uncovered_rows = _uncovered_rows(
-        list(run.messages), snapshot_time, snapshot_document
-    )
+    uncovered_rows = _uncovered_rows(list(run.messages), snapshot_document)
     if not uncovered_rows:
         return False
     covered_through_sequence = max(row.sequence for row in uncovered_rows)
@@ -235,9 +231,13 @@ def _snapshot_one_run(
     if ctx.pipe is not None:
         ctx.pipe.raise_if_cancelled()
 
-    current_time, _ = latest_timestamped_file(snapshot_folder, suffix=MARKDOWN_SUFFIX)
+    current_time, current_location = latest_timestamped_file(
+        snapshot_folder, suffix=MARKDOWN_SUFFIX
+    )
     if current_time is not None and (
         snapshot_time is None or current_time > snapshot_time
+    ) and current_location is not None and _persisted_snapshot_covers(
+        current_location, sequence=covered_through_sequence
     ):
         return False
 

roboshed-0.1.1.dev4/src/roboshed/tools/stop_when_watched_agents_inactive.py

@@ -0,0 +1,50 @@
+"""Require a final maintenance sweep after watched agents become inactive."""
+
+import json
+
+from roboshed.identifiers import STOP_WHEN_WATCHED_AGENTS_INACTIVE_TOOL_NAME
+from roboshed.tools.contexts import StopWhenWatchedAgentsInactiveContext
+from roboz.models import NO_MESSAGE, All, Message, Stop, Str, filter_messages
+from roboz.runtime.persistence import active_marker_paths
+from roboz.tooling.decorators import factory
+
+_FINAL_SWEEP_REQUIRED = (
+    f"{STOP_WHEN_WATCHED_AGENTS_INACTIVE_TOOL_NAME}: final sweep required"
+)
+
+
+@factory
+def stop_when_watched_agents_inactive(
+    input: All, messages: list[Message], ctx: StopWhenWatchedAgentsInactiveContext
+) -> Str | Stop:
+    """Stop only after watched agents remain inactive for a full final sweep."""
+    del input
+    if active_marker_paths(ctx.conversation_root, ctx.agent_names):
+        return Str(
+            value=f"{STOP_WHEN_WATCHED_AGENTS_INACTIVE_TOOL_NAME}: watched agents active",
+            truncation=NO_MESSAGE,
+        )
+
+    previous_checks = filter_messages(
+        messages, caller=STOP_WHEN_WATCHED_AGENTS_INACTIVE_TOOL_NAME
+    )
+    last_result = (
+        json.loads(previous_checks[-1].content).get("value")
+        if previous_checks
+        else None
+    )
+    if last_result == _FINAL_SWEEP_REQUIRED:
+        # A complete maintenance sweep has run since the previous inactive check.
+        return Stop(
+            value=f"{STOP_WHEN_WATCHED_AGENTS_INACTIVE_TOOL_NAME}: watched agents inactive"
+        )
+
+    # The preceding sweep may have missed a run's final output. Now that the
+    # watched agents are inactive, require another sweep before allowing shutdown.
+    return Str(
+        value=_FINAL_SWEEP_REQUIRED,
+        truncation=NO_MESSAGE,
+    )
+
+
+__all__ = ["StopWhenWatchedAgentsInactiveContext", "stop_when_watched_agents_inactive"]

{roboshed-0.1.1.dev3 → roboshed-0.1.1.dev4}/src/roboshed/tools/types.py

@@ -10,7 +10,7 @@ from roboshed.models import (
     TInput,
     TPayload,
 )
-from roboz import Empty
+from roboz.models import Empty
 
 if TYPE_CHECKING:
     pass