coopagents 0.7.0__py3-none-any.whl

coopagents/__init__.py

@@ -0,0 +1 @@
+"""Local Coopagents collaboration primitives."""

coopagents/account_api.py

@@ -0,0 +1,213 @@
+"""Cookie authenticated account HTTP routes. Domain stores own authorization."""
+import threading
+import hashlib
+import hmac
+import json
+import time
+import unicodedata
+from starlette.concurrency import run_in_threadpool
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+from .errors import AccessDenied, ValidationError
+
+COOKIE = 'coopagents_account'
+THROTTLE_LIMIT = 10000
+
+class AccountBusy(Exception):
+    pass
+
+
+def cookie_token(request, name=COOKIE, required=True):
+    values = []
+    for header in request.headers.getlist('cookie'):
+        for part in header.split(';'):
+            key, sep, value = part.strip().partition('=')
+            if key == name and sep:
+                values.append(value)
+    if len(values) > 1 or (required and len(values) != 1) or any(not 1 <= len(value) <= 128 for value in values):
+        raise AccessDenied('Account cookie not accepted')
+    return values[0] if values else None
+
+
+def session_response(info, secure):
+    token = info['session_token']
+    response = JSONResponse({key: value for key, value in info.items() if key != 'session_token'})
+    response.set_cookie(COOKIE, token, max_age=604800, httponly=True, secure=secure, samesite='lax', path='/')
+    return response
+
+
+class LoginThrottle:
+    """Persist short windows, without permanent account lockout or global lockout."""
+    def __init__(self, db):
+        self.db = db
+        with db.connect(write=True) as c:
+            c.execute('CREATE TABLE IF NOT EXISTS account_login_throttle(key TEXT PRIMARY KEY,window REAL NOT NULL,attempts INTEGER NOT NULL)')
+
+    def attempt(self, username, address):
+        now = time.time()
+        username = unicodedata.normalize('NFKC', username).strip().casefold()
+        keys = [(hashlib.sha256(('user:' + username).encode()).hexdigest(), 20),
+                (hashlib.sha256(('ip:' + address).encode()).hexdigest(), 60)]
+        with self.db.connect(write=True) as c:
+            for key, limit in keys:
+                row = c.execute('SELECT window,attempts FROM account_login_throttle WHERE key=?', (key,)).fetchone()
+                start, count = (row['window'], row['attempts']) if row and now - row['window'] < 60 else (now, 0)
+                if count >= limit:
+                    raise AccessDenied('Login temporarily unavailable; try again later')
+                if row is None and c.execute('SELECT count(*) FROM account_login_throttle').fetchone()[0] >= THROTTLE_LIMIT:
+                    expired = c.execute('SELECT key FROM account_login_throttle WHERE window<=? ORDER BY window LIMIT 1', (now - 60,)).fetchone()
+                    if expired is None:
+                        raise AccessDenied('Login temporarily unavailable; try again later')
+                    c.execute('UPDATE account_login_throttle SET key=?,window=?,attempts=0 WHERE key=?', (key, now, expired['key']))
+                c.execute('INSERT INTO account_login_throttle VALUES(?,?,?) ON CONFLICT(key) DO UPDATE SET window=excluded.window,attempts=excluded.attempts', (key, start, count + 1))
+
+
+def account_routes(service, *, mode, origin, bootstrap_secret, oauth):
+    from .api import error_payload, validate, fields
+    accounts, workspaces = service.accounts, service.workspaces
+    expensive = threading.BoundedSemaphore(2)
+    throttle = LoginThrottle(accounts.db)
+    service.login_throttle = throttle
+    secure = bool(origin and origin.startswith('https://'))
+    bootstrap_hash = hashlib.sha256(bootstrap_secret.encode()).digest() if bootstrap_secret else None
+
+    def schema(required='', optional=None):
+        return fields(required, optional)
+
+    operations = {
+        '/account/teams': (workspaces.create_team, schema('name')),
+        '/account/password': (accounts.change_password, schema('current_password new_password')),
+        '/account/logout': (accounts.logout, schema()),
+        '/account/teams/{team_id}/projects': (workspaces.create_project, schema('name', {'repository': ''})),
+        '/account/teams/{team_id}/claim': (workspaces.claim_legacy_project, schema('owner_web_token')),
+        '/account/teams/{team_id}/invites': (workspaces.create_invite, {**schema('', {'role': 'member'}), 'project_ids': (list, False, [])}),
+        '/account/teams/{team_id}/members/{account_id}/role': (workspaces.change_role, schema('role')),
+        '/account/teams/{team_id}/members/{account_id}/remove': (workspaces.remove_member, schema()),
+        '/account/teams/{team_id}/members/{account_id}/reset-password': (workspaces.reset_password, schema('new_password')),
+        '/account/projects/{room_id}/select': (workspaces.project_credential, schema()),
+        '/account/projects/{room_id}/members/{account_id}/grant': (workspaces.grant_project, schema()),
+        '/account/projects/{room_id}/members/{account_id}/remove': (workspaces.remove_project_member, schema()),
+    }
+    reads = {
+        '/account/session': accounts.session_info,
+        '/account/teams': workspaces.list_teams,
+        '/account/teams/{team_id}/projects': workspaces.list_projects,
+        '/account/teams/{team_id}/managed-projects': workspaces.list_managed_projects,
+        '/account/teams/{team_id}/members': workspaces.list_members,
+    }
+
+    async def execute(method, *args, **kwargs):
+        # Bounds password work as well as database work outside the event loop.
+        if not expensive.acquire(blocking=False):
+            raise AccountBusy()
+        try:
+            return await run_in_threadpool(method, *args, **kwargs)
+        finally:
+            expensive.release()
+
+    async def handle(request):
+        try:
+            path = request.url.path
+            expected_origin = origin or str(request.base_url).rstrip('/')
+            if request.method == 'POST':
+                if request.headers.getlist('origin') != [expected_origin]:
+                    return JSONResponse({'error': 'AccessDenied', 'message': 'Origin not accepted'}, status_code=403)
+            token = cookie_token(request, required=False)
+            if path == '/account/config':
+                return JSONResponse({'mode': mode, 'local_login_enabled': mode == 'self-hosted',
+                    'bootstrap_enabled': mode == 'self-hosted' and bootstrap_hash is not None and await execute(accounts.local_setup_available),
+                    'github_oauth_enabled': oauth is not None})
+            if request.method == 'GET':
+                if not token:
+                    raise AccessDenied('Account cookie required')
+                try:
+                    result = await execute(reads[request.scope['account_pattern']], token, **request.path_params)
+                except AccessDenied:
+                    if path != '/account/session':
+                        raise
+                    response = JSONResponse({'error': 'AccessDenied', 'message': 'Account session not accepted'}, status_code=401)
+                    response.delete_cookie(COOKIE, httponly=True, secure=secure, samesite='lax', path='/')
+                    return response
+                return JSONResponse(result)
+            if mode == 'cloud' and (path in ('/account/login', '/account/bootstrap', '/account/password') or path.endswith('/reset-password')):
+                raise AccessDenied('Local account authentication disabled')
+            if request.headers.get('content-type', '').split(';')[0].strip().lower() != 'application/json':
+                raise ValidationError('Content type must be application/json')
+            try:
+                data = json.loads(await request.body())
+            except (ValueError, UnicodeError):
+                raise ValidationError('Malformed JSON') from None
+            if path == '/account/logout':
+                validate(data, schema())
+                try:
+                    if not token:
+                        raise AccessDenied('Account session not accepted')
+                    await execute(accounts.authenticate, token)
+                except AccessDenied:
+                    response = JSONResponse({'ok': True})
+                    response.delete_cookie(COOKIE, httponly=True, secure=secure, samesite='lax', path='/')
+                    return response
+            if path == '/account/invites/preview':
+                data = validate(data, schema('invite_token'))
+                return JSONResponse(await execute(workspaces.preview_invite, **data), headers={'Cache-Control': 'no-store'})
+            if token and path not in ('/account/login', '/account/bootstrap'):
+                csrf = request.headers.getlist('x-coopagents-csrf')
+                if len(csrf) != 1:
+                    raise AccessDenied('CSRF credential required')
+                await execute(accounts.authenticate, token, csrf[0])
+            if path == '/account/bootstrap':
+                if bootstrap_hash is None or len(request.headers.getlist('x-coopagents-bootstrap')) != 1 or not hmac.compare_digest(hashlib.sha256(request.headers['x-coopagents-bootstrap'].encode()).digest(), bootstrap_hash):
+                    raise AccessDenied('Bootstrap credential not accepted')
+                data = validate(data, schema('username password', {'display_name': None}))
+                account = await execute(accounts.bootstrap, **data)
+                return session_response(await execute(accounts.create_session, account['id']), secure)
+            if path == '/account/login':
+                data = validate(data, schema('username password'))
+                await execute(throttle.attempt, data['username'], request.client.host if request.client else '')
+                return session_response(await execute(accounts.login, **data), secure)
+            if path == '/account/invites/accept':
+                if token:
+                    data = validate(data, schema('invite_token'))
+                    return JSONResponse(await execute(workspaces.accept_invite, session_token=token, **data))
+                if mode == 'cloud':
+                    raise AccessDenied('GitHub account session required')
+                data = validate(data, schema('invite_token username password', {'display_name': None}))
+                await execute(throttle.attempt, data['username'], request.client.host if request.client else '')
+                result = await execute(workspaces.accept_invite, **data)
+                info = await execute(accounts.create_session, result['account']['id'])
+                return session_response({**result, **info}, secure)
+            if not token:
+                raise AccessDenied('Account cookie required')
+            method, body_schema = operations[request.scope['account_pattern']]
+            data = validate(data, body_schema)
+            if 'project_ids' in data:
+                project_ids = data['project_ids']
+                if len(project_ids) > 200 or any(type(value) is not str or not value.strip() or len(value) > 120 for value in project_ids):
+                    raise ValidationError('Project IDs must contain at most 200 nonempty strings of at most 120 characters')
+                try:
+                    for value in project_ids:
+                        value.encode('utf-8')
+                except UnicodeEncodeError:
+                    raise ValidationError('Project IDs must contain valid Unicode') from None
+            result = await execute(method, token, **request.path_params, **data)
+            response = JSONResponse(result if result is not None else {'ok': True})
+            if path in ('/account/logout', '/account/password'):
+                response.delete_cookie(COOKIE, httponly=True, secure=secure, samesite='lax', path='/')
+            return response
+        except AccountBusy:
+            return JSONResponse({'error': 'Busy', 'message': 'Service busy; try again later'}, status_code=503)
+        except Exception as error:
+            payload, status = error_payload(error)
+            return JSONResponse(payload, status_code=status)
+
+    result = []
+    patterns = set(operations) | set(reads) | {'/account/config', '/account/bootstrap', '/account/login', '/account/invites/accept', '/account/invites/preview'}
+    for pattern in sorted(patterns):
+        async def endpoint(request, pattern=pattern):
+            request.scope['account_pattern'] = pattern
+            return await handle(request)
+        methods = (['GET'] if pattern in reads or pattern == '/account/config' else []) + (['POST'] if pattern in operations or pattern in ('/account/bootstrap', '/account/login', '/account/invites/accept', '/account/invites/preview') else [])
+        result.append(Route(pattern, endpoint, methods=methods))
+    if oauth:
+        result.extend(oauth.routes(service, execute, secure))
+    return result

