sideby 0.13.0 → 0.14.0

package/schemas/quota-setup.json

@@ -54,6 +54,68 @@
           "type": "string"
         }
       }
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Updates the installed sideby skill (run it after the user agrees)."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
     }
   },
   "title": "sideby quota setup --json"

package/schemas/quota-teardown.json

@@ -24,6 +24,68 @@
     },
     "diff": {
       "type": "string"
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Updates the installed sideby skill (run it after the user agrees)."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
     }
   },
   "title": "sideby quota teardown --json"

package/schemas/quota.json

@@ -66,6 +66,10 @@
                         "label": {
                           "type": "string"
                         },
+                        "name": {
+                          "type": "string",
+                          "description": "The group of models this limit covers, when it covers only some (spec §3.26); it does not count toward Quota Pressure."
+                        },
                         "windowMinutes": {
                           "type": "number"
                         },
@@ -90,6 +94,14 @@
                   "from": {
                     "type": "string",
                     "description": "The account this reading was taken from, when it is another account of the same login (spec §3.21); observedAt is its time."
+                  },
+                  "fetched": {
+                    "type": "boolean",
+                    "description": "This reading is the kept answer of a quota check that costs a request (spec §3.26)."
+                  },
+                  "fetchError": {
+                    "type": "string",
+                    "description": "Why the latest quota check failed, while this older reading is shown."
                   }
                 }
               },
@@ -105,7 +117,8 @@
                     "const": "unavailable"
                   },
                   "reason": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "not-enabled, no-session, unrecognized, no-source, api-account or fetch-failed."
                   },
                   "detail": {
                     "type": "string"
@@ -207,6 +220,68 @@
           }
         }
       }
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Updates the installed sideby skill (run it after the user agrees)."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
     }
   },
   "title": "sideby quota --json"

package/schemas/remote-control.json

@@ -123,6 +123,68 @@
     },
     "message": {
       "type": "string"
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Updates the installed sideby skill (run it after the user agrees)."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
     }
   },
   "title": "sideby remote-control [off|undo] --json"

package/schemas/tune-change.json

@@ -120,6 +120,68 @@
     },
     "message": {
       "type": "string"
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Updates the installed sideby skill (run it after the user agrees)."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
     }
   },
   "title": "sideby tune apply|undo --json"

package/schemas/tune.json

@@ -242,6 +242,68 @@
           }
         }
       }
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Updates the installed sideby skill (run it after the user agrees)."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
     }
   },
   "title": "sideby tune --json"

package/schemas/update.json

@@ -108,11 +108,117 @@
     },
     "skill": {
       "type": "string",
-      "description": "The command that updates the sideby skill; sideby never runs it."
+      "description": "The command that installs the sideby skill by hand."
+    },
+    "skillUpdate": {
+      "type": "object",
+      "required": [
+        "installed",
+        "outdated",
+        "command",
+        "canRun"
+      ],
+      "properties": {
+        "installed": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "description": "Versions of the installed sideby skills; null for one without a version."
+        },
+        "outdated": {
+          "type": "boolean",
+          "description": "Some installed skill is for another version than sideby will run."
+        },
+        "command": {
+          "type": "string"
+        },
+        "canRun": {
+          "type": "boolean",
+          "description": "False when sideby leaves the skill alone (see reason): give the user command."
+        },
+        "reason": {
+          "type": "string"
+        }
+      },
+      "description": "The installed sideby skill, which the Update brings along; absent when none is installed."
+    },
+    "skillUpdated": {
+      "type": "boolean",
+      "description": "The skill was updated too (true) or that failed (false); absent when not tried."
     },
     "output": {
       "type": "string",
       "description": "What the failed install command printed."
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Updates the installed sideby skill (run it after the user agrees)."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
     }
   },
   "title": "sideby update --json"

package/skills/sideby/SKILL.md

@@ -2,7 +2,7 @@
 name: sideby
 description: Use when the user runs, or wants to run, several AI coding accounts (Claude Code, Codex, Grok Build, pi) side by side. Covers installing sideby and setting up a new account ("install sideby", "set up another Claude account", "add cc008", "配置一个 cc00x", "再加一个 Codex 账号"), explaining what accounts share and what stays separate ("what do my accounts share?", "这些账号共享了什么"), showing which account a session is ("show [cc001] in the status line", "加上账号标识"), seeing accounts, quota and usage, moving on when one hits its 5-hour or weekly limit, moving the current task to another account ("用 cc008 继续", "交回 cc008"), adding a short command (alias), and repairing drifted account directories (skills, hooks, rules or settings not shared, wrong symlinks, credential file permissions). Drives the `sideby` CLI with `--json`; the agent does every step except browser sign-in, filling in secrets and starting interactive sessions, which it hands to the user as one command (inside an Auto Handoff session, `sideby handoff ready --to` moves the task itself).
 metadata:
