@synopackageland/cli 0.6.1 → 0.7.1

package/skills/SKILL.md

@@ -5,15 +5,15 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託；支援邊界與真機驗收依 delegate guide／驗收矩陣，禁止發明新的身分平台。
+Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。
 
 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.
+Native projects use schema 2 capabilities and `--with files,jobs,login,root-ops,delegate`; 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 and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate authorization-sdk build-time adapter; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
+Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting. Read reference/files.md and reference/identity.md for capability boundaries. RootOps and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate authorization-sdk build-time adapter; do not mix its tasks with generated executor capabilities. 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.
 
@@ -26,4 +26,106 @@ Use `syno-pkg-land-ui` directly in npm scripts; keep AI guidance version-indepen
 
 For existing native products, schema 2 `backend: {kind: native}` preserves project-owned payload/metadata, prepare/compile argv hooks and pinned toolkits. See the native-layout guide; run `check`, `build`, then `inspect <spk>` locally. Keep lifecycle/systemd as the package account and preserve product-owned digest approval/revocation. Native layouts do not opt into generated Go capabilities.
 
-Delegate is for non-administrator subjects only and currently cannot combine with daemon. Gopeed-style completed-download integration needs an App-owned fixed worker and durable job/delegation binding; the shipped URL example is limited to 64 MiB / 60 seconds and grants to one hour. Scope is a usage restriction, not hard subtree isolation against user-controlled directory moves. Do not claim a daemon-based administrator-only app can simply enable delegate.
+
+## Permanent destination integration
+
+`init --with delegate` / `add delegate` default to `operations: [files.moveFromStaging]`,
+`destinations: [save]`, `lifetime: until-revoked`, `scope: install-selected`. Existing legacy
+TTL declarations retain their 1–3600 second service / 30-day wire ceiling and
+64 MiB / 60-second URL example. Do not apply those limits to the new move API.
+Delegate can coexist with daemon; ordinary standalone jobs cannot. Preserve
+App business route floors. Binary/compose remain unsupported.
+
+Use File Station `/home[/...]`, never `/homes/<user>`. The SDK destination picker
+selection itself grants access after fresh DSM session/UID/write verification,
+without a second consent dialog. Ordinary and administrator subjects use their
+own nonzero UID/current groups, never root. An online App can create an in-scope
+grant using a valid session; there is no trusted external consent or notification.
+
+Use the default `createBackgroundSaveFacade(ctx)` / CapabilityPanels management
+page. `delegate.status` exposes verified `disabled` and manifest mode; missing
+protected evidence must not imply enabled. `delegate.operations.list` accepts
+only `{}`, uses the backend move mirrors, and returns the caller's username+UID
+operations only, including for admins. Mirrors are not completion receipts:
+query original `delegate.operations.get` and show Saved only for committed with
+a receipt. Cancel by the same reference; revoke by grant ID. Never resubmit
+uncertain/interrupted work. Admin disable is protected and revokes grants;
+enable/mailbox start does not resurrect them. Keep IDs, never session credentials.
+
+App-owned daemon completion and scheduled CSV export call configured Go
+`Service.MoveFromStaging` with `delegation_id`, stable `job_id`, private relative
+`staging`, `name`, `size`. No owner/UID selector. Bounds: 16 GiB/file, queued16,
+active1/package, 24-hour attempt, 5-second revalidation ticks (one check at a time, 30-second complete-check deadline; proven timeouts retain private copying, publication still revalidates), 10 MiB operation records,
+50 MiB audit. Scope is a usage restriction, not hard subtree confinement.
+Local production-executor fixtures use fake DSM/peer/bulk writer; do not claim
+NAS ACL, actual writer UID, logout/reboot or full lifecycle acceptance from them.
+Gopeed product wiring remains a separate task.
+
+Admission recovery (per job): on `EXECUTOR_UNAVAILABLE`, `EXECUTOR_TIMEOUT`,
+`EXECUTOR_PROTOCOL`, `canceled`, `EXECUTOR_PAUSED`, `queue-full`,
+`STORAGE_ERROR`, `ADMISSION_PENDING`, `jobs_busy` or `jobs_unavailable` (the
+package journal was busy or failed transiently; a caller deadline or cancel
+spent waiting for it is `canceled`), call `MoveFromStaging` again later with
+the same exact params. It queries the original reference first and re-sends
+admission only when the executor does not know it and the pinned source is
+unchanged; executor tuple deduplication keeps one operation, so a lost reply or a
+racing caller never copies twice. At most 10 possibly-delivered sends, 2 s
+backoff doubling to 5 min; the worker sweep does the same. Terminal, do not
+retry: `APP_DENIED`, `DELEGATION_DENIED`, `operation-conflict`, `disabled`,
+`SCOPE_DENIED` and other executor refusals, `STAGING_CHANGED`,
+`ADMISSION_EXHAUSTED`, `spool_unsafe` and `journal_corrupt` (repair the package
+spool first), and `operation-not-found` for an accepted operation.
+Never change job/grant IDs, delete mirrors or call the socket directly to retry.
+
+Cancellation (per job): `CancelOperation` / `delegate.operations.cancel` with the
+original ref is idempotent; repeat it with the same ref after any retryable
+error or a lost reply. A reply `queued`→`canceled` is final at once. A copy in
+flight answers `copying` with code `CANCEL_REQUESTED`: the cancel is accepted and
+durable, not finished; poll `OperationStatus` on the same ref until terminal
+(repeating the cancel is harmless). `canceled` (`OPERATION_CANCELED`) guarantees the writer
+stopped, its part file is removed, nothing was published and staging is kept; it
+stays canceled across executor crash, package stop/start and logout. Revoke, scope change and disable store their reason (`grant-revoked`,
+`scope-changed`, `integration-disabled`) the same way: a copy in flight answers
+`CANCEL_REQUESTED` with it and settles `canceled` with it across a restart. A
+copy the executor stops without a cancel ends `interrupted`/`EXECUTOR_PAUSED`
+(`interrupted`/`interrupted` after a crash), never `WRITE_FAILED`. `committed`
+means publication won the race: the file stays (cancel never removes it) and only
+the app record may be dropped. `uncertain` means a publish attempt failed before
+the cancel; keep querying. A cancel of a ref the executor has not admitted yet
+(reserved/sent mirror) returns `canceled` and leaves a tombstone, so a late or
+recovered admission of that ref returns `canceled` and never copies; a producer
+cancel is also written to the mirror first, so `MoveFromStaging` and the worker
+sweep forward the cancel instead of admitting it.
+
+
+### Install-selected scope and the destination API
+
+- The DSM install wizard dynamically lists local shares (`SYNO.Core.Share list`
+  via `api_store`) and offers home. It saves only a package-owned pre-selection
+  in `var/delegate-install.json`; never trust that file for authority.
+- The existing administrator PasswordConfirm form displays this pre-selection
+  at first enable. `ctx.executor.authorize(password, selectedScope)` confirms it
+  through a pinned, exact-readback one-time root task. Settings changes use the
+  same form/password path; no App CGI route may set protected scope directly.
+- The executor trusts `/usr/local/etc/synopkgland/<pkg>/delegations/selected-scope.record`
+  only. Its scope/generation are runtime protected state; shipped policy pins
+  lock the selection mode and operations. Changes revoke old grants and cancel
+  pending writes. Change-away-and-back never revives an old grant.
+- Follow `selection` from verified `delegate.status` / `sdk.destination(key)`.
+  If the draft differs, display the difference and follow the protected value.
+  Home and fixed `shared:<name>` manifests stay compatible.
+- Frontend: `const sdk = createBackgroundSaveFacade(ctx); const current = await
+  sdk.destination('save')` returns typed `{key, selection, destination, status}`.
+  `selection` contains `{scope, root, generation}`; `destination` is this caller's
+  grant or null. Handle active/missing/reselection-required/needs-scope-confirmation/disabled.
+- Go: `Service.Destination(ctx, caller, request, key)` verifies the fresh DSM
+  session and username+UID. Capture its active grant ID into the App job. The
+  offline producer uses existing `Service.MoveFromStaging`; no user/UID selector,
+  cookie, token, or browser path cache. Executor revalidates at use/publication.
+- The generated Background saves page includes a working **Save example file**
+  (`sdk.exportExample({key, job_id})`, `delegate.example.export`). Go
+  `ExportExample` creates a private JSON file, calls `MoveFromStaging` once, and
+  repeats the original request on repeated IDs. Review `example.go` to
+  adapt a real producer; show Saved only from a protected committed receipt.
+- Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
+  forward. This is not proof of other DSM releases or full writer/reboot behavior.

package/skills/reference/create.md

@@ -27,8 +27,107 @@ synopkgland init -t compose --from ./compose.yaml upstream-app
 ## 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。
+`--with files,jobs,login,root-ops,delegate` 分別宣告 `capabilities.files: session`、`jobs: true`、`identity: standalone`、`rootOps: true`、`delegate: {operations: [files.moveFromStaging], destinations: [save], lifetime: until-revoked, scope: install-selected}`。jobs 可寫 `{worker: sha256-v1}`，與 daemon 互斥；delegate 隱含 worker 並可與 daemon 共存；admin／normal 都以本人 UID 執行。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 自訂版本拒絕。
+rootOps 與 delegate 已共用管理員 PasswordConfirm 核准的 protected executor、boot/control tasks；精確 task readback 與 digest health 一致才 ready，pins 變更須重核准。native 產品另可明確 opt-in authorization-sdk adapter，不與 generated executor tasks 混用。SDK off stub 與 routes_test.go 的預設 policy scaffold 只有內容仍等於 bundled base 時才會替換；App 自訂版本拒絕。
+
+## Permanent destination integration
+
+`init --with delegate` / `add delegate` default to `operations: [files.moveFromStaging]`,
+`destinations: [save]`, `lifetime: until-revoked`, `scope: install-selected`. Existing legacy
+TTL declarations retain their 1–3600 second service / 30-day wire ceiling and
+64 MiB / 60-second URL example. Do not apply those limits to the new move API.
+Delegate can coexist with daemon; ordinary standalone jobs cannot. Preserve
+App business route floors. Binary/compose remain unsupported.
+
+Use File Station `/home[/...]`, never `/homes/<user>`. The SDK destination picker
+selection itself grants access after fresh DSM session/UID/write verification,
+without a second consent dialog. Ordinary and administrator subjects use their
+own nonzero UID/current groups, never root. An online App can create an in-scope
+grant using a valid session; there is no trusted external consent or notification.
+
+Use the default `createBackgroundSaveFacade(ctx)` / CapabilityPanels management
+page. `delegate.status` exposes verified `disabled` and manifest mode; missing
+protected evidence must not imply enabled. `delegate.operations.list` accepts
+only `{}`, uses the backend move mirrors, and returns the caller's username+UID
+operations only, including for admins. Mirrors are not completion receipts:
+query original `delegate.operations.get` and show Saved only for committed with
+a receipt. Cancel by the same reference; revoke by grant ID. Never resubmit
+uncertain/interrupted work. Admin disable is protected and revokes grants;
+enable/mailbox start does not resurrect them. Keep IDs, never session credentials.
+
+App-owned daemon completion and scheduled CSV export call configured Go
+`Service.MoveFromStaging` with `delegation_id`, stable `job_id`, private relative
+`staging`, `name`, `size`. No owner/UID selector. Bounds: 16 GiB/file, queued16,
+active1/package, 24-hour attempt, 5-second revalidation ticks (one check at a time, 30-second complete-check deadline; proven timeouts retain private copying, publication still revalidates), 10 MiB operation records,
+50 MiB audit. Scope is a usage restriction, not hard subtree confinement.
+Local production-executor fixtures use fake DSM/peer/bulk writer; do not claim
+NAS ACL, actual writer UID, logout/reboot or full lifecycle acceptance from them.
+Gopeed product wiring remains a separate task.
+
+Admission recovery (per job): on `EXECUTOR_UNAVAILABLE`, `EXECUTOR_TIMEOUT`,
+`EXECUTOR_PROTOCOL`, `canceled`, `EXECUTOR_PAUSED`, `queue-full`,
+`STORAGE_ERROR`, `ADMISSION_PENDING`, `jobs_busy` or `jobs_unavailable` (the
+package journal was busy or failed transiently; a caller deadline or cancel
+spent waiting for it is `canceled`), call `MoveFromStaging` again later with
+the same exact params. It queries the original reference first and re-sends
+admission only when the executor does not know it and the pinned source is
+unchanged; executor tuple deduplication keeps one operation, so a lost reply or a
+racing caller never copies twice. At most 10 possibly-delivered sends, 2 s
+backoff doubling to 5 min; the worker sweep does the same. Terminal, do not
+retry: `APP_DENIED`, `DELEGATION_DENIED`, `operation-conflict`, `disabled`,
+`SCOPE_DENIED` and other executor refusals, `STAGING_CHANGED`,
+`ADMISSION_EXHAUSTED`, `spool_unsafe` and `journal_corrupt` (repair the package
+spool first), and `operation-not-found` for an accepted operation.
+Never change job/grant IDs, delete mirrors or call the socket directly to retry.
+
+Cancellation (per job): `CancelOperation` / `delegate.operations.cancel` with the
+original ref is idempotent; repeat it with the same ref after any retryable
+error or a lost reply. A reply `queued`→`canceled` is final at once. A copy in
+flight answers `copying` with code `CANCEL_REQUESTED`: the cancel is accepted and
+durable, not finished; poll `OperationStatus` on the same ref until terminal
+(repeating the cancel is harmless). `canceled` (`OPERATION_CANCELED`) guarantees the writer
+stopped, its part file is removed, nothing was published and staging is kept; it
+stays canceled across executor crash, package stop/start and logout. `committed`
+means publication won the race: the file stays (cancel never removes it) and only
+the app record may be dropped. `uncertain` means a publish attempt failed before
+the cancel; keep querying. A cancel of a ref the executor has not admitted yet
+(reserved/sent mirror) returns `canceled` and leaves a tombstone, so a late or
+recovered admission of that ref returns `canceled` and never copies; a producer
+cancel is also written to the mirror first, so `MoveFromStaging` and the worker
+sweep forward the cancel instead of admitting it.
+
+
+### Install-selected scope and the destination API
+
+- The DSM install wizard dynamically lists local shares (`SYNO.Core.Share list`
+  via `api_store`) and offers home. It saves only a package-owned pre-selection
+  in `var/delegate-install.json`; never trust that file for authority.
+- The existing administrator PasswordConfirm form displays this pre-selection
+  at first enable. `ctx.executor.authorize(password, selectedScope)` confirms it
+  through a pinned, exact-readback one-time root task. Settings changes use the
+  same form/password path; no App CGI route may set protected scope directly.
+- The executor trusts `/usr/local/etc/synopkgland/<pkg>/delegations/selected-scope.record`
+  only. Its scope/generation are runtime protected state; shipped policy pins
+  lock the selection mode and operations. Changes revoke old grants and cancel
+  pending writes. Change-away-and-back never revives an old grant.
+- Follow `selection` from verified `delegate.status` / `sdk.destination(key)`.
+  If the draft differs, display the difference and follow the protected value.
+  Home and fixed `shared:<name>` manifests stay compatible.
+- Frontend: `const sdk = createBackgroundSaveFacade(ctx); const current = await
+  sdk.destination('save')` returns typed `{key, selection, destination, status}`.
+  `selection` contains `{scope, root, generation}`; `destination` is this caller's
+  grant or null. Handle active/missing/reselection-required/needs-scope-confirmation/disabled.
+- Go: `Service.Destination(ctx, caller, request, key)` verifies the fresh DSM
+  session and username+UID. Capture its active grant ID into the App job. The
+  offline producer uses existing `Service.MoveFromStaging`; no user/UID selector,
+  cookie, token, or browser path cache. Executor revalidates at use/publication.
+- The generated Background saves page includes a working **Save example file**
+  (`sdk.exportExample({key, job_id})`, `delegate.example.export`). Go
+  `ExportExample` creates a private JSON file, calls `MoveFromStaging` once, and
+  repeats the original request on repeated IDs. Review `example.go` to
+  adapt a real producer; show Saved only from a protected committed receipt.
+- Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
+  forward. This is not proof of other DSM releases or full writer/reboot behavior.

