apsimo 1.3.0__py3-none-any.whl

apsimo/turns/hermes_history.py

@@ -0,0 +1,245 @@
+"""Import reviewed Hermes DM source quotations without replaying turn effects.
+
+Run with --dry-run first. Input must be a stable SQLite backup, not a live WAL
+database. No Hermes runtime, model client, network fetch or ordinary turn API is
+invoked. Unmapped history remains in its original database.
+"""
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+from contextlib import closing
+from datetime import datetime, timezone
+import hashlib
+import json
+import math
+from pathlib import Path
+import re
+import sqlite3
+
+from .idempotency import TurnIdempotencyLedger, SourceErased, canonical_turn_digest
+
+AUTOMATION = {'cron', 'subagent', 'webhook', 'api_server', 'api', 'cli', 'tool', 'system'}
+OPTIONAL_MESSAGE = {'active': '1', 'compacted': '0', '_compressed_summary': '0',
+    'observed': '0', 'tool_calls': 'NULL', 'finish_reason': 'NULL',
+    'effect_disposition': 'NULL', 'display_kind': 'NULL', 'platform_message_id': 'NULL'}
+
+
+def mapping_document(path):
+    return validate_mapping(json.loads(Path(path).read_text()))
+
+
+def validate_mapping(value):
+    if not isinstance(value, dict) or value.get('version') != 1 or not isinstance(value.get('namespace'), str) or not re.fullmatch(r'[a-zA-Z0-9_.-]{1,80}', value['namespace']):
+        raise ValueError('Expected a version 1 mapping with a stable database namespace')
+    bindings = value.get('bindings')
+    if not isinstance(bindings, list) or not bindings or len(bindings) > 500:
+        raise ValueError('Provide 1..500 explicitly reviewed session bindings')
+    seen = set()
+    for binding in bindings:
+        if not isinstance(binding, dict):
+            raise ValueError('Every binding must be an object')
+        for field in ('session_id', 'platform', 'actor_id', 'chat_id', 'contact_id'):
+            if not isinstance(binding.get(field), str) or not binding[field].strip():
+                raise ValueError('Every binding needs session, platform, actor, chat and contact IDs')
+        if binding['session_id'] in seen:
+            raise ValueError('A session cannot have multiple actor bindings')
+        seen.add(binding['session_id'])
+        if binding['platform'] in AUTOMATION or binding.get('chat_type') != 'dm':
+            raise ValueError('This importer accepts explicitly attributed direct messages only')
+        if not binding.get('review_evidence'):
+            raise ValueError('Every binding requires an independent review evidence reference')
+    return value
+
+
+def open_snapshot(path):
+    path = Path(path).resolve(strict=True)
+    wal = path.with_name(path.name + '-wal')
+    if wal.exists() and wal.stat().st_size:
+        raise ValueError('Use a consistent SQLite backup, not an active WAL database')
+    with path.open('rb') as stream:
+        digest = hashlib.file_digest(stream, 'sha256').hexdigest()
+    conn = sqlite3.connect(path.as_uri() + '?mode=ro', uri=True)
+    conn.row_factory = sqlite3.Row
+    conn.execute('PRAGMA query_only=ON')
+    conn.execute('BEGIN')
+    return conn, digest
+
+
+def validate_bindings(conn, mapping):
+    columns = {r['name'] for r in conn.execute('PRAGMA table_info(sessions)')}
+    required = {'id', 'source', 'user_id', 'chat_id', 'chat_type'}
+    if not required <= columns:
+        raise ValueError('Hermes session schema lacks required origin fields; do not infer missing identities')
+    messages = {r['name'] for r in conn.execute('PRAGMA table_info(messages)')}
+    if not {'id', 'session_id', 'role', 'content', 'timestamp'} <= messages:
+        raise ValueError('Unsupported Hermes message schema')
+    sessions = {}
+    for binding in mapping['bindings']:
+        row = conn.execute('SELECT * FROM sessions WHERE id=?', (binding['session_id'],)).fetchone()
+        if row is None:
+            raise ValueError('A reviewed session is missing from this snapshot')
+        row = dict(row)
+        for field, actual in (('platform', 'source'), ('actor_id', 'user_id'), ('chat_id', 'chat_id'), ('chat_type', 'chat_type')):
+            if row[actual] != binding[field]:
+                raise ValueError('A reviewed session no longer matches its exact transport binding')
+        origin = row.get('origin_json')
+        if origin:
+            try:
+                origin = json.loads(origin)
+            except (TypeError, ValueError):
+                raise ValueError('Invalid recorded session origin') from None
+            if not isinstance(origin, dict):
+                raise ValueError('Invalid recorded session origin')
+            for field, actual in (('platform', 'platform'), ('user_id', 'actor_id'), ('chat_id', 'chat_id'), ('chat_type', 'chat_type')):
+                if origin.get(field) and origin[field] != binding[actual]:
+                    raise ValueError('Session origin conflicts with the reviewed binding')
+        sessions[row['id']] = row
+    return sessions, messages
+
+
+def source_message(row, session, binding, namespace):
+    """Classify stored messages without treating their role as actor evidence."""
+    if row['role'] not in {'user', 'assistant'}:
+        return None, 'non_conversation_role'
+    if row['_compressed_summary']:
+        return None, 'generated_summary'
+    if not row['active'] and not row['compacted']:
+        return None, 'rewound_or_inactive'
+    if row['observed']:
+        return None, 'ambient_observation'
+    if row['effect_disposition'] or row['display_kind']:
+        return None, 'special_message_metadata'
+    if row['tool_calls'] not in (None, '', '[]') or row['finish_reason'] in {'tool_calls', 'function_call'}:
+        return None, 'tool_call_message'
+    content = row['content']
+    if not isinstance(content, str) or not content.strip():
+        return None, 'empty_or_unsupported_content'
+    # Hermes JSON-encodes multimodal block lists in this TEXT column. Retain
+    # exact text-only lists; leave attachment history in the original database
+    # rather than fetch URLs, flatten blocks, or schedule old vision jobs.
+    if content.lstrip().startswith('['):
+        try:
+            decoded = json.loads(content)
+        except ValueError:
+            decoded = None
+        if isinstance(decoded, list) and decoded and all(isinstance(b, dict) and 'type' in b for b in decoded):
+            if any(b['type'] not in {'text', 'input_text', 'output_text'} or not isinstance(b.get('text'), str) for b in decoded):
+                return None, 'historical_attachment_unretained'
+            content = decoded
+    timestamp = row['timestamp']
+    try:
+        occurred_at = datetime.fromtimestamp(float(timestamp), timezone.utc).isoformat() if math.isfinite(float(timestamp)) else None
+    except (ValueError, TypeError, OverflowError, OSError):
+        occurred_at = None
+    provenance = {'kind': 'hermes_history', 'database_namespace': namespace,
+        'message_id': row['id'], 'session_id': row['session_id'],
+        'platform': binding['platform'], 'actor_id': binding['actor_id'],
+        'chat_id': binding['chat_id'], 'actor_basis': 'reviewed_direct_session',
+        'speaker': 'contact' if row['role'] == 'user' else 'assistant',
+        'timestamp_basis': 'hermes_recorded_timestamp' if occurred_at else 'unknown',
+        'platform_message_id': row['platform_message_id'],
+        'session_model_hint': session.get('model'), 'message_model_revision': 'unknown',
+        'model_basis': 'session_hint_not_per_message_attribution',
+        'review_evidence': binding['review_evidence'], 'learning': 'source_only'}
+    return ({'role': row['role'], 'content': content, 'provenance': provenance}, occurred_at), None
+
+
+def _progress(ledger):
+    with closing(ledger._connect()) as conn, conn:
+        conn.execute('''CREATE TABLE IF NOT EXISTS source_import_progress (
+            run_id TEXT PRIMARY KEY, namespace TEXT NOT NULL, snapshot_sha256 TEXT NOT NULL,
+            mapping_sha256 TEXT NOT NULL, cursor INTEGER NOT NULL DEFAULT 0,
+            counts_json TEXT NOT NULL DEFAULT '{}')''')
+
+
+def import_history(database, mapping, *, state_dir=None, apply=False, limit=1000):
+    mapping = validate_mapping(mapping)
+    if not 1 <= limit <= 10000:
+        raise ValueError('Batch limit must be between 1 and 10000 messages')
+    if apply and (mapping.get('reviewed') is not True or state_dir is None):
+        raise ValueError('Apply requires a reviewed mapping and an explicit target state directory')
+    if state_dir is not None and Path(database).resolve() == (Path(state_dir) / 'turn-idempotency.db').resolve():
+        raise ValueError('Source snapshot and destination ledger must be different files')
+    conn, snapshot_hash = open_snapshot(database)
+    with closing(conn):
+        sessions, columns = validate_bindings(conn, mapping)
+        mapping_hash = canonical_turn_digest(mapping)
+        run_id = canonical_turn_digest([mapping['namespace'], snapshot_hash, mapping_hash])
+        ledger = TurnIdempotencyLedger(Path(state_dir) / 'turn-idempotency.db') if apply else None
+        cursor, counts = 0, Counter()
+        if ledger:
+            _progress(ledger)
+            with closing(ledger._connect()) as progress, progress:
+                progress.execute('INSERT OR IGNORE INTO source_import_progress(run_id,namespace,snapshot_sha256,mapping_sha256) VALUES (?,?,?,?)',
+                                 (run_id, mapping['namespace'], snapshot_hash, mapping_hash))
+                previous = progress.execute('SELECT cursor,counts_json FROM source_import_progress WHERE run_id=?', (run_id,)).fetchone()
+                cursor, counts = previous['cursor'], Counter(json.loads(previous['counts_json']))
+        selected = 'id,session_id,role,content,timestamp,' + ','.join(
+            key if key in columns else default + ' AS ' + key for key, default in OPTIONAL_MESSAGE.items())
+        ids = list(sessions)
+        placeholders = ','.join('?' for _ in ids)
+        bindings = {b['session_id']: b for b in mapping['bindings']}
+        query = f'SELECT {selected} FROM messages WHERE session_id IN ({placeholders}) AND id>? ORDER BY id'
+        rows = conn.execute(query + (' LIMIT ?' if apply else ''), (*ids, cursor, limit) if apply else (*ids, cursor))
+        for row in rows:
+            previous_cursor = cursor
+            row = dict(row)
+            binding = bindings[row['session_id']]
+            prepared, reason = source_message(row, sessions[row['session_id']], binding, mapping['namespace'])
+            if reason:
+                counts[reason] += 1
+            elif ledger:
+                message, occurred_at = prepared
+                turn_id = f"hermes-history:{mapping['namespace']}:{row['id']}"
+                try:
+                    created = ledger.record_source(turn_id, contact_id=binding['contact_id'],
+                        session_id=row['session_id'], messages=[message], scope='person',
+                        occurred_at=occurred_at, derive_claims=False)
+                    counts['retained_new' if created else 'retained_existing'] += 1
+                except SourceErased:
+                    counts['erased_not_restored'] += 1
+            else:
+                counts['eligible_source_quotations'] += 1
+            cursor = row['id']
+            if ledger:
+                # Source commit precedes cursor acknowledgement. A crash in
+                # between safely repeats record_source, never ordinary effects.
+                with closing(ledger._connect()) as progress, progress:
+                    updated = progress.execute('UPDATE source_import_progress SET cursor=?,counts_json=? WHERE run_id=? AND cursor=?',
+                                               (cursor, json.dumps(counts), run_id, previous_cursor))
+                    if updated.rowcount != 1:
+                        raise ValueError('Another importer advanced this run; resume with one process')
+        remaining = conn.execute(f'SELECT count(*) FROM messages WHERE session_id IN ({placeholders}) AND id>?', (*ids, cursor)).fetchone()[0]
+        unbound = [dict(r) for r in conn.execute(f'''SELECT s.source,count(DISTINCT s.id) sessions,count(m.id) messages
+            FROM sessions s LEFT JOIN messages m ON m.session_id=s.id
+            WHERE s.id NOT IN ({placeholders}) GROUP BY s.source''', ids)]
+        return {'mode': 'apply' if apply else 'dry_run', 'run_id': run_id,
+            'snapshot_sha256': snapshot_hash, 'mapping_sha256': mapping_hash,
+            'bound_sessions': len(sessions), 'cursor': cursor, 'remaining': remaining,
+            'complete': remaining == 0, 'counts': dict(counts),
+            'unmapped_retained_in_hermes': unbound,
+            'learning_replayed': False, 'models_called': False,
+            'projection': 'canonical_source_fts_and_queued_semantic_text_only'}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--database', type=Path, required=True)
+    parser.add_argument('--mapping', type=Path, required=True)
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument('--dry-run', action='store_true')
+    mode.add_argument('--apply', action='store_true')
+    parser.add_argument('--state-dir', type=Path)
+    parser.add_argument('--limit', type=int, default=1000)
+    args = parser.parse_args()
+    try:
+        result = import_history(args.database, mapping_document(args.mapping), state_dir=args.state_dir,
+                                apply=args.apply, limit=args.limit)
+    except (ValueError, OSError, sqlite3.Error) as exc:
+        parser.exit(1, f'History import stopped: {exc}\n')
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()

