@hagicode/cli 0.1.0-dev.43.1.03d9a6a → 0.1.0-dev.48.1.ce630a8

package/dist/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./chunks/main-mvnmEVmb.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-_kYHYZ-C.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-mvnmEVmb.js");exports.createCliApp=e.createCliApp;exports.runCli=e.runCli;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/main-_kYHYZ-C.js");exports.createCliApp=e.createCliApp;exports.runCli=e.runCli;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/cli",
-  "version": "0.1.0-dev.43.1.03d9a6a",
+  "version": "0.1.0-dev.48.1.ce630a8",
   "description": "HagiCode CLI for project, proposal, vault, chat, and AutoTask management.",
   "homepage": "https://github.com/HagiCode-org/cli#readme",
   "bugs": {
@@ -17,7 +17,8 @@
   "files": [
     "dist",
     "README.md",
-    "skills"
+    "skills",
+    "resources/saga"
   ],
   "packageManager": "pnpm@12.16.1",
   "engines": {
@@ -25,7 +26,7 @@
   },
   "scripts": {
     "clean": "rimraf dist",
-    "build": "export NODE_OPTIONS=\"${NODE_OPTIONS:-} --max-old-space-size=8192\"; pnpm run clean && vite build",
+    "build": "export NODE_OPTIONS=\"${NODE_OPTIONS:-} --max-old-space-size=8192\"; pnpm run clean && vite build && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
     "dev": "tsx ./src/cli.ts",
     "generate:grpc": "node ./buildTools/generate-grpc.mjs",
     "generate:grpc:check": "node ./buildTools/generate-grpc.mjs --check",

package/resources/saga/.gitignore

@@ -0,0 +1 @@
+**/runtime/

package/resources/saga/manifest.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "files": {
+    ".gitignore": "b43c8b58f191b9e0a0b54b6938c0aa4685d70b8f4ae2294c83a9ad6e728b7c0a",
+    "prompts/acceptance.md": "11ca06794d0ec19e87d1a4e883a67014563e9750b9fa62a8bedd43a69d52ca65",
+    "prompts/amend.md": "be621d1221a85656851548aee1e9e9d78480288bd856baf1bdbf50cb3317f49b",
+    "prompts/goal.md": "a545b01c9f6010df661f02cf62ef9bcae527ccf329f304ea82ffdda239b118df",
+    "prompts/plan.md": "bcc4c0509f2971083775db2b3678f41c55f16e69deba2d994d3ed636f314d917",
+    "prompts/research.md": "2504283ea845440c7909ff1da20bfb70f846d55ca16565740168848cfb8060b1",
+    "prompts/run.md": "1193fbc45645b513bbd6e1017513b62a53286d1d60fd00df479cff15de7c785b"
+  }
+}

package/resources/saga/prompts/acceptance.md

@@ -0,0 +1,15 @@
+# acceptance.md
+
+## Instruction
+Give every plan item one acceptance command. A separate verification worker runs it, so it must decide pass or fail by itself.
+
+- One heading per item: `## <ID> <name>`, followed by one line `cmd: <command>`.
+- The command runs from the project root (the folder that holds `.hagicode`), not from the saga root. Write `cd <dir> && ...` when it needs a subfolder. Exit code 0 means the item is done.
+- The command must be able to fail. A command that always passes proves nothing.
+- Every plan item has exactly one heading here, and every heading here is a plan item. If you change the command of an item that is already ticked, the next freeze reopens that item.
+
+## Template
+```
+## <ID> <name>
+cmd: <command to run from the project root>
+```

package/resources/saga/prompts/amend.md

@@ -0,0 +1,10 @@
+# Folding an amendment into a saga
+
+An amendment is a file under `<saga>/amendments/`. It is open while its `merged-in:` line is empty. Folding it in changes the planning artifacts only.
+
+1. `hagi saga status <saga> --path <root> --json` reports the current `revision` N (0 means the saga was never frozen). The merge target is `r<N+1>`.
+2. Read the amendment. Update `goal.md`, `research.md`, `acceptance.md` and `progress.md` so they agree with each other and with the amendment.
+3. Items may be added or superseded (`- ~ <ID> <name> | superseded in r<N+1>: <reason>`), never deleted. Do not touch the ticks: when an item's acceptance command changes, the next freeze reopens it.
+4. Do not decide new open questions yourself. List them under `## Open questions`.
+5. In the amendment file set `merged-in: r<N+1>`.
+6. Run `hagi saga check <saga> --phase plan --path <root>` and fix what it reports. Do not run `freeze`.

package/resources/saga/prompts/goal.md

@@ -0,0 +1,23 @@
+# goal.md
+
+## Instruction
+Write the goal contract of the saga: what it must achieve, in what scope, with which safety rules.
+
+- Every work item the saga will have must be checkable by a machine (a command that exits 0 when the item is done). Say so in the goal.
+- Write the non-goals and the block conditions (when an item is blocked instead of forced).
+- Do not write implementation details.
+- Write in the language the user used for the objective.
+- If `amendments/` holds files whose `merged-in:` line is empty, fold them in and set `merged-in: r<next revision>` in each file (see `prompts/amend.md`).
+
+## Template
+```
+## Goal
+
+## Scope
+
+## Non-goals
+
+## Safety rules
+
+## Block conditions
+```

package/resources/saga/prompts/plan.md

@@ -0,0 +1,16 @@
+# progress.md (the plan)
+
+## 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.
+- 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>`.
+- Planning ends here. Do not run `freeze`, do not start the run, do not edit project code.
+
+## Template
+```
+- [ ] <ID> <name> | 
+```

package/resources/saga/prompts/research.md

@@ -0,0 +1,16 @@
+# research.md
+
+## Instruction
+Read the project and the references the user gave. Read only: change no project file.
+
+- Record what you found: the layout, the existing conventions, the commands that run the tests, anything the plan depends on.
+- List every decision you cannot make yourself under the heading `## Open questions` (the Chinese heading `## 待决问题` also works). One line per question, starting with `- `. Leave them undecided: a human answers them before the run by rewriting a line as `- [decided: <answer>] <question>` (or `- [已决定: <结论>] <问题>`).
+- If there is nothing to decide, write `- none` under that heading.
+- If an item has no honest verification command, say so here as an open question. Do not invent a check.
+
+## Template
+```
+## Findings
+
+## Open questions
+```

package/resources/saga/prompts/run.md

@@ -0,0 +1,18 @@
+# Running a saga (the orchestrator)
+
+You are the orchestrator. You dispatch work and keep the record. You do not plan, you do not edit the contract, and you do not implement items yourself. A human started this run; starting it is the approval.
+
+`<root>` is the registered project path given in the run's input. Every command is `hagi saga <command> <saga> --path <root>` and works from any directory. Every command that changes a Saga also takes `--token <token>`: the token that `claim` printed.
+
+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.
+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:
+   - 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, quota) does not count. 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.
+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, verification and tick. Append every session you create to `<root>/.hagicode/sagas/<saga>/runtime/sessions.md`. Run `hagi saga set-status <saga> --state running --note "<heartbeat>" --path <root> --token <token>` at every heartbeat, and `hagi saga status <saga> --path <root> --json` to read the projection at the end.
+7. **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.
+8. **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), then, once every worker has stopped, `hagi saga release <saga> --path <root> --token <token> --workers-settled`. Do not archive 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 the next step for a human.

package/skills/hagi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hagi
-description: Use when the user wants to run, verify, or update the HagiCode CLI against the Hagi API, or asks about their own projects, proposals, chat sessions, vaults, scheduled plans, or installed skills, including user skills versus built-in skills, and enabling or disabling a built-in skill. Also covers the OpenSpec workflow behind proposal commands and Super Commit, which commits a code repository through a HagiTask session. Keep package-first command guidance primary, then follow the proposal flow, local development, and validation references as needed. Inside a HagiCode session, read the session-data reference first for questions about the user's own data.
+description: Use when the user wants to run, verify, or update the HagiCode CLI against the Hagi API, use local Saga initialization, creation, checks, writes, or read-only queries, or asks about their own projects, proposals, chat sessions, vaults, scheduled plans, or installed skills, including user skills versus built-in skills and enabling or disabling a built-in skill. Also covers the OpenSpec workflow behind proposal commands and Super Commit, which commits a code repository through a HagiTask session. Keep package-first command guidance primary, then follow the Saga, proposal, local development, and validation references as needed. Inside a HagiCode session, read the session-data reference first for questions about the user's own data.
 ---
 
 # Hagi
@@ -11,7 +11,9 @@ Use this skill when the user asks to:
 - list which installed skills are user skills and which are built-in skills, or which built-in skills are enabled
 - enable or disable a built-in skill
 - run or verify the `hagi` CLI