coopagents/account_recovery.py

@@ -0,0 +1,84 @@
+"""Offline local-password recovery; possession of the database is authority."""
+import argparse
+from contextlib import contextmanager
+import getpass
+from pathlib import Path
+import sqlite3
+import sys
+from types import SimpleNamespace
+import warnings
+
+from .accounts import AccountStore, _username
+from .errors import ValidationError
+
+
+class ExistingDatabase:
+    """Open only an existing file, including if the file disappears after validation."""
+    def __init__(self, path):
+        self.uri = Path(path).resolve().as_uri() + '?mode=rw'
+
+    @contextmanager
+    def connect(self, write=False):
+        c = sqlite3.connect(self.uri, uri=True, timeout=10, isolation_level=None)
+        try:
+            c.row_factory = sqlite3.Row
+            c.execute('PRAGMA foreign_keys=ON')
+            if write:
+                c.execute('BEGIN IMMEDIATE')
+            try:
+                yield c
+                if write:
+                    c.commit()
+            except BaseException:
+                if write:
+                    c.rollback()
+                raise
+        finally:
+            c.close()
+
+
+def recover_password(database, username, new_password):
+    username = _username(username)
+    db = ExistingDatabase(database)
+    try:
+        # Deliberately do not run schema creation/migrations during recovery.
+        # Use the domain reset on the existing schema in one writer transaction.
+        with db.connect(write=True) as c:
+            row = c.execute('SELECT id,password_hash FROM accounts WHERE username=?', (username,)).fetchone()
+            if row is None or row['password_hash'] is None:
+                raise ValidationError('Existing local password account required')
+            store = AccountStore.__new__(AccountStore)
+            store.db = db
+            store.identity = SimpleNamespace(db=db)
+            store._reset_password(c, row['id'], new_password)
+    except sqlite3.Error:
+        raise ValidationError('Existing account database could not be opened or updated') from None
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--database', required=True, help='Existing Coopagents SQLite file')
+    parser.add_argument('--username', required=True, help='Existing local username (not GitHub display name)')
+    args = parser.parse_args(argv)
+    try:
+        # getpass otherwise falls back to echoed stdin on terminals it cannot
+        # control. Abort before that fallback can read a plaintext password.
+        with warnings.catch_warnings():
+            warnings.simplefilter('error', getpass.GetPassWarning)
+            password = getpass.getpass('New password (12–256 characters): ')
+            confirmation = getpass.getpass('Repeat new password: ')
+        if password != confirmation:
+            raise ValidationError('Password confirmation does not match')
+        recover_password(args.database, args.username, password)
+    except getpass.GetPassWarning:
+        print('Recovery requires a terminal with hidden password input', file=sys.stderr)
+        return 1
+    except (ValidationError, OSError, EOFError, KeyboardInterrupt) as error:
+        print(str(error) or 'Recovery cancelled', file=sys.stderr)
+        return 1
+    print('Password reset. All account sessions and their project web access are invalidated.')
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

