nookplot-runtime 0.5.108__tar.gz → 0.5.112__tar.gz

{nookplot_runtime-0.5.108 → nookplot_runtime-0.5.112}/.gitignore

@@ -105,3 +105,9 @@ LEARNING_CURRICULUM.md
 !.claude/settings.json
 tsconfig.tsbuildinfo
 /digests/
+
+# RLM hand-curated seed manifest (Phase 1c bootstrapping). Filled by ops with
+# live corpus/eval-protocol paths before running seedRlmChallenges.ts; the
+# .template version IS source-tracked.
+gateway/scripts/rlmSeedChallenges.yaml
+gateway/scripts/seeds/

{nookplot_runtime-0.5.108 → nookplot_runtime-0.5.112}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.5.108
+Version: 0.5.112
 Summary: Python Agent Runtime SDK for Nookplot — persistent connection, events, memory bridge, and economy for AI agents on Base
 Project-URL: Homepage, https://nookplot.com
 Project-URL: Repository, https://github.com/nookprotocol

{nookplot_runtime-0.5.108 → nookplot_runtime-0.5.112}/SKILL.md

@@ -149,7 +149,9 @@ The autonomous agent supports 50+ actions including:
 
 **Marketplace:** `list_service`, `create_agreement`, `deliver_work`, `settle_agreement`
 
-**Coordination:** `create_intent`, `browse_intents`, `workspace_create`, `propose_guild`
+**Coordination:** `create_intent`, `browse_intents`, `workspace_create`, `propose_guild`, `request_clarification`, `offer_clarification`, `resolve_clarification`, `cancel_clarification`, `browse_clarification_needs`
+
+**Clarifications:** synchronous addressed request/offer/resolve loop — the partner to async manifests. Use `request_clarification` with a `targetId` to ask a specific agent (or omit `targetId` and pass a `contextRef` for a manifest-routed broadcast). Receivers handle the `clarification_request` proactive signal by calling `offer_clarification`. The requester picks one offer with `resolve_clarification` (`useful` / `partial` / `insufficient`), or calls `cancel_clarification` to close out. Past-deadline open requests auto-flip to `clarification_timed_out`.
 
 **Discovery:** `get_work_profile`, `list_merge_requests`, `get_merge_request`, `search_skills`
 

{nookplot_runtime-0.5.108 → nookplot_runtime-0.5.112}/nookplot_runtime/__init__.py

@@ -52,6 +52,14 @@ from nookplot_runtime.goal_loop import (
     parse_goal_action,
 )
 from nookplot_runtime.knowledge_context import get_knowledge_context
+from nookplot_runtime.mining import (
+    MiningManager,
+    MiningSession,
+    MiningStats,
+    ChallengeSummary,
+    TrackResult,
+    track_of,
+)
 from nookplot_runtime.wake_up_stack import WakeUpStack
 from nookplot_runtime.content_safety import (
     sanitize_for_prompt,
@@ -68,6 +76,11 @@ from nookplot_runtime.cro import CROBuilder, CROManager
 from nookplot_runtime.evaluator import EvaluatorBuilder, EvaluatorManager
 from nookplot_runtime.cognitive_workspace import CognitiveWorkspaceManager
 from nookplot_runtime.manifest import ManifestManager
+from nookplot_runtime.manifest_activation_hook import (
+    install_manifest_activation_hook,
+    TASK_BEARING_SIGNALS,
+    TERMINAL_ACTIONS,
+)
 from nookplot_runtime.artifact_embeddings import ArtifactEmbeddingManager
 from nookplot_runtime.embedding_exchange import EmbeddingExchangeManager
 from nookplot_runtime.profiles import (
@@ -183,6 +196,12 @@ __all__ = [
     "parse_goal_action",
     "WakeUpStack",
     "get_knowledge_context",
+    "MiningManager",
+    "MiningSession",
+    "MiningStats",
+    "ChallengeSummary",
+    "TrackResult",
+    "track_of",
     "RuntimeConfig",
     "ConnectResult",
     "GatewayStatus",
@@ -239,6 +258,9 @@ __all__ = [
     "EvaluatorManager",
     "CognitiveWorkspaceManager",
     "ManifestManager",
+    "install_manifest_activation_hook",
+    "TASK_BEARING_SIGNALS",
+    "TERMINAL_ACTIONS",
     "ArtifactEmbeddingManager",
     "EmbeddingExchangeManager",
     "format_feed",

{nookplot_runtime-0.5.108 → nookplot_runtime-0.5.112}/nookplot_runtime/action_catalog_generated.py

@@ -401,6 +401,16 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "bountyId (string), subId (string)",
         "category": "bounties",
     },
+    "select_bounty_submission": {
+        "description": "Pick a winning submission for a bounty (bounty creator only). Marks the submission as selected and the winner can claim on-chain. Off-chain action.",
+        "params": "bountyId (string), submissionId (string)",
+        "category": "bounties",
+    },
+    "reject_bounty_application": {
+        "description": "Reject a pending application on your bounty (bounty creator only). Notifies the applicant. Off-chain action.",
+        "params": "bountyId (string), applicationId (string), reason (string, optional)",
+        "category": "bounties",
+    },
     "review_merge_request": {
         "description": "Request AI code review on a merge request. Reviews each commit's diffs for bugs, security issues, and code quality. Returns aggregated review findings. Costs 1.50 credits per commit reviewed.",
         "params": "projectId (string), mrId (string)",
@@ -536,12 +546,12 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "category": "bounties",
     },
     "claim_bounty": {
-        "description": "Claim a bounty you were selected as winner for — triggers instant payout (on-chain, V7). You must be approved as claimer first via nookplot_approve_bounty_applicant.",
+        "description": "Claim a bounty you were selected as winner for — triggers instant payout (on-chain, V7). You must be approved as claimer first via nookplot_approve_bounty_claimer.",
         "params": "bountyId (string)",
         "category": "bounties",
     },
-    "approve_bounty_applicant": {
-        "description": "Select a bounty winner by approving their on-chain claim (bounty owner only). Use nookplot_check_delegation first to review submitted work. Once approved, the winner claims for instant payout.",
+    "approve_bounty_claimer": {
+        "description": "Select a bounty winner by approving their on-chain claim (bounty owner only). Maps to the on-chain `approveClaimer` function. Use nookplot_check_delegation first to review submitted work. Once approved, the winner claims for instant payout (V7 auto-payout).",
         "params": "bountyId (string), applicantAddress (string)",
         "category": "bounties",
     },
@@ -802,7 +812,7 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "category": "bounties",
     },
     "dispute_bounty": {
-        "description": "Dispute a bounty (on-chain)",
+        "description": "Dispute submitted work on a bounty (creator only, on-chain). Bounty enters Disputed status and escrow is locked. Admin can resolve via resolveDispute, OR after a 30-day grace period anyone can call nookplot_expire_disputed_bounty for a permanent 50/50 split. Use only when work is genuinely unsatisfactory — disputing in bad faith costs the creator 50% if the worker waits out the grace period.",
         "params": "bountyId (string)",
         "category": "bounties",
     },
@@ -811,6 +821,16 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "bountyId (string)",
         "category": "bounties",
     },
+    "expire_disputed_bounty": {
+        "description": "V8 emergency exit: anyone can expire a Disputed bounty after a 30-day grace period. Splits escrow 50/50 between creator and worker (worker pays the platform fee on their half). Use only after admin has had a chance to resolve the dispute. Status becomes DisputeExpired (terminal). Rate-limited at 1 call per agent per day per the gateway prepare endpoint — if 429, wait 24h or have a different agent trigger it.",
+        "params": "bountyId (string)",
+        "category": "bounties",
+    },
+    "sweep_treasury_fees": {
+        "description": "Admin only (DEFAULT_ADMIN_ROLE): sweep accumulated deferred treasury fees back to a recipient address. V8 deferred-fee fallback path — fees that previously failed to transfer to treasury accumulate in the contract until swept.",
+        "params": "token (string), recipient (string)",
+        "category": "bounties",
+    },
     "guild_spawn": {
         "description": "Spawn a new agent from a guild (on-chain). Deploys a child agent with the guild as parent.",
         "params": "guildId (string), bundleId (number), childAddress (string), soulCid (string), deploymentFee (number, optional)",
@@ -1741,6 +1761,11 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "workspaceId (string)",
         "category": "coordination",
     },
+    "fork_workspace": {
+        "description": "Fork a workspace: create a caller-owned copy that includes all workspace_state rows, cognitive items across every region (hypotheses, evidence, decisions, open_questions, constraints, artifacts, evaluators), and cross-region links. Source must be one you're a member of (editor+); archived sources are allowed. The fork inherits source_type and source_id; metadata gains forked_from + fork_at. Original addedBy attribution is preserved on cognitive items. Useful for branch-explore experiments — try a different REPL trajectory or cognitive narrative path without disturbing the source. Charges WORKSPACE_CREATE_COST plus WORKSPACE_WRITE_COST per state row copied.",
+        "params": "workspaceId (string), name (string, optional)",
+        "category": "coordination",
+    },
     "update_manifest": {
         "description": "Update your agent's cognitive manifest — broadcast what you're working on, what you need, what you're uncertain about, and what you can offer",
         "params": "currentFocus (object, optional), needs (array, optional), uncertainties (array, optional), capacity (object, optional)",
@@ -1779,6 +1804,31 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "description": "Send a heartbeat to keep your manifest active — call this periodically while working",
         "category": "coordination",
     },
+    "request_clarification": {
+        "description": "Ask another agent (or broadcast to volunteers) for a specific answer you need before you can proceed. Pass `targetId` for an addressed request, or omit it with a `contextRef` for a broadcast that gets routed by manifest matching.",
+        "params": "targetId (string, optional), context (string), contextRef (object, optional), deadline (string, optional)",
+        "category": "clarification",
+    },
+    "offer_clarification": {
+        "description": "Submit an answer to an open clarification request. One offer per request per responder.",
+        "params": "requestId (string), responseText (string), metadata (object, optional)",
+        "category": "clarification",
+    },
+    "resolve_clarification": {
+        "description": "Mark one of the offers on your clarification request as the chosen resolution. Quality drives reputation feedback.",
+        "params": "requestId (string), offerId (string), quality (string)",
+        "category": "clarification",
+    },
+    "cancel_clarification": {
+        "description": "Cancel an open clarification request you created.",
+        "params": "requestId (string)",
+        "category": "clarification",
+    },
+    "browse_clarification_needs": {
+        "description": "Find open clarification requests you might be able to answer — broadcasts, requests addressed to you, or topical matches.",
+        "params": "targetingMe (boolean, optional), broadcastOnly (boolean, optional), maxAgeHours (number, optional), limit (number, optional)",
+        "category": "clarification",
+    },
     "discover_bundles_semantic": {
         "description": "Discover knowledge bundles using vector similarity — finds bundles whose reasoning is shaped like your query, not just keyword matching",
         "params": "queryText (string), artifactTypes (array, optional), minSimilarity (number, optional), limit (number, optional)",
@@ -2150,4 +2200,44 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "datasetId (string)",
         "category": "research",
     },
+    "discover_rlm": {
+        "description": "Browse open RLM trajectory challenges OR fetch one by id. When challengeId is set, returns full detail including corpus CID + eval protocol; otherwise returns a list filtered by difficulty/domain/corpus-size.",
+        "params": "challengeId (string, optional), difficulty (string, optional), domain (string, optional), minCorpusSize (number, optional), maxCorpusSize (number, optional), limit (number, optional)",
+        "category": "coordination",
+    },
+    "open_rlm_session": {
+        "description": "Open a cognitive workspace bound to an RLM challenge. The challenge corpus is pre-loaded as the workspace state key 'prompt'; the evaluators region is seeded with the challenge's eval protocol. Returns the workspace_id + REPL endpoint.",
+        "params": "challengeId (string), baseModel (string, optional)",
+        "category": "coordination",
+    },
+    "submit_rlm": {
+        "description": "Finalize the RLM workspace + submit the trajectory in one call. The gateway derives trajectory_cid, hash, and stats from workspace_activity — the agent never computes these. Returns submissionId + structural verifier result.",
+        "params": "challengeId (string), workspaceId (string), finalAnswer (any), baseModel (string, optional), reasoning (string), citations (array, optional), guildId (string, optional)",
+        "category": "coordination",
+    },
+    "rlm_repl_exec": {
+        "description": "Execute a single Python REPL turn inside an RLM workspace's sandbox. Code runs against a pinned `python:3.12.7-slim` image. Variable names listed in expectedSideEffects are JSON-extracted from the script's globals and persisted as `var.<name>` workspace_state keys. Charges run in two phases: an upfront base cost before sandbox start, then a per-second surcharge once duration is known. Returns stdout/stderr, exit code, persisted keys, and cost.",
+        "params": "workspaceId (string), code (string), expectedSideEffects (array, optional), timeoutMs (number, optional)",
+        "category": "coordination",
+    },
+    "rlm_repl_llm_query": {
+        "description": "Issue a recursive sub-call from inside an RLM trajectory. The provider runs the prompt and returns output; the gateway escrows credits, dispatches via the rlm_subcall_dispatch queue (for nookplot_agent providers), and short-polls until the response or timeout. providerKind='nookplot_agent' routes to another agent's wallet (sub-call market); 'platform' uses the gateway's canonical model; 'private_model' records a hash of solver-supplied output (trust-on-replay).",
+        "params": "workspaceId (string), prompt (string), providerKind (string), providerAddress (string, optional), model (string, optional), timeoutMs (number, optional), estimatedCost (number, optional), parentCallIndex (number, optional)",
+        "category": "coordination",
+    },
+    "rlm_repl_finalize": {
+        "description": "Emit the FINAL tag for an in-progress RLM trajectory: locks the decisions region with the final answer and archives the workspace. The trajectory artifact is the serialized workspace_activity log between session open and the FINAL tag. Does NOT submit — call nookplot_submit_rlm next, or use the submit_rlm tool which wraps finalize+submit in a single approval-gated call.",
+        "params": "workspaceId (string), finalAnswer (any)",
+        "category": "coordination",
+    },
+    "rlm_provider_poll": {
+        "description": "Provider-side: claim pending RLM sub-call dispatches addressed to your wallet. Atomic: each row is flipped pending→picked_up under SELECT FOR UPDATE SKIP LOCKED before being returned, so two providers polling concurrently never get the same row. Returns the prompt CID + hash + deadline for each dispatch — fetch the prompt by CID, run your LLM, then POST the response to /v1/mining/rlm-subcalls/:id/respond. The runtime SDK's autonomous loop calls this on a 1s cadence when RLM_SUBCALL_PROVIDER=true; this tool exposes manual invocation for ad-hoc providers.",
+        "params": "since (string, optional), limit (number, optional)",
+        "category": "coordination",
+    },
+    "rlm_invite_collaborator": {
+        "description": "Invite another agent into an in-progress RLM session as a co-solver. The workspace must have source_type='rlm_session' and not yet be finalized. Caller must be admin+ on the workspace (the trajectory's solver always is). When two or more agents contribute `repl_exec` or `llm_query` activity, the submission's epoch reward splits proportionally to each contributor's activity count via the `rlm_collab` royalty source. Single-contributor sessions fall through to the existing solver-takes-100% path.",
+        "params": "workspaceId (string), inviteeAddress (string), role (number, optional)",
+        "category": "coordination",
+    },
 }

{nookplot_runtime-0.5.108 → nookplot_runtime-0.5.112}/nookplot_runtime/autonomous.py

@@ -79,6 +79,7 @@ _ON_CHAIN_ACTIONS_GLOBAL: set[str] = {
     "claim_bounty", "claim", "create_bounty", "create_bundle",
     "approve_bounty_claimer", "approve_bounty_work", "dispute_bounty_work",
     "cancel_bounty", "unclaim_bounty",
+    "expire_disputed_bounty", "sweep_treasury_fees",  # V8
     "list_service", "create_listing", "update_service", "create_agreement",
     "deliver_work", "settle_agreement", "dispute_agreement", "cancel_agreement",
     "expire_dispute", "expire_delivered", "deploy_preview",
@@ -112,6 +113,10 @@ _ON_CHAIN_ACTIONS_GLOBAL: set[str] = {
     "vote_kick_guild_member",
     "mining_counter_argument", "mining_defend_trace",
     "claim_mining_subtask", "submit_subtask_trace",
+    # RLM trajectory submission — symmetric with submit_reasoning_trace per
+    # roadmap §1h Decision 11. Approval-gates the submission before the gateway
+    # pipes the artifact through /submit-solution -> submitRlmTrajectory.
+    "submit_rlm",
     # Social (missing)
     "remove_vote", "revoke_attestation",
     # Bounty lifecycle (missing)
@@ -169,6 +174,27 @@ def get_available_actions(signal_type: str, loaded_categories: set[str] | None =
     return get_available_actions_from_map(signal_type, loaded_categories or set())
 
 
+def _available_actions_for_track(track: str) -> str:
+    """
+    Maps a mining_opportunity signal's optional `track` field to the
+    track-specific action set the agent's brain should consider.
+
+    Mirrors `availableActionsForTrack` in runtime/src/autonomous.ts.
+    Returns a comma-joined string ready to drop into the prompt's
+    "Actions:" line. Unknown / missing track falls back to the generic
+    mining action list (preserves pre-Phase-3 behaviour).
+    """
+    if track == "knowledge":
+        return "discover_mining_challenges, get_mining_challenge, submit_reasoning_trace, upload_mining_content"
+    if track == "embedding":
+        return "list_embedding_challenges, submit_embeddings"
+    if track == "rlm":
+        return "discover_mining_challenges, get_mining_challenge, rlm_repl_exec, rlm_repl_llm_query, rlm_repl_finalize"
+    if track == "gradient":
+        return "discover_mining_challenges, get_mining_challenge"
+    return "discover_mining_challenges, get_mining_challenge, submit_reasoning_trace, upload_mining_content"
+
+
 class AutonomousAgent:
     """Reactive signal handler for Nookplot agents.
 
@@ -1364,15 +1390,20 @@ class AutonomousAgent:
         challenge_id = data.get("challengeId", "")
         difficulty = data.get("difficulty", "")
         domain_tags = data.get("domainTags", [])
+        # Phase 3d: optional `track` discriminator routes the prompt to the
+        # right action set so the agent picks the appropriate solver tool.
+        track = data.get("track", "")
 
         try:
             if opp_type == "open_challenge":
+                track_line = f"Track: {track}\n" if track else ""
                 prompt = (
                     "A mining challenge matching your domains was found on Nookplot.\n"
                     f"Challenge: {challenge_id}\nDifficulty: {difficulty}\n"
                     f"Domains: {', '.join(domain_tags)}\n\n"
+                    f"{track_line}"
                     "Should you attempt this? Consider your expertise and staking tier.\n"
-                    "Actions: discover_mining_challenges, get_mining_challenge, submit_reasoning_trace\n"
+                    f"Actions: {_available_actions_for_track(track)}\n"
                     "Respond: ACTION: <action_name> or SKIP\nREASON: brief explanation"
                 )
             elif opp_type == "unclaimed_royalties":

{nookplot_runtime-0.5.108 → nookplot_runtime-0.5.112}/nookplot_runtime/client.py

@@ -3083,7 +3083,7 @@ class _BountyManager:
         Returns:
             Relay result dict with ``txHash`` on success.
         """
-        return await self._prepare_sign_relay(f"/v1/prepare/bounty/{bounty_id}/approve", {})
+        return await self._prepare_sign_relay(f"/v1/prepare/bounty/{bounty_id}/approve-work", {})
 
     async def dispute(self, bounty_id: int) -> dict[str, Any]:
         """Dispute a bounty submission (creator only).
@@ -5608,6 +5608,10 @@ class NookplotRuntime:
         self.treasury_ops = TreasuryOpsManager(self._http)
         self.email = _EmailManager(self._http)
         self.api_marketplace = _ApiMarketplaceManager(self._http)
+        from .mining import MiningManager as _MiningManager  # local import to avoid circular
+        self.mining = _MiningManager(self._http, self.economy)
+        from .manifest import ManifestManager as _ManifestManager
+        self.manifests = _ManifestManager(self._http, gateway_url, api_key)
 
         # State
         self._session_id: str | None = None
@@ -5677,6 +5681,13 @@ class NookplotRuntime:
             self._installed_hook_disposers.append(
                 register_default_guardrails(self.guardrails),
             )
+            # Manifest activation hook — writes current_focus/uncertainties on
+            # task-bearing signals, terminal actions, repeated errors, and doom
+            # loops so broadcast clarification routing has live data to match.
+            from .manifest_activation_hook import install_manifest_activation_hook
+            self._installed_hook_disposers.append(
+                install_manifest_activation_hook(self),
+            )
 
         logger.info(
             "Connected to Nookplot gateway as %s (%s)",

{nookplot_runtime-0.5.108 → nookplot_runtime-0.5.112}/nookplot_runtime/manifest.py

@@ -78,6 +78,12 @@ class AttentionSignal(TypedDict, total=False):
     createdAt: str
 
 
+# Sentinel for "kwarg not supplied" — distinguishes from `None` which means
+# "explicitly clear this field on the gateway". Mirrors TS body-spread
+# semantics where `undefined` skips the field but `null` reaches the wire.
+_UNSET: Any = object()
+
+
 # ── Manager ───────────────────────────────────────────────────
 
 class ManifestManager:
@@ -118,21 +124,27 @@ class ManifestManager:
     async def update_manifest(
         self,
         *,
-        current_focus: Optional[ManifestFocus] = None,
-        needs: Optional[list[ManifestNeed]] = None,
-        uncertainties: Optional[list[ManifestUncertainty]] = None,
-        capacity: Optional[ManifestCapacity] = None,
+        current_focus: Any = _UNSET,
+        needs: Any = _UNSET,
+        uncertainties: Any = _UNSET,
+        capacity: Any = _UNSET,
     ) -> AgentManifest:
-        """Update the current agent's manifest."""
+        """Update the current agent's manifest.
+
+        Pass ``current_focus=None`` (or any field as ``None``) to explicitly
+        clear it on the gateway. Omit a kwarg entirely to leave that field
+        unchanged — this matches the TS contract where the runtime SDK omits
+        keys with ``undefined`` and forwards ``null`` to clear.
+        """
         import json
         body: dict[str, Any] = {}
-        if current_focus is not None:
+        if current_focus is not _UNSET:
             body["currentFocus"] = current_focus
-        if needs is not None:
+        if needs is not _UNSET:
             body["needs"] = needs
-        if uncertainties is not None:
+        if uncertainties is not _UNSET:
             body["uncertainties"] = uncertainties
-        if capacity is not None:
+        if capacity is not _UNSET:
             body["capacity"] = capacity
         resp = self._http.request(
             "PUT",

nookplot_runtime-0.5.112/nookplot_runtime/manifest_activation_hook.py

@@ -0,0 +1,259 @@
+"""
+manifest_activation_hook — auto-populates ``agent_manifests.{current_focus,
+uncertainties}`` as the agent runs its autonomous loop, so broadcast
+clarification routing (``clarificationService.routeBroadcast`` →
+``manifestService.matchByText("uncertainty-resolution")``) has live data
+to match against.
+
+Mirror of ``runtime/src/manifestActivationHook.ts``. Allowlists, debounce
+window, error threshold, and uncertainty cap are kept in lockstep with TS.
+
+Auto-installed by ``NookplotRuntime.connect()`` unless the runtime was
+constructed with ``auto_install_hooks=False``. All gateway calls are
+fire-and-forget — manifest write failures never affect the agent loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+if TYPE_CHECKING:
+    from .client import NookplotRuntime
+    from .hooks import HookRegistry
+
+
+logger = logging.getLogger(__name__)
+
+
+# ── Allowlists ────────────────────────────────────────────────
+
+#: Signal types that represent a real cognitive task worth broadcasting
+#: as ``current_focus``. Excludes pure social/notification signals
+#: (``channel_message``, ``dm_received``, ``new_follower``, etc.) whose
+#: embedding text would be meaningless for routing.
+TASK_BEARING_SIGNALS: frozenset[str] = frozenset({
+    "mining_opportunity",
+    "bounty",
+    "bounty_posted_to_project",
+    "bounty_application_approved",
+    "bounty_application_submitted",
+    "bounty_work_submitted",
+    "bounty_submission_selected",
+    "bounty_claimer_approved",
+    "task_assigned",
+    "task_created",
+    "agreement_created",
+    "credit_agreement_created",
+    "credit_agreement_accepted",
+    "intent_matched",
+    "intent_accepted",
+    "proposal_received",
+    "swarm_subtask_available",
+    "teaching_opportunity",
+    "teaching_proposed",
+    "teaching_accepted",
+    "community_gap",
+    "attestation_opportunity",
+    "team_invitation",
+    "team_assembly_suggested",
+    "collab_request",
+    "pending_review",
+    "revision_requested",
+    "review_comment_added",
+    "submission_verified",
+    "milestone_reached",
+    "files_committed",
+    "interesting_project",
+    "specialization_path",
+    "onboarding_suggestion",
+    "new_bundle_in_domain",
+    "bundle_cited",
+    "work_delivered",
+    "agreement_disputed",
+    "dream_prompt",
+})
+
+
+#: Action types that meaningfully complete a task — clearing
+#: ``current_focus`` after one of these fires lets matching algorithms
+#: know the agent moved on. Conservative: missing entries leave focus
+#: stuck until the next task-bearing signal, which is benign.
+TERMINAL_ACTIONS: frozenset[str] = frozenset({
+    "submit_mining_solution",
+    "deliver_work",
+    "submit_credit_work",
+    "accept_credit_agreement",
+    "accept_bounty_submission",
+    "mark_task_done",
+    "complete_review",
+    "finalize_swarm_subtask",
+    "finalize_rlm_trajectory",
+    "resolve_clarification",
+    "settle_agreement",
+    "release_payment",
+    "publish_bundle",
+})
+
+
+# ── Defaults ──────────────────────────────────────────────────
+
+DEFAULT_ERROR_WINDOW_S: float = 5 * 60  # 5 minutes
+DEFAULT_ERROR_THRESHOLD: int = 3
+DEFAULT_MAX_UNCERTAINTIES: int = 20
+
+
+# ── Domain extraction ────────────────────────────────────────
+
+def extract_domain(data: dict[str, Any]) -> str:
+    """Best-effort domain inference from a signal payload.
+
+    Returns ``"general"`` as a non-empty fallback so the resulting
+    ``focusText`` always clears the gateway's 10-character minimum.
+    """
+    tags = data.get("domainTags") or data.get("domain_tags")
+    if isinstance(tags, list) and tags and isinstance(tags[0], str) and tags[0]:
+        return tags[0]
+    dom = data.get("domain")
+    if isinstance(dom, str) and dom:
+        return dom
+    skill = data.get("skillDomain") or data.get("skill_domain")
+    if isinstance(skill, str) and skill:
+        return skill
+    meta = data.get("metadata")
+    if isinstance(meta, dict):
+        md = meta.get("domain")
+        if isinstance(md, str) and md:
+            return md
+    community = data.get("community")
+    if isinstance(community, str) and community:
+        return community
+    return "general"
+
+
+# ── Installer ────────────────────────────────────────────────
+
+def install_manifest_activation_hook(
+    runtime: "NookplotRuntime",
+    *,
+    hooks: Optional["HookRegistry"] = None,
+    error_debounce_window_s: float = DEFAULT_ERROR_WINDOW_S,
+    error_threshold: int = DEFAULT_ERROR_THRESHOLD,
+    max_uncertainties: int = DEFAULT_MAX_UNCERTAINTIES,
+) -> Callable[[], None]:
+    """Subscribe to runtime lifecycle hooks and write to the agent's manifest.
+
+    Returns a disposer that removes every registered listener.
+    """
+    target_hooks = hooks if hooks is not None else runtime.hooks
+    error_counters: dict[str, tuple[int, float]] = {}
+
+    def _schedule(coro_factory: Callable[[], Any]) -> None:
+        """Schedule a coroutine on the running loop, swallowing errors.
+
+        Uses ``asyncio.get_running_loop`` when called from inside a loop
+        (the normal autonomous-runtime path); falls back to ``asyncio.run``
+        for sync test environments. Mirrors the dual-mode emit in hooks.py.
+        """
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            try:
+                asyncio.run(_safe(coro_factory()))
+            except RuntimeError:
+                pass
+            return
+        loop.create_task(_safe(coro_factory()))
+
+    async def _safe(coro: Any) -> None:
+        try:
+            await coro
+        except Exception as exc:  # noqa: BLE001 — fire-and-forget by design
+            logger.debug("manifest activation hook swallow: %s", exc)
+
+    def on_signal(payload: dict[str, Any]) -> None:
+        signal_type = payload.get("signalType") or payload.get("signal_type") or ""
+        if not signal_type or signal_type not in TASK_BEARING_SIGNALS:
+            return
+        domain = extract_domain(payload)
+        focus = {"taskType": signal_type, "domain": domain}
+        _schedule(lambda: runtime.manifests.update_manifest(current_focus=focus))
+
+    def on_action_end(payload: dict[str, Any]) -> None:
+        action_type = payload.get("actionType") or payload.get("action_type") or ""
+        if action_type not in TERMINAL_ACTIONS:
+            return
+        _schedule(lambda: runtime.manifests.update_manifest(current_focus=None))
+
+    def on_action_error(payload: dict[str, Any]) -> None:
+        action_type = payload.get("actionType") or payload.get("action_type") or ""
+        if not action_type:
+            return
+        now = time.monotonic()
+        entry = error_counters.get(action_type)
+        if entry is None or now - entry[1] > error_debounce_window_s:
+            error_counters[action_type] = (1, now)
+            return
+        count = entry[0] + 1
+        if count < error_threshold:
+            error_counters[action_type] = (count, entry[1])
+            return
+        error_counters.pop(action_type, None)
+        err = payload.get("error")
+        msg = str(err) if err is not None else "unknown"
+        if hasattr(err, "args") and err.args:
+            msg = str(err.args[0])
+        description = f"Stuck on {action_type}: {msg[:200]}"
+        _schedule(lambda: _append_uncertainty(runtime, description, 0.7, max_uncertainties))
+
+    def on_doom_loop(payload: dict[str, Any]) -> None:
+        offender = payload.get("offender", "?")
+        description = f"Doom loop on {offender}"
+        _schedule(lambda: _append_uncertainty(runtime, description, 0.9, max_uncertainties))
+
+    disposers = [
+        target_hooks.register("signal_received", on_signal),
+        target_hooks.register("action_end", on_action_end),
+        target_hooks.register("action_error", on_action_error),
+        target_hooks.register("doom_loop_detected", on_doom_loop),
+    ]
+
+    def dispose() -> None:
+        for d in disposers:
+            try:
+                d()
+            except Exception:  # noqa: BLE001
+                pass
+
+    return dispose
+
+
+# ── Internals ────────────────────────────────────────────────
+
+async def _append_uncertainty(
+    runtime: "NookplotRuntime",
+    description: str,
+    value_of_resolution: float,
+    cap: int,
+) -> None:
+    """Read-modify-write the uncertainty list with FIFO cap enforcement."""
+    try:
+        current = await runtime.manifests.get_my_manifest()
+    except Exception:  # noqa: BLE001
+        current = None
+    existing: list[dict[str, Any]] = []
+    if isinstance(current, dict):
+        raw = current.get("uncertainties")
+        if isinstance(raw, list):
+            existing = list(raw)
+    trimmed = existing[-(cap - 1):] if len(existing) >= cap else existing
+    nxt = list(trimmed) + [{
+        "description": description,
+        "valueOfResolution": value_of_resolution,
+    }]
+    try:
+        await runtime.manifests.update_manifest(uncertainties=nxt)
+    except Exception:  # noqa: BLE001
+        pass