@synopackageland/cli 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,6 +1,239 @@
 # Changelog
 
-## Unreleased
+## 0.7.1 (2026-10-10)
+
+Rebuild packages to pick up template, hook and executor changes. The executor
+digest changed. A package built with CLI 0.7.0 needs one administrator approval
+after upgrading to a 0.7.1 build: the 0.7.0 executor opened the package
+`target` link without following it, so it cannot install the anchored executor
+itself. Executor-only upgrades between 0.7.1 or later builds need no approval.
+
+### Executor upgrade and daemon timeouts
+
+- During an INFO-anchored executor-only upgrade the executor log said
+  `executor paused: package pins require administrator approval` about two
+  seconds before the new executor was ready. That line now appears only when
+  the pins differ; an anchored handover logs only `executor upgrade:
+  INFO-anchored executor installed under the approved policy`. The executor
+  digest changes.
+
+- `executor_status_mismatch` in the app window and the app's settings names
+  its cause: `the approved executor is not answering (<reason>)`, `the running
+  executor reports other digests than this package pins`, or `the executor
+  status request failed` with the request's own code, instead of `scheduler
+  readback or operation failed` for all three. The Data and removal
+  troubleshooting table explains each.
+
+- After approval or control start the window asked `executor.status` every
+  500 ms for up to 10 s. The wait now doubles from 500 ms to 2 s within the
+  same 10 s budget: at most 7 requests instead of 20.
+
+- For live upgrade tests, the repository's `scripts/test/executor-bump.py`
+  makes an executor-only build+1 SPK and now rewrites the window script's
+  embedded pins with the INFO anchor and `executor/setup.json`. The earlier
+  out-of-tree copy left the window pins behind, so the panel reported
+  `executor_status_mismatch` after every such upgrade while CGI and CLI
+  status were ready.
+
+- On kernel 3.10 (DSM 7.1, for example DS416 armv7) an executor-only
+  upgrade, and approving again while the executor runs, no longer fail
+  with "pid executable mismatch". That kernel names a running executor
+  replaced by a rename after the rename source (`runtime/.executor
+  (deleted)`), and root control accepted only `runtime/executor`. Root
+  control now identifies the monitor by inode: the current
+  `runtime/executor`, or an unlinked root-owned inode on the runtime's
+  device whose last name was `executor` or `.executor*` in the runtime.
+  The fix runs in the new executor, which the installed one starts: an
+  upgrade from a package built with the target-link fix below needs no
+  approval; from 0.7.0 it still needs the one approval described there.
+  The executor digest changes.
+
+- When the approved tasks are ready but the executor does not answer
+  (`executor_status_mismatch`), the app window offers Approve background
+  access again. With the tasks approved, it restarts the executor without
+  a password.
+
+- `executor.status` (root-ops) names approval, not "Start the package", as
+  the next step when the package's last lifecycle request was start.
+  Regenerate or copy `backend/internal/app/executor.go`.
+
+- An executor-only upgrade (same policy, new executor matching the INFO
+  `synopkgland_executor_sha256` anchor) no longer fails with "executor
+  upgrade refused: INFO-anchored executor could not be installed". The
+  installer opened `/var/packages/<pkg>/target/executor` without following
+  the DSM `target` link, which the executor refuses, so every such upgrade
+  stayed paused. The fix runs in the executor that is already installed:
+  an upgrade from a package built with an earlier SDK still needs one
+  administrator approval. The executor digest changes.
+
+- `executor.status` (root-ops and delegate projects) no longer answers
+  `internal` while the executor is paused (package stopped, or pins waiting
+  for approval). It answers `{ready: false, state: "paused", reason:
+  "executor_not_listening", next}`, and `synopkgland status` shows the
+  reason and next step. Regenerate or copy
+  `backend/internal/app/executor.go` into existing projects.
+
+- `daemon.timeouts` defaults are now `{start: 30, stop: 30, status: 5,
+  uninstall: 60}` (were `start: 5, stop: 10, status: 2`). On vt-nas under
+  IO load a boot start took more than 5 s and a Connect revoke more than
+  9 s. The new `timeouts.uninstall` (2–120) bounds `uninstall_args`
+  separately; it used to get `stop - 1`, so an app had to raise the SIGKILL
+  wait to give its revoke time. DSM's package unit allows 3600 s for start
+  and stop. `inspect` still accepts SPKs built before `timeouts.uninstall`.
+  The manifest reference explains how to pick values from a loaded NAS.
+
+### Approval, identity and uninstall fixes
+
+- `identity: standalone`: "Continue with DSM" and every live revalidation
+  failed with `session_required` after a DSM web login, because DSM web
+  sessions enable SynoToken and DSM answers the `id` cookie alone with 119.
+  The backend now forwards the request's single `X-SYNO-TOKEN` header, which
+  the DSM window's `ctx.call` already sends, when it checks the DSM session.
+  Sessions without SynoToken still verify with the cookie alone. The token is
+  never put in a URL, logged or stored. This also unblocks root-ops approval
+  in an `identity: standalone` package, which stopped at `executor.control`.
+  Existing projects need the updated `internal/identity` files.
+- When approval created and read back both tasks but the executor then did
+  not start or report healthy, the window left the tasks behind, and with no
+  running executor there was no task inventory for uninstall to delete them.
+  The window now withdraws the tasks that approval created; tasks from an
+  earlier approval stay.
+- After a wrong password or a withdrawn approval, the window panel showed
+  only "Check status". It and the app's settings now keep the approve action.
+- Uninstall no longer logs `task cleanup unconfirmed` for every successful
+  delete: EventScheduler `delete` v1 and TaskScheduler `delete` v2 answer
+  `{"success":true}` without data, which now counts as confirmed. The task
+  definitions are unchanged, so no new approval is needed; the executor
+  digest changes.
+- The native root window (`@synopackageland/cli/authorization-sdk`) gave up
+  after about 30 s with `root_timeout`, while a loaded NAS ran the bootstrap
+  task for up to 4.5 minutes. It now keeps waiting while the task is queued or
+  running, up to 10 minutes, reports `{op, state, elapsedMs}` through
+  `options.progress`, and the authorization flow accepts the backend's ready
+  grant after `root_timeout` or `root_task_failed`.
+- A DSM certificate that Node does not trust failed with only
+  `fetch failed`. The CLI now reports `DSM_TLS_UNTRUSTED` with the origin and
+  certificate error and points to `NODE_EXTRA_CA_CERTS`; certificate checks
+  stay on.
+- Docs: on DSM 7.1 the purge timing lines are only in the journal
+  (`journalctl -t synopkgland-executor`); `init -t native-go` does not include
+  `armv7` in `arches`, so add it for an armv7 NAS.
+
+### Deploy and status fixes
+
+- `status` no longer reports `blocked` for every `identity: standalone`
+  project. It opens a short-lived App session from the administrator's DSM
+  session, reads `executor.status`, then logs out. That needs an `https://`
+  host; over `http://` the capability stays `blocked` and the reason says so.
+- `deploy` accepts the install wizard values of an `install-selected`
+  delegate: `--param delegate_share=<Shared Folder>` or
+  `--param delegate_home=true`. A first install without one now fails with
+  `DEPLOY_PARAM_REQUIRED` and a usage line before anything is built, instead
+  of failing inside DSM. Invalid values fail with `DEPLOY_PARAM_TYPE_INVALID`.
+- `deploy` and `status` work on a native layout (existing native product).
+  `deploy` builds the NAS architecture only; an `aarch64` NAS uses a declared
+  `armv8`.
+- The deploy note no longer says every upgrade needs approval: an
+  executor-only upgrade stays ready; a policy digest change needs approval.
+- Uninstall logs per-phase purge timing with the package name to the system
+  log (`synopkgland-executor`): `task cleanup timing` per task and
+  `purge timing` for the task and file phases. The executor digest changes.
+- `add root-ops` and `add portal` print a notice on stderr when they raise
+  `os_min_ver`.
+- `inspect` on an executor SPK describes the root boot and control tasks
+  instead of saying the package needs no root privileges.
+
+### DSM 7.1: root-ops and delegate approval work
+
+- DSM 7.1.1 has no `SYNO.Core.TaskScheduler.Root` or
+  `SYNO.Core.EventScheduler.Root`, TaskScheduler stops at v3 and
+  PasswordConfirm at v1, so approval failed with "Background file access is
+  unavailable" and `status`/`deploy` showed `rootOps: unsupported — DSM 103`
+  or `DSM 104`. DSM 7.1.1 answers a version above the API's maximum with 104
+  (PasswordConfirm v2, TaskScheduler `get` v4) and a method missing at an
+  existing version with 103 (TaskScheduler `list` v3). When DSM answers a
+  scheduler read or the password check with 103 or 104, the app now uses
+  PasswordConfirm v1, TaskScheduler `list` v2/`get` v3 and creates
+  the tasks with EventScheduler `create` v1 and TaskScheduler `create` v3.
+  The password is still confirmed first and both tasks are still read back
+  exactly before anything runs. Other errors (such as 105, 119, 102 or a
+  wrong password, 3121) never fall back, and a create is never retried. DSM
+  7.1 does not bind task creation to the password check; see the root-ops
+  guide.
+- `status` and `deploy` read the control task the same way.
+- Uninstall on DSM 7.1 now removes the boot and control tasks. The executor
+  looked the control task up with TaskScheduler `get` v4, which DSM 7.1.1
+  refuses with 104, so it wrote no task inventory and left both tasks behind.
+- If approval stops after it created a task (for example, the boot task was
+  created and the control task was not), the app deletes the tasks it created
+  in that attempt instead of leaving an enabled root boot task that nothing
+  owns. Tasks from an earlier approval stay.
+- A failed approval shows its reason and DSM error code in the app's settings
+  instead of only "Background file access is unavailable", and a refused
+  password reads as a password failure, not a scheduler failure.
+- After the app's settings approve, the window's status line no longer shows
+  "needs-admin-approval: Task is missing" until a reload; the window panel and
+  the settings now follow each other's results.
+
+### DSM 7.1: jobs import and file downloads
+
+- DSM 7.1.1 sends `SYNO.FileStation.Download` v2 replies without
+  `Content-Disposition`, so `bg.jobs.submit` and downloads failed with
+  `unavailable`. With no such header, a body of at most 4 KiB that decodes
+  as a DSM reply is still refused as that reply; any other body is the file.
+
+### Docs: build your own armv7 Go code with Go 1.26.9
+
+- On armv7 DSM 7.1.1 (kernel 3.10), a program built with Go 1.26.0 crashed
+  at start (`futexwakeup returned -22`, SIGSEGV) and Go 1.26.9 ran. Other
+  1.26 releases were not tested.
+
+### init: next steps install frontend dependencies
+
+- `init -t native-go` with a Vue frontend now lists `(cd frontend && npm ci)`
+  before `synopkgland build`; without it the build fails with
+  `STANDALONE_UI_BUILD_FAILED`. `build` still does not install dependencies.
+
+### Executor, daemon and gateway build with exactly Go 1.26.9
+
+- The CLI builds the executor, lifecycle helper, daemon controller and gateway
+  with `GOTOOLCHAIN=go1.26.9`, ignoring your `GOTOOLCHAIN`, `GOFLAGS`,
+  `GOEXPERIMENT`, `GOWORK` and `GOAMD64`/`GOARM64`, so every builder produces
+  the same executor digest. Go 1.21 or later downloads go1.26.9 when needed;
+  offline without it the build fails and names go1.26.9. A binary whose Go
+  build info names another release is refused.
+- Template go.mod files now say `toolchain go1.26.9`. The executor digest
+  changes; it is anchored in INFO, so an upgrade with an unchanged policy needs
+  no new approval.
+
+### INFO arch: four more DSM platforms
+
+- x86_64 SPKs now also list `broadwellntb`, `coffeelake` and `skylaked`, and
+  aarch64 SPKs list `rtd1619` (DSM Developer Guide Appendix A family members).
+  INFO `arch` now matches the platforms the package source maps to each family.
+
+### 繁體中文摘要
+
+- 升級後重新建置套件；executor digest 改變。**從 0.7.0 建的套件升級需管理員再核准一次**（0.7.0 的
+  executor 開啟套件 `target` symlink 時未跟隨連結，無法自行安裝錨定的 executor）；之後 0.7.1 起的
+  executor-only 升級不需核准。
+- executor：kernel 3.10（DSM 7.1，如 DS416 armv7）上 executor-only 升級與執行中再核准不再出現
+  `pid executable mismatch`；INFO 錨定升級不再誤報 `executor upgrade refused`，也不再先印
+  「paused: 需管理員核准」；`executor.status` 暫停時回 `paused`／`executor_not_listening` 與下一步。
+- 面板：executor 不回應時可再按一次「Approve background access」免密碼重啟；
+  `executor_status_mismatch` 會寫出原因（不回應／digest 不同／status 請求失敗）；
+  啟動後的 `executor.status` 等待改為 500 ms→2 s 退避，10 s 預算不變。
+- `daemon.timeouts` 預設改為 `{start: 30, stop: 30, status: 5, uninstall: 60}`，新增 `timeouts.uninstall`。
+- `identity: standalone`：DSM 網頁 session（SynoToken）下「Continue with DSM」與 root-ops 核准修正；
+  核准建立 task 後 executor 未啟動時自動撤回本次建立的 task；卸載不再誤記 `task cleanup unconfirmed`。
+- 原生 root window 等待上限改為 10 分鐘並回報進度；`DSM_TLS_UNTRUSTED` 指向 `NODE_EXTRA_CA_CERTS`。
+- `status`／`deploy`：standalone 專案的 status 改用短期 App session；`deploy` 接受
+  install-selected delegate 的精靈參數；支援 native layout；卸載記錄 purge timing。
+- DSM 7.1：無 Root API 時改走 PasswordConfirm v1／TaskScheduler v2–v3／EventScheduler create v1，
+  卸載會移除 boot／control task；`SYNO.FileStation.Download` v2 無 `Content-Disposition` 的下載修正。
+- 建置：executor、lifecycle、daemon、gateway 一律以 Go 1.26.9 建置（armv7 kernel 3.10 上 1.26.0 會當機）；
+  INFO `arch` 新增 `broadwellntb`、`coffeelake`、`skylaked`、`rtd1619`。
+- 測試工具：`scripts/test/executor-bump.py` 收進 repo，會一併改寫視窗腳本內嵌的 executor pin。
 
 ## 0.7.0 (2026-10-10)
 