package/skills/reference/deploy.md

@@ -1,6 +1,6 @@
 # Build and deploy
 
-1. Run `synopkgland check` and `synopkgland build --arch x86_64` (use aarch64 for that target).
+1. Run `synopkgland check` and `synopkgland build --arch x86_64` (use aarch64 or armv7 for those targets; armv7 must be listed in `arches`; its jobs, daemon and executor are built but not NAS-verified). deploy detects the NAS arch, except on Marvell CPUs, where it asks for `--arch`.
 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>`.
@@ -9,4 +9,4 @@ Deployment uploads directly to DSM. It does not publish artifacts. Container ins
 
 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.
+5. After installation run `synopkgland status --host <profile> --json`; inspect every capability state and Open URL. Installation is not readiness. Delegate is implemented and shipped (default `files.moveFromStaging`); full device lifecycle acceptance is still pending for the shared delegate/rootOps executor: install → setup → reboot → upgrade → revoke → uninstall. Delete App Data is not evidence of complete cleanup; verify retained directories/account artifacts.

package/skills/reference/files.md

@@ -1,13 +1,124 @@
 # 檔案與背景工作
 
-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 判權，不需管理員進行能力設定。
+Native-go 的 B 能力使用 `init --with files` 或 `add files`，對應 schema 2 `capabilities.files: session`。File tree 與共用 NasPicker 以 TreeView／DataGrid 顯示本人可見內容；一般選取不建立授權；delegate destination 選取例外，確認即授權。FilePicker 選瀏覽器本機檔案。上傳／下載使用 streaming transport，不把內容放進 JSON。每次以呼叫者有效 DSM session 由 File Station 判權，不需管理員進行能力設定。
 
 只有 App session 沒有有效 DSM cookie 時回 `dsm_session_required`，須在同 hostname 登入 DSM。不能以套件帳號或 root 作後備存取。
 
 A 能力 `--with jobs` 使用套件帳號處理已匯入的私有副本，依可信 username／UID 綁定；一般使用者不需 admin 設定即可提交、查詢與取消自己的工作。關閉瀏覽器後繼續，不保存 cookie／SID／密碼。匯入需要本人在線 session；私有副本不是離線讀取原檔案的權限。Jobs 與 daemon 互斥。
 
-C 能力 delegate 為 P2 整合中，目前 CLI 拒絕。規劃 admin 確認一次密碼設定 executor；使用者委託／撤銷，綁定 job／operations／scope／期限。DSM runner 與降權寫檔依本人權限執行；scope 限制使用範圍，不是權限邊界。每次重驗帳號與 AppPriv，停用或拒絕即阻擋。不宣稱完整生命週期已驗證。
+
+## Permanent destination integration
+
+`init --with delegate` / `add delegate` default to `operations: [files.moveFromStaging]`,
+`destinations: [save]`, `lifetime: until-revoked`, `scope: install-selected`. Existing legacy
+TTL declarations retain their 1–3600 second service / 30-day wire ceiling and
+64 MiB / 60-second URL example. Do not apply those limits to the new move API.
+Delegate can coexist with daemon; ordinary standalone jobs cannot. Preserve
+App business route floors. Binary/compose remain unsupported.
+
+Use File Station `/home[/...]`, never `/homes/<user>`. The SDK destination picker
+selection itself grants access after fresh DSM session/UID/write verification,
+without a second consent dialog. Ordinary and administrator subjects use their
+own nonzero UID/current groups, never root. An online App can create an in-scope
+grant using a valid session; there is no trusted external consent or notification.
+
+Use the default `createBackgroundSaveFacade(ctx)` / CapabilityPanels management
+page. `delegate.status` exposes verified `disabled` and manifest mode; missing
+protected evidence must not imply enabled. `delegate.operations.list` accepts
+only `{}`, uses the backend move mirrors, and returns the caller's username+UID
+operations only, including for admins. Mirrors are not completion receipts:
+query original `delegate.operations.get` and show Saved only for committed with
+a receipt. Cancel by the same reference; revoke by grant ID. Never resubmit
+uncertain/interrupted work. Revoke, scope change and disable store their reason (`grant-revoked`,
+`scope-changed`, `integration-disabled`) the same way: a copy in flight answers
+`CANCEL_REQUESTED` with it and settles `canceled` with it across a restart. A
+copy the executor stops without a cancel ends `interrupted`/`EXECUTOR_PAUSED`
+(`interrupted`/`interrupted` after a crash), never `WRITE_FAILED`. A lost publish receipt (or a restart after publish
+intent) settles to committed only when the recorded part inode is the final name;
+otherwise it stays uncertain. Nothing is copied twice. Admin disable is protected and revokes grants;
+enable/mailbox start does not resurrect them. Keep IDs, never session credentials.
+
+App-owned daemon completion and scheduled CSV export call configured Go
+`Service.MoveFromStaging` with `delegation_id`, stable `job_id`, private relative
+`staging`, `name`, `size`. No owner/UID selector. Bounds: 16 GiB/file, queued16,
+active1/package, 24-hour attempt, 5-second revalidation ticks (one check at a time, 30-second complete-check deadline; proven timeouts retain private copying, publication still revalidates), 10 MiB operation records,
+50 MiB audit. Scope is a usage restriction, not hard subtree confinement.
+Local production-executor fixtures use fake DSM/peer/bulk writer; do not claim
+NAS ACL, actual writer UID, logout/reboot or full lifecycle acceptance from them.
+Gopeed product wiring remains a separate task.
+
+Admission recovery (per job): on `EXECUTOR_UNAVAILABLE`, `EXECUTOR_TIMEOUT`,
+`EXECUTOR_PROTOCOL`, `canceled`, `EXECUTOR_PAUSED`, `queue-full`,
+`STORAGE_ERROR`, `ADMISSION_PENDING`, `jobs_busy` or `jobs_unavailable` (the
+package journal was busy or failed transiently; a caller deadline or cancel
+spent waiting for it is `canceled`), call `MoveFromStaging` again later with
+the same exact params. It queries the original reference first and re-sends
+admission only when the executor does not know it and the pinned source is
+unchanged; executor tuple deduplication keeps one operation, so a lost reply or a
+racing caller never copies twice. At most 10 possibly-delivered sends, 2 s
+backoff doubling to 5 min; the worker sweep does the same. Terminal, do not
+retry: `APP_DENIED`, `DELEGATION_DENIED`, `operation-conflict`, `disabled`,
+`SCOPE_DENIED` and other executor refusals, `STAGING_CHANGED`,
+`ADMISSION_EXHAUSTED`, `spool_unsafe` and `journal_corrupt` (repair the package
+spool first), and `operation-not-found` for an accepted operation.
+Never change job/grant IDs, delete mirrors or call the socket directly to retry.
+
+Cancellation (per job): `CancelOperation` / `delegate.operations.cancel` with the
+original ref is idempotent; repeat it with the same ref after any retryable
+error or a lost reply. A reply `queued`→`canceled` is final at once. A copy in
+flight answers `copying` with code `CANCEL_REQUESTED`: the cancel is accepted and
+durable, not finished; poll `OperationStatus` on the same ref until terminal
+(repeating the cancel is harmless). `canceled` (`OPERATION_CANCELED`) guarantees the writer
+stopped, its part file is removed, nothing was published and staging is kept; it
+stays canceled across executor crash, package stop/start and logout. `committed`
+means publication won the race: the file stays (cancel never removes it) and only
+the app record may be dropped. `uncertain` means a publish attempt failed before
+the cancel; keep querying. A cancel of a ref the executor has not admitted yet
+(reserved/sent mirror) returns `canceled` and leaves a tombstone, so a late or
+recovered admission of that ref returns `canceled` and never copies; a producer
+cancel is also written to the mirror first, so `MoveFromStaging` and the worker
+sweep forward the cancel instead of admitting it.
+
 
 容器使用固定 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 不是完整清理證明，須讀回殘留。
+
+
+### Install-selected scope and the destination API
+
+- The DSM install wizard dynamically lists local shares (`SYNO.Core.Share list`
+  via `api_store`) and offers home. It saves only a package-owned pre-selection
+  in `var/delegate-install.json`; never trust that file for authority.
+- The existing administrator PasswordConfirm form displays this pre-selection
+  at first enable. `ctx.executor.authorize(password, selectedScope)` confirms it
+  through a pinned, exact-readback one-time root task. Settings changes use the
+  same form/password path; no App CGI route may set protected scope directly.
+  A change on a running, pin-verified executor never restarts it; copies in
+  flight end `canceled`/`scope-changed`. A `blocked` reply with `requested:
+  {scope, generation}` may still land: poll `ctx.executor.status()` until
+  `selection` shows that scope above that generation; resubmitting is safe.
+- The executor trusts `/usr/local/etc/synopkgland/<pkg>/delegations/selected-scope.record`
+  only. Its scope/generation are runtime protected state; shipped policy pins
+  lock the selection mode and operations. Changes revoke old grants and cancel
+  pending writes. Change-away-and-back never revives an old grant.
+- Follow `selection` from verified `delegate.status` / `sdk.destination(key)`.
+  If the draft differs, display the difference and follow the protected value.
+  Home and fixed `shared:<name>` manifests stay compatible.
+- Frontend: `const sdk = createBackgroundSaveFacade(ctx); const current = await
+  sdk.destination('save')` returns typed `{key, selection, destination, status}`.
+  `selection` contains `{scope, root, generation}`; `destination` is this caller's
+  grant or null. Handle active/missing/reselection-required/needs-scope-confirmation/disabled.
+- Go: `Service.Destination(ctx, caller, request, key)` verifies the fresh DSM
+  session and username+UID. Capture its active grant ID into the App job. The
+  offline producer uses existing `Service.MoveFromStaging`; no user/UID selector,
+  cookie, token, or browser path cache. Executor revalidates at use/publication.
+- The generated Background saves page includes a working **Save example file**
+  (`sdk.exportExample({key, job_id})`, `delegate.example.export`). Go
+  `ExportExample` creates a private JSON file, calls `MoveFromStaging` once, and
+  repeats the original request on repeated IDs. Review `example.go` to
+  adapt a real producer; show Saved only from a protected committed receipt.
+- Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
+  forward. This is not proof of other DSM releases or full writer/reboot behavior.
+
+The pinned scope-selection task also binds the protected generation observed before confirmation. The executor compares it under the publish lock and refuses stale tasks, so a retained task cannot replay an older selection after another confirmation.

package/skills/reference/identity.md

@@ -2,10 +2,79 @@
 
 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.
 
+Entry: omit `entry` for legacy access; `entry: admin-only` admits administrators only and is the floor of every route: SDK routes a capability adds (files, jobs, portal, delegate, rootOps) refuse ordinary users with `admin_required`, the launcher is hidden, and an app route marked `authenticated` or `public` in permissions.json fails validate/build with `STANDALONE_ENTRY_WIDENED` (only the public `identity: standalone` login routes stay public; they admit no one by themselves). The SPK records the mode in `sdk-package.json`; `inspect` prints it and flags `ENTRY_LAUNCHER_MISMATCH`; `entry: app-privilege` also admits accounts DSM Application Privileges allows for `SYNO.SDS.<package>.Instance` (native-go only, needs an `authenticated` route). DSM evaluates user/group/everyone rules, allow/deny precedence and IP ranges; one CGI check covers every route, failures refuse with `app_privilege_denied`, and decisions are cached at most 30 seconds. DSM's install default allows administrators only, so declaring or upgrading never opens the app to everyone. The delegate executor applies the same entry rule to every protected and producer move: once DSM no longer allows a user, new moves under that user's still-valid grant are refused (`APP_DENIED`, grant invalidated); files already saved stay. Guard global settings in shared routes with Go `api.RequireAdmin(caller)` (`admin_required`); the frontend `ctx.user?.isAdmin` only hides controls.
+
 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.
+
+## Permanent destination integration
+
+`init --with delegate` / `add delegate` default to `operations: [files.moveFromStaging]`,
+`destinations: [save]`, `lifetime: until-revoked`, `scope: home`. Existing legacy
+TTL declarations retain their 1–3600 second service / 30-day wire ceiling and
+64 MiB / 60-second URL example. Do not apply those limits to the new move API.
+Delegate can coexist with daemon; ordinary standalone jobs cannot. Preserve
+App business route floors. Binary/compose remain unsupported.
+
+Use File Station `/home[/...]`, never `/homes/<user>`. The SDK destination picker
+selection itself grants access after fresh DSM session/UID/write verification,
+without a second consent dialog. Ordinary and administrator subjects use their
+own nonzero UID/current groups, never root. An online App can create an in-scope
+grant using a valid session; there is no trusted external consent or notification.
+
+Use the default `createBackgroundSaveFacade(ctx)` / CapabilityPanels management
+page. `delegate.status` exposes verified `disabled` and manifest mode; missing
+protected evidence must not imply enabled. `delegate.operations.list` accepts
+only `{}`, uses the backend move mirrors, and returns the caller's username+UID
+operations only, including for admins. Mirrors are not completion receipts:
+query original `delegate.operations.get` and show Saved only for committed with
+a receipt. Cancel by the same reference; revoke by grant ID. Never resubmit
+uncertain/interrupted work. Admin disable is protected and revokes grants;
+enable/mailbox start does not resurrect them. Keep IDs, never session credentials.
+
+App-owned daemon completion and scheduled CSV export call configured Go
+`Service.MoveFromStaging` with `delegation_id`, stable `job_id`, private relative
+`staging`, `name`, `size`. No owner/UID selector. Bounds: 16 GiB/file, queued16,
+active1/package, 24-hour attempt, 5-second revalidation ticks (one check at a time, 30-second complete-check deadline; proven timeouts retain private copying, publication still revalidates), 10 MiB operation records,
+50 MiB audit. Scope is a usage restriction, not hard subtree confinement.
+Local production-executor fixtures use fake DSM/peer/bulk writer; do not claim
+NAS ACL, actual writer UID, logout/reboot or full lifecycle acceptance from them.
+Gopeed product wiring remains a separate task.
+
+Admission recovery (per job): on `EXECUTOR_UNAVAILABLE`, `EXECUTOR_TIMEOUT`,
+`EXECUTOR_PROTOCOL`, `canceled`, `EXECUTOR_PAUSED`, `queue-full`,
+`STORAGE_ERROR`, `ADMISSION_PENDING`, `jobs_busy` or `jobs_unavailable` (the
+package journal was busy or failed transiently; a caller deadline or cancel
+spent waiting for it is `canceled`), call `MoveFromStaging` again later with
+the same exact params. It queries the original reference first and re-sends
+admission only when the executor does not know it and the pinned source is
+unchanged; executor tuple deduplication keeps one operation, so a lost reply or a
+racing caller never copies twice. At most 10 possibly-delivered sends, 2 s
+backoff doubling to 5 min; the worker sweep does the same. Terminal, do not
+retry: `APP_DENIED`, `DELEGATION_DENIED`, `operation-conflict`, `disabled`,
+`SCOPE_DENIED` and other executor refusals, `STAGING_CHANGED`,
+`ADMISSION_EXHAUSTED`, `spool_unsafe` and `journal_corrupt` (repair the package
+spool first), and `operation-not-found` for an accepted operation.
+Never change job/grant IDs, delete mirrors or call the socket directly to retry.
+
+Cancellation (per job): `CancelOperation` / `delegate.operations.cancel` with the
+original ref is idempotent; repeat it with the same ref after any retryable
+error or a lost reply. A reply `queued`→`canceled` is final at once. A copy in
+flight answers `copying` with code `CANCEL_REQUESTED`: the cancel is accepted and
+durable, not finished; poll `OperationStatus` on the same ref until terminal
+(repeating the cancel is harmless). `canceled` (`OPERATION_CANCELED`) guarantees the writer
+stopped, its part file is removed, nothing was published and staging is kept; it
+stays canceled across executor crash, package stop/start and logout. `committed`
+means publication won the race: the file stays (cancel never removes it) and only
+the app record may be dropped. `uncertain` means a publish attempt failed before
+the cancel; keep querying. A cancel of a ref the executor has not admitted yet
+(reserved/sent mirror) returns `canceled` and leaves a tombstone, so a late or
+recovered admission of that ref returns `canceled` and never copies; a producer
+cancel is also written to the mirror first, so `MoveFromStaging` and the worker
+sweep forward the cancel instead of admitting it.
+
+RootOps/delegate share PasswordConfirm-approved digest-pinned setup with exact task readback and health. Pins changes require reapproval. The separate native authorization-sdk adapter must not mix its tasks with generated executor tasks.
 
 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/portal.md

@@ -0,0 +1,17 @@
+# DSM Application Portal
+
+Declare: native-go/binary `portal: {}` or `portal: {alias: my-app}` in dsm-package.yaml (`synopkgland add portal`); Compose `integration.web.portal: {}` only for a DSM-window app behind the DSM auth gateway. The alias defaults to the package name in lowercase. Aliases are 1–64 lowercase letters, digits or `-`, not starting or ending with `-`, and not a DSM path or Synology App alias (`webman`, `file`, …). The native-layout `backend: {kind: native}` owns its conf/scripts: the SDK does not register a portal for it.
+
+Build: the SPK carries `etc/portal.json` (every field DSM's app-portal worker needs) and `etc/portal.mustache`, `conf/resource` registers them, and the install wizard adds a prefilled alias step. preinst validates the answer; postinst stores it as the package's own draft and default alias. Nothing is active until an administrator applies it. `inspect <spk> --json` reports `portal: {appId, alias}` and refuses any other portal content.
+
+Activate: DSM owns the saved setting. Administrators use the app's portal panel (`ctx.portal.apply(alias)` / `disable()`, DSM `SYNO.Core.AppPortal set` with their own session; DSM refuses non-administrators with 105) or Control Panel > Login Portal > Applications (`ctx.portal.openControlPanel()`). DSM errors map to `portal_alias_invalid`, `portal_alias_reserved`, `portal_alias_in_use`, `admin_required`, `portal_unavailable`.
+
+Read: ordinary users call the Go backend's `portal.status` (`authenticated`), which reads `/var/packages/<package>/etc/AppPortal.json` read-only, bounded (64 KiB, no symlinks, one JSON object, matching app id). Anything else is `unavailable` and the UI shows "ask an administrator". A binary CGI must implement the same `{state, alias}` answer itself or ordinary users never see the link.
+
+DSM floor: os_min_ver must be 7.3.2-86009 or later. DSM 7.1.1-42962 refuses an unsigned SPK whose conf/resource carries web-config app-portal (Package Center error 320, "non-synology-signed package should not use internal worker"); 7.3.2-86009 and 7.4 install it; 7.2 and 7.3.0/7.3.1 are untested (unknown). validate/build fail with `STANDALONE_PORTAL_MIN_DSM` / `CONTRACT_PORTAL_MIN_DSM`, `--min-dsm` cannot go below it, `add portal` raises a lower os_min_ver, and inspect flags a lower INFO os_min_ver. Fix: raise os_min_ver or remove the portal.
+
+Capability: beyond that floor, no version gate. The panel needs SYNO.API.Info to list `SYNO.Core.AppPortal` (v2) and the app's registration to exist; otherwise administrators get only the Control Panel shortcut.
+
+UI: plain JS calls `ctx.portal && ctx.portal.mountPanel(element)` and disposes it on unmount; Vue renders `portal/PortalSettings.vue`. `ctx.portal.messages` carries the SDK text in all nine languages.
+
+Never: write `AppPortal.json`, `@appconf/<package>` or `/usr/syno/etc/www/app.d`; add a backend route that changes the alias; relay QuickConnect responses or build QuickConnect links; reboot or change other packages' portal entries while testing. DSM keeps the alias across upgrades and removes the entry on uninstall.

package/skills/reference/ui-vue.md

@@ -69,3 +69,15 @@ 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.
+
+
+## Delegate scope Settings
+
+Default delegate uses `install-selected`. Keep ExecutorSettings and BackgroundSavePanel
+in the existing Settings surface. Show the installer draft only as a pre-selection;
+follow protected `selection` from `delegate.status` / `sdk.destination(key)`. Use
+`ctx.executor.authorize(password, scope)` for both first enable and scope changes,
+with the same PasswordConfirm form and no extra dialog. Mismatch must be explicit.
+Restrict the existing NasPicker to `selection.root`; do not grant via cached paths.
+The default facade includes typed `destination(key)` and `exportExample({key,job_id})`;
+use original operation references and display Saved only for protected receipts.

package/templates/_daemon/go.mod

@@ -2,4 +2,4 @@ module synopkgland-daemon
 
 go 1.24
 
-toolchain go1.26.8
+toolchain go1.26.9

package/templates/_daemon/main.go

@@ -28,6 +28,9 @@ type deadlines struct {
 	Start  int `json:"start"`
 	Stop   int `json:"stop"`
 	Status int `json:"status"`
+	// Uninstall bounds uninstall_args separately from Stop: a revoke on a
+	// loaded NAS can take longer than stopping the daemon.
+	Uninstall int `json:"uninstall"`
 }
 type config struct {
 	Package       string            `json:"package"`
@@ -88,7 +91,7 @@ func load(dest, data string) (*controller, error) {
 	if cfg.Exec == "" || filepath.IsAbs(cfg.Exec) || filepath.Clean(cfg.Exec) != cfg.Exec || strings.HasPrefix(cfg.Exec, "../") {
 		return nil, errors.New("invalid fixed executable")
 	}
-	if cfg.Timeouts.Start < 2 || cfg.Timeouts.Start > 120 || cfg.Timeouts.Stop < 2 || cfg.Timeouts.Stop > 120 || cfg.Timeouts.Status < 1 || cfg.Timeouts.Status > 10 {
+	if cfg.Timeouts.Start < 2 || cfg.Timeouts.Start > 120 || cfg.Timeouts.Stop < 2 || cfg.Timeouts.Stop > 120 || cfg.Timeouts.Status < 1 || cfg.Timeouts.Status > 10 || cfg.Timeouts.Uninstall < 2 || cfg.Timeouts.Uninstall > 120 {
 		return nil, errors.New("invalid daemon deadlines")
 	}
 	hash := sha256.Sum256(raw)
@@ -162,7 +165,7 @@ func (c *controller) run(action string) (int, error) {
 		budget += c.Timeouts.Start
 	}
 	if action == "uninstall" {
-		budget += c.Timeouts.Stop + 1
+		budget += c.Timeouts.Uninstall + 2
 	}
 	if action != "start" && action != "stop" && action != "status" && action != "restart" && action != "uninstall" {
 		return 1, errors.New("unsupported daemon action")
@@ -414,7 +417,7 @@ func (c *controller) uninstall() error {
 	select {
 	case err := <-done:
 		return err
-	case <-time.After(time.Duration(c.Timeouts.Stop-1) * time.Second):
+	case <-time.After(time.Duration(c.Timeouts.Uninstall) * time.Second):
 		cmd.Process.Signal(syscall.SIGTERM)
 	}
 	select {