Generalize readonly stores for zero-footprint query commands

Add readonly=True pattern to MemoryCatalog, SkillCandidateStore, and
AutomationStore to prevent query commands from creating .teaagent
directories in fresh workspaces.

Store layer:
- Add readonly parameter to MemoryCatalog, SkillCandidateStore, AutomationStore
- Skip directory creation when readonly=True
- Add RuntimeError guards in mutating methods when readonly=True

CLI handlers:
- memory list/search/show use MemoryCatalog(readonly=True)
- skill candidate list/show use SkillCandidateStore(readonly=True)
- automation list/show use AutomationStore(readonly=True)
- Add JSON error boundary for memory show missing

Preflight chain (critical for status):
- build_daily_brief: Add readonly parameter, propagate to RunStore and preflight
- build_automation_status: Use AutomationStore(readonly=True) and BackgroundRunStore(readonly=True)
- preflight: Add readonly parameter, propagate to MemoryCatalog and build_context_pack
- build_context_pack: Use MemoryCatalog(readonly=True)
- check_env_health: Skip write health checks in readonly mode
- status_short: Pass readonly=True to build_daily_brief

Ergonomics:
- run_history: Use RunStore(readonly=True) for yesterday/recall
- automation_observability: Use AutomationStore(readonly=True) for blocked_reason

Tests:
- Add table-driven test distinguishing zero-footprint queries from mutating initializers
- Add status short and automation status to zero-footprint test table
- Add assertions for mutating initializer half
- Fix ruff issues (contextlib.suppress, import ordering)

This ensures high-frequency commands like status and yesterday/recall are
truly zero-footprint for fresh workspaces, suitable for shell prompts,
HUDs, and automated watchers.

Constraint: Must maintain backward compatibility; readonly defaults to False for all stores. Query commands must not create .teaagent in fresh workspaces. Mutating commands must continue to initialize state normally.

Tested: 22 tests in test_cli_ergonomics_handlers.py pass including new table-driven test. Fresh-root CLI black-box verification confirms status, agent automation status, yesterday/recall, memory/skill/automation list/show are zero-footprint. Ruff check passes.

Confidence: high

Author: johnteee

teaagent/automation_observability.py