apsimo/turns/hermes_kanban.py

@@ -0,0 +1,268 @@
+"""Read selected native boards and accepted draft associations.
+
+Hermes owns its database, task transitions and recovery. This reader never
+initializes a board or imports the native runtime into the sidecar environment.
+"""
+from contextlib import closing
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import sqlite3
+import time
+
+from .hermes_work import selected_home
+
+
+_BOARD = re.compile(r'[a-z0-9][a-z0-9_-]{0,63}')
+_TERMINAL = ('done', 'cancelled', 'archived')
+
+
+def _board_path(home, board):
+    return home/'kanban.db' if board == 'default' else home/'kanban/boards'/board/'kanban.db'
+
+
+def observed_boards():
+    """Select explicit boards or the native current namespace, never enumerate."""
+    home = selected_home()
+    if home is None:
+        return None, [], 'profile_not_bound'
+    if home.parent.name == 'profiles':
+        home = home.parent.parent
+    override = os.environ.get('HERMES_KANBAN_HOME', '').strip()
+    if override and Path(override).expanduser().resolve() != home:
+        raise ValueError('conflicting_native_home')
+    configured = os.environ.get('COLONY_HERMES_WORK_BOARDS')
+    if configured is not None:
+        boards = json.loads(configured)
+        if (not isinstance(boards, list) or not 1 <= len(boards) <= 8
+                or any(not isinstance(b, str) or not _BOARD.fullmatch(b) for b in boards)):
+            raise ValueError('invalid_selected_boards')
+        boards = list(dict.fromkeys(boards))
+        selection = 'configured_boards'
+    else:
+        # Match native current-board precedence. Stale native selections fall
+        # through to default; explicit observer selections remain unavailable.
+        candidates = [os.environ.get('HERMES_KANBAN_BOARD', '').strip().lower()]
+        pointer = home/'kanban/current'
+        if pointer.is_file() and pointer.stat().st_size <= 256:
+            candidates.append(pointer.read_text().strip().lower())
+        boards = [next((b for b in candidates if _BOARD.fullmatch(b) and
+                        (b == 'default' or _board_path(home, b).exists()
+                         or (_board_path(home, b).parent/'board.json').exists())), 'default')]
+        selection = 'current_board_only'
+    pinned = os.environ.get('HERMES_KANBAN_DB', '').strip()
+    if pinned and (len(boards) != 1 or Path(pinned).expanduser().resolve()
+                   != _board_path(home, boards[0]).resolve()):
+        raise ValueError('conflicting_native_board')
+    return home, boards, selection
+
+
+def kanban_view(*, limit=8, now=None, read_budget=.2):
+    """Owner-only operational projection; no board initialization or dispatch."""
+    view = {'source': 'hermes_native_kanban_ledgers', 'available': False,
+            'items': [], 'recent': [], 'complete': False, 'boards': [],
+            'coverage': 'selected native boards only; task/run records and goal budgets, '
+                        'not process liveness or verified external effects'}
+    try:
+        home, boards, selection = observed_boards()
+    except (OSError, ValueError, KeyError, TypeError):
+        return {**view, 'reason': 'invalid_native_board_binding'}
+    if home is None:
+        return {**view, 'reason': selection}
+    view.update(source_home_id=hashlib.sha256(str(home).encode()).hexdigest(), selection=selection)
+    limit = max(1, min(int(limit), 100))
+    now = time.time() if now is None else now
+    deadline = time.monotonic() + min(.2, max(.001, read_budget))
+    active, recent, total, recent_total = [], [], 0, 0
+    for board in boards:
+        coverage = {'board': board, 'available': False}
+        view['boards'].append(coverage)
+        path = _board_path(home, board)
+        if not path.is_file():
+            coverage['reason'] = 'native_board_absent'
+            continue
+        try:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError
+            with closing(sqlite3.connect(path.as_uri()+'?mode=ro', uri=True,
+                                         timeout=min(.05, remaining))) as db:
+                db.row_factory = sqlite3.Row
+                db.execute('PRAGMA query_only=ON')
+                db.set_progress_handler(lambda: int(time.monotonic() >= deadline), 1000)
+                db.execute('BEGIN')
+                terminal = "status IN ('done','cancelled','archived')"
+                # Archiving an unfinished task records an event, not a
+                # completion. Preserve that distinction in the projection.
+                terminal_at = ("CASE WHEN status='archived' THEN "
+                               "(SELECT MAX(e.created_at) FROM task_events e "
+                               "WHERE e.task_id=tasks.id AND e.kind='archived') "
+                               "ELSE completed_at END")
+                active_count = db.execute(f'SELECT count(*) FROM tasks WHERE NOT ({terminal})').fetchone()[0]
+                recent_count = db.execute(f'SELECT count(*) FROM tasks WHERE {terminal} AND ({terminal_at})>=?', (now-7*86400,)).fetchone()[0]
+                columns = ('id,title,status,assignee,goal_mode,goal_max_turns,current_run_id,'
+                           'created_at,started_at,completed_at,last_heartbeat_at,'
+                           f'{terminal_at} AS terminal_record_at')
+                rows = db.execute(f'SELECT {columns} FROM tasks WHERE NOT ({terminal}) '
+                                  'ORDER BY created_at DESC,id LIMIT ?', (limit,)).fetchall()
+                done = db.execute(f'SELECT {columns} FROM tasks WHERE {terminal} AND ({terminal_at})>=? '
+                                  'ORDER BY terminal_record_at DESC,id LIMIT ?', (now-7*86400,limit)).fetchall()
+
+                def project(row):
+                    run = db.execute('SELECT status FROM task_runs WHERE id=? AND task_id=?',
+                                     (row['current_run_id'], row['id'])).fetchone()
+                    heartbeat = row['last_heartbeat_at']
+                    return {'native_board': board, 'native_task_id': row['id'],
+                            'label': str(row['title'] or '')[:128], 'status': row['status'],
+                            'assignee': str(row['assignee'] or '')[:128],
+                            'goal_mode': bool(row['goal_mode']), 'goal_max_turns': row['goal_max_turns'],
+                            'native_run_id': row['current_run_id'], 'native_run_status': run['status'] if run else None,
+                            'created_at': row['created_at'], 'started_at': row['started_at'],
+                            'completed_at': row['completed_at'],
+                            'terminal_record_at': row['terminal_record_at'],
+                            'heartbeat_age_seconds': round(max(0., now-heartbeat), 1) if heartbeat else None,
+                            'liveness': 'native_terminal_record' if row['status'] in _TERMINAL else 'unknown'}
+                projected, projected_done = [project(r) for r in rows], [project(r) for r in done]
+            active.extend(projected); recent.extend(projected_done)
+            total += active_count; recent_total += recent_count
+            coverage.update(available=True, total=active_count, recent_total=recent_count)
+        except (OSError, sqlite3.Error, ValueError, TypeError):
+            coverage['reason'] = 'native_board_unavailable'
+    active.sort(key=lambda r: (-r['created_at'], r['native_board'], r['native_task_id']))
+    recent.sort(key=lambda r: (-r['terminal_record_at'], r['native_board'], r['native_task_id']))
+    available = any(b['available'] for b in view['boards'])
+    return {**view, 'available': available, 'partial': not all(b['available'] for b in view['boards']),
+            **({} if available else {'reason': 'selected_native_boards_unavailable'}),
+            'items': active[:limit], 'recent': recent[:limit], 'total': total,
+            'recent_total': recent_total, 'truncated': total>limit, 'recent_truncated': recent_total>limit,
+            'limit': limit, 'recent_window_seconds': 7*86400}
+
+
+def selected_board():
+    home = selected_home()
+    if home is not None and home.parent.name == 'profiles':
+        home = home.parent.parent
+    board = os.environ.get('COLONY_LOCAL_WORK_BOARD', 'colony-drafts').strip()
+    profile = os.environ.get('COLONY_LOCAL_WORK_PROFILE', 'colony-drafts').strip()
+    if home is None or not re.fullmatch(r'[a-z0-9][a-z0-9_-]{0,63}', board) or not profile:
+        raise ValueError('native_board_binding_unavailable')
+    path = home/'kanban.db' if board == 'default' else home/'kanban/boards'/board/'kanban.db'
+    return home, board, profile, path
+
+
+def task_snapshot(identifier, contact_id, native, *, review=False, followup=False, read_timeout=.2):
+    """Verify native provenance and, when supplied, the currently held run."""
+    if review or followup:
+        home, boards, _ = observed_boards()
+        if home is None or 'default' not in boards:
+            raise ValueError('selected_native_review_board_required')
+        board, profile, path = 'default', 'default', _board_path(home, 'default')
+    else:
+        home, board, profile, path = selected_board()
+    if native['native_board'] != board:
+        raise ValueError('selected_native_board_required')
+    if not path.is_file():
+        raise OSError('native_board_unavailable')
+    with closing(sqlite3.connect(path.as_uri()+'?mode=ro', uri=True,
+                                 timeout=min(2., max(0., read_timeout)))) as db:
+        db.row_factory = sqlite3.Row
+        db.execute('PRAGMA query_only=ON')
+        db.execute('BEGIN')
+        task = db.execute('SELECT * FROM tasks WHERE id=?', (native['native_task_id'],)).fetchone()
+        if review:
+            profile = 'colony-reviews'
+            # Preserve historical observations; an unrestricted never-run task
+            # cannot be associated through this API after the boundary change.
+            if task is not None and task['assignee'] == 'default' and db.execute(
+                    'SELECT 1 FROM task_runs WHERE task_id=? LIMIT 1', (task['id'],)).fetchone():
+                profile = 'default'
+        creator = 'colony-followup' if followup else 'colony-initiative' if review else 'colony-local-work'
+        if (task is None or task['created_by'] != creator
+                or task['idempotency_key'] != creator+':'+identifier
+                or task['tenant'] != contact_id or task['assignee'] != profile):
+            raise ValueError('accepted_native_task_required')
+        result = {'source_home_id': hashlib.sha256(str(home).encode()).hexdigest(),
+                  'native_board': board, 'native_task_id': task['id']}
+        count = db.execute('SELECT count(*) FROM task_runs WHERE task_id=?', (task['id'],)).fetchone()[0]
+        run = None
+        if native.get('native_run_id') is not None:
+            run = db.execute('SELECT * FROM task_runs WHERE id=? AND task_id=?',
+                             (native['native_run_id'], task['id'])).fetchone()
+            if (task['status'] != 'running' or task['current_run_id'] != native['native_run_id']
+                    or run is None or run['status'] != 'running'
+                    or not native.get('native_claim_lock')
+                    or task['claim_lock'] != native['native_claim_lock']
+                    or run['claim_lock'] != native['native_claim_lock']):
+                raise ValueError('current_native_run_required')
+            result.update(native_run_id=run['id'], native_claim_lock=run['claim_lock'])
+        state = {'status': task['status'], 'native_run_id': task['current_run_id'],
+                 'attempt_count': count, 'archived': task['status'] == 'archived'}
+        if review or followup:
+            state['forecast_configuration'] = {
+                'runtime_budget_seconds': dict(task).get('max_runtime_seconds'),
+                'requested_profile': task['assignee'],
+                'task_model_override_at_observation': dict(task).get('model_override'),
+                'task_provider_override_at_observation': dict(task).get('provider_override'),
+                'served_model': None, 'timestamp_precision_seconds': 1,
+            }
+            latest = db.execute('SELECT * FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1',
+                                (task['id'],)).fetchone()
+            gave_up = bool(latest and db.execute("SELECT 1 FROM task_events WHERE task_id=? "
+                "AND kind='gave_up' AND created_at>=? LIMIT 1", (task['id'], latest['started_at'])).fetchone())
+            state.update(contract_sha256=hashlib.sha256((task['body'] or '').encode()).hexdigest(),
+                         completed_run=bool(latest and latest['outcome'] == 'completed'),
+                         gave_up=gave_up and task['status'] == 'blocked' and latest['outcome'] in
+                                 {'gave_up', 'crashed', 'timed_out', 'spawn_failed'},
+                         run_outcome=latest['outcome'] if latest else None,
+                         error=str(latest['error'] or task['last_failure_error'] or '')[:500] if latest else '',
+                         summary=str(latest['summary'] or '')[:1600] if latest else '',
+                         native_run_id=latest['id'] if latest else None)
+            terminal_at = dict(task).get('completed_at')
+            if task['status'] == 'archived':
+                terminal_at = db.execute("SELECT MAX(created_at) FROM task_events WHERE task_id=? AND kind='archived'", (task['id'],)).fetchone()[0]
+            if latest and latest['ended_at'] is not None:
+                state['duration_observation'] = {
+                    'outcome': latest['outcome'], 'started_at': latest['started_at'],
+                    'ended_at': latest['ended_at'], 'attempt_count': count,
+                    'profile': latest['profile'], 'served_model': None,
+                    'execution_seconds': latest['ended_at'] - latest['started_at'],
+                    'timestamp_precision_seconds': 1,
+                }
+            elif terminal_at is not None and task['status'] in {'done', 'archived', 'cancelled'}:
+                state['duration_observation'] = {
+                    'outcome': task['status'], 'started_at': dict(task).get('started_at'),
+                    'ended_at': terminal_at, 'attempt_count': count,
+                    'profile': task['assignee'], 'served_model': None,
+                    'execution_seconds': None, 'timestamp_precision_seconds': 1,
+                }
+            if latest and latest['outcome'] in {'crashed', 'timed_out', 'spawn_failed', 'gave_up'}:
+                state['runtime_observation'] = {
+                    'outcome': latest['outcome'], 'started_at': latest['started_at'],
+                    'ended_at': latest['ended_at'], 'max_runtime_seconds': latest['max_runtime_seconds'],
+                    'attempt_count': count, 'profile': latest['profile'],
+                    'task_model_override_at_observation': dict(task).get('model_override'),
+                    'task_provider_override_at_observation': dict(task).get('provider_override'),
+                    'served_model': 'unknown',
+                    'role': 'native_default_worker',
+                }
+        return result, state
+
+
+def project_accepted(identifier, contact_id, context):
+    """Observe only an accepted task, never expose a machine-wide board."""
+    review = context.get('native_review')
+    if review:
+        contact_id, context = review['contact_id'], {**review, 'execution_backend': 'kanban'}
+    if context.get('execution_backend') != 'kanban' or not context.get('native_task_id'):
+        return None
+    try:
+        native, state = task_snapshot(identifier, contact_id, {
+            'native_board': context.get('native_board'), 'native_task_id': context['native_task_id']}, review=bool(review))
+        if native['source_home_id'] != context.get('source_home_id'):
+            raise ValueError('selected_native_home_changed')
+        return {'available': True, **native, **state,
+                'liveness': 'native_running_record' if state['status'] == 'running' else 'native_task_record'}
+    except (OSError, sqlite3.Error, ValueError, KeyError, TypeError):
+        return {'available': False, 'reason': 'accepted_native_task_unavailable'}