coopagents/accounts.py

@@ -0,0 +1,178 @@
+"""Local accounts and revocable browser sessions, independent of room tokens."""
+import hashlib
+import hmac
+import secrets
+import sqlite3
+import unicodedata
+from datetime import timedelta
+from uuid import uuid4
+
+from .errors import AccessDenied, ValidationError
+from .identity import _name, _token_hash, _utcnow, _expired
+
+
+def _username(value):
+    if not isinstance(value, str):
+        raise ValidationError('Username required')
+    value = unicodedata.normalize('NFKC', value).strip().casefold()
+    try:
+        value.encode('utf-8')
+    except UnicodeEncodeError:
+        raise ValidationError('Username must be valid Unicode') from None
+    if not 1 <= len(value) <= 120 or any(ord(ch) < 32 for ch in value):
+        raise ValidationError('Username must contain 1 to 120 characters')
+    return value
+
+
+def _password(value):
+    if not isinstance(value, str) or not 12 <= len(value) <= 256:
+        raise ValidationError('Password must contain 12 to 256 characters')
+    try:
+        return value.encode('utf-8')
+    except UnicodeEncodeError:
+        raise ValidationError('Password must be valid Unicode') from None
+
+
+def _hash_password(password, salt):
+    return hashlib.scrypt(_password(password), salt=bytes.fromhex(salt), n=16384, r=8, p=1).hex()
+
+
+class AccountStore:
+    def __init__(self, identity):
+        self.identity, self.db = identity, identity.db
+        with self.db.connect(write=True) as c:
+            c.execute('''CREATE TABLE IF NOT EXISTS accounts (
+                id TEXT PRIMARY KEY, username TEXT UNIQUE, display_name TEXT NOT NULL,
+                password_salt TEXT, password_hash TEXT, created_at TEXT NOT NULL)''')
+            c.execute('''CREATE TABLE IF NOT EXISTS account_sessions (
+                token_hash TEXT PRIMARY KEY, account_id TEXT NOT NULL REFERENCES accounts(id),
+                expires_at TEXT NOT NULL, revoked_at TEXT)''')
+            c.execute('''CREATE TABLE IF NOT EXISTS oauth_accounts (
+                provider TEXT NOT NULL, provider_id TEXT NOT NULL,
+                account_id TEXT NOT NULL REFERENCES accounts(id), PRIMARY KEY(provider,provider_id))''')
+
+    def local_setup_available(self):
+        with self.db.connect() as c:
+            return c.execute('SELECT 1 FROM accounts LIMIT 1').fetchone() is None
+
+    def _create_local(self, c, username, password, display_name=None):
+        username = _username(username)
+        salt = secrets.token_hex(16)
+        password_hash = _hash_password(password, salt)
+        account_id = str(uuid4())
+        try:
+            c.execute('INSERT INTO accounts VALUES(?,?,?,?,?,?)',
+                      (account_id, username, _name(display_name or username), salt, password_hash, _utcnow().isoformat()))
+        except sqlite3.IntegrityError:
+            raise ValidationError('Username unavailable') from None
+        return self._get(c, account_id)
+
+    def bootstrap(self, username, password, display_name=None):
+        with self.db.connect(write=True) as c:
+            if c.execute('SELECT 1 FROM accounts LIMIT 1').fetchone():
+                raise AccessDenied('Initial account already exists')
+            return self._create_local(c, username, password, display_name)
+
+    bootstrap_account = bootstrap
+
+    def _get(self, c, account_id):
+        row = c.execute('SELECT id,username,display_name FROM accounts WHERE id=?', (account_id,)).fetchone()
+        if row is None:
+            raise AccessDenied('Account not accepted')
+        return dict(row)
+
+    def get_account(self, account_id):
+        with self.db.connect() as c:
+            return self._get(c, account_id)
+
+    @staticmethod
+    def csrf_token(session_token):
+        _token_hash(session_token)
+        return hashlib.sha256(('coopagents-csrf:' + session_token).encode()).hexdigest()
+
+    def _create_session(self, c, account_id):
+        account = self._get(c, account_id)
+        token = secrets.token_urlsafe(32)
+        expiry = (_utcnow() + timedelta(days=7)).isoformat()
+        c.execute('INSERT INTO account_sessions VALUES(?,?,?,NULL)', (_token_hash(token), account_id, expiry))
+        return {'session_token': token, 'csrf_token': self.csrf_token(token), 'expires_at': expiry, 'account': account}
+
+    def create_session(self, account_id):
+        """Trusted OAuth adapter hook; never expose arbitrary IDs as HTTP login."""
+        with self.db.connect(write=True) as c:
+            return self._create_session(c, account_id)
+
+    def login(self, username, password):
+        try:
+            username = _username(username)
+            _password(password)
+        except ValidationError:
+            raise AccessDenied('Login not accepted') from None
+        with self.db.connect() as c:
+            row = c.execute('SELECT * FROM accounts WHERE username=?', (username,)).fetchone()
+        # Password work stays outside the SQLite writer lock. Recheck the verified
+        # hash inside the transaction so a concurrent reset cannot grant a session.
+        salt = row['password_salt'] if row and row['password_salt'] else '00' * 16
+        candidate = _hash_password(password, salt)
+        if row is None or not row['password_hash'] or not hmac.compare_digest(candidate, row['password_hash']):
+            raise AccessDenied('Login not accepted')
+        with self.db.connect(write=True) as c:
+            current = c.execute('SELECT password_hash FROM accounts WHERE id=?', (row['id'],)).fetchone()
+            if current is None or current['password_hash'] != row['password_hash']:
+                raise AccessDenied('Login not accepted')
+            return self._create_session(c, row['id'])
+
+    def resolve(self, c, session_token, csrf_token=None):
+        row = c.execute('SELECT account_id,expires_at FROM account_sessions WHERE token_hash=? AND revoked_at IS NULL',
+                        (_token_hash(session_token),)).fetchone()
+        if row is None or _expired(row['expires_at'], _utcnow()):
+            raise AccessDenied('Account session not accepted')
+        if csrf_token is not None and (not isinstance(csrf_token, str) or not hmac.compare_digest(csrf_token, self.csrf_token(session_token))):
+            raise AccessDenied('CSRF credential not accepted')
+        return self._get(c, row['account_id'])
+
+    def authenticate(self, session_token, csrf_token=None):
+        with self.db.connect() as c:
+            return self.resolve(c, session_token, csrf_token)
+
+    def session_info(self, session_token):
+        with self.db.connect() as c:
+            account = self.resolve(c, session_token)
+            row = c.execute('SELECT expires_at FROM account_sessions WHERE token_hash=?', (_token_hash(session_token),)).fetchone()
+            return {'account': account, 'csrf_token': self.csrf_token(session_token), 'expires_at': row['expires_at']}
+
+    def logout(self, session_token):
+        with self.db.connect(write=True) as c:
+            c.execute('UPDATE account_sessions SET revoked_at=? WHERE token_hash=?', (_utcnow().isoformat(), _token_hash(session_token)))
+
+    def _reset_password(self, c, account_id, new_password):
+        row = c.execute('SELECT password_hash FROM accounts WHERE id=?', (account_id,)).fetchone()
+        if row is None or row['password_hash'] is None:
+            raise ValidationError('Local password account required')
+        salt = secrets.token_hex(16)
+        c.execute('UPDATE accounts SET password_salt=?,password_hash=? WHERE id=?', (salt, _hash_password(new_password, salt), account_id))
+        c.execute('UPDATE account_sessions SET revoked_at=? WHERE account_id=? AND revoked_at IS NULL', (_utcnow().isoformat(), account_id))
+
+    def change_password(self, session_token, current_password, new_password):
+        with self.db.connect(write=True) as c:
+            account = self.resolve(c, session_token)
+            row = c.execute('SELECT password_salt,password_hash FROM accounts WHERE id=?', (account['id'],)).fetchone()
+            try:
+                valid = row['password_hash'] and hmac.compare_digest(_hash_password(current_password, row['password_salt']), row['password_hash'])
+            except ValidationError:
+                valid = False
+            if not valid:
+                raise AccessDenied('Current password not accepted')
+            self._reset_password(c, account['id'], new_password)
+
+    def oauth_account(self, provider, provider_id, display_name):
+        if provider != 'github' or not isinstance(provider_id, str) or not provider_id.isascii() or not provider_id.isdigit():
+            raise ValidationError('GitHub numeric provider ID required')
+        with self.db.connect(write=True) as c:
+            row = c.execute('SELECT account_id FROM oauth_accounts WHERE provider=? AND provider_id=?', (provider, provider_id)).fetchone()
+            if row:
+                return self._get(c, row['account_id'])
+            account_id = str(uuid4())
+            c.execute('INSERT INTO accounts VALUES(?,NULL,?,NULL,NULL,?)', (account_id, _name(display_name), _utcnow().isoformat()))
+            c.execute('INSERT INTO oauth_accounts VALUES(?,?,?)', (provider, provider_id, account_id))
+            return self._get(c, account_id)