@@ -98,7 +98,7 @@ def automation_blocked_gate_reason(
     ticket = validate_automation_spec(spec, root=str(root))
     if ticket.errors:
         return '; '.join(ticket.errors[:2])
-    store = AutomationStore(root)
+    store = AutomationStore(root, readonly=True)
     with contextlib.suppress(FileNotFoundError):
         store.show_quarantined(spec.automation_id)
         return 'automation is quarantined; promote after review'

teaagent/automations.py

@@ -159,12 +159,14 @@ def compute_next_run_at(schedule: str, *, now: Optional[datetime] = None) -> str
 
 
 class AutomationStore:
-    def __init__(self, root: str | Path = '.') -> None:
+    def __init__(self, root: str | Path = '.', *, readonly: bool = False) -> None:
         self.root = Path(root).resolve()
         self.dir = self.root / '.teaagent' / 'automations'
         self.quarantine_dir = self.root / '.teaagent' / 'automations-quarantine'
-        self.dir.mkdir(parents=True, exist_ok=True)
-        self.quarantine_dir.mkdir(parents=True, exist_ok=True)
+        self.readonly = readonly
+        if not readonly:
+            self.dir.mkdir(parents=True, exist_ok=True)
+            self.quarantine_dir.mkdir(parents=True, exist_ok=True)
 
     def _spec_path(self, automation_id: str) -> Path:
         return self.dir / f'{automation_id}.json'
@@ -282,6 +284,8 @@ def create(
         context_from: str = '',
         provenance_digest: str = '',
     ) -> AutomationSpec:
+        if self.readonly:
+            raise RuntimeError('Cannot create automation in readonly mode')
         spec = self.draft(
             name=name,
             task=task,
@@ -337,6 +341,8 @@ def create_quarantined(
         *,
         provenance: dict[str, Any],
     ) -> AutomationSpec:
+        if self.readonly:
+            raise RuntimeError('Cannot create quarantined automation in readonly mode')
         payload = {
             **spec.to_dict(),
             'enabled': False,
@@ -378,6 +384,8 @@ def promote_quarantined(
         *,
         attested: bool = False,
     ) -> AutomationSpec:
+        if self.readonly:
+            raise RuntimeError('Cannot promote quarantined automation in readonly mode')
         payload = dict(self.show_quarantined(automation_id))
         provenance = payload.pop('provenance', None)
         payload.pop('quarantine', None)
@@ -426,6 +434,8 @@ def promote_quarantined(
         return promoted
 
     def delete(self, automation_id: str) -> None:
+        if self.readonly:
+            raise RuntimeError('Cannot delete automation in readonly mode')
         path = self._spec_path(automation_id)
         quarantine_path = self._quarantine_path(automation_id)
         if path.exists():
@@ -437,13 +447,17 @@ def delete(self, automation_id: str) -> None:
         raise FileNotFoundError(f"automation '{automation_id}' not found")
 
     def update(self, spec: AutomationSpec) -> AutomationSpec:
+        if self.readonly:
+            raise RuntimeError('Cannot update automation in readonly mode')
         updated = AutomationSpec(**{**spec.to_dict(), 'updated_at': iso_utc(utc_now())})
         atomic_write_text(
             self._spec_path(spec.automation_id), json.dumps(updated.to_dict())
         )
         return updated
 
     def set_enabled(self, automation_id: str, enabled: bool) -> AutomationSpec:
+        if self.readonly:
+            raise RuntimeError('Cannot set enabled in readonly mode')
         spec = self.show(automation_id)
         next_run_at = spec.next_run_at
         if enabled and not next_run_at:
@@ -472,13 +486,14 @@ def build_automation_status(
     root: str | Path,
     *,
     store: Optional[AutomationStore] = None,
+    readonly: bool = True,
 ) -> dict[str, Any]:
     """Summarize automation health for CLI status output."""
     from teaagent.automation_observability import enrich_automation_status_row
     from teaagent.ergonomics.background_run import BackgroundRunStore
 
-    automation_store = store or AutomationStore(root)
-    bg_store = BackgroundRunStore(root)
+    automation_store = store or AutomationStore(root, readonly=readonly)
+    bg_store = BackgroundRunStore(root, readonly=readonly)
     rows: list[dict[str, Any]] = []
     for spec in automation_store.list():
         log_tail = ''

teaagent/cli/_handlers/_agent.py

@@ -960,7 +960,7 @@ def automation_add_command(args: argparse.Namespace) -> int:
 
 
 def automation_list_command(args: argparse.Namespace) -> int:
-    store = AutomationStore(args.root)
+    store = AutomationStore(args.root, readonly=True)
     if getattr(args, 'quarantined', False):
         print_json(store.list_quarantined())
         return 0
@@ -985,7 +985,7 @@ def automation_promote_command(args: argparse.Namespace) -> int:
 
 def automation_show_command(args: argparse.Namespace) -> int:
     try:
-        spec = AutomationStore(args.root).show(args.automation_id)
+        spec = AutomationStore(args.root, readonly=True).show(args.automation_id)
     except FileNotFoundError as exc:
         print_json({'status': 'error', 'message': str(exc)})
         return 1

teaagent/cli/_handlers/_memory.py

@@ -42,7 +42,7 @@ def memory_add_command(args: argparse.Namespace) -> int:
 
 def memory_list_command(args: argparse.Namespace) -> int:
     print_json(
-        [entry.to_dict() for entry in MemoryCatalog(args.root).list(limit=args.limit)]
+        [entry.to_dict() for entry in MemoryCatalog(args.root, readonly=True).list(limit=args.limit)]
     )
     return 0
 
@@ -51,15 +51,19 @@ def memory_search_command(args: argparse.Namespace) -> int:
     print_json(
         [
             entry.to_dict()
-            for entry in MemoryCatalog(args.root).search(args.query, limit=args.limit)
+            for entry in MemoryCatalog(args.root, readonly=True).search(args.query, limit=args.limit)
         ]
     )
     return 0
 
 
 def memory_show_command(args: argparse.Namespace) -> int:
-    print_json(MemoryCatalog(args.root).show(args.memory_id).to_dict())
-    return 0
+    try:
+        print_json(MemoryCatalog(args.root, readonly=True).show(args.memory_id).to_dict())
+        return 0
+    except FileNotFoundError as exc:
+        print_json({'status': 'error', 'message': str(exc)})
+        return 1
 
 
 def print_json(value: Any) -> None:

teaagent/cli/_handlers/_skill.py

@@ -81,13 +81,13 @@ def skill_candidate_eval_command(args: argparse.Namespace) -> int:
 
 
 def skill_candidate_list_command(args: argparse.Namespace) -> int:
-    rows = [row.to_dict() for row in SkillCandidateStore(args.root).list()]
+    rows = [row.to_dict() for row in SkillCandidateStore(args.root, readonly=True).list()]
     _print_json(rows)
     return 0
 
 
 def skill_candidate_show_command(args: argparse.Namespace) -> int:
-    store = SkillCandidateStore(args.root)
+    store = SkillCandidateStore(args.root, readonly=True)
     try:
         row = store.show(args.candidate_id)
     except FileNotFoundError as exc:

teaagent/context_pack.py

@@ -427,6 +427,7 @@ def build_context_pack(
     hydrate_lsp: bool = False,
     search_graph: bool = True,
     code_analysis_config: Optional[CodeAnalysisConfig] = None,
+    readonly: bool = False,
 ) -> ContextPack:
     root_path = Path(root).resolve()
     texts = [task]
@@ -440,7 +441,7 @@ def build_context_pack(
     ]
     memories = [
         entry.to_dict()
-        for entry in MemoryCatalog(root_path).search(task, limit=memory_limit)
+        for entry in MemoryCatalog(root_path, readonly=readonly).search(task, limit=memory_limit)
     ]
     graph_rag = _graph_rag_evidence(
         root_path, task, search_graph=search_graph, hit_limit=graph_hit_limit

teaagent/daily.py

@@ -295,6 +295,7 @@ def build_daily_brief(
     memory_limit: Optional[int] = None,
     runs_limit: int = 5,
     context_profile: str = 'balanced',
+    readonly: bool = False,
 ) -> DailyBrief:
     from teaagent.preflight import preflight
 
@@ -309,8 +310,9 @@ def build_daily_brief(
         route=route,
         memory_limit=profile.memory_limit,
         context_profile=profile.name,
+        readonly=readonly,
     )
-    store = RunStore(root)
+    store = RunStore(root, readonly=readonly)
     recent_runs = _recent_run_rollups(store, runs_limit)
     token_budget = build_token_budget_report(
         task=effective_task,

teaagent/ergonomics/run_history.py

@@ -16,7 +16,7 @@ def _parse_day(value: str) -> date | None:
 
 def list_yesterday_runs(root: str | Path, *, limit: int = 20) -> list[dict[str, Any]]:
     target = date.today() - timedelta(days=1)
-    store = RunStore(root)
+    store = RunStore(root, readonly=True)
     results: list[dict[str, Any]] = []
     for summary in store.list_runs(limit=200):
         day = _parse_day(summary.created_at)
@@ -28,7 +28,7 @@ def list_yesterday_runs(root: str | Path, *, limit: int = 20) -> list[dict[str,
 
 
 def list_recall_runs(root: str | Path, *, limit: int = 5) -> list[dict[str, Any]]:
-    store = RunStore(root)
+    store = RunStore(root, readonly=True)
     return [_enrich_summary(store, summary) for summary in store.list_runs(limit=limit)]
 
 

teaagent/ergonomics/status_short.py

@@ -24,6 +24,7 @@ def build_status_short(
         permission_mode=permission_mode,
         context_profile='lean',
         runs_limit=3,
+        readonly=True,
     )
     level = brief.token_budget.usage_level
     colour = {'green': 'G', 'yellow': 'Y', 'red': 'R'}.get(level, '?')
@@ -36,7 +37,7 @@ def build_status_short(
                 break
         if not active:
             active = brief.recent_runs[0].run_id
-    store = RunStore(root)
+    store = RunStore(root, readonly=True)
     status = 'idle'
     if active:
         try:

teaagent/memory.py

@@ -34,13 +34,17 @@ def to_dict(self) -> dict[str, Any]:
 
 
 class MemoryCatalog:
-    def __init__(self, root: str | Path = '.') -> None:
+    def __init__(self, root: str | Path = '.', *, readonly: bool = False) -> None:
         self.root = Path(root).resolve()
         self.path = self.root / '.teaagent' / 'memory.jsonl'
         self.quarantine_path = self.root / '.teaagent' / 'memory-quarantine.jsonl'
-        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.readonly = readonly
+        if not readonly:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
 
     def add(self, content: str, *, tags: tuple[str, ...] = ()) -> MemoryEntry:
+        if self.readonly:
+            raise RuntimeError('Cannot add memory in readonly mode')
         entry = MemoryEntry(
             memory_id=uuid4().hex, content=content.strip(), tags=normalize_tags(tags)
         )
@@ -56,6 +60,8 @@ def add_quarantined(
         tags: tuple[str, ...] = (),
         provenance: dict[str, Any],
     ) -> MemoryEntry:
+        if self.readonly:
+            raise RuntimeError('Cannot add quarantined memory in readonly mode')
         entry = MemoryEntry(
             memory_id=uuid4().hex, content=content.strip(), tags=normalize_tags(tags)
         )