package/dist/add.d.ts

@@ -1,4 +1,7 @@
-export declare function addCapabilities(root: string, requested: string[]): {
+type AddResult = {
     added: string[];
     unchanged: string[];
+    notes?: string[];
 };
+export declare function addCapabilities(root: string, requested: string[]): AddResult;
+export {};

package/dist/add.js

@@ -46,11 +46,17 @@ function safePath(root, file) {
     }
     return true;
 }
-/** Raise a lower os_min_ver to the floor a capability needs; a higher one stays. */
-function raiseOsMinVer(doc, current, floor) {
+/** Raise a lower os_min_ver to the floor a capability needs; a higher one stays. Returns the notice. */
+function raiseOsMinVer(doc, current, floor, capability) {
     const osMinVer = doc.get('os_min_ver', true);
-    if (isScalar(osMinVer) && !isDsmAtLeast(current, floor))
-        osMinVer.value = floor;
+    if (!isScalar(osMinVer) || isDsmAtLeast(current, floor))
+        return [];
+    osMinVer.value = floor;
+    return [`os_min_ver raised from ${current} to ${floor}: ${capability} needs DSM ${floor} or later.`];
+}
+function withNotes(result, notes) {
+    const all = [...(result.notes ?? []), ...notes];
+    return all.length ? { ...result, notes: all } : result;
 }
 /**
  * `portal: {}` in dsm-package.yaml; the Go and binary starters already carry the UI and backend side.
@@ -67,9 +73,9 @@ function addPortal(root, result) {
     const manifestPath = join(root, 'dsm-package.yaml');
     const doc = parseDocument(readFileSync(manifestPath, 'utf8'));
     doc.set('portal', doc.createNode({}, { flow: true }));
-    raiseOsMinVer(doc, loaded.manifest.os_min_ver, PORTAL_MIN_DSM);
+    const notes = raiseOsMinVer(doc, loaded.manifest.os_min_ver, PORTAL_MIN_DSM, 'portal');
     writeFileSync(manifestPath, String(doc));
-    return { ...result, added: [...result.added, 'portal'] };
+    return withNotes({ ...result, added: [...result.added, 'portal'] }, notes);
 }
 export function addCapabilities(root, requested) {
     const wanted = [...new Set(requested.flatMap(value => value.split(',')).map(value => value.trim()))];
@@ -129,8 +135,7 @@ export function addCapabilities(root, requested) {
         for (const [key, value] of Object.entries(nativeCapabilitySettings(added)))
             doc.setIn(['capabilities', key], value);
         // rootOps needs DSM 7.1-42661 or later.
-        if (added.includes('root-ops'))
-            raiseOsMinVer(doc, m.os_min_ver, DEFAULT_MIN_DSM);
+        const notes = added.includes('root-ops') ? raiseOsMinVer(doc, m.os_min_ver, DEFAULT_MIN_DSM, 'root-ops') : [];
         for (const file of destinations) {
             const path = join(root, file);
             mkdirSync(dirname(path), { recursive: true });
@@ -139,7 +144,7 @@ export function addCapabilities(root, requested) {
         for (const file of deletions)
             rmSync(join(root, file), { force: true });
         writeFileSync(manifestPath, String(doc));
-        return { added, unchanged };
+        return withNotes({ added, unchanged }, notes);
     }
     finally {
         rmSync(work, { recursive: true, force: true });

package/dist/build-spk/dsm-platforms.json

@@ -7,9 +7,11 @@
             "broadwell",
             "broadwellnk",
             "broadwellnkv2",
+            "broadwellntb",
             "broadwellntbap",
             "bromolow",
             "cedarview",
+            "coffeelake",
             "denverton",
             "epyc7002",
             "epyc7003",
@@ -23,13 +25,14 @@
             "purley",
             "r1000",
             "r1000nk",
+            "skylaked",
             "v1000",
             "v1000nk"
         ],
         "platformOnly": []
     },
     "aarch64": {
-        "members": ["armada37xx", "rtd1296", "rtd1619b"],
+        "members": ["armada37xx", "rtd1296", "rtd1619", "rtd1619b"],
         "platformOnly": []
     },
     "armv7": {

package/dist/build-spk/gateway.d.ts

@@ -1,6 +1,6 @@
 import { type CommandRunner } from "../standalone/build.js";
 import type { AppContract } from "../types.js";
-import { type NativeArchFamily } from "./dsm-arch.js";
+import type { NativeArchFamily } from "./dsm-arch.js";
 export { gatewayEntryPath } from "../contract/web-launch.js";
 /** Where the gateway CGI sits in the package payload; DSM serves `ui/` under /webman/3rdparty/<package>/. */
 export declare const GATEWAY_CGI_PAYLOAD = "ui/cgi/gateway.cgi";

package/dist/build-spk/gateway.js

@@ -4,7 +4,7 @@ import { checkCgiBinary } from "../standalone/binary.js";
 import { runCommand } from "../standalone/build.js";
 import { resolvedWebAccess } from "../contract/web-launch.js";
 import { templatesRoot } from "../template-paths.js";
-import { goBuildEnv } from "./dsm-arch.js";
+import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem } from "./go-toolchain.js";
 export { gatewayEntryPath } from "../contract/web-launch.js";
 /** Where the gateway CGI sits in the package payload; DSM serves `ui/` under /webman/3rdparty/<package>/. */
 export const GATEWAY_CGI_PAYLOAD = "ui/cgi/gateway.cgi";