-- explain or execute `project`, `proposal`, `chat`, `hagitask`, `vault`, `plan`, or `skills` commands
+- run, explain, or verify local `saga init`, `saga new`, `saga list`, `saga status`, or `saga items` operations
+- run, explain, or verify local Saga ownership, checks, and writes: `claim`, `assert-owner`, `release`, `freeze`, `check`, `tick`, `block`, `set-status`, `amend`, `archive`
+- explain or execute `project`, `proposal`, `chat`, `hagitask`, `vault`, `plan`, `skills`, or `saga` commands
 - explain the OpenSpec workflow behind `proposal` commands, which stage each command starts, or how to follow a run until it settles
 - take turns on a shared resource (a game server, a test environment) with other agents through `hagi agent lock`
 - run, explain or check a Super Commit, which commits the uncommitted changes of a code repository through a HagiTask session
@@ -38,7 +40,8 @@ Use this skill when the user asks to:
 5. Source-tree development in `repos/cli` -> read [`references/local-development.md`](references/local-development.md)
 6. Post-change validation -> read [`references/validation.md`](references/validation.md)
 7. The user's own data, inside a HagiCode session -> read [`references/session-data.md`](references/session-data.md)
-8. A shared resource that other agents also use, or any `hagi agent lock` command -> read [`references/resource-lock.md`](references/resource-lock.md)
+8. Local Saga initialization, creation, list, status, item queries, ownership, checks, freeze, ticks, status writes, amendments, or archive -> read [`references/saga.md`](references/saga.md)
+9. A shared resource that other agents also use, or any `hagi agent lock` command -> read [`references/resource-lock.md`](references/resource-lock.md)
 
 When `hagi` is loaded as a built-in skill inside a HagiCode session, read item 7 first for any question about the user's own data or skills, before the other references.
 
@@ -84,6 +87,9 @@ The current top-level command families are:
 - `plan`
 - `skills`
 - `agent`
+- `saga`
+
+`hagi saga` provides `init`, `new`, `list`, `status`, and `items`, plus the write and check commands `claim`, `assert-owner`, `release`, `freeze`, `check`, `tick`, `block`, `set-status`, `amend`, and `archive`; mutating commands take `--token` or `SAGA_EXECUTION_TOKEN`. With `--path`, these operate on host-local files without reading backend configuration or calling the API; `--project-id` resolves a project through the backend. See [`references/saga.md`](references/saga.md) for initialization, creation, offline behavior, and read-only query guarantees.
 
 `project repositories --id <project-id>` is read-only. It lists one project's repositories with each path relative to the project root (for example `repos/cli`). Those paths are the values a proposal's `Repository scope` names; see [`references/proposal-flow.md`](references/proposal-flow.md#repository-scope).
 
@@ -116,5 +122,6 @@ Each family also reads one session by id. `proposal get` and `hagitask get` read
 - [`references/openspec-workflow.md`](references/openspec-workflow.md) - the OpenSpec stage each proposal command starts, stage boundaries, who drives each step, and the monitoring rule
 - [`references/super-commit.md`](references/super-commit.md) - Super Commit: starting it by prompt id, its options, result reading and the explicit-request rule
 - [`references/resource-lock.md`](references/resource-lock.md) - the shared resource lock: numbers, owner, exit codes, the watcher protocol, the seven agent rules and requisition
+- [`references/saga.md`](references/saga.md) - local initialization, creation, ownership, checks, Saga writes, and read-only queries
 - [`references/local-development.md`](references/local-development.md) - maintainer-only development, build, and repository internals
 - [`references/validation.md`](references/validation.md) - targeted verification after documentation or code changes

package/skills/hagi/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Hagi CLI"
-  short_description: "Answer questions about your HagiCode data and skills, operate the hagi CLI, follow the OpenSpec workflow, and run a Super Commit."
-  default_prompt: "Use $hagi to look up your projects, proposals, sessions, vaults, plans, or skills, to follow the OpenSpec workflow of a proposal, to run a Super Commit, to enable or disable a built-in skill, or to inspect, run, or update the HagiCode CLI in repos/cli."
+  short_description: "Operate the hagi CLI, including local Saga commands, and work with HagiCode data, skills, proposals, and Super Commit."
+  default_prompt: "Use $hagi to operate local Saga init, new, list, status, or items commands and the Saga ownership, check, freeze, tick, set-status, amend, and archive commands; look up HagiCode projects, proposals, sessions, vaults, plans, or skills; follow a proposal's OpenSpec workflow; run a Super Commit; enable or disable a built-in skill; or inspect, run, or update the CLI in repos/cli."
 
 policy:
   allow_implicit_invocation: true

package/skills/hagi/references/cli-usage.md

@@ -35,6 +35,7 @@ For one-off execution, replace `hagi` with `npx @hagicode/cli`.
 hagi --help
 hagi project list --json
 hagi proposal list --json
+hagi saga list --path .
 hagi chat list --json
 hagi hagitask list --json
 hagi hagitask create --title "Auto commit" --project-id <project-id> --prompt-id auto-compose-commit.en-US
@@ -55,9 +56,11 @@ Example:
 hagi --base-url https://api.example.com --token "$HAGI_TOKEN" project list --json
 ```
 
+Saga commands using `--path` accept these flags but do not read backend configuration or contact the backend.
+
 ## Environment variables
 
-The CLI resolves runtime settings centrally before every command.
+Backend operations resolve runtime settings centrally before accessing the API.
 Explicit flags always override environment variables.
 
 | Variable | Purpose |
@@ -78,7 +81,9 @@ The base URL can also be stored in a local config file:
 The file is `$XDG_CONFIG_HOME/hagi/config.json`, or `~/.config/hagi/config.json` when `XDG_CONFIG_HOME` is unset. The `steer` key must be `true` or `false`; any other value exits with code `2` and names the file.
 
 Base URL precedence, highest first: `--base-url`, then `HAGI_API_BASE_URL`, then `baseUrl` in the config file.
-There is no default. When none of the three is set, the CLI exits with code `2` and names all three sources.
+There is no default. When none of the three is set, a backend operation exits with code `2` and names all three sources.
+The local Saga selector `--path` is the exception: it does not read this file, so malformed, unreachable, or absent backend
+settings do not affect that local operation.
 
 ## Command overview
 
@@ -87,6 +92,7 @@ hagi
 |-- project   list | repositories | create | update | delete
 |   `-- monospecs show | init | set | validate | reload | clone | remove-checkout
 |-- proposal  list | create | optimize-description | generate | annotate | execute | archive | status | complete | send | get | messages
+|-- saga      init | new | list | status | items | claim | assert-owner | release | freeze | check | tick | block | set-status | amend | archive
 |-- vault     list | create | update | delete
 |   `-- files list | preview
 |-- chat      list | create | archive | delete | send
@@ -98,6 +104,33 @@ hagi
 `-- agent     lock acquire | status | renew | heartbeat | release | requisition | list
 ```
 
+## Saga commands
+
+Each command requires exactly one nonempty project selector:
+
+- `--path <directory>` resolves a local directory on the CLI host. Relative paths use the current working directory. This
+  selector does not read backend configuration or make API calls, and shared backend flags do not change its behavior.
+- `--project-id <id>` reads the project list through the configured backend. Its project path must be a directory available
+  on the machine running the CLI; the CLI does not execute filesystem operations remotely.
+
+Missing, empty, or conflicting selectors exit `2` before backend access or file writes. Paths with spaces should be quoted.
+Shared `--base-url`, `--token`, `--lang`, and `--json` options are accepted.
+
+```bash
+hagi saga init --path "./My Project"
+hagi saga new demo --path "./My Project" --json
+hagi saga list --path "./My Project"
+hagi saga status demo --project-id <project-id> --json
+hagi saga items demo --path "./My Project" --json
+hagi saga claim demo --path "./My Project" --session orchestrator-1 --json
+hagi saga check demo --path "./My Project" --phase run --json
+hagi saga tick demo T1 --path "./My Project" --token "$SAGA_EXECUTION_TOKEN" --json
+```
+
+For offline use, invoke an installed package or a package already present in the `npx` cache. An uncached
+`npx @hagicode/cli` command may need network access to download the package; the local `--path` operation itself does not
+need backend access.
+
 ## Project repositories
 
 `project repositories --id <project-id>` is read-only. It reads the same aggregation snapshot as `project list` and prints one project's repositories: name, path relative to the project root (for example `repos/cli`), display name, type and branch, with the project's MonoSpecs flag. The `path` values are the ones a proposal's `Repository scope` names.

package/skills/hagi/references/local-development.md

@@ -63,6 +63,16 @@ The DTO types in `src/generated/api/models` are committed and maintained by hand
 generated: the backend's OpenAPI document now lists only the retained REST routes, so regenerating from it would delete the
 types of every removed route. When a proto DTO changes, edit or add the matching type there.
 
+## Saga asset bundle
+
+The Saga resources are owned by this repository. `resources/saga/` contains the six method prompt files, `.gitignore`,
+and `manifest.json`; there is no standalone Saga tool and no sync step. Keep the bytes raw: do not render templates or
+normalize line endings. The manifest uses schema version `1` and sorted POSIX relative paths mapped to lowercase SHA-256
+digests; it does not hash itself.
+
+After editing a prompt, update its digest in `manifest.json`. `tests/runtime/saga/assets.test.ts` fails on any mismatch
+between the files and the manifest, and `pnpm run pack:check` verifies the published contents.
+
 ## Release automation
 
 GitHub workflows under `.github/workflows/` handle release drafting and npm publishing.

package/skills/hagi/references/saga.md

@@ -0,0 +1,189 @@
+# Saga commands
+
+Saga files are project-local. Select exactly one project with `--path <directory>` or `--project-id <id>` for every
+Saga command. A local `--path` is resolved on the CLI host and does not read backend configuration or make API calls.
+
+## Initialize managed resources
+
+Run `init` before creating a Saga:
+
+```bash
+hagi saga init --path "./My Project"
+hagi saga init --path "./My Project" --force --json
+```
+
+Initialization installs the six bundled method prompts and the ignore template under `.hagicode/sagas`. It does not repair
+or overwrite existing Saga contracts, metadata, or runtime records.
+
+By default, differing managed resources are preserved as conflicts while missing nonconflicting resources are still
+installed. The command prints each file's `created`, `unchanged`, `merged`, `replaced`, or `conflict` outcome and exits
+with code `4` if any conflicts remain. Use `--force` to replace differing managed resources with the bundled versions;
+identical resources remain untouched. Forced initialization never discards custom `.gitignore` entries.
+
+The `.gitignore` rule `**/runtime/` is merged as a separate exact line. Existing bytes, line endings, and entries are
+preserved; LF and CRLF files are supported, and repeated initialization does not append duplicate rules.
+
+Before writing, initialization checks that managed directories and files are not redirected, that resource targets are
+regular files, and that writes will not replace unsafe hard-linked resources. Refused targets are reported as operation
+failures rather than followed outside the selected project. Exact resources are not rewritten on repeat runs, preserving
+their modes and modification times.
+
+With `--json`, stdout contains the installation root, `force` setting, per-file `path`/`outcome` entries, and any
+conflicts. A conflict report is still emitted before the command reports the code-4 error on stderr.
+
+## Create and inspect Sagas
+
+`new <saga-id>` creates the Saga natively: it reserves `<saga-id>/` with an exclusive directory creation and writes
+`saga.json` with `id`, `createdAt`, and `method`. It writes no runtime file. IDs must
+match `^[a-z0-9][a-z0-9-]{0,62}$`: one to 63 lowercase letters, digits, or hyphens, beginning with a letter or digit. The
+reserved names are `prompts`, `tools`, `archive`, `runtime`, `amendments`, and `revisions`. Invalid IDs are usage errors
+(code `2`). An existing active path or an archive entry whose name ends in `-<saga-id>` is a collision; creation is
+refused with code `30` and neither Saga is changed. Concurrent creations of one ID leave exactly one Saga.
+
+The `--json` result identifies the Saga directory and includes the metadata written to `saga.json`:
+
+```json
+{
+  "id": "demo",
+  "directory": "/path/to/My Project/.hagicode/sagas/demo",
+  "metadata": {
+    "id": "demo",
+    "createdAt": "2026-01-01T00:00:00Z",
+    "method": 1
+  }
+}
+```
+
+The human result names the installed goal prompt and the four planning files to write. From the project root, the prompt is
+`.hagicode/sagas/prompts/goal.md`; the planning files are `goal.md`, `research.md`, `acceptance.md`, and `progress.md`.
+
+Then inspect the Saga with the read-only commands:
+
+```bash
+hagi saga new demo --path "./My Project" --json
+hagi saga status demo --path "./My Project" --json
+hagi saga list --path "./My Project"
+hagi saga items demo --path "./My Project" --json
+```
+
+### Query payloads and read-only behavior
+
+`list --json` returns `{ "sagas": [...] }`; each row contains `sagaId`, `state`, `revision`, `counts`, `openAmendments`,
+and `updatedAt`. `items <saga-id> --json` returns `{ "sagaId": "...", "items": [...] }`, with each item carrying its
+canonical `id`, `title`, `state`, `cmd`, and `note`.
+
+`status <saga-id> --json` returns the `saga-status/2` projection directly, with `schema`, `sagaId`, `revision`, `state`,
+`updatedAt`, `note`, `artifacts`, `nextArtifact`, `counts`, `openAmendments`, and `items`. It derives this view from the
+Saga files; `updatedAt` is the time of this observation, not the execution heartbeat in `runtime/status.json`. The query
+does not refresh or rewrite that stored status, and its default `note` is empty rather than a cached execution note.
+
+All three queries are strictly read-only: they do not initialize or repair resources, create runtime files, run the Saga
+tool, or execute acceptance commands. Missing optional draft files use canonical empty-data behavior; malformed or
+unreadable existing data is reported instead of being repaired. ## Execution ownership and the token
+
+`claim`, `assert-owner`, and `release` manage `runtime/execute.lock`. Every mutating command (`freeze`, `tick`, `block`,
+`set-status`, `amend`, `archive`, `release`, `assert-owner`) reads the execution token from `--token <token>` or, when
+that flag is absent, from `SAGA_EXECUTION_TOKEN`.
+
+```bash
+hagi saga claim demo --path "./My Project" --session orchestrator-1
+hagi saga assert-owner demo --path "./My Project" --token "$SAGA_EXECUTION_TOKEN"
+hagi saga release demo --path "./My Project" --token "$SAGA_EXECUTION_TOKEN" --workers-settled --json
+```
+
+- `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.
+- 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.
+- `release` removes the lock only for the holder, with `--workers-settled`, and only when `runtime/status.json` records
+  `paused` or `done`. Any other case exits `1` and keeps the lock.
+- `status`, `items`, `list`, and `check` need no token and never write.
+- With `--project-id`, the root `--token` is the backend bearer token, so `--token` is rejected with `--project-id` as a
+  usage error (code `2`) that explains the rule. Pass the execution token through `SAGA_EXECUTION_TOKEN` instead. An execution token is never sent to the backend.
+
+## Plan check and freeze
+
+```bash
+hagi saga check demo --path "./My Project" --phase plan
+hagi saga check demo --path "./My Project" --phase run --json
+hagi saga freeze demo --path "./My Project" --token "$SAGA_EXECUTION_TOKEN" --json
+```
+
+`check --phase plan` passes when `goal.md`, `research.md`, `acceptance.md`, and `progress.md` exist, `progress.md` has at
+least one active item, every active item has an acceptance `cmd:`, and every acceptance entry names an active item.
+`check --phase run` is the default; it adds the frozen-contract hash comparison, the amendment and open-question gates,
+and the proof of every ticked item (an evidence file and a `Status: PASS` or `状态: PASS` report). Any other `--phase`
+value is a usage error (code `2`). Checks write nothing.
+
+`freeze` writes `contract.lock` revision 1 for a valid first contract. A repeat on an unchanged contract exits `0`, reports
+the existing revision, and leaves the lock bytes intact. After a contract change, freeze writes revision N+1 only when an
+amendment is merged into `rN+1` and no frozen item disappeared without a superseded row. The previous lock moves to
+`revisions/rN.lock`, each ticked item whose acceptance command changed is reopened, and its evidence and report move to
+`runtime/history/rN/`. Every refusal (open question, unmerged amendment, plan mismatch, tampered contract, removed item)
+lists each reason, exits `1`, and writes nothing.
+
+## Items, amendments, and archive
+
+```bash
+hagi saga tick demo T1 --path "./My Project" --token "$SAGA_EXECUTION_TOKEN" --json
+hagi saga block demo T2 "tests keep failing" --path "./My Project" --token "$SAGA_EXECUTION_TOKEN"
+hagi saga amend demo "Add retry" "Retry twice on timeout" --path "./My Project" --token "$SAGA_EXECUTION_TOKEN"
+hagi saga archive demo --path "./My Project" --token "$SAGA_EXECUTION_TOKEN" --json
+```
+
+- `tick` marks an active item done in `progress.md` as `- [x] <id> <title> | evidence/<id>.log`. It needs a PASS report at
+  `runtime/reports/<id>.md`, the evidence file, and a passing run check; otherwise it exits `1` and keeps `progress.md`.
+  A successful tick clears that item's blocker. Item IDs containing a path separator or `.`/`..` are refused before any
+  file access.
+- `block` records a reason for an active item in `runtime/blocked.json`. An unknown item is refused. An empty reason is a
+  usage error (code `2`).
+- `amend` appends the next numbered file, `amendments/<NNN>-<slug>.md`, with an empty `merged-in:` header; the new
+  amendment is open until the contract merges it. An empty title is a usage error (code `2`).
+- `archive` moves a finished Saga (every active item done, no open amendment) to `archive/<date>-<saga-id>`. Use
+  `--force` to archive unfinished work. An existing destination is refused even with `--force`.
+
+## Status snapshot
+
+```bash
+hagi saga set-status demo --state paused --note "freeze refused" --path "./My Project" --token "$SAGA_EXECUTION_TOKEN" --json
+```
+
+`set-status --state` accepts `draft`, `planned`, `running`, `paused`, or `done`; any other value (or a missing value) is a
+usage error (code `2`) and writes no file. The snapshot is the same `saga-status/2` projection that `status` reports, with
+only `state` and `note` replaced. `planned` and `running` require the plan check to pass. `done` requires every active
+item to be done with its evidence and PASS report, a frozen and unchanged contract, no open amendment, and no undecided
+research question. A refusal exits `1`, lists its reasons, and leaves the stored `runtime/status.json` unchanged. The file
+is replaced atomically, so a concurrent reader always sees a complete document.
+
+## Exit codes and JSON
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success. |
+| `1` | Refusal or failed check. Every reason is printed; nothing was changed. |
+| `2` | Usage error: bad selector, missing or invalid argument, or `--token` with `--project-id`. |
+| `4` | Init resource conflict (see above). |
+| `24` | Saga or project not found. |
+| `30` | Operation failed, including a `new` collision. |
+
+Write and check commands accept `--json`. Success and refusal write one object to stdout:
+
+```json
+{ "sagaId": "demo", "command": "tick", "ok": true, "itemId": "T1", "evidence": "evidence/T1.log" }
+{ "sagaId": "demo", "command": "tick", "ok": false, "errors": ["no PASS report for T1: runtime/reports/T1.md must contain \"Status: PASS\""] }
+```
+
+Human output prints a one-line outcome and one line per refusal reason.
+
+## Runtime ignore precondition
+
+Before any command writes a file under a Saga's `runtime/` directory (`claim`, `set-status`, `tick`, `block`, and a
+`freeze` that moves history), it makes sure `.hagicode/sagas/.gitignore` ignores runtime directories. An existing
+`**/runtime/` line is kept byte for byte; otherwise `**/runtime/` is appended with the file's line endings.
+If the ignore file cannot be written, the command stops before `runtime/` is created.
+
+## Read-only projection and ownership
+
+Every write and check command is implemented by the CLI and never executes a separate tool. The CLI installs only the method prompts and the ignore rule; there is no installed tool to run.

package/skills/hagi/references/session-data.md

@@ -98,6 +98,19 @@ hagi plan list --json
 hagi plan get --id <plan-id> --json
 ```
 
+### Sagas
+
+```bash
+hagi saga list --project-id <project-id> --json
+hagi saga status <saga-id> --project-id <project-id> --json
+hagi saga items <saga-id> --project-id <project-id> --json
+```
+
+These queries read the selected project's Saga files without initializing or repairing them, refreshing runtime status,
+or executing acceptance commands. Status is a fresh `saga-status/2` observation; its `updatedAt` is not the stored
+execution heartbeat in `runtime/status.json`. `init` installs resources and `new` creates a Saga, so run either only
+when the user explicitly asks for that change. Contract and lifecycle operations run through `hagi saga` with the execution token rules in `references/saga.md`.
+
 ### Skills
 
 ```bash
@@ -128,6 +141,7 @@ A question such as "what is in my plan" is not a request to run, enable, disable
 | `chat` | `create`, `archive`, `delete`, `send` |
 | `hagitask` | `create`, `send` |
 | `plan` | `create`, `update`, `enable`, `disable`, `delete`, `run` |
+| `saga` | `init`, `new` |
 | `skills` | `local enable`, `local disable`, `local uninstall`, `gallery install`, `trusted upsert`, `trusted delete`, `trusted reset` |
 
 A `send` or `run` starts agent work, and `execute` and `generate` start it too. Treat those as changes of the same kind.

package/skills/hagi/references/validation.md

@@ -135,11 +135,15 @@ If only a specific command changed, also verify that command's help directly.
 
 ## Package publish-surface check
 
-Run this only when `package.json`, publish contents, or release metadata changed:
+Run this when `package.json`, publish contents, or release metadata changed. The Saga asset check and the package check
+are offline:
 
 ```bash
 cd repos/cli
+pnpm exec vitest run tests/runtime/saga/assets.test.ts
 pnpm run pack:check
 ```
 
-The npm tarball ships `dist` and `README.md` only (`package.json` `files`), so `skills/**` is not in the package. The skill reaches users through the repository and the server's built-in skill copy, not through npm. Change `files` only if that decision changes.
+The npm tarball ships `dist`, `README.md`, `skills/**`, and only
+the allowlisted Saga resources, including the hidden `.gitignore` template. `pack:check` verifies the actual package
+contents and rejects source maps or unexpected resource files.