@hagicode/cli 0.1.0-dev.55.1.790ae59 → 0.1.0-dev.59.1.47fc04a

package/dist/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./chunks/main-B-hAwHb9.js");s.runCli().then(e=>{e!==0&&(process.exitCode=e)}).catch(e=>{const n=e instanceof Error?e.stack??e.message:String(e);process.stderr.write(`${n}
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./chunks/main-nHMH-5Rj.js");s.runCli().then(e=>{e!==0&&(process.exitCode=e)}).catch(e=>{const n=e instanceof Error?e.stack??e.message:String(e);process.stderr.write(`${n}
 `),process.exitCode=s.EXIT_CODES.UNKNOWN});

package/dist/main.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/main-B-hAwHb9.js");exports.createCliApp=e.createCliApp;exports.runCli=e.runCli;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/main-nHMH-5Rj.js");exports.createCliApp=e.createCliApp;exports.runCli=e.runCli;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/cli",
-  "version": "0.1.0-dev.55.1.790ae59",
+  "version": "0.1.0-dev.59.1.47fc04a",
   "description": "HagiCode CLI for project, proposal, vault, chat, and AutoTask management.",
   "homepage": "https://github.com/HagiCode-org/cli#readme",
   "bugs": {

package/resources/saga/manifest.json

@@ -7,8 +7,8 @@
     "goal": "a545b01c9f6010df661f02cf62ef9bcae527ccf329f304ea82ffdda239b118df",
     "research": "2504283ea845440c7909ff1da20bfb70f846d55ca16565740168848cfb8060b1",
     "acceptance": "11ca06794d0ec19e87d1a4e883a67014563e9750b9fa62a8bedd43a69d52ca65",
-    "plan": "bcc4c0509f2971083775db2b3678f41c55f16e69deba2d994d3ed636f314d917",
-    "run": "ea3fc7f5c54230cef95b09595cb296432f733bdbe8cbe42c40cf73f6f6b900e4",
+    "plan": "6573a02a36ab2d6995c2e4740d2c8771a41e77e5179145d0a2b8e30023816916",
+    "run": "915f34584cb15bf5c66a32bbe377c54343b0acae3353fc045cf276b09b99e08e",
     "amend": "be621d1221a85656851548aee1e9e9d78480288bd856baf1bdbf50cb3317f49b"
   }
 }

package/resources/saga/prompts/plan.md

@@ -3,14 +3,34 @@
 ## Instruction
 List the work items, one line each: `- [ ] <ID> <name> | `. The evidence path is added when an item is ticked.
 
-- Items are small enough to verify with one command, mostly independent, and ordered so that earlier items do not depend on later ones.
+- Items are small enough to verify with one command, and ordered so that earlier items do not depend on later ones.
 - Keep the list short enough to review (roughly 3 to 15 items). Use the user's work items as a start; add or split items only when needed.
 - Do not add items for committing, pushing, opening a pull request, releasing or archiving: they are outside the contract.
 - IDs match the headings of `acceptance.md`.
-- In a revision an item may be added or superseded, never deleted. A superseded item is written without brackets: `- ~ <ID> <name> | superseded in r<N>: <reason>`.
+- In a revision an item may be added or superseded, never deleted. A superseded item is written without brackets: `- ~ <ID> <name> | superseded in r<N>: <reason>`. A superseded item is not active: it has no node in the graph and no edges.
 - Planning ends here. Do not run `freeze`, do not start the run, do not edit project code.
 
+## Dependency graph
+`progress.md` holds exactly one Mermaid `flowchart` that describes every dependency between the active items. Write it in its own section, outside the item rows. It is the only place dependencies are declared.
+
+- Each active item is one node. The node ID equals the item ID, and the node label holds the item's name in quotes.
+- An edge `A --> B` means B cannot start until A is ticked. Write an edge only when that order is required.
+- Two items with no path between them are independent and may run together. Independence is expressed only by the absence of a path.
+- Group nodes with one `subgraph` per module, repository or area the item changes, titled in quotes (for example `subgraph CLI["repos/cli"]`). A subgraph states ownership only. Two items in one subgraph are not dependent because of it, and items in different subgraphs are not dependent because of it either.
+- Item IDs must be valid Mermaid node IDs: start with a letter and use only letters, digits and underscores (`T1`, `CLI_2`; not `1.2`, not `T-1`). Never use the word `end`. Put the readable name in the node label, not in the ID.
+- Keep every dependency in this one graph. Do not declare a dependency in prose, in the note column after `|` of an item row (that text is evidence only), in a separate list, or in a second diagram.
+- Item rows keep their format `- [ ] <ID> <name> | <evidence>` unchanged, and the graph lines are never edited by ticking an item.
+
 ## Template
 ```
 - [ ] <ID> <name> | 
 ```
+
+```mermaid
+flowchart TD
+    subgraph <MODULE>["<module or repository>"]
+        <ID>["<ID> <name>"]
+    end
+    <ID> --> <ID>
+```
+</content>

package/resources/saga/prompts/run.md

@@ -11,7 +11,7 @@ The run's options may name these, with the defaults shown:
 
 0. **Claim first.** `hagi saga claim <saga> --session <your session id> --path <root> --json`. Keep the printed token for every later command. If it refuses because another owner holds the Saga, stop and report it. Never take over by age, and never write a paused snapshot over another owner's progress.
 1. **Freeze.** `hagi saga freeze <saga> --path <root> --token <token>`. If it refuses (open questions, open amendments, a changed contract), run `hagi saga set-status <saga> --state paused --note "<reason>" --path <root> --token <token>`, stop and report the reasons. Do not edit contract files and do not decide open questions. A first freeze writes revision 1. After an amendment was merged it writes the next revision, chained to the previous one, and reopens the items whose acceptance command changed.
-2. **Check before every item and at every heartbeat.** `hagi saga assert-owner <saga> --path <root> --token <token>` before each dispatch, then `hagi saga check <saga> --phase run --path <root>`. If a check fails, pause the same way and report. An open amendment also means: pause.
+2. **Check before every dispatch and at every heartbeat.** `hagi saga assert-owner <saga> --path <root> --token <token>` before each dispatch, then `hagi saga check <saga> --phase run --path <root>`. If a check fails, pause the same way and report. An open amendment also means: pause.
    - **Quota before every Worker.** Before you create any Worker (step 3, and a tuning worker in step 4), resolve the provider that Worker spends, in this order, and use the first that applies:
      1. the hint for the Worker's hero id, when the run input names the hero that Worker runs;
      2. the hint for the Worker's role;
@@ -23,15 +23,24 @@ The run's options may name these, with the defaults shown:
      - exit `34`, no usable figure: dispatch the Worker, log `quota unknown` with the provider in `orchestrator-log.md`, and read again before the next Worker.
      - Any other exit code: pause the same way as a failed check, and report it.
    - The JSON output's `windows` lists each window with `remainingPercent` and `resetsAtUtc`. Record the provider, the remaining percent and the reset time for every dispatch and every held dispatch (step 6).
-3. **Work one item at a time** (`hagi saga items <saga> --path <root>` lists them with their commands), unless the goal allows parallel items. For each item:
+   - **Concurrent Workers.** Each Worker that runs alongside others gets its own ownership assert, its own check, its own quota check and its own logged reading (step 6), in that order, before it is created. A held dispatch (exit `0`, `guard.state` `low`) holds only that Worker: the Workers already running keep running, and between two runs of the held quota check you handle their reports, ticks and archiving. A held dispatch never stops a running Worker; only the wait total of that dispatch can pause the Saga.
+3. **Dispatch by the dependency graph.** Read the Mermaid flowchart in `<root>/.hagicode/sagas/<saga>/progress.md` and the items (`hagi saga items <saga> --path <root>` lists them with their commands). Then:
+   - **Ready set.** An item is ready when it is unticked, not blocked, and every predecessor of it in the graph (every node with an edge `P --> <ITEM>`) is ticked. Compute the ready set from the graph and the Saga record, not from memory, and recompute it after every tick or block.
+   - **No graph, serial.** If `progress.md` holds no Mermaid flowchart, the Saga runs serially: one item at a time, in the listed order, with no inferred parallelism.
+   - **Graph problems pause.** If an unticked active item has no node in the graph, or an edge names a node that is not an active item, pause the Saga with that reason (step 9). Do not guess an order.
+   - **Goal forces serial.** If the goal says items run one at a time, dispatch one item at a time regardless of the graph.
+   - **Hold back overlap.** Among ready items, do not run two at once when they share a subgraph module or are likely to edit the same files, judged from the subgraph, the item name and its acceptance command. Dispatch one of them and hold the others until the running item is ticked or blocked. Ready items in disjoint modules with no shared files are not held back.
+   - **Cap.** At most 3 Workers run at once by default, counting implementation and verification Workers together. The goal may name a different cap; never exceed it. When more items are ready than there are free slots, start the rest as Workers settle.
+   - **Fan out.** Dispatch each remaining ready item by creating its implementation Worker, one after another, each behind its own quota check (step 2). Workers never tick or block items themselves: the orchestrator is the only writer of the Saga record.
+   For each Worker:
    - Before each implementation, verification and tuning Worker, not once per item, run the quota check of step 2 for the provider that Worker spends.
    - Create each Worker with `hagi saga session create --saga <saga> --path <root> --title "<ITEM> <role>" --role <role> --master <your session id> --item <ITEM>`, where `<role>` is `implementation` or `verification`. This command takes the token from `SAGA_EXECUTION_TOKEN`, set to the token that `claim` printed, and refuses `--token`. It creates the chat session with its Saga metadata and records it in `sessions.md`. Then give the Worker its instructions below.
    - An implementation worker writes code and tests only. Give it the goal, the item, the scope and the safety rules, the project root and its report path.
    - A separate verification worker runs the item's command from `acceptance.md` in the project root, writes the output to `<root>/.hagicode/sagas/<saga>/runtime/evidence/<ITEM>.log`, and writes `<root>/.hagicode/sagas/<saga>/runtime/reports/<ITEM>.md` with the line `Status: PASS` (or `状态: PASS`) only if the exit code is 0. It changes no files.
    - Only `hagi saga tick <saga> <ITEM> --path <root> --token <token>` ticks an item. It refuses without a PASS report and an evidence file.
-4. **On a failed verification, classify it.** An environment fault (missing module, port in use) does not count. A quota fault does not count either: a worker that stopped because its provider's quota was exhausted is not given to a tuning worker and is not counted. Re-dispatch the same Worker role with the same instructions, unchanged, once the step-2 quota check for that Worker's own provider (the provider it used, not the default) returns exit `0` with `guard.state` `ready`. A real failure counts: give a tuning worker the failure log path, then verify again. After 3 real failures run `hagi saga block <saga> <ITEM> "<reason>" --path <root> --token <token>` and move on.
+4. **On a failed verification, classify it.** An environment fault (missing module, port in use) does not count. A quota fault does not count either: a worker that stopped because its provider's quota was exhausted is not given to a tuning worker and is not counted. Re-dispatch the same Worker role with the same instructions, unchanged, once the step-2 quota check for that Worker's own provider (the provider it used, not the default) returns exit `0` with `guard.state` `ready`. A real failure counts: give a tuning worker the failure log path, then verify again. After 3 real failures run `hagi saga block <saga> <ITEM> "<reason>" --path <root> --token <token>` and move on. A blocked item blocks everything downstream of it: every item reachable from it in the graph is never dispatched and is reported as waiting on that item. Items with no path from the blocked item continue as in step 3.
 5. **After a revision reopened items,** also re-verify any item whose command is the full regression: its own command did not change, so it was not reopened.
-6. **Keep the record.** Append a line to `<root>/.hagicode/sagas/<saga>/runtime/orchestrator-log.md` after every dispatch, held dispatch, verification and tick. Every dispatch line and every held dispatch line carries the quota reading it was made on: the provider, the remaining percent, the `resetsAtUtc` and the seconds waited. `hagi saga session create` records each Worker session it creates in `<root>/.hagicode/sagas/<saga>/runtime/sessions.md`, so do not append those sessions to that file by hand. Run `hagi saga set-status <saga> --state running --note "<heartbeat>" --path <root> --token <token>` at every heartbeat, and put the latest quota reading (provider, remaining percent, reset time and seconds waited) in that note. Run `hagi saga status <saga> --path <root> --json` to read the projection at the end.
+6. **Keep the record.** Append a line to `<root>/.hagicode/sagas/<saga>/runtime/orchestrator-log.md` after every dispatch, held dispatch, verification and tick. Every dispatch line and every held dispatch line carries the quota reading it was made on: the provider, the remaining percent, the `resetsAtUtc` and the seconds waited. `hagi saga session create` records each Worker session it creates in `<root>/.hagicode/sagas/<saga>/runtime/sessions.md`, so do not append those sessions to that file by hand. Run `hagi saga set-status <saga> --state running --note "<heartbeat>" --path <root> --token <token>` at every heartbeat, and put the latest quota reading (provider, remaining percent, reset time and seconds waited) in that note. While several Workers run, heartbeat at every check of a running Worker and name the running items in the note. Run `hagi saga status <saga> --path <root> --json` to read the projection at the end.
 7. **Archive each settled item's sessions.** Once an item is ticked or blocked and its workers have stopped, archive the worker sessions you created for it: `hagi chat archive --session-id <session id> --json`. Take the IDs from `<root>/.hagicode/sagas/<saga>/runtime/sessions.md`. Archive only sessions you created in this run: never your own orchestrator session, a session that is still running, a session you did not create, or the Saga itself (`hagi saga archive` is not part of a run). Archiving leaves the reports, evidence and `sessions.md` record in `runtime/` untouched. Log each archived ID in `orchestrator-log.md`. If an archive call fails, log the error and go on: do not retry in a loop and do not pause for it.
 8. **Never leave a command hanging.** Every shell command must end on its own: never read from standard input, and give waits a limit. If something does not answer, report it instead of waiting forever. Every quota check is bounded as in step 2, and a dispatch that has waited six hours in total on quota pauses the Saga.
-9. **Stop** when every item is ticked or blocked, when a pause condition appears, or when the human's run options say so. Write the terminal snapshot first (`set-status --state done` only when every active item is verified, otherwise `paused` with the reason; a quota pause names the provider, the remaining percent and the reset time). Once every worker has stopped, archive any remaining worker sessions as in step 7, then run `hagi saga release <saga> --path <root> --token <token> --workers-settled`. Never archive the Saga itself and do not commit. Report the revision, every item with its state and evidence path, the blocked items with reasons, the sessions you created and which of them you archived, and the next step for a human.
+9. **Stop** when every item is ticked, blocked or waiting on a blocked item, when a pause condition appears (including an item missing from the graph or an unknown node, as in step 3), or when the human's run options say so. Write the terminal snapshot first (`set-status --state done` only when every active item is verified, otherwise `paused` with the reason; a quota pause names the provider, the remaining percent and the reset time). Once every worker has stopped, archive any remaining worker sessions as in step 7, then run `hagi saga release <saga> --path <root> --token <token> --workers-settled`. Never archive the Saga itself and do not commit. Report the revision, every item with its state and evidence path, the blocked items with reasons, the items waiting on a blocked item with the blocked item each one waits on, the sessions you created and which of them you archived, and the next step for a human.

package/skills/hagi/references/saga.md

@@ -139,6 +139,13 @@ hagi saga release demo --path "./My Project" --token "$SAGA_EXECUTION_TOKEN" --w
 - `claim --session <id>` creates the lock exclusively and returns the token once, in the human output and as `token` in
   JSON. A second claim is refused with code `1` and names the owning session. A lock is never taken over because of its
   age, and a refused claim changes no file.
+- After the lock is taken, `claim` marks the owner session as the Saga's orchestrator: it adds `saga.id` (the Saga) and
+  `saga.role=master` to that session's `userMetadata` through the backend, so the session lists show the orchestrator
+  inside the Saga's group with its Workers. The mark is best effort and never fails the claim: an owner ID that is not a
+  HagiCode session, an unreachable backend, or a session that already carries another `saga.id` is reported as
+  `master: { "marked": false, "reason": "..." }` in JSON and as `master mark    not set: <reason>` in the human output. A
+  successful mark is `master: { "sessionId": "<id>", "marked": true }`. Stored entries are never changed. Pass
+  `--no-mark-session` to skip the mark.
 - While a lock exists, a mutating command needs the holder's token. A missing or different token is refused with exit
   code `1` and changes no file. Without a lock, mutating commands run under their own gates, so a Saga created before ownership stays runnable.
 - `assert-owner` exits `0` when no lock exists or the token matches, and `1` otherwise.