apsimo/turns/hermes_work.py

@@ -0,0 +1,96 @@
+"""Read one explicitly bound native cron ledger, without importing its scheduler.
+
+Hermes owns transitions and recovery. These rows are a read projection, not a
+new lease, process inventory, or proof that an external effect completed.
+"""
+from contextlib import closing
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import sqlite3
+import time
+
+from apsimo import get_state_dir
+
+
+def selected_home():
+    """Use the private instance binding or explicit HERMES_HOME, never a scan."""
+    selected = os.environ.get('HERMES_HOME', '').strip()
+    path = get_state_dir() / 'instance.json'
+    if path.is_file():
+        manifest = json.loads(path.read_text())
+        if manifest.get('version') != 1 or manifest.get('profile') != 'local':
+            raise ValueError('unsupported_instance_binding')
+        bound = Path(manifest['hermes_home']).expanduser().resolve()
+        if selected and Path(selected).expanduser().resolve() != bound:
+            raise ValueError('conflicting_instance_binding')
+        return bound
+    return Path(selected).expanduser().resolve() if selected else None
+
+
+def _age(value, now):
+    if not value:
+        return None
+    parsed = datetime.fromisoformat(value.replace('Z', '+00:00'))
+    if parsed.tzinfo is None:
+        return None
+    return round(max(0., now - parsed.timestamp()), 1)
+
+
+def cron_view(*, limit=8, now=None):
+    view = {'source': 'hermes_native_cron_ledger', 'available': False,
+            'items': [], 'recent': [], 'complete': False,
+            'coverage': 'one selected Hermes profile; no process liveness or external-effect verification'}
+    try:
+        home = selected_home()
+    except (OSError, ValueError, KeyError, TypeError):
+        return {**view, 'reason': 'invalid_profile_binding'}
+    if home is None:
+        return {**view, 'reason': 'profile_not_bound'}
+    view['source_home_id'] = hashlib.sha256(str(home).encode()).hexdigest()
+    path = home / 'cron' / 'executions.db'
+    limit = max(1, min(int(limit), 100))
+    now = time.time() if now is None else now
+    deadline = time.monotonic() + .2
+    try:
+        if not path.is_file():
+            return {**view, 'reason': 'native_ledger_absent'}
+        with closing(sqlite3.connect(path.as_uri() + '?mode=ro', uri=True, timeout=.1)) as conn:
+            conn.row_factory = sqlite3.Row
+            conn.execute('PRAGMA query_only=ON')
+            conn.set_progress_handler(lambda: int(time.monotonic() >= deadline), 1000)
+            # One snapshot for active counts and rows. No initialization,
+            # recovery, native list_executions(), or schema writes on read.
+            conn.execute('BEGIN')
+            total = conn.execute("SELECT count(*) FROM executions WHERE status IN ('claimed','running')").fetchone()[0]
+            columns = 'id, job_id, source, status, claimed_at, started_at, finished_at'
+            active = conn.execute(f"SELECT {columns} FROM executions WHERE status IN ('claimed','running') ORDER BY claimed_at DESC, id DESC LIMIT ?", (limit,)).fetchall()
+            cutoff = datetime.fromtimestamp(now - 86400, timezone.utc).isoformat()
+            recent = conn.execute(f"SELECT {columns} FROM executions WHERE status IN ('completed','failed','unknown') AND julianday(finished_at) >= julianday(?) ORDER BY finished_at DESC, id DESC LIMIT ?", (cutoff, limit)).fetchall()
+        # Labels are optional, bounded, and never fall back to prompts/scripts.
+        names = {}
+        jobs = home / 'cron' / 'jobs.json'
+        if jobs.is_file() and jobs.stat().st_size <= 4 * 1024 * 1024:
+            try:
+                document = json.loads(jobs.read_text())
+                names = {str(job['id']): str(job['name'])[:200]
+                         for job in document.get('jobs', [])
+                         if isinstance(job, dict) and job.get('id') and isinstance(job.get('name'), str)}
+            except (OSError, ValueError, TypeError, AttributeError):
+                pass
+
+        def project(row):
+            item = dict(row)
+            item['execution_id'] = item.pop('id')
+            item['name'] = names.get(item['job_id'])
+            item['record_age_seconds'] = _age(item['finished_at'] or item['started_at'] or item['claimed_at'], now)
+            item['liveness'] = 'unknown' if item['status'] in {'claimed', 'running', 'unknown'} else 'native_terminal_record'
+            return item
+
+        return {**view, 'available': True, 'items': [project(row) for row in active],
+                'recent': [project(row) for row in recent], 'total': total,
+                'truncated': total > len(active), 'recent_window_seconds': 86400}
+    except (OSError, sqlite3.Error, ValueError, TypeError):
+        return {**view, 'reason': 'native_ledger_unavailable'}