@synopackageland/cli 0.6.1 → 0.7.0

package/templates/_executor/supervise_test.go

@@ -0,0 +1,130 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"reflect"
+	"testing"
+	"time"
+)
+
+type superviseFixture struct {
+	scripts []string
+	revived []bool
+	delays  []time.Duration
+	present bool
+	clock   time.Time
+	runFor  []time.Duration
+}
+
+// Each run executes a real child so exit status and signal death come from the
+// kernel, exactly as the supervisor sees serve.
+func (f *superviseFixture) run(ctx context.Context, revived bool) error {
+	i := len(f.revived)
+	f.revived = append(f.revived, revived)
+	if i < len(f.runFor) {
+		f.clock = f.clock.Add(f.runFor[i])
+	}
+	script := "exit 0"
+	if i < len(f.scripts) {
+		script = f.scripts[i]
+	}
+	return exec.CommandContext(ctx, "/bin/sh", "-c", script).Run()
+}
+func (f *superviseFixture) sleep(_ context.Context, d time.Duration) bool {
+	f.delays = append(f.delays, d)
+	return true
+}
+func (f *superviseFixture) supervise(ctx context.Context) error {
+	return supervise(ctx, f.run, func() bool { return f.present }, f.sleep, func() time.Time { return f.clock }, func(string) {})
+}
+
+func TestSuperviseRestartsAbnormalServeUntilCleanExit(t *testing.T) {
+	f := &superviseFixture{present: true, scripts: []string{"kill -KILL $$", "exit 1", "exit 0"}}
+	if err := f.supervise(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if want := []bool{false, true, true}; !reflect.DeepEqual(f.revived, want) {
+		t.Fatalf("revived %v, want %v", f.revived, want)
+	}
+	if want := []time.Duration{time.Second, 2 * time.Second}; !reflect.DeepEqual(f.delays, want) {
+		t.Fatalf("delays %v, want %v", f.delays, want)
+	}
+}
+
+func TestSuperviseLeavesWhenAnotherMonitorOwnsThePidfile(t *testing.T) {
+	f := &superviseFixture{present: true, scripts: []string{"exit 3", "exit 0"}}
+	if err := f.supervise(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if len(f.revived) != 1 || len(f.delays) != 0 {
+		t.Fatalf("runs %v delays %v", f.revived, f.delays)
+	}
+}
+
+func TestSuperviseStopsOnceRuntimeIsPurged(t *testing.T) {
+	f := &superviseFixture{present: false, scripts: []string{"kill -KILL $$", "exit 0"}}
+	if err := f.supervise(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if len(f.revived) != 1 || len(f.delays) != 0 {
+		t.Fatalf("runs %v delays %v", f.revived, f.delays)
+	}
+}
+
+func TestSuperviseBacksOffToCapAndResetsAfterStableRun(t *testing.T) {
+	scripts := make([]string, 10)
+	for i := range scripts {
+		scripts[i] = "exit 2"
+	}
+	scripts = append(scripts, "exit 0")
+	runFor := make([]time.Duration, len(scripts))
+	runFor[8] = time.Minute
+	f := &superviseFixture{present: true, scripts: scripts, runFor: runFor}
+	if err := f.supervise(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	s := time.Second
+	want := []time.Duration{s, 2 * s, 4 * s, 8 * s, 16 * s, 32 * s, 60 * s, 60 * s, s, 2 * s}
+	if !reflect.DeepEqual(f.delays, want) {
+		t.Fatalf("delays %v, want %v", f.delays, want)
+	}
+}
+
+func TestSuperviseTerminationEndsWithoutRestart(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	f := &superviseFixture{present: true, scripts: []string{"sleep 30", "exit 0"}}
+	time.AfterFunc(100*time.Millisecond, cancel)
+	if err := f.supervise(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if len(f.revived) != 1 || len(f.delays) != 0 {
+		t.Fatalf("runs %v delays %v", f.revived, f.delays)
+	}
+}
+
+func TestRootStartLaunchesSupervisorThatRevivesServe(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("checks the non-root refusal")
+	}
+	if err := run([]string{"supervise", "--package", "TestApp"}); err == nil || err.Error() != "root required" {
+		t.Fatalf("supervise mode: %v", err)
+	}
+	if err := run([]string{"control", "start", "--package", "TestApp", "--revived"}); err == nil || err.Error() != "unexpected revive" {
+		t.Fatalf("revive outside serve: %v", err)
+	}
+	if got := supervisorCommand("/x/runtime/executor", "TestApp").Args; !reflect.DeepEqual(got, []string{"/x/runtime/executor", "supervise", "--package", "TestApp"}) {
+		t.Fatal(got)
+	}
+	for revived, want := range map[bool][]string{false: {"serve", "--package", "TestApp"}, true: {"serve", "--package", "TestApp", "--revived"}} {
+		if got := serveArgs("TestApp", revived); !reflect.DeepEqual(got, want) {
+			t.Fatal(got)
+		}
+	}
+	if exitStatus(fmt.Errorf("serve: %w", errAlreadyRunning)) != exitAlreadyRunning || exitStatus(errors.New("other")) != 1 {
+		t.Fatal("exit status")
+	}
+}

package/templates/_executor/task_race_review_test.go

@@ -24,7 +24,7 @@ func (s *reviewEditDuringDelete) Exec(ctx context.Context, path string, args []s
 }
 func TestReviewPurgeAcceptedAdminRaceLogsRemainingTasksWithoutRetry(t *testing.T) {
 	cmd := &reviewEditDuringDelete{}
-	inv := taskInventory{Package: "TestApp", ExecutorDigest: strings.Repeat("a", 64), PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
+	inv := taskInventory{Package: "TestApp", PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
 	logs := []string{}
 	purgeTasks(context.Background(), &liveDSM{Command: cmd}, "TestApp", inv, func(s string) { logs = append(logs, s) })
 	if len(cmd.deleted) != 1 {

package/templates/_executor/tasks.go

@@ -18,15 +18,14 @@ type approvedTask struct {
 	ScriptDigest string `json:"script_digest"`
 }
 type taskInventory struct {
-	Package        string         `json:"package"`
-	ExecutorDigest string         `json:"executor_digest"`
-	PolicyDigest   string         `json:"policy_digest"`
-	Tasks          []approvedTask `json:"tasks"`
+	Package      string         `json:"package"`
+	PolicyDigest string         `json:"policy_digest"`
+	Tasks        []approvedTask `json:"tasks"`
 }
 
 func hashBytes(b []byte) string { h := sha256.Sum256(b); return hex.EncodeToString(h[:]) }
 func validInventory(pkg string, inventory taskInventory) bool {
-	if inventory.Package != pkg || len(inventory.Tasks) != 2 || !idRE.MatchString(inventory.ExecutorDigest) || !idRE.MatchString(inventory.PolicyDigest) {
+	if inventory.Package != pkg || len(inventory.Tasks) != 2 || !idRE.MatchString(inventory.PolicyDigest) {
 		return false
 	}
 	seen := map[string]bool{}
@@ -150,11 +149,11 @@ func snapshotTasks(ctx context.Context, d *liveDSM, pkg, ed, pd, setupPath, runt
 	if strictJSON(b, &setup) != nil || setup.Package != pkg || setup.ExecutorDigest != ed || setup.PolicyDigest != pd || setup.Implementation != "executor" {
 		return errors.New("setup pins")
 	}
-	generated, err := taskscript.Generate(pkg, ed, pd)
+	generated, err := taskscript.Generate(pkg, pd)
 	if err != nil || len(setup.Tasks) != len(generated) {
 		return errors.New("setup task inventory")
 	}
-	inv := taskInventory{Package: pkg, ExecutorDigest: ed, PolicyDigest: pd}
+	inv := taskInventory{Package: pkg, PolicyDigest: pd}
 	for i, task := range generated {
 		hint := setup.Tasks[i]
 		if hint.Kind != task.Kind || hint.Name != task.Name || hint.Header != task.Header || hint.Script != task.Script {
@@ -214,7 +213,7 @@ func purgeTasks(ctx context.Context, d *liveDSM, pkg string, inv taskInventory,
 		log("task cleanup skipped: invalid protected inventory")
 		return
 	}
-	generated, err := taskscript.Generate(pkg, inv.ExecutorDigest, inv.PolicyDigest)
+	generated, err := taskscript.Generate(pkg, inv.PolicyDigest)
 	if err != nil {
 		log("task cleanup skipped: invalid protected pins")
 		return

package/templates/_executor/tasks_review_test.go

@@ -35,7 +35,7 @@ func TestReviewSnapshotRejectsUnrelatedSameNamedRootTasks(t *testing.T) {
 func TestReviewPurgeRejectsUnrelatedSameNamedRootTasks(t *testing.T) {
 	script := "#!/bin/sh\n# synopkgland executor boot\n# " + strings.Repeat("a", 64) + strings.Repeat("b", 64) + "\necho unrelated-backup-task\n"
 	cmd := &schedulerFixture{script: script}
-	inv := taskInventory{Package: "TestApp", ExecutorDigest: strings.Repeat("a", 64), PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: hashBytes([]byte(script))}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: hashBytes([]byte(script))}}}
+	inv := taskInventory{Package: "TestApp", PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: hashBytes([]byte(script))}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: hashBytes([]byte(script))}}}
 	purgeTasks(context.Background(), &liveDSM{Command: cmd}, "TestApp", inv, func(string) {})
 	if len(cmd.deleted) != 0 {
 		t.Fatal("deleted unrelated tasks", cmd.deleted)

package/templates/_executor/tasks_test.go

@@ -31,7 +31,7 @@ func (s *schedulerFixture) Exec(_ context.Context, _ string, args []string) ([]b
 	if s.foreignOwner {
 		owner = "other"
 	}
-	generated, _ := taskscript.Generate("TestApp", strings.Repeat("a", 64), strings.Repeat("b", 64))
+	generated, _ := taskscript.Generate("TestApp", strings.Repeat("b", 64))
 	script := generated[1].Script
 	if api == "SYNO.Core.EventScheduler" {
 		script = generated[0].Script
@@ -66,7 +66,7 @@ func TestPurgeDeletesOnlyExactOwnRootTasksAndProtectedState(t *testing.T) {
 	for _, mode := range []string{"exact", "script changed", "owner changed", "duplicate control", "foreign name"} {
 		t.Run(mode, func(t *testing.T) {
 			cmd := &schedulerFixture{changed: mode == "script changed", foreignOwner: mode == "owner changed", duplicate: mode == "duplicate control"}
-			inventory := taskInventory{Package: "TestApp", ExecutorDigest: strings.Repeat("a", 64), PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
+			inventory := taskInventory{Package: "TestApp", PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
 			if mode == "foreign name" {
 				inventory.Tasks[0].Name = "OtherApp executor boot"
 			}
@@ -101,7 +101,7 @@ func TestSnapshotRequiresBothExactSchedulerDefinitionsBeforeWritingInventory(t *
 			ed := strings.Repeat("a", 64)
 			pd := strings.Repeat("b", 64)
 			tasks := []map[string]string{}
-			generated, err := taskscript.Generate("TestApp", ed, pd)
+			generated, err := taskscript.Generate("TestApp", pd)
 			if err != nil {
 				t.Fatal(err)
 			}
@@ -152,7 +152,7 @@ func (s *snapshotFixture) Exec(ctx context.Context, path string, args []string)
 
 func canonicalTaskDigest(t *testing.T, kind string) string {
 	t.Helper()
-	tasks, err := taskscript.Generate("TestApp", strings.Repeat("a", 64), strings.Repeat("b", 64))
+	tasks, err := taskscript.Generate("TestApp", strings.Repeat("b", 64))
 	if err != nil {
 		t.Fatal(err)
 	}

package/templates/_executor/watch.go

@@ -32,6 +32,14 @@ func newLifecycleMonitor(pkg, packageDir, control string, log func(string)) *lif
 	return m
 }
 
+// A supervisor restart carries no new approval, so a stop already in the
+// mailbox stays in force.
+func newRevivedLifecycleMonitor(pkg, packageDir, control string, log func(string)) *lifecycleMonitor {
+	m := newLifecycleMonitor(pkg, packageDir, control, log)
+	m.initialStop = nil
+	return m
+}
+
 // DSM's var link is expected. Resolve its parent, then reject final symlinks,
 // FIFOs and oversized input. Linux openRegular pins all resolved components.
 func readLifecycleFile(path string, limit int) ([]byte, os.FileInfo, error) {

package/templates/_executor/watch_test.go

@@ -209,7 +209,8 @@ func TestLifecycleWatchIgnoresInvalidControlAndResumesAfterOldStop(t *testing.T)
 	os.WriteFile(control, []byte("stop\n"), 0600)
 	var mu sync.Mutex
 	logs := 0
-	monitor := newLifecycleMonitor("TestApp", pkg, control, func(string) { mu.Lock(); logs++; mu.Unlock() })
+	observed := make(chan struct{}, 32)
+	monitor := newLifecycleMonitor("TestApp", pkg, control, func(string) { mu.Lock(); logs++; mu.Unlock(); observed <- struct{}{} })
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
 	defer cancel()
 	result := make(chan string, 1)
@@ -225,7 +226,13 @@ func TestLifecycleWatchIgnoresInvalidControlAndResumesAfterOldStop(t *testing.T)
 	checkRunning()
 	for _, value := range []string{"STOP", " purge", "purge\n\n", "purge;id", "wrong"} {
 		os.WriteFile(control, []byte(value), 0600)
-		checkRunning()
+		select {
+		case <-observed:
+		case got := <-result:
+			t.Fatalf("unexpected action %q", got)
+		case <-ctx.Done():
+			t.Fatal("invalid request not observed")
+		}
 	}
 	mu.Lock()
 	count := logs
@@ -268,3 +275,17 @@ func TestLifecycleMonitorReadsStartAfterStopAndKeepsCheckingPurge(t *testing.T)
 		}
 	}
 }
+
+// A supervisor restart is not a new administrator approval: the stop already in
+// the mailbox keeps the revived monitor paused.
+func TestRevivedMonitorHonorsStopAlreadyInMailbox(t *testing.T) {
+	pkg := t.TempDir()
+	os.WriteFile(filepath.Join(pkg, "INFO"), []byte("package=\"TestApp\"\n"), 0600)
+	control := filepath.Join(pkg, "control")
+	os.WriteFile(control, []byte("stop\n"), 0600)
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if got := newRevivedLifecycleMonitor("TestApp", pkg, control, func(string) {}).watch(ctx, time.Millisecond); got != "stop" || ctx.Err() != nil {
+		t.Fatal("revived monitor ignored stop", got, ctx.Err())
+	}
+}

package/templates/_executor/write_review_linux_test.go

@@ -11,15 +11,6 @@ import (
 	"time"
 )
 
-func TestReviewCopyChild(t *testing.T) {
-	if os.Getenv("P2_REVIEW_COPY_CHILD") != "1" {
-		t.Skip("child only")
-	}
-	if err := runWriteChild(os.Getenv("P2_REVIEW_CLEANUP_CHILD") == "1"); err != nil {
-		os.Exit(2)
-	}
-	os.Exit(0)
-}
 func TestReviewCanceledWriteDoesNotLeavePartialDestination(t *testing.T) {
 	if os.Geteuid() != 0 {
 		t.Skip("requires disposable local Linux root runner")
@@ -39,7 +30,7 @@ func TestReviewCanceledWriteDoesNotLeavePartialDestination(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if err = src.Truncate(1 << 40); err != nil {
+	if err = src.Truncate(8 << 30); err != nil {
 		src.Close()
 		t.Skip(err)
 	}
@@ -49,7 +40,7 @@ func TestReviewCanceledWriteDoesNotLeavePartialDestination(t *testing.T) {
 		t.Fatal(err)
 	}
 	launcher := filepath.Join(base, "child")
-	body := "#!/bin/sh\nexport P2_REVIEW_COPY_CHILD=1\n[ \"$1\" != cleanup-child ] || export P2_REVIEW_CLEANUP_CHILD=1\nexec " + strconv.Quote(binary) + " -test.run=^TestReviewCopyChild$\n"
+	body := "#!/bin/sh\nexport W3_MOVE_CHILD=\"$1\"\nexec " + strconv.Quote(binary) + " -test.run=^TestMoveChild$ 2>" + strconv.Quote(filepath.Join(base, "error")) + "\n"
 	os.WriteFile(launcher, []byte(body), 0700)
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
@@ -74,7 +65,8 @@ func TestReviewCanceledWriteDoesNotLeavePartialDestination(t *testing.T) {
 		}
 		select {
 		case err := <-done:
-			t.Fatalf("child ended before write: %v", err)
+			b, _ := os.ReadFile(filepath.Join(base, "error"))
+			t.Fatalf("child ended before write: %v %s", err, b)
 		case <-deadline:
 			t.Fatal("write did not start")
 		default:

package/templates/_shared/AGENTS.md

@@ -15,3 +15,132 @@ From the project root, run `synopkgland check --json`,
 `synopkgland build --json`, then `synopkgland inspect <spk> --json` on the emitted SPK.
 For Vue, first run `npm ci`, `npm test` and `npm run build` in frontend.
 Do not connect to or change a NAS without explicit task authorization.
+
+## Who may use the app (`entry`)
+
+Omit `entry` to keep legacy access. `entry: admin-only` admits DSM administrators
+only. `entry: app-privilege` also admits accounts that Control Panel >
+Application Privileges allows for `SYNO.SDS.<package>.Instance`; DSM's install
+default allows administrators only, so nobody else enters until an admin grants
+access. One CGI check covers every route; failures refuse; changes apply within
+30 seconds. Never re-implement AppPriv rules in the App.
+Mark routes ordinary users call `authenticated` in permissions.json, keep whole
+admin routes at the default, guard global settings inside shared routes with
+`api.RequireAdmin(caller)`, and hide admin controls with `ctx.user?.isAdmin`
+(UI only, never the authority). Example: users read the greeting; only admins
+call `greeting.set`.
+
+## DSM Application Portal (`portal`)
+
+`synopkgland add portal` (or `portal: {}` / `portal: {alias: my-app}` in
+dsm-package.yaml; Compose: `integration.web.portal` for a DSM-window app behind
+the auth gateway) registers `https://<nas>/<alias>/`, which opens the app after
+DSM sign-in. Read `synopkgland skill show portal` before changing it.
+The install wizard only proposes the alias; an administrator activates it from
+the app's portal panel (`ctx.portal`, DSM's own `SYNO.Core.AppPortal` in the
+admin's session) or Control Panel > Login Portal > Applications. Ordinary users
+get the link from the backend's read-only `portal.status`, else "ask an
+administrator". Never write `AppPortal.json` or `@appconf/<package>`, never add
+a backend route that sets the alias, and never relay QuickConnect responses or
+build QuickConnect links. A portal needs os_min_ver 7.3.2-86009 or later (DSM
+7.1.1 refuses it with error 320; 7.2 is untested) and `add portal` raises it;
+beyond that, support is detected (SYNO.API.Info), not version-gated.
+
+## 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, 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/templates/binary/dsm-package.yaml

@@ -6,7 +6,27 @@ build: 1
 displayname: __DISPLAY_NAME__
 description: A DSM package with a prebuilt binary CGI and DSM window UI.
 maintainer: Your Name
+# Optional INFO/website metadata. Omit fields you do not need.
+# metadata:
+#   contact_email: you@example.com
+#   support_email: support@example.com
+#   homepage: https://example.com
+#   source_url: https://github.com/you/your-app
+#   issues_url: https://github.com/you/your-app/issues
+#   license: MIT
+#   long_description:
+#     en: |-
+#       Explain what the app does and how to use it.
+#     zh-TW: Translated description.
+#   changelog:          # text, or per-language like long_description
+#     en: |-
+#       - Most important change first. Omit to use Release notes.
+#     zh-TW: |-
+#       - Translated changes.
+#   screenshots: [https://example.com/screenshot.png]
 os_min_ver: "7.1-42661"
+# One SPK per architecture. For armv7, add it here and a static 32-bit ARM file
+# under files (e.g. CGO_ENABLED=0 GOARCH=arm GOARM=7 go build).
 arches: [x86_64, aarch64]
 backend:
   kind: binary
@@ -14,6 +34,10 @@ backend:
     x86_64: prebuilt/api-x86_64
     aarch64: prebuilt/api-aarch64
 ui: {dir: ui}
+# UI languages: i18n/messages/<locale>.json for en, zh-TW, zh-CN, ja, ko, de,
+# fr, es and it (DSM's other languages fall back to English); ctx.t(key) reads them.
+i18n:
+  messages: i18n/messages
 # init compiles example/main.go for convenience. Replace prebuilt/api-* with
 # your application's static Linux ELF files; the CGI owns authentication.
 # daemon may optionally declare a separately packaged foreground service.

package/templates/binary/i18n/messages/de.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Ihr vorab kompiliertes CGI ist in dieser DSM-Anwendung enthalten.",
+  "app.title": "Binary App"
+}

package/templates/binary/i18n/messages/en.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Your prebuilt CGI is packaged in this DSM application.",
+  "app.title": "Binary App"
+}

package/templates/binary/i18n/messages/es.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Su CGI precompilado está empaquetado en esta aplicación de DSM.",
+  "app.title": "Binary App"
+}

package/templates/binary/i18n/messages/fr.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Votre CGI précompilé est intégré à cette application DSM.",
+  "app.title": "Binary App"
+}

package/templates/binary/i18n/messages/it.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Il CGI precompilato è incluso in questa applicazione DSM.",
+  "app.title": "Binary App"
+}

package/templates/binary/i18n/messages/ja.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "事前にビルドした CGI がこの DSM アプリケーションにパッケージ化されています。",
+  "app.title": "Binary App"
+}

package/templates/binary/i18n/messages/ko.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "미리 빌드한 CGI가 이 DSM 응용 프로그램에 패키징되어 있습니다.",
+  "app.title": "Binary App"
+}

package/templates/binary/i18n/messages/zh-CN.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "预先构建的 CGI 已打包在此 DSM 应用程序中。",
+  "app.title": "Binary App"
+}

package/templates/binary/i18n/messages/zh-TW.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "預先建置的 CGI 已封裝在這個 DSM 應用程式中。",
+  "app.title": "Binary App"
+}

package/templates/binary/ui/app.js

@@ -2,16 +2,31 @@
   "use strict";
   window.DsmPackageApps = window.DsmPackageApps || {};
   window.DsmPackageApps["__PACKAGE__"] = {
-    mount(root) {
+    // ctx.t(key) returns text from i18n/messages/<locale>.json in DSM's language.
+    // ctx.portal exists only with `portal:` in dsm-package.yaml; its panel
+    // shows the DSM Application Portal link, or the alias form to administrators.
+    mount(root, ctx) {
       const app = document.createElement("main");
       app.className = "binary-app";
       const title = document.createElement("h1");
-      title.textContent = "Binary App";
+      title.textContent = ctx.t("app.title");
       const description = document.createElement("p");
-      description.textContent = "Your prebuilt CGI is packaged in this DSM application.";
+      description.textContent = ctx.t("app.description");
       app.append(title, description);
+      let portalPanel = null;
+      if (ctx.portal) {
+        const portal = document.createElement("section");
+        portal.setAttribute("class", "dsmapp-portal");
+        app.append(portal);
+        portalPanel = ctx.portal.mountPanel(portal);
+      }
       root.append(app);
-      return { unmount() { app.remove(); } };
+      return {
+        unmount() {
+          if (portalPanel) portalPanel.dispose();
+          app.remove();
+        },
+      };
     },
   };
 })();

package/templates/native-authorization/AuthorizationGate.vue

@@ -22,9 +22,9 @@ const canAuthorize=computed(()=>required.value&&!untrusted.value)
 const unavailableKey=computed(()=>shown.value?.reason==='credential_not_ready'?'credential':'unavailable')
 const title=computed(()=>!shown.value?text.value('checking'):required.value?text.value('title'):shown.value.state==='ready'?text.value('ready'):shown.value.state==='not_admin'?text.value('not_admin.title'):shown.value.state==='session_expired'?text.value('session_expired.title'):text.value(unavailableKey.value+'.title'))
 const body=computed(()=>required.value?text.value('purpose'):shown.value?.state==='not_admin'?text.value('not_admin.body'):shown.value?.state==='session_expired'?text.value('session_expired.body'):shown.value?.state==='unavailable'?text.value(unavailableKey.value+'.body'):text.value('purpose'))
-const reasons=['grant_missing','helper_untrusted','cli_untrusted','grant_incompatible','package_identity_changed','maintenance_task_missing','maintenance_task_mismatch','helper_health_rejected','capability_missing']
+const reasons=['grant_missing','upgrade_reapproval','helper_untrusted','cli_untrusted','grant_incompatible','package_identity_changed','maintenance_task_missing','maintenance_task_mismatch','helper_health_rejected','capability_missing']
 const reason=computed(()=>reasons.includes(shown.value?.reason||'')?shown.value!.reason!:'unknown')
-const next=computed(()=>untrusted.value?'next.reinstall':reason.value==='grant_missing'?'next.install':reason.value==='grant_incompatible'?'next.update':'next.repair')
+const next=computed(()=>untrusted.value?'next.reinstall':reason.value==='grant_missing'?'next.install':reason.value==='upgrade_reapproval'||reason.value==='grant_incompatible'?'next.update':'next.repair')
 async function action(method:'status'|'request'|'revoke'){
  if(busy.value||disposed)return
  const current=++sequence
@@ -37,6 +37,8 @@ async function action(method:'status'|'request'|'revoke'){
   const result=await props.ctx.authorization?.[method]()
   if(disposed||current!==sequence)return
   if(!result||result.command!=='authorization'||result.schema_version!==1||!['ready','authorization_required','not_admin','session_expired','unavailable'].includes(result.state))throw Error('invalid status')
+  // A reason-only upgrade tombstone never accompanies a usable authorization.
+  if(result.reason==='upgrade_reapproval'&&result.state!=='authorization_required')throw Error('invalid status')
   state.value=result
   if(result.state==='ready')emit('ready')
  } catch(e){if(!disposed&&current===sequence){
@@ -54,7 +56,7 @@ onUnmounted(()=>{disposed=true;sequence++;if(typeof unsubscribe==='function')uns
    <span class="authorization-icon" aria-hidden="true"><component :is="shown?.state==='unavailable'||shown?.state==='session_expired'?TriangleAlert:ShieldCheck" class="authorization-icon-glyph" /></span>
    <h1 class="authorization-title">{{ title }}</h1>
    <p class="authorization-body">{{ body }}</p>
-   <Callout v-if="required" class="authorization-status" :tone="reason==='grant_missing'?'info':'warning'" :title="text('reason.'+reason)">{{ text(next) }}</Callout>
+   <Callout v-if="required" class="authorization-status" :tone="['grant_missing','upgrade_reapproval'].includes(reason)?'info':'warning'" :title="text('reason.'+reason)">{{ text(next) }}</Callout>
    <Callout v-if="failure" class="authorization-failed" tone="warning">{{ text('failed') }}</Callout>
    <div class="authorization-actions">
     <Button v-if="canAuthorize" variant="primary" :loading="busy" :disabled="busy" @click="action('request')">{{ busy ? text('authorizing') : text('authorize') }}</Button>

package/templates/native-authorization/i18n/de.json

@@ -2,6 +2,7 @@
   "authorization.title": "{package} benötigt Ihre Erlaubnis",
   "authorization.purpose": "Dieses Paket benötigt eine Genehmigung für feste Root-Operationen. DSM verarbeitet Ihr Passwort; das Paket sieht oder speichert es nicht.",
   "authorization.reason.grant_missing": "Root-Operationen sind noch nicht autorisiert.",
+  "authorization.reason.upgrade_reapproval": "Das Paket wurde im Paket-Zentrum aktualisiert, daher wurde die bisherige Autorisierung widerrufen.",
   "authorization.reason.helper_untrusted": "Dem privilegierten Helfer konnte nicht vertraut werden.",
   "authorization.reason.cli_untrusted": "Dem privilegierten Befehl konnte nicht vertraut werden.",
   "authorization.reason.grant_incompatible": "Der privilegierte Helfer muss aktualisiert werden.",