@@ -29,18 +29,22 @@ export function buildGatewayBinary(input) {
     const ldflags = ["-s", "-w", "-buildid=", `-X main.packageID=${input.packageId}`, `-X 'main.configJSON=${JSON.stringify(input.config)}'`].join(" ");
     const result = (input.run ?? runCommand)("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, "."], {
         cwd: join(templatesRoot(), "_gateway"),
-        env: { ...process.env, ...goBuildEnv(input.arch) },
+        env: { ...process.env, ...pinnedGoBuildEnv(input.arch) },
     });
     if (result.missing) {
-        return { error: "GATEWAY_GO_MISSING", detail: "找不到 go 指令。DSM 驗證閘道需要 Go 1.24 以上版本（https://go.dev/dl/）才能建置。" };
+        return { error: "GATEWAY_GO_MISSING", detail: `找不到 go 指令。DSM 驗證閘道需要 Go 1.21 以上版本（https://go.dev/dl/）才能建置。${PINNED_GO_HINT}` };
     }
     if (result.status !== 0) {
-        return { error: "GATEWAY_BUILD_FAILED", detail: `go build（${input.arch}）失敗。\n${result.stderr}` };
+        return { error: "GATEWAY_BUILD_FAILED", detail: `go build（${input.arch}）失敗。${PINNED_GO_HINT}\n${result.stderr}` };
     }
     const problem = checkCgiBinary(input.work, out, input.arch);
     if (problem) {
         return { error: "GATEWAY_BUILD_FAILED", detail: problem.message };
     }
+    const toolchainProblem = pinnedGoProblem(out);
+    if (toolchainProblem) {
+        return { error: "GATEWAY_BUILD_FAILED", detail: toolchainProblem };
+    }
     return { binary: out };
 }
 /** Puts the CGI (mode 0755) and its readable configuration into the package payload. */

package/dist/build-spk/go-toolchain.d.ts

@@ -0,0 +1,20 @@
+import { type NativeArchFamily } from "./dsm-arch.js";
+/**
+ * The Go release that compiles every binary the CLI ships from its own
+ * templates, so their digests do not depend on the builder's Go. Each
+ * template go.mod names it in its `toolchain` line.
+ */
+export declare const PINNED_GO_TOOLCHAIN = "go1.26.9";
+/**
+ * The `go build` environment for a binary the CLI ships from its own templates
+ * (executor, lifecycle helper, daemon controller, gateway). GOTOOLCHAIN names
+ * the exact release, overriding `local` or `auto`: Go 1.21+ runs it from PATH
+ * or the module cache, or downloads it, and fails when it cannot.
+ */
+export declare function pinnedGoBuildEnv(family: NativeArchFamily): Record<string, string>;
+/** The Go release recorded in a binary's build info (Go 1.18+ layout), or undefined. */
+export declare function goBinaryVersion(file: string): string | undefined;
+/** Why a CLI-owned binary cannot ship: it was not built by the pinned Go release. */
+export declare function pinnedGoProblem(file: string): string | undefined;
+/** Appended to a failed CLI-owned `go build`: what the build needs. */
+export declare const PINNED_GO_HINT = "These binaries need go1.26.9: Go 1.21 or later downloads it automatically; offline, install go1.26.9 on PATH or allow GOPROXY to serve golang.org/toolchain.";

package/dist/build-spk/go-toolchain.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { goBuildEnv } from "./dsm-arch.js";
+/**
+ * The Go release that compiles every binary the CLI ships from its own
+ * templates, so their digests do not depend on the builder's Go. Each
+ * template go.mod names it in its `toolchain` line.
+ */
+export const PINNED_GO_TOOLCHAIN = "go1.26.9";
+/**
+ * The `go build` environment for a binary the CLI ships from its own templates
+ * (executor, lifecycle helper, daemon controller, gateway). GOTOOLCHAIN names
+ * the exact release, overriding `local` or `auto`: Go 1.21+ runs it from PATH
+ * or the module cache, or downloads it, and fails when it cannot.
+ */
+export function pinnedGoBuildEnv(family) {
+    return { ...goBuildEnv(family), GOTOOLCHAIN: PINNED_GO_TOOLCHAIN, GOFLAGS: "", GOEXPERIMENT: "", GOWORK: "off", GOAMD64: "v1", GOARM64: "v8.0" };
+}
+const BUILD_INFO_MAGIC = Buffer.from("\xff Go buildinf:", "latin1");
+const BUILD_INFO_INLINE_STRINGS = 0x2;
+/** The Go release recorded in a binary's build info (Go 1.18+ layout), or undefined. */
+export function goBinaryVersion(file) {
+    const bytes = readFileSync(file);
+    const start = bytes.indexOf(BUILD_INFO_MAGIC);
+    if (start < 0 || !(bytes[start + 15] & BUILD_INFO_INLINE_STRINGS))
+        return undefined;
+    let length = 0, shift = 0, at = start + 32;
+    for (;;) {
+        const byte = bytes[at++];
+        if (byte === undefined || shift > 28)
+            return undefined;
+        length |= (byte & 0x7f) << shift;
+        shift += 7;
+        if (byte < 0x80)
+            break;
+    }
+    return bytes.subarray(at, at + length).toString("latin1") || undefined;
+}
+/** Why a CLI-owned binary cannot ship: it was not built by the pinned Go release. */
+export function pinnedGoProblem(file) {
+    const version = goBinaryVersion(file);
+    return version === PINNED_GO_TOOLCHAIN ? undefined : `${file} was built by ${version ?? "an unknown Go release"}, not ${PINNED_GO_TOOLCHAIN}.`;
+}
+/** Appended to a failed CLI-owned `go build`: what the build needs. */
+export const PINNED_GO_HINT = `These binaries need ${PINNED_GO_TOOLCHAIN}: Go 1.21 or later downloads it automatically; offline, install ${PINNED_GO_TOOLCHAIN} on PATH or allow GOPROXY to serve golang.org/toolchain.`;

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { Command, CommanderError } from "commander";
-import { readFileSync, renameSync } from "node:fs";
+import { existsSync, readFileSync, renameSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { findProjectRoot } from "./discovery.js";
 import { loadContract } from "./contract/load.js";
@@ -62,7 +62,11 @@ function formatSpkInspection(spk, report) {
         "payload：",
         ...(report.uninstallCleanup ?? []).map(item => `Uninstall cleanup (if needed)：${item.target} — ${item.condition} ${item.action}`),
         ...report.payload.map((e) => `  ${e.mode} ${e.path}`),
-        report.findings.length ? "問題：" : "檢查：沒有 root 權限需求或異常。",
+        report.findings.length
+            ? "問題："
+            : report.executor
+                ? "檢查：沒有異常。管理員核准後會建立 root executor 排程（boot 與 control task），以 root 執行此 SPK 固定的 executor 與 policy。"
+                : "檢查：沒有 root 權限需求或異常。",
         ...report.findings.map((f) => `  - ${f}`),
     ].join("\n");
 }
@@ -234,13 +238,15 @@ export async function runCli(argv) {
         });
         stdout(`已建立 ${options.template} 專案於 ${targetDir}`);
         if (options.template === "native-go")
-            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n  synopkgland build\n說明見 README.md。`);
+            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n${existsSync(join(targetDir, "frontend", "package.json")) ? "  (cd frontend && npm ci)\n" : ""}  synopkgland build\n說明見 README.md。`);
     });
     program
         .command("add <caps...>")
         .description(`加入能力（${CAPABILITY_NAMES.join("、")}）或 portal 與 SDK-owned overlay；不覆寫既有應用檔案`)
         .action((caps, _options, command) => {
         const result = addCapabilities(rootOf(command), caps);
+        for (const note of result.notes ?? [])
+            console.error(`[注意] ${note}`);
         stdout(`已新增：${result.added.join(", ") || "無"}；已存在：${result.unchanged.join(", ") || "無"}`);
     });
     program
@@ -281,7 +287,7 @@ export async function runCli(argv) {
         .option("--dev", "Development Package Identity")
         .option("--share <slot=name>", "Compose 共用資料夾", (value, previous) => collectKv(value, previous, "--share"))
         .option("--run-as <slot=name>", "Compose DSM 使用者", (value, previous) => collectKv(value, previous, "--run-as"))
-        .option("--param <NAME=value>", "Compose 安裝參數", (value, previous) => collectKv(value, previous, "--param"))
+        .option("--param <NAME=value>", "安裝參數（Compose）或安裝精靈值（native-go／binary）", (value, previous) => collectKv(value, previous, "--param"))
         .option("--dry-run", "只輸出本機部署計畫，不連接 NAS")
         .action(async (options, command) => {
         if (options.arch !== undefined &&
@@ -292,15 +298,15 @@ export async function runCli(argv) {
             dev: options.dev,
         });
         if (plan.kind !== "container" &&
-            (options.share || options.runAs || options.param))
-            throw failure("CLI_OPTION_INVALID", "native-go／binary 不接受 Compose 安裝參數。");
+            (options.share || options.runAs))
+            throw failure("CLI_OPTION_INVALID", "native-go／binary 不接受 --share／--run-as；安裝精靈值請用 --param。");
         if (options.dryRun) {
             emit("deploy", plan, JSON.stringify(plan, null, 2));
             return;
         }
         if (plan.kind !== "container") {
             const host = hostOf(options.host);
-            const output = await deployStandalone(plan, host);
+            const output = await deployStandalone(plan, host, { params: options.param });
             const status = await standaloneInfo({ root: plan.root, host });
             emit("deploy", { ...plan, output, status }, `已部署 ${plan.packageId}: ${output}\n${formatProjectInfo(status)}${plan.notes.length ? "\n" + plan.notes.join("\n") : ""}`);
             return;

package/dist/deploy/native-install-values.d.ts

@@ -0,0 +1,17 @@
+import type { StandaloneManifest } from "../standalone/manifest.js";
+export type NativeInstallValuesResult = {
+    ok: true;
+    extraValues: Record<string, string>;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Install wizard values for a native-go/binary deploy. Only an install-selected
+ * delegate asks the wizard for anything; preinst refuses an empty selection on
+ * the first install, so refuse it here before building or uploading.
+ */
+export declare function resolveNativeInstallValues(manifest: StandaloneManifest, provided: Record<string, string>, state: {
+    installed: boolean;
+}): NativeInstallValuesResult;

package/dist/deploy/native-install-values.js

@@ -0,0 +1,32 @@
+const USAGE = "synopkgland deploy --param delegate_share=<shared folder>，或 --param delegate_home=true";
+/** Mirrors the preinst draft check in build-spk/delegate-scope.ts. */
+function validShareName(name) {
+    return (name !== "" && name !== "." && !name.includes("..") &&
+        !/[/\\:"%\x00-\x1f\x7f]/.test(name) &&
+        !/^homes?$/i.test(name) && name.trim() === name && name.length <= 256);
+}
+/**
+ * Install wizard values for a native-go/binary deploy. Only an install-selected
+ * delegate asks the wizard for anything; preinst refuses an empty selection on
+ * the first install, so refuse it here before building or uploading.
+ */
+export function resolveNativeInstallValues(manifest, provided, state) {
+    const fail = (code, message) => ({ ok: false, code, message });
+    const selected = manifest.capabilities.delegate?.scope === "install-selected";
+    const names = Object.keys(provided);
+    if (!selected && names.length)
+        return fail("DEPLOY_PARAM_UNDECLARED", `${manifest.package} has no install wizard values; remove --param ${names[0]}.`);
+    const unknown = names.find((name) => name !== "delegate_share" && name !== "delegate_home");
+    if (unknown)
+        return fail("DEPLOY_PARAM_UNDECLARED", `--param ${unknown} is not an install wizard value. Use: ${USAGE}.`);
+    const { delegate_share: share, delegate_home: home } = provided;
+    if (home !== undefined && home !== "true" && home !== "false")
+        return fail("DEPLOY_PARAM_TYPE_INVALID", "--param delegate_home must be true or false.");
+    if (share !== undefined && !validShareName(share))
+        return fail("DEPLOY_PARAM_TYPE_INVALID", `--param delegate_share must be one Shared Folder name, not a path, home or homes.`);
+    if (share !== undefined && home === "true")
+        return fail("DEPLOY_PARAM_TYPE_INVALID", "Choose either --param delegate_share or --param delegate_home=true, not both.");
+    if (selected && !state.installed && share === undefined && home !== "true")
+        return fail("DEPLOY_PARAM_REQUIRED", `The first install of ${manifest.package} must select the delegate scope: ${USAGE}.`);
+    return { ok: true, extraValues: { ...provided } };
+}

package/dist/deploy/plan.d.ts

@@ -1,8 +1,9 @@
+import { type CommandRunner } from "../standalone/build.js";
 import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import type { NasHost } from "../host/types.js";
 export interface DeploymentPlan {
     root: string;
-    kind: "native-go" | "binary" | "container";
+    kind: "native-go" | "binary" | "native-layout" | "container";
     packageId: string;
     version: string;
     arch?: NativeArchFamily;
@@ -15,4 +16,7 @@ export declare function planDeployment(root: string, options?: {
     arch?: NativeArchFamily;
     dev?: boolean;
 }): DeploymentPlan;
-export declare function deployStandalone(plan: DeploymentPlan, host: NasHost): Promise<string>;
+export declare function deployStandalone(plan: DeploymentPlan, host: NasHost, options?: {
+    params?: Record<string, string>;
+    run?: CommandRunner;
+}): Promise<string>;