runtime-queue

Your objective is to process .cocoplus/v2-runtime-requests.jsonl as a durable handoff queue between fast hooks and feature-owned skills.

Hooks must stay fast, deterministic, and side-effect constrained. When a hook observes work that belongs to a feature skill, it appends a request envelope to the queue and returns. The owning skill later claims, executes, and settles that request.

Request Envelope

Each queue line is one JSON object. Required fields:

• skill: owning skill contract, such as cocometer/meter-reconcile
• requested_at: ISO timestamp from the hook
• source: hook or skill that wrote the request
• idempotency_key: deterministic key for the semantic work item

Recommended fields:

• operation: skill-specific verb
• session_id, run_id, stage_id, or subagent_id when available
• input, input_data, or explicit path fields
• out or output_path when the skill writes an artifact
• priority: inline-followup, background, or maintenance

Never include raw secrets, full transcripts, or large payloads. Prefer paths and stable identifiers.

Claim Protocol

Before executing a request, write a claim record to .cocoplus/v2-runtime-claims.jsonl:

{
  "idempotency_key": "<key>",
  "skill": "<skill>",
  "claim_token": "<session-or-process-token>",
  "claimed_at": "<ISO timestamp>",
  "state": "claimed"
}

If a completed settlement already exists for the same idempotency_key, do not execute the request again. If a stale claim exists without settlement, a later worker may supersede it by writing a new claim with state: "superseded" for the old claim_token.

Settlement States

Every claimed request must settle in .cocoplus/v2-runtime-settlements.jsonl with one of:

• claimed
• completed
• failed
• superseded

The compact state vocabulary is claimed|completed|failed|superseded.

Settlement fields:

• idempotency_key
• skill
• claim_token
• state
• settled_at
• artifact or output_path when produced
• error only for failed

Execution Rules

• Execute the owning skill contract directly.
• Do not execute JavaScript helpers.
• Do not treat queue append as completion.
• Do not delete queue lines; append settlements instead.
• Do not silently skip failed requests. Record failed with a concise reason.
• Do not weaken active run policy while processing a queued request.

Exit Criteria

• Every processed request has a stable idempotency_key.
• Every execution writes a claim before doing feature work.
• Every claim settles as completed, failed, or superseded.
• Replayed queue lines do not duplicate artifacts or metrics.
• No non-console runtime script is invoked.

Anti-Rationalization

Shortcut / Temptation	Why It Fails
Treat the skill as complete because the file exists	Skill contracts must describe observable behavior and verification, not just command names.
Skip artifact and safety checks for a small command	Small commands still mutate state or guide execution; preserve the same gates.