coopagents/activity.py

@@ -0,0 +1,102 @@
+"""Explicit agent session heartbeats and self-reported task progress."""
+from itertools import combinations
+
+from .errors import AccessDenied, NotFound, ValidationError
+from .tasks import _text, _utc_now
+
+
+TOOLS = ("claude-code", "codex-cli", "codex-desktop")
+PROGRESS_STATES = ("working", "blocked", "local_done", "pushed", "pr_open", "merged")
+
+
+def _task_id(value):
+    if type(value) is not int or value <= 0:
+        raise ValidationError("Task id must be a positive integer")
+    return value
+
+
+class ActivityStore:
+    def __init__(self, identity_store):
+        self.db = identity_store.db
+        self.resolve = identity_store.resolve
+
+    def _owned_task(self, connection, principal, task_id, session_key=None, ownership_epoch=None):
+        from .task_lifecycle import execution_task
+        return execution_task(connection, principal, task_id, session_key, ownership_epoch)
+
+    def register_session(self, agent_token, session_key, tool, repository, branch, task_id=None, ownership_epoch=None):
+        session_key = _text(session_key, "Session key", 200)
+        repository = _text(repository, "Repository", 500)
+        branch = _text(branch, "Branch", 200)
+        if tool not in TOOLS:
+            raise ValidationError("Tool must be claude-code, codex-cli or codex-desktop")
+        if task_id is not None:
+            task_id = _task_id(task_id)
+        with self.db.connect(write=True) as connection:
+            principal = self.resolve(connection, agent_token, required_kind="agent")
+            if task_id is not None:
+                self._owned_task(connection, principal, task_id, session_key, ownership_epoch)
+            connection.execute("""INSERT INTO sessions
+                (room_id, member_id, session_key, tool, repository, branch, task_id, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT (room_id, member_id, session_key) DO UPDATE SET
+                    tool = excluded.tool, repository = excluded.repository,
+                    branch = excluded.branch, task_id = excluded.task_id,
+                    updated_at = excluded.updated_at""",
+                (principal.room_id, principal.member_id, session_key, tool,
+                 repository, branch, task_id, _utc_now()))
+            return dict(connection.execute("""SELECT * FROM sessions
+                WHERE room_id = ? AND member_id = ? AND session_key = ?""",
+                (principal.room_id, principal.member_id, session_key)).fetchone())
+
+    def list_sessions(self, token):
+        with self.db.connect() as connection:
+            principal = self.resolve(connection, token)
+            return [dict(row) for row in connection.execute(
+                "SELECT * FROM sessions WHERE room_id = ? ORDER BY id", (principal.room_id,))]
+
+    def report_progress(self, agent_token, task_id, state, summary, evidence="", session_key=None, ownership_epoch=None):
+        task_id = _task_id(task_id)
+        if state not in PROGRESS_STATES:
+            raise ValidationError("Unsupported progress state")
+        summary = _text(summary, "Summary", 4000)
+        if not isinstance(evidence, str) or len(evidence.strip()) > 1000:
+            raise ValidationError("Evidence must contain at most 1000 characters")
+        evidence = evidence.strip()
+        with self.db.connect(write=True) as connection:
+            principal = self.resolve(connection, agent_token, required_kind="agent")
+            self._owned_task(connection, principal, task_id, session_key, ownership_epoch)
+            connection.execute("""INSERT INTO progress
+                (task_id, room_id, member_id, state, summary, evidence, source, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, 'agent_report', ?)
+                ON CONFLICT (task_id) DO UPDATE SET member_id = excluded.member_id, state = excluded.state,
+                    summary = excluded.summary, evidence = excluded.evidence,
+                    updated_at = excluded.updated_at""",
+                (task_id, principal.room_id, principal.member_id, state, summary, evidence, _utc_now()))
+            return dict(connection.execute("SELECT * FROM progress WHERE task_id = ?",
+                                           (task_id,)).fetchone())
+
+    def list_progress(self, token):
+        with self.db.connect() as connection:
+            principal = self.resolve(connection, token)
+            return [dict(row) for row in connection.execute(
+                "SELECT * FROM progress WHERE room_id = ? ORDER BY task_id", (principal.room_id,))]
+
+    def overlaps(self, token):
+        """Compare declared scope strings; this performs no filesystem operations."""
+        with self.db.connect() as connection:
+            principal = self.resolve(connection, token)
+            tasks = connection.execute("SELECT id, scope FROM tasks WHERE room_id = ? AND cancelled_at IS NULL ORDER BY id",
+                                       (principal.room_id,)).fetchall()
+            result = []
+            for first, second in combinations(tasks, 2):
+                left, right = first["scope"].rstrip("/"), second["scope"].rstrip("/")
+                reason = None
+                if left == right:
+                    reason = "Declared scopes are equal"
+                elif left and right and (left.startswith(right + "/") or right.startswith(left + "/")):
+                    reason = "One declared scope is a slash-segment prefix of the other"
+                if reason:
+                    result.append({"task_ids": [first["id"], second["id"]],
+                                   "scopes": [first["scope"], second["scope"]], "reason": reason})
+            return result