-  version: "0.13.0"
+  version: "0.14.0"
   requires:
     bins: [sideby, node]
   cliHelp: sideby --help
@@ -29,6 +29,7 @@ Do every step you can yourself. Only browser sign-in, secrets and interactive se
 - Every `--json` output has `schemaVersion: 1`. On an error it is `{ "schemaVersion": 1, "error": "<what to do next>", "code": "<reason>" }`; `code` is `usage` for a malformed command line.
 - Exit codes: `0` done, `1` failed or found a `fail` problem, `2` malformed command line, `10` **needs the user's confirmation**. `run`, `next` and `login` return the Host's own exit code once it starts.
 - On `10`: show the user the change the command printed, ask, and only after a clear yes run the same command again with `--yes` added. Never add `--yes` on your own.
+- `_notice` on any `--json` output: a newer sideby (`_notice.update`) or an installed sideby skill for another version (`_notice.skill`). It is not the answer to the task: finish the task first, then mention it in one line and offer to update, following `references/update.md`.
 
 ## What do you want to do
 
@@ -48,6 +49,7 @@ Account refs are `<family>:<name>`; a bare `<name>` works only when it is unique
 | See or set the model and effort an account starts with ("用哪个模型", "set effort to high for cc002") | `sideby model <acct> --json`; `sideby model <acct> <model\|default> --effort <level\|default>` (exit 10 first, then `--yes` after the user agrees) | — |
 | Stop Claude sessions from connecting to claude.ai / the Claude app by themselves ("关闭 remote control", "别让别人远程看到对话") for every account | `sideby remote-control --json`, then `sideby remote-control off` (exits 10 with the change; rerun with `--yes` after they agree); `sideby remote-control undo` puts it back; `sideby remote-control on` turns it back on the same way (only when they ask for it) | — |
 | See Claude quota (it shows `not-enabled`) | `sideby quota setup claude` (exits 10) | `references/quota.md` |
+| Update sideby or its skill ("is there a new version", "更新 sideby"), or an output has `_notice` | `sideby update --json` (exits 10 first) | `references/update.md` |
 | See everything at once | `sideby ui` (local panel on `127.0.0.1:17420`; `--no-open` prints the address) | — |
 | Start an account | give them `sideby run <ref> [-- host args]` | — |
 
