syntaur 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {

package/platforms/claude-code/.claude-plugin/plugin.json

@@ -25,6 +25,10 @@
     "./skills/add-memory",
     "./skills/list-assignments",
     "./skills/log-progress",
-    "./skills/set-workspace"
+    "./skills/set-workspace",
+    "./skills/claim-resource",
+    "./skills/release-resource",
+    "./skills/extend-resource",
+    "./skills/list-resources"
   ]
 }

package/platforms/claude-code/skills/claim-resource/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: claim-resource
+description: Claim an idle member of a Syntaur leases inventory (dev env, test DB, API key, named lock, etc.) for the current assignment session. Triggers on "/claim-resource", "claim a dev env", "lease an environment", "grab a test DB", "claim a slot", or when the user wants to coordinate access to a shared finite resource.
+license: MIT
+---
+
+# Claim Resource
+
+Claim an idle member of a Syntaur leases inventory and persist the lease into `.syntaur/context.json`. The claimed member's connection metadata (URL, ssh string, port, etc.) is printed back so the agent can use it immediately.
+
+The claim is **fail-fast** — if no member is idle, the command exits non-zero. If a long-running blocking claim is wanted, the agent retries externally with backoff.
+
+## Usage
+
+User arguments: `$ARGUMENTS`
+
+- `<inventory_slug>` (required) — which inventory to claim from
+- `--ttl <duration>` (optional) — lease TTL, e.g. `15m`, `2h`. Defaults to the inventory's `default_ttl`.
+- `--for <tag>` (optional) — free-form requester tag (defaults to the active assignment slug if omitted)
+
+Examples:
+- `/claim-resource dev-envs`
+- `/claim-resource dev-envs --ttl 1h`
+- `/claim-resource prod-migration-lock --ttl 5m --for "migration-2026-05-12"`
+
+## Workflow
+
+### Step 1: Parse arguments
+
+Extract `<inventory_slug>` (required, first positional), plus optional `--ttl <duration>` and `--for <tag>`.
+
+### Step 2: Pre-check assignment context
+
+Read `.syntaur/context.json` from the current working directory. If the file is missing, OR has neither `sessionId` nor any of `projectSlug`/`assignmentSlug`/`assignmentDir`, abort with:
+
+> "No active Syntaur context in this workspace. Grab an assignment first (`/grab-assignment <project> <slug>`) or restart the session so the SessionStart hook can populate `.syntaur/context.json`."
+
+This guard exists because writing a leases-only context file would trip `syntaur doctor`'s workspace check.
+
+If `--for` was not provided, derive its value from the context: prefer `assignmentSlug` if present, otherwise `sessionId`.
+
+### Step 3: Run the claim CLI
+
+```bash
+syntaur lease claim "$INVENTORY_SLUG" --json \
+  ${TTL:+--ttl "$TTL"} \
+  --for "$TAG"
+```
+
+(Use `dangerouslyDisableSandbox: true` for the Bash call — the CLI writes to `~/.syntaur/syntaur.db`.)
+
+Possible non-zero exits and how to surface them to the user:
+
+| stderr fragment | meaning | how to respond |
+|---|---|---|
+| `no idle members in '<slug>'` | `NoIdleMemberError` — pool exhausted | Tell user; suggest waiting / retrying later or asking a human to add capacity. |
+| `contention timeout on '<slug>'; retry` | `LeaseContentionError` — busy timeout | Retry once after ~1s. If it fails again, surface the error. |
+| `inventory '<slug>' not found` | typo or inventory doesn't exist | Tell user; list with `syntaur lease list`. |
+
+### Step 4: Parse the claim result
+
+Parse the stdout JSON: `{ lease_id, inventory_slug, member_id, member_gen, granted_at, expires_at, metadata }`.
+
+### Step 5: Persist the lease in `.syntaur/context.json`
+
+Append the lease record to the `leases: []` array in `.syntaur/context.json` (creating the array if absent). Atomic write via `jq` + rename:
+
+```bash
+mkdir -p .syntaur
+jq --arg lid "$LEASE_ID" \
+   --arg slug "$INVENTORY_SLUG" \
+   --arg mid "$MEMBER_ID" \
+   --arg exp "$EXPIRES_AT" \
+   --arg claimed "$GRANTED_AT" \
+   --argjson meta "$METADATA_JSON" \
+   '.leases = ((.leases // []) | map(select(.lease_id != $lid)) +
+    [{ lease_id: $lid, inventory_slug: $slug, member_id: $mid,
+       expires_at: $exp, metadata: $meta, claimed_at: $claimed }])' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+### Step 6: Report back
+
+Tell the user:
+- Which member was claimed (`<inventory>/<member_id>`) and the lease id.
+- When the lease expires (`expires_at`).
+- The connection metadata, if any (URL, port, credentials reference, etc.) — print as a code block so the agent (or human) can use it.
+- Reminder: leases do NOT auto-release on session end or assignment completion in v1. Call `/release-resource <lease_id>` when finished, or let the TTL expire and `gc` reclaim.

package/platforms/claude-code/skills/extend-resource/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: extend-resource
+description: Extend the TTL on a Syntaur resource lease previously claimed via /claim-resource. Triggers on "/extend-resource", "extend my lease", "renew the lease", "bump the TTL", "keep this resource a bit longer", or when the user wants more time on an active claim.
+license: MIT
+---
+
+# Extend Resource
+
+Extend an active Syntaur resource lease by pushing its `expires_at` forward. On success, also updates the lease's `expires_at` in `.syntaur/context.json` so the local record stays accurate. If the lease has already gone stale (expired, revoked, or member generation advanced), drops it from `.syntaur/context.json` and reports.
+
+## Usage
+
+User arguments: `$ARGUMENTS`
+
+- `<lease_id>` (required) — lease to extend
+- `--ttl <duration>` (required) — new TTL from now (e.g. `15m`, `2h`)
+
+Examples:
+- `/extend-resource cf3bd0a6-ba38-4a8c-a882-bdba9cabad80 --ttl 1h`
+- `/extend-resource 6d4a... --ttl 30m`
+
+## Workflow
+
+### Step 1: Parse arguments
+
+Extract `<lease_id>` (first positional) and `--ttl <duration>` (required). If either is missing, abort with a usage message and a hint to call `/list-resources` to see active leases.
+
+### Step 2: Pre-check assignment context
+
+Read `.syntaur/context.json` from the current working directory. If the file is missing, OR has neither `sessionId` nor any of `projectSlug`/`assignmentSlug`/`assignmentDir`, abort with:
+
+> "No active Syntaur context in this workspace. Grab an assignment first (`/grab-assignment <project> <slug>`) or restart the session so the SessionStart hook can populate `.syntaur/context.json`."
+
+This guard mirrors `/claim-resource` and `/release-resource` — writing a leases-only context file would trip `syntaur doctor`'s workspace check.
+
+### Step 3: Run the extend CLI
+
+```bash
+syntaur lease extend "$LEASE_ID" --ttl "$TTL"
+```
+
+(Use `dangerouslyDisableSandbox: true` — the CLI writes to `~/.syntaur/syntaur.db`.)
+
+Possible non-zero exits and how to surface them:
+
+| stderr fragment | meaning | how to respond |
+|---|---|---|
+| `cannot be extended (expired, revoked, or member generation advanced)` | `StaleLeaseError` — lease is no longer the holder. | Drop the entry from `.syntaur/context.json` (Step 5) and tell user the lease is dead — they'll need to `/claim-resource` again. |
+| `contention timeout; retry` | `LeaseContentionError` — busy timeout. | Retry once after ~1s. If it fails again, surface to user. |
+| `--ttl must be positive` | Bad duration. | Tell user to pass a positive duration like `15m`, `2h`. |
+
+### Step 4: Parse the new expiry from stdout
+
+On exit 0, stdout looks like: `Extended lease <id> (new expires_at=<iso>).`
+
+Capture the `new_expires_at` value (the ISO timestamp inside the parens).
+
+### Step 5a: On success, update `.syntaur/context.json`
+
+Find the matching entry in `leases[]` by `lease_id` and rewrite its `expires_at`:
+
+```bash
+jq --arg lid "$LEASE_ID" --arg exp "$NEW_EXPIRES_AT" \
+   '.leases = ((.leases // []) | map(
+      if .lease_id == $lid then .expires_at = $exp else . end
+    ))' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+### Step 5b: On `StaleLeaseError`, drop the entry instead
+
+```bash
+jq --arg lid "$LEASE_ID" \
+   '.leases = ((.leases // []) | map(select(.lease_id != $lid)))' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+### Step 6: Report back
+
+- On success: `Extended <lease_id> — new expires_at=<iso>.` Also surface the original member id (look it up in the context entry before mutation) so the user knows which resource was extended.
+- On stale: `Lease <lease_id> is no longer active — removed from context. Run /claim-resource to grab a new one.`

package/platforms/claude-code/skills/list-resources/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: list-resources
+description: List the Syntaur resource leases held by the current session, plus the workspace-wide overview of inventories and active leases. Triggers on "/list-resources", "what leases do I have", "show my leases", "list my resources", "what resources am I holding", or when the user wants both a session-local and system-wide view of leased resources.
+license: MIT
+---
+
+# List Resources
+
+Print two views in one call:
+
+1. **Your active leases** — the `leases[]` array from `.syntaur/context.json` (this session's claims).
+2. **All active leases in this workspace** — output of `syntaur lease list`, which shows every inventory plus its idle/leased counts.
+
+This is the cheap "what am I holding, and what's out there?" lookup before deciding to extend, release, or grab another resource.
+
+## Usage
+
+User arguments: `$ARGUMENTS` (no arguments accepted in v1).
+
+Examples:
+- `/list-resources`
+
+## Workflow
+
+### Step 1: Read this session's leases
+
+```bash
+jq -r '.leases // []' .syntaur/context.json 2>/dev/null
+```
+
+(No `dangerouslyDisableSandbox` needed — read-only.)
+
+If `.syntaur/context.json` is missing or has no `leases` array, treat it as empty. Do NOT abort — listing is informational; the absence of session context is itself a useful signal.
+
+For each entry, capture: `lease_id`, `inventory_slug`, `member_id`, `expires_at`, `claimed_at`, and any `metadata` (e.g. connection URL).
+
+### Step 2: Run the system-wide overview
+
+```bash
+syntaur lease list
+```
+
+(Use `dangerouslyDisableSandbox: true` — the CLI reads `~/.syntaur/syntaur.db`.)
+
+Capture stdout. If the CLI exits non-zero, surface the error message but still print whatever Step 1 produced.
+
+### Step 3: Report back
+
+Print two sections:
+
+**Your active leases (from `.syntaur/context.json`):**
+
+If the array is empty:
+> "No leases held by this session."
+
+Otherwise, one block per lease:
+```
+<lease_id>
+  inventory: <inventory_slug>/<member_id>
+  expires:   <expires_at>
+  claimed:   <claimed_at>
+  metadata:  <metadata JSON, if any>
+```
+
+**All inventories in this workspace (from `syntaur lease list`):**
+
+Paste the CLI output verbatim (one row per inventory with kind/idle/leased counts).
+
+### Step 4: Suggest next actions if any leases are nearing expiry
+
+If any session-local lease's `expires_at` is within the next 5 minutes, append:
+> "Note: lease `<id>` expires at `<iso>` (within 5 minutes). Run `/extend-resource <id> --ttl <duration>` to keep it."
+
+This is informational only — don't extend automatically.

package/platforms/claude-code/skills/release-resource/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: release-resource
+description: Release a Syntaur resource lease previously claimed via /claim-resource, freeing the member for the next claimant. Triggers on "/release-resource", "release this dev env", "drop the lease", "release my slot", "release all leases", or when the user is done with a claimed resource.
+license: MIT
+---
+
+# Release Resource
+
+Release one or more active resource leases, removing them from `.syntaur/context.json` and freeing their members for the next claimant.
+
+## Usage
+
+User arguments: `$ARGUMENTS`
+
+- `<lease_id>` — release a specific lease by id
+- `--all` — release every active lease recorded in `.syntaur/context.json`
+
+Examples:
+- `/release-resource cf3bd0a6-ba38-4a8c-a882-bdba9cabad80`
+- `/release-resource --all`
+
+## Workflow
+
+### Step 1: Parse arguments
+
+If `--all` is passed, build the list of `lease_id`s from `.syntaur/context.json`'s `leases: []` array. Otherwise the first positional argument is the single `lease_id` to release.
+
+If there is no `lease_id` and `--all` was not passed, abort with: "Specify `<lease_id>` or use `--all`. Active leases: $(jq -r '.leases[]?.lease_id' .syntaur/context.json 2>/dev/null || echo 'none')."
+
+### Step 2: Release each lease
+
+For each `lease_id`:
+
+```bash
+syntaur lease release "$LEASE_ID"
+```
+
+(Use `dangerouslyDisableSandbox: true` since the CLI writes to `~/.syntaur/syntaur.db`.)
+
+Outcomes:
+
+| Result | Meaning | What to do |
+|---|---|---|
+| Exit 0 with `Released lease <id>.` | Normal release. | Continue. |
+| Exit 1 with `lease ... is no longer active` | Stale lease (already expired/revoked). The slot has already been freed. | Still remove from `.syntaur/context.json` — the row is dead either way. Note the staleness in the final summary. |
+| Exit 1 with `contention timeout; retry` | `LeaseContentionError`. | Retry once after ~1s; if it fails again, surface to the user. |
+
+### Step 3: Remove the entry from `.syntaur/context.json`
+
+Whether the CLI succeeded OR returned a stale-lease error, drop the matching record from `.syntaur/context.json` (stale leases are dead — keeping them in context is misleading):
+
+```bash
+jq --arg lid "$LEASE_ID" \
+   '.leases = ((.leases // []) | map(select(.lease_id != $lid)))' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+### Step 4: Report back
+
+For a single release: `Released <lease_id> (<inventory>/<member_id>).` or `Lease <id> was already stale; removed from context.`
+
+For `--all`: print one line per lease, then a summary count: `Released N lease(s), M already stale.`
+
+If no leases were recorded in context, say so explicitly.

package/platforms/claude-code/skills/syntaur-protocol/SKILL.md

@@ -60,6 +60,7 @@ If `.syntaur/context.json` exists in the current working directory, read it befo
 - `workspaceRoot` — absolute path to the code workspace
 - `sessionId` — real agent-runtime session id (never a synthesized UUID)
 - `transcriptPath` — absolute path to the agent's rollout/transcript file, if known
+- `leases` — array of active resource-lease records (managed by `/claim-resource` and `/release-resource`). Entry shape: `{ lease_id, inventory_slug, member_id, expires_at, metadata, claimed_at }`. Leases are NOT auto-released on session end or assignment completion in v1 — call `/release-resource` explicitly (or let the TTL expire).
 
 ## Required Reading Order
 

package/platforms/codex/skills/claim-resource/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: claim-resource
+description: Claim an idle member of a Syntaur leases inventory (dev env, test DB, API key, named lock, etc.) for the current assignment session. Triggers on "/claim-resource", "claim a dev env", "lease an environment", "grab a test DB", "claim a slot", or when the user wants to coordinate access to a shared finite resource.
+license: MIT
+---
+
+# Claim Resource
+
+Claim an idle member of a Syntaur leases inventory and persist the lease into `.syntaur/context.json`. The claimed member's connection metadata (URL, ssh string, port, etc.) is printed back so the agent can use it immediately.
+
+The claim is **fail-fast** — if no member is idle, the command exits non-zero. If a long-running blocking claim is wanted, the agent retries externally with backoff.
+
+## Usage
+
+User arguments: `$ARGUMENTS`
+
+- `<inventory_slug>` (required) — which inventory to claim from
+- `--ttl <duration>` (optional) — lease TTL, e.g. `15m`, `2h`. Defaults to the inventory's `default_ttl`.
+- `--for <tag>` (optional) — free-form requester tag (defaults to the active assignment slug if omitted)
+
+Examples:
+- `/claim-resource dev-envs`
+- `/claim-resource dev-envs --ttl 1h`
+- `/claim-resource prod-migration-lock --ttl 5m --for "migration-2026-05-12"`
+
+## Workflow
+
+### Step 1: Parse arguments
+
+Extract `<inventory_slug>` (required, first positional), plus optional `--ttl <duration>` and `--for <tag>`.
+
+### Step 2: Pre-check assignment context
+
+Read `.syntaur/context.json` from the current working directory. If the file is missing, OR has neither `sessionId` nor any of `projectSlug`/`assignmentSlug`/`assignmentDir`, abort with:
+
+> "No active Syntaur context in this workspace. Grab an assignment first (`/grab-assignment <project> <slug>`) or restart the session so the SessionStart hook can populate `.syntaur/context.json`."
+
+This guard exists because writing a leases-only context file would trip `syntaur doctor`'s workspace check.
+
+If `--for` was not provided, derive its value from the context: prefer `assignmentSlug` if present, otherwise `sessionId`.
+
+### Step 3: Run the claim CLI
+
+```bash
+syntaur lease claim "$INVENTORY_SLUG" --json \
+  ${TTL:+--ttl "$TTL"} \
+  --for "$TAG"
+```
+
+(Use `dangerouslyDisableSandbox: true` for the Bash call — the CLI writes to `~/.syntaur/syntaur.db`.)
+
+Possible non-zero exits and how to surface them to the user:
+
+| stderr fragment | meaning | how to respond |
+|---|---|---|
+| `no idle members in '<slug>'` | `NoIdleMemberError` — pool exhausted | Tell user; suggest waiting / retrying later or asking a human to add capacity. |
+| `contention timeout on '<slug>'; retry` | `LeaseContentionError` — busy timeout | Retry once after ~1s. If it fails again, surface the error. |
+| `inventory '<slug>' not found` | typo or inventory doesn't exist | Tell user; list with `syntaur lease list`. |
+
+### Step 4: Parse the claim result
+
+Parse the stdout JSON: `{ lease_id, inventory_slug, member_id, member_gen, granted_at, expires_at, metadata }`.
+
+### Step 5: Persist the lease in `.syntaur/context.json`
+
+Append the lease record to the `leases: []` array in `.syntaur/context.json` (creating the array if absent). Atomic write via `jq` + rename:
+
+```bash
+mkdir -p .syntaur
+jq --arg lid "$LEASE_ID" \
+   --arg slug "$INVENTORY_SLUG" \
+   --arg mid "$MEMBER_ID" \
+   --arg exp "$EXPIRES_AT" \
+   --arg claimed "$GRANTED_AT" \
+   --argjson meta "$METADATA_JSON" \
+   '.leases = ((.leases // []) | map(select(.lease_id != $lid)) +
+    [{ lease_id: $lid, inventory_slug: $slug, member_id: $mid,
+       expires_at: $exp, metadata: $meta, claimed_at: $claimed }])' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+### Step 6: Report back
+
+Tell the user:
+- Which member was claimed (`<inventory>/<member_id>`) and the lease id.
+- When the lease expires (`expires_at`).
+- The connection metadata, if any (URL, port, credentials reference, etc.) — print as a code block so the agent (or human) can use it.
+- Reminder: leases do NOT auto-release on session end or assignment completion in v1. Call `/release-resource <lease_id>` when finished, or let the TTL expire and `gc` reclaim.

package/platforms/codex/skills/extend-resource/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: extend-resource
+description: Extend the TTL on a Syntaur resource lease previously claimed via /claim-resource. Triggers on "/extend-resource", "extend my lease", "renew the lease", "bump the TTL", "keep this resource a bit longer", or when the user wants more time on an active claim.
+license: MIT
+---
+
+# Extend Resource
+
+Extend an active Syntaur resource lease by pushing its `expires_at` forward. On success, also updates the lease's `expires_at` in `.syntaur/context.json` so the local record stays accurate. If the lease has already gone stale (expired, revoked, or member generation advanced), drops it from `.syntaur/context.json` and reports.
+
+## Usage
+
+User arguments: `$ARGUMENTS`
+
+- `<lease_id>` (required) — lease to extend
+- `--ttl <duration>` (required) — new TTL from now (e.g. `15m`, `2h`)
+
+Examples:
+- `/extend-resource cf3bd0a6-ba38-4a8c-a882-bdba9cabad80 --ttl 1h`
+- `/extend-resource 6d4a... --ttl 30m`
+
+## Workflow
+
+### Step 1: Parse arguments
+
+Extract `<lease_id>` (first positional) and `--ttl <duration>` (required). If either is missing, abort with a usage message and a hint to call `/list-resources` to see active leases.
+
+### Step 2: Pre-check assignment context
+
+Read `.syntaur/context.json` from the current working directory. If the file is missing, OR has neither `sessionId` nor any of `projectSlug`/`assignmentSlug`/`assignmentDir`, abort with:
+
+> "No active Syntaur context in this workspace. Grab an assignment first (`/grab-assignment <project> <slug>`) or restart the session so the SessionStart hook can populate `.syntaur/context.json`."
+
+This guard mirrors `/claim-resource` and `/release-resource` — writing a leases-only context file would trip `syntaur doctor`'s workspace check.
+
+### Step 3: Run the extend CLI
+
+```bash
+syntaur lease extend "$LEASE_ID" --ttl "$TTL"
+```
+
+(Use `dangerouslyDisableSandbox: true` — the CLI writes to `~/.syntaur/syntaur.db`.)
+
+Possible non-zero exits and how to surface them:
+
+| stderr fragment | meaning | how to respond |
+|---|---|---|
+| `cannot be extended (expired, revoked, or member generation advanced)` | `StaleLeaseError` — lease is no longer the holder. | Drop the entry from `.syntaur/context.json` (Step 5) and tell user the lease is dead — they'll need to `/claim-resource` again. |
+| `contention timeout; retry` | `LeaseContentionError` — busy timeout. | Retry once after ~1s. If it fails again, surface to user. |
+| `--ttl must be positive` | Bad duration. | Tell user to pass a positive duration like `15m`, `2h`. |
+
+### Step 4: Parse the new expiry from stdout
+
+On exit 0, stdout looks like: `Extended lease <id> (new expires_at=<iso>).`
+
+Capture the `new_expires_at` value (the ISO timestamp inside the parens).
+
+### Step 5a: On success, update `.syntaur/context.json`
+
+Find the matching entry in `leases[]` by `lease_id` and rewrite its `expires_at`:
+
+```bash
+jq --arg lid "$LEASE_ID" --arg exp "$NEW_EXPIRES_AT" \
+   '.leases = ((.leases // []) | map(
+      if .lease_id == $lid then .expires_at = $exp else . end
+    ))' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+### Step 5b: On `StaleLeaseError`, drop the entry instead
+
+```bash
+jq --arg lid "$LEASE_ID" \
+   '.leases = ((.leases // []) | map(select(.lease_id != $lid)))' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+### Step 6: Report back
+
+- On success: `Extended <lease_id> — new expires_at=<iso>.` Also surface the original member id (look it up in the context entry before mutation) so the user knows which resource was extended.
+- On stale: `Lease <lease_id> is no longer active — removed from context. Run /claim-resource to grab a new one.`

package/platforms/codex/skills/list-resources/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: list-resources
+description: List the Syntaur resource leases held by the current session, plus the workspace-wide overview of inventories and active leases. Triggers on "/list-resources", "what leases do I have", "show my leases", "list my resources", "what resources am I holding", or when the user wants both a session-local and system-wide view of leased resources.
+license: MIT
+---
+
+# List Resources
+
+Print two views in one call:
+
+1. **Your active leases** — the `leases[]` array from `.syntaur/context.json` (this session's claims).
+2. **All active leases in this workspace** — output of `syntaur lease list`, which shows every inventory plus its idle/leased counts.
+
+This is the cheap "what am I holding, and what's out there?" lookup before deciding to extend, release, or grab another resource.
+
+## Usage
+
+User arguments: `$ARGUMENTS` (no arguments accepted in v1).
+
+Examples:
+- `/list-resources`
+
+## Workflow
+
+### Step 1: Read this session's leases
+
+```bash
+jq -r '.leases // []' .syntaur/context.json 2>/dev/null
+```
+
+(No `dangerouslyDisableSandbox` needed — read-only.)
+
+If `.syntaur/context.json` is missing or has no `leases` array, treat it as empty. Do NOT abort — listing is informational; the absence of session context is itself a useful signal.
+
+For each entry, capture: `lease_id`, `inventory_slug`, `member_id`, `expires_at`, `claimed_at`, and any `metadata` (e.g. connection URL).
+
+### Step 2: Run the system-wide overview
+
+```bash
+syntaur lease list
+```
+
+(Use `dangerouslyDisableSandbox: true` — the CLI reads `~/.syntaur/syntaur.db`.)
+
+Capture stdout. If the CLI exits non-zero, surface the error message but still print whatever Step 1 produced.
+
+### Step 3: Report back
+
+Print two sections:
+
+**Your active leases (from `.syntaur/context.json`):**
+
+If the array is empty:
+> "No leases held by this session."
+
+Otherwise, one block per lease:
+```
+<lease_id>
+  inventory: <inventory_slug>/<member_id>
+  expires:   <expires_at>
+  claimed:   <claimed_at>
+  metadata:  <metadata JSON, if any>
+```
+
+**All inventories in this workspace (from `syntaur lease list`):**
+
+Paste the CLI output verbatim (one row per inventory with kind/idle/leased counts).
+
+### Step 4: Suggest next actions if any leases are nearing expiry
+
+If any session-local lease's `expires_at` is within the next 5 minutes, append:
+> "Note: lease `<id>` expires at `<iso>` (within 5 minutes). Run `/extend-resource <id> --ttl <duration>` to keep it."
+
+This is informational only — don't extend automatically.

package/platforms/codex/skills/release-resource/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: release-resource
+description: Release a Syntaur resource lease previously claimed via /claim-resource, freeing the member for the next claimant. Triggers on "/release-resource", "release this dev env", "drop the lease", "release my slot", "release all leases", or when the user is done with a claimed resource.
+license: MIT
+---
+
+# Release Resource
+
+Release one or more active resource leases, removing them from `.syntaur/context.json` and freeing their members for the next claimant.
+
+## Usage
+
+User arguments: `$ARGUMENTS`
+
+- `<lease_id>` — release a specific lease by id
+- `--all` — release every active lease recorded in `.syntaur/context.json`
+
+Examples:
+- `/release-resource cf3bd0a6-ba38-4a8c-a882-bdba9cabad80`
+- `/release-resource --all`
+
+## Workflow
+
+### Step 1: Parse arguments
+
+If `--all` is passed, build the list of `lease_id`s from `.syntaur/context.json`'s `leases: []` array. Otherwise the first positional argument is the single `lease_id` to release.
+
+If there is no `lease_id` and `--all` was not passed, abort with: "Specify `<lease_id>` or use `--all`. Active leases: $(jq -r '.leases[]?.lease_id' .syntaur/context.json 2>/dev/null || echo 'none')."
+
+### Step 2: Release each lease
+
+For each `lease_id`:
+
+```bash
+syntaur lease release "$LEASE_ID"
+```
+
+(Use `dangerouslyDisableSandbox: true` since the CLI writes to `~/.syntaur/syntaur.db`.)
+
+Outcomes:
+
+| Result | Meaning | What to do |
+|---|---|---|
+| Exit 0 with `Released lease <id>.` | Normal release. | Continue. |
+| Exit 1 with `lease ... is no longer active` | Stale lease (already expired/revoked). The slot has already been freed. | Still remove from `.syntaur/context.json` — the row is dead either way. Note the staleness in the final summary. |
+| Exit 1 with `contention timeout; retry` | `LeaseContentionError`. | Retry once after ~1s; if it fails again, surface to the user. |
+
+### Step 3: Remove the entry from `.syntaur/context.json`
+
+Whether the CLI succeeded OR returned a stale-lease error, drop the matching record from `.syntaur/context.json` (stale leases are dead — keeping them in context is misleading):
+
+```bash
+jq --arg lid "$LEASE_ID" \
+   '.leases = ((.leases // []) | map(select(.lease_id != $lid)))' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+### Step 4: Report back
+
+For a single release: `Released <lease_id> (<inventory>/<member_id>).` or `Lease <id> was already stale; removed from context.`
+
+For `--all`: print one line per lease, then a summary count: `Released N lease(s), M already stale.`
+
+If no leases were recorded in context, say so explicitly.

package/platforms/codex/skills/syntaur-protocol/SKILL.md

@@ -60,6 +60,7 @@ If `.syntaur/context.json` exists in the current working directory, read it befo
 - `workspaceRoot` — absolute path to the code workspace
 - `sessionId` — real agent-runtime session id (never a synthesized UUID)
 - `transcriptPath` — absolute path to the agent's rollout/transcript file, if known
+- `leases` — array of active resource-lease records (managed by `/claim-resource` and `/release-resource`). Entry shape: `{ lease_id, inventory_slug, member_id, expires_at, metadata, claimed_at }`. Leases are NOT auto-released on session end or assignment completion in v1 — call `/release-resource` explicitly (or let the TTL expire).
 
 ## Required Reading Order