@synopackageland/cli 0.5.0 → 0.6.0

package/skills/SKILL.md

@@ -1,7 +1,25 @@
+---
+name: synopkgland-sdk
+description: Initialize, extend, check, build, inspect, and deploy Synology applications with the synopkgland CLI and schema 2 capabilities.
+---
+
 # Independent Synology SPKs
 
-Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 禁止發明已完成的登入橋接、逐使用者檔案 ACL 或新身分平台。
+Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 為 P2 整合中，禁止發明已完成的離線委託或新身分平台。
+
+Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. Container authentication belongs to upstream; fixed service credentials govern mounted data access.
+
+Never install, uninstall, publish or modify NAS data without task authorization. Prefer check, inspect and deploy --dry-run for reviewable artifacts.
+
+Native projects use schema 2 capabilities and `--with files,jobs,login,root-ops`; use `add` for existing projects. Prefer `check --json`, `build --json`, `inspect <spk> --json`, `deploy --dry-run --json`, and `status --host <profile> --json` for structured results. Read the conflict policy in reference/create.md before adding overlays.
+
+Read reference/files.md and reference/identity.md for capability boundaries. RootOps currently uses individual administrator task approval; P2 will share one-time protected executor setup with delegate. App sessions alone do not grant NAS file authority.
+
+Read [reference/ui-vue.md](reference/ui-vue.md) when editing Vue components in the native-go Vue template; use the installed SDK contracts, keep DSM embedding boundaries, and verify the actual app.
 
-Start with `synopkgland init -t native-go`, `synopkgland init --binary`, or `synopkgland init -t compose-import`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. Container authentication belongs to upstream; fixed service credentials govern mounted data access.
+Read [reference/ui-json.md](reference/ui-json.md) when generating or editing JSON UI; discover the installed catalog, validate the spec, then render and fix layout issues.
 
-Never install, uninstall, publish or modify NAS data without task authorization. Prefer validate, inspect and deploy --dry-run for reviewable artifacts.
+For UI discovery, run `npx --no syno-pkg-land-ui catalog --json` and
+`npx --no syno-pkg-land-ui describe Button --json` from the installed frontend.
+Read its prompt and exported Vue docs/types before choosing component APIs.
+Use `syno-pkg-land-ui` directly in npm scripts; keep AI guidance version-independent.

package/skills/reference/create.md

@@ -1,25 +1,34 @@
 # 建立（Create）
 
-先選擇 `native-go`（Go CGI + DSM 視窗）、`binary`（預建服務程式）或 `compose-import`（上游容器）。`hello-web` 與 `hello-web-page` 分別示範 DSM 視窗及新分頁入口；`hello-files` 示範 Share 與固定 run-as 使用者。
+先選擇 `native-go`（Go CGI + DSM 視窗）、`binary`（預建服務程式）或 `compose`（上游容器）。`compose` 預設示範 Share 與固定 run-as 使用者，`--from <compose.yaml>` 匯入現有 Compose。
 
 ```sh
-synopkgland init -t native-go --package MyApp my-app
-synopkgland init --binary service
-synopkgland init -t compose-import upstream-app
+synopkgland init -t native-go --with files,jobs,login --package MyApp my-app
+synopkgland init -t binary service
+synopkgland init -t compose --from ./compose.yaml upstream-app
 ```
 
 容器沿用上游登入。包現成 Compose 時保留 upstream target，只把 host source 換成 `${PARAM}`；管理員在安裝時選 Share。不要硬編碼 NAS 路徑，不要以固定 UID/GID 冒充逐使用者 ACL。
 
 ## Published port
 
-hello-web 預設 published port 是 18333。每個 package／instance 都要分配獨立的 port；同一台 NAS 上不要重用。可挑選未使用的 19xxx 高位 port，例如 19160；同時修改 contract adminport 與 Compose published port，保留容器內 target。
+有 Web 入口的 Compose 專案需要 published port。每個 package／instance 都要分配獨立的 port；同一台 NAS 上不要重用。可挑選未使用的 19xxx 高位 port，例如 19160；同時修改 contract adminport 與 Compose published port，保留容器內 target。
 
 ## 容器存取控制
 
-有 adminport 的容器 App 預設經 DSM 驗證 gateway（`integration.web.access`：dsm-users 預設、dsm-admins、dsm-groups＋groups、public）。Compose published port 必須綁 loopback：`127.0.0.1:<adminport>:<port>`，否則 validate 失敗（`COMPOSE_GATEWAY_PORT_EXPOSED`）。gateway 是編譯的 Go，建置需要 Go 與 `--arch`。`public` 才保留匿名 Web Station portal，inspect 會以 `CONTAINER_ANONYMOUS_PORTAL` 提醒。
+有 adminport 的容器 App 預設經 DSM 驗證 gateway（`integration.web.access`：dsm-users 預設、dsm-admins、dsm-groups＋groups、public）。Compose published port 必須綁 loopback：`127.0.0.1:<adminport>:<port>`，否則 check 失敗（`COMPOSE_GATEWAY_PORT_EXPOSED`）。gateway 是編譯的 Go，建置需要 Go 與 `--arch`。`public` 才保留匿名 Web Station portal，inspect 會以 `CONTAINER_ANONYMOUS_PORTAL` 提醒。
 
 ## 建置與檢查
 
-執行 validate、build-spk、inspect --spk，再看 deploy --dry-run。Go CGI 每包驗證 DSM session，root 模式只提供固定管理員核准工作。容器必須使用已建置映像；不支援的特權 host 存取、secret/config 與 build stanza 會拒絕。
+執行 check、build、inspect，再看 deploy --dry-run。Go CGI 每包驗證 DSM session，root-ops 能力只提供固定管理員核准工作。容器必須使用已建置映像；不支援的特權 host 存取、secret/config 與 build stanza 會拒絕。
 
 安裝前讀 deploy.md。需要資料或登入時讀 files.md、identity.md；不加入尚未實作的 bridge。
+
+## Schema 2 能力
+
+native-go 與 binary 使用 `dsm-package.yaml` 的 `schema: 2`，backend 寫 `kind: go, dir: backend` 或 `kind: binary, files: {x86_64: prebuilt/api-x86_64}`。
+`--with files,jobs,login,root-ops` 分別宣告 `capabilities.files: session`、`jobs: true`、`identity: standalone`、`rootOps: true`。jobs 可寫 `{worker: sha256-v1}`，與 daemon 互斥；delegate 尚未實作（P2）。binary／compose 不支援 files／jobs／login／delegate。
+既有 native-go 專案用 `synopkgland add files jobs login`；已存在能力回報 no-op。overlay 檔案已有不同內容或 stub 被改動時，add 拒絕並列出衝突；不修改業務 routes 或 App.vue。
+check、inspect、build、deploy、status 支援 `--json`，stdout 只有單一 JSON 物件，錯誤包含 code、message、hint；進度在 stderr。
+
+目前 rootOps 仍需 native-Go 管理員核准 adapter；P2 改為與 delegate 共用一次密碼 executor 設定，仍待整合。SDK off stub 與 routes_test.go 的預設 policy scaffold 只有內容仍等於 bundled base 時才會替換；App 自訂版本拒絕。

package/skills/reference/deploy.md

@@ -1,10 +1,12 @@
 # Build and deploy
 
-1. Run `synopkgland validate` and `synopkgland build-spk --arch x86_64` (use aarch64 for that target).
-2. Inspect the resulting file with `synopkgland inspect --spk <file>`.
+1. Run `synopkgland check` and `synopkgland build --arch x86_64` (use aarch64 for that target).
+2. Inspect the resulting file with `synopkgland inspect <file>`.
 3. Review `synopkgland deploy --dry-run --arch x86_64`, which does not connect to a NAS.
 4. Only when installation is authorized, run `synopkgland deploy --host <profile>`.
 
 Deployment uploads directly to DSM. It does not publish artifacts. Container install answers use --share, --run-as and --param; omitted upgrade answers are retained by package preinst, which also rejects missing newly required values.
 
-For native-go root, approve fixed operations in DSM after installation. Updates that change the task text require fresh approval. Remove tasks before uninstall. Never delete installed packages or data as part of a code cleanup.
+For native-go root-ops, approve fixed operations in DSM after installation. Updates that change the task text require fresh approval. Remove tasks before uninstall. Never delete installed packages or data as part of a code cleanup.
+
+5. After installation run `synopkgland status --host <profile> --json`; inspect every capability state and Open URL. Installation is not readiness. P2 shared executor setup, integrated reboot/upgrade and cleanup still need acceptance. Delete App Data is not evidence of complete cleanup; verify retained directories/account artifacts.

package/skills/reference/diagnose.md

@@ -1,6 +1,6 @@
 # Diagnose
 
-Start with validate and inspect. For DSM broken / 150 inspect Package Center status, including broken_by=install_corruption, and whether a required port 被占用. `info` reads package state; `log` reads package status, not app stdout streaming.
+Start with check; inspect the built SPK. For DSM broken / 150 inspect Package Center status, including broken_by=install_corruption, and whether a required port 被占用. `status` reads package state; `logs` reads package status, not app stdout streaming.
 
 The independent container path uses resource-worker lifecycle. Unsupported Compose settings fail before build; there is no alternate installer. COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN means DSM may strip quoting from 純數字 command 元素. Use a single shell command when appropriate, for example `command: ["sh","-c","httpd -f -p 18333 -h /srv"]`.
 

package/skills/reference/files.md

@@ -1,11 +1,13 @@
-# 檔案（Files）
+# 檔案與背景工作
 
-管理員在安裝時選 Share，並指定 Container Run-as 的 DSM 使用者。容器路徑依 Compose／映像的 upstream target；只替換 host source，保留 target 與 ro/rw。固定 UID/GID 與 supplementary groups 決定整個服務的檔案存取，並非目前瀏覽器使用者的 DSM ACL。
+Native-go 的 B 能力使用 `init --with files` 或 `add files`，對應 schema 2 `capabilities.files: session`。File tree 與共用 NasPicker 以 TreeView／DataGrid 顯示本人可見內容；選取路徑不建立授權。FilePicker 選瀏覽器本機檔案。上傳／下載使用 streaming transport，不把內容放進 JSON。每次以呼叫者有效 DSM session 由 File Station 判權，不需管理員進行能力設定。
 
-App Data 使用 package var；外部 Share 與 named volume 各有自己的備份及生命週期。不要更改上游 target 以配合範例，不要對現有資料 chown。選擇另一個 run-as 使用者不會自動轉移舊檔案所有權。
+只有 App session 沒有有效 DSM cookie 時回 `dsm_session_required`，須在同 hostname 登入 DSM。不能以套件帳號或 root 作後備存取。
 
-`posix_all_shares` 僅支援 CLI deploy 的管理員 Share 快照；安裝後新增的 Share 不會自動掛入。一般情況用明確 shared_folder。
+A 能力 `--with jobs` 使用套件帳號處理已匯入的私有副本，依可信 username／UID 綁定；一般使用者不需 admin 設定即可提交、查詢與取消自己的工作。關閉瀏覽器後繼續，不保存 cookie／SID／密碼。匯入需要本人在線 session；私有副本不是離線讀取原檔案的權限。Jobs 與 daemon 互斥。
 
-App 自行保存敏感設定；此工具不提供自動 secret 產生／注入，也沒有廣域 files.* 能力。逐登入者的 NAS 檔案 bridge 尚未實作，須另行設計可信任身份交接及使用者授權。
+C 能力 delegate 為 P2 整合中，目前 CLI 拒絕。規劃 admin 確認一次密碼設定 executor；使用者委託／撤銷，綁定 job／operations／scope／期限。DSM runner 與降權寫檔依本人權限執行；scope 限制使用範圍，不是權限邊界。每次重驗帳號與 AppPriv，停用或拒絕即阻擋。不宣稱完整生命週期已驗證。
 
-使用 validate 與 inspect 檢查路徑，再依 deploy.md 安裝。不要因檔案存取失敗改用 root。
+容器使用固定 DSM run-as 使用者與掛載，不代表瀏覽器本人 ACL。容器路徑依 Compose／映像的 upstream target，保留 target、ro/rw，只替換 host source；管理員在安裝時選擇 Share（共用資料夾）。不要對既有資料 chown。App Data 使用 package var；共用資料夾與 named volume 分別備份。`posix_all_shares` 僅為部署時快照，不會自動加入新資料夾。
+
+`install.sharedFolder` 使用套件帳號：select 模式安裝後可能須管理員手動授予權限，create 由 DSM data-share 建立；都不是逐使用者 session access。移除不刪共用資料夾。Delete App Data 不是完整清理證明，須讀回殘留。

package/skills/reference/identity.md

@@ -1,5 +1,11 @@
-# Identity boundaries
+# Identity and authorization
 
-native-go includes per-package CGI DSM session validation. Preserve it when extending the app, and make app authorization explicit. Do not treat login alone as file permission or root authorization.
+Native-go validates the caller's DSM session per package. Business route permissions come from backend/internal/api/permissions.json; SDK-owned route policy is protected separately. Capabilities describe execution/resources and do not grant business route access. Never trust a request username as owner.
 
-OSS defaults to upstream authentication. A fixed service UID/GID does not identify the browser user. Bare DSM-to-app session handoff and a trusted user-aware file bridge are separate future designs, not implemented features. Optional standards-based login requires an actual provider and app interoperability validation. Do not create a mandatory shared service or invent a completed bridge.
+I capability: init --with login or add login enables Go-native standalone identity and Vue login. Same-host DSM cookies can be reused across ports after backend verification. Missing cookies use an HTTPS DSM account/password/OTP fallback; passwords and DSM credentials are not persisted. Plain UI is unsupported. App sessions last at most 15 minutes; sensitive operations revalidate live DSM cookies and local UID. Password-only sessions permit only basic app.status/greeting.get reads. Missing revalidation returns session_revalidation_required; files return dsm_session_required. Sign in to DSM on the same hostname. Web Station portal/proxy acceptance remains pending.
+
+B files needs the current user's DSM session. A jobs processes owner-bound private copies as the package account without administrator setup. Neither App identity nor login alone grants offline File Station access.
+
+C delegate is P2 integration in progress and rejected by the current CLI. Planned grants bind verified subject/uid, job, operations, scope and expiry. The executor rechecks account enablement and AppPriv and dispatches with the user's own permissions. User/admin revocation is required. R exposes only fixed admin operations; current approval is per operation. P2 shares one-time password-confirmed, digest-locked executor setup and reboot boot task between C/R. Do not invent final API names or claim complete cleanup before integration acceptance.
+
+Compose uses its DSM gateway plus upstream authentication. A fixed service UID/GID identifies the service, not the browser user. Do not infer general SSO or per-user file authority from a service mount.

package/skills/reference/ui-json.md

@@ -0,0 +1,78 @@
+# JSON UI for DSM apps
+
+Use the project's installed `@synopackageland/ui` from the frontend directory.
+Run `npm ci` first if dependencies are missing. Run `npx --no syno-pkg-land-ui <command>`
+to use the package bin, or add `node_modules/.bin` to PATH and use `syno-pkg-land-ui <command>`
+for the commands below. Discovery and validation must use the app's installed SDK
+and lockfile. If the installed bin is missing, report the missing CLI and stop the
+self-check instead of silently fetching another version or claiming success.
+Check the installed package CLI usage for its supported options.
+
+## Discover before generating
+
+```sh
+npx --no syno-pkg-land-ui prompt
+npx --no syno-pkg-land-ui catalog --json
+npx --no syno-pkg-land-ui schema
+npx --no syno-pkg-land-ui describe AppRoot --json
+npx --no syno-pkg-land-ui describe AppShell --json
+```
+
+Read these outputs and describe each additional component you need. Use the
+current schema, props, slots and events; do not copy an old catalog or guess APIs.
+Generate a JSON object containing `root`, `elements` and optional `state`. Seed
+every state path you bind. Use only catalog components and real app-owned actions,
+computed functions and message keys. Keep NAS pickers, native DSM bridges,
+authorization, polling and domain-specific views in Vue/TypeScript extensions.
+
+## Validate, fix, render
+
+After saving the generated spec as `ui.json`, run:
+
+```sh
+npx --no syno-pkg-land-ui validate ui.json --json --strict
+```
+
+Pass the actual host contracts when needed: `--actions save,refresh`,
+`--functions formatBytes`, `--state host-state.json`, and
+`--messages messages/en.json`. Register these same handlers and functions in
+the app; declaring their names to the checker does not implement them. For i18n,
+register the renderer's `t` function and supply the real message catalog.
+
+Fix every reported JSON Pointer `path` using its `hint`, then validate again
+until exit 0 with no warnings. Next run:
+
+```sh
+npx --no syno-pkg-land-ui render ui.json --json --strict --widths 390,700,960,1350 --out shots
+```
+
+Render needs Node 22 or newer and local Chrome/Chromium; set `CHROME` to its
+executable if discovery fails. Supply the same state/messages and any supported
+host declarations used for validation. Inspect the screenshots and every issue's
+spec key, especially `outside_viewport` and `clipped_content`; fix the spec and
+repeat both checks. Use other widths/heights when the target requires them.
+
+Exit 0 means the check passed; exit 1 means spec errors, strict warnings or layout
+issues; exit 2 means input/usage/browser failure. A browser failure is not a pass.
+Hand over the spec only after validate and render both exit 0. Preserve screenshots
+as review artifacts outside the repository. The built-in preview cannot execute
+the application's backend actions or custom renderers, so verify those separately
+in the real app before claiming interaction or DSM acceptance.
+
+## Embed in the existing Vue app
+
+Use `SynoJsonRenderer` and `Spec` from `@synopackageland/ui/json`; keep host
+handlers and extensions in app code. For constrained generation, the package
+also exports `@synopackageland/ui/json-catalog.schema.json` and
+`@synopackageland/ui/json-ai-prompt.md`.
+
+In DSM windows, keep a bounded `AppRoot` (for example `height: 100%`), use its
+default app modal scope or explicit `modalScope: "app"`, and set JSON `AppShell`
+`wideLayout: "window"`. Vue `AppLayout` uses `wide-layout="window"`. Reserve
+root sizing for the Vue/host wrapper; only use props exposed by the current JSON
+schema inside the spec. Reserve
+`modalScope: "document"` and `wideLayout: "web"` for whole-page web/Portal apps.
+Let the DSM host set AppWindow `minWidth` to 700px; do not force it through CSS.
+Import only `@synopackageland/ui/themes/dsm7-embedded.css` (or its embedded
+reset/theme pair), and assign a unique `app.config.idPrefix` before each mount.
+Follow the existing template's mount, unmount and host subscription lifecycle.

package/skills/reference/ui-vue.md

@@ -0,0 +1,71 @@
+# Vue UI for DSM apps
+
+## Choose Vue or JSON
+
+The native-go Vue template writes Vue components directly. Keep Vue for existing
+pages, backend actions, NAS pickers, authorization, polling and custom interactions.
+Use public components from the installed `@synopackageland/ui`; preserve the
+app's host subscriptions, per-window state and unmount cleanup.
+
+Use JSON specs for declarative screens expressible in the installed JSON catalog.
+Read [ui-json.md](ui-json.md) for schema discovery, strict validation and preview
+rendering. JSON is optional: keep host actions and custom renderers in Vue/TypeScript.
+Do not convert the existing app merely to run the JSON checker.
+
+## Discover the installed contract
+
+Work from `frontend` after `npm ci`. See [ui-json.md](ui-json.md) for the shared
+package-bin setup. Query the installed package before choosing components:
+
+```sh
+npx --no syno-pkg-land-ui catalog --json
+npx --no syno-pkg-land-ui describe Button --json
+```
+
+Describe each component you intend to use. The CLI catalog describes the JSON
+surface; it is not the complete Vue API. Confirm Vue props, slots, events and
+exports in the installed `node_modules/@synopackageland/ui/README.md`, `docs/`
+and exported type declarations. In particular, consult `docs/app-local-modal.md`
+and `docs/adaptive-layout.md`. Use those current contracts and the app lockfile;
+do not guess APIs or copy a version-specific component inventory.
+
+## Keep DSM embedding boundaries
+
+- Keep a bounded `AppRoot`, for example `<AppRoot style="height: 100%">`, with
+  a sized host/mount container. Use its default app modal scope (`modalScope`);
+  avoid overriding it to document scope in a DSM window.
+- Import only `@synopackageland/ui/themes/dsm7-embedded.css` for the template.
+  The standalone `theme.css` and `dsm7.css` entrypoints affect the host page.
+- Set a unique `app.config.idPrefix` for every independent Vue app before
+  `app.mount`. Preserve the existing template's per-mount prefix generation.
+- Keep `AppLayout wide-layout="window"` in DSM. JSON uses `AppShell` with
+  `wideLayout: "window"`. Let the host set the 700px minimum window width;
+  do not enforce a page-wide minimum in CSS.
+- Reserve `modalScope: "document"` / `modal-scope="document"` and
+  `wide-layout="web"` for whole-page web/Portal applications.
+
+Reuse the embedded theme's typography, spacing and public controls. Preserve
+loading, empty, error, disabled and permission states. Backend policies and DSM
+checks decide authority; component visibility cannot grant access.
+
+## Verify the actual Vue app
+
+From `frontend`, run:
+
+```sh
+npx --no-install vue-tsc --noEmit
+npm run build
+npm test
+```
+
+Inspect screenshots of the actual app at its minimum DSM width and a maximized
+window. Check long text, scrolling, focus, modal open/close and cleanup with two
+independent mounts. A local mock host can check layout; it cannot prove NAS
+permissions or real DSM integration. Obtain authorization before testing on NAS.
+
+For JSON portions, also follow ui-json's strict validate/render loop at the target
+widths. The JSON preview renders a spec, not arbitrary `.vue` files or backend
+handlers; it does not replace the Vue build, tests or actual-app screenshots.
+Finally run the project's `check --json`, `build --json` and
+`inspect <spk> --json` workflow from AGENTS.md. Fix errors, warnings and layout
+issues before handing over the app.

package/skills/reference/wrap.md

@@ -1,12 +1,11 @@
 # 封裝（Wrap）
 
-已有 Compose 或要補齊 App Contract 時使用。權威仍是 schema + `validate`。
+已有 Compose 或要補齊 App Contract 時使用。權威仍是 schema + `check`。
 
 ## 命令
 
 ```bash
-synopkgland inspect    # Compose 意圖、Web entry 提示
-synopkgland validate   # 契約 + Compose 安全與交叉引用
+synopkgland check      # 契約、Compose 意圖與 Web entry 提示
 ```
 
 ## 契約允許什麼（v1 schema 1）
@@ -25,7 +24,7 @@ synopkgland validate   # 契約 + Compose 安全與交叉引用
 
 容器路徑跟映像／upstream 的 container target 走，原樣保留；只把 host source 換成 `${NAME}` 這類 install parameter。原有的 upstream named volume mount 與頂層 `volumes:` 宣告也保留，不要為了套模板改成 `/data`。需要既有 Share 時，管理員在安裝時選這台 NAS 的 Share。
 
-修復方式：看 `validate` 輸出的 `[錯誤碼]` 與「建議」行，對照 `diagnose.md`。**不要**為了過驗證而亂改 runtime 語意。
+修復方式：看 `check` 輸出的 `[錯誤碼]` 與「建議」行，對照 `diagnose.md`。**不要**為了過驗證而亂改 runtime 語意。
 
 ## 下一步
 

package/templates/_executor/README.md

@@ -0,0 +1,204 @@
+# Protected executor
+
+Standalone, standard-library-only Go module. Build with `CGO_ENABLED=0 GOOS=linux
+GOARCH=amd64|arm64 go build -trimpath -o executor .`. No network listener: the
+package account uses `/run/synopkgland/<package>/executor.sock` (one JSON line,
+including newline at most 65536 bytes). Socket access additionally requires exact
+Linux SO_PEERCRED UID equality, even for another member of the package group.
+Non-Linux builds support portable tests and refuse privileged service operations.
+
+## Protected inventory and policy
+
+Setup must copy the digest-pinned executor, policy and root scripts into:
+
+```
+/usr/local/etc/synopkgland/<package>/             root:root 0700
+  runtime/                                     root:root 0700
+    executor                                   root:root 0700
+    policy.json                                root:root 0600
+    tasks.json                                 root:root 0600 (verified setup task inventory)
+    root/<name>.sh                             root:root 0600
+  delegations/                                 root:root 0700
+    <random-256-bit-id>.json                    root:root 0600
+    executor.pid                               root:root 0600
+    executor.log                               root:root 0600 (control start)
+```
+
+The runtime location is mandatory; `control purge` removes this package's entire
+protected inventory after stopping it. The parent `/usr/local/etc/synopkgland`
+may be root:root 0755. Ancestors must be root-owned and not group/world writable;
+symlinks and writable runtime files are refused. Neither package-owned `etc` nor
+package `var` is trusted for executor code or delegation storage. The chosen path
+was measured on vt-nas DSM 7.4; survival of future DSM updates remains unverified.
+
+`policy.json` has this strict schema (no unknown keys):
+
+```json
+{
+  "v": 1,
+  "package": "com.example.downloader",
+  "app": "com.example.downloader.Application",
+  "scope": "home",
+  "operations": [
+    "status", "delegate.create", "delegate.list", "delegate.revoke",
+    "files.list", "files.info", "files.createFolder",
+    "files.checkPermission", "files.write", "root.run"
+  ],
+  "root": {"whoami": "<64 lowercase hexadecimal SHA-256 digits>"}
+}
+```
+
+`app` is the actual registered DSM AppPriv application ID, not a guessed package
+ID. DSM 7.x omits default-allowed Apps from AppPriv preview; an absent
+entry in a valid applications array is allowed. Explicit deny/custom, duplicate
+entries and malformed responses are refused. Account eligibility is rechecked
+independently, so absence never bypasses a disabled account. `scope` is the
+manifest's fixed `home` or `shared:<share-name>`; omit it for root-only packages.
+`operations` includes every permitted ID, including management and status IDs;
+no implicit allowlist exemptions. `root` is omitted when root operations are
+disabled. Only names in this digest map can execute. Setup pins policy bytes and
+all root scripts; no policy data comes from the package socket. The caller authentication pair follows the coordinator-approved v6 update to PLAN §2.4.
+
+## Requests
+
+Every request: `{"v":1,"op":"...","auth":{},"params":{...}}` followed by
+newline. `auth.dsm_cookie` is only the DSM `id` value, never a raw Cookie header.
+Caller requests also require `auth.dsm_synotoken`, forwarded from the current
+HTTP request's X-SYNO-TOKEN or SynoToken header. Both aliases may be present
+when their values match; conflicting aliases or repeated values of either header
+are refused. Local NormalUser verification
+sends both the id cookie and X-SYNO-TOKEN; neither value enters logs or storage.
+Only the executor's local DSM NormalUser HTTP result establishes identity. Other
+identity fields, duplicate JSON keys, invalid UTF-8, unrelated parameters, unknown
+operations and policy-excluded operations are rejected. Replies follow §2.4.
+
+| Operation | Parameters | Result |
+| --- | --- | --- |
+| status | none | executor_digest, policy_digest, version, ready |
+| delegate.create | job_id, ops[], scope, path, ttl_seconds | delegation_id, subject {username, uid}, expires_at (RFC3339) |
+| delegate.list | none | delegations[] with public metadata, including revoked/expired records |
+| delegate.revoke | delegation_id; job_id required without cookie | revoked |
+| files.list, files.info, files.checkPermission | delegation_id, job_id, path | DSM data object |
+| files.createFolder | delegation_id, job_id, path (parent), name | DSM data object |
+| files.write | delegation_id, job_id, staging (relative), dest_dir, name | path |
+| root.run | name | output (stdout and stderr combined) |
+
+Create/list require a cookie and SynoToken. Revoke accepts the subject/admin session pair or a matching
+package job ID. Root operations require the session pair independently verified as an
+active administrators member. Delegated operations recheck the account, UID,
+expired=`normal`, non-admin membership, App and File Station privileges, scope,
+job, operation, expiry and revocation. UIDs below 1024 are excluded as system
+accounts. TTL must be 1–2592000 seconds. No cookie/SynoToken/SID/password is persisted.
+
+Paths use File Station spellings `/home[/...]` or `/<share>[/...]`. A delegation
+binds the requested directory's canonical path. Symlinks resolving outside that
+directory are denied. `files.write` opens package-owned, singly linked regular
+staging files with no symlink components; its fresh child checks setgroups,
+setresgid and setresuid in order, then all real/effective IDs and groups. The child
+opens the destination after dropping identity, verifies its pinned directory and
+scope, and copies into an exclusive hidden `.synopkgland-<job_id>-<random>.part`
+file. After fsync it publishes the complete file with a hard link, then removes
+the temporary name. Existing files and symlinks are never overwritten. The
+executor cleans the exact temporary name as the subject user after a canceled or
+killed child, using a retained directory descriptor; startup performs no scan.
+Successful writes delete staging. DSM ACL inheritance can
+produce a mode different from the requested 0600 (observed 0711 on vt-nas).
+
+File Station CheckPermission uses v3 with a fixed non-overwriting probe filename
+and size zero; it creates no file. Missing/failed API data is denied. DSM output
+and root script output are capped at 1 MiB; commands have 20-second deadlines,
+connection read/write deadlines are 15/5 seconds and request execution is bounded
+by 30 seconds. At most 16 connections are admitted. Execution/revocation are
+serialized. Linux command timeouts kill the entire command process group.
+
+File Station APIs resolve path strings inside DSM after executor scope validation;
+there is no atomic DSM API for binding that subsequent lookup to our directory
+FD. Concurrent subject-controlled directory renames remain a scope-race limitation
+for runner API operations. The writer uses pinned directory descriptors; a user
+can still move a directory after its final scope check. These are release review
+items, not assertions of complete race freedom.
+
+## Lifecycle and checks
+
+```
+executor serve --package com.example.downloader
+executor control start --package com.example.downloader
+executor control stop --package com.example.downloader
+executor control purge --package com.example.downloader
+```
+
+Root control start launches asynchronously; the caller reads socket status to
+establish readiness. A held flock pidfile refuses duplicate serve. Root's pinned
+boot/control start can validate and terminate a previous monitor before launching
+its replacement; package-account start only writes the mailbox and cannot replace
+runtime. Stop pauses the listener while the monitor continues. Purge removes this
+package's protected state and deletes only its verified recorded scheduler tasks.
+
+Run `go test -race ./...` and `bash scripts/ci/gate.sh native-go`. The gate adds
+Linux amd64/arm64 vet, static binary builds and test compilation. Linux-specific
+syscall tests also run on vt-nas from a cross-compiled test executable. The
+`testdata/live_probe.py` harness expects isolated disposable accounts and a
+manually copied runtime, reads passwords only from stdin, and logs no credentials.
+The live harness uses DSM's registered `SYNO.Desktop` AppPriv ID as a stand-in for
+an installed App; installed-package AppPriv integration belongs to setup testing.
+
+
+## Package lifecycle
+
+Package-account hooks atomically write `stop` before upgrades/stops, `start` on
+install/upgrade completion and package start, and `purge` before uninstall.
+`stop` cancels/drains requests and removes the listener without ending the root
+monitor. `start` resumes only if both package executor and policy hashes equal
+the approved runtime pins; otherwise the service stays paused for administrator
+approval. Only root's pinned boot/control path can replace a monitor or runtime.
+
+At start, scheduler readback must exactly match the canonical lifecycle scripts
+regenerated from the package identity and approved executor/policy pins. Package
+setup metadata supplies hints only. The verified names, pins and script hashes
+are stored in root:root 0600 `runtime/tasks.json`. Purge regenerates the scripts
+and revalidates each current definition before EventScheduler v1
+delete (`task_name`) or TaskScheduler v2 delete (`tasks=[{id,real_owner}]`).
+Boot mirrors from TaskScheduler are ignored. Changed, missing, ambiguous or
+unverifiable records are logged and retained for administrator review; protected
+runtime, delegations and sockets are still removed, then the monitor exits.
+An absent process does not block uninstall; the pinned boot task handles pending
+purge or a missing package on the next boot. If the retained binary/policy is
+missing or tampered with, boot refuses execution and requires manual review.
+
+
+The separate package-account `executor/lifecycle` helper writes an atomic 0600
+mailbox request. Stop/purge wait at most 50 seconds for socket disappearance;
+start returns after writing and lets the monitor verify pins asynchronously.
+The helper never calls synowebapi or TaskScheduler. Socket inspection failures
+and timeouts warn and permit lifecycle to continue. Write/validation failures
+remain errors. Delegate hooks attempt worker stop first; a worker stop failure
+warns and still requests executor pause/purge.
+
+The monitor polls every 500 ms with bounded regular-file reads, accepting only
+exact start/stop/purge (optionally one trailing newline). Invalid values are
+ignored and logged without logging contents. The preuninst `purge` mailbox is
+handled immediately; cleanup completes asynchronously. Package directory/INFO
+identity absence is a fallback: the monitor pauses the socket and requests,
+retains runtime/delegations/tasks, and purges only after 10 continuous minutes of
+confirmed absence, even while paused. Every poll checks again; a valid identity
+resets the timer, and an unreadable path cannot count as confirmed absence.
+Reappearance re-reads the mailbox, including an unchanged `start`: matching pins
+resume, changed pins stay paused for administrator approval, `stop` stays paused,
+and `purge` clears state immediately. A root-approved new monitor ignores the
+stop file already present at startup; that exception ends after an absence.
+
+The boot task checks pending purge/package disappearance before accessing source.
+It verifies retained pins and protected copies again before offline purge. Normal
+boot installs verified copies and calls root control start to replace a previous
+monitor. Scripts stay within 1 KiB with no percent characters, including the
+longest package name. Partial/tampered retained state requires administrator
+review. All nine uninstall wizard locales name the two tasks and disclose the
+retained DSM storage/infrastructure. `inspect`/`status` cleanup guidance is
+conditional; it does not claim that remote remnants were observed.
+
+Directories newly created by the executor are explicitly chowned/chmodded through
+a directory descriptor and verified with fstat, so boot umask 0077 cannot reduce
+/run/synopkgland 0755 or its package directory 0750. Existing directories are
+validated and never repaired/adopted. The package directory must already have
+root/package-group ownership. The socket is set to root/package-group 0660 and
+verified using Linux O_PATH + fstat on its filesystem inode.

package/templates/_executor/apppriv_review_test.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"context"
+	"testing"
+)
+
+func TestReviewAppPrivRejectsAmbiguousOrError(t *testing.T) {
+	cases := map[string]string{
+		"outer error":                    `{"success":true,"error":{"code":105},"data":{"applications":[]}}`,
+		"inner error":                    `{"success":true,"data":{"applications":[],"error":{"code":105}}}`,
+		"duplicate array hides deny":     `{"success":true,"data":{"applications":[{"app_id":"app","privilelge":"deny"}],"applications":[]}}`,
+		"duplicate privilege hides deny": `{"success":true,"data":{"applications":[{"app_id":"app","privilelge":"deny","privilelge":"allow"}]}}`,
+		"duplicate app id":               `{"success":true,"data":{"applications":[{"app_id":"other","app_id":"app","privilelge":"allow"}]}}`,
+		"null error":                     `{"success":true,"data":{"applications":[],"error":null}}`,
+		"nonobject entry":                `{"success":true,"data":{"applications":[42]}}`,
+		"nested error":                   `{"success":true,"data":{"applications":[{"app_id":"other","privilelge":"allow","details":{"error":null}}]}}`,
+		"malformed entries":              `{"success":true,"data":{"applications":[null,{}]}}`,
+	}
+	for name, reply := range cases {
+		t.Run(name, func(t *testing.T) {
+			d := &liveDSM{Command: &cmdStub{reply: reply}}
+			if d.Allow(context.Background(), Subject{Username: "alice"}, "app") == nil {
+				t.Fatal("unsafe AppPriv response allowed")
+			}
+		})
+	}
+}

package/templates/_executor/auth_presence_review_test.go

@@ -0,0 +1,38 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+)
+
+func TestReviewEmptyPartialAuthMustNotBecomeWorkerRevoke(t *testing.T) {
+	for _, auth := range []string{`{"dsm_cookie":""}`, `{"dsm_synotoken":""}`, `{"dsm_cookie":"","dsm_synotoken":""}`, `null`} {
+		e, _, _ := setup(t)
+		id := create(t, e)
+		var req Request
+		p, _ := json.Marshal(map[string]string{"delegation_id": id, "job_id": "job1"})
+		raw := []byte(`{"v":1,"op":"delegate.revoke","auth":` + auth + `,"params":` + string(p) + `}`)
+		if err := strictJSON(raw, &req); err != nil {
+			t.Fatal(err)
+		}
+		if r := e.Handle(context.Background(), req); r.Code != "AUTH_DENIED" {
+			t.Errorf("partial auth %s became worker revoke: %+v", auth, r)
+		}
+	}
+}
+
+func TestWorkerRevokeRequiresAbsentOrEmptyAuthObject(t *testing.T) {
+	for _, auth := range []string{"", `,"auth":{}`} {
+		e, _, _ := setup(t)
+		id := create(t, e)
+		p, _ := json.Marshal(map[string]string{"delegation_id": id, "job_id": "job1"})
+		var req Request
+		if err := strictJSON([]byte(`{"v":1,"op":"delegate.revoke"`+auth+`,"params":`+string(p)+`}`), &req); err != nil {
+			t.Fatal(err)
+		}
+		if r := e.Handle(context.Background(), req); !r.OK {
+			t.Fatal("valid worker revoke denied", r)
+		}
+	}
+}