@@ -73,4 +75,4 @@ To update sideby, run `sideby update --json` yourself: it shows `current`, `late
 
 ## Keeping this skill current
 
-If `sideby doctor --json` reports `skill.outdated`, this skill was written for another sideby version. Tell the user to update it with `npx skills add Adonis0123/sideby -g`.
+If `sideby doctor --json` reports `skill.outdated`, this skill was written for another sideby version. Offer `sideby update --json` (exit 10, then `--yes` after they agree): it updates the skill, together with sideby when a newer one is out (`references/update.md`).

package/skills/sideby/references/diagnose.md

@@ -23,13 +23,14 @@ Shared Items the Main Account does not have are skipped: no Finding, not counted
 | `fail` `link.dangling` | The link points at nothing | Show the hint (`ls -l <path>`); the user decides how to repair it |
 | `fail` `symlink-forbidden` without `fixable` | The Host needs a real file here, but the link points somewhere other than the Main Account | Show the hint; sideby will not replace a link it did not create |
 | credential item, mode not 600 | `proxy.env`, `auth.json`, `.claude.json` readable by others | `--fix` resets the mode to 600 |
-| `warn` `skill.outdated` (in `general`) | The installed sideby skill is for another sideby version | Tell the user to run `npx skills add Adonis0123/sideby -g` |
+| `warn` `skill.outdated` (in `general`) | The installed sideby skill is for another sideby version | Offer `sideby update` (it updates the skill; see `update.md`) |
 | name looks like a backup (`bak`, `backup`, `old`, `tmp`) | A stray directory was picked up as an account | Suggest adding its ref to `ignore` in `${XDG_CONFIG_HOME:-~/.config}/sideby/config.json` |
 | `login: "not-needed"` (`key` in `sideby list`) | API account; it authenticates with `proxy.env` | Nothing to do |
 | `problems` on an account in `list --json` | A plugin failed while reading it (for example a settings file that is not valid JSON) | Show the message; the account itself still works |
 | quota `unavailable` / `not-enabled` | Claude quota source is off | Offer `sideby quota setup claude` |
 | quota `unavailable` / `no-session` | No session since the source was enabled | Ask the user to start one session with that account |
-| quota `unavailable` / `no-source` | Grok, pi: the Host has no public source | Nothing to fix |
+| quota `unavailable` / `no-source` | pi: the Host has no public source | Nothing to fix |
+| quota `unavailable` / `fetch-failed` | Grok: its CLI could not get the quota | Follow `detail` (update Grok, `sideby login grok:<name>`), then `sideby quota grok --refresh` |
 | quota `unavailable` / `api-account` | API accounts have no quota | Nothing to fix |
 | quota `unavailable` / `unrecognized` | Host changed its file format | Report it; suggest filing an issue with the Host version |
 | host not installed | Accounts exist but the CLI is missing | Point to the Host's install docs; do not install it unasked |

package/skills/sideby/references/handoff.md

@@ -29,7 +29,7 @@ Use this when the user says an account hit its 5-hour or weekly limit ("usage li
 
 ## Other answers
 
-- Error `code: "no-quota-source"` (Grok, pi): the Host publishes no quota. The message lists the family's accounts; let the user choose one for `sideby run <ref>`.
+- Error `code: "no-quota-source"` (pi, or a plugin family without quota): the Host publishes no quota. The message lists the family's accounts; let the user choose one for `sideby run <ref>`.
 - Error `code: "no-accounts"`: the family has no account yet; see creating accounts.
 - Many `unknown` Claude accounts: Claude quota may be off. `sideby quota --json` shows `not-enabled`; the one-time setup turns it on.
 - Host arguments the user wants (another model, say) go after `--`: `sideby next claude -- --model opus`.

package/skills/sideby/references/quota.md

@@ -13,4 +13,8 @@ After setup, each account shows quota once it has had one session with a reply.
 
 Two Claude accounts signed in as the same login (same email and organization; `sameLogin` in `sideby list --json`) share one quota: both show the freshest reading, and `quota.from` names the account it was read from. Explain that to the user rather than calling the numbers wrong; usage stays per account, and sideby never merges or deletes either directory.
 
-Usage (7-day tokens) is read by sideby itself from Claude Code and Codex local records; no ccusage is needed. Grok and pi have no quota or usage source.
+Grok quota needs no setup: sideby asks the `grok` CLI of each signed-in account (`grok agent --no-leader stdio`, the Host makes the request with its own login; sideby never reads `auth.json`) at most every 15 minutes, and also reads the quota Grok logs after each turn. `sideby quota grok --refresh` asks again now. `quota.status: "unavailable"` with `reason: "fetch-failed"` carries the cause and next step in `detail` (update Grok, `sideby login grok:<name>`); `"not-enabled"` means the user turned it off (config `quota.check.grok: false`, or the Panel's Settings) or it runs in CI. A reading with `fetchError` is the last good one; say it may be old.
+
+A window with a `name` (a plugin's Cursor "Other models") covers only some models: show it, but it does not make the account full.
+
+Usage (7-day tokens) is read by sideby itself from Claude Code and Codex local records; no ccusage is needed. Grok and pi have no usage source; pi has no quota either.

package/skills/sideby/references/update.md

@@ -0,0 +1,16 @@
+# Updates and `_notice`
+
+Every `--json` output can carry `_notice` (it comes from sideby's daily Update Check and the installed skill, and reads no network itself):
+
+- `_notice.update`: `{ current, latest, command: "sideby update", message }`, a newer sideby is out.
+- `_notice.skill`: `{ installed, current, command, message }`, the sideby skill agents read here is for another version (`installed: null` when it has no version), so it may describe commands this CLI does not have.
+
+What to do:
+
+1. Finish what the user asked first. Do not answer with the notice, and do not stop a task to update.
+2. If the notice is still relevant at the end, say it in one line in the user's language, for example "sideby 0.14.0 is out (you have 0.13.0); want me to update it?", and offer to do it. Say it once per conversation, not after every command.
+3. When they agree:
+   - Run `sideby update --json`. It shows the version, the install method and the command it would run, and exits `10`. Show that to the user; after their yes, run `sideby update --yes --json`.
+   - If it exits `1` with `canRun: false` (npx, Volta, a project dependency, a source checkout, a Local Build), sideby cannot update itself: give the user the `command` it printed as one line to run.
+   - The same command updates the installed sideby skill (`skillUpdate` in the plan, `skillUpdated` in the result), so do not run a skill command yourself. With sideby already current and only the skill old (`_notice.skill`), `sideby update` updates the skill alone, after the same preview. When `skillUpdate.canRun` is false (the skill lives in a git repository), tell the user `reason` and give them `command`. Tell them that sessions already running keep the old version until they start again.
+4. The user can turn notices off with `SIDEBY_NO_UPDATE_NOTIFIER=1` (or config `update.check: false`); set it for one command when a script needs JSON without `_notice`. A Local Build (`pnpm local`) never has one.