@aion0/forge 0.10.32 → 0.10.34

package/lib/help-docs/06-skills.md

@@ -16,11 +16,21 @@ Both register as `/slash-command` in Claude Code.
 
 ## Install
 
-1. Go to **Skills** tab in Forge
+1. Go to **Marketplace** tab in Forge
 2. Click **Sync** to fetch latest registry
 3. Click **Install** on any skill → choose Global or specific project
 4. Use in Claude Code with `/<skill-name>`
 
+## Navigating the Marketplace
+
+The toolbar has three group-scoped controls, ordered by usage frequency. Opening the Marketplace tab lands on **Pipelines** by default — the highest-traffic category.
+
+- **Pipelines** (button) — Templates synced from `forge-workflow`. Default landing view.
+- **Extensions ▾** — Connectors / Plugins / Crafts
+- **Catalog ▾** — All / Skills / Commands / Local / Rules
+
+The control whose value is currently active highlights in the accent color; the other two show their group label as a placeholder. Click any option to switch — no need to traverse a single long dropdown.
+
 ## Update
 
 Skills with newer versions show a yellow "update" indicator. Click to update (checks for local modifications first).

package/lib/help-docs/12-usage.md

@@ -4,7 +4,7 @@ Forge tracks Claude API token usage and estimated costs across all your projects
 
 ## Access
 
-Click **Usage** in the Dashboard top navigation.
+Open the **user menu** (top-right `▾`) and click **Usage**. It sits next to Monitor and Login Status — the three periodic-check screens are grouped there so the top toolbar only carries at-a-glance signals.
 
 ## Data Source
 

package/lib/help-docs/24-watch.md

@@ -47,25 +47,50 @@ Both use the same background machinery; you experience them identically.
 ## `start_watch` (for the assistant)
 
 When you've just started a long job and have a tool that reports its
-status, register a watch instead of polling in the conversation:
+status, register a watch instead of polling in the conversation. Two
+poll forms are accepted:
+
+**1. Connector tool** — `"<connector>.<tool>"`, e.g. `jenkins.get_build`:
 
 ```
 start_watch({
-  poll: "jenkins.get_build",                       // <connector>.<status tool>
+  poll: "jenkins.get_build",
   poll_args: { job_path: "job/foo", build_number: 18 },
-  done_match: { path: "result", equals: "SUCCESS" },  // or done_path (truthy)
+  done_match: { path: "result", equals: "SUCCESS" },
   interval_sec: 60, timeout_sec: 1800,
-  message: "Build 18 finished: {poll.result}"      // {poll.<path>} = latest result
+  message: "Build 18 finished: {poll.result}"
+})
+```
+
+**2. Bare builtin name** — Forge's own status readers:
+
+| Builtin | Pair with | done condition |
+|---|---|---|
+| `get_pipeline_status` | `trigger_pipeline` → pipeline_id | `done_match={path:"status",equals:"done"}` (or `done_path:"terminal"`) |
+| `get_task_status` | `dispatch_task` → task_id | `done_path:"terminal"` |
+
+```
+start_watch({
+  poll: "get_pipeline_status",                   // bare builtin, no prefix
+  poll_args: { pipeline_id: "a8e049a3" },
+  done_path: "terminal",
+  message: "Pipeline {poll.workflowName} finished: {poll.status}"
 })
 ```
 
-Then **stop** — do not keep calling get_build in the conversation. A
-completion message arrives in chat; the user can cancel it from the watch
-list. Pick `done_match`/`done_path` from a field you saw in the status
-tool's output (you usually called it once already). Queue/startup errors
-(e.g. a build number 404 while still queued) are tolerated for a while.
-Guards (max polls, timeout, lifetime, active cap) keep it from running
-away; worst case it times out and reports that.
+Then **stop** — do not keep calling the status tool in the conversation.
+A completion message arrives in chat; the user can cancel it from the
+watch list. Pick `done_match`/`done_path` from a field you saw in the
+status tool's output (you usually called it once already). Queue/startup
+errors (e.g. a build number 404 while still queued) are tolerated for a
+while. Guards (max polls, timeout, lifetime, active cap) keep it from
+running away; worst case it times out and reports that.
+
+### `_raw` fallback for non-JSON tools
+
+The poll result is parsed as JSON. If the tool returns plain text (some
+shell-protocol tools), Forge wraps it as `{_raw: "...full output..."}`
+so you can still grep — e.g. `done_match={path:"_raw",contains:"DONE"}`.
 
 ## Limits
 

package/lib/watch/watch-runner.ts

@@ -40,6 +40,45 @@ function parseResult(content: string): any {
   try { return JSON.parse(content); } catch { return { _raw: content }; }
 }
 
+/** Heuristic: spot common "this work is finished" shapes from a poll
+ *  result, regardless of whether the connector author thought to set
+ *  `terminal: true` or pre-declare done conditions. Walks well-known
+ *  state-bearing fields (state / status / phase / result / done /
+ *  finished / complete / completed) and matches their values against
+ *  a curated vocabulary used across CI, Jenkins, k8s, generic build
+ *  systems, etc.
+ *  Returns { failure } when a hit is found, null otherwise. Intended
+ *  to run AFTER user's explicit done_match/done_path, so a caller who
+ *  configured "done when status == running" (rare but legal) still
+ *  wins. */
+function detectTerminalState(obj: any): { failure: boolean; source: string; value: string } | null {
+  if (!obj || typeof obj !== 'object') return null;
+  // Boolean done-ish flags
+  for (const f of ['done', 'finished', 'complete', 'completed']) {
+    if (truthy(obj[f])) return { failure: false, source: f, value: 'true' };
+  }
+  // State-bearing fields with a terminal vocabulary
+  const fields = ['state', 'status', 'phase', 'result', 'conclusion', 'lifecycle_state'];
+  const failureWords = new Set([
+    'failed', 'failure', 'error', 'errored', 'cancelled', 'canceled',
+    'aborted', 'killed', 'terminated', 'timeout', 'timed_out', 'rejected',
+    'unstable', 'broken',
+  ]);
+  const successWords = new Set([
+    'done', 'success', 'succeeded', 'complete', 'completed', 'finished',
+    'passed', 'ok', 'green', 'healthy',
+  ]);
+  for (const f of fields) {
+    const raw = obj[f];
+    if (raw == null) continue;
+    const v = String(raw).toLowerCase().trim();
+    if (!v) continue;
+    if (failureWords.has(v)) return { failure: true, source: f, value: v };
+    if (successWords.has(v)) return { failure: false, source: f, value: v };
+  }
+  return null;
+}
+
 const g = globalThis as any;
 
 export function startWatchRunner(hooks: WatchRunnerHooks = {}): void {
@@ -120,7 +159,27 @@ export function startWatchRunner(hooks: WatchRunnerHooks = {}): void {
     if (w.fail_path && truthy(getPath(obj, w.fail_path))) {
       return finish(w, 'failed', obj, `${w.label}: failure condition met.`);
     }
-    // done check
+    // Hard terminal check — if the poll tool itself says "this is a
+    // terminal state" (cancelled / failed / done / etc.), believe it
+    // regardless of the user-configured done condition. Without this,
+    // a watch on get_pipeline_status with done_match={status:"done"}
+    // would keep polling after the user cancels the pipeline, because
+    // status="cancelled" never matches "done" — wasting polls until
+    // max_polls / timeout. The builtin status tools (get_pipeline_status,
+    // get_task_status) all set obj.terminal = true on cancelled/failed
+    // too, so honoring it here drops the watch the moment the user
+    // intervenes.
+    if (truthy(getPath(obj, 'terminal'))) {
+      const statusVal = String(getPath(obj, 'status') || '').toLowerCase();
+      const isFailureLike = statusVal === 'failed' || statusVal === 'cancelled';
+      return finish(
+        w,
+        isFailureLike ? 'failed' : 'done',
+        obj,
+        `${w.label}: ${statusVal || 'reached a terminal state'}.`,
+      );
+    }
+    // done check (user-configured)
     let done = false;
     if (w.done_match) {
       const v = getPath(obj, w.done_match.path);
@@ -132,6 +191,22 @@ export function startWatchRunner(hooks: WatchRunnerHooks = {}): void {
     if (done) {
       return finish(w, 'done', obj, `${w.label}: done.`);
     }
+    // Heuristic terminal detection — fallback for connector pollers
+    // that don't set obj.terminal AND whose authors didn't anticipate
+    // a particular done condition. If the poll result has a common
+    // "I'm finished" shape (state/status/phase/result with a known
+    // terminal word, or done:true / finished:true), trust it. User's
+    // explicit done_match/done_path runs first (above), so a watch
+    // wanting "done when status==running" still works as intended.
+    const term = detectTerminalState(obj);
+    if (term) {
+      return finish(
+        w,
+        term.failure ? 'failed' : 'done',
+        obj,
+        `${w.label}: detected ${term.source}=${term.value} — closing watch.`,
+      );
+    }
     // not done — bound by polls / timeout, else reschedule
     if (polls >= w.max_polls || now - w.created_at > w.timeout_sec * 1000) {
       return finish(w, 'timed_out', obj, `${w.label}: not done within ${w.max_polls} polls / ${w.timeout_sec}s — please verify manually.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.10.32",
+  "version": "0.10.34",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {