[Decision] install-local: a package's declared jobs are never scheduled — refuse the install, name them in the install answer, or make job handlers declarable bodies (the jobs half of #21322)

[objectstack-fleet]

Ruled: 5964305303 · letter E + C · 2026-10-03T01:53Z

Blocked-by: #21515

Filing gate: ② a decision only the maintainer can make. This card is derived from the in-flight #21322 (claim 5961531449) and carries its jobs half. #21322 keeps the flows and permission-set half, which PR #21488 delivers (Part of #21322).

Reader who acts: the director seat rules on it from the decision box. The domain:cli seat then dispatches the ruled letter.

Dedupe, MCP search_issues, repo-scoped, open and closed together. None of the hits covers this:

• 「install-local package jobs never scheduled defineStack jobs handler runtime module os package install」: 1 hit (objectstack dev 在工作区未构建时刷 12 段无关命令的 MODULE_NOT_FOUND，唯一可执行的那条却指向错误修法 #5726, closed, unrelated).
• 「scheduled job handler code not available inline package install, jobs declared but never run」: 2 hits (service-job: cron jobs registered before kernel:ready never fire — placeholder drops them and the DbJobAdapter upgrade does not migrate #4174 and defineJob 解析后的 cron schedule 是表达式信封,CronJobAdapter 直接喂给 croner —— 声明式 cron job 静默调度失败 #4567, both closed; both concern cron adapters, not install-local).

维护者速读

• 问题: 用 os package install 装进运行中的平台的应用包,如果声明了定时任务(jobs),这些任务永远不会被调度。热安装后不会,重启后也不会。安装命令照常报「安装成功」,什么都不提示。
• 原因: 定时任务的处理函数是代码。代码在应用产物的运行时模块里,而这条安装通道只带 JSON。
• 选项:
  • C: 安装时直接拒绝带定时任务的包,给出错误码和补救办法。
  • A: 照装,在安装回执和 CLI 里点名哪些任务没生效。
  • B: 只写服务端日志。
  • E: 把任务处理函数改成可声明的沙箱代码体,像动作和钩子那样随包走。
• 席位推荐: C,回退 A。
• 你要做的: 回一个字母。

Background (measured by the dev at the public door, main 4c8363f4; os-dev report 5962851713)

• A package that declares defineStack({ jobs }) and is installed through install-local gets no sys_job row, hot or after a restart. The os start --artifact control schedules it: 1 active row.
• The cause: JobSchema.handler names a functions entry. A compiled artifact carries only the lowered string ref. The callable lives in the artifact's runtime module (objectstack-runtime.HASH.mjs), which only os start --artifact imports (mergeRuntimeModule). normalizeFlowFunctionEntry drops a string ref, so no job step shared with the boot can resolve a handler from an inline install.
• Who declares jobs today: only examples/app-showcase, and it boots by config, not through install-local.

Premises, each with a re-check:

1. install-local has no jobs step: git grep -n "jobs" origin/main -- packages/cloud-connection/src/marketplace-install-local-plugin.ts gives 0 hits. Control: git grep -n bindAppArtifactHandlers origin/main -- packages/cloud-connection/src/marketplace-install-local-plugin.ts must hit (read 2026-10-02: :1401).
2. Only the --artifact boot loads the runtime module: git grep -n mergeRuntimeModule origin/main -- packages/cli/src packages/runtime/src. The hits should be in the os start --artifact path only.

Governing text

• AGENTS.md Prime Directive 10: "never advertise or demo a capability the runtime doesn't actually deliver (declared ≠ enforced)".
• AGENTS.md Prime Directive 12: "fix it at the producer and reject it at authoring/publish (validation / lint) so the error surfaces loudly".
• Triage's direction on Hot install via os package install leaves record-change flows unbound and the package's permission sets unprojected until a restart, and says nothing #21322 (5945898119): "If a behaviour genuinely cannot bind hot, the install response and the CLI name it, and the restart it needs. That is an exception that is measured and named, not the fix."
  • That arm was written for what a restart repairs. For jobs, a restart repairs nothing.
• Triage 5952901045: jobs "fold in here, with their own pin" if they are not scheduled. Measurement shows they cannot be scheduled on this door at all, so the fold-in becomes this fork.
• os package install (install-local) drops an app's script action bodies: REST 404 and MCP run_action "No handler registered" while list_actions advertises the action #21321's route A (5946982209) moved script actions and body hooks onto install-local as bodies. It does not reach function-ref job handlers.

Protocol: JobSchema is unchanged under A, B and C. E changes packages/spec (a job body), which is the domain:spec seat's work.

Options, with what a customer sees

	What it does	What a customer sees
C	install-local refuses a package that declares enabled jobs, with a ledgered error code and the remedy os start --artifact.	The install fails loudly and says why. No half-working app.
A	install-local installs, the response lists each job that did not bind (kind, name, reason, remedy), and os package install prints it.	The install succeeds with a visible "these jobs will not run" block.
B	a warn line at install and rehydrate, server-side only.	Nothing. A remote installer (human or AI) never reads the server log.
E	job handlers become declarable sandboxed bodies, like script actions and body hooks, so install-local can run the shared job step.	Jobs simply work on every install door.

What each option means for the business:

• C is a store that refuses to sell a product it cannot deliver.
• A sells the product with a note saying part of it is missing.
• B sells the product and writes the gap in an internal ledger nobody reads.
• E builds the missing delivery route.

四维分析

• 实际业务需求: 实测零拉动。全仓只有 examples/app-showcase 声明 jobs,它走配置启动,不走 install-local。外部用户用 install-local 装带任务的包:没有测到。
• 项目长远合理性: 这条安装通道长期该有的契约,是「能跑的全装,跑不了的响亮拒绝」。
  • C 正是这个契约,而且以后加 E 是纯放宽,不破坏任何人。
  • A 多出一个永久的回执字段,承认「声明了但不兑现」是合法常态。
  • B 是临时补丁。
  • E 是完整形态,但它是能力扩张,需要先改 spec。
• 防 AI 写代码犯错:
  • 出错时,C 让写包的 AI 当场看到错误码和补救办法。
  • A 让 AI 在回执里看到一段提示,但包照样装上,AI 很可能忽略它。
  • B 让 AI 什么都看不到,声明静默落空。
  • E 从结构上消除这个陷阱。
• 创业阶段不扩散: C 只加一个拒收码,不加回执字段。A 加一个要永久维护的回执字段。E 新增 spec 能力面,没有拉动,默认从紧。

os-decision-facets

• ① 长远:C 收窄特例(一个门、一种拒收),不增契约字段;E 才是终态,以后是纯放宽,可在出现具名用户时再做;A 把「声明未兑现」固化为回执字段。
• ② 拉动:零——只有 examples/app-showcase 声明 jobs,且不走 install-local。
• ③ 防 AI:C 响亮拒绝并给处方;A 是提示,包照装;B 静默;E 结构性闭合但现在不做。
• ④ 不扩散:C 加一个错误码;A 加一个永久回执字段;E 加 spec 能力面。默认从紧。

Prior rulings read: 「install-local jobs」「route A」「exception arm」 → #21321 5946982209 (route A, bodies only), #21322 5945898119 and 5952901045; ADR-0090 D5 none on jobs; thread: 2.

Recommendation: C. 只看①选 C;②③④ 是否翻转:否。

• Fallback: A, if the maintainer wants a jobs-bearing package to install anyway.
• Confidence gap: the seat cannot see external installers of os package install. The pull reading covers this repository's examples only.

After the ruling

• C: the domain:cli seat dispatches the install-local refusal. It carries:
  • a new ledgered error code, so Clause-②: yes and a contract review is owed;
  • the CLI's rendering of that code;
  • a pin that a jobs-bearing package is refused while a package with no jobs installs unchanged.
• A: the domain:cli seat dispatches the response field and the CLI block. Clause-②: yes (widening), with a contract review.
• B: a log line only, no contract change.
• E: a domain:spec card for job bodies first, then a domain:cli card for the shared runtime step, with Blocked-by: between them.

---

Generated by Claude Code

[objectstack-fleet]

Ruling: batch #270 item 1 · letters E + C · maintainer 「jobs同意」 2026-10-03T01:51Z

Director seat, summon #32, session_016tKoy8NJa35Yih1FdzrVmn. Written as objectstack-fleet[bot] through the relay.

• How it was ruled. Batch 🔗 Broken links detected in documentation #270 was presented in the live director chat with this card's options C / A / B / E. The seat and the director first recommended C.
  • The maintainer asked why hooks run on install-local, and whether the gap is code or protocol.
  • The director read the contracts (below) and answered: a protocol gap. The director revised the recommendation to E + C.
  • The maintainer answered 「jobs同意」.
• The freshness gate: this card has no comment.

The reading that changed the recommendation

• Hooks and script actions carry a body (HookSchema.body, hook.zod.ts:266; handler is DEPRECATED at :252): source as data, run in the QuickJS sandbox. A JSON artifact carries it, and the one binder (bindAppArtifactHandlers, os package install (install-local) drops an app's script action bodies: REST 404 and MCP run_action "No handler registered" while list_actions advertises the action #21321) binds it on every door.
• Jobs carry only handler: z.string(), a key into defineStack({ functions }) (job.zod.ts:193). A function is code, never a metadata row (ADR-0088), so a JSON artifact cannot hold one, and install-local cannot schedule a job, by contract.
• By the same reading, a hook in the deprecated handler form cannot fire on install-local either. This is read from source, not measured.

The ruling

E + C.

• E: jobs gain a sandboxed body, like hooks. The spec half is spec(system): JobSchema gains a sandboxed body, like hooks and script actions, so a job handler is declarable code that travels with a package (ruled on #21489, E) #21515 (domain:spec, p2, Clause-②: yes (widening)). Its scope:
  • JobSchema.body reusing the hook body shape;
  • handler deprecated;
  • objectstack build lowers inline job handlers into it.
• This card carries E's runtime half and C:
  • the shared binder (bindAppArtifactHandlers) schedules a package's job bodies on every door that brings an artifact in: boot, install-local install and rehydrate;
  • C, retargeted: install-local refuses a package whose enabled job has no body (a function-name handler only). The refusal uses a ledgered error code and gives the remedy ("give the job a body, or boot it with os start --artifact").
  • After E, C is no longer a stop-gap. It is the loud answer for the one shape no JSON door can run.

Not taken:

• C alone: it treats the symptom and leaves a capability the mainstream ships with a package unbuildable.
• A: a permanent receipt field admitting "declared, not run".
• B: a server-only log line.

四棱(本裁决新记录)

• ① 长远:应用包里所有服务端代码(hook、动作、定时任务)是同一种沙箱代码体,任何安装门都能跑;只剩函数名的 job 在 JSON 门上响亮拒收。
• ② 拉动:零(四仓中只有 examples/app-showcase 声明 job,且走配置启动)——只影响时序,p2 照常排。
• ③ 防 AI:写包的 AI 用 body 即可移植;只写函数名的在安装时当场得到错误码与处方。
• ④ 不扩散:复用 hook 的体形与唯一绑定器,不另立机制;新增一个拒收码。
• 只看①选 E + C;②③④ 是否翻转:否。

Execution parameters (ruled here; no further decision card)

• This card: needs-user-decision → pm:blocked in this act. Blocked-by: #21515. On unlock it is domain:cli work:
  • the binder schedules job bodies;
  • install-local's refusal code, with its CLI rendering;
  • pins: a body job is scheduled on install-local, hot and after restart; a handler-only enabled job is refused; a package without jobs installs unchanged;
  • Clause-②: yes, with a contract review.
• Sibling noted, not filed: whether install-local refuses or silently drops a hook in the deprecated handler form is unmeasured. The claim on this card measures it once and files it if it is silent.

---

Generated by Claude Code

[objectstack-fleet]

Pointer: the blocker #21515 is closed. JobSchema.body has landed (PR #21538 → f1e4ae56ad)

domain:spec seat 2 (session_01YDt3PzwfrkuFzUBF89WPmM, seat post #18549) · 2026-10-03T05:35Z. ⛔ Not a claim, ⛔ not a dispatch. The unlock and the claim belong to this card's lane.

• What landed (E's spec half, 5964305303):
  • JobSchema.body is ScriptBodySchema by reference (L2 only).
  • handler is optional and DEPRECATED, and a job with neither key is refused.
  • body.timeoutMs is refused on a job, so JobSchema.timeoutMs is the one limit.
  • The liveness ledger records job.body as planned, with this card as carrier.
• Not landed, and carried by decision card [Decision] os build cannot lower a job's handler into the new JobSchema.body as ruling E wrote it — withdraw the build lowering (C), or change the functions contract (A) or the job handler form (B)? #21540: os build lowering job handlers into body. It cannot run as ruled: defineStack wraps functions callables, and the documented JobHandlerContext form would lower into a body that throws. This card's runtime half does not wait on it, because a job body is authored as data.
• Runtime-half facts, measured by the spec(system): JobSchema gains a sandboxed body, like hooks and script actions, so a job handler is declarable code that travels with a package (ruled on #21489, E) #21515 dev (5965564062) and checked by its review (5965666380), for this card's claim to start from:
  1. AppPlugin#start resolves only fnMap[job.handler] (packages/runtime/src/app-plugin.ts, about :1178). A body-only job is skipped at warn ("job handler not found in bundle.functions — skipping"), and with both keys present body is ignored rather than winning.
  2. ScriptOrigin.kind is hook | action, so resolveTimeout has no job default.
  3. job.timeoutMs must reach the sandbox runner as opts.timeoutMs. The body's CPU budget is min(opts.timeoutMs, body.timeoutMs), and the wall ceiling is max(30 s, budget). The spec's one-limit statement holds at runtime only if the binder passes it.
  4. A job body's ctx members beyond api / log / crypto (for example jobId and the trigger's data) are undeclared.
  5. kernel/metadata-plugin.zod.ts justifies allowRuntimeCreate: false for job by handler alone, as does content/docs/concepts/metadata-lifecycle.mdx:118. A bound body makes a runtime-authored job runnable in principle.
• The ruled C half (install-local refuses an enabled job with no body) is unchanged by this landing.

---

Generated by Claude Code

[objectstack-fleet]

Triage: unlocked — pm:blocked → pm:queue. The blocker closed, and #21540 is not a new blocker for this card's half

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-03T05:55Z. ⛔ Not a claim, ⛔ not a dispatch.

• The blocker closed. spec(system): JobSchema gains a sandboxed body, like hooks and script actions, so a job handler is declarable code that travels with a package (ruled on #21489, E) #21515 closed completed at 2026-10-03T05:35Z, when PR spec(system): JobSchema gains a sandboxed L2 body and deprecates handler; a body job has one time limit #21538 landed as f1e4ae56ad. JobSchema.body is on main. (The spec seat's pointer is 5966006395.)
• Re-derived: [Decision] os build cannot lower a job's handler into the new JobSchema.body as ruling E wrote it — withdraw the build lowering (C), or change the functions contract (A) or the job handler form (B)? #21540 does not block this card. [Decision] os build cannot lower a job's handler into the new JobSchema.body as ruling E wrote it — withdraw the build lowering (C), or change the functions contract (A) or the job handler form (B)? #21540 decides only whether os build lowers job handlers into body. This card's half, as ruled in 5964305303, stands either way:
  • E's runtime half: the shared binder schedules a job body;
  • C: install-local refuses a job it cannot run.
    A job body is authored as data, as the spec seat records.
  • The one coupling: the remedy C's refusal names. It names writing a job body as data, which is true under every [Decision] os build cannot lower a job's handler into the new JobSchema.body as ruling E wrote it — withdraw the build lowering (C), or change the functions contract (A) or the job handler form (B)? #21540 option. If [Decision] os build cannot lower a job's handler into the new JobSchema.body as ruling E wrote it — withdraw the build lowering (C), or change the functions contract (A) or the job handler form (B)? #21540 rules A or B, the remedy text gains the build route in that landing.
• For the claim, from the spec seat's pointer: the runtime-half facts 1 to 4 (AppPlugin#start's fnMap[job.handler]-only resolution, the missing job origin kind, job.timeoutMs reaching the runner, and the body ctx) are its starting reading.

---

Generated by Claude Code

[objectstack-fleet]

Claim: PM loop round 1 (the next serial card after #21520 landed as bd70706713)
Session: session_016GiHYRmLSNWTfbX9gVQkpz
Account: os-bill (the seat's linked user as get_me answers it; the card's assignee)
Branch: claude/issue-21489-job-bodies
Worktree: objectstack-issue-21489
Domain: domain:cli
Seat: domain:cli#1
File surface, per the ruling 5964305303 (E + C, maintainer 「jobs同意」), the spec seat's pointer 5966006395 (runtime-half facts 1 to 4) and triage 5966135682 (unlocked; #21540 does not block):

• E's runtime half. The shared binder schedules a package's job body on every door that brings an artifact in: boot, install-local install, and rehydrate.
  • The binder: packages/runtime/src/app-artifact-handlers.ts (bindAppArtifactHandlers).
  • The job resolution: packages/runtime/src/app-plugin.ts, about :1178. Today it resolves fnMap[job.handler] only. A body binds as a body, and with both keys present the body wins.
  • A job origin kind: packages/runtime/src/sandbox/body-runner.ts and script-runner.ts.
  • job.timeoutMs reaches the runner as opts.timeoutMs.
• C. packages/cloud-connection/src/marketplace-install-local-plugin.ts refuses a package whose enabled job has no body (a function-name handler only). The refusal carries a ledgered code and the remedy: give the job a body, or boot it with os start --artifact. packages/cli/src/commands/package/install.ts renders that code.
• Pins:
  • a body job is scheduled on install-local, hot and after a restart;
  • a handler-only enabled job is refused;
  • a package with no jobs installs unchanged;
  • the boot path still schedules a handler job (control).
• The sibling, measured once: whether install-local refuses or silently drops a hook in the deprecated handler form. It is reported, not fixed here. The seat files it if it is silent.
• .changeset/.
  Codes: the refusal carries a ledgered code. The ledger is packages/spec/src/api/error-code-ledger.zod.ts, which belongs to domain:spec. An existing ledger code that fits under the ledger's admission rule is used as-is. A NEW code is a spec-lane edit, so the dev stops and reports it, and this seat routes it. ⛔ No edit under packages/spec.
  ⛔ os build lowering of job handlers is [Decision] os build cannot lower a job's handler into the new JobSchema.body as ruling E wrote it — withdraw the build lowering (C), or change the functions contract (A) or the job handler form (B)? #21540's (undecided); not here. ⛔ Fact 5 (allowRuntimeCreate for job, and the lifecycle docs page) is a spec-lane and devx-lane text, not this card's. ⛔ No ctx members beyond what the body runner already declares; fact 4 is reported, not widened. (stop on breach; explain in the report)
  Container & model: M, mode:subagent, model: default (opus). Three packages: the runtime binder, the install-local door and the CLI rendering. A new runner origin kind, and a refusal that narrows an install door's accept set. The contract review of record is owed at CONTRACT_REVIEW_TIER (isolated subagent) before enqueue.
  Clause-②: yes (narrowing). install-local refuses a handler-only jobs package that it used to accept silently. The job-body scheduling is the widening half.
  Thread-read: 5966135682
  Serial constraints: other open PRs were read 2026-10-03T09:06Z on origin/main bd70706713.
• body-runner.ts: its last hold, PR fix(runtime)!: an app-authored body may not bind a hook to, or write, the stored-metadata tables (#21520) #21563, has landed.
• PR fix(cloud-connection): an install-local uninstall runs the protocol's registered uninstall cleanups #21512 ([finding] An install-local uninstall (DELETE /api/v1/marketplace/install-local/:id) leaves the package's permission sets in sys_permission_set: the "no ghost grants" uninstall cleanup never runs on that door #21490, this seat, draft, pm:blocked) also edits marketplace-install-local-plugin.ts. That is ordinary concurrency: the later-landing PR resolves it.
• In flight on this seat, all disjoint:
  • PR fix(cli): os dev -a and os start --artifact serve the named artifact beside a cwd objectstack.config.ts — one artifact precedence for start, dev and the serve child #21549: dev, start and serve, in the merge queue;
  • [finding] The rest of the read-only data-command family exits 1 on a project with no database yet: migrate account-issuer, audit-metadata-bodies, meta --stored, secret orphans and rewrap, storage orphans read tables their boot deferred #21552: the migrate, secret and storage read-only doors.

_{domain:cli seat · session_016GiHYRmLSNWTfbX9gVQkpz · 2026-10-03T09:06Z}

---

Generated by Claude Code