= {
eligible_endpoints: { label: "灵活池可用执行器", description: "每行一个已授权执行器,仅用于 flexible;必须包含首选执行器。" },
executor_model: { label: "模型", description: "所选执行器使用的模型,可留空;留空表示沿用执行器自身的默认模型。" },
executor_reasoning_effort: { label: "推理档位", description: "所选执行器使用的推理档位,可留空;留空表示沿用执行器自身的默认档位。" },
+ user_space: { label: "记忆用户空间", description: "本机管家在 OpenViking 中隔离使用的 user space 标识。" },
+ auto_recall: { label: "跨会话自动召回", description: "收到非命令的实质私聊消息时,执行一次有界历史事件检索。" },
+ recall_timeout_seconds: { label: "召回超时(秒)", description: "等待记忆读取的上限(1–15 秒);超时后跳过记忆直接恢复正常回复。" },
count_unit: { label: "复核计数依据", description: "有效工作 Turn 须完成结算;轮询和重复重试不计数。", options: { completed_todos: "已完成 Todo", effective_turns: "已结算工作 Turn" } },
planning_horizon_goal: { label: "在规划视野中显示 Goal", description: "默认开启,选择工作前可见原目标与验收要求。可为回滚或对照实验关闭;不改变复盘、步幅策略或执行权限。" },
yardstick_enabled: { label: "复核衡量标准", description: "默认关闭。使用已有 Explore 证据复核测量范围与反馈;需有可用的 Explore 证据,不会自动启用它或授予执行权限。" },
@@ -280,6 +294,11 @@ export function localizedCapabilityFieldCopy(locale: WorkspaceLocale, capability
label: "Exploration mode", description: "Planning includes the evidence graph; worker and execution permissions remain separate.",
options: {off: "Off", evidence: "Evidence only", planning: "Evidence and planning"},
}};
+ if (capabilityId === "steward_memory") return {...fieldCopy[locale], enabled: locale === "zh-CN" ? {
+ label: "启用", description: "为本人私聊管家开启独立 OpenViking 长期记忆。",
+ } : {
+ label: "Enabled", description: "Enable isolated OpenViking long-term memory for owner private steward conversations.",
+ }};
return fieldCopy[locale];
}
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/context-drawer.tsx b/apps/presentation/dashboard/src/features/personal-workspace/context-drawer.tsx
index 1ee6ce52e3..e4364606f6 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/context-drawer.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/context-drawer.tsx
@@ -1231,7 +1231,9 @@ export function ContextDrawer({ agents, attentionHistory = [], onSelectAttention
{selection.item.title}
{selection.item.todoId && (selection.item.actionKind === "gate.resolve" || selection.item.actionKind === "todo.update")
? : null}
- {selection.item.impact ? {selection.item.impact}
: null}
+ {selection.item.reviewPlan?.retryOriginal && selection.item.errorMessage
+ ? {selection.item.errorMessage}
+ : selection.item.impact ? {selection.item.impact}
: null}
{selection.item.reviewPlan && !selection.item.reviewPlan.creationExecution && !selection.item.reviewPlan.retryOriginal && !taskExecution && selection.item.actionKind !== "team.plan" && !(decisionFrame && ["ready", "applied"].includes(selection.item.status)) ? {operationUnknown
? t("actionReview.operation_reconcile_original")
: selection.item.reviewPlan.operationFrame?.kind === "inactive"
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/goal-activity.ts b/apps/presentation/dashboard/src/features/personal-workspace/goal-activity.ts
index ea1b2eabe5..3f922c18db 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/goal-activity.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/goal-activity.ts
@@ -156,7 +156,7 @@ export function goalHostSurfaces(goal: Pick) {
const observation = goal.hostThreadActivity;
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/goal-research-analysis.tsx b/apps/presentation/dashboard/src/features/personal-workspace/goal-research-analysis.tsx
index 072a88d214..60c4689388 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/goal-research-analysis.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/goal-research-analysis.tsx
@@ -314,7 +314,7 @@ export function useResearchAnalysis(goalId: string, active: boolean, zh: boolean
requestAnimationFrame(() => {if (closedAt === citeGeneration.current) origin?.focus();});
};
return {readOnly: currentSnapshot?.execution_enabled === false || (Boolean(readSourceUrl) && currentSnapshot?.execution_enabled !== true), sourceScope, readUsageComparison, citation, citationBusy, citationError, sourcePanel, readCitation, readUsageTurn, retryCitation, closeCitation, onCitationLocationChange, goalId, zh, location, snapshot: currentSnapshot, pack: readingPack, requestPack: pack, savedOriginal, readError, error, loading, pending, cancelPending, recordedRunning, panel, trigger, read, show, execute, cancel,
- studyNavigation, close: () => {invalidateCitation(); navigate(false); requestAnimationFrame(() => trigger.current?.focus());}, select: (id: string) => navigate(location.open, id, true)};
+ studyNavigation, close: () => {invalidateCitation(); navigate(false); requestAnimationFrame(() => trigger.current?.focus());}, select: (id: string | null) => navigate(location.open, id, true)};
}
type Controller = ReturnType;
@@ -385,14 +385,18 @@ function AnalysisContinuation({pack: p, analysis: a}: {pack: Pack; analysis: Con
;
}
-function AnalysisReadState({analysis: a}: {analysis: Controller}) {
+function AnalysisReadState({analysis: a, onBrowseStudies}: {analysis: Controller; onBrowseStudies?: () => void}) {
const error = a.readError || a.snapshot?.originalReadError;
if (error) return
{a.snapshot?.originalReadError && !a.readError ?
{a.zh ? "已保存原文暂不可读,当前语言的分析状态仍保留。" : "The saved original could not be read. The current language’s analysis state is preserved."} :
-
{a.pack ? (a.zh ? "刷新失败,保留上次结果。" : "Refresh failed. Showing the last result.")
+ {onBrowseStudies ? (a.zh ? "无法读取链接指定的解读。" : "The linked study version could not be read.")
+ : a.pack ? (a.zh ? "刷新失败,保留上次结果。" : "Refresh failed. Showing the last result.")
: (a.zh ? "暂时无法读取分析。" : "Analysis could not be read.")} }
void a.read().catch(() => undefined)}>
{a.loading ? (a.zh ? "正在重试…" : "Retrying…") : (a.zh ? "重试" : "Retry")}
+ {onBrowseStudies ?
+ {a.zh ? "查看已保存的解读" : "Browse saved studies"}
+ : null}
{error}
;
if (!a.pack && a.loading && (!a.snapshot || a.snapshot.catalog.packs.length > 0)) return
@@ -419,24 +423,38 @@ export function ResearchReportSummary({analysis: a}: {analysis: Controller}) {
}
export function ResearchCaseReading({analysis: a, active}: {analysis: Controller; active: boolean}) {
+ const reader = useRef
(null);
+ const focusAfterBrowse = useRef(false);
const packs = (a.snapshot?.catalog.packs ?? []).filter(p => p.case_study_summary);
const p = a.pack;
const firstStudy = packs[0]?.pack_id;
useEffect(() => {
- const hash = window.location.hash;
- if (!a.loading && !a.readError && p && !p.case_study && firstStudy
- && !(hash.startsWith(caseChapterHashPrefix) && hash.includes("~"))) a.select(firstStudy);
- }, [a.loading, a.readError, p?.pack_id, Boolean(p?.case_study), firstStudy]);
- return
+ if (!a.loading && !a.readError && a.location.packId === null && p && !p.case_study && firstStudy
+ && !window.location.hash.startsWith(caseChapterHashPrefix)) a.select(firstStudy);
+ }, [a.loading, a.readError, a.location.packId, p?.pack_id, Boolean(p?.case_study), firstStudy]);
+ useLayoutEffect(() => {
+ if (!focusAfterBrowse.current || a.loading || (!p?.case_study && !a.readError)) return;
+ focusAfterBrowse.current = false;
+ if (document.activeElement === document.body) {
+ reader.current?.querySelector("select, h2, .analysis-read-error button")?.focus({preventScroll: true});
+ }
+ }, [a.loading, a.readError, Boolean(p?.case_study)]);
+ const browseStudies = a.readError && !p && a.location.packId !== null ? () => {
+ focusAfterBrowse.current = true;
+ a.select(null);
+ } : undefined;
+ return
{packs.length > 1 || (packs.length === 1 && !p?.case_study) ? {a.zh ? "解读版本" : "Study version"}
a.select(e.target.value)}>
{!p?.case_study ? {a.zh ? "选择已保存的解读" : "Choose a saved study"} : null}
{packs.map(pack => {pack.title} )}
: null}
-
+
{p?.case_study ? : !a.loading && !a.readError ? {a.zh ? "选择一份解读,阅读问题背景、策略差异、关键转折与证据。" : "Choose a study to read its background, approaches, turning points and evidence."}
: null}
+ onCitationLocationChange={a.onCitationLocationChange}/> : !a.loading && !a.readError && p ?
+ {a.zh ? "此版本没有已保存的案例解读。" : "This version has no saved case study."}
+
: null}
;
}
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/goal-research-history.tsx b/apps/presentation/dashboard/src/features/personal-workspace/goal-research-history.tsx
index 3b2ff20e73..7bb83d289b 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/goal-research-history.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/goal-research-history.tsx
@@ -68,10 +68,11 @@ export function GoalResearchHistory({goalId, originalGoalId = goalId, preferHist
const requestedCase = caseMode.goalId === goalId ? caseMode.requested : null;
const caseReading = requestedCase ?? !preferHistory;
const hasCases = (analysis.snapshot?.catalog.packs ?? []).some(pack => pack.case_study_summary);
- // Preserve the saved reading during catalogue loading or failure. A
- // successful catalogue without a study falls back to the original history.
+ // A link to a particular version stays in the case reader even when that
+ // version has no study. An unpinned visit can fall back to ordinary history.
const awaitingRequestedCase = requestedCase === true && (analysis.loading || Boolean(analysis.readError));
- const deferHistory = requestedCase === true && (hasCases || awaitingRequestedCase);
+ const caseViewAvailable = hasCases || awaitingRequestedCase || (requestedCase === true && analysis.location.packId !== null);
+ const deferHistory = requestedCase === true && caseViewAvailable;
const historySource = JSON.stringify([goalId, originalGoalId, readSourceUrl]);
const [openedHistorySource, setOpenedHistorySource] = useState(null);
const readHistory = active && (!deferHistory || openedHistorySource === historySource);
@@ -530,13 +531,13 @@ export function GoalResearchHistory({goalId, originalGoalId = goalId, preferHist
: null;
const emptyHistoryMessage = zh ? "这个 Goal 尚无研究历程" : "No research history for this Goal yet";
const selectedStrategy = hasNativeSource && !emptySourceHistory ? strategies.selection : null;
- const readingCase = caseReading && (hasCases || awaitingRequestedCase) && (requestedCase === true || selectedStrategy === null);
+ const readingCase = caseReading && caseViewAvailable && (requestedCase === true || selectedStrategy === null);
const alternateReading = readingCase ?
: selectedStrategy !== null ? strategies.choose(null)}/> : null;
return <>
- {hasCases || awaitingRequestedCase ?
+ {caseViewAvailable ?
{
if (readingCase) {analysis.closeCitation(); setCaseMode(false);}
}}>{zh ? "研究历程" : "Research history"}
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/goal-storage-settings.tsx b/apps/presentation/dashboard/src/features/personal-workspace/goal-storage-settings.tsx
index e056f50eaf..1d59971ac7 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/goal-storage-settings.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/goal-storage-settings.tsx
@@ -4,7 +4,7 @@ import {discardGoalStorage, fetchGoalStorage, previewGoalStorage, recoverGoalSto
import {useWorkspaceI18n} from "./i18n";
/** Restore opaque intent from the owning server across native origin changes.
- * Neither that carrier nor cached source facts replace current source checks. */
+ * */
export function GoalStorageSettings({goalId, onChanged}: {goalId: string; onChanged: () => void}) {
const {t} = useWorkspaceI18n();
const key = `loopx-storage-preview:${goalId}`;
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/machine-configuration-settings.tsx b/apps/presentation/dashboard/src/features/personal-workspace/machine-configuration-settings.tsx
index 20730ae91d..0d8c7d1042 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/machine-configuration-settings.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/machine-configuration-settings.tsx
@@ -135,8 +135,8 @@ export function MachineConfigurationSettings({ section, onChanged }: {
(inspection?.capability_catalog.capabilities ?? []).filter((capability) =>
capability.available_scopes.includes("machine")
&& (section === "conversation" ? capability.capability_id === "codex_chat" : section === "steward"
- ? capability.capability_id === "steward_executor" || capability.capability_id === "manager_runtime"
- : capability.capability_id !== "steward_executor" && capability.capability_id !== "manager_runtime" && capability.capability_id !== "codex_chat")),
+ ? capability.capability_id === "steward_executor" || capability.capability_id === "manager_runtime" || capability.capability_id === "steward_memory"
+ : capability.capability_id !== "steward_executor" && capability.capability_id !== "manager_runtime" && capability.capability_id !== "steward_memory" && capability.capability_id !== "codex_chat")),
locale,
), [inspection, locale, section]);
const invalidNamespace = inspection?.invalid_namespaces[0];
@@ -526,6 +526,15 @@ export function MachineConfigurationSettings({ section, onChanged }: {
) : null}
+ {selected.capability_id === "steward_memory" ? (
+
+
+ {locale === "zh-CN" ? "仅限本人私聊与独立身份" : "Owner private chats only"} {locale === "zh-CN"
+ ? "连接信息读取自本机管家私有文件,不在此表单收集;记忆按已验证发言人隔离保存,超时不阻塞正常回复,也不会进入群聊或转交给工作 Agent。"
+ : "Connection settings stay in the private local steward file outside this form. Memory stays isolated per verified speaker, fails open on timeout, and never enters group chats or worker handoffs."}
+
+ ) : null}
+
{selected.capability_id === "pull_request_review" ? (
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-contract.test.mjs b/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-contract.test.mjs
index 0fdc7b1162..cf2ed749d0 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-contract.test.mjs
+++ b/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-contract.test.mjs
@@ -502,11 +502,12 @@ for (const capabilityId of [
"pull_request_review",
"reward_memory",
"steward_executor",
+ "steward_memory",
]) {
const matches = capabilityLocalization.match(new RegExp(`${capabilityId}:`, "g")) ?? [];
assert.equal(matches.length, 2, `${capabilityId} has English and Simplified Chinese metadata`);
}
-for (const fieldKey of ["agent_orders", "allowed_domains", "coordinator_agent_id", "eligible_endpoints", "enabled", "executor_endpoint", "executor_model", "executor_reasoning_effort", "max_children", "profile", "profile_preset", "review_order", "route_ref", "safe_fix", "selection_policy", "strict_receipt", "timezone"]) {
+for (const fieldKey of ["agent_orders", "allowed_domains", "auto_recall", "coordinator_agent_id", "eligible_endpoints", "enabled", "executor_endpoint", "executor_model", "executor_reasoning_effort", "max_children", "profile", "profile_preset", "recall_timeout_seconds", "review_order", "route_ref", "safe_fix", "selection_policy", "strict_receipt", "timezone", "user_space"]) {
const matches = capabilityLocalization.match(new RegExp(`^\\s+${fieldKey}:`, "gm")) ?? [];
assert.equal(matches.length, 2, `${fieldKey} has English and Simplified Chinese field copy`);
}
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx b/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx
index 94e96ece80..66f5c99f70 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx
@@ -1832,10 +1832,21 @@ export function PersonalWorkspacePage({
// not have a Turn to revisit.
.filter(proposal => proposal.actionKind !== "todo.create" || proposal.status !== "applied"
|| Boolean(proposal.reviewPlan?.taskExecution));
- const restored = Object.fromEntries(restoreable.map((proposal) => [proposal.previewId, proposal]));
const previousIds = restoredProposalIdsRef.current;
- restoredProposalIdsRef.current = new Set(Object.keys(restored));
- setProposals((current) => ({...Object.fromEntries(Object.entries(current).filter(([id]) => !previousIds.has(id))), ...restored}));
+ restoredProposalIdsRef.current = new Set(restoreable.map(proposal => proposal.previewId));
+ setProposals((current) => {
+ const next = Object.fromEntries(Object.entries(current).filter(([id]) => !previousIds.has(id)));
+ for (const proposal of restoreable) {
+ const previous = current[proposal.previewId];
+ // The stored confirmation outlives a failed dispatch attempt.
+ // Keep the local reason until readback observes a different confirmation.
+ const retryError = proposal.reviewPlan?.retryOriginal && previous?.reviewPlan?.retryOriginal
+ && previous.actionKind === proposal.actionKind && previous.goalId === proposal.goalId
+ && previous.updatedAt === proposal.updatedAt ? previous.errorMessage : undefined;
+ next[proposal.previewId] = retryError ? { ...proposal, errorMessage: retryError } : proposal;
+ }
+ return next;
+ });
// The manager conversation shows the cards this channel offered: a team
// plan the steward proposed from here is confirmed here, instead of the
// owner hunting for the Goal whose workspace happens to hold the card.
@@ -2140,7 +2151,7 @@ export function PersonalWorkspacePage({
: null;
const lifecycleChange = options.lifecycleProjection ?? inferredLifecycleChange;
setActionFeedback(t("feedback.applying", { title: proposal.title }));
- const applying = { ...proposal, reviewPlan: proposal.reviewPlan ? { ...proposal.reviewPlan, interaction: "pending" as const, reason: "apply_pending" as const, canApply: false as const } : undefined, status: "applying" as const };
+ const applying = { ...proposal, errorMessage: undefined, reviewPlan: proposal.reviewPlan ? { ...proposal.reviewPlan, interaction: "pending" as const, reason: "apply_pending" as const, canApply: false as const } : undefined, status: "applying" as const };
setProposals((current) => ({ ...current, [proposal.previewId]: applying }));
if (showDrawer) setSelection({ item: applying, kind: "proposal" });
let applyingSelection = selectionRevision.current;
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-case-study.tsx b/apps/presentation/dashboard/src/features/personal-workspace/research-case-study.tsx
index 4487639894..35ab8f6e18 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-case-study.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-case-study.tsx
@@ -62,11 +62,15 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
onCitationLocationChange: (hash: string) => void;
}) {
const article = useRef(null);
+ const currentStudy = useRef(study);
+ currentStudy.current = study;
const openCitation = useRef(onCitation);
openCitation.current = onCitation;
- const [missingCitation, setMissingCitation] = useState(false);
+ const [missingAnchor, setMissingAnchor] = useState("");
const {url, goalId, packId, namespace, follow} = navigation;
const prefix = `${caseChapterHashPrefix.slice(1)}${namespace ? namespace + '-' : ''}${packId}-`;
+ // A reread can replace the study object while the saved version and address
+ // stay the same. Only navigation should run chapter and citation restoration.
useEffect(() => {
if (!active) return;
let frame = 0;
@@ -85,23 +89,27 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
// into a source identifier or range for the evidence API.
const match = scoped ? /^([a-zA-Z0-9_-]*)~([1-9][0-9]?)$/.exec(hash.slice(prefix.length + 1)) : null;
const section = match?.[1];
- const citations = section ? study.sections.find(item => item.id === section)?.citations : study.citations;
+ const savedStudy = currentStudy.current;
+ const citations = section ? savedStudy.sections.find(item => item.id === section)?.citations : savedStudy.citations;
const citation = match ? citations?.[Number(match[2]) - 1] : undefined;
const origin = document.getElementById(hash.slice(1));
if (!citation || !origin || !article.current?.contains(origin)) {
- setMissingCitation(true);
+ setMissingAnchor(hash);
return;
}
- setMissingCitation(false);
+ setMissingAnchor("");
const disclosure = origin.closest('details');
if (disclosure) disclosure.open = true;
openCitation.current(citation, origin, {hash, chapterHash: section ? `#${prefix}${section}` : ""});
return;
}
- setMissingCitation(false);
- if (!scoped) return;
- const chapter = document.getElementById(hash.slice(1));
- if (chapter && article.current?.contains(chapter) && chapter.getClientRects().length) focusChapter(chapter);
+ const chapter = scoped ? document.getElementById(hash.slice(1)) : null;
+ if (chapter && article.current?.contains(chapter) && chapter.getClientRects().length) {
+ setMissingAnchor("");
+ focusChapter(chapter);
+ } else {
+ setMissingAnchor(hash.startsWith(caseChapterHashPrefix) ? hash : "");
+ }
});
};
restore();
@@ -112,7 +120,7 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
window.removeEventListener('popstate', restore);
window.removeEventListener('hashchange', restore);
};
- }, [active, goalId, packId, prefix, study, onCitationLocationChange]);
+ }, [active, goalId, packId, prefix, onCitationLocationChange]);
const citationLinks = (citations: AssessmentCitation[], section = "") =>
{citations.map((c, i) => {
const id = `${prefix}${section}~${i + 1}`;
@@ -121,7 +129,7 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
return {
if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return;
e.preventDefault();
- setMissingCitation(false);
+ setMissingAnchor("");
follow(href, true);
onCitation(c, e.currentTarget, {hash: href.hash, chapterHash: section ? `#${prefix}${section}` : ""});
}}>
@@ -132,11 +140,13 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
return
{scope.case_id}
- {study.title}
+ {study.title}
{historical ? {zh ? '来源已变化或暂不可读。下文保留注册时的解读与证据快照,不能视作当前结果。' : 'The source changed or is unavailable. This reading and its evidence snapshot describe the registered version, not current results.'}
: null}
{study.language !== (zh ? 'zh' : 'en') ? {zh ? '显示已保存的英文原文。' : 'Showing the saved Chinese original.'}
: null}
- {missingCitation ? {zh ? '这条链接在所选解读中找不到原文。可从下方的依据入口选择。' : 'This link does not identify an original in the selected study. Choose a source below.'}
: null}
+ {missingAnchor ? {missingAnchor.includes('~')
+ ? (zh ? '这条链接在所选解读中找不到原文。可从下方的依据入口选择。' : 'This link does not identify an original in the selected study. Choose a source below.')
+ : (zh ? '这条链接在所选解读中找不到章节。可从目录选择。' : 'This link does not identify a chapter in the selected study. Choose a chapter from the contents.')}
: null}
{zh ? '结论依据与范围' : 'Conclusion evidence and scope'}
{citationLinks(study.citations)}
{zh ? '已保存的作者分析;来源绑定不代表结论已独立验证。' : 'Saved author analysis; source binding does not independently verify the conclusions.'}
@@ -152,7 +162,7 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return;
e.preventDefault();
onCitationLocationChange(href.hash);
- setMissingCitation(false);
+ setMissingAnchor("");
follow(href);
const chapter = document.getElementById(id);
if (chapter && article.current?.contains(chapter)) focusChapter(chapter);
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-record-export.ts b/apps/presentation/dashboard/src/features/personal-workspace/research-record-export.ts
index fff0532b21..40bac0ce58 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-record-export.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-record-export.ts
@@ -1,7 +1,7 @@
import type {ExploreHistoryEvent} from "../../../../../../loopx/control_plane/presentation/explore_history.ts";
import {searchResearchRecords, type ResearchRecordDisplay} from "./research-record-search.ts";
-/** A portable reading snapshot, not an import format or an acceptance receipt.
+/** A portable reading snapshot.
* Export canonical records, never translated/analysed display replacements.
* Source endpoints are deliberately absent: opening a file needs no connection.
*/
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-record-search.ts b/apps/presentation/dashboard/src/features/personal-workspace/research-record-search.ts
index ce3a92682c..80c9ebb718 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-record-search.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-record-search.ts
@@ -2,7 +2,7 @@ import type {ExploreHistoryEvent, ExploreHistoryNode} from "../../../../../../lo
import type {ExploreFindingSections} from "../../../../../../loopx/control_plane/presentation/explore_timeline.ts";
/** The history reader supplies its already qualified, current-language projection.
- * This search neither validates a translation nor borrows another snapshot. */
+ * */
export type ResearchRecordDisplay = {
events?: ReadonlyMap;
sections?: ReadonlyMap;
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-record-versions.ts b/apps/presentation/dashboard/src/features/personal-workspace/research-record-versions.ts
index c6aebc18aa..02369d3bd0 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-record-versions.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-record-versions.ts
@@ -8,7 +8,7 @@ export function researchRecordVersions(events: readonly ExploreHistoryEvent[], s
&& event.event_kind === selected.event_kind && event.result_id === selected.result_id);
}
-// Local display fields, not a new evidence or lifecycle vocabulary.
+// Local display fields.
export const researchComparisonFields = ["title", "summary", "status", "blocked_reason", "evidence_refs",
"measurements", "confidence", "run_id", "agent_id", "node_kind", "node_id", "parent_id",
"from_node", "to_node", "edge_type", "supersedes", "execution_observation"] as const;
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-usage-selection.ts b/apps/presentation/dashboard/src/features/personal-workspace/research-usage-selection.ts
index f500e4223f..08130e66a3 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-usage-selection.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-usage-selection.ts
@@ -1,6 +1,6 @@
import type {TrajectorySolverUsage} from "../../../../../../loopx/control_plane/capabilities/trajectory_assessment_types.js";
-/** Presentation arithmetic over one already-qualified capture, not a ledger. */
+/** Presentation arithmetic over one already-qualified capture. */
export function researchUsageRows(usage: TrajectorySolverUsage) {
const complete = usage.turns.map(turn => ({...turn, incomplete: false}));
const partial = [...(usage.interrupted_turns ?? [])];
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/todo-completion-feedback.ts b/apps/presentation/dashboard/src/features/personal-workspace/todo-completion-feedback.ts
index 5e7315bcda..1db714206a 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/todo-completion-feedback.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/todo-completion-feedback.ts
@@ -21,7 +21,7 @@ export function parseTodoCompletionProof(text: string): {
} catch { return null; }
}
-/** Present the terminal owner's refusal; neither inspect nor acquire a lease. */
+/** Present the terminal owner's refusal; */
export function todoCompletionProofRequired(error: unknown): boolean {
return error instanceof ChatApiError && (error.payload.error_code === "handoff_mode_requires_lease"
|| error.payload.error_code === "lease_fence_required");
diff --git a/apps/presentation/site/public/blog/context-delivery/example.py b/apps/presentation/site/public/blog/context-delivery/example.py
index f8bb013320..d1d3db9137 100644
--- a/apps/presentation/site/public/blog/context-delivery/example.py
+++ b/apps/presentation/site/public/blog/context-delivery/example.py
@@ -9,7 +9,6 @@
import json
import os
from pathlib import Path
-import shlex
import subprocess
import sys
diff --git a/apps/presentation/site/src/time-machine/records.ts b/apps/presentation/site/src/time-machine/records.ts
index cbfb8a6f19..fa2282dfa0 100644
--- a/apps/presentation/site/src/time-machine/records.ts
+++ b/apps/presentation/site/src/time-machine/records.ts
@@ -1,4 +1,4 @@
-/** Verbatim public capture reader, not an Explore state reducer or validator.
+/** Verbatim public capture reader.
* Explore owns v0 semantics. Pinned bytes prevent a different capture or edited
* record from silently acquiring these editorial scenes. Status stays source text.
*/
diff --git a/apps/workbench/AGENTS.md b/apps/workbench/AGENTS.md
index 561574e40d..9384f67502 100644
--- a/apps/workbench/AGENTS.md
+++ b/apps/workbench/AGENTS.md
@@ -1,7 +1,7 @@
# AGENTS.md
在远程主机上跑 coding agent,用手机或电脑浏览器操作。
-要做的事看 `docs/TODO.md`,架构看 `docs/PLAN.md`,设计图在 `docs/design/`。
+安装和连接 LoopX Core 见 `docs/install-agent.md`。
## 开始前
@@ -9,7 +9,7 @@
## 三条原则
-1. **简单,不干扰 agent。** 不改 agent 的目录、配置和会话。不做 IDE:没有补全、调试、多面板那一套。终端例外,是给人的运维工具(见 `TODO.md` 第 10 节),不碰 agent 的会话。文件默认只读:能浏览这台机器的目录(线程目录、项目目录、家目录,见第 11 节),回复里明确引用的单个文件也照旧能开。需要人写字的地方可以有纯文本编辑,像写字一样干净好看,不像代码编辑器;现在只有写作模式的正文(见 `docs/writing-design.md`)。
+1. **简单,不干扰 agent。** 不改 agent 的目录、配置和会话。不做 IDE:没有补全、调试、多面板那一套。终端例外,是给人的运维工具,不碰 agent 的会话。文件默认只读:能浏览线程目录、项目目录和家目录,回复里明确引用的单个文件也照旧能开。需要人写字的地方可以有纯文本编辑,像写字一样干净好看,不像代码编辑器;现在只有写作模式的正文。
2. **界面要好看。** 标准是 Codex,目标是超过它。丑就是 bug。
3. **先参考再动手。** 新功能和改交互前,先看两三个同类开源项目怎么解这个问题(如 Codex、Claude Code、Chatwoot、LibreChat、Open WebUI),对比分析、择优借鉴,再开始写;参考结论一句话写进回复,让取舍有据可查。
diff --git a/apps/workbench/README.md b/apps/workbench/README.md
index 3542288a30..31800d00f0 100644
--- a/apps/workbench/README.md
+++ b/apps/workbench/README.md
@@ -19,35 +19,13 @@ LooChat 是一个开源的 agent 工作台。用简单的界面管理 TRAE、zco
LooChat 不动 agent 本身的目录、配置和会话,装好即用。LooChat 是自创品牌名,呼应随时叫上 AI 伙伴的感觉;图标采用一只举着大小双钳的蓝色小螃蟹,配浅蓝背景,保持简单、亲切的形象。
-## 界面预览
-
-| 桌面 · 亮色 | 桌面 · 深色 |
-|---|---|
-|  |  |
-
-| 手机 · 亮色 | 手机 · 深色 |
-|---|---|
-|  |  |
+## 使用方式
实时语音:开启后输入框换成一个会随声音起伏的球,你说的话以浅蓝气泡记进线程;后台任务和待批准事项一行可见;结束后逐句对话折成一行,下面留一份文字总结。
-
-
-
-
用量与诊断:多 agent 的 token 用量、TPM 走势和费用估算。
-
-
-写作模式:在加号菜单里一点就开。你口述观点,agent 用你的原话记成初稿、标出【待补】、追问具体场景,再按二稿、三稿、配图、润色一稿一稿往下走。正文是 `writing/` 下的 Markdown,按文章排版,画出 Mermaid 图、显示配图;读和写是同一张纸,可以直接改(键盘或语音输入法都行),agent 同时改过时不会覆盖你的版本。在正文里选中一句,一点「删」「待补」「为什么」「改成…」就成了给 agent 的注释。说「复盘」,agent 把你反复改的地方提炼成写作习惯,记进 `~/.loochat/notes/writing.md` 等你确认,之后每篇都照着写。设计见 [写作流程设计](docs/writing-design.md)。
-
-
-
-
-
-
-
-> 状态:可用,正在迭代。产品方向见 [愿景与设计思路](docs/VISION.md),现有架构见 [PLAN](docs/PLAN.md),进度见 [TODO](docs/TODO.md),扩展方案见 [扩展设计](docs/extensions-design.md)。
+写作模式:在加号菜单里一点就开。你口述观点,agent 用你的原话记成初稿、标出【待补】、追问具体场景,再按二稿、三稿、配图、润色一稿一稿往下走。正文是 `writing/` 下的 Markdown,按文章排版,画出 Mermaid 图、显示配图;读和写是同一张纸,可以直接改(键盘或语音输入法都行),agent 同时改过时不会覆盖你的版本。在正文里选中一句,一点「删」「待补」「为什么」「改成…」就成了给 agent 的注释。说「复盘」,agent 把你反复改的地方提炼成写作习惯,记进 `~/.loochat/notes/writing.md` 等你确认,之后每篇都照着写。
## 已支持
@@ -61,7 +39,7 @@ LooChat 不动 agent 本身的目录、配置和会话,装好即用。LooChat
| zcode | `zcode app-server` 精简接入 | 有 | 按原生模型能力 | 暂无 |
| DeepSeek Harness | `dsh --profile acp`(ACP) | 有(仅允许一次/拒绝) | 有(按当前模型路由) | 暂无 |
-各家 agent CLI 需要先在主机上装好并完成登录或鉴权。没装的 agent 在界面里显示为不可用;各家的能力和接入边界见 [架构说明](docs/PLAN.md)。
+各家 agent CLI 需要先在主机上装好并完成登录或鉴权。没装的 agent 在界面里显示为不可用。
## 插件与参与
@@ -69,10 +47,10 @@ LooChat 不动 agent 本身的目录、配置和会话,装好即用。LooChat
- **线程看板**:按进行中、等你、待验收、已完成排列线程;agent 每轮结束报告进度,完成由你勾选。
- **Memory 记忆看板**:只读浏览 Codex 已有的记忆文档,不生成或同步记忆。
-- **实时语音**(试验中,真人听说仍在验收):用这台机器上已登录的 Codex 原生语音,不需要另配 API Key;会消耗现有额度,具体计费归属尚未核实。在任意支持协作的线程里都能开,任务可以交给当前线程的 agent(Claude Code、pi 等)去做。浏览器开麦需要 HTTPS 或 localhost,见 [语音设计](docs/voice-design.md)。
+- **实时语音**(试验中,真人听说仍在验收):用这台机器上已登录的 Codex 原生语音,不需要另配 API Key;会消耗现有额度,具体计费归属尚未核实。在任意支持协作的线程里都能开,任务可以交给当前线程的 agent(Claude Code、pi 等)去做。浏览器开麦需要 HTTPS 或 localhost。
- **LoopX**:需先安装并配置 LoopX,关联目标和线程后,在会话与看板中查看目标、待办和待决定事项。当前不提供自动推进。
-skills 和 MCP 属于 agent 资源,通过各自的管理页操作,与 LooChat 插件分开。想接入工具、贡献一个工作视图,或者反馈使用中的问题,可以从 [参与和插件指南](docs/contributing-extensions.md) 开始。独立数据源可放在自己的仓库;当前还没有自动收录的插件市场。
+skills 和 MCP 属于 agent 资源,通过各自的管理页操作,与 LooChat 插件分开。想接入工具、贡献一个工作视图,或者反馈使用中的问题,可以在 LoopX 仓库提交 issue。独立数据源可放在自己的仓库;当前还没有自动收录的插件市场。
## 快速开始
@@ -99,8 +77,6 @@ curl -fsSL "https://raw.githubusercontent.com/loopx-project/loopx/$ref/apps/work
**Core 单独安装。** 上述稀疏检出不包含 Python Core,安装器不会启动或升级 Core。普通 agent 会话可独立使用;Goal 功能需要运行中的 Core,以及对应注册表的 LoopX CLI。安装器会检查 Core 的 `/healthz`,不可达时打印地址和配置提示。在生成的 `.env` 中配置 `LOOCHAT_LOOPX_CORE_URL`(默认 `http://127.0.0.1:8792`);源码 Core 还需设置 `LOOCHAT_LOOPX_CMD`、`LOOCHAT_LOOPX_CWD`,具体见 [安装与 Core 连接](docs/install-agent.md#连接-loopx-core)。
-以上 `main` 安装链接在本次变更合入 `main` 后生效;合入前请使用包含本安装器的提交 SHA。
-
**让 agent 帮你装**:把这句话发给这台机器上的 Claude Code、Codex 等:
```text
@@ -116,7 +92,7 @@ curl -fsSL "https://raw.githubusercontent.com/loopx-project/loopx/$ref/apps/work
```bash
cd apps/workbench # 从 LoopX 仓库根目录进入
npm install
-npm run setup # 生成仓库根目录的 .env 和随机 LOOCHAT_TOKEN,并打印出来
+npm run setup # 生成 apps/workbench 下的 .env 和随机 LOOCHAT_TOKEN,并打印出来
npm run build
LOOCHAT_ENV_FILE=../../.env npm start -w @loopx/loochat # 默认监听 127.0.0.1:8787
```
@@ -128,28 +104,7 @@ LOOCHAT_ENV_FILE=../../.env npm run dev:daemon # 后端
npm run dev:web # Vite,http://127.0.0.1:5173,/api 代理到后端
```
-daemon 在 `packages/daemon` 目录里运行,所以用 `LOOCHAT_ENV_FILE` 指向根目录的 `.env`。没有设置 `LOOCHAT_ENV_FILE` 时,读取的是当前目录下的 `.env`。
-
-## 产品官网与引导体验
-
-官网:[maxliux5.github.io/loochat](https://maxliux5.github.io/loochat/)。
-
-仓库包含独立的中文产品官网,展示「简单管理更多国内外 agent、按需安装插件、一起参与建设」的方向。官网展示自动交接、agent 协作、看板与记忆等可操作例子:体验账号接力、取消倒计时或原会话换模型,派发任务、查看成员与返回结果,勾选看板验收,以及搜索记忆、阅读原文;同时保留任务、审批和方案体验,介绍可安装的 LoopX 工作数据源,并提供插件贡献与需求反馈入口。技能和 MCP 通过各自的资源页管理;BotMux 提醒与通用任务控制仍在规划,具体状态见 [扩展设计](docs/extensions-design.md)。
-
-```bash
-npm run dev:site # 开发官网,默认端口 5174
-npm run build:site # 输出 packages/site/dist
-npm run preview:site # 预览构建后的静态站点
-npm run test:site # 构建并运行官网浏览器测试
-```
-
-`packages/site/dist` 可以单独部署到静态托管服务,支持网站根目录和子目录。首页是 `index.html`,独立体验入口是 `demo/index.html`;托管服务需要支持目录首页。开发与本地预览默认只监听本机。
-
-GitHub Pages 通过 `.github/workflows/pages.yml` 发布:推送到 `main` 后,自动安装依赖、检查并构建官网,再上传 `packages/site/dist`;也可在 Actions 中手动运行「Deploy website」。首次启用需在仓库 Settings → Pages 选择 GitHub Actions 作为发布来源。Pages 仅托管官网和本地模拟体验,运行 agent 的 hub 仍部署在自己的主机上。
-
-体验区进入可视范围或点击场景后才加载,手机保留内嵌交互并提供「全屏体验」。官网使用自己的轻量图标和静态资源目录,不复制 hub 的应用清单。安装区包含启动后打开工作台、输入 token 及远程访问说明。
-
-引导体验仅在浏览器内回放预置事件,不需要 daemon,不读取已保存的 hub token,不发送 `/api/` 请求,也不运行真实 agent。回复、命令结果和文件改动都是示例;切换任务可浏览不同流程,重新体验会清空本轮演示。普通 hub 的入口、登录和原有只读示例保持不变。官网独立构建,不由 `scripts/restart.sh` 部署。
+daemon 在 `packages/daemon` 目录里运行,所以用 `LOOCHAT_ENV_FILE` 指向 `apps/workbench/.env`。没有设置 `LOOCHAT_ENV_FILE` 时,读取的是当前目录下的 `.env`。
## 远程访问
@@ -176,7 +131,7 @@ GitHub Pages 通过 `.github/workflows/pages.yml` 发布:推送到 `main` 后
私有 socket 由本机用户文件权限保护。hub token 能操作登记的节点;节点令牌只能领取自己的 relay 任务。移除机器会撤销令牌,不删除节点线程和文件。
-`scripts/update-hosts.sh [机器ID] [--check]` 可经 relay 更新在线节点。节点需要 systemd 用户服务与仓库克隆(默认优先使用 `install.sh` 的 `~/.local/share/loochat`,否则回退 `~/code/loochat`;hosts.json 的 `repo` 可设为仓库根或 `apps/workbench` 子目录)。更新任务独立于节点服务运行,构建快照、等待空闲后切换、失败回滚;hub 在重连后读取结果。`--check` 会 fetch 并快进克隆,但不构建或切换服务。真实 systemd 更新与跨网络部署仍待验收,机制和限制见 [多机管理设计](docs/multi-host-design.md)。
+`scripts/update-hosts.sh [机器ID] [--check]` 可经 relay 更新在线节点。节点需要 systemd 用户服务与仓库克隆(默认优先使用 `install.sh` 的 `~/.local/share/loochat`,否则回退 `~/code/loochat`;hosts.json 的 `repo` 可设为仓库根或 `apps/workbench` 子目录)。更新任务独立于节点服务运行,构建快照、等待空闲后切换、失败回滚;hub 在重连后读取结果。`--check` 会 fetch 并报告候选版本,保留当前检出、构建和服务。真实 systemd 更新与跨网络部署仍待验收。
## 开机自启
@@ -206,7 +161,7 @@ scripts/migrate-name.sh # 构建,等线程空闲后切换,服务
## 发布前检查
```bash
-npm run check:publish
+node scripts/check-publish.mjs
```
扫描会被发布的文件,查找你的用户名、主机名、家目录路径、内网 IP、长密钥、邮箱地址。公司名、项目名这类私人词放在仓库外的 `~/.config/loochat/publish-denylist`(每行一个),也会一起检查。
@@ -216,14 +171,13 @@ npm run check:publish
```
packages/daemon 网关:HTTP/SSE API、鉴权、SQLite 存储、各 agent 的适配器
packages/web 界面:React + Vite,手机与桌面共用一套组件
-docs/ 计划与界面说明
+docs/ 安装与 Core 连接指南
```
## 开发
```bash
scripts/init.sh # 装依赖、构建,起一个用假 agent 的临时 hub 并跑一轮冒烟测试;加 --check 跑完即停
-scripts/demo.sh # 起一个浏览器可打开的体验 hub:假 agent,绑定所有网卡,打印地址和 token;用 stop 子命令停止并清理
npm test # daemon 与 web 的全部单元测试和 API 测试
npm run typecheck
npm run test:e2e # 统一构建一次,再运行浏览器 E2E(最多并行 2 个测试文件)
diff --git a/apps/workbench/docs/install-agent.md b/apps/workbench/docs/install-agent.md
index 537e2e0fd6..22b1203b33 100644
--- a/apps/workbench/docs/install-agent.md
+++ b/apps/workbench/docs/install-agent.md
@@ -4,7 +4,7 @@
## 预览、安装与版本
-默认安装当前 `main`;要复现某个版本,将下面的 `main` 替换为完整提交 SHA 或 tag。脚本和源码使用同一个 ref。下面的 `main` 链接在本变更合入后才生效。
+默认安装当前 `main`;要复现某个版本,将下面的 `main` 替换为完整提交 SHA 或 tag。脚本和源码使用同一个 ref。先用 `--dry-run` 检查安装目录与版本。
```bash
ref=main
diff --git a/apps/workbench/install.sh b/apps/workbench/install.sh
index 3e957d1f48..24727425be 100755
--- a/apps/workbench/install.sh
+++ b/apps/workbench/install.sh
@@ -1,20 +1,4 @@
#!/usr/bin/env bash
-# Installs LooChat on this machine, or updates it when it is there already:
-#
-# curl -fsSL https://raw.githubusercontent.com/loopx-project/loopx/main/apps/workbench/install.sh | bash
-# curl -fsSL .../install.sh | bash -s -- --dry-run only print what it would do
-#
-# It clones the code to ~/.local/share/loochat, builds it, writes ~/.config/loochat/.env (a random
-# token; data under ~/.local/state/loochat; your home as the working directory), runs it as a
-# systemd user service and prints the address and token. Run again to update: the .env, the
-# token and the data stay. Agents (Claude Code, Codex, ...) are installed and signed in apart.
-#
-# --dry-run print the steps, change nothing
-# --no-service do not install the service; print how to start it by hand
-# --uninstall stop and remove the service and the code; the .env and the data stay
-#
-# LOOCHAT_REPO (git URL or path), LOOCHAT_REF (branch, tag or commit; default main) and
-# LOOCHAT_HOME (checkout directory) override the defaults. Core is installed separately.
set -euo pipefail
REPO_URL="${LOOCHAT_REPO:-https://github.com/loopx-project/loopx.git}"
@@ -25,13 +9,30 @@ ENV_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/loochat/.env"
DATA_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/loochat/data"
NAME=loochat
+usage() {
+ cat <<'USAGE'
+Install or update LooChat from the LoopX repository.
+
+Usage: bash install.sh [--dry-run] [--no-service] [--uninstall]
+ ... | bash -s -- [options]
+
+ --dry-run Print the steps without writing files or starting services.
+ --no-service Build the application and print the foreground start command.
+ --uninstall Remove the service and checkout, keeping configuration and data.
+ -h, --help Show this help.
+
+LOOCHAT_REPO, LOOCHAT_REF (default: main), and LOOCHAT_HOME override
+the source, revision and checkout directory. Install LoopX Core separately.
+USAGE
+}
+
DRY=0 SERVICE=1 UNINSTALL=0
for arg in "$@"; do
case "$arg" in
--dry-run) DRY=1 ;;
--no-service) SERVICE=0 ;;
--uninstall) UNINSTALL=1 ;;
- -h | --help) sed -n '2,17p' "$0" 2>/dev/null | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -h | --help) usage; exit 0 ;;
*) echo "Unknown option: $arg (see --help)" >&2; exit 2 ;;
esac
done
diff --git a/apps/workbench/packages/e2e/test/install.spec.mjs b/apps/workbench/packages/e2e/test/install.spec.mjs
index ea661c9679..016137ac42 100644
--- a/apps/workbench/packages/e2e/test/install.spec.mjs
+++ b/apps/workbench/packages/e2e/test/install.spec.mjs
@@ -123,6 +123,14 @@ test('setup preserves current and historical tokens without appending a second c
}
});
+test('help works when the installer is supplied on stdin', () => {
+ const installer = readFileSync(join(repo, 'install.sh'), 'utf8');
+ const result = spawnSync('bash', ['-s', '--', '--help'], { input: installer, encoding: 'utf8' });
+ assert.equal(result.status, 0, result.stderr);
+ assert.match(result.stdout, /--dry-run/);
+ assert.match(result.stdout, /--no-service/);
+});
+
test('a dry run changes nothing', (t) => {
const { run, read, home } = fixture(t);
const r = run('--dry-run');
diff --git a/apps/workbench/packages/web/src/demo/DemoApi.ts b/apps/workbench/packages/web/src/demo/DemoApi.ts
index 465e962710..86dc1d1b1b 100644
--- a/apps/workbench/packages/web/src/demo/DemoApi.ts
+++ b/apps/workbench/packages/web/src/demo/DemoApi.ts
@@ -1,7 +1,7 @@
import type { ExtensionManifest, ExtensionState, Permission } from '@calli/extension-api';
import { Api, ApiError, type FolderListing, type MachineUsageReport, type SearchHit, type TextFile, type Thread, type ThreadOutputs, type UsagePoint, type UsageTokens, type VideoRef } from '../api';
import { BUILTIN_MANIFESTS } from '../extensions/catalog';
-import { demoPicture, type DemoData } from './data';
+import type { DemoData } from './data';
import { t } from '../i18n';
/**
@@ -99,20 +99,23 @@ export class DemoApi extends Api {
return Promise.reject(new DemoError(true));
}
- override threadFile(_threadId: string, path: string): Promise {
+ override async threadFile(_threadId: string, path: string): Promise {
+ const { demoPicture } = await import('./data');
const picture = demoPicture(path);
- return picture ? Promise.resolve(new Blob([picture], { type: 'image/svg+xml' })) : Promise.reject(new DemoError(false));
+ if (!picture) throw new DemoError(false);
+ return new Blob([picture], { type: 'image/svg+xml' });
}
/** A page the demo wrote: a small stand-in with its name, served the way a signed link would be. */
- override previewLink(_threadId: string, path: string): Promise<{ url: string }> {
+ override async previewLink(_threadId: string, path: string): Promise<{ url: string }> {
+ const { demoPicture } = await import('./data');
const picture = demoPicture(path);
const name = path.split('/').pop() ?? path;
// The demo's stand-in page is written by an agent, not by the interface, so it stays in the
// demo's own words: a real hub serves the page the agent left in the thread's folder.
const page = picture ?? `${name} ${name} Example page: in a real hub this is the page the agent wrote into the thread's folder.
`;
const type = picture ? 'image/svg+xml' : 'text/html';
- return Promise.resolve({ url: `data:${type};charset=utf-8,${encodeURIComponent(page)}` });
+ return { url: `data:${type};charset=utf-8,${encodeURIComponent(page)}` };
}
override attachment(_threadId: string, _attachmentId: string): Promise {
diff --git a/apps/workbench/packages/web/test/demo.test.ts b/apps/workbench/packages/web/test/demo.test.ts
index 34e96fbf3a..023eb228d6 100644
--- a/apps/workbench/packages/web/test/demo.test.ts
+++ b/apps/workbench/packages/web/test/demo.test.ts
@@ -87,6 +87,16 @@ test('files and search work inside the demo threads', async () => {
assert.ok(hits.some((h) => h.threadId === 'demo-dark-mode'));
});
+test('demo files and previews resolve pictures with no prior workspace read', async () => {
+ const api = new DemoApi();
+ const picture = await api.threadFile('demo-dark-mode', 'preview-light.svg');
+ assert.equal(picture.type, 'image/svg+xml');
+ assert.match(await picture.text(), / {
const api = demoApi();
const day = await api.machineUsage(24);
diff --git a/apps/workbench/scripts/check-publish.mjs b/apps/workbench/scripts/check-publish.mjs
index 7ad2dcafd2..96cea8dfa2 100755
--- a/apps/workbench/scripts/check-publish.mjs
+++ b/apps/workbench/scripts/check-publish.mjs
@@ -2,7 +2,7 @@
// Looks for things that must not be published: your user name, host name and home directory,
// private IP addresses, long secrets, personal e-mail addresses, and words you list yourself.
//
-// npm run check:publish
+// node scripts/check-publish.mjs
//
// Words of your own (company or project names, for example) go in a file outside the repository,
// one per line: $LOOCHAT_PUBLISH_DENYLIST, or ~/.config/loochat/publish-denylist by default.
diff --git a/benchmark/deepswe-gptxhigh-v1/goal_codex.py b/benchmark/deepswe-gptxhigh-v1/goal_codex.py
index 2eaf0d99f8..b7ef14a187 100644
--- a/benchmark/deepswe-gptxhigh-v1/goal_codex.py
+++ b/benchmark/deepswe-gptxhigh-v1/goal_codex.py
@@ -228,7 +228,6 @@ async def exec_as_agent(self, environment, command: str = "", env=None, **kwargs
# option. Packed once per run rather than once per task would be nicer
# still, but the tar is ~13 MB and building it is far cheaper than the
# model turn that follows.
- runner_source = getattr(self, "_goal_runner_source", None)
with tempfile.TemporaryDirectory() as tmp:
tarball = Path(tmp) / "loopx.tar.gz"
subprocess.run(
diff --git a/benchmark/edgebench/online_sampling.py b/benchmark/edgebench/online_sampling.py
index a0c6b9afa2..a1fafe3480 100644
--- a/benchmark/edgebench/online_sampling.py
+++ b/benchmark/edgebench/online_sampling.py
@@ -12,7 +12,6 @@
import threading
import time
from enum import StrEnum
-from pathlib import Path
import requests
from sforge.harness.run_agent import _extract_archive_from_container
diff --git a/benchmark/frontiercs2-single-host-v1/local_runner.py b/benchmark/frontiercs2-single-host-v1/local_runner.py
index bf6ae9f831..6de153ec42 100644
--- a/benchmark/frontiercs2-single-host-v1/local_runner.py
+++ b/benchmark/frontiercs2-single-host-v1/local_runner.py
@@ -13,7 +13,6 @@
from pathlib import Path
import signal
import subprocess
-import sys
import tarfile
import time
diff --git a/benchmark/runtime/RUNTIME.md b/benchmark/runtime/RUNTIME.md
index bc44dd1f19..a5bbd696dd 100644
--- a/benchmark/runtime/RUNTIME.md
+++ b/benchmark/runtime/RUNTIME.md
@@ -389,13 +389,22 @@ For a task-entry comparison, pin the same source and vary only `task_entry`;
keep task inputs, scoring, model, budget and evaluation windows fixed. Include
planning time in the common run budget.
-New `loopx-planned` invocations deliver the product planning packet without the
-previous benchmark research-strategy prefix. Only explicitly selected execution
-observation tool context is added. This applies to both Harbor and SForge callers;
-task content, the Core first-delivery contract, identity/readback validation and
-host deadline enforcement remain unchanged. Pin the runner revision when comparing
-planning policies. This adapter change does not qualify model adoption, earlier
-evaluation or outcome improvement.
+New `loopx-planned` invocations deliver the product planning packet, optional
+initial batch authoring and explicitly selected execution observation tool
+context. This applies to both Harbor and SForge callers. Pin the runner revision
+when comparing planning policies. The batch changes how the planner submits its
+decisions. Model adoption, time to a scored candidate and outcome improvements
+require separate run evidence.
+
+For an empty planning frontier, the model can save the same requirement
+declaration and ordered advancement Todos in one JSON proposal and invoke
+`python -m benchmark.runtime.planning_batch PROPOSAL.json` during the planning
+wake. Use the checkpoint's exact input digest and acceptance provider revision.
+The command declares requirements, writes Todos and binds their actual IDs
+through public LoopX operations. Each write has its own receipt. If the command
+is interrupted, reuse the unchanged proposal so the original effects can be
+replayed and missing links completed. Use the ordinary planning steps for
+existing work, changes to requirements and blockers.
The model writes or reuses actual task Todos through the public CLI. The worker
reads the product packet again and checks the input digest, identity, Todo ids
diff --git a/benchmark/runtime/planning.py b/benchmark/runtime/planning.py
index 86082f6924..4351bdf942 100644
--- a/benchmark/runtime/planning.py
+++ b/benchmark/runtime/planning.py
@@ -25,8 +25,14 @@ def render_planning_prompt(packet: dict, env: dict[str, str]) -> str:
raise ValueError(f"{key} must be finite and positive")
from .research_probe import runtime_execution_guidance
+ batch = ""
+ if env.get("LOOPX_TASK_STAGE") == "plan":
+ from .planning_batch import planning_batch_guidance
+
+ batch = planning_batch_guidance()
return ("$loopx\n\n"
+ runtime_execution_guidance(env)
+ + batch
+ "Host-supplied planning checkpoint:\n" + json.dumps(packet, ensure_ascii=False))
diff --git a/benchmark/runtime/planning_batch.py b/benchmark/runtime/planning_batch.py
new file mode 100644
index 0000000000..7b4a2fb200
--- /dev/null
+++ b/benchmark/runtime/planning_batch.py
@@ -0,0 +1,205 @@
+"""Apply one initial planning proposal through the existing LoopX owners."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import shlex
+import subprocess
+import sys
+import tempfile
+
+from .planning import task_plan_packet
+
+
+def planning_batch_guidance() -> str:
+ command = shlex.join([sys.executable, "-m", "benchmark.runtime.planning_batch"])
+ return (
+ "Initial plan batch (optional for an empty work and requirements frontier). "
+ "After following the planner, save a JSON proposal alongside "
+ "LOOPX_PLANNING_RESULT with input_digest from "
+ "the checkpoint and expected_provider_revision from "
+ "goal_acceptance.provider_revision. Set outcome to the "
+ "declaration's objective, requirements and source. Set todos to the "
+ "ordered list of objects with text, action_kind and optional target_key. "
+ f"Run {command} and return the successful planning result. Keep the unchanged "
+ "proposal on interruption and rerun the same command. For existing work, "
+ "requirement revisions or blockers, follow the ordinary planning steps.\n\n"
+ )
+
+
+def _record(value, required: set[str], optional: set[str] | frozenset[str] = frozenset()) -> dict:
+ if not isinstance(value, dict) or not required <= value.keys() <= required | optional:
+ raise ValueError("Planning proposal has missing or unsupported fields")
+ return value
+
+
+def _text(value) -> str:
+ if not isinstance(value, str) or not value.strip() or "\0" in value:
+ raise ValueError("Planning proposal requires non-empty text")
+ return value.strip()
+
+
+def _request(proposal: dict) -> dict:
+ _record(proposal, {"input_digest", "expected_provider_revision", "outcome", "todos"})
+ outcome = _record(proposal["outcome"], {"objective", "requirements", "source"})
+ source = _record(outcome["source"], {"ref", "summary"})
+ requirements, todos = outcome["requirements"], proposal["todos"]
+ if not all(isinstance(items, list) and items for items in (requirements, todos)):
+ raise ValueError("Planning proposal needs at least one requirement and one Todo")
+ requirements = [
+ {key: _text(value) for key, value in _record(item, {"id", "description"}).items()}
+ for item in requirements
+ ]
+ todos = [
+ {key: _text(value) for key, value in _record(todo, {"text", "action_kind"}, {"target_key"}).items()}
+ for todo in todos
+ ]
+ if len({item["id"] for item in requirements}) != len(requirements):
+ raise ValueError("Planning requirement IDs must be unique")
+ if len({todo["text"] for todo in todos}) != len(todos):
+ raise ValueError("Planning Todos must be distinct")
+ return {
+ "input_digest": _text(proposal["input_digest"]),
+ "expected_provider_revision": _text(proposal["expected_provider_revision"]),
+ "outcome": {
+ "objective": _text(outcome["objective"]),
+ "requirements": requirements,
+ "source": {key: _text(value) for key, value in source.items()},
+ },
+ "todos": todos,
+ }
+
+
+def _outcomes(acceptance: dict) -> list[dict]:
+ return acceptance["goal_acceptance_contract"].get("outcome_requirements", {}).get("outcomes", [])
+
+
+def _declared_outcome(acceptance: dict, declaration: dict) -> dict:
+ state = acceptance["goal_acceptance_contract"].get("outcome_requirements", {})
+ if state.get("current_lifetime") is not True:
+ raise ValueError("Planning declaration belongs to a different Goal lifetime")
+ for row in _outcomes(acceptance):
+ if row["id"] == declaration["outcome_id"]:
+ requirements = {item["id"]: item["description"] for item in row["requirements"]}
+ expected = {item["id"]: item["description"] for item in declaration["requirements"]}
+ if (row["owner_agent_id"] == declaration["owner_agent_id"]
+ and row["objective"] == declaration["objective"]
+ and requirements == expected):
+ return row
+ break
+ raise ValueError("Planning declaration is missing or changed; inspect the current Goal")
+
+
+def apply_initial_plan(env: dict[str, str], proposal: dict) -> dict:
+ if env.get("LOOPX_TASK_STAGE") != "plan":
+ raise ValueError("Planning batch requires the runner's planning stage")
+ proposal = _request(proposal)
+ from .worker import loopx_command
+
+ cli = loopx_command(env)
+ packet = task_plan_packet(env, cli)
+ if proposal["input_digest"] != packet["input_digest"]:
+ raise ValueError("Planning input changed")
+ revision = proposal["expected_provider_revision"]
+ acceptance = packet["goal_acceptance"]
+ if packet["goal_waiting_on"] or packet["blocking_todo_ids"]:
+ raise ValueError("Use the ordinary planning path for a Goal wait or blocker")
+
+ def digest(value) -> str:
+ return hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest()
+
+ # Bind all Todo intent to the declaration receipt. Two different proposals
+ # for one input cannot replay the same declaration and mix their Todo writes.
+ operation = f"benchmark-plan:{packet['input_digest']}"
+ declaration = {
+ **proposal["outcome"],
+ "outcome_id": f"benchmark-plan-{digest(proposal)[:32]}",
+ "owner_agent_id": packet["agent_id"],
+ }
+ if acceptance["provider_revision"] == revision:
+ if packet["existing_todos"] or _outcomes(acceptance):
+ raise ValueError("Use the ordinary planning path for existing work or requirements")
+ else:
+ _declared_outcome(acceptance, declaration)
+
+ goal = ["--goal-id", packet["goal_id"]]
+ actor = ["--agent-id", packet["agent_id"]]
+
+ def call(*args: str) -> dict:
+ process = subprocess.run(
+ [*cli, *args], cwd=env["LOOPX_PROJECT"], env=env, text=True,
+ capture_output=True, timeout=120,
+ )
+ try:
+ result = json.loads(process.stdout)
+ except ValueError:
+ raise ValueError(f"LoopX {args[0]} {args[1]} returned no JSON receipt") from None
+ if not isinstance(result, dict):
+ raise ValueError(f"LoopX {args[0]} {args[1]} returned an invalid receipt")
+ if process.returncode or result.get("ok") is not True:
+ reason = result.get("error_code") or result.get("error") or "unknown"
+ raise ValueError(f"LoopX {args[0]} {args[1]} failed: {reason}")
+ return result
+
+ with tempfile.TemporaryDirectory(prefix="loopx-planning-") as directory:
+ document = Path(directory) / "refinement.json"
+
+ def refine(value: dict, expected: str, effect: str) -> None:
+ document.write_text(json.dumps(value, ensure_ascii=False), encoding="utf-8")
+ call("goal-acceptance", "refine", *goal, *actor, "--document", str(document),
+ "--expected-provider-revision", expected, "--operation-id", effect, "--execute")
+
+ refine(declaration, revision, f"{operation}:declare")
+ ids = []
+ for index, item in enumerate(proposal["todos"]):
+ written = call(
+ "todo", "add", *goal, "--project", env["LOOPX_PROJECT"],
+ "--role", "agent", "--claimed-by", packet["agent_id"],
+ "--task-class", "advancement_task",
+ *(f"--{key.replace('_', '-')}={value}" for key, value in item.items()),
+ "--operation-id", f"{operation}:todo:{index}", "--execute",
+ )
+ todo_id = written.get("todo_id")
+ if not isinstance(todo_id, str) or not todo_id or todo_id in ids:
+ raise ValueError("Planning writer did not return distinct real Todo IDs")
+ ids.append(todo_id)
+
+ # Resolve the binding revision and check actual runnable ownership. A
+ # historical add receipt can be valid even if its Todo changed later.
+ current_packet = task_plan_packet(env, cli)
+ if current_packet["input_digest"] != packet["input_digest"]:
+ raise ValueError("Planning input changed before binding")
+ if not set(ids).issubset(current_packet["runnable_todo_ids"]):
+ raise ValueError("Planning Todos are no longer runnable by this agent")
+ if current_packet["goal_waiting_on"] or current_packet["blocking_todo_ids"]:
+ raise ValueError("Planning encountered a new Goal wait or blocker")
+ current = current_packet["goal_acceptance"]
+ linked = _declared_outcome(current, declaration)["todo_ids"]
+ if linked and linked != ids:
+ raise ValueError("Planning work links changed; inspect the current Goal")
+ if not linked:
+ basis = current["provider_revision"]
+ refine({"outcome_id": declaration["outcome_id"], "todo_ids": ids},
+ basis, f"{operation}:bind:{digest(basis)[:32]}")
+ return {"input_digest": packet["input_digest"], "status": "ready", "todo_ids": ids}
+
+
+def main() -> int:
+ if len(sys.argv) != 2:
+ print("Usage: python -m benchmark.runtime.planning_batch PROPOSAL.json", file=sys.stderr)
+ return 2
+ try:
+ proposal = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+ result = apply_initial_plan(dict(os.environ), proposal)
+ except (ValueError, KeyError, OSError, subprocess.TimeoutExpired) as exc:
+ print(json.dumps({"ok": False, "error": str(exc)}))
+ return 1
+ print(json.dumps(result))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/benchmark/runtime/worker.py b/benchmark/runtime/worker.py
index 93ebf2c394..8b234e193b 100644
--- a/benchmark/runtime/worker.py
+++ b/benchmark/runtime/worker.py
@@ -496,6 +496,7 @@ def native_command(env, execution, stage, wake, session_wake):
reasoning_effort=env["REASONING_EFFORT"],
session_id=session_wake.session_id if session_wake else None,
mcp_server=None,
+ mcp_turn_environment={},
)
if execution.context_delivery != "off":
command[-1:-1] = json.loads(env.get("LOOPX_CODEX_CONTEXT_TRUST_ARGS", "[]"))
diff --git a/benchmark/tests/test_shared_codex_runtime.py b/benchmark/tests/test_shared_codex_runtime.py
index b4c8c961bb..c229f26f00 100644
--- a/benchmark/tests/test_shared_codex_runtime.py
+++ b/benchmark/tests/test_shared_codex_runtime.py
@@ -168,6 +168,19 @@ def worker_env(tmp_path):
}
+def test_resumed_worker_builds_native_command_without_collaboration_server(tmp_path):
+ env = worker_env(tmp_path)
+ execution = Execution(context_delivery="off")
+ session = SimpleNamespace(session_id="retained-session")
+
+ command = worker.native_command(env, execution, "execute", tmp_path, session)
+
+ assert command[:2] == [env["CODEX_BIN"], "exec"]
+ assert "resume" in command
+ assert command[-2:] == [session.session_id, "-"]
+ assert not any(argument.startswith("mcp_servers.") for argument in command)
+
+
def test_non_heartbeat_wakes_do_not_import_checkpoint_control_plane(tmp_path, monkeypatch):
# plain/native-goal workers stage no LoopX control plane; a checkpoint import
# there turned a 90-minute trial into a 0.7s ModuleNotFoundError exit.
diff --git a/benchmark/tests/test_task_entry.py b/benchmark/tests/test_task_entry.py
index 7bc54676e4..0be9d0f086 100644
--- a/benchmark/tests/test_task_entry.py
+++ b/benchmark/tests/test_task_entry.py
@@ -468,6 +468,7 @@ def test_prose_or_fabricated_todo_does_not_qualify_planning(planning_env):
@pytest.mark.parametrize("producer", [None, "local_probe"])
def test_planner_delivers_product_contract_and_only_opted_in_tool_context(planning_env, producer):
from benchmark.runtime.planning import task_plan_packet
+ from benchmark.runtime.planning_batch import planning_batch_guidance
from benchmark.runtime.research_probe import execution_observation_guidance
from benchmark.runtime.worker import loopx_command
@@ -488,7 +489,8 @@ def test_planner_delivers_product_contract_and_only_opted_in_tool_context(planni
packet = json.loads(body.split("Host-supplied planning checkpoint:\n", 1)[1])
assert packet == before
prefix = body.split("Host-supplied planning checkpoint:\n", 1)[0]
- assert prefix.replace(execution_observation_guidance(), "").strip() == "$loopx"
+ assert prefix.count(planning_batch_guidance()) == 1
+ assert prefix.replace(execution_observation_guidance(), "").replace(planning_batch_guidance(), "").strip() == "$loopx"
assert receipt["planning"]["input_digest"] == before["input_digest"]
assert env["LOOPX_PHASE_DEADLINE_EPOCH"] == deadline
assert not list(Path(env["LOOPX_PROJECT"]).iterdir())
diff --git a/benchmark/widesearch/tests/test_tasks.py b/benchmark/widesearch/tests/test_tasks.py
index f1ea1aa626..10681c8140 100644
--- a/benchmark/widesearch/tests/test_tasks.py
+++ b/benchmark/widesearch/tests/test_tasks.py
@@ -4,7 +4,6 @@
import sys
from pathlib import Path
-import pytest
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md
index cf60956983..580b70dcff 100644
--- a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md
+++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md
@@ -223,10 +223,10 @@ management tree.
| Role / owner | Decisions and behavior it owns | Responsibilities it does not own |
| --- | --- | --- |
-| Router / steward | Understand intent, discover context-affine capable units, propose reuse/creation, pass revisions, synthesize results and cross-task tradeoffs | Micromanage worker tools, claim/accept for receivers, copy Goal task stores or budgets |
-| Controller / within a unit | Select work from Goal, planning horizon and evidence; maintain continuity, discover/inspect worker sessions, read/write and validate in the shared environment, interact with user/router, assess correction and acceptance, call Core | Become another authority or replace durable work with chat notes; approve every local tool step |
-| Worker / within a unit | Autonomously use tools, experiment, produce artifacts and report evidence/questions within admitted scope | Consume Core packets, author settlement or directly hold Core write access |
-| Core + managed execution + Host adapter | Existing typed rules, persistence, identity, dispatch, observation, stop and recovery | Infer authority/completion from prose or choose domain solutions for the model |
+| Router / steward | Understand intent, discover context-affine capable units, propose reuse/creation, dispatch scoped `collaboration_brief_v0` contracts, track bounded `remaining_work` and typed `resume_when` continuation predicates, synthesize results and close the original-route async inbox without polling loops | Micromanage worker tools, poll workers in loops, claim/accept for receivers, copy Goal task stores or budgets |
+| Controller / within a unit | Select work from Goal, planning horizon and evidence; emit/consume upward adaptive stride and receipt-gated context policy proposals (`{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}`); maintain continuity, discover/inspect worker sessions, read/write and validate in the shared environment, interact with user/router, assess correction and acceptance, call Core | Become another `AuthorityStore` writer, bypass CAS/lease fencing, replace durable work with chat notes, or approve every local tool step |
+| Worker / within a unit | Autonomously use tools, experiment, produce patches/artifacts and report evidence/questions inside an isolated **sandboxed executor worktree** within admitted scope | Consume Core packets, author settlement, access hidden verifiers/credentials, or directly hold Core write access |
+| Core (`AuthorityStore` + CAS + lease) + Host adapter | Sole deterministic owner of `AuthorityStore` transactions, conditional revision `CAS`, single-writer `claim/lease` fencing, once-only receipts, default-deny ACLs, sandbox isolation, observation, stop and recovery | Infer authority/completion from prose, rewrite active KV-cache prefixes without receipts, or choose domain solutions for the model |
The router may answer simple questions from sufficient existing evidence without
creating a unit. Prefer reuse of an Agent whose current context and authority fit;
@@ -236,6 +236,24 @@ A router's priority is a request: the controller assesses local commitments and
dependencies, returns adoption, deferral or refusal with reasons, and Core applies
legal changes.
+Keep three architectural planes strictly separated across every unit:
+
+1. **Deterministic Kernel (`AuthorityStore` + CAS + single-writer lease ownership):**
+ holds authoritative Goal, Todo, `claim/lease`, generation fence, `remaining_work` /
+ `resume_when`, and once-only settlement receipts under default-deny ACLs and
+ out-of-tree deterministic validation gates.
+2. **Sandboxed Executor Worktrees:** host-enforced execution sandboxes (`linked
+ worktrees` / containers with normalized patch delivery and credential exclusion)
+ where workers experiment freely without Core credentials or write authority;
+ resetting or losing a sandbox leaves `AuthorityStore` state uncorrupted.
+3. **Upward Adaptive Stride and Context Policy Decisions:** sits beside the
+ controller and `control_plane/work_items` / `progressive_context.ts` to select
+ `{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}` proposals
+ ([History working sets §5.1](history-working-set-context-policy-v0.md#51-one-projection-owner),
+ [Joint decisions §5.9](target-yardstick-stride-decisions-v0.md#policy-evolution));
+ these proposals remain strictly advisory until Core validates deterministic
+ receipts, CAS preconditions, and budget bounds.
+
### One Agent identity, two independent sessions
@@ -387,9 +405,14 @@ dependency, user-action, budget, stop or terminal condition remains effective;
otherwise useful authorized work must not wait for the user to say “continue”.
This logical loop is event-driven, not a blocking wait that occupies the
-controller session. Persist dispatch, observations, pending assessment and
-continuation through their existing owners. The host/runtime resumes eligible
-processing after a result or recorded wake; it does not keep a model polling.
+controller session. Persist dispatch, observations, pending assessment, bounded
+`remaining_work`, typed `resume_when` continuation predicates (`todo_done`,
+`pr_merged`, `capacity_available`, `monitor_changed`, `resume_at`), and
+continuation state inside the Core `AuthorityStore` owner. The host/runtime
+wakes eligible processing only when a verified result, `collaboration_brief_v0`
+return, or satisfied `resume_when` trigger arrives; it **never keeps a steward or
+controller model running polling loops**, and closes the steward async inbox
+back to the original requester upon completion or actionable blocker.
On recovery, reconcile the original attempt and unfinished decision/effect before
continuing, without dispatching another worker merely to restart the loop.
@@ -713,10 +736,14 @@ additional design choice here is **where decisions and attention are spent**:
| What the executor must know | Deliver the task's full constraints, relevant contrary evidence, original materials and unresolved reads; explain the decision in task language | A summary is not an alternate contract or proof of source reading. Unknown relevance requires more material before dependent work |
| What a result changes | Distinguish a finding, verified artifact, blocked attempt and accepted outcome; decide whether to continue, investigate or replan | Independent validation and current Core receipts, rather than either session's narrative, determine acceptance and settlement |
-Keep three operations separate. The deterministic composition owner combines
-domain facts without inventing policy; the existing codec encodes an exactly
-recoverable full/delta input; the controller performs task-dependent semantic
-selection and reasoning. A natural-language task can omit irrelevant control
+Keep three operations separate. The deterministic composition and `AuthorityStore`
+owner combines domain facts, enforces CAS/single-writer lease fencing, and gates
+`FoldToReceipt` / `EpochReset` transitions on deterministic receipts without
+inventing policy; the existing codec encodes an exactly recoverable full/delta
+input while preserving monotonic `KeepRaw` KV-cache prefixes between epochs; the
+controller performs task-dependent semantic selection, reasoning, and upward
+`{grow, switch, verify}` stride proposals over the isolated worker's sandboxed
+worktree results. A natural-language task can omit irrelevant control
syntax and cannot promise bit-for-bit equivalence. Its adequacy is tested by
preserved constraints, actual executor decisions and accepted outcomes, with
the original authorized material reachable. Do not replace these operations
diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md
index abc7f8769d..df7f66b9e9 100644
--- a/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md
+++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md
@@ -183,16 +183,30 @@ Router 只汇总获授权的结果,不能因此读取所有单元的私有会
| 角色 / owner | 负责的判断与行为 | 不承担的职责 |
| --- | --- | --- |
-| Router(管家) | 理解用户意图,发现有上下文和能力的单元,选择复用/创建的提议,传递修订,汇总结果及跨任务取舍 | 不逐工具指挥 worker,不替接收方认领/验收,不复制各 Goal 的任务库与预算 |
-| Controller(单元内) | 结合 Goal、planning horizon 与证据选择工作,维护任务连续性,发现并检查 worker 会话,在共享工作环境中读写、核验,与用户/router 交互,判断纠偏与验收并调用 Core | 不成为第二权威,不用自己的聊天笔记代替工作状态;不必为每个工具步骤审批 |
-| Worker(单元内) | 在已准入范围内自主使用工具、实验、产出及报告证据/问题 | 不消费 Core packet,不编造结算,不直接持有 Core 写权限 |
-| Core + 受管执行 + Host adapter | 既有 typed 规则、持久化、身份、派发、观察、停止和恢复 | 不从自然语言猜权限/完成,不替模型决定领域方案 |
+| Router(管家) | 理解用户意图,发现有上下文和能力的单元,选择复用/创建的提议,传递作用域受限的 `collaboration_brief_v0` 契约,持久化有界 `remaining_work` 与类型化 `resume_when` 接续谓词,汇总结果并无轮询地闭合原路异步 inbox | 不逐工具指挥 worker,不执行轮询循环,不替接收方认领/验收,不复制各 Goal 的任务库与预算 |
+| Controller(单元内) | 结合 Goal、planning horizon 与证据选择工作,提出或消费向上自适应步幅与受回执门控上下文策略建议(`{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}`),维护任务连续性,发现并检查 worker 会话,在共享工作环境中读写、核验,与用户/router 交互,判断纠偏与验收并调用 Core | 不成为第二个 `AuthorityStore` 写入方,不绕过 CAS/租约围栏,不用自己的聊天笔记代替工作状态,不必为每个工具步骤审批 |
+| Worker(单元内) | 在已准入范围内,于隔离的**沙盒执行器 worktree(sandboxed executor worktree)**中自主使用工具、实验、产出补丁/产物及报告证据/问题 | 不消费 Core packet,不编造结算,不接触隐藏 verifier 或凭据,不直接持有 Core 写权限 |
+| Core(`AuthorityStore` + CAS + 单写者租约)+ Host adapter | `AuthorityStore` 事务、条件版本 `CAS`、单写者 `claim/lease` 围栏、仅一次回执、默认拒绝 ACL、沙盒隔离、观察、停止和恢复的唯一确定性权威 | 不从自然语言猜权限/完成,不在缺少回执时改写在线 KV-cache 前缀,不替模型决定领域方案 |
Router 可以直接回答已有证据足够的简单问题,不必每次创建单元。分配工作优先复用
当前上下文与授权匹配的 Agent;创建新 Agent 仍沿既有生命周期和资源准入。多个候选
绑定不明时先消歧,不能按标题相似或“最近在线”抢占。Router 给出的优先级是请求;
controller 结合本地承诺与依赖评估并返回接受、延后或拒绝及理由,Core 执行合法变更。
+每个单元严格分离三个架构平面:
+
+1. **确定性内核(`AuthorityStore` + CAS + 单写者租约归属):** 在默认拒绝 ACL 与树外确定性
+ 验证门禁保护下,唯一持有权威 Goal、Todo、`claim/lease`、代际围栏、`remaining_work` /
+ `resume_when` 与仅一次结算回执。
+2. **沙盒执行器 worktree:** 宿主强制隔离的执行沙盒(带归一化补丁交付与凭据排除的 `linked
+ worktree` / 容器),worker 可在其中自由实验而无 Core 凭据或写权限;沙盒重置或丢失不破坏
+ `AuthorityStore` 持久状态。
+3. **向上自适应步幅与上下文策略决策:** 位于 controller 与 `control_plane/work_items` /
+ `progressive_context.ts` 一侧,用于选择 `{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}`
+ 建议(见[历史工作集策略 §5.1](history-working-set-context-policy-v0.zh-CN.md#51-单一投影-owner)、
+ [联合决策 §5.9](target-yardstick-stride-decisions-v0.zh-CN.md#policy-evolution));这些建议在
+ Core 验证确定性回执、CAS 前置条件与预算边界前始终仅为建议态。
+
### 一个 Agent 身份,两个独立会话
@@ -310,10 +324,13 @@ flowchart TB
完成,都不等于整个 Goal 结束。真实依赖、用户操作、预算、停止或终态条件仍然有效;
除此之外,有用且已获授权的工作不应停等用户说“继续”。
-这个逻辑循环由事件驱动,不是占住 controller 会话的阻塞等待。派发、观察、待评估结果与
-接续仍由各自既有 owner 持久化;结果或已记录唤醒到达后,由 host/runtime 恢复合格处理,
-不让模型空轮询。恢复时先核对原 attempt 以及未完成决策/effect,再继续,不能为了
-“重启循环”另派一个 worker。
+这个逻辑循环由事件驱动,不是占住 controller 会话的阻塞等待。派发、观察、待评估结果、
+有界 `remaining_work`、类型化 `resume_when` 接续谓词(`todo_done`、`pr_merged`、
+`capacity_available`、`monitor_changed`、`resume_at`)与接续状态均由 Core `AuthorityStore`
+owner 持久化;仅当已验证结果、`collaboration_brief_v0` 回传或满足的 `resume_when`
+触发器到达时,才由 host/runtime 唤醒合格处理,**绝不让管家或 controller 模型保持空轮询循环**,
+并在完成或遇可操作阻塞时将管家异步 inbox 原路闭合回请求方。恢复时先核对原 attempt 以及
+未完成决策/effect,再继续,不能为了“重启循环”另派一个 worker。
处理完用户/router 输入后,**从当前主循环待办重新选择**:可能先评估未读结果、补上反馈、
派发已合格工作或结算,而不是无条件恢复旧汇报。汇报根据已有证据,在执行并行期间或
@@ -583,9 +600,11 @@ digest 保护传输,canonical hash 保护语义内容,既有 effect 身份
| Executor 必须知道什么 | 交付任务完整约束、相关反证、原始材料和未完成必读,用任务语言解释判断 | 摘要不是另一份契约,也不证明读过来源;相关性未知时,依赖工作前须补足材料 |
| 结果改变什么 | 区分发现、已验证产物、受阻尝试与已接受成果,判断继续、调查或 replan | 独立验证与当前 Core 回执决定验收和结算,不能由任一会话的叙述替代 |
-区分三种操作:确定性的 composition owner 组合 domain 事实,不另造 policy;既有
-codec 编码可精确恢复的 full/delta 输入;controller 按任务进行语义选择和推理。自然
-语言任务可以省去无关控制语法,不能承诺逐字节等价。其充分性要由约束保留、executor
+区分三种操作:确定性的 composition 与 `AuthorityStore` owner 组合 domain 事实、强制 CAS/单写者
+租约围栏,并以确定性回执门控 `FoldToReceipt` / `EpochReset` 迁移,不另造 policy;既有
+codec 编码可精确恢复的 full/delta 输入,并在 epoch 间维持单调 `KeepRaw` KV-cache 前缀;
+controller 围绕沙盒执行器 worktree 返回的证据按任务进行语义选择、推理及向上的
+`{grow, switch, verify}` 步幅提议。自然语言任务可以省去无关控制语法,不能承诺逐字节等价。其充分性要由约束保留、executor
实际决策与验收成果检验,同时原始获授权材料仍可到达。不能用第二套 schema、模型编写的
状态库或按关键词判断相关性的分类器替代这些操作。Controller 笔记是工作上下文,不是
新的持久权威。
diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.md
index 71e2fc78b1..335ae7f4f4 100644
--- a/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.md
+++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.md
@@ -579,6 +579,12 @@ design, not a claim that these paths have changed.
| `turn_driver/decision_capture.py` and `cli_commands/quota_capture.py` | Reuse immutable capture, validated readers and full/delta delivery. Fresh delivery and saved-capture recovery must reconstruct the same contract; do not reuse a continuity baseline for a different projection merely because its Turn identity matches. |
| `benchmark/runtime/worker.py`, `benchmark/runtime/sessions.py` and `scripts/external_scheduler_worker.py` | Migrate the product entry they actually invoke. Keep evaluation setup and outer wake ownership; do not add benchmark-only conversion or count a managed-host test as attached-host acceptance. |
+The current heartbeat generator uses `interaction_contract` for target
+selection, required reads and exact Turn settlement. Saved bootstrap wrappers
+reload that generator on wake. All in-tree generation callers use this route,
+so the old envelope-specific instructions and their prompt budget allowance
+are retired. Previously captured work still uses its recorded recovery reader.
+
Before replacing any seam, its implementation PR records source path, field or
instruction clause, current readers, target owner, representation, recovery and
retirement condition. Relocation must include reference resolution; an omitted
diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.zh-CN.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.zh-CN.md
index e0775360bf..efc1e6ee5d 100644
--- a/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.zh-CN.md
+++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.zh-CN.md
@@ -431,6 +431,11 @@ Draft,不是仅等待评审。尚无模型或成本收益证据。历史 effec
| `turn_driver/decision_capture.py` 与 `cli_commands/quota_capture.py` | 复用不可变 capture、校验读取器和 full/delta 交付。首次交付和保存后恢复必须重建同一契约;不能仅因 Turn 身份相同,就把某投影的 continuity baseline 用于另一投影。 |
| `benchmark/runtime/worker.py`、`benchmark/runtime/sessions.py` 与 `scripts/external_scheduler_worker.py` | 迁移它们实际调用的产品入口。保留评估配置与外层唤醒归属,不新增 benchmark 专用转换,也不把 managed-host 测试算作 attached-host 验收。 |
+当前 heartbeat 生成器通过 `interaction_contract` 交付目标选择、必读和原 Turn
+结算。已保存的 bootstrap 在唤醒时重新调用该生成器。树内所有生成调用都已采用
+此路径,因此退役旧 envelope 专用指令和额外提示词预算。已有 capture 中的工作
+继续由记录的恢复 reader 读取。
+
替换任一接缝前,实现 PR 记录源路径、字段或指令条款、当前 reader、目标 owner、表示、
恢复与退役条件。字段搬迁须包含引用解析;删除诊断须证明其中不含动作、权限、必读或
验收义务。未知数据不得静默消失;未知的必需执行语义也不能靠转发 JSON 就变安全,
diff --git a/docs/architecture/rfcs/history-working-set-context-policy-v0.md b/docs/architecture/rfcs/history-working-set-context-policy-v0.md
index d7552f73c9..a3d1a6a183 100644
--- a/docs/architecture/rfcs/history-working-set-context-policy-v0.md
+++ b/docs/architecture/rfcs/history-working-set-context-policy-v0.md
@@ -138,6 +138,18 @@ flowchart TD
D/E are proposed capabilities, not model calls performed during each synchronous view assembly. Current work authority, capture IO, shared TypeScript projection, exact codec, and host delivery remain with their existing owners.
+#### Downward harness co-design: receipt-gated sampling-stack primitives (`KeepRaw` / `FoldToReceipt` / `EpochReset`)
+
+To eliminate mid-trajectory cache-busting dynamic working-set rewrites while keeping historical promotion verifiable, the shared TypeScript projection owner (`progressive_context.ts` + `context_delivery.ts` + `turn_envelope.ts`) formalizes downward harness co-design through **three receipt-gated sampling-stack primitives** (a proposed contract with `Proposal` maturity and `default-off` execution):
+
+| Primitive | Legal precondition | Prefix & KV-cache effect | Working-set & authority rule |
+| --- | --- | --- | --- |
+| `KeepRaw` | Default intra-epoch state for active obligations, unverified probes, open candidates, or ineligible ranges (§5.2) | **Monotonic append-only:** appends new eligible spans strictly at the tail of the current prefix, preserving **100% prefix KV-cache stability** across consecutive steps | Zero mid-trajectory deletion, reordering, or summary rewriting of already emitted spans |
+| `FoldToReceipt` | Candidate meets §5.2 eligibility **and** holds a deterministic settlement, capture, or verification receipt binding outcome, revision, failure cause, and exact source ref | Marks the verified historical unit folded and **queues** its compact receipt/summary entry for the next `EpochReset`, never mutating the already emitted live prefix mid-epoch | Working-set promotion is strictly **receipt-backed**; unverified model prose, self-reports, or unconfirmed proxy claims cannot trigger folding |
+| `EpochReset` | Explicit quiescent, settlement, session-resume, or compaction checkpoint (`decision_capture` + `context_delivery` epoch advance) where accumulated folded savings clear cold-prefill break-even | **Sole** transition permitted to rebase the canonical prefix (`epoch + 1`), compacting queued `FoldToReceipt` entries into a fresh immutable base prefix | Preserves original captures and exact readback refs; resets warm KV-cache prefix explicitly rather than silently mid-stride |
+
+Between any two `EpochReset` boundaries, the prefix preceding the monotonic append tail stays byte-identical (`100%` prefix KV-cache hit preservation). Upward policy layers (`{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}` in [Joint Target, Yardstick and Stride Decisions](target-yardstick-stride-decisions-v0.md#policy-evolution)) may propose these transitions, while the deterministic projection owner enforces receipt verification, eligibility checks, and epoch invariance.
+
### 5.2 Historical eligibility
V0 candidates come from existing typed attempt/result/evidence facts and bounded sources, not completion inferred from strings such as “done” or “old logs.” A candidate must meet all of the following:
@@ -202,7 +214,7 @@ The following is necessary to extend a current-turn capture into history across
- **Deletion and invalidation:** Declare reference validity scope and duration at publication. Normal cleanup must not break that promise early. If the owner cannot honor it, shorten the promise or do not enable that view. Explicit user deletion, revocation, and corruption must immediately affect source and summary visibility; preserving a summary cannot bypass them. An unreadable source cannot remain labeled fully expandable. Remove optional summaries; handle required dependencies under existing rules.
- **Locator limitation:** With the current path-bound reader, a path is the locator for that profile. Do not claim transparent cross-machine recovery or automatic relocation before validating migration.
- **Deduplication boundary:** Equal content hashes do not authorize visible reference reuse across users, Goals, or permission boundaries.
-- **Cache key:** Include scope/visibility, exact ordered sources and digests, and policy/generation versions. Do not rewrite stable summaries every turn and cause needless prefix changes.
+- **Cache key:** Include scope/visibility, exact ordered sources and digests, epoch boundary identity, and policy/generation versions. Maintain monotonic `KeepRaw` append stability within an epoch and defer dynamic working-set rewriting until an explicit `EpochReset` checkpoint so prefix KV-cache reuse stays intact across steps.
- **Historical truth versus current applicability:** “R1 failed then” can remain true. Moving the current task from R2 to R3 requires revalidation of selection and applicability, not treating an old failure as current state or rewriting originals merely because time passed.
- **One level first:** Future summaries of summaries must trace coverage to leaves. V0 does not implement a general DAG/GC framework.
@@ -218,7 +230,7 @@ Recommended observation points are the existing ended-attempt/recorded-result li
### 5.7 Composition with exact delivery
-The order is fixed: complete sources → legal view selection/summary → validated working view → exact full/delta → host.
+The order is fixed: complete sources and verification receipts → legal `KeepRaw` / receipt-gated `FoldToReceipt` selection → epoch-frozen working view (or explicit `EpochReset` rebase) → exact full/delta → host.
The exact codec can reconstruct a derived view containing summaries; it cannot prove those summaries equivalent to original facts. A summary file cannot set host retained/complete evidence, and invalidation cannot re-run guard, create a new attempt, or repeat settlement. [LX4]
@@ -299,7 +311,7 @@ Measure separately:
1. Independently accepted outcomes, omitted constraints, incorrect revision references, repeated failed approaches, and human intervention.
2. LoopX projection bytes/estimated tokens, actual host input, and observable coverage; mark invisible portions unknown.
-3. Provider usage for every execution/summary/retry call: cached and uncached input, output, and later input caused by readback. Avoid counting the same usage twice.
+3. Provider usage for every execution/summary/retry call: explicitly separate `cached_prefix_tokens` (warm KV-cache hits along stable `KeepRaw` prefixes) from `uncached_input_tokens` (cold-prefill starts, cache-TTL misses, or `EpochReset` prefix rebuilds), output tokens, and later input caused by readback. Report cold-versus-warm KV-cache regimes separately and avoid counting the same usage twice.
4. Summary preparation, reads, retries, overall wall time, and tail latency.
5. Source disk use, retention duration, and cleanup/recovery overhead.
diff --git a/docs/architecture/rfcs/history-working-set-context-policy-v0.zh-CN.md b/docs/architecture/rfcs/history-working-set-context-policy-v0.zh-CN.md
index 4839f852fd..c70b9b6589 100644
--- a/docs/architecture/rfcs/history-working-set-context-policy-v0.zh-CN.md
+++ b/docs/architecture/rfcs/history-working-set-context-policy-v0.zh-CN.md
@@ -138,6 +138,18 @@ flowchart TD
D/E 为拟新增能力,不在每轮同步视图构建时临时执行模型调用。当前工作权威、capture IO、共享 TypeScript 投影、exact codec、host delivery 分别沿原 owner 实施。
+#### 向下 Harness 协同设计:受回执门控的采样栈原语(`KeepRaw` / `FoldToReceipt` / `EpochReset`)
+
+为消除回合中动态改写工作集对前缀 KV-cache 的破坏,同时确保历史视图晋升具备可核验性,共享 TypeScript 投影 owner(`progressive_context.ts` + `context_delivery.ts` + `turn_envelope.ts`)通过**三类受回执门控的采样栈原语**将向下 harness 协同设计形式化(仍属 `Proposal` 成熟度且默认关闭):
+
+| 原语 | 合法前置条件 | 前缀与 KV-cache 效应 | 工作集与权威边界 |
+| --- | --- | --- | --- |
+| `KeepRaw` | 默认的 epoch 内状态,适用于活跃义务、未验证探针、开放候选或不符合 §5.2 条件的范围 | **单调仅追加:** 仅在当前前缀尾部追加符合条件的新片段,在连续步骤间保持 **100% 前缀 KV-cache 稳定性** | 禁止在回合中删除、重排或重摘要已发出的前缀片段 |
+| `FoldToReceipt` | 候选满足 §5.2 准入条件,**且**持有确定性的结算、capture 或验证回执,绑定结果、失败原因、版本与精确来源引用 | 将已核验历史单元标记为已折叠,并把精简回执/摘要条目**排队等待**下一次 `EpochReset`,绝不在 epoch 中途改写已发出的在线前缀 | 工作集晋升严格**以回执为依据**;未经验证的模型散文、自报结果或未确认代理声明均不能触发折叠 |
+| `EpochReset` | 显式的静默、结算、会话恢复或压缩 checkpoint(`decision_capture` + `context_delivery` epoch 推进),且累计折叠收益超过冷启动 prefill 回本阈值 | **唯一**允许重定基规范前缀(`epoch + 1`)的迁移,将排队中的 `FoldToReceipt` 条目压缩为新的不可变基础前缀 | 保留原始 capture 与精确回读引用;显式重置温 KV-cache 前缀,而非在步幅中途静默失效 |
+
+在任意两次 `EpochReset` 边界之间,单调追加尾部之前的前缀保持字节级恒定(`100%` 前缀 KV-cache 命中保持)。向上策略层([联合决策 RFC §5.9](target-yardstick-stride-decisions-v0.zh-CN.md#policy-evolution) 中的 `{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}`)可提议这些迁移,确定性投影 owner 负责执行回执校验、资格检查与 epoch 不变量。
+
### 5.2 哪些材料允许进入候选集
首版候选来自已存在的 typed attempt/result/evidence 事实与有界来源,不通过“done”“旧日志”等字符串推测完成度。
@@ -204,7 +216,7 @@ interface HistorySummaryProvider {
- **原文删除/失效:** 发布时声明引用的有效范围/期限,正常清理不能提前破坏这项承诺;既有 owner 不能保证时,缩短承诺范围或不启用该历史视图。用户显式删除、权限撤销与异常损坏须立即反映到来源和摘要可见性,不能为了保留摘要而绕过。失去可读来源时不得继续标为完整可展开;可选摘要退出,必需材料依赖按原规则处理。
- **引用定位限制:** 复用当前 path-bound reader 时,路径只是该 profile 下的定位方式;未验证迁移前,不宣称跨机器透明恢复或引用可自动重定位。
- **去重边界:** 即使内容哈希相同,也不因此跨用户、Goal 或权限边界复用可见引用。
-- **缓存键:** 基于 scope/可见性边界、精确有序来源集合与 digest、策略和生成版本。稳定材料不每轮重写摘要,避免无意义 prefix 变化。
+- **缓存键:** 基于 scope/可见性边界、精确有序来源集合与 digest、epoch 边界身份、策略和生成版本。在一个 epoch 内保持单调 `KeepRaw` 追加稳定性,把工作集动态改写推迟到显式 `EpochReset` checkpoint 执行,从而在连续步骤间保持前缀 KV-cache 复用完整。
- **历史真实性与当前适用性分开:** “R1 当时失败”可以持续为真;当前任务从 R2 变成 R3 后,要重新验证该历史的选择计划和适用性,不把旧失败当作当前状态,也不必仅因时间流逝重写历史原文。
- **首版只做一层:** 以后增加摘要的摘要时,父摘要仍需能追溯叶子 coverage;不在首版实现通用 DAG/GC 框架。
@@ -220,7 +232,7 @@ interface HistorySummaryProvider {
### 5.7 与 exact delivery 的组合
-顺序固定为:完整来源 → 合法视图选择/摘要 → 校验后的工作视图 → exact full/delta → 宿主。
+顺序固定为:完整来源与验证回执 → 合法 `KeepRaw` / 回执门控 `FoldToReceipt` 视图选择 → epoch 冻结工作视图(或显式 `EpochReset` 重定基) → exact full/delta → 宿主。
exact codec 可以精确重建一份含摘要的派生视图,但不能据此证明摘要等价于原始事实。不能因摘要文件存在就设置宿主 retained/complete,也不能借摘要失效重新 guard、创建新 attempt 或重复 settlement。[LX4]
@@ -303,7 +315,7 @@ exact codec 可以精确重建一份含摘要的派生视图,但不能据此
1. 独立验收成果、约束遗漏、错误版本引用、重复失败路径和人工介入。
2. LoopX projection bytes/estimated tokens、实际 host input 与可观测覆盖;不可见部分标 unknown。
-3. 所有执行/摘要/重试调用的 provider usage,cached 与 uncached 输入、输出、回读引起的后续输入;避免同一 usage 重复计费。
+3. 所有执行/摘要/重试调用的 provider usage:显式区分 `cached_prefix_tokens`(沿稳定 `KeepRaw` 前缀命中的温 KV-cache)与 `uncached_input_tokens`(冷 prefill 启动、缓存 TTL 失效或 `EpochReset` 前缀重建)、输出 token 以及回读引起的后续输入;分别报告冷/温 KV-cache 工况,避免同一 usage 重复计数。
4. 摘要构建、读取、重试和整体 wall time / tail latency。
5. 来源磁盘量、保留期限和清理/恢复开销。
diff --git a/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md b/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md
index 30688e2ce7..2703ae9548 100644
--- a/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md
+++ b/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md
@@ -133,17 +133,26 @@ outperform lossy hand-written summaries:
discovery precisely by keeping a fixed immutable outer loop over deterministic
programmatic verifiers without letting the solver alter its own harness or
grading contract.
+- [AgentFlow](https://arxiv.org/abs/2510.05592) demonstrates in multi-turn tool
+ planning that offline SFT on static traces causes distribution collapse under
+ trajectory shift, whereas in-the-loop segment optimization (`Flow-GRPO`) keeps
+ exploration grounded in live tool outcomes while leaving frozen executors clean;
+ and [HELIX](https://arxiv.org/abs/2608.13951) demonstrates how verified
+ sibling trajectories forked from shared states separate causal policy uplift
+ from confounded starting-state drift.
- Published LoopX context studies ([context delivery](https://loopx-project.github.io/loopx/blog/context-delivery/)
and [EdgeBench feedback and memory](https://loopx-project.github.io/loopx/blog/edgebench-feedback-and-memory/))
likewise show that verbose serialization and post-peak replan loops can consume
- substantial uncached context when raw-code inspection and local probes would
- suffice.
+ substantial uncached context—and mid-trajectory dynamic prompt rewriting
+ breaks prefix KV-cache reuse, shifting warm-cache runs into expensive cold
+ prefill regimes—when raw-code inspection, local probes, and monotonic append
+ prefixes would suffice.
However, empirical evidence establishes **five failure regimes** where raw
artifacts, scalar rewards, and clean resets cannot replace a governed control
plane:
-1. **Goodharting and verifier tampering:** Whenever the solver shares process,
+1. **Goodharting, verifier tampering, and symptom-masking shortcuts:** Whenever the solver shares process,
filesystem, network, or secret boundaries with the grader, unguarded
optimization exploits shortcut channels—observed in `LHTB 2.0` (`14/17` early
perfect scores came from grader leaks prior to process freezing and verifier
@@ -154,8 +163,10 @@ plane:
rollout reward hacking), [Darwin Gödel Machine](https://arxiv.org/abs/2505.22954)
(Node 114 falsifying verification logs), and
[METR reward-hacking evaluations](https://metr.org/blog/2025-06-05-recent-reward-hacking/).
- In-agent Python probes cannot enforce OS/container verifier isolation or
- `benchmark_integrity_audit_v0` (§6.5, §7.1).
+ In-agent Python probes cannot enforce OS/container verifier isolation,
+ `benchmark_integrity_audit_v0`, or out-of-tree **anti-reward-hacking
+ root-cause certification guards** (distinguishing real invariant repairs from
+ test-muting, threshold relaxation, or fixture hardcoding; §6.5, §7.1).
2. **Out-of-distribution (OOD) overfitting and harness bloat:** Unregularized
evolution over raw artifacts memorizes training traces and degrades OOD.
[RRSI](https://arxiv.org/abs/2609.24972) finds unregularized Meta-Harness
@@ -741,7 +752,7 @@ change, not a corresponding percentage reduction in total research cost.
| Observation | Required interpretation |
| --- | --- |
| Packet bytes and delivered context | Measure serialization, source reading and actual consumer input separately. References must still resolve to complete applicable instructions; smaller output obtained by omitting obligations is not an efficiency gain. |
-| Model usage | Attribute actual request identities and retained counters to their covered session/Turn window. Reconcile compaction, retries, mirrored records and cumulative snapshots without double counting; distinguish cached from uncached input. Missing request or tail coverage remains unknown. |
+| Model usage | Attribute actual request identities and retained counters to their covered session/Turn window. Reconcile compaction, retries, mirrored records and cumulative snapshots without double counting; explicitly separate `cached_prefix_tokens` (warm KV-cache hits) from `uncached_input_tokens` (cold prefill / post-`EpochReset` prefix rebuilds) and output tokens, reporting **cold vs. warm KV-cache regimes** separately. Missing request or tail coverage remains unknown. |
| Complete marginal cost | Include task work, control, evaluation, recovery and human attention where measured. Report collection/validation overhead too; unknown components prevent a claim about full monetary cost. Preserve cancelled and failed attempts rather than dividing only by successful work. |
| Useful result | Report the best valid retained native artifact/result, terminal completion and new verified improvements separately. Task-native ranking remains authoritative; a partial score, completed Todo or final file alone is not whole-task success. |
@@ -756,13 +767,28 @@ adding a parallel cost ledger or converting bytes into estimated savings.
**Agent decision rule for harness and planning changes.** Judge every candidate
harness, context or planning change by net terminal accepted outcome
$\Delta J(B \mid s_0) = \mathbb{E}[Y_B^\pi - Y_B^{\pi_0} \mid s_0]$ under
-**complete budget accounting**—charging model/context processing, control-plane
-and protocol tax (RPC round trips, schema ceremony, governance prompts),
-checkpoint creation, yardstick build/repair, and evaluator/confirmation compute
-and cooldown waits. Preserve negative, null and inconclusive results in the
-denominator, and prioritize restorable quiescent same-state checkpoint
-counterfactuals ($\tau_B(s; a, a_0, \pi)$) over unattributed tweaks inferred
-from confounded observational action logs.
+**complete budget accounting**—charging model/context processing (explicitly
+separating `cached_prefix_tokens` vs. `uncached_input_tokens` across cold vs.
+warm KV-cache regimes so mid-trajectory cache-busting rewrites cannot masquerade
+as packet-byte savings), control-plane and protocol tax (RPC round trips, schema
+ceremony, governance prompts), checkpoint creation, yardstick build/repair, and
+evaluator/confirmation compute and cooldown waits. Preserve negative, null and
+inconclusive results in the denominator, and prioritize restorable quiescent
+same-state checkpoint counterfactuals ($\tau_B(s; a, a_0, \pi)$) over
+unattributed tweaks inferred from confounded observational action logs.
+
+**Counterfactual arm attribution across adaptive policy variants.** When an
+adaptive meta-policy (such as Phase 1 `KL-UCB` arm selection in
+[Joint decisions §5.9](target-yardstick-stride-decisions-v0.md#policy-evolution))
+explores among candidate `(target–yardstick, stride, context-stack)` arms, raw
+selected-arm win rates conflate state difficulty with treatment effect. Log each
+arm's exact assignment propensity $p(a \mid s)$ at decision time and evaluate
+cross-variant contrasts with inverse-propensity / Horvitz-Thompson style matched
+arm attribution ($\hat{\Delta}_{\text{HT}}(B \mid s)$ or doubly-robust
+residuals over shared-checkpoint sibling groups as in
+[HELIX](https://arxiv.org/abs/2608.13951)), verifying positivity ($p(a \mid s) > 0$),
+overlap diagnostics, and effective sample size ($N_{\text{eff}}$) rather than
+promoting observational win-rate artifacts.
### 6.3 Long-horizon control quality
@@ -911,8 +937,14 @@ The [Research human-attention observer](../../reference/trajectory-assessment.md
now reads source-bound human inputs, separate active/wait interval unions and
recorded avoidable-input candidates through the existing pack and citation owner.
Recorder classifications, partial timing and historical sources remain explicit.
-Synthetic packaged-reader checks qualify this reading path; live capture coverage,
-calibrated necessity and lower attention for equal accepted quality remain unqualified.
+Synthetic packaged-reader checks qualify this reading path. The live producer
+boundary is now qualified only for authenticated LoopX Lark `operation.execute`
+and `team.plan` card decisions, explicitly bound to a Goal pack and UTC window.
+It preserves partial coverage, treats delivery-to-confirmation as waiting, leaves
+active attention and necessity unknown, rejects multi-principal windows to retain
+the single-human contract, and labels conservative pre-marker backfill as legacy.
+Unauthenticated, pending/expired and runtime-native approval capture, calibrated
+necessity and lower attention for equal accepted quality remain unqualified.
### 6.5 Benchmark integrity and anti-cheating
@@ -940,6 +972,17 @@ environment digests, parity status, disposition, reason codes, and redacted
evidence references. A public receipt cannot upgrade an unknown private audit
to `eligible`.
+**Anti-reward-hacking root-cause certification guards.** Alongside mount, network,
+and hidden-verifier isolation, integrity and acceptance qualification must
+enforce deterministic out-of-tree root-cause certification guards: verifying that
+candidate fixes preserve frozen test harnesses, unmodified assertions, and
+differential invariants across held-out/adversarial checks rather than passing
+via skipped tests, weakened tolerances, fixture hardcoding, or grading-path
+shortcuts. Structured guard outcomes (missing failing-to-passing evidence,
+unauthorized test edits, or differential regressions) feed directly into
+`benchmark_integrity_audit_v0` dispositions (`quarantined` / `invalid`) without
+inferring cheating from solver prose substrings.
+
#### Declared feedback and evaluation timing
Qualification must compare observed access with the preregistered experiment
@@ -1200,8 +1243,10 @@ To avoid benchmark overfitting:
The [Post-Outcome Memory Utility Attribution RFC](./post-outcome-memory-utility-attribution-v0.md)
can use verified benchmark outcomes as one evidence source. A trajectory-level
-reward does not establish per-memory causal credit. Holdout replay or a bounded
-ablation is required before assigning strong utility. Benchmark content must
+reward does not establish per-memory causal credit. Holdout replay, propensity-logged
+counterfactual arm attribution (§6.2), or a bounded ablation across batch-barrier
+`add / revise / retire` memory transitions (gated by Semantic Duplicate Gate
+deduplication) is required before assigning strong utility. Benchmark content must
never be retained in a way that contaminates later tasks.
@@ -1358,7 +1403,13 @@ information and confirmed gain. Attribute delayed gains to the relevant sequence
for analysis, not automatically to its last action; observational associations
remain non-causal. Only then add an affordable lookahead-depth or calibration
ablation where a specific uncertainty justifies it, rather than a full factorial
-matrix upfront.
+matrix upfront. When comparing Phase 1 (`KL-UCB` + batch-barrier memory) against
+Phase 2 Checkpoint-Forked `Segment Flow-GRPO` ($\Delta T$ rollouts over $O(1)$
+state projections; [Joint decisions §5.9](target-yardstick-stride-decisions-v0.md#policy-evolution))
+or evaluating `KeepRaw` / `FoldToReceipt` / `EpochReset` policies, report
+propensity-weighted Horvitz-Thompson arm contrasts (§6.2), cold-versus-warm
+KV-cache token splits, and anti-reward-hacking root-cause certification pass
+rates alongside native terminal scores.
Expand when repeated terminal benefits meet frozen margins and uncertainty
requirements without unacceptable correctness, resource or authority regressions.
@@ -1895,6 +1946,8 @@ This is a living research RFC, not a frozen benchmark snapshot.
- [Self-Harness](https://arxiv.org/abs/2606.09498)
- [Reward Hacking Benchmark (RHB)](https://arxiv.org/abs/2605.02964)
- [DuoDiscover paper](https://arxiv.org/abs/2610.17184)
+- [AgentFlow paper](https://arxiv.org/abs/2510.05592)
+- [HELIX paper](https://arxiv.org/abs/2608.13951)
- [AlphaEvolve paper](https://arxiv.org/abs/2506.13131)
- [Darwin Gödel Machine (DGM) paper](https://arxiv.org/abs/2505.22954)
- [Darwin Gödel Machine repository](https://github.com/jennyzzt/dgm)
diff --git a/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md b/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md
index eb08713df7..e979e01299 100644
--- a/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md
+++ b/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md
@@ -103,21 +103,27 @@ typed contract 与 public-safe 结论可以进入仓库。
`80%` 升至 `100%`,同时减少 `37%` token 并将延迟降低 `3.5x`。
- [AlphaEvolve](https://arxiv.org/abs/2506.13131) 在算法代码发现上的成功,恰恰依赖固定不变的
外层循环与确定性程序 verifier,而不允许求解器改写自身 harness 或评分契约。
+- [AgentFlow](https://arxiv.org/abs/2510.05592) 在多轮工具规划中表明,静态轨迹上的离线 SFT
+ 在轨迹分布偏移下会发生分布坍缩,而在环闭环分片优化(`Flow-GRPO`)使探索保持在真实工具结果上,
+ 同时让冻结执行器保持简洁;[HELIX](https://arxiv.org/abs/2608.13951) 则表明从共享状态分叉的
+ 已验证兄弟轨迹能够将因果策略增益与混淆的起点状态漂移分离开来。
- LoopX 已发布的上下文研究([上下文交付研究](https://loopx-project.github.io/loopx/blog/context-delivery/)
与 [EdgeBench 反馈与记忆研究](https://loopx-project.github.io/loopx/blog/edgebench-feedback-and-memory/))
同样表明,冗余序列化与见顶后的重复 replan 循环会在原始代码检查与本地探针即可解决的场景下消耗大量
- uncached 上下文。
+ uncached 上下文——而且回合中的动态提示词改写会破坏前缀 KV-cache 复用,把温缓存运行推入高昂的冷
+ prefill 工况——此时保留单调追加前缀与本地探针已足够。
然而,实证研究确立了**五类失败机制**,证明原始产物、标量奖励与干净重置无法替代受治理控制面:
-1. **Goodhart 与 verifier 篡改:** 当求解器与评分器共享进程、文件系统、网络或密钥边界时,
+1. **Goodhart、verifier 篡改与掩盖症状的捷径作弊:** 当求解器与评分器共享进程、文件系统、网络或密钥边界时,
缺乏防护的优化会利用捷径通道——实证见于 `LHTB 2.0`(在冻结 agent 进程并隔离 verifier 之前,
早期 `14/17` 个满分属于评分器泄漏)、[Reward Hacking Benchmark](https://arxiv.org/abs/2605.02964)
(13 个前沿模型利用漏洞比例为 `0%` 至 `13.9%`,其中 `72%` 带有显式思维链合理化,且在任务复杂度
超过诚实求解阈值后生产对齐保护失效)、[SWE-Marathon](https://arxiv.org/abs/2606.07682)
(观测到 `13.8%` rollout 存在 reward hacking)、[Darwin Gödel Machine](https://arxiv.org/abs/2505.22954)
(Node 114 伪造验证日志),以及 [METR reward-hacking 评估](https://metr.org/blog/2025-06-05-recent-reward-hacking/)。
- Agent 容器内的 Python 探针无法提供 OS/容器级 verifier 隔离与 `benchmark_integrity_audit_v0`(§6.5、§7.1)。
+ Agent 容器内的 Python 探针无法提供 OS/容器级 verifier 隔离、`benchmark_integrity_audit_v0`
+ 或树外**反 Reward-Hacking 根因认证守卫**(将真正的不变量修复与屏蔽测试、放宽阈值或硬编码fixture 区分开;§6.5、§7.1)。
2. **分布外(OOD)过拟合与 harness 膨胀:** 在原始产物上做无正则进化会死记训练轨迹并导致 OOD 退化。
[RRSI](https://arxiv.org/abs/2609.24972) 发现未正则的 Meta-Harness 在 OOD 仅提升 `+0.9`
(`40.6` vs `39.7`),`TTHE` 甚至下降 `-1.7`(`38.0` 并膨胀出 `8,500` 词提示词),而加入 critic
@@ -590,7 +596,7 @@ token、缓存处理、金额或验收价值。[#7050](https://github.com/loopx-
| 观测 | 必须保留的解释 |
| --- | --- |
| Packet 字节与交付上下文 | 分别测序列化、来源读取及实际消费者输入。引用仍须能解析完整适用指令;省略义务得到的小输出不是效率收益。 |
-| 模型用量 | 将真实 request 身份及保留的 counter 归属到覆盖的 session/Turn 窗口。核对压缩、重试、镜像记录与累计快照,避免重复计数,区分缓存/未缓存输入。请求或尾段覆盖缺失保持未知。 |
+| 模型用量 | 将真实 request 身份及保留的 counter 归属到覆盖的 session/Turn 窗口。核对压缩、重试、镜像记录与累计快照,避免重复计数;显式区分 `cached_prefix_tokens`(温 KV-cache 命中)与 `uncached_input_tokens`(冷 prefill / `EpochReset` 后前缀重建)及输出 token,并分别报告**冷 vs. 温 KV-cache 工况**。请求或尾段覆盖缺失保持未知。 |
| 完整边际成本 | 纳入已测任务工作、控制、评估、恢复及人工注意力,也报告采集/验证开销。未知项阻止完整金额主张;保留取消和失败尝试,不只用成功工作作分母。 |
| 有效成果 | 分别报告保留的最佳有效 native 产物/结果、终态完成与新增已验证提升。原生排名仍由任务拥有;部分分数、Todo 完成或最终文件单独不代表整题成功。 |
@@ -602,11 +608,19 @@ provider 计费完整或匹配研究收益。通过既有 Research 阅读入口
**面向 Agent 的 harness 与规划改动决策准则。** 评估任何候选 harness、上下文策略或
规划机制时,统一以**完整预算记账**下的净终局原生验收成果
-$\Delta J(B \mid s_0) = \mathbb{E}[Y_B^\pi - Y_B^{\pi_0} \mid s_0]$ 为准:模型/上下文处理、
-控制面与协议税(RPC 往返、必填表单仪式、治理提示词)、checkpoint 构建、yardstick 造尺/修尺,
-以及评测/确认计算和冷却等待均计入成本;将负结果、无差异结果和信息不足实验原样保留在分母中;
-优先构建可恢复的静默同状态 checkpoint 反事实接续($\tau_B(s; a, a_0, \pi)$),而非根据混淆起点状态的
-观察动作日志做无归因微调。
+$\Delta J(B \mid s_0) = \mathbb{E}[Y_B^\pi - Y_B^{\pi_0} \mid s_0]$ 为准:模型/上下文处理
+(显式区分冷/温 KV-cache 工况下的 `cached_prefix_tokens` 与 `uncached_input_tokens`,防止回合中
+破坏缓存的改写伪装成序列化字节节省)、控制面与协议税(RPC 往返、必填表单仪式、治理提示词)、
+checkpoint 构建、yardstick 造尺/修尺,以及评测/确认计算和冷却等待均计入成本;将负结果、
+无差异结果和信息不足实验原样保留在分母中;优先构建可恢复的静默同状态 checkpoint 反事实接续
+($\tau_B(s; a, a_0, \pi)$),而非根据混淆起点状态的观察动作日志做无归因微调。
+
+**跨策略变体的反事实 arm 归因。** 当自适应元策略(例如[联合决策 §5.9](target-yardstick-stride-decisions-v0.zh-CN.md#policy-evolution)
+中的 Phase 1 `KL-UCB` arm 选择)在候选 `(target–yardstick, stride, context-stack)` arm
+间探索时,单纯统计被选中 arm 的胜率会混淆状态难度与处理效应。应在决策时记录每个 arm 的精确分配倾向度
+$p(a \mid s)$,并采用逆倾向度加权 / Horvitz-Thompson 风格的匹配 arm 归因($\hat{\Delta}_{\text{HT}}(B \mid s)$
+或基于共享 checkpoint 兄弟轨迹组的双稳健残差,见 [HELIX](https://arxiv.org/abs/2608.13951))评估策略对比,
+同时核验正概率条件($p(a \mid s) > 0$)、重叠度诊断与有效样本量($N_{\text{eff}}$),避免把选择偏差当成因果收益。
### 6.3 长程控制质量
@@ -715,8 +729,12 @@ replan 前 checkpoint、恢复、接收者读回及下一次可观察动作的
[研究页人工注意力 observer](../../reference/trajectory-assessment.md#human-attention-in-research-optional)
现在通过既有 pack 与引用 owner 读取有来源的人工介入、分别取并集的主动/等待时间
及标记可避免的介入候选。记录方分类、部分时间覆盖和历史来源保持明确。
-合成打包阅读检查只验收此读取路径;真实采集覆盖、必要性校准及同等验收质量下的
-注意力降低仍未验收。
+合成打包阅读检查验收此读取路径。真实 producer 当前仅验收经过认证、由目标 Goal
+pack 与 UTC 时间窗显式绑定的 LoopX Lark `operation.execute` 与 `team.plan` 卡片决定。
+该边界保留部分覆盖,把投递到确认记为等待,主动投入和必要性保持未知;为保留单人
+记录契约,它拒绝包含多个 principal 的窗口,并将 marker 引入前的保守回填标为 legacy。
+未认证、pending/expired、runtime-native approval 的采集,必要性校准及同等验收质量下
+的注意力降低仍未验收。
### 6.5 Benchmark integrity 与反作弊
@@ -740,6 +758,12 @@ answer 相似这一事实来推断作弊。
run identity、固定 policy/environment digest、parity status、disposition、reason code 与
redacted evidence reference。公开 receipt 不能把未知的 private audit 升级为 `eligible`。
+**反 Reward-Hacking 根因认证守卫。** 除挂载、网络与隐藏 verifier 隔离之外,完整性与验收资格还必须
+执行树外确定性的根因认证守卫:核验候选修复是否保持冻结测试框架、未篡改断言与跨留出/对抗性检查的
+差分不变量,而非通过跳过测试、放宽容差、硬编码 fixture 输出或评分通道捷径过关。结构化守卫失败结果
+(缺少失败到通过证据、未授权测试改动或差分回归)直接记入 `benchmark_integrity_audit_v0` 处置
+(`quarantined` / `invalid`),而不依赖求解器文本子串推断作弊。
+
#### 声明反馈权限与评测时机
完整性资格必须比较实际访问与预注册实验协议。协议包含两个独立选择:solver 能否请求并
@@ -957,8 +981,9 @@ capability approval。capability candidate 必须按 caller outcome 命名,不
[结果后记忆效用归因 RFC](./post-outcome-memory-utility-attribution-v0.zh-CN.md)可以把经过验证的
benchmark outcome 作为一种 evidence source。trajectory-level reward 不能建立 per-memory
-causal credit。给出强 utility 前必须做 holdout replay 或 bounded ablation。benchmark 内容
-绝不能以污染后续 task 的方式被保留。
+causal credit。给出强 utility 前必须做 holdout replay、记录倾向度的反事实 arm 归因(§6.2),
+或针对受 Semantic Duplicate Gate 去重保护的批屏障 `add / revise / retire` 记忆迁移开展有界消融。
+benchmark 内容绝不能以污染后续 task 的方式被保留。
@@ -1073,7 +1098,10 @@ workspace。按预先声明的处理保留正确性失败、未完成评分、
把行动前预测与真实方法、资源、中间证据及终局结果对照,区分预测价值、实际采用、
信息与确认收益。分析延迟收益时关联相关工作序列,不自动只归给最后一步;观察关联
仍不是因果结论。只有具体疑问值得时,再增加可负担的 lookahead 深度或校准消融,
-不一开始铺开全因子矩阵。
+不一开始铺开全因子矩阵。在对比 Phase 1(`KL-UCB` + 批屏障记忆)与 Phase 2 Checkpoint-Forked
+`Segment Flow-GRPO`(基于 $O(1)$ 状态投影的 $\Delta T$ rollout;[联合决策 §5.9](target-yardstick-stride-decisions-v0.zh-CN.md#policy-evolution))
+或评估 `KeepRaw` / `FoldToReceipt` / `EpochReset` 策略时,须与原生终局分数一并报告倾向度加权
+Horvitz-Thompson arm 对比(§6.2)、冷/温 KV-cache token 拆分及反 Reward-Hacking 根因认证通过率。
重复终局收益达到冻结的界限与不确定性要求,且无不可接受的正确性、资源或权限
回归,才扩大实验。保留负结果及不确定结果。冻结选中策略后再测 held-out 任务和
@@ -1537,6 +1565,8 @@ promotion 或修改 LoopX default。
- [Self-Harness](https://arxiv.org/abs/2606.09498)
- [Reward Hacking Benchmark (RHB)](https://arxiv.org/abs/2605.02964)
- [DuoDiscover 论文](https://arxiv.org/abs/2610.17184)
+- [AgentFlow 论文](https://arxiv.org/abs/2510.05592)
+- [HELIX 论文](https://arxiv.org/abs/2608.13951)
- [AlphaEvolve 论文](https://arxiv.org/abs/2506.13131)
- [Darwin Gödel Machine (DGM) 论文](https://arxiv.org/abs/2505.22954)
- [Darwin Gödel Machine 仓库](https://github.com/jennyzzt/dgm)
diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md
index 57016cc4fc..3d7bdde2f8 100644
--- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md
+++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md
@@ -8,8 +8,9 @@
separately in Section 8. The history working-set RFC inventory addition uses
`701795db2` on 2026-11-09; goal-oriented slice selection, zero-ceremony
progressive entry, structural moats, and selected priority/RFC boundaries are
- reconciled through 2026-11-11 against `bf8a66eb9c`, without re-auditing every
- historical subsystem.
+ reconciled through 2026-11-11 against `bf8a66eb9c`, with Bitter-Lesson
+ subtraction discipline and six compounding structural moats refined against
+ `e235cde9c8`, without re-auditing every historical subsystem.
- Ownership: overall product outcomes, cross-domain dependencies, priorities and portfolio acceptance here; concrete rules in domain RFCs/stable protocols; execution state in canonical Todos.
- Language: [中文版](loopx-overall-roadmap-v0.zh-CN.md) is the semantic mirror.
@@ -101,29 +102,67 @@ and routine uncontested single-Agent turns:
Mandatory per-Turn schema forms, extra RPC round trips, or verbose governance
prompts when nothing material changed degrade net long-horizon efficiency and
must be rejected.
-
-### Three compounding structural moats
-
-As frontier base models strengthen, LoopX avoids investing in brittle hand-written
-prompt micro-scheduling—prescribed tool sequences, rigid per-Turn checklists or
-verbose tactical reminders—that stronger models absorb natively. Engineering and
-research focus concentrates on three structural capabilities outside a single
-model forward pass:
-
-1. **Heterogeneous local/cloud continuity and authority boundaries (`S2/S4/S9`, `R5/R6`):**
- bridging local personal context, interactive logins and owner confirmation
- gates with unattended or cloud execution workers under single-owner
- transactional leases, fencing and revocable grants.
-2. **Deterministic quiescent checkpoints and same-state counterfactual continuation (`S4/S10/S11`, `R5`, `T01/T03`):**
- restoring exact task, session, authority, incumbent and evaluator-cooldown
- state at elapsed budget $t_0$ so candidate strategies and harness mechanisms
- are evaluated via matched same-state continuations ($\tau_B(s; a, a_0, \pi)$)
- rather than confounded observational action logs.
-3. **Closed-loop trajectory-to-memory and budgeted allocation flywheel (`S6/S7/S11`, `T01–T04`):**
- turning verified trajectory outcomes, scoped neighborhood yardstick fidelity
- and same-checkpoint counterfactual evidence into procedural recall and
- calibrated `Target/Yardstick/Stride` continuation choices (`current-model
- pilot -> calibrated estimates -> learned allocation`).
+- **Bitter-Lesson subtraction discipline:** as frontier base models strengthen,
+ reject brittle hand-written prompt micro-scheduling, speculative compatibility
+ shims, and mid-trajectory dynamic prompt surgery that stronger models absorb
+ natively or that induce context gravity
+ ([Subtraction Gate](controller-executor-unified-contract-v0.md#subtraction-gate)).
+ Invest only in verifiable deterministic invariants outside a single model
+ forward pass, and retire superseded wrappers and unreferenced adapters when a
+ single typed owner replaces them.
+
+
+
+### Six compounding structural moats
+
+As frontier base models strengthen, LoopX applies the Bitter-Lesson subtraction
+discipline above—avoiding brittle hand-written prompt micro-scheduling,
+prescribed tool sequences, rigid per-Turn checklists or verbose tactical
+reminders that stronger models absorb natively
+([Research Bitter-Lesson boundary](long-horizon-harness-benchmark-research-program-v0.md#22-bitter-lesson-boundary-raw-artifact-resets-versus-governed-control)).
+Engineering and research focus concentrates on **six compounding structural
+moats** outside a single model forward pass:
+
+1. **Non-scalar Yardstick calibration (`S3/S6/S11`, `T01–T04`):**
+ co-discovering `Target/Yardstick/Stride` decisions (`grow / switch / verify`)
+ backed by multi-evidence, decision-local neighborhood fidelity rather than
+ uncalibrated scalar proxies, and compounding verified trajectory outcomes
+ into closed-loop recall and calibrated allocation
+ (`current-model pilot -> calibrated estimates -> learned allocation`;
+ [Joint decisions](target-yardstick-stride-decisions-v0.md)).
+2. **Out-of-tree deterministic Merge, Visual, and Boundary gates (`S5/S8/S11/S12`):**
+ enforcing host- and process-isolated verification outside the solver's
+ write boundary—`benchmark_integrity_audit_v0` verifier/mount isolation and
+ anti-reward-hacking root-cause certification, public/private boundary scans,
+ exact-head `loopx pr-review` and merge-readiness contracts, and populated
+ first-screen visual/behavioral evidence that an agent cannot rewrite, spoof,
+ or self-certify in prose.
+3. **Single-owner `AuthorityStore` + CAS + default-deny ACL (`S2/S3/S9`, `R4/R5/R6`):**
+ anchoring Goal/Todo/effect truth in transactional event, projection and
+ receipt commits with conditional revision `CAS`, exclusive `claim/lease` and
+ generation fencing, explicit ambiguous-commit handling, once-only idempotent
+ settlement, and default-deny audience, credential and capability ACL
+ boundaries across File/SQLite/NoKV/PostgreSQL providers.
+4. **Steward async inbox closure (`S1/S3/S4/S5`, `R1–R3`):**
+ delivering cross-Agent delegation and original-route return via scoped
+ `collaboration_brief_v0` payloads, bounded `remaining_work` projections and
+ typed `resume_when` continuation predicates, keeping steward and controller
+ sessions asleep until verified wake triggers fire (**zero polling loops**).
+5. **Prefix-KV-cache-preserving context delivery (`S2/S6/S7`, `T02`):**
+ maintaining monotonic append-only canonical prefix stability and exact
+ full/delta transport (`progressive_context.ts` / `context_delivery.ts` with
+ receipt-gated `KeepRaw` / `FoldToReceipt` / `EpochReset` transitions;
+ [History working sets](history-working-set-context-policy-v0.md#51-one-projection-owner))
+ to avoid mid-trajectory cache-busting rewrites while pricing cached versus
+ uncached prefix tokens separately.
+6. **Durable state vs. ephemeral sandbox separation (`S2/S4/S10/S11`, `R5/R6`):**
+ isolating persistent `AuthorityStore`, capture and quiescent checkpoint
+ state—restorable at elapsed budget $t_0$ for heterogeneous local/cloud
+ continuity and same-state counterfactual continuation ($\tau_B(s; a, a_0, \pi)$)
+ rather than confounded observational logs—from disposable worker sandboxes
+ and worktrees (`--worker turn-resume`, isolated containers, normalized patch
+ delivery) so sandbox resets or failures never corrupt control authority or
+ expose host credentials.
### App-first conversation delivery
diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md
index 87c007d7e3..846df20ecb 100644
--- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md
+++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md
@@ -7,6 +7,7 @@
`08e290fb5`。管家故障复现基线单独保留在第 8 节。历史工作集 RFC 的清单新增
使用 2026-11-09 的 `701795db2`;面向终局目标的切片选择、零仪式感渐进式入口、
结构性护城河及所选当前优先级/RFC 边界依据 2026-11-11 的 `bf8a66eb9c` 核对更新,
+ 并依据 `e235cde9c8` 细化 Bitter-Lesson 减法纪律与六大结构性护城河,
不代表对所有历史子系统重新审计。
- 责任:总纲拥有产品目标、跨领域依赖、优先级和组合验收;领域 RFC/稳定协议拥有具体规则;运行 Todo 拥有执行状态。
- 语言:[English](loopx-overall-roadmap-v0.md) 与本文互为语义镜像。
@@ -80,22 +81,46 @@ LoopX 内部保持严格、唯一 owner 的类型化内核(`AuthorityStore`、
- **控制面税计入完整成本:** 控制 token、工具调用、额外 RPC 往返与人工打断都消耗任务总预算。
在事实未发生实质变化时强加每 Turn 必填表单、额外 RPC 往返或冗长治理提示词,会降低净长程效率,
应当拒绝。
-
-### 三大复利结构性护城河
-
-随着前沿基座模型快速升级,LoopX 避免投入会被更强基模原生吸收的脆弱手写提示词微操
-(预设工具调用顺序、每 Turn 机械清单、冗长战术提醒),把工程与研究重心集中在单次模型前向推理之外的
-三项复利结构能力:
-
-1. **端云异构连续性与权限围栏(`S2/S4/S9`、`R5/R6`):** 在唯一 owner 事务租约、旧执行器
- 围栏与可撤销授权下,把本地个人上下文、交互登录态和 owner 确认门禁安全桥接到无人值守或云端
- 执行 worker。
-2. **确定性静默 Checkpoint 与同状态反事实接续底座(`S4/S10/S11`、`R5`、`T01/T03`):**
- 在已消耗预算 $t_0$ 处精确恢复任务、会话、权限、已验收 incumbent 与评测冷却状态,使候选策略与
- harness 机制通过匹配的同状态接续($\tau_B(s; a, a_0, \pi)$)评估,而非混淆了起点状态的观察动作日志。
-3. **闭环轨迹归因记忆与预算内计算选择飞轮(`S6/S7/S11`、`T01–T04`):** 将已验证终局成果、
- 邻域范围化的 yardstick 保真度与同 checkpoint 反事实证据转化为可复用的过程召回,以及经校准的
- `Target/Yardstick/Stride` 预算内接续选择(`当前模型试验 -> 校准预期 -> 学习预算分配`)。
+- **Bitter-Lesson 减法纪律:** 随着前沿基座模型持续增强,拒绝脆弱的手写提示词微操、投机性兼容垫片,
+ 以及会被更强模型原生吸收或诱发上下文重力的回合中动态提示词改写(见[减法门禁](controller-executor-unified-contract-v0.zh-CN.md#subtraction-gate))。
+ 工程与研究只投入单次前向推理之外的可验证确定性不变量,一旦单一类型化 owner 替代旧路径,
+ 立即退役被取代的封装与无引用适配器。
+
+
+
+### 六大复利结构性护城河
+
+随着前沿基座模型快速升级,LoopX 贯彻上述 Bitter-Lesson 减法纪律——避免投入会被更强基模原生吸收的
+脆弱手写提示词微操(预设工具调用顺序、每 Turn 机械清单、冗长战术提醒;见
+[研究计划 Bitter-Lesson 边界](long-horizon-harness-benchmark-research-program-v0.zh-CN.md#22-bitter-lesson-边界原始产物重置与受治理控制面)),
+把工程与研究重心集中在单次模型前向推理之外的**六项复利结构能力**:
+
+1. **非标量 Yardstick 校准(`S3/S6/S11`、`T01–T04`):**
+ 围绕 `Target/Yardstick/Stride` 联合决策(`grow / switch / verify`)开展多证据、决策局部邻域
+ 保真度校准,而非依赖未校准的标量代理指标;并将已验证轨迹成果沉淀为闭环过程召回与经校准的预算分配
+ (`当前模型试验 -> 校准预期 -> 学习预算分配`;见[联合决策](target-yardstick-stride-decisions-v0.zh-CN.md))。
+2. **树外确定性 Merge、Visual 与 Boundary 门禁(`S5/S8/S11/S12`):**
+ 在求解器写边界之外执行宿主与进程隔离的确定性验证——包含 `benchmark_integrity_audit_v0` 的
+ verifier/挂载隔离与反 Reward-Hacking 根因认证、公私边界扫描、精确 head 的 `loopx pr-review` 与
+ merge-readiness 契约,以及高信息密度首屏视觉与行为证据;Agent 无法在文本中改写、伪造或自证通过。
+3. **唯一 owner `AuthorityStore` + CAS + 默认拒绝 ACL(`S2/S3/S9`、`R4/R5/R6`):**
+ 将 Goal/Todo/effect 真相锚定在事务化事件、投影与回执提交中,跨 File/SQLite/NoKV/PostgreSQL
+ provider 强制条件版本 `CAS`、独占 `claim/lease` 与代际围栏、显式 `ambiguous_commit` 处理、
+ 仅一次幂等结算,以及默认拒绝的受众、凭据与能力 ACL 隔离边界。
+4. **管家异步 inbox 闭环(`S1/S3/S4/S5`、`R1–R3`):**
+ 通过作用域受限的 `collaboration_brief_v0` 委派载荷、有界 `remaining_work` 投影与类型化
+ `resume_when` 恢复谓词完成跨 Agent 协作与原路回报,使管家与 controller 会话在已验证唤醒触发器
+ 到达前保持休眠(**零空轮询循环**)。
+5. **前缀 KV-Cache 保序上下文交付(`S2/S6/S7`、`T02`):**
+ 保持单调仅追加的规范前缀稳定性与精确 full/delta 传输(`progressive_context.ts` /
+ `context_delivery.ts` 配合回执门控的 `KeepRaw` / `FoldToReceipt` / `EpochReset` 状态迁移;
+ 见[历史工作集策略](history-working-set-context-policy-v0.zh-CN.md#51-单一投影-owner)),
+ 避免回合中破坏前缀缓存的动态改写,并分别计量 cached 与 uncached 前缀 token 成本。
+6. **持久状态与临时沙盒分离(`S2/S4/S10/S11`、`R5/R6`):**
+ 将持久 `AuthorityStore`、capture 与静默 checkpoint 状态——可在已消耗预算 $t_0$ 处精确恢复,
+ 支持端云异构连续性与同状态反事实接续($\tau_B(s; a, a_0, \pi)$),而非混淆起点的观察动作日志——与
+ 一次性 worker 沙盒及 worktree(`--worker turn-resume`、隔离容器、归一化补丁交付)严格分离,
+ 确保沙盒重置或故障不会破坏控制权威或暴露宿主凭据。
### 总纲与现有文档的关系
diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md
index 6e5521ac0a..67ca1a7af9 100644
--- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md
+++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md
@@ -4,7 +4,7 @@
- **Delivery maturity:** Proposal
- **Authors / owners:** LoopX maintainers
- **Created:** 2026-09-26
-- **Last normative revision:** 2026-11-17
+- **Last normative revision:** 2026-11-19
- **Implementation baseline:** packaging inventory `2f3d13ae9`; runtime composition audit `9cae3b28939f72fa4aadab5cfe49e19bcbdab372`
- **Related contracts:** [TypeScript Control-Plane Migration v0](typescript-control-plane-migration-v0.md), [Extensions reference](../../reference/extensions.md), [Capability catalog](../../../loopx/capabilities/README.md), [Overall Roadmap v0](loopx-overall-roadmap-v0.md) (S2, S8, S12), [import-boundary tests](../../../tests/architecture/test_control_plane_import_boundaries.py)
- **Tracking issue:** [#5072](https://github.com/loopx-project/loopx/issues/5072)
@@ -35,7 +35,7 @@ retain their original baselines.
wheel is replaced over time by `loopx-core`, `loopx-workspace`, and
per-capability packages under `packages/`, with `loopx` retained as a
meta-package that depends on all of them.
-3. **Top-level regrouping happens before any packaging change.** `loopx/chat_*`
+3. **Regroup the selected dependency closure as needed for independent packaging.** `loopx/chat_*`
moves to `loopx/chat/`, `loopx/*_goal_mode/` moves to `loopx/hosts/`, with
compatibility re-exports for established public imports for at least one minor
release. Internal-only callers move together and the old internal entry is deleted.
@@ -63,6 +63,20 @@ can be installed, not what every command must load. Installing standard grants
no service activation or permission. Existing defaults and machine-enforced
work obligations remain until a qualified, explicitly disclosed migration.
+The immediate outcome is an independently installed core that executes a task,
+recovers its original result and returns evidence. Unrelated directory moves,
+workspace packaging or another model session do not block that core-artifact
+slice; full M3 retains its complete distribution acceptance. Ordinary callers
+supply a task and consequential constraints, without first learning Vision,
+Quota, Lease or method names. The host carries bookkeeping; relevant permission,
+budget, uncertainty and recovery decisions remain visible when needed.
+
+The **10% complexity / 90% current-function coverage** target remains an unproven
+hypothesis. Fix a versioned journey denominator and compare necessary concepts,
+mandatory steps, loaded/activated code, model reads, complete costs and accepted
+outcomes. Report kernel-only and assembled coverage; do not drop specialized
+journeys from the denominator or treat code counts as model benefit.
+
## 2. Problem and motivation
A developer who wants a CLI-only or kernel-only LoopX installs the same wheel as
@@ -269,6 +283,19 @@ contract into prose guidance. The kernel is a cohesive set of domains, not one
large file. The adjacent refactor should localize the next change and preserve
characterized behavior.
+### Required mechanisms and optional task methods
+
+Core owns legal scoped work, durable evidence, stop, budget and original-attempt
+recovery. Bench, workbench and manager compose specialized workflows around the
+same owners. Their absence must not block unrelated authorized core work.
+**Yardstick is an independently optional decision method, not a provider or a
+mandatory kernel stage.** Methods choose how to reason or measure; providers
+supply execution, storage or concrete external operations. Reuse existing
+capability owners and `yardstick_enabled`; add no method registry, provider id
+or enable switch. Ordinary result validation remains required when a method is
+off. Existing records, configured obligations, authority and defaults survive;
+method/dependency removal needs its own absence, parity and recovery evidence.
+
### Presets over the distribution tiers
| Composition | Required content | Explicit optional content |
@@ -283,6 +310,16 @@ flag applied after standard fully initializes. A host-free read-only kernel
library does not qualify that executable preset. Exact contents and the first
supported host/authority combination are D2/D5 decisions.
+The initial proposed **Standard** selection is `agent-turn-recall` for relevant
+prior guidance, `issue-fix` for validated repository changes, and
+`pull-request-review` for delivery review. These retain their existing capability
+owners and default-off settings; installation grants no source access, starts
+no watcher and authorizes no publication or merge. Load only the selected task's
+implementation. Basic recovery stays in Minimal without advisory recall.
+Yardstick, Stride, research/benchmark machinery and manager routing remain
+separate optional additions. This selects the R2 target; the current monolithic
+and core-candidate wheels do not yet implement that isolated package selection.
+
Keep composition, managed/attached mode, host provider, one/two model sessions,
storage provider and benchmark arm independent. Minimal does not imply attached,
standard does not require two model sessions, and research does not mean
@@ -419,6 +456,11 @@ contract explicitly requires their receipt. Batch best-effort telemetry only;
do not defer authoritative receipt persistence, weaken fsync/transaction
guarantees or cache stale permission/lease decisions to meet a timing target.
+For an admitted ordinary task, the built-in Worker view omits known empty
+Todo summary lanes. The selected task, nonempty lanes, counts, references and
+upstream truncation remain visible. The signed source and original reader
+retain the complete summaries for recovery and diagnosis.
+
### Governed lifecycle and external effects
Use existing Goal/Agent/work/Turn identities, revisions, leases, effect ids and
@@ -489,6 +531,13 @@ defaults or a new LoopX model loop. Pinned sources are in Appendix C.
## 7. Safety, privacy, and compatibility
+Ordinary C1 composition and replay use shared Explore guidance and exact
+context references. An empty read with graph and planning disabled returns
+the existing disabled view before loading the graph projector. A scoped
+Explore read loads Yardstick when its graph is available and the Goal enables
+evaluation. Settings, evidence identities, and recovery remain with the
+current Goal and Explore owners.
+
- **Default-off / feature-off parity:** absent `loopx-workspace` or capability
packages behave like the existing extension off state (I4). No command
silently falls back to another implementation.
@@ -611,6 +660,14 @@ moves; it does not qualify the kernel. R3/R4 are optional and do not block a
qualified CLI or managed task. No unused provider, field or framework is added
ahead of its real caller. Report the applied/deferred adjacent refactor in each PR.
+### Core discovery checkpoint — 2026-11-19
+
+| Boundary | Delivered delta / evidence | Still open |
+| --- | --- | --- |
+| V1/V3, capability discovery | Benchmark package exports resolve their selected existing owner on demand, retaining all 199 public symbols and their order; explicit star imports still request all. Help/list/detail succeed with benchmark execution implementations unavailable, no Node, process launch, network or state writes. | Does not remove benchmark files from the wheel or qualify absent-capability installation. |
+| Metadata and active consumers | The same catalog and all 25 details are byte-identical to the frozen `main@e235cde9c` workload; 53 CLI help/list/detail/unknown-id observations match. Discovery loads 2 benchmark children instead of 28, and 298 LoopX modules instead of 326. Existing benchmark semantics and canonical export identities remain unchanged. | Import counts are not latency, total cost, model benefit or full D2/D5 closure. |
+| Acceptance and continuation | 52 installed-core discovery/execution/context/recovery cases pass on the rebuilt artifact; 383 selected consumer cases and 43 architecture/documentation cases pass separately. No new state owner, provider id, activation toggle or top-level module. | Keep R1/M3 and V1–V5/V10 open; continue capability package isolation and selected Standard delivery. Public-channel C1 qualification remains with its release owner. |
+
### Subtraction Gate & Anti-Context-Gravity Rules
diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
index 2303929af4..673316d11c 100644
--- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
+++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
@@ -4,7 +4,7 @@
- **交付成熟度:** Proposal
- **作者 / 负责人:** LoopX maintainers
- **创建:** 2026-09-26
-- **最近规范性修订:** 2026-11-17
+- **最近规范性修订:** 2026-11-19
- **实现基线:** 发行盘点 `2f3d13ae9`;运行时装配审计 `9cae3b28939f72fa4aadab5cfe49e19bcbdab372`
- **相关契约:** [TypeScript 控制面迁移 v0](typescript-control-plane-migration-v0.zh-CN.md)、[Extensions 参考](../../reference/extensions.md)、[Capability 目录](../../../loopx/capabilities/README.md)、[总体路线图 v0](loopx-overall-roadmap-v0.zh-CN.md)(S2、S8、S12)、[import 边界测试](../../../tests/architecture/test_control_plane_import_boundaries.py)
- **跟踪 issue:** [#5072](https://github.com/loopx-project/loopx/issues/5072)
@@ -25,7 +25,7 @@
1. **仓库保持单一 monorepo。** 一条 PR 流程、一套 CI、一个发布列车。拆成多个 Git 仓库是本 RFC 的非目标。
2. **安装物拆成多个发行物。** 单一 `loopx` wheel 逐步替换为 `loopx-core`、`loopx-workspace` 以及 `packages/` 下的按 capability 打包;`loopx` 保留为依赖全部子包的 meta-package。
-3. **先做顶层目录重组,再做打包变更。** `loopx/chat_*` 迁入 `loopx/chat/`,`loopx/*_goal_mode/` 迁入 `loopx/hosts/`,已建立的公开 import 保留至少一个 minor 版本的兼容 re-export;内部调用方一起迁移并删除旧内部入口。
+3. **按独立打包所需重组所选依赖闭包。** `loopx/chat_*` 迁入 `loopx/chat/`,`loopx/*_goal_mode/` 迁入 `loopx/hosts/`,已建立的公开 import 保留至少一个 minor 版本的兼容 re-export;内部调用方一起迁移并删除旧内部入口。
4. **新增一条架构测试钉住顶层增长。** `loopx/*.py` 的文件数只能减少,与现有零例外 import 边界测试并列。
5. **仅内核安装不得在 import 阶段要求 Node.js。** TS effect runtime 对有副作用的命令仍是必需的;缺失时必须以现有的类型化 `node_unavailable` 诊断呈现,而不是安装或 import 失败。
6. **不变:** 内核权威、CLI 兼容基线、extension 生命周期规则、公开/私有边界、全部稳定协议。
@@ -39,6 +39,15 @@ Minimal 必须执行并恢复真实的受治理任务;standard 围绕同一内
发行表定义可安装内容,不代表每条命令都必须加载。安装 standard 不授予服务激活或权限。
现有默认值与机器强制工作义务持续生效,直到合格且明确披露的迁移改变它们。
+当前优先结果是可独立安装、执行任务、恢复原结果并返回证据的 core。无关目录移动、
+workspace 打包或额外模型会话不阻塞这一 core 发行物切片;完整 M3 仍保留全部发行
+验收。普通调用者提供任务与关键约束,不必先学 Vision、Quota、Lease 或方法名称。
+Host 承担记账;必要的权限、预算、不确定性与恢复决策仍在相关时可见。
+
+**10% 复杂度/90% 当前功能覆盖率**仍是未验证假设。固定版本化用户旅程分母,比较
+必要概念、必经步骤、加载/启用代码、模型读取、完整成本和已验收成果。分别报告
+仅内核与组合后的覆盖率;不能从分母删除特化旅程,也不能以代码计数代替模型收益。
+
## 2. 问题与动机
只想要 CLI 或内核的开发者,安装的和运行桌面工作台、Lark 管家、全部内置 capability 的人是同一个 wheel。`2f3d13ae9` 上的历史发行盘点:
@@ -181,6 +190,16 @@ Planner 可以建议工作或 stride,所属迁移规则决定准入与义务
预设不能把机器强制的 `must_attempt_work` 契约变成文字 guidance。
内核是内聚领域的集合,不是一个大文件。相邻重构应让下一次修改更局部,并保持已刻画的行为。
+### 必要机制与可选任务方法
+
+Core 负责合法限定工作、持久证据、停止、预算及原 attempt 恢复。Bench、workbench、
+管家围绕相同 owner 组合特化工作流;它们缺席不能阻塞无关的已授权 core 工作。
+**Yardstick 是独立可选的决策方法,不是 provider 或强制内核阶段。** 方法选择如何
+推理或衡量;provider 提供执行、存储或具体外部操作。复用既有 capability owner 和
+`yardstick_enabled`,不增加方法 registry、provider id 或开关。关闭方法不免除普通
+结果验收。保留既有记录、已配置义务、权限与默认值;移除方法/依赖须独立证明组件
+缺席、一致性与恢复。
+
### 发行层之上的预设
| 装配 | 必需内容 | 显式可选内容 |
@@ -194,6 +213,13 @@ Minimal 是可执行装配,不是在 standard 完成全部初始化后加开
不带宿主的只读 kernel library 不构成可执行预设资格。
精确内容与首个受支持宿主/authority 组合由 D2/D5 决定。
+首批 **Standard** 选型提案为:`agent-turn-recall` 取回相关既有指导,`issue-fix`
+交付已验证仓库变更,`pull-request-review` 执行交付审查。保留各自既有 owner 和默认
+关闭设置;安装不授予来源访问、不启动 watcher,也不授权发布或合并。仅加载所选
+任务实现;可选指导召回缺席时,Minimal 仍保有基本恢复。Yardstick、Stride、研究/
+benchmark 机制与管家路由继续独立可选。这选定 R2 的目标,现有单体和 core 候选 wheel
+尚未实现该隔离分包组合。
+
装配、managed/attached 模式、宿主 provider、一个/两个模型 Session、存储 provider、benchmark arm
保持独立。Minimal 不意味着 attached,standard 不要求双模型 Session,research 不等于不受治理。
只发布已测组合,保留现有模式默认值;改变装配不能静默改变 binding 的执行 owner。
@@ -289,6 +315,10 @@ Capability 指令仅在适用时提供;authority 不能从 prompt 文字推导
其延迟不能进入准入/结算事务。只批处理尽力而为的 telemetry;不能为满足时间目标而延迟
authority receipt 持久化、弱化 fsync/事务保证,或缓存过期权限/租约决策。
+普通任务获准执行后,内置 Worker 视图省去已知为空的 Todo 摘要列表。所选任务、
+非空列表、计数、引用与来源截断信息继续可见。签名来源和原有读取入口保留完整摘要,
+供恢复与诊断使用。
+
### 受治理生命周期与外部副作用
通过统一工作契约使用既有 Goal/Agent/work/Turn 身份、revision、lease、effect id 与 receipt。
@@ -345,6 +375,10 @@ minimal 包含持久 shell、图像读取与 compaction。SDK minimal 还提供
## 7. 安全、隐私与兼容
+普通 C1 组装和重放沿用 Explore 的共享指引及精确上下文引用。图和规划关闭时,
+空读取在加载图投影前返回既有的关闭状态。有范围的 Explore 读取在图可用且 Goal
+启用评估时加载 Yardstick。设置、证据身份和恢复继续由当前 Goal 与 Explore 负责。
+
- **默认关闭 / 功能关闭一致性:** 缺失 `loopx-workspace` 或 capability 包时,行为等同现有 extension off state(I4)。没有命令会静默回退到另一实现。
- **公开/私有边界:** 不变。`loopx check` 继续扫描每个包;移动文件不改变其扫描类别。
- **旧读者/写者:** import shim(I3)覆盖已建立的公开 Python import。console script 保持名字;`loopx` meta-package 让 `pip install loopx` 在一个 minor 版本内行为完全一致。
@@ -443,6 +477,14 @@ M0–M5 保留原发行里程碑;R0–R4 是同一计划中的运行时和旅
R0 可以先于目录移动交付,但不代表内核合格。R3/R4 可选,不阻塞已合格的 CLI 或 managed 任务。
真实调用者出现前不增加闲置 provider、字段或框架。每个 PR 记录应用/推迟的相邻重构。
+### Core 发现入口检查点 — 2026-11-19
+
+| 边界 | 交付增量/证据 | 仍未完成 |
+| --- | --- | --- |
+| V1/V3,能力发现 | Benchmark 包公开符号按需解析到所选既有 owner,保留全部 199 个符号及顺序;显式星号导入仍请求全部。执行实现不可用且无 Node 时,帮助/列表/详情仍可用,无进程启动、网络或状态写入。 | 未从 wheel 删除 benchmark 文件,也不验收 capability 分包缺席安装。 |
+| 元数据与活跃调用方 | 同冻结 `main@e235cde9c` workload 的目录和全部 25 项详情逐字节一致;53 项 CLI 帮助/列表/详情/未知 id 观察一致。发现入口的 benchmark 子模块从 28 降到 2,LoopX 模块从 326 降到 298。保留 benchmark 语义及公开符号的 canonical 对象身份。 | Import 数量不代表时延、完整成本、模型收益或完整 D2/D5 闭包。 |
+| 验收与继续方向 | 重建发行物通过 52 项安装 core 发现/执行/上下文/恢复用例;383 项所选消费方与 43 项架构/文档用例分别通过。没有新增状态 owner、provider id、启用开关或顶层模块。 | R1/M3 与 V1–V5/V10 继续开放;下一步仍是 capability 分包隔离与所选 Standard 交付。公开渠道 C1 资格仍归既有 release owner。 |
+
### 减法门禁与反上下文重力规则
diff --git a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md
index bb8027908a..c4cab9b373 100644
--- a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md
+++ b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md
@@ -49,10 +49,22 @@ Stride action. Continuing unchanged is a legal decision and needs no fabricated
`grow` record on quiet Turns. A target can also use direct authoritative
evaluation without a proxy.
-The new ordinary-Turn and yardstick treatment starts explicitly off. Existing
+For upward model–harness co-design along the same owner (`§5.9`), this RFC
+composes the downward receipt-gated context-stack primitives
+`{KeepRaw, FoldToReceipt, EpochReset}`
+([History working sets](history-working-set-context-policy-v0.md#51-one-projection-owner))
+with stride actions `{grow, switch, verify}` across a two-phase policy roadmap:
+**Phase 1** uses a frozen-model non-parametric meta-policy (`KL-UCB` arm
+selection, bounded batch-barrier `add/revise/retire` memory evolution,
+Semantic Duplicate Gate, and protected control/root-cause guards); **Phase 2**
+advances only when matched-budget evidence justifies learned allocation via
+Checkpoint-Forked `Segment Flow-GRPO` ($\Delta T$ single-stride rollouts over
+$O(1)$ deterministic state projections).
+
+The new ordinary-Turn, yardstick, and upward co-design treatments start explicitly off. Existing
Stride defaults, configured periodic reviews, acceptance, budgets and host
continuation retain their meaning. This RFC does not approve automatic tool
-execution, benchmark-protocol changes or autonomous acceptance changes.
+execution, benchmark-protocol changes, learned-policy deployment, or autonomous acceptance changes.
## 2. Problem and motivation
@@ -76,6 +88,23 @@ repository tasks and 73% versus 33% on kernels; corresponding yardstick costs
are 4% versus 29% and 2% versus 18% of a true evaluation. These are results of
that study, with different target/task denominators, not predicted LoopX gains.
+Joint research decisions also couple directly to context-stack retention and
+long-horizon learning stability. Folding unverified exploration before a
+deterministic receipt discards counterevidence needed for `verify` or `switch`,
+while unbounded raw retention or mid-epoch prefix rewriting erodes remaining
+budget $B$ and breaks prefix KV-cache reuse
+([History working sets §5.1](history-working-set-context-policy-v0.md#51-one-projection-owner)).
+At the policy-learning layer, [AgentFlow](https://arxiv.org/abs/2510.05592)
+shows that offline supervised fine-tuning (SFT) on static trajectories induces
+distribution collapse under compounding long-horizon shifts compared with
+in-the-loop segment optimization (`Flow-GRPO`), while naive outcome-only
+multi-turn RL suffers linear credit-assignment decay across long episodes;
+[HELIX](https://arxiv.org/abs/2608.13951) further motivates grouping verified
+sibling trajectories forked from shared states to isolate causal gains without
+confounding starting conditions. These motivate unifying
+`{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}` behind a
+two-phase policy roadmap under the same typed owner (`§5.9`).
+
### Invariants
1. Task acceptance and authoritative evaluation stay with their existing owner.
@@ -576,9 +605,9 @@ promotion.
| Stage | Useful next result | Retained boundary |
| --- | --- | --- |
-| Current-model pilot | A revision-pinned bounded planning treatment changes actual work and improves the §8.7 comparison. | Existing Stride/Yardstick/Explore owners and ordinary responses; no second controller session or numerical fidelity engine prerequisite. |
-| Calibrated estimates | Pre-action predictions linked to actual method, duration, next state and terminal result improve forecast/calibration on held-out episodes. | The domain provider owns measurement meaning; supporting estimates are not acceptance, permission or fabricated counterfactual labels. |
-| Learned allocation | A learned policy beats the qualified current-model policy under matched full budgets and transfer tests. | Replace the policy implementation behind the same work decision boundary; Core retains admission, budget, identity and settlement. |
+| Current-model pilot (Phase 1 entry) | A revision-pinned bounded planning treatment changes actual work and improves the §8.7 comparison. | Existing Stride/Yardstick/Explore owners and ordinary responses; no second controller session or numerical fidelity engine prerequisite. |
+| Calibrated estimates (Phase 1 non-parametric meta-policy) | Pre-action predictions linked to actual method, duration, next state and terminal result improve forecast/calibration on held-out episodes. | The domain provider owns measurement meaning; supporting estimates are not acceptance, permission or fabricated counterfactual labels. |
+| Learned allocation (Phase 2 gated upgrade) | A learned policy beats the qualified Phase 1 frozen-model policy under matched full budgets and transfer tests. | Replace the policy implementation behind the same work decision boundary; Core retains admission, budget, identity and settlement. |
Record state and evidence as they were available at decision time, action and
actual method, resource use, next observation/state, and later outcomes through
@@ -632,6 +661,71 @@ Ordinary current-work evidence also keeps its original commit chronology and
canonical-prefix boundary; a late old delivery cannot become a newer decision's
uncited evidence. Explicitly cited verified history remains available.
+#### Upward model–harness co-design: joint `{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}` two-phase roadmap (proposed)
+
+To align context economics with research-horizon decisions without splitting
+ownership, upward co-design unifies the downward receipt-gated sampling-stack
+primitives (`{KeepRaw, FoldToReceipt, EpochReset}` in
+[History working sets §5.1](history-working-set-context-policy-v0.md#51-one-projection-owner))
+and research stride actions (`{grow, switch, verify}`) over the same typed
+`control_plane/work_items` decision boundary. Deterministic kernel guards reject
+illegal cross-layer combinations (for example, `FoldToReceipt` on an unverified
+active probe before settlement/verification receipt or silent mid-epoch prefix
+mutation). All co-design policy mechanisms below hold `Proposal` maturity,
+default off, and add no runtime/training loop to M1.
+
+1. **Phase 1 — Frozen-Model Non-Parametric Meta-Policy:** operates strictly
+ with frozen base-model weights while logging assignment probabilities and
+ receipts for counterfactual attribution:
+ - **`KL-UCB` arm selection:** selects among discrete `(target–yardstick,
+ stride, context-stack)` arms using bounded KL-upper-confidence indices over
+ matched counterfactual value estimates, respecting horizon-$B$
+ confirmation back-scheduling and multi-evidence Yardstick fidelity (`§5.4`,
+ `§5.8`).
+ - **Bounded batch-barrier `add / revise / retire` memory evolution:**
+ updates procedural/episodic guidance only at explicit batch barriers
+ (never mutating active intra-epoch prefixes), restricted to typed
+ `add` (verified new insight), `revise` (narrowed scope/counterevidence),
+ and `retire` (superseded or invalidated guidance) gated by
+ [post-outcome memory utility](post-outcome-memory-utility-attribution-v0.md).
+ - **Semantic Duplicate Gate:** normalizes action, probe, and gate
+ fingerprints (`actor + target/operation + resource/scope_key +
+ boundary_rules`) before admitting new candidates or user prompts, reusing
+ active incumbents, prior grants, or existing evidence trails rather than
+ spawning redundant probes or duplicate Todos.
+ - **Protected control and root-cause guards:** deterministic kernel checks
+ protect verified incumbents (`proxy_order_reversed` and suspect fences),
+ forbid `FoldToReceipt` promotion without independent deterministic
+ receipts, keep proxy gains strictly distinct from authoritative acceptance,
+ and enforce root-cause certification (requiring failing-to-passing or
+ differential invariant proof rather than test-relaxation shortcuts).
+2. **Phase 2 — Checkpoint-Forked `Segment Flow-GRPO`:** entered only after Phase
+ 1 establishes a calibrated baseline and matched-budget evidence motivates a
+ learned allocator:
+ - **Avoids offline SFT collapse and linear credit-assignment decay:**
+ instead of offline behavioral cloning on static logs—which collapses under
+ compounding distribution shift as documented in
+ [AgentFlow](https://arxiv.org/abs/2510.05592)—or sparse outcome-only RL
+ over entire multi-hundred-turn trajectories, Phase 2 optimizes in-the-loop
+ over bounded **single-stride segments ($\Delta T$)** aligned with `KeepRaw` /
+ `EpochReset` boundaries.
+ - **Checkpoint-forked $\Delta T$ rollouts over $O(1)$ deterministic state
+ projections:** branches matched sibling continuations directly from
+ quiescent deterministic checkpoints (`AuthorityStore` + `decision_capture`
+ + frozen prefix state) using $O(1)$ deterministic projections of the active
+ Goal/Todo/incumbent/budget/yardstick frontier rather than replaying full
+ raw logs. Computes group-relative segment advantages (`Segment Flow-GRPO`)
+ across verified sibling rollouts sharing checkpoint $s$
+ ([HELIX](https://arxiv.org/abs/2608.13951); [Research §6.2](long-horizon-harness-benchmark-research-program-v0.md#62-efficiency)),
+ while preserving potential-based objective alignment (`[E7]`) and keeping
+ admission, budgets, and authoritative grading outside the learner's write
+ access.
+ - **Promotion gate:** Phase 2 remains research-only (`default-off`) and may
+ replace the Phase 1 policy behind the same Core boundary only after beating
+ the qualified Phase 1 meta-policy on held-out tasks under complete-cost
+ accounting ($\Delta J(B \mid s_0) > 0$, including cached vs. uncached prefix
+ tokens and checkpoint/evaluation compute).
+
## 6. Alternatives and design choices
| Alternative | Decision / trade-off |
@@ -795,6 +889,11 @@ capability. Disabling removes the extra ordinary-Turn cue and rejects new
captures before primary commit, while historical findings and successful exact
replays remain readable.
+An Explore context read loads the Yardstick projector when the graph is
+available and the setting is enabled. Ordinary C1 reads use the shared
+guidance and exact references for the captured context. Prior decisions stay
+bound to their original source when selected or replayed.
+
The existing Research finding reader exposes the recorded target, outcome/proxy
metrics, source, next action and cost bound. The ordinary task-scoped Explore
context projects only that Todo's current target, a short next-choice cue and
@@ -882,6 +981,7 @@ followthrough do not close C13 or M2/M3.
| E6 | [Multi-fidelity Bayesian Optimisation](https://proceedings.mlr.press/v70/kandasamy17a.html), §§1–3 | Distinguishes cheap approximations from the target outcome; GP/fidelity assumptions require qualification for program search. |
| E7 | [Policy invariance under reward transformations](https://people.eecs.berkeley.edu/~russell/papers/icml99-shaping.pdf), §3 | Potential-based shaping preserves the objective under its assumptions; arbitrary milestone bonuses do not. |
| E8 | [EdgeBench adapter contract](../../../benchmark/edgebench/README.md), [feedback and memory analysis](https://loopx-project.github.io/loopx/blog/zh/edgebench-feedback-and-memory/), and §4 source owners | Native protocol, starting-state/continuation distinctions and current M1 seams; motivates the pilot, not a new measured gain. |
+| E9 | [AgentFlow](https://arxiv.org/abs/2510.05592) and [HELIX](https://arxiv.org/abs/2608.13951) | Motivates in-the-loop single-stride `Segment Flow-GRPO` over offline SFT (avoiding distribution collapse) and verified sibling trajectory grouping from shared checkpoints. Author-reported studies; neither implemented nor qualified in LoopX M1. |
The paper's favorable fallback observations do not prove a no-regret guarantee:
failed yardstick construction has already consumed budget. Per-target versus
diff --git a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md
index 8414645063..59952e0a0c 100644
--- a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md
+++ b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md
@@ -41,8 +41,17 @@
Fidelity 是关于组合的证据,不是第四种 Stride 动作。保持原计划合法,
没有变化的 Turn 不必补造 `grow` 记录。方向也可以直接使用权威评测,不配置代理。
-新增普通 Turn 与 yardstick 行为初始显式关闭。现有 Stride 默认值、配置的周期复盘、
-验收、预算和宿主续跑语义保持。本 RFC 不批准自动工具执行、benchmark 协议改动,
+在沿同一 owner 推进的向上模型—Harness 协同设计中(§5.9),本 RFC 将向下的受回执门控
+上下文采样栈原语 `{KeepRaw, FoldToReceipt, EpochReset}`
+(见[历史工作集策略](history-working-set-context-policy-v0.zh-CN.md#51-单一投影-owner))
+与步幅动作 `{grow, switch, verify}` 统一在两阶段策略演进路线中:**Phase 1** 采用
+冻结模型非参数元策略(`KL-UCB` arm 选择、有界批屏障 `add/revise/retire` 记忆演化、
+Semantic Duplicate Gate 及受保护控制/根因守卫);只有在匹配预算证据支持转向学习型
+预算分配时,才进入 **Phase 2** Checkpoint-Forked `Segment Flow-GRPO`(基于 $O(1)$
+确定性状态投影的 $\Delta T$ 单步幅 rollout)。
+
+新增普通 Turn、yardstick 与向上协同设计行为初始显式关闭。现有 Stride 默认值、配置的周期复盘、
+验收、预算和宿主续跑语义保持。本 RFC 不批准自动工具执行、benchmark 协议改动、学习型策略部署,
也不允许 Agent 自行改变验收。
## 2. 问题与动机
@@ -63,6 +72,16 @@ fidelity 检查比例分别为 58% / 21%,kernel 为 73% / 33%;尺子成本
比例分别为 4% / 29% 和 2% / 18%。这是论文结果,且 target/task 的分母不同,
不能作为 LoopX 收益预测。
+联合研究决策同样直接耦合上下文保留与长程学习稳定性:在确定性回执生成前就过早折叠探索过程,
+会丢弃 `verify` 或 `switch` 所需的反面证据;反之,无边界保留原文或在 epoch 中途改写前缀,
+则会侵蚀剩余预算 $B$ 并破坏前缀 KV-cache 复用(见[历史工作集策略 §5.1](history-working-set-context-policy-v0.zh-CN.md#51-单一投影-owner))。
+在策略学习层面,[AgentFlow](https://arxiv.org/abs/2510.05592) 表明静态轨迹上的离线监督微调
+(SFT)在长程分布偏移下会出现分布坍缩,而在线闭环分片优化(`Flow-GRPO`)可保持工具反馈探索;
+朴素纯终局多轮强化学习则会沿百轮轨迹出现线性信用分配衰减,而 [HELIX](https://arxiv.org/abs/2608.13951)
+则证明从同一状态分叉的已验证兄弟轨迹组可在不混淆起点的前提下分离真实因果收益。这些证据共同驱动
+我们在同一类型化 owner 后构建 `{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}`
+的两阶段演进路线(§5.9)。
+
### 不变量
1. 任务验收和权威评测仍由原 owner 决定。代理可以引导搜索,不能证明收益已获验收。
@@ -425,9 +444,9 @@ Bellman 表达式不会提供状态转移模型;事后峰值不能成为决策
| 阶段 | 下一项有用结果 | 保留的边界 |
| --- | --- | --- |
-| 当前模型试验 | 固定版本的有界规划策略改变实际工作,并改善 §8.7 对照结果。 | 沿用 Stride/Yardstick/Explore owner 和普通响应;不以第二个 controller session 或数值 fidelity 引擎为前置。 |
-| 校准预期 | 将事前预测关联实际方法、耗时、后继状态与终局结果,在留出 episode 上改善预测/校准。 | 领域 provider 负责测量含义;估计不是验收、权限或编造的反事实标签。 |
-| 学习预算分配 | 学习型策略在匹配完整预算和迁移测试中胜过已资格确认的当前模型策略。 | 在同一工作决策边界替换策略实现;Core 保留准入、预算、身份与结算。 |
+| 当前模型试验(Phase 1 入口) | 固定版本的有界规划策略改变实际工作,并改善 §8.7 对照结果。 | 沿用 Stride/Yardstick/Explore owner 和普通响应;不以第二个 controller session 或数值 fidelity 引擎为前置。 |
+| 校准预期(Phase 1 非参数元策略) | 将事前预测关联实际方法、耗时、后继状态与终局结果,在留出 episode 上改善预测/校准。 | 领域 provider 负责测量含义;估计不是验收、权限或编造的反事实标签。 |
+| 学习预算分配(Phase 2 门控升级) | 学习型策略在匹配完整预算和迁移测试中胜过已资格确认的 Phase 1 冻结模型策略。 | 在同一工作决策边界替换策略实现;Core 保留准入、预算、身份与结算。 |
通过已有 provenance/followthrough 记录决策当时可见的状态与证据、选择和实际方法、
资源消耗、后继观察/状态及后续成果。已选动作日志可以训练预测,却不揭示未选动作的结果。
@@ -463,6 +482,46 @@ profile 保留真实 workload revision 与 evaluator。既有 typed 比较 owner
普通 current-work 证据还保留原提交时间与 canonical prefix 边界;旧记录延迟写入
不能变成新 decision 的未引用证据,已显式引用并验证的历史仍可使用。
+#### 向上模型—Harness 协同设计:`{KeepRaw, FoldToReceipt, EpochReset} × {grow, switch, verify}` 两阶段演进路线(提案)
+
+为使上下文经济学与研究期限决策保持同一归属,向上协同设计在同一类型化 `control_plane/work_items`
+决策边界之上统一向下的受回执门控采样栈原语([历史工作集策略 §5.1](history-working-set-context-policy-v0.zh-CN.md#51-单一投影-owner)
+中的 `{KeepRaw, FoldToReceipt, EpochReset}`)与研究步幅动作(`{grow, switch, verify}`)。
+确定性内核守卫会拒绝跨层非法组合(例如在未形成结算/验证回执前对活跃未验证探针执行
+`FoldToReceipt`,或静默在 epoch 中途改写前缀)。以下协同策略机制均保持 `Proposal` 成熟度并默认关闭,
+不向 M1 增加运行时或训练循环:
+
+1. **Phase 1 — 冻结模型非参数元策略(Frozen-Model Non-Parametric Meta-Policy):**
+ 严格保持基座模型权重冻结,同时为反事实归因记录动作分配概率与回执:
+ - **`KL-UCB` arm 选择:** 基于匹配的同状态反事实价值估计与 KL 上置信界指标,在离散的
+ `(target–yardstick, stride, context-stack)` arm 之间选择,遵守从总预算 $B$ 倒排的确认窗口
+ 与多证据 Yardstick 保真度约束(§5.4、§5.8)。
+ - **有界批屏障 `add / revise / retire` 记忆演化:** 仅在显式批屏障处更新过程性/情景性经验
+ (不改动当前 epoch 内活跃前缀),且严格限定为类型化的 `add`(经核验的新洞见)、`revise`
+ (收窄适用范围或补充反证)与 `retire`(已被替代或失效的经验),并受
+ [结果后记忆效用归因](post-outcome-memory-utility-attribution-v0.zh-CN.md)门控。
+ - **Semantic Duplicate Gate:** 在准入新候选探针或人工提示前规范化动作/探针/门禁指纹
+ (`actor + target/operation + resource/scope_key + boundary_rules`),优先复用现役
+ incumbent、既有授权或已有证据链,防止重复发起等价探针或冗余 Todo。
+ - **受保护控制与根因守卫:** 确定性内核检查强制保护已验证 incumbent(`proxy_order_reversed`
+ 与 suspect 围栏),禁止无独立确定性回执的 `FoldToReceipt` 晋升,严格分离局部代理涨分与
+ 权威终局验收,并执行根因认证守卫(要求失败到通过或差分不变量证明,禁止通过放松测试或硬编码走捷径)。
+2. **Phase 2 — Checkpoint-Forked `Segment Flow-GRPO`:** 仅在 Phase 1 建立经校准的基线、且匹配预算下的证据
+ 证明需要转向学习型分配器后才可进入:
+ - **规避离线 SFT 坍缩与线性信用分配衰减:** 不在静态日志上做离线行为克隆(如
+ [AgentFlow](https://arxiv.org/abs/2510.05592) 所示,离线 SFT 在分布偏移下会发生坍缩),
+ 也不对数百轮完整轨迹做稀疏终局 RL(信用分配随长度线性衰减);Phase 2 围绕与
+ `KeepRaw` / `EpochReset` 边界对齐的有界**单步幅片段($\Delta T$)**执行在环(in-the-loop)优化。
+ - **基于 $O(1)$ 确定性状态投影的 Checkpoint 分叉 $\Delta T$ rollout:** 直接从静默确定性
+ checkpoint(`AuthorityStore` + `decision_capture` + 冻结前缀状态)分叉出匹配的兄弟接续,
+ 通过当前 Goal/Todo/incumbent/预算/yardstick 前沿的 $O(1)$ 确定性状态投影启动,而不重放冗长原始日志;
+ 在共享同一 checkpoint $s$ 的已验证兄弟 rollout 组内计算相对优势(`Segment Flow-GRPO`,参考
+ [HELIX](https://arxiv.org/abs/2608.13951) 兄弟轨迹分组与[研究计划 §6.2](long-horizon-harness-benchmark-research-program-v0.zh-CN.md#62-效率)),
+ 同时保持势函数目标一致性(`[E7]`),并将准入、预算与权威评分留在学习器写边界之外。
+ - **晋升门禁:** Phase 2 保持研究态(默认关闭),唯有在完整成本记账下($\Delta J(B \mid s_0) > 0$,
+ 含 cached 与 uncached 前缀 token 及 checkpoint/评测计算成本)于留出任务上超越已资格化的 Phase 1
+ 元策略后,方可在同一 Core 边界下替换策略实现。
+
## 6. 替代方案与设计选择
| 方案 | 选择 / 取舍 |
@@ -596,6 +655,9 @@ Explore evidence 可用;开启该设置不启动工作或自动开启其他 ca
关闭后移除普通 Turn 的新增提示,并在主提交前拒绝新 capture;历史 finding
及成功的精确重放仍可读。
+Explore 读取在图可用且设置已开启时加载 Yardstick 投影。普通 C1 使用共享指引和
+精确引用读取捕获的上下文。选中或重放既有决策时仍绑定原始来源。
+
既有 Research finding reader 展示记录的目标、成果/代理指标、来源、下一步和成本边界。
普通 task-scoped Explore context 只投影该 Todo 当前目标、下一选择短提示和反证引用。
既有 question-scoped 扩读命令返回完整决策、精确 profile 的反馈和前次执行归属;
@@ -662,6 +724,7 @@ fence。普通主提交已经成功的附件恢复,继续遵守原有延迟交
| E6 | [Multi-fidelity Bayesian Optimisation](https://proceedings.mlr.press/v70/kandasamy17a.html),§§1–3 | 区分廉价近似与目标结果;GP/fidelity 假设用于程序搜索前需要验证。 |
| E7 | [Policy invariance under reward transformations](https://people.eecs.berkeley.edu/~russell/papers/icml99-shaping.pdf),§3 | 势函数 shaping 在其假设下保持目标;任意里程碑奖励没有这个保证。 |
| E8 | [EdgeBench 适配器契约](../../../benchmark/edgebench/README.md)、[反馈与记忆分析](https://loopx-project.github.io/loopx/blog/zh/edgebench-feedback-and-memory/)及第 4 节源码 owner | Native 协议、起点/接续的区分与当前 M1 接缝;说明 pilot 的动机,不是新的实测收益。 |
+| E9 | [AgentFlow](https://arxiv.org/abs/2510.05592) 与 [HELIX](https://arxiv.org/abs/2608.13951) | 为以在环单步幅 `Segment Flow-GRPO` 替代离线 SFT(避免分布坍缩)及从共享 checkpoint 分叉已验证兄弟轨迹分组提供研究动机。均为作者报告结果;未在 LoopX M1 中实现或取得资格。 |
论文中回退的有利观测不代表无后悔保证:失败造尺子已经消耗预算。
每 target 与每 task 的通过率单位不同;候选选择和重复 fidelity 检验限制统计解释。
diff --git a/docs/book/chapters/00-reading-guide.md b/docs/book/chapters/00-reading-guide.md
index 37a69cff4f..8481409fb5 100644
--- a/docs/book/chapters/00-reading-guide.md
+++ b/docs/book/chapters/00-reading-guide.md
@@ -91,7 +91,7 @@ T1 的一次写回可留下回执 R1,但它不自动关闭 G1 或接受整个
[选择正确的放置位置](./08-extension-placement.md)。
项目接入与开发者贡献共享基础模型,但没有先后依赖。Extension 是开发者贡献中的一种交付和
-lifecycle 选择,不是所有贡献的默认终点。
+lifecycle 选择。
## 这本书的主线
@@ -120,7 +120,7 @@ lifecycle 选择,不是所有贡献的默认终点。
概念章解释因果和设计取舍;实践章给出前提、动作、读回和失败出口;贡献章沿协议与实现寻找
第一处需要改变的边界。它们不必都写成同一张四列表,但不能把关键推理留给读者猜。
-状态机专题和附录供回查,不是要求第一次接入前全部背完的考试范围。
+状态机专题和附录供回查。
[项目接入章](05-connect-existing-project.md#three-completions)区分安装、接入与工作交付,
其[第一份交付](05-connect-existing-project.md#first-delivery)把 T1/T2、CI、决定与最终返回接在一起。
@@ -149,7 +149,7 @@ lifecycle 选择,不是所有贡献的默认终点。
这四问是教学与修订标准,不新增 schema、运行时义务或审批门禁。资料不足时,应明确
“尚不能判断什么、缺少哪项证据、由谁确认”;不能为了填满四格而猜测。
-拒绝也不是最终目标:条件补齐后要重新判断,保留已经发生的工作,并走向下一次合法行动。
+条件补齐后要重新判断,保留已经发生的工作,并走向下一次合法行动。
## 怎样理解书中的证据
@@ -221,7 +221,7 @@ node --version
为进展单位,不继续堆 leaf helper 与 bridge。
核对这一历史里程碑时,以 `v0.5.4` tag 和 release notes 为准。历史记录中的
-Stage 3/Stage 4 是阶段边界,不是当前支持矩阵;后续 cutover 与 CLI/App 收敛以
+Stage 3/Stage 4 是阶段边界;后续 cutover 与 CLI/App 收敛以
[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)
的当前状态为准。`v0.5.4` 只交付了 Stage 3 的第一个 receipt-bound scheduler follow-up 切片;更广的
CLI/App convergence 与 Stage 4 distribution cleanup 仍是后续方向。
@@ -238,13 +238,12 @@ CLI/App convergence 与 Stage 4 distribution cleanup 仍是后续方向。
| Capability / Provider | Capability 由 package-owned catalog entry、真实 command 和 durable validation 共同定义;Provider/Extension 不继承 Kernel authority | [Capability Catalog](/loopx/docs/capabilities/) |
| Shared authority | file、NoKV 与 PostgreSQL provider 仍是 staged candidate;安装 Provider 不会改变默认本地 authority | [Shared Authority RFC](/loopx/docs/architecture/rfcs/shared-goal-authority-state-provider-v0/) |
-这张表是阅读导航,不是 release notes 的副本。某个 surface 是否可用,仍应从当前安装版本的
+这张表是阅读导航。某个 surface 是否可用,仍应从当前安装版本的
`doctor`、`capability show`、对应 Host readback 和 versioned 文档判断。
### 从 `v0.5.4` 进入 `v1.0.0` Workspace
-`v1.0.0` 的产品里程碑是 Personal Workspace,而不是一次对所有 staged authority 或可选 Provider
-的整体提升。它把跨 Goal 总览、Agent lane、已完成任务、Capability 设置、verified reports、
+`v1.0.0` 的产品里程碑是 Personal Workspace。它把跨 Goal 总览、Agent lane、已完成任务、Capability 设置、verified reports、
Goal Channel 与桌面恢复汇集到一个 operator surface,同时保留 CLI、typed Kernel 与项目状态的
事实所有权。沿[1.0 Workspace 操作章](./workspace-v1.md)完成启动、readback、preview/apply/receipt、
配置与停用验收,再进入项目接入或开发者贡献主线。
@@ -260,5 +259,5 @@ live operation 不进入当前主线。需要这些能力时,应回到官方
覆盖面更宽:`loopx/host_loop_activation.py` 的 `SUPPORTED_AGENT_TYPES` 列出 21 个类型,其中 9 个
另有独立的 goal-mode 适配包(`claude_goal_mode`、`kunluncode_goal_mode`、`opencode_goal_mode`、
`pi_goal_mode`、`zcode_goal_mode`、`agy_goal_mode`、`dsh_goal_mode`、`kiro_cli_goal_mode` 等)。
-路线选择是教学取舍,不是能力边界:其余 harness 的接入差异,以各自适配包和
+路线选择是教学取舍:其余 harness 的接入差异,以各自适配包和
[协议文档](/loopx/docs/reference/protocols/) 为准。
diff --git a/docs/book/chapters/01-from-session-to-loop.md b/docs/book/chapters/01-from-session-to-loop.md
index 11065ba92a..cf319c361b 100644
--- a/docs/book/chapters/01-from-session-to-loop.md
+++ b/docs/book/chapters/01-from-session-to-loop.md
@@ -1,7 +1,5 @@
# 从一次会话到长程任务
-一个 Agent 能在当前会话里改代码、跑测试、解释结果,不代表它能可靠地拥有一项持续数天的工作。本章说明这个差别从哪里来,以及它为什么需要一个不在会话里的东西。
-
## 一个看起来很顺利的开头
假设你要给已有 CLI 增加 `--format json`:
@@ -56,7 +54,7 @@
| 哪个 Agent 拥有当前任务 | 重启或交接后,所有权无法从记忆里恢复 |
| 外部世界的当前状态 | 昨天读到的 CI 状态今天可能已经变了 |
-Host 可以持久保存 transcript,但旧对话本身不提供当前权限、验收或恢复状态。判据是接手者能否从明确的事实源重新核对这些信息,而不依赖原会话的隐含理解。
+判据是接手者能否从明确的事实源重新核对这些信息,而不依赖原会话的隐含理解。
## 执行面与控制面
@@ -76,7 +74,7 @@ Observation / receipt: 返回可验证结果
Control plane: 接受、拒绝或重规划
```
-**控制面不替代执行面。** LoopX 不写代码、不托管 Git、也不代替 CI。它让这些系统的结果能被一个跨 Turn 的工作生命周期消费——这正是 10:17 之后缺的那一环。
+它让这些系统的结果能被一个跨 Turn 的工作生命周期消费——这正是 10:17 之后缺的那一环。
## 三类长程任务为什么能共用同一控制面
@@ -100,7 +98,7 @@ LoopX 的控制合同不绑定某一种业务流程。仓库里的 Control-Plane
→ 重新计算 continue | wait | ask | replan | repair | terminal
```
-复用的是**生命周期不变量**,而非一段通用 prompt。Issue-Fix 理解 `CHANGES_REQUESTED`,Auto ML 理解 matched baseline,Auto Research 理解 holdout——这些领域含义属于 Capability 与 Domain State。而谁能 claim、是否可执行、何时再次唤醒、什么证据允许 writeback、Goal 能否终止,由同一套 Kernel 合同决定。
+复用的是**生命周期不变量**。Issue-Fix 理解 `CHANGES_REQUESTED`,Auto ML 理解 matched baseline,Auto Research 理解 holdout——这些领域含义属于 Capability 与 Domain State。而谁能 claim、是否可执行、何时再次唤醒、什么证据允许 writeback、Goal 能否终止,由同一套 Kernel 合同决定。
这条边界也解释了为什么新增领域能力不该复制一套 runner、queue、retry 和 completion 状态机。领域层提供可判定事实与 proposal,Provider 执行外部调用,Kernel 拥有跨领域生命周期。
@@ -108,7 +106,7 @@ LoopX 的控制合同不绑定某一种业务流程。仓库里的 Control-Plane
## 最小外置状态长什么样
-对上面的贯穿任务,最小状态不是完整 transcript,而是一组能回答恢复问题的事实:
+对上面的贯穿任务,最小状态是一组能回答恢复问题的事实:
```yaml
# 为解释而简化,不是 LoopX 文件格式
@@ -127,7 +125,7 @@ next_wake:
when: maintainer decision arrives
```
-这些字段的价值在于:**下一位执行者不必相信上一位 Agent 的自述**,而能从目标、工作队列、Gate、证据和 fresh environment 重新判断下一步。示例是解释模型,不是 LoopX 的存储格式。
+这些字段的价值在于:**下一位执行者不必相信上一位 Agent 的自述**,而能从目标、工作队列、Gate、证据和 fresh environment 重新判断下一步。示例是解释模型。
## 代价与边界:什么被放弃了
@@ -147,9 +145,9 @@ next_wake:
## 不变式
-1. **Prompt 内容不能独自证明持久写回。** 检查可寻址的记录、身份和版本,而不是窗口是否还开着。
+1. **Prompt 内容不能独自证明持久写回。** 检查可寻址的记录、身份和版本。
2. **执行面与控制面不能互相替代。** 控制面不写代码,执行面不决定自己是否合法。
-3. **复用的是生命周期不变量,不是 prompt。** 三个不同领域能共用一套控制面,靠的是这条。
+3. **复用的是生命周期不变量。** 三个不同领域能共用一套控制面,靠的是这条。
4. **下一位执行者不需要相信前一位的自述。** 如果需要,说明外置得不够。
接下来用[会话、Host Goal 与 LoopX](02-session-goal-loopx.md)判断任务需要哪层状态,再读[四个要求](02b-long-horizon-requirements.md),把这些问题组织成完整的架构视角。
diff --git a/docs/book/chapters/02-session-goal-loopx.md b/docs/book/chapters/02-session-goal-loopx.md
index 3ec5625b16..3038fc5ce8 100644
--- a/docs/book/chapters/02-session-goal-loopx.md
+++ b/docs/book/chapters/02-session-goal-loopx.md
@@ -78,9 +78,8 @@ Host 可以保存会话 transcript,也可以保存 native Goal 的 objective
| Executor / Agent | 当前 Turn 的推理、工具调用、bounded delivery 与验证 | 隐式长期记忆和越权批准 |
| LoopX control plane | Goal、Todo、Gate、quota、evidence lineage、recovery protocol | 模型推理、Git/CI 外部事实 |
-Dashboard、review packet 和 prompt 是 projection/interaction surfaces,不构成第五个
-authority。上一节说的"唤醒表面"就落在 Host 这一行:能不能把一个问题送到人面前,取决于
-Host 提供了什么,而不是取决于控制面写了什么。
+Dashboard、review packet 和 prompt 是 projection/interaction surfaces。上一节说的"唤醒表面"就落在 Host 这一行:能不能把一个问题送到人面前,取决于
+Host 提供了什么。
## 三种身份必须分开
@@ -92,7 +91,7 @@ LoopX 同时处理 Goal、Agent 和 Host,但三者回答的是不同问题:
| `agent_id` | 当前由哪个 peer/lane 承担工作? | 绑定 claim、Vision、quota 与 writeback;只有不存在已注册 lane 或显式 `--new-peer` 时新接入才默认注册 fresh identity |
| `host_surface` / runtime profile | 这一轮实际由哪个产品表面执行和唤醒? | 绑定 App heartbeat、visible Goal 或其他 host loop;必须按当前运行面显式声明 |
-已有 Goal 可以继续复用,不代表新 session 应接管已有 Agent identity。最新 Goal-start 合同要求:
+最新 Goal-start 合同要求:
1. 多个已注册 Goal 同时存在时,先返回只读 `goal_selection_gate`,再以精确 `--goal-id` 重跑;
2. 不根据相似的 objective、聊天摘要或目录名猜测 Goal;
@@ -103,15 +102,15 @@ LoopX 同时处理 Goal、Agent 和 Host,但三者回答的是不同问题:
才默认注册 fresh identity:`start-goal` 返回 `fresh_agent_registration_required`
(`register_fresh_agent`),首次接入无需额外 `--new-peer`;已绑定的 thread 沿用其绑定的 lane;
5. 只有用户明确要求接管某个已有 Agent,才以该精确 `agent_id` 继续;
-6. Agent 名称或前缀不证明 Host,实际运行面要由 host/runtime metadata 说明。
+6. 实际运行面要由 host/runtime metadata 说明。
这样,"继续同一个项目"与"冒充上一个执行者"不会被压成同一操作。
## 任务资格卡:先判断是否值得使用 LoopX
-LoopX 不是"任务越大越应该用"的同义词。先把任务写成一张可审查的资格卡:
+先把任务写成一张可审查的资格卡:
-这张卡是本书提供的决策工具,不是 LoopX CLI schema,也不会被 `start-goal` 自动写入状态。
+这张卡是本书提供的决策工具。
真正进入 LoopX 的 Goal、Todo、Gate、acceptance 和 boundary 仍以当前协议与 CLI 为准。
| 字段 | 要回答的问题 | 不满足时的默认选择 |
@@ -126,9 +125,9 @@ LoopX 不是"任务越大越应该用"的同义词。先把任务写成一张可
前四个字段直接对应第二段故事里的失败:`external_wait` 为真,说明这个任务会停在等待上;
`authority` 为真,说明这个等待必须由人给出决定。两项都满足时,"谁来唤醒那个人"就成了
-启动前必须回答的问题,而不是运行一段时间之后才发现的缺口。
+启动前必须回答的问题。
-满足一项不代表必须使用 LoopX。真正有价值的组合通常是:跨 session + 有外部等待或 handoff +
+真正有价值的组合通常是:跨 session + 有外部等待或 handoff +
有独立 acceptance,并且项目需要把 authority、evidence 和恢复条件外置。
### 如何比较普通会话、Goal 与 LoopX
@@ -211,10 +210,9 @@ Gate G
Goal 表达项目结果,Todo 表达可调度的工作单元。LoopX 可以为 Todo 记录优先级、依赖、claim、
lease、successor 和 handoff。Per-Agent Vision 则保存某个 peer 当前的 bounded role direction、
-acceptance summary 与 replan trigger;它是 per-Agent 的路线,也不是全局产品愿景。
+acceptance summary 与 replan trigger;它是 per-Agent 的路线。
-这使"目标仍 active"与"当前谁可以做哪件事"成为两个问题。Agent id 是工作身份,不证明 Host
-身份;`codex-*` 前缀也不能证明任务实际运行在 Codex App 还是 CLI。新 session 可以复用同一
+这使"目标仍 active"与"当前谁可以做哪件事"成为两个问题。Agent id 是工作身份。新 session 可以复用同一
Goal 的历史与 frontier,并在没有已注册 lane 或显式 `--new-peer` 时以 fresh Agent identity 进入;
已有 claim 则通过显式 takeover 或 handoff 处理。
@@ -260,7 +258,7 @@ Host 仍然拥有实际唤醒机制。LoopX 输出调度合同,不假装自己
### 5. 跨 Agent、跨 Host 与恢复
LoopX 的 canonical state 属于项目。Codex App、Codex CLI 或其他受支持 Host 可以读取同一个
-Goal 边界,而不是各自维护一份"当前进度"。
+Goal 边界。
```text
Codex App heartbeat ─┐
@@ -289,8 +287,7 @@ LoopX 保留同一 control-plane contract,但不同 Host 的启动和唤醒机
| DeepSeek Harness | native skill + same-session Driver / `loopx turn run-once` | 每段 bounded execution 仍需独立 validation |
| Shell / other Agent | guided packet + caller-owned runner | 无 runner hook 时由调用方唤醒 |
-这张表就是资格卡第二个维度的数据来源。表中出现一个 Host 不代表所有 Host 都支持相同
-automation API。`host_surface` 未知时,应省略一次该参数并使用只读 selection Gate;不要把
+这张表就是资格卡第二个维度的数据来源。`host_surface` 未知时,应省略一次该参数并使用只读 selection Gate;不要把
Codex CLI、IDE plugin、App SSH 或普通 shell 猜成 Codex App heartbeat。完整表面、启动方式、
停止策略和验证证据以 Runtime Connector Catalog 与对应 Host 文档为准;Dev Book 不复制每个
adapter 的完整 runbook。
@@ -311,8 +308,7 @@ LoopX control plane -> Codex Goal continuation -> Agent Turn
`---------- validated writeback -------'
```
-因此,Codex Goal 与 LoopX 的关系更像 Host lifecycle 与 project lifecycle 的组合,而不是两套
-互相替代的 Agent runtime。
+因此,Codex Goal 与 LoopX 的关系更像 Host lifecycle 与 project lifecycle 的组合。
## 代价与边界:引入一层状态买到了什么
@@ -337,7 +333,7 @@ evidence lineage。维护成本随任务数量增长,而它换来的是任务
**边界三:Host 表面决定哪些能力真的可用。** 资格卡判定的 `external_wait` 和 `handoff`,
只有在当前 Host 能唤醒、能推送、能回读时才会生效。缺少这些表面的 Host 上,正确的做法是
-缩小任务范围或换一个表面,而不是把任务升级上去期待它自己解决。
+缩小任务范围或换一个表面。
**边界四:控制面只为项目级问题存在。** 没有跨 session、没有外部等待、也没有交接的单次任务,
留在会话里更快。为了"更 Agentic"而制造状态,付出的就是上面的代价一。
@@ -356,7 +352,7 @@ Todo 阻塞得对,控制面每次 tick 都做出正确判断,而那个人从
lane 或显式 `--new-peer` 时以 fresh Agent identity 进入,这是合法路径。若推断出一个相似的 `goal_id`,或者直接接管旧
`agent_id`,得到的就是两个写入者对同一份"当前进度"的假设。
-对应的观察方式是读状态,而不是读 transcript:重启之后控制面还能说出任务停在哪、在等谁,
+对应的观察方式是读状态:重启之后控制面还能说出任务停在哪、在等谁,
以及下一步由谁执行。这三项是判断能否接手的基础,还需结合任务风险与维护成本决定是否值得接入。
## 不变式
diff --git a/docs/book/chapters/02b-long-horizon-requirements.md b/docs/book/chapters/02b-long-horizon-requirements.md
index af21a49c8b..58c587d17e 100644
--- a/docs/book/chapters/02b-long-horizon-requirements.md
+++ b/docs/book/chapters/02b-long-horizon-requirements.md
@@ -15,9 +15,9 @@
## 要求一:状态能脱离当前上下文
-接手者需要知道精确 PR、commit、已经验证的行为和未解决的决定,而不是只读“我刚才修好了”。聊天可以被保存并解释历史,但它的持久性不自动产生结构、新鲜度或当前授权。
+接手者需要知道精确 PR、commit、已经验证的行为和未解决的决定。聊天可以被保存并解释历史,但它的持久性不自动产生结构、新鲜度或当前授权。
-有影响的事实需要可寻址的来源、适用版本与读取入口。代价是维护这些记录;收益是换会话后可以重新判断,而不是凭记忆补齐缺失条件。读[状态章节](state-substrate.md)时,重点检查 source 与 display 在当前模式下分别是什么。
+有影响的事实需要可寻址的来源、适用版本与读取入口。代价是维护这些记录;收益是换会话后可以重新判断。读[状态章节](state-substrate.md)时,重点检查 source 与 display 在当前模式下分别是什么。
## 要求二:保留已知事实,也保留不确定性
@@ -31,13 +31,13 @@
两名 Agent 可以处理不同工作,也可能同时认为同一项工作归自己。Claim 表达责任,适用的 lease/fence 约束当前实例;二者都不能替代 Goal 边界、Gate scope、能力和工作区要求。
-Default legacy、soft claim 和 hard lease 有不同实施边界,不应从一个模式推广出全局独占保证。多 peer 也不意味着全 Goal 只有一个执行者。接管和并行必须落到具体 writer 和当前输入上,见[权限分层](work-graph-and-authority.md#authority-layers)。
+Default legacy、soft claim 和 hard lease 有不同实施边界,不应从一个模式推广出全局独占保证。接管和并行必须落到具体 writer 和当前输入上,见[权限分层](work-graph-and-authority.md#authority-layers)。
## 要求四:预算与观察约束无效重复
预算限制数量,但余额不能独自决定下一轮是否有意义。等待 CI 需要实际读取正确 revision;等待批准需要对应决定;没有可用 Host 的 next due 只是一个时间记录。
-Monitor 保存目标与观察关系;scheduler/backoff 安排后续时机;Host 或已接入事件通道实际执行。退避减少重复读取但可能增加发现延迟;replan 重新判断路线,不是更强的退避。内部 no-spend 不表示模型、工具或网络免费,详见[观察责任](04b-budget-and-admission.md#observation-owners)。
+Monitor 保存目标与观察关系;scheduler/backoff 安排后续时机;Host 或已接入事件通道实际执行。退避减少重复读取但可能增加发现延迟;replan 重新判断路线。内部 no-spend 不表示模型、工具或网络免费,详见[观察责任](04b-budget-and-admission.md#observation-owners)。
## 四条要求怎样协同
@@ -49,13 +49,13 @@ Monitor 保存目标与观察关系;scheduler/backoff 安排后续时机;Hos
→ 重新观察变化,再决定继续、改路或停止
```
-这是教学责任链,不是新的全局 API 顺序。单项机制不能保证目标成功;读者需要理解它们怎样为彼此提供依据,以及哪一种失败应回到哪一个 owner。
+这是教学责任链。单项机制不能保证目标成功;读者需要理解它们怎样为彼此提供依据,以及哪一种失败应回到哪一个 owner。
## 阅读路线与证据
**首次阅读**先进入[完整一轮](03-one-turn.md#running-turn),看 T1 怎样形成可接受结果;再回到[状态](state-substrate.md)和[权限](work-graph-and-authority.md#design-choice),理解支撑这轮工作的事实与写入者;随后读[恢复](04-runtime-boundaries.md)和[观察](04b-budget-and-admission.md)。这与导读中的主线相同,不要求先背状态机枚举。
-**替代路线**适合已有控制面经验的读者:先状态与权限,再读 Turn。状态机专题与附录供回查,不是接入前必须全部完成的课程。
+**替代路线**适合已有控制面经验的读者:先状态与权限,再读 Turn。状态机专题与附录供回查。
| 核对边界 | 协议入口 | 不由它单独证明 |
| --- | --- | --- |
diff --git a/docs/book/chapters/03-one-turn.md b/docs/book/chapters/03-one-turn.md
index 4c5c681897..af1989865d 100644
--- a/docs/book/chapters/03-one-turn.md
+++ b/docs/book/chapters/03-one-turn.md
@@ -1,6 +1,6 @@
# 一轮受治理的工作
-一轮工作的核心不是调用一次模型,而是把当前事实变成有边界的行动,再把结果交给对应 owner 验证和接受。本章先走正常路径,再处理三个容易混淆的情况:产物验证通过但尚未获准发布、已经写回但结算不完整,以及发现依赖后需要让其他工作继续。
+一轮工作的核心是把当前事实变成有边界的行动,再把结果交给对应 owner 验证和接受。本章先走正常路径,再处理三个容易混淆的情况:产物验证通过但尚未获准发布、已经写回但结算不完整,以及发现依赖后需要让其他工作继续。
## 用贯穿任务走完正常一轮 {#running-turn}
@@ -40,7 +40,7 @@ flowchart TD
| 允许向指定对象发布 | G1 | 有权决定者对对象、scope 和条件的明确决定 | 发布动作已经发生 |
| 交付到指定位置或接受者 | T3 | 产物版本、目标位置的实际读回,以及任务要求的接收确认 | 仅创建本地文件就完成了外部投递 |
-这是一张教学推理表,不是新增的验收 schema。当前 objective、acceptance、permissions 和 terminal conditions 分布在项目材料、Vision、Todo 与运行约束中;不能假装已有一个统一可写的 Goal intent 对象自动完成所有判断。实际存储与版本依据见[状态章节](state-substrate.md)和[状态机地图](core-state-machines.md)。
+这是一张教学推理表。当前 objective、acceptance、permissions 和 terminal conditions 分布在项目材料、Vision、Todo 与运行约束中;不能假装已有一个统一可写的 Goal intent 对象自动完成所有判断。实际存储与版本依据见[状态章节](state-substrate.md)和[状态机地图](core-state-machines.md)。
局部证据通过对应 lifecycle 入口被接受,才产生相应工作事实。随后还要检查依赖、未解决的决定、后继与目标验收。若任务只要求返回一份可审阅 patch,不能额外要求真实生产发布;若任务明确要求投递,则本地文件存在不够。**接受条件来自原任务与当前有效决定,不来自执行者为了宣告完成临时降低的标准。**
@@ -60,13 +60,13 @@ flowchart TD
**Decide** 读取当前 `interaction_contract` 和选中工作。旧 prompt、旧卡片或上轮建议不覆盖当前选择。
-**Act** 产生一个输入明确、范围有界、结果连贯的工作段。Bounded 不等于只改一行;一个能独立验证的功能切片比若干无法验收的零碎修改更有用。
+**Act** 产生一个输入明确、范围有界、结果连贯的工作段。一个能独立验证的功能切片比若干无法验收的零碎修改更有用。
**Validate** 检查后置条件:代码要验证行为,文档要核对命令和解释,外部效果需要相应系统的读回,blocker 也需要可核对的缺失条件。退出码只有在验证器确实检查了目标后置条件时才有意义。
**Write back** 由对应 owner 接受状态变化和紧凑证据引用。验证期间代码或 Todo 声明改变时,重新判断结果适用性;不能用针对旧声明的成功覆盖新状态。Todo completion 的锁内 snapshot 检查是其中一个具体边界,参见 [completion adapter](https://github.com/loopx-project/loopx/blob/76b7583a9f67d6090b43a8c6e58c42cb67a1f3c6/loopx/control_plane/todos/completion_transaction.py)。
-**Account** 根据本次结果的结算合同记账。LoopX quota 是内部预算 slot,不是供应商账单。Gate 通知、dry-run、未变化的观察和重复写回不能冒充新的 delivery spend;它们仍可能消耗时间、模型和网络资源。
+**Account** 根据本次结果的结算合同记账。LoopX quota 是内部预算 slot。Gate 通知、dry-run、未变化的观察和重复写回不能冒充新的 delivery spend;它们仍可能消耗时间、模型和网络资源。
缺验证时,不知道产物是否符合要求;缺写回时,后续读者不知道哪些结果被接受;投影滞后时,显示可能还停在旧状态;欠结算时,恢复对应记录而不是重做产物。不同缺口需要不同 owner,不能统一执行一次 `refresh-state` 就宣布全部修好。
@@ -80,7 +80,7 @@ host_execute → typed_result → validation
→ scheduler_apply → scheduler_ack
```
-`completed_phases` 必须满足对应合同的合法前缀约束。它约束可以声称完成的阶段,不证明进程只能在阶段间退出;Host 内部仍可能包含多个工具调用。TurnEnvelope 是 bounded projection,`turn plan` / `turn run-once` 是显式集成入口,不能推广成所有 Host 工具调用都受同一个 journal 管理。
+`completed_phases` 必须满足对应合同的合法前缀约束。它约束可以声称完成的阶段;Host 内部仍可能包含多个工具调用。TurnEnvelope 是 bounded projection,`turn plan` / `turn run-once` 是显式集成入口,不能推广成所有 Host 工具调用都受同一个 journal 管理。
对已 prepared 而未确认的 settlement step,恢复按原 effect identity 读取 provider:
@@ -104,7 +104,7 @@ host_execute → typed_result → validation
恢复后记录完整:settled
```
-在回执修复用例中,执行原响应返回的恢复命令得到 `appended=false`,扣减记录仍为一次。它证明该记录修复路径没有重复扣减,不证明外部服务免费或 Goal 已接受。故障注入只属于隔离测试;不要在真实项目里删除回执来“重现流程”。
+在回执修复用例中,执行原响应返回的恢复命令得到 `appended=false`,扣减记录仍为一次。它证明该记录修复路径没有重复扣减。故障注入只属于隔离测试;不要在真实项目里删除回执来“重现流程”。
从可信当前入口取得 `settlement_owed.command` 后,核对原 Goal、Agent、Todo、Turn 和 registry/runtime 绑定及权限。不要删参数,也不要执行任意日志中出现的命令。详细练习见[结算检查](12-control-plane-course.md#checkpoint-settlement)。
@@ -124,7 +124,7 @@ host_execute → typed_result → validation
该测试使用真实 CLI dispatch、TS 进程和 File/SQLite fixture。它断言同一 Turn 强行改绑得到 `heartbeat_receipt_identity_conflict`;原等待写回重放不重复记录,扣减为零;T1 仍为 open,等待条件未满足且验证摘要保留;新 Turn 才选中替代工作。它没有执行远端 CI,也没有证明每一种 Host 都用相同恢复入口。
-用户在旧版本遇到类似问题时,应保留原身份并查看本机实际提供的恢复动作;不得通过复制测试中的新字段或换 Todo 绕过。判断“是否等待”见[观察章](04b-budget-and-admission.md#wait-and-next-turn),而不是把收口与调度揉成一条规则。
+用户在旧版本遇到类似问题时,应保留原身份并查看本机实际提供的恢复动作;不得通过复制测试中的新字段或换 Todo 绕过。判断“是否等待”见[观察章](04b-budget-and-admission.md#wait-and-next-turn)。
## 尺度二:这一轮为什么获准?
@@ -142,7 +142,7 @@ identity
→ scheduler hint
```
-这是依赖关系的教学图,不是新的全局 first-match 表。实际优先级取决于当前入口和规则 owner。不能由“余额充足”“Goal active”或“另一个 Agent 很忙”推出本轮允许任意交付。
+这是依赖关系的教学图。实际优先级取决于当前入口和规则 owner。不能由“余额充足”“Goal active”或“另一个 Agent 很忙”推出本轮允许任意交付。
身份和来源不明时,不授予交付资格;scope 缺失时不能推断批准;独立工作不应被无关 Gate 冻结;有适用的恢复义务时不能用新交付掩盖原记录缺口。多个条件同时出现,先读最终 contract 与具名 reason,再追到负责的规则,不能让 Host 从零散计数重新拼一个决策。
@@ -154,7 +154,7 @@ identity
| Agent | 当前是否需要尝试工作,允许哪项 bounded action? |
| CLI | 需要哪些受控写回、结算或恢复动作? |
-G1 等待发布批准时,user channel 可以要求行动,agent channel 同时允许独立 T2。反之,“用户已看到提醒”不构成批准。`bounded_delivery`、`user_gate`、`scoped_user_gate_fallback`、`external_evidence_observation`、`monitor_quiet_skip`、`agent_scope_wait`、`autonomous_replan` 和 repair 等 mode 应结合当前 payload 阅读,不背成永远固定的枚举表。
+G1 等待发布批准时,user channel 可以要求行动,agent channel 同时允许独立 T2。`bounded_delivery`、`user_gate`、`scoped_user_gate_fallback`、`external_evidence_observation`、`monitor_quiet_skip`、`agent_scope_wait`、`autonomous_replan` 和 repair 等 mode 应结合当前 payload 阅读,不背成永远固定的枚举表。
Owner 在 Workspace 停止 Goal 属于相应生命周期,不应先由自动 Turn 的 quota 决定 owner 能否行使该权限。暂停也不抹去历史提交;是否允许某项恢复 mutation,仍由那条入口判断。完整组合 case 见 [Course 第 6 讲](/loopx/docs/development/control-plane-course/06-quota-decision-kernel/)。
@@ -162,7 +162,7 @@ Owner 在 Workspace 停止 Goal 属于相应生命周期,不应先由自动 Tu
已迁移的事务由 TypeScript owner 解释,Python 负责适配或明确的外部 effect。已知切片包括 Turn settlement、Todo completion、Host Todo settlement、spend/void/monitor-poll commit、本地 task-lease 完整生命周期、Vision refresh 与 receipt-bound scheduler follow-up。
-`v0.5.4` 仍提供 `turn plan` / `turn run-once`,这是历史迁移基线,不是当前发布版的替代标签,也不意味着“Python 已被移除”。[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)解释 transaction-payoff 与 owner 边界。排查不一致时,找当前合同和实际调用路径,而不是一律相信某一种语言。
+`v0.5.4` 仍提供 `turn plan` / `turn run-once`,这是历史迁移基线。[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)解释 transaction-payoff 与 owner 边界。排查不一致时,找当前合同和实际调用路径。
## 读回与本章的完成标准
diff --git a/docs/book/chapters/04-runtime-boundaries.md b/docs/book/chapters/04-runtime-boundaries.md
index 6b94f8adf6..2b28fe0869 100644
--- a/docs/book/chapters/04-runtime-boundaries.md
+++ b/docs/book/chapters/04-runtime-boundaries.md
@@ -2,7 +2,7 @@
上一章说明一轮怎样留下可接受的结果。本章把时间拉长:会话更换、代码更新、权限撤销、外部请求超时以后,哪些工作可以沿用,哪些判断必须重做,什么时候应改路或停止。
-恢复不是加载一段旧思维,而是重建**当前行动条件**。历史 transcript 可以按 Host 的规则保存并用于理解背景;它不是当前授权、有效验收或外部状态的替代品。恢复历史事实与批准下一次行动,始终是两个问题。
+恢复是重建**当前行动条件**。历史 transcript 可以按 Host 的规则保存并用于理解背景。恢复历史事实与批准下一次行动,始终是两个问题。
## 同一任务:响应丢失之后恢复哪一项 {#receipt-recovery}
@@ -28,7 +28,7 @@ sequenceDiagram
end
```
-图的第一条分支有“R1 确实存在且有效”的前提。只有错误输出而没有 provider 读回时,不能猜自己位于哪条分支。已确认 absent 后是否可以执行,仍取决于当前恢复合同、身份和授权,不是从缺失记录直接得到许可。
+图的第一条分支有“R1 确实存在且有效”的前提。只有错误输出而没有 provider 读回时,不能猜自己位于哪条分支。已确认 absent 后是否可以执行,仍取决于当前恢复合同、身份和授权。
R1 恢复后,继续读取 T3 的当前条件。C1 的提交成功不能验收 C2;T1 的结算也不能替代 G1 对发布的决定。
@@ -74,7 +74,7 @@ G1 是否仍覆盖 C2,取决于原决定绑定的对象和条件;不是所
**Retry / reconcile**:原意图仍成立,但需要确认或完成原操作。只对具有已核对幂等和恢复边界的操作重试;外部结果未知时,优先 reconcile / readback。`unknown` 不是失败的另一种拼写。
-**Replan**:工作含义需要改变,例如新证据推翻方案、验收改变、工作候选耗尽但目标未满足。它应产生当前协议接受的 Todo、Vision、successor、acceptance 关系变化或有据的终止结果,不是再写一遍计划。
+**Replan**:工作含义需要改变,例如新证据推翻方案、验收改变、工作候选耗尽但目标未满足。它应产生当前协议接受的 Todo、Vision、successor、acceptance 关系变化或有据的终止结果。
**Self-Repair**:目标工作可能仍然正确,但来源、投影、路由或回执链存在缺口。先定位 owner,再修具体缺口;不能把删 Gate、降低 validator 或清空历史当成修复。
@@ -82,28 +82,28 @@ Dreaming 产生候选方向或假设,不直接获得执行权。只有被当
## Material Evidence Delta:有活动不等于有进展
-设想一个教学案例:一天里不断改笔记、补无关测试、重排目录,却没有降低目标的任何验收缺口。每项产物可能真实存在,但这不足以说明整体收敛;这也不是声称当前规则会无条件允许无限次同类工作。
+设想一个教学案例:一天里不断改笔记、补无关测试、重排目录,却没有降低目标的任何验收缺口。每项产物可能真实存在,但这不足以说明整体收敛。
-Material Evidence Delta 关注新增的、能改变下一步判断的证据或状态,而不是只数 Turn、文件或字符。负面结果也可能有价值:排除一个假设、确认一个真实 blocker、缩小未知范围,都能改变后续路线。
+Material Evidence Delta 关注新增的、能改变下一步判断的证据或状态。负面结果也可能有价值:排除一个假设、确认一个真实 blocker、缩小未知范围,都能改变后续路线。
Delivery Batch Scale 描述改动范围;Delivery Outcome 描述成果与目标的关系。`multi_surface` 或 `implementation` 不自动意味着完成 Goal。`surface_only`、`outcome_gap`、`outcome_progress`、`primary_goal_outcome` 要按对应合同解释;执行者选择一个好看的标签不能替代证据。
### Vision checkpoint 与 baseline
-Vision 是 per-Agent 的执行路线,不是随手笔记。适用的 material refresh 需要说明路线被 patch、保持不变的依据、retired/superseded 的关系,或该角色为何不需要 Vision。
+Vision 是 per-Agent 的执行路线。适用的 material refresh 需要说明路线被 patch、保持不变的依据、retired/superseded 的关系,或该角色为何不需要 Vision。
-“保持不变”需要可比较的 baseline。没有 baseline 时先建立当前路线;不能把从未检查过写成没有变化。出现 `vision_checkpoint_missing` 等 gap 时,回到负责的 checkpoint 入口,补实际关系,而不是增加愿景 prose。不同 replan/repair 的优先级仍由当前 owner 决定,不把这段教学说明变成所有 Host 的全局规则表。
+“保持不变”需要可比较的 baseline。没有 baseline 时先建立当前路线;不能把从未检查过写成没有变化。出现 `vision_checkpoint_missing` 等 gap 时,回到负责的 checkpoint 入口,补实际关系。不同 replan/repair 的优先级仍由当前 owner 决定,不把这段教学说明变成所有 Host 的全局规则表。
### 六条收敛不变量
这六个问题用于检查完整性,不新增公共字段或一条自动通过算法:
1. **方向**:当前工作如何关联 Goal / Acceptance 与适用的 Vision?
-2. **权限**:正确主体是否在正确对象和 scope 上具有当前资格?能力存在不等于得到授权。
+2. **权限**:正确主体是否在正确对象和 scope 上具有当前资格?
3. **证据**:观察、验证与决定是否绑定正确输入和来源,仍满足新鲜度要求?
4. **Delta**:新增了什么可重读事实,或确认了哪项合法等待?
5. **活性**:未完成目标还有工作、可执行观察、决定、修复或明确停止责任吗?
-6. **终局**:后继、等待、回执与验收缺口是否按适用合同全部处理,而不是只看列表为空?
+6. **终局**:后继、等待、回执与验收缺口是否按适用合同全部处理?
安全避免错误推进,活性避免在缺少下一入口时永久卡住;二者都不保证任意目标必然成功。更多案例见[长程收敛专题](/loopx/docs/development/control-plane-course/topic-long-horizon-convergence/)和[证据与修复课程](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/)。
@@ -118,9 +118,9 @@ Vision 是 per-Agent 的执行路线,不是随手笔记。适用的 material r
→ 读回并重新判断依赖该结果的工作
```
-Legacy Markdown 可能仍是源;已选 canonical provider 的 Todo 不能从旧 Markdown 兜底。若源已提交但显示旧,修投影;若源本身错误,通过原 lifecycle 修正;若读取不可用,保留未知。让几个页面手工显示相同内容,不等于恢复了正确状态。
+Legacy Markdown 可能仍是源;已选 canonical provider 的 Todo 不能从旧 Markdown 兜底。若源已提交但显示旧,修投影;若源本身错误,通过原 lifecycle 修正;若读取不可用,保留未知。
-`refresh-state` 是受控写回,不是所有故障的通用查询。纯查看入口与 mutation 分开,参见[现场查阅](appendix-reference.md#read-before-change)。Workspace 操作回执与页面状态的具体比较见[暂停案例](workspace-v1.md#pause-readback)。
+`refresh-state` 是受控写回。纯查看入口与 mutation 分开,参见[现场查阅](appendix-reference.md#read-before-change)。Workspace 操作回执与页面状态的具体比较见[暂停案例](workspace-v1.md#pause-readback)。
## 停止、闭环与补偿
@@ -128,13 +128,13 @@ Goal 被 owner 停止、quota 暂停或 Host 退出,不能反证目标已完
若当前要求确实满足,按已有终局入口留下依据;若仍需工作,保留后继;若结果未知,保留观察或 blocker。被验证的负向结果和有覆盖依据的 no-follow-up 可以诚实结束一条路径,不需要伪造成功。
-已经生效的错误操作需要补偿,不是删除历史。[Rollback packet 协议](/loopx/docs/reference/protocols/rollback-packet-v0/)帮助表达影响对象、来源、恢复选择、批准与验证,但 packet 不是执行许可。Revert、fix-forward、外部清理和支持请求有不同前提;回滚安装也不必然逆转状态格式或远端效果。
+已经生效的错误操作需要补偿,不是删除历史。[Rollback packet 协议](/loopx/docs/reference/protocols/rollback-packet-v0/)帮助表达影响对象、来源、恢复选择、批准与验证。Revert、fix-forward、外部清理和支持请求有不同前提;回滚安装也不必然逆转状态格式或远端效果。
补偿完成后重新检查真实后置条件,并明确哪些结果仍需接受者确认。内部记录收口、收件人收到产物和整体验收是分开的,参见[第一份交付](05-connect-existing-project.md#first-delivery)。
## 恢复的代价与公开边界
-恢复依赖可读的原记录、可用的 provider 读回与当前权限。缺少它们时可能需要人工或外部支持,不能靠换身份推断问题消失。反复修投影的成本也应成为工程问题,而不是把“系统能自修复”当成持续故障的理由。
+恢复依赖可读的原记录、可用的 provider 读回与当前权限。缺少它们时可能需要人工或外部支持,不能靠换身份推断问题消失。反复修投影的成本也应成为工程问题。
证据采集消耗时间与资源,应与风险匹配;检查太少会漏掉变化,过度重复又可能吞噬交付。正文讨论的是如何保存最小充分证据,不要求把每段思考永久记录下来。
@@ -149,8 +149,7 @@ Goal 被 owner 停止、quota 暂停或 Host 退出,不能反证目标已完
- 写回时用 `--vision-unchanged-reason` 给出“不变”理由;LoopX 会自动把已有 vision 绑定为 baseline,
不需要另外传入 revision。
-如果 baseline 缺失但 agent 仍声称 unchanged,quota 会产生 `vision_checkpoint_missing` gap。这不是
-为了惩罚,而是为了防止 agent 在 never-checked 状态上积累错误假设。完整失败回放见
+如果 baseline 缺失但 agent 仍声称 unchanged,quota 会产生 `vision_checkpoint_missing` gap。为了防止 agent 在 never-checked 状态上积累错误假设。完整失败回放见
[Control-Plane Course 第 8 讲](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/)。
## Terminal Closure
@@ -182,7 +181,7 @@ required external readbacks are fresh
| Capability | 定义 caller outcome,规范 Provider 输出,应用 domain policy |
| LoopX Kernel | 接受或拒绝 proposal,拥有通用 Goal/Todo/Gate/Quota/Recovery state |
-正常流向不是“Agent 调工具后直接写完成”:
+正常流向:
```text
Agent -> Capability -> Provider -> external system
@@ -296,5 +295,5 @@ LoopX 不替代:
Capability/Domain State、Provider、Host/Runner、Projection/Dashboard、Docs/fixtures 或
Extension。
-Extension 是开发者贡献中的独立 packaging/lifecycle 路径,不是所有贡献的统一抽象。两条主线共享
+Extension 是开发者贡献中的独立 packaging/lifecycle 路径。两条主线共享
同一控制面模型,但不互相要求。下一部分先从最常见的项目接入开始。
diff --git a/docs/book/chapters/04b-budget-and-admission.md b/docs/book/chapters/04b-budget-and-admission.md
index ea01234d0f..d6814e0529 100644
--- a/docs/book/chapters/04b-budget-and-admission.md
+++ b/docs/book/chapters/04b-budget-and-admission.md
@@ -1,6 +1,6 @@
# 消耗的上限与外部观察
-T1 完成后,M1 仍在等待 C1 的 CI,G1 仍在等待发布决定。预算还有余额,不代表应该反复调用模型;没有新消息,也不证明外部条件没有变化。本章把“是否行动”“何时再看”“谁去观察”与“何时改路”分开,再让它们共同支持一次可解释的等待。
+T1 完成后,M1 仍在等待 C1 的 CI,G1 仍在等待发布决定。预算还有余额,不代表应该反复调用模型。本章把“是否行动”“何时再看”“谁去观察”与“何时改路”分开,再让它们共同支持一次可解释的等待。
## 先区分五种责任 {#observation-owners}
@@ -16,7 +16,7 @@ T1 完成后,M1 仍在等待 C1 的 CI,G1 仍在等待发布决定。预算
## 一个错误计数策略会怎样误导判断
-以下是**假设性的错误策略**,不是声称当前实现仍有此缺陷:把“最近连续没有变化”只记在一个全局目标上,每次换目标就清零。
+以下是**假设性的错误策略**:把“最近连续没有变化”只记在一个全局目标上,每次换目标就清零。
| 时间 | 到期工作 | 正确的工作项事实 | 假设的错误全局判断 |
| --- | --- | --- | --- |
@@ -25,7 +25,7 @@ T1 完成后,M1 仍在等待 C1 的 CI,G1 仍在等待发布决定。预算
| 11:00 | M1 | M1 第二次无变化 | 又换目标,重新计数 |
| 11:30 | M1、M2 各自到期 | 分别更新自己的观察 | 结果取决于处理顺序,而非目标真正停滞多久 |
-错误不在阈值太高,而在于把不同目标的观察混成了一段历史。修正应保留每个 Monitor 自己的身份和计数,而不是不断降低阈值。相反,假如根本没有可用 Host 去执行 due observation,计数器再正确也只是一份静态记录:这是执行活性缺口,不是 no-change。
+错误不在阈值太高,而在于把不同目标的观察混成了一段历史。修正应保留每个 Monitor 自己的身份和计数。相反,假如根本没有可用 Host 去执行 due observation,计数器再正确也只是一份静态记录:这是执行活性缺口,不是 no-change。
## 等 CI 时,观察频率怎样选择 {#running-wait}
@@ -51,7 +51,7 @@ Monitor 保存调用者完成的观察。本身不访问 CI,`next_due_at` 也
正常交付仍受预算限制:当前窗口 `spent_slots >= allowed_slots` 时会进入相应 throttling。余额不足不能通过换 Todo 或把交付叫作观察绕过;余额充足也不能绕过 Gate、当前身份、能力、工作区和依赖。
-读取最终 contract,至少区分“允许交付”“需要恢复或修复”“观察”“等待”与“要求决定”。身份不明时拒绝交付资格,不等于整个诊断过程不消耗任何资源。`quota should-run --codex-app` 的相关准入路径可能创建 heartbeat receipt,不应当作无副作用的循环查询。现场读取见[附录](appendix-reference.md#read-before-change)。
+读取最终 contract,至少区分“允许交付”“需要恢复或修复”“观察”“等待”与“要求决定”。身份不明时拒绝交付资格。`quota should-run --codex-app` 的相关准入路径可能创建 heartbeat receipt,不应当作无副作用的循环查询。现场读取见[附录](appendix-reference.md#read-before-change)。
内部记账回答已接受的工作如何归因;scheduler cadence change、Gate 通知、dry-run、未变化的 poll、重复写回不能冒充新的 delivery spend。不要用“无费轮次”描述 no-spend,否则会掩盖观察本身的资源成本。
@@ -61,11 +61,11 @@ T1 发现真实依赖时,等待需要有具体对象,例如 `monitor_changed
工作图中存在独立 T2,并不意味着已绑定 T1 的当前 Turn 可以直接改绑。应先完成原 Turn 按其合同要求的等待写回和收口,再由后续准入选择新工作。**Turn 收口、Todo 等待与下轮选择是三件事。**
-[Turn 章的等待时序](03-one-turn.md#wait-closeout)用主线 `f49b4a00…` 的明确测试解释这条路径,并标注了它不属于旧发布版承诺。它验证不重复扣减、不强迫执行 Monitor poll、原 Todo 的等待和验证声明仍保留;不是一条适用于所有 Host 的全局调度顺序。
+[Turn 章的等待时序](03-one-turn.md#wait-closeout)用主线 `f49b4a00…` 的明确测试解释这条路径,并标注了它不属于旧发布版承诺。它验证不重复扣减、不强迫执行 Monitor poll、原 Todo 的等待和验证声明仍保留。
## Cadence backoff 与路线重规划
-Backoff 问的是“相同条件下,多久以后再观察”。它从已仲裁的 decision 和运行 profile 派生调度建议,并按对应 scheduler state 的 identity / `reset_token` 保持或重置退避。具体间隔、上限与 unchanged limit 应读取当前 profile,而不是把一组示例数值当作所有 Host 的共同协议。
+Backoff 问的是“相同条件下,多久以后再观察”。它从已仲裁的 decision 和运行 profile 派生调度建议,并按对应 scheduler state 的 identity / `reset_token` 保持或重置退避。具体间隔、上限与 unchanged limit 应读取当前 profile。
如果没有事件通道,外部变化只能在下一次真实观察后被发现。reset 可以改变后续间隔,但不会追回已经等待的时间。Host apply 成功或已经匹配目标 cadence 后,才按绑定 ACK 路径确认;失败或超时要记录对应失败,不能伪造 ACK。详见[调度入口](appendix-reference.md#scheduler-entry)。
@@ -78,9 +78,9 @@ Replan 问的是“继续等待是否仍符合目标,是否有更好的下一
| 只有 peer 有工作 | 不以 peer 的进展抹掉当前 Agent 的停滞 |
| Monitor 明确为 `watch_only` | 相关测试中即使计数很大,也不因此触发这项 replan |
-[策略测试](https://github.com/loopx-project/loopx/blob/76b7583a9f67d6090b43a8c6e58c42cb67a1f3c6/tests/control_plane/test_monitor_replan_agent_scope.py)中的阈值为 5。这是被测策略,不是所有等待必须改路的普遍定理。测试预置计数后检查 decision;它不证明真实交错 poll、并发计数写入或真实 Host 唤醒。更完整的预测练习见[Monitor 检查](12-control-plane-course.md#checkpoint-monitor)。
+[策略测试](https://github.com/loopx-project/loopx/blob/76b7583a9f67d6090b43a8c6e58c42cb67a1f3c6/tests/control_plane/test_monitor_replan_agent_scope.py)中的阈值为 5。这是被测策略。测试预置计数后检查 decision。更完整的预测练习见[Monitor 检查](12-control-plane-course.md#checkpoint-monitor)。
-因此,replan 不是“更强的 backoff”。一次可以改变观察频率,另一次需要重新判断路线并形成当前协议认可的结果;仅写“重新想过了”不能替代所需的变化或明确终止依据。
+一次可以改变观察频率,另一次需要重新判断路线并形成当前协议认可的结果;仅写“重新想过了”不能替代所需的变化或明确终止依据。
## 怎样定义一项可解释的观察
diff --git a/docs/book/chapters/05-connect-existing-project.md b/docs/book/chapters/05-connect-existing-project.md
index 98a8d63a29..ca905fcd8d 100644
--- a/docs/book/chapters/05-connect-existing-project.md
+++ b/docs/book/chapters/05-connect-existing-project.md
@@ -5,7 +5,7 @@
沿用[贯穿任务](00-reading-guide.md#running-example):A 实现兼容的 JSON 输出 T1,B 补文档 T2,
M1 观察 CI,G1 保留维护者的 schema/发布决定,T3 在条件满足后交付。
-这是合成教学任务,不是已经运行成功的项目记录。命令使用你的真实项目与当前 packet;
+这是合成教学任务。命令使用你的真实项目与当前 packet;
T1、M1、C1 等代号不是 CLI id,也不能当作 API payload。
!!! tip "快速阅读路线"
@@ -16,7 +16,7 @@ T1、M1、C1 等代号不是 CLI id,也不能当作 API payload。
## 先分清三个完成点 {#three-completions}
-安装完成、接入完成、工作完成不是同一句话。安装回答 CLI 与所需 runtime 是否可用;
+安装回答 CLI 与所需 runtime 是否可用;
接入回答工作归属、状态位置与运行路径是否明确;交付回答实际产物是否满足当前验收。
接入成功可以暂时没有执行中的 Turn;一轮成功也可以仍在等待外部检查或批准。
@@ -30,14 +30,14 @@ T1、M1、C1 等代号不是 CLI id,也不能当作 API payload。
`.loopx/registry.json` 与 `.loopx/goals//ACTIVE_GOAL_STATE.md`);`loopx status` 能显示
active state 与当前 frontier;再次连接按精确 `goal_id` 复用已有 Goal 而不是覆盖;新接入的执行者使用
fresh `agent_id`,除非用户明确授权 takeover;`.loopx/` 与 `.loopx/goals/` 不进入 Git。这些本地状态
-是控制面状态,不是项目源码。
+是控制面状态。
-因此,本章不是把所有命令连成一段可以盲目粘贴的脚本。读取、预览和执行分段进行,
+读取、预览和执行分段进行,
每次只在前一步给出足够依据后继续。出现拒绝时先理解所保护的条件,不为让教程跑通而绕过检查。
## 一、准备:确认项目,保护已有状态 {#prepare-project}
-从你准备管理的 Git 项目根目录开始,不是从 LoopX 的源码目录开始。在目标仓库根目录打开你正在使用的 Agent 开发工具,把下面提示词中的目标和 Host 改成自己的
+从你准备管理的 Git 项目根目录开始。在目标仓库根目录打开你正在使用的 Agent 开发工具,把下面提示词中的目标和 Host 改成自己的
情况后直接发送:
```text
@@ -74,7 +74,7 @@ fresh `agent_id`,除非用户明确授权 takeover;`.loopx/` 与 `.loopx/goa
明确写“尚未接入完成”。
```
-这份提示词不是把控制权交给 Agent。它把可执行工作委托给 Agent,同时把以下决定留给你:
+它把可执行工作委托给 Agent,同时把以下决定留给你:
- 多个 Goal 中选择哪一个;
- 是否 takeover 已有 Agent identity;
@@ -142,7 +142,7 @@ git ls-files .loopx .loopx/goals .local
项目可能已经包含 `.loopx/registry.json` 或 `.loopx/goals/`。先识别已有 Goal、在途工作和状态位置,
不要复制其他项目的 registry,也不要为了得到一个空白起点覆盖旧状态。
-下面是常见布局示意,不是所有 authority、租约和日志的完整物理位置:
+下面是常见布局示意:
```text
your-project/
@@ -181,7 +181,6 @@ git check-ignore -v .loopx/goals/example/ACTIVE_GOAL_STATE.md
默认情况下已跟踪文件不受忽略规则支配;`--no-index` 用于不考虑 index 而诊断规则,
不是“强制忽略”,也不是专门处理尚不存在的文件。
`ls-files` 默认显示当前 index 中的路径;有输出说明路径被跟踪或暂存,**不单独证明已经推送**。
-没有输出也不证明旧提交或远端从未包含敏感材料。
依据见 [Git check-ignore](https://git-scm.com/docs/git-check-ignore) 与
[Git ls-files](https://git-scm.com/docs/git-ls-files)。
@@ -215,7 +214,7 @@ loopx doctor
已有 pip、pipx 或 archive 安装则按[附录升级说明](appendix-reference.md)确认安装 owner,
不要在不清楚来源时叠加另一个安装。
-`doctor` 比 `command -v loopx` 多回答依赖、安装和集成状态,但不是所有 Host 路径都已验证的证明。
+`doctor` 比 `command -v loopx` 多回答依赖、安装和集成状态。
需要验证实际 Effect runtime 与 journal checkpoint 路径时再使用:
```bash
@@ -245,9 +244,9 @@ loopx registry
loopx status
```
-对于已有项目,应先读取当前连接,按现有路径续接,而不是为了重试一项任务重复连接。
+对于已有项目,应先读取当前连接,按现有路径续接。
`connect` / `bootstrap` 登记 Goal 并写 active state;首连不会替调用方生成一套 onboarding Todo。
-没有可执行工作时,下一步是确认实际任务与工作边界,不是凭空增加配额。
+没有可执行工作时,下一步是确认实际任务与工作边界。
### Guided packet 是计划,不是执行回执
@@ -258,7 +257,7 @@ loopx start-goal --guided --project . \
--goal-text "增加兼容的 JSON 输出,保留默认文本输出;验证和文档完成后交付,不自动发布"
```
-返回的是 guided transaction packet。预览成功不证明 Todo 已写、Agent 已注册或 Host 已启动。
+返回的是 guided transaction packet。
读取 packet 当前要求补齐的选择,按照其提供的精确命令继续;不要从旧对话恢复一条已过时的执行指令。
存在多个 Goal 时,在 `goal_selection_gate` 的 choices 中选择精确 `goal_id`;目标文本相似不能作为
@@ -281,7 +280,7 @@ true,`global_sync.ok` 为 true,且 `registration_readback.verified` 为 true
### Host 选择不是能力授予
-已知实际 Host 时显式传入;以下二选一,不是依次激活两个 Host:
+已知实际 Host 时显式传入;以下二选一:
```bash
# Codex App
@@ -299,7 +298,6 @@ loopx start-goal --guided --project . \
不要用一个熟悉的名称代替探测。具体激活与读回分别见 [Codex App](06-codex-app.md) 和
[Codex CLI](07-codex-cli.md),其他适配器见 [Runtime Connector Catalog](/loopx/docs/integrations/runtime-connector-catalog/)。
类型注册、当前可启动、进程内自主继续、进程退出后可再次唤醒,是不同条件。
-一个参数被接受不证明这些条件都已成立。
## 四、接入验收:现在可以进入哪一步? {#connection-acceptance}
@@ -314,8 +312,7 @@ git status --short
git ls-files .loopx .loopx/goals .local
```
-它们不请求完成 Todo 或扣减交付配额,但“读取”不承诺整个进程完全无 IO:
-可能涉及 runtime 启动等支持动作。若环境有严格隔离要求,应按所用入口、provider 和设置单独确认。
+它们不请求完成 Todo 或扣减交付配额。若环境有严格隔离要求,应按所用入口、provider 和设置单独确认。
不要把所有名称带有“检查”的命令归入同一种无副作用类别。
准备进入本轮时,使用当前 Host 规定的准入路径,例如:
@@ -327,7 +324,7 @@ loopx quota should-run --goal-id --agent-id
读取完整 interaction contract、selected Todo、权限、workspace 与后续指令,不能只取一个
`should_run` 布尔值。尤其 `--codex-app` 的相关准入路径可以创建 heartbeat receipt;
它与单纯列举现状不同,不应在诊断脚本中无限重复。
-`refresh-state`、获取/续租、结算和 scheduler ACK 也都是各自有条件的操作,不是通用查询。
+`refresh-state`、获取/续租、结算和 scheduler ACK 也都是各自有条件的操作。
| 四问 | 接入验收需要的答案 |
| --- | --- |
@@ -341,11 +338,11 @@ loopx quota should-run --goal-id --agent-id
> 项目连接与身份已读回,私有状态未进入当前 index。Host 激活尚未确认,所以只完成接入准备,
> 还没有第一次执行。下一步按 CLI 章节中的当前 activation packet 启动并读回;不会宣称 T1 已交付。
-这是一份本地操作报告的**教学示意**,不是产品返回类型。对外分享时去掉私有路径、目标内容和凭据。
+这是一份本地操作报告的**教学示意**。对外分享时去掉私有路径、目标内容和凭据。
## 五、从接入走到第一份交付 {#first-delivery}
-完成 Host 章节后回到这里。目标不是让界面显示“正在运行”,而是完成一个足以独立验证的小工作段。
+完成 Host 章节后回到这里。目标是完成一个足以独立验证的小工作段。
不要把本节的推演称为真实 Host 的端到端测试;实际验收必须来自自己的运行结果。
### 第一幕:让 A 做 T1,而不是让它拥有整个发布流程
@@ -381,8 +378,8 @@ G1 没有批准发布时,T3 不能因 CI 通过或 T1 已结算而获得权限
可以在自身约束满足后继续。用户需要回答问题与 Agent 可以继续另一项工作可以同时成立。
具体判断见[观察与调度](04b-budget-and-admission.md)和[工作图](work-graph-and-authority.md)。
-无变化的观察不应冒充交付;它仍可能有计算和网络成本。没有收到通知也不是外部世界没有变化的证据。
-若 Host 已退出且没有可用唤醒机制,应报告运行缺口,而不是把 quiet 状态解释为健康等待。
+无变化的观察不应冒充交付;它仍可能有计算和网络成本。
+若 Host 已退出且没有可用唤醒机制,应报告运行缺口。
### 第四幕:条件改变,更新受影响的判断
@@ -391,7 +388,7 @@ G1 没有批准发布时,T3 不能因 CI 通过或 T1 已结算而获得权限
对象、scope 与条件,不能只看“approved”这个词。
若维护者同时修改了目标或验收,应走已有 planning/replan 和决定入口,将变化与当前工作关联。
-书中的 C1/C2 是解释适用性的例子,不是在声明已有一个统一的 Goal intent-version schema。
+书中的 C1/C2 是解释适用性的例子。
修改目标的权限不能由 Agent 为了凑齐“完成”而自行产生。
### 第五幕:把结果返回给需要验收的人
@@ -403,7 +400,7 @@ T3 的当前条件均有证据后,重新判断下一步。交付一个可审
以及接下来由谁决定或行动。链接到了产物、工作内部已结算、收件人实际得到结果、Goal 已接受,
这些事实分别核对,不能把其中任一项自动提升为全部完成。
-下面是本地交付报告的示意,而不是额外持久化格式:
+下面是本地交付报告的示意:
> JSON 输出与文档已在 C2 完成;列出的兼容检查及 C2 的 CI 支持当前实现结论。
> 已有工作写回与结算可追溯。维护者的发布决定仍未完成,因此返回待审阅产物,不执行发布。
@@ -414,7 +411,7 @@ T3 的当前条件均有证据后,重新判断下一步。交付一个可审
## 六、让 Agent 帮你接入,但不给它猜测权限 {#delegate-onboarding}
-可以把以下提示交给已在项目里工作的 Agent。它是委托示例,不是机器强制执行的新协议。
+可以把以下提示交给已在项目里工作的 Agent。它是委托示例。
已有明确授权的普通操作可按其范围完成,不要求每个命令都再次打断用户;身份接管、权限扩大、
外部发布和破坏性操作不能从模糊目标中推断出来。
diff --git a/docs/book/chapters/06-codex-app.md b/docs/book/chapters/06-codex-app.md
index 5725534d8f..683c5a322b 100644
--- a/docs/book/chapters/06-codex-app.md
+++ b/docs/book/chapters/06-codex-app.md
@@ -50,8 +50,7 @@ Agent Turn no delivery
validate -> writeback -> optional spend
```
-右分支是合法结局,而且是经常发生的那一种。它只说明**这一次**没有该做的工作,不等于 Goal
-frontier 已经收尾:已结算 Turn 的回放会返回 `should_run=false`,同时保留当前 cadence,等新的
+右分支是合法结局,而且是经常发生的那一种。它只说明**这一次**没有该做的工作:已结算 Turn 的回放会返回 `should_run=false`,同时保留当前 cadence,等新的
Turn identity 再评估。所以频繁走到右分支并不说明 cadence 该放慢;只有当前 `scheduler_hint`
提出调整(`apply_needed=true`)时,才按下面的四步执行。
@@ -94,8 +93,7 @@ Codex 当前通过 command-facade skill 暴露 LoopX;不要假设用户自定
第 5 步和第 7 步的顺序容易搞反。先激活 heartbeat 意味着你在 Todo 成型之前就开始被定时唤醒,每次
唤醒都会拿到一个还没有 frontier 的 Goal。先写 Todo 再激活,第一轮唤醒就有确定的候选。
-你不需要手工执行所有内部命令,但应该能从 Agent 报告中看到这些状态转换。得到一段自然语言计划,
-不等于项目状态已经建立;看到 guided packet,也不等于 heartbeat 已经安装。这两件事都要单独 readback。
+你不需要手工执行所有内部命令,但应该能从 Agent 报告中看到这些状态转换。这两件事都要单独 readback。
## 每一轮仍然要过 Quota Gate
@@ -150,8 +148,7 @@ loopx quota scheduler-ack-current
这里最容易漏掉的是 readback。应用了 `recommended_rrule` 就当作完成,是一种常见做法:本地 ACK
ledger 里有了记录,cadence 看起来生效了。但 ledger 记下的是**提议**,Host 上真正生效的**实际值**要单独读回。两者
不一致时,packet 会在 `scheduler_hint.app_automation.stateful_backoff.host_observation.status`
-上报 `drift_detected`,这时真实 cadence 和 ledger 已经分叉,必须按当前 hint 修复,而不是信任那份
-看起来完整的记录。
+上报 `drift_detected`,这时真实 cadence 和 ledger 已经分叉,必须按当前 hint 修复。
反向的组合也存在。当 `apply_needed=false, ack_needed=true` 时,精确 Host readback 已经匹配目标
cadence,应当跳过这次 no-op update 并直接执行绑定 ACK。把它当成"没事可做"会留下一条未结算的
@@ -173,12 +170,12 @@ readback 中表现为 `drift_detected`。
这是一条需要 readback 才能闭合的链路,不像本地写一个变量那样即时。
**代价三:空转与工作在图上看不出区别。** 两者都留下触发记录、都以成功退出。要区分它们,必须看
-writeback 和 spend 历史,而不是看 heartbeat 日志。
+writeback 和 spend 历史。
**边界一:heartbeat 不创造 frontier。** 一个没有 Todo 的 Goal 不会因为被频繁唤醒而出现下一步。
App 能保证有人看,不能保证有东西可做;没有可运行候选时就该进入 wait 或 monitor,让 cadence 放慢。
-**边界二:automation 不是第二控制面。** 不要在 automation prompt 里复制 quota 状态机,也不要让
+不要在 automation prompt 里复制 quota 状态机,也不要让
它自己解析 Todo 是否 runnable。稳定 prompt 只负责协议,判断属于每次读到的 packet。
**边界三:切换 Host 要核对工作归属。** App 和 CLI 可以读同一 Goal;切换前应查清旧实例是否仍执行、claim/lease 由谁持有,以及当前 writer 的围栏模式。需要显式移交时走对应 lifecycle,不能仅凭新 Host 已启动就并发推进同一项工作。
@@ -222,8 +219,7 @@ loopx start-goal --guided --project . \
### heartbeat 频繁空跑
-查看 `scheduler_hint`、monitor Todo 和 spend history。无变化的外部等待应转为 monitor/backoff,
-而不是每次启动完整 Agent Turn。若 RRULE 已放慢但触发频率没变,检查 `host_observation.status`
+查看 `scheduler_hint`、monitor Todo 和 spend history。无变化的外部等待应转为 monitor/backoff。若 RRULE 已放慢但触发频率没变,检查 `host_observation.status`
是否报告 `drift_detected`,并按当前 hint 重新 apply 与 ACK。
### Goal 被 Gate 阻塞
@@ -235,15 +231,15 @@ Gate 而不重复同样的安静轮询;若 Host cadence 更新失败而留下
## 不变式
-1. **heartbeat 触发不等于工作发生。** 判断真实性看 writeback 与 spend,不看触发次数。
+1. 判断真实性看 writeback 与 spend,不看触发次数。
2. **每次唤醒都过一次 `quota should-run`。** 没有这层 Gate,automation 就变成绕过决策的旁路。
3. **`should_run=false` 是合法结果,但它只关闭这一个 Turn。** 已结算回放保留当前 cadence,用新的
Turn identity 重新评估;`false` 的次数或本 Turn 的 receipt 都不能当作放慢 cadence 的依据。需要
放慢时,由当前 `scheduler_hint` 提出(`apply_needed=true`),再走第 4 条的四步。
4. **cadence 变化的四步缺一不可**:proposal、host apply、host readback、ACK。
-5. **本地 ACK ledger 不证明 Host 状态。** 只有 Host readback 与目标一致才闭合,不一致时按
+5. 只有 Host readback 与目标一致才闭合,不一致时按
`drift_detected` 修复。
6. **切换 Host 需要明确接管。** 同一 Goal 可被多处读取,写入仍须满足当前 authority、claim/lease 与围栏要求。
-这六条指向同一件事:定时唤醒买到的是**持续尝试的能力**,不是**持续进展的事实**。区分这两者,
+这六条指向同一件事:定时唤醒买到的是**持续尝试的能力**。区分这两者,
就是本章要求四的全部内容。
diff --git a/docs/book/chapters/07-codex-cli.md b/docs/book/chapters/07-codex-cli.md
index 57278e5d41..fc899618d2 100644
--- a/docs/book/chapters/07-codex-cli.md
+++ b/docs/book/chapters/07-codex-cli.md
@@ -4,7 +4,7 @@
## 为什么 active Goal 与后台唤醒不同
-假设修复还未完成,你结束了当前 Codex 进程。再次打开终端时,工作没有继续。这说明执行环境已经离开,不代表 native Goal 在进程存活时每轮都需要用户发消息。
+假设修复还未完成,你结束了当前 Codex 进程。再次打开终端时,工作没有继续。这说明执行环境已经离开。
| Host 状态 | 当前路径的行为 | 用户需要判断什么 |
| --- | --- | --- |
@@ -91,8 +91,7 @@ loopx quota should-run \
--runtime-profile codex_cli
```
-你应该看到 Host runtime 指向 `codex_cli`,scheduler owner 属于 Goal/agent loop,而不是 Codex App
-heartbeat。这个区别决定了"该唤醒时谁负责唤醒":如果 packet 报告 scheduler context 缺失,先修复
+你应该看到 Host runtime 指向 `codex_cli`,scheduler owner 属于 Goal/agent loop。这个区别决定了"该唤醒时谁负责唤醒":如果 packet 报告 scheduler context 缺失,先修复
runtime profile,不要忽略 warning。scheduler context 缺失或矛盾时,`scheduler_hint` 返回
`repair_scheduler_execution_context`,并把 unchanged poll 设为 `stop_until_context_repaired`:在修复
runtime profile 之前,它不会提出新的 cadence,也不会替你安排下一次唤醒。
@@ -110,7 +109,7 @@ lane 时,沿用该绑定。只有 Goal 没有任何已注册 lane 或显式 `-
lane,工作归属就被静默改写了。显式传入后,未注册的 id 会被拒绝;与 thread 绑定不同的已注册 id
会被当作明确的覆盖选择,所以只在确实要换 lane 时这样做。
-Agent identity 表达 LoopX 工作 lane,不证明具体 Host。判断工作是否真的在 Codex CLI 运行,要看
+判断工作是否真的在 Codex CLI 运行,要看
`host_surface`、runtime profile 或对应 run metadata。
交接时的正确顺序是:
@@ -155,13 +154,12 @@ Agent identity 表达 LoopX 工作 lane,不证明具体 Host。判断工作是
### 误用了隐藏 worker
停止该 worker,检查它是否写回了新 evidence 或 lease。先恢复 Todo ownership,再回到 visible
-TUI;不要让两个执行者并发修改同一工作树。检查这件事时要看 claim 与 lease 的实际归属,而不是看你
-记忆中谁在跑。
+TUI;不要让两个执行者并发修改同一工作树。检查这件事时要看 claim 与 lease 的实际归属。
### Goal 无变化轮询
达到 unchanged limit 后,Goal 应阻塞或安静等待。外部状态观察应转成 monitor Todo;用户通过
-Host 的 Goal resume 表面恢复,而不是反复重发完整任务。反复重发会让同一轮工作看起来像多轮进展。
+Host 的 Goal resume 表面恢复。反复重发会让同一轮工作看起来像多轮进展。
### App 与 CLI 同时激活
@@ -172,7 +170,7 @@ Host 的 Goal resume 表面恢复,而不是反复重发完整任务。反复
1. **区分 active、blocked 与进程退出。** 活跃 native Goal 可以继续;blocked 后按 Host resume 合同处理,退出后不能假定存在定时唤醒。
2. **setup Turn 只建立连接。** 连接和交付混在一轮里,后续每一步都建立在一个未审的计划上。
3. **`/goal` body 保持稳定。** 动态 Todo、Gate 和能力来自当次 decision packet,不来自 prompt。
-4. **visible Goal 与 selected Todo 是两件事。** Goal 能继续,不代表这个 Todo 就该做。
+4. **visible Goal 与 selected Todo 是两件事。**
5. **identity 一律显式传入。** 唯一已注册 lane 可能被自动选中;显式 `--agent-id` 让未注册的身份被拒绝,也让换 lane 成为看得见的选择。
6. **两个 Host 并存需要明确执行归属。** 复核当前 mode 下的 claim、lease 与围栏,不能凭同一 Goal 可读就并发写同一项工作。
diff --git a/docs/book/chapters/07b-when-loopx-is-not-the-answer.md b/docs/book/chapters/07b-when-loopx-is-not-the-answer.md
index cd10e85bc1..96ee1d1eed 100644
--- a/docs/book/chapters/07b-when-loopx-is-not-the-answer.md
+++ b/docs/book/chapters/07b-when-loopx-is-not-the-answer.md
@@ -30,7 +30,7 @@ LoopX 能记录 Goal、acceptance、工作队列、权限和证据,也能通
[状态底座](state-substrate.md)负责工作生命周期事实。LoopX 也有带来源、范围和撤销语义的 Agent 偏好,以及 decision context、reward memory、turn recall 等能力或接入边界。
-这些能力不等于任意聊天都自动进入永久知识库。偏好不是 action authority,召回内容需要检查来源、新鲜度和适用范围;是否可用还取决于当前版本、配置与 provider。
+召回内容需要检查来源、新鲜度和适用范围;是否可用还取决于当前版本、配置与 provider。
**使用判断:** 要保存的是 Todo/回执、明确的用户偏好,还是外部知识材料?先选择已有 owner,再决定保存与召回方式,避免把全部聊天塞进 active state。
diff --git a/docs/book/chapters/08-extension-placement.md b/docs/book/chapters/08-extension-placement.md
index e3c89cc739..be49ecf5e6 100644
--- a/docs/book/chapters/08-extension-placement.md
+++ b/docs/book/chapters/08-extension-placement.md
@@ -187,7 +187,7 @@ Provider 边界、来源 freshness、license 与 credential Gate。
### 2. 现有 Capability 的 Provider
-如果调用者需要的结果已经由一个 Capability 定义,新实现应进入该合同,而不是创建同义 Capability。
+如果调用者需要的结果已经由一个 Capability 定义,新实现应进入该合同。
Provider 可以是:
@@ -331,8 +331,7 @@ generic runner 要求 manifest 和 runtime 的权限都为空。发消息、写
### "多个文件共用代码,所以抽成 Extension"
-共享代码只说明可能存在 helper,不说明需要独立安装和生命周期。抽象应该跟随 change reason,
-而不是文件数量。
+共享代码只说明可能存在 helper,不说明需要独立安装和生命周期。抽象应该跟随 change reason。
## 本书示例的决定
@@ -358,17 +357,17 @@ generic runner 要求 manifest 和 runtime 的权限都为空。发消息、写
如果你要设计的不只是 standalone package,而是 Explore、Domain State、Capability Pack、
multi-agent preset、Provider 或 presentation 的组合,继续阅读
[Control-Plane Course 第 11 讲](/loopx/docs/development/control-plane-course/11-extension-layer/)。
-它解释这些扩展面怎样复用 Kernel,而不是创建第二套 Goal、Todo、Quota 或 Scheduler。
+它解释这些扩展面怎样复用 Kernel。
## 不变式
六句可以自己核对的话。
-1. **一个 capability 的存在理由是它的 caller outcome,不是它的目录名。** 找不到 caller、
+1. **一个 capability 的存在理由是它的 caller outcome。** 找不到 caller、
resolver 和 domain policy,它就不该出现在 catalog 里。
2. **capability 与 extension 是两个维度,一次改动可以只落在其中一个上。** 看到新 package
就直接推断新 capability,是放置错误最常见的形式。
-3. **共享代码并不构成升级成 capability 的理由。** 判据是独立调用合同与生命周期,而非文件数量。
+3. 判据是独立调用合同与生命周期,而非文件数量。
4. **manifest 可发现并不等于合同可调用。** `[[provides]]` 与 `[[implements]]` 只有在真实入口、
resolver 和 validation 就位后才应写入。
5. **Extension 的独立生命周期是用户可见的成本。** 声明它之前先确认这份成本换来了 caller
diff --git a/docs/book/chapters/09-extension-scaffold.md b/docs/book/chapters/09-extension-scaffold.md
index e7a897d8ce..3e42119494 100644
--- a/docs/book/chapters/09-extension-scaffold.md
+++ b/docs/book/chapters/09-extension-scaffold.md
@@ -58,7 +58,7 @@ timeout_seconds = 30
## 用明确的度量定义结果
-`characters` 是 Python Unicode code point 数,`words` 是空白分隔片段数,`lines` 遵循 `str.splitlines()`。所以“你好世界”的 words 是 1,组合字符可能包含多个 code point。这是示例的语义,不是通用自然语言分词。
+`characters` 是 Python Unicode code point 数,`words` 是空白分隔片段数,`lines` 遵循 `str.splitlines()`。所以“你好世界”的 words 是 1,组合字符可能包含多个 code point。这是示例的语义。
示例输入为:
@@ -75,13 +75,13 @@ timeout_seconds = 30
{"characters": 51, "non_whitespace_characters": 44, "words": 8, "lines": 2}
```
-外层同时保留 `ok`、response schema、request schema 与 extension identity。完整输出结构见 `schemas/response.schema.json`;额外的 LoopX managed receipt 不是领域计算结果的一部分。
+外层同时保留 `ok`、response schema、request schema 与 extension identity。完整输出结构见 `schemas/response.schema.json`。
## Decoder 为什么还要自己校验
请求要求 object、精确 schema、非空白 text,并拒绝额外字段。JSON Schema 用于描述 wire shape;decoder 实际执行字段约束,并检查编码、重复键、输入字节上限和 Python 空白语义。
-本例的输入上限是 65,536 字节,text 上限是 32,000 code point。这是教学包自己的限制,不代表 LoopX 全局默认值。
+本例的输入上限是 65,536 字节,text 上限是 32,000 code point。这是教学包自己的限制。
长整数暴露了另一条边界:Python 的 `json.loads` 可能因整数转换限制抛出 `ValueError`,即使数据还没超过字节上限。只捕获 `JSONDecodeError` 会让这个输入越过统一错误结果。
@@ -97,7 +97,7 @@ timeout_seconds = 30
| 5,000 位整数 | 错误 JSON,stderr 无 traceback | Python 3.11+ 整数解析回归 |
| doctor、CLI 输出 | doctor 不处理业务请求,run 输出一个对象 | 真实 provider 子进程入口 |
-源码与测试放在同一个配套目录。测试不调用模型、外部服务或 live Goal,也不证明 managed runtime 的进程回收、权限隔离或升级路径。下一章将这些生命周期步骤单独验证。
+源码与测试放在同一个配套目录。测试不调用模型、外部服务或 live Goal。下一章将这些生命周期步骤单独验证。
## 怎样扩展这个例子
diff --git a/docs/book/chapters/10-extension-lifecycle.md b/docs/book/chapters/10-extension-lifecycle.md
index 3b826a0adf..98bafc9b6e 100644
--- a/docs/book/chapters/10-extension-lifecycle.md
+++ b/docs/book/chapters/10-extension-lifecycle.md
@@ -94,7 +94,7 @@ identity,identity 覆盖 entrypoint 文件内容、所选 Python interpreter
以及 extension 自己声明的 view validator。任何一项变化都会让旧 doctor proof 失效;LoopX 自身的
内置 validator 被刻意排除,因此升级 LoopX 不会连坐所有 extension。
-doctor 的状态是一条阶梯,而不是布尔值:
+Doctor 的状态是一条阶梯:
```text
entrypoint_missing -> identity 无法解析
@@ -198,7 +198,7 @@ loopx extension rollback loopx-text-stats --execute --format json --state-file "
```
rollback 先按 previous revision 记录的 manifest 与入口位置 probe **当前安装的** entrypoint,通过后再
-切换。它不是任意 Git checkout 回退,而是 activation state 中已验证 revision 的生命周期转换。probe
+切换。它是 activation state 中已验证 revision 的生命周期转换。probe
通过不证明旧版本 package 已经装回:若环境里仍是新 package,rollback 后 LoopX 记录的是旧 revision,
实际运行的却是新代码。回滚前后应安装与目标 revision 匹配的 package,再用 `run` 读回实际行为。activation state 保留最近的 validated revision 快照,
数量有限(当前保留 5 个)。
diff --git a/docs/book/chapters/11-engineering-boundaries.md b/docs/book/chapters/11-engineering-boundaries.md
index b5a3b89ecd..ccf9502a25 100644
--- a/docs/book/chapters/11-engineering-boundaries.md
+++ b/docs/book/chapters/11-engineering-boundaries.md
@@ -67,7 +67,7 @@ loopx capability list --format json
loopx extension --help
```
-命令存在不代表完整流程已验证。Host automation、visible Goal 和 Extension activation 需要各自的
+Host automation、visible Goal 和 Extension activation 需要各自的
readback;`doctor --deep` 还会启动并探测发布物携带的 TypeScript Effect runtime。迁移中的
Python facade 成功返回,也不单独证明 TypeScript semantic owner、runtime decoder 和 durable
effect path 都已通过。
@@ -208,5 +208,4 @@ loopx check \
- [ ] internal links 与 public boundary scan 通过;
- [ ] 首页预览已由 owner 审阅。
-完成这些检查后,GitHub Pages workflow 才应从 `main` 发布站点。Pages 是展示面,不是内容或
-LoopX 状态的事实源。
+完成这些检查后,GitHub Pages workflow 才应从 `main` 发布站点。Pages 是展示面。
diff --git a/docs/book/chapters/12-control-plane-course.md b/docs/book/chapters/12-control-plane-course.md
index 34461284e1..f5422d5f40 100644
--- a/docs/book/chapters/12-control-plane-course.md
+++ b/docs/book/chapters/12-control-plane-course.md
@@ -58,7 +58,7 @@ uv sync --extra test
前三组使用临时目录中的真实本地状态或 CLI,第四组使用构造的 quota 输入。它们会写测试状态,也可能启动本地 Effect runtime。不能把 fixture 的 registry、删除或损坏注入步骤替换成 live Goal。缺依赖、收集失败、零项测试或 runtime 不可用,都不等于行为通过。
-源码链接固定到核对过的提交,命令运行你记录的 checkout。先核对版本差异;测试改名时沿原 invariant 找 owner,不把新输出直接抄为期望。这些测试不是模型、真实 Host、远端 provider 或全产品资格验证。
+源码链接固定到核对过的提交,命令运行你记录的 checkout。先核对版本差异;测试改名时沿原 invariant 找 owner,不把新输出直接抄为期望。
### 先读取,再决定是否改变状态 {#read-before-change}
@@ -75,7 +75,7 @@ uv sync --extra test
#### 允许或拒绝的理由 {#state-reason}
-拒绝来自当前源状态或读取失败,不是页面措辞。done/blocked 不能因缓存显示 open 而重新获得准入;authority 不可读也不能证明工作开放。另一方面,显示截断不是拒绝依据:真实存在、当前满足条件的 Todo,可以经精确选择进入本轮。
+拒绝来自当前源状态或读取失败。done/blocked 不能因缓存显示 open 而重新获得准入;authority 不可读也不能证明工作开放。另一方面,显示截断不是拒绝依据:真实存在、当前满足条件的 Todo,可以经精确选择进入本轮。
#### 支持结论的证据 {#state-evidence}
@@ -88,7 +88,7 @@ uv run --extra test pytest -q \
[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_quota_authority_settlement_journey.py)的第一项断言 `decision=skip`、没有 selected Todo、receipt 为 `not_committed`;第二项断言没有选中项且本轮 receipt 数为零。第三项覆盖 legacy/File/SQLite:精确选择得到 `decision=run`,selected Todo 与 settlement identity 都绑定目标 id,即使它超出展示范围。
-这证明特定路径的来源与选择约束,不证明 provider 已恢复、所有 legacy 路径只读投影,或仅凭 Todo open 就能执行。
+这证明特定路径的来源与选择约束。
#### 下一步入口与停止条件 {#state-next}
@@ -102,11 +102,11 @@ uv run --extra test pytest -q \
#### 事实依据 {#lease-facts}
-分别读取当前 lease 与 original receipt,核对 Goal/Todo、owner、模式、状态、version 与 execution identity。本例仅覆盖 File/SQLite 的 `hard_lease` fixture;同名 Agent 和过去的成功都不是当前执行实例的充分证明。
+分别读取当前 lease 与 original receipt,核对 Goal/Todo、owner、模式、状态、version 与 execution identity。本例仅覆盖 File/SQLite 的 `hard_lease` fixture。
#### 允许或拒绝的理由 {#lease-reason}
-返回历史结果不应复活旧权限。renew 后仍需使用当前 lease 的证明;release 后旧 acquire key 已退役,不能把同一请求变成新的执行。新的 key 也不是绕过拒绝的方法:只有新的工作准入、当前归属和版本条件均满足时,才能获取新 lease。
+返回历史结果不应复活旧权限。renew 后仍需使用当前 lease 的证明;release 后旧 acquire key 已退役,不能把同一请求变成新的执行。只有新的工作准入、当前归属和版本条件均满足时,才能获取新 lease。
#### 支持结论的证据 {#lease-evidence}
@@ -117,7 +117,7 @@ uv run --extra test pytest -q \
[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_canonical_lease_acquire.py)断言 renew 后 acquire 读回当前 lease,同时保留 original receipt;release 后复用旧 key 得到 `idempotency_key_reuse`。新的合法 acquire 推进版本,完成后 Todo 为 done、lease 为 released;对已完成 Todo 再 acquire 得到 `todo_not_open`。真正完成后 `state.exists()` 为真,并非所有状态文件都被删除。
-这是顺序执行的测试,不证明 soft-claim 的强互斥、TTL 到期后的真实竞争,或外部服务能够拒绝旧执行者的写入。
+这是顺序执行的测试。
#### 下一步入口与停止条件 {#lease-next}
@@ -146,7 +146,7 @@ uv run --extra test pytest -q \
[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_quota_authority_settlement_journey.py)先从 `spend_required` 到 `settled`,随后仅在 fixture 中移除对应回执。再次写回得到 `spend_receipt_required` 与 `recovery_does_not_spend=true`;执行返回的命令后 `appended=false`,扣减记录仍为一次。最终再次检查达到 `settled` 且没有 `settlement_owed`,下一轮不再卡在这项结算恢复上。
-这些断言证明本例的内部结算恢复,不证明供应商账单为零、不确认其他未知 effect,也不关闭 G1 或接受整个 Goal。测试通过本身不是 live Goal 已恢复的证据。
+这些断言证明本例的内部结算恢复。
#### 下一步入口与停止条件 {#settlement-next}
@@ -166,7 +166,7 @@ uv run --extra test pytest -q \
#### 允许或拒绝的理由 {#monitor-reason}
-是否产生这项 replan obligation,要同时考虑计数、归属和可选工作。这里的五次是具体策略阈值,不是所有等待的定理;current-Agent advancement 可以优先,显式 watch-only 也不受同一重规划触发约束。不产生 obligation 不代表一定有 Host 会醒来,更不自动授权一次写入或交付扣额。
+是否产生这项 replan obligation,要同时考虑计数、归属和可选工作。这里的五次是具体策略阈值;current-Agent advancement 可以优先,显式 watch-only 也不受同一重规划触发约束。
#### 支持结论的证据 {#monitor-evidence}
@@ -178,7 +178,7 @@ uv run --extra test pytest -q \
tests/control_plane/test_settled_replay_construction.py::test_settled_replay_preserves_schedule_without_new_host_effects
```
-[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_monitor_replan_agent_scope.py)分别断言:只有符合条件的当前 Agent lane 产生 `monitor_no_change_streak`;有当前 advancement 时为 `run` 且没有该 obligation;watch-only 即使 streak 为 50 也不因此触发。它们预置计数器后执行决策,没有交错发送远端 poll,不证明计数写入并发、真实唤醒或 backoff 时间。
+[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_monitor_replan_agent_scope.py)分别断言:只有符合条件的当前 Agent lane 产生 `monitor_no_change_streak`;有当前 advancement 时为 `run` 且没有该 obligation;watch-only 即使 streak 为 50 也不因此触发。它们预置计数器后执行决策。
这里同时给出一个直接反例:**已结算 Turn 的回放**。该测试在仍有 open advancement successor 时返回
`should_run=false`,但 `scheduler_hint.action` 是 `preserve_current_schedule`、`next_trigger` 是 `fresh_turn_identity`,host action 为 `none` 且不需要 ACK。所以 `false` 的
@@ -197,7 +197,7 @@ uv run --extra test pytest -q \
假设外部写入已经发出,随后响应丢失。现在只有超时和 prepared 意图,缺少能确认结果的读回。**不知道是否发生**与**已经确认没发生**是不同事实;换 operation id 再发一次可能制造第二次效果。
在当前 Turn settlement 的
-[`_resolve_prepared_effect`](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/loopx/control_plane/turn_driver/settlement.py)中,没有 resolver、resolver 异常或 unsupported kind 都不能授权执行;有效 committed payload 可供复用,`absent` 才进入未提交分支。这个局部判断仍受外围 journal、身份与恢复条件约束,不是所有外部系统的统一恢复保证。
+[`_resolve_prepared_effect`](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/loopx/control_plane/turn_driver/settlement.py)中,没有 resolver、resolver 异常或 unsupported kind 都不能授权执行;有效 committed payload 可供复用,`absent` 才进入未提交分支。这个局部判断仍受外围 journal、身份与恢复条件约束。
| 原身份的读回 | 允许或拒绝的理由 | 下一入口及需要取得的证据 |
| --- | --- | --- |
@@ -213,7 +213,7 @@ uv run --extra test pytest -q \
## 综合练习:一次交付为什么仍未获准? {#integrated-judgment}
-回到[贯穿任务](00-reading-guide.md#running-example)。以下是合成推演,不是新增产品 fixture:T1 在 C1 上验证过且已结算;随后代码变成 C2。M1 仍只有 C1 的绿色 CI 观察,G1 的发布批准尚未完成,T2 有可独立检查的文档工作。
+回到[贯穿任务](00-reading-guide.md#running-example)。以下是合成推演:T1 在 C1 上验证过且已结算;随后代码变成 C2。M1 仍只有 C1 的绿色 CI 观察,G1 的发布批准尚未完成,T2 有可独立检查的文档工作。
| 四问 | 足够具体的答案 |
| --- | --- |
@@ -222,13 +222,13 @@ uv run --extra test pytest -q \
| 哪项证据支持? | 当前 revision 的验证与外部读回、覆盖正确对象/scope 的明确决定,以及当前工作的读回;单独一张绿色截图不足以组合成批准 |
| 下一步找哪个入口? | 经现有验证/Monitor 路径获取 C2 的证据;由维护者通过已有 Gate/Workspace 决定入口处理 G1;独立工作交回当前准入。条件满足后重算 T3,而不是重做已确认的 C1 工作 |
-[权限](work-graph-and-authority.md)、[恢复](04-runtime-boundaries.md)与 [Workspace](workspace-v1.md)分别拥有这些操作说明。Owner 决定不统一由自动 Turn 的 quota 授权;运行某个内部测试也不证明本次真实 CI 或批准已经发生。
+[权限](work-graph-and-authority.md)、[恢复](04-runtime-boundaries.md)与 [Workspace](workspace-v1.md)分别拥有这些操作说明。Owner 决定不统一由自动 Turn 的 quota 授权。
将任务换成“依据两份公开材料完成比较报告”,仍能使用同一判断:材料版本替代 commit,方法与引用检查支持结论,接受人与发布范围需要明确。材料更新后重新检查受影响的分析,不把全部旧讨论变成新证据;报告写完也不自动授权发布。这是概念迁移练习,不宣称另一条产品旅程已经验证。
### 再加一个条件:原 Turn 尚未收口
-若 T1 还欠原身份的等待写回,“T2 独立”并不允许同一 Turn 改绑结算身份。先解释原 Turn 怎样收口,再解释新的准入怎样选择 T2。进阶测试与版本边界见[等待时序](03-one-turn.md#wait-closeout);上面八个测试函数是四组练习选定的范围,不是完整源码的测试清单。
+若 T1 还欠原身份的等待写回,“T2 独立”并不允许同一 Turn 改绑结算身份。先解释原 Turn 怎样收口,再解释新的准入怎样选择 T2。进阶测试与版本边界见[等待时序](03-one-turn.md#wait-closeout);上面八个测试函数是四组练习选定的范围。
再检查协作:A 和 B 各自通过验证,不足以验收组合结果;按[交接到集成](work-graph-and-authority.md#handoff-to-integration)指出采用版本、集成验证、发布决定与最终接受者。
diff --git a/docs/book/chapters/appendix-reference.md b/docs/book/chapters/appendix-reference.md
index 0572497be6..248c1dc4d3 100644
--- a/docs/book/chapters/appendix-reference.md
+++ b/docs/book/chapters/appendix-reference.md
@@ -23,7 +23,7 @@ loopx --registry "$REGISTRY" --runtime-root "$RUNTIME" --format json \
## 从症状找到负责入口 {#diagnostic-routing}
-先找第一处缺少证据的关系,而不是清空整个 Goal。下表是查阅方法,不是新的自动修复状态机。
+先找第一处缺少证据的关系。下表是查阅方法。
| 症状 | 先取得的事实 | 规则与操作入口 | 完成或停止条件 |
| --- | --- | --- | --- |
@@ -57,7 +57,7 @@ Todo 是有身份的工作;frontier 是按当前约束得到的候选;Turn /
## 要求三:明确当前执行者与作用范围 {#requirement-three-one-accountable-actor}
-Agent identity 表达 lane,不证明 Host。Vision 表达适用的 per-Agent 路线。Claim 是归属;lease 在适用 writer/mode 下参与执行证明;Gate 表达具名决定范围;Host 提供实际执行与唤醒条件。这些机制不合成一个全系统唯一行动者,也不自动提供 OS sandbox。详见[工作图](work-graph-and-authority.md)。
+Vision 表达适用的 per-Agent 路线。Claim 是归属;lease 在适用 writer/mode 下参与执行证明;Gate 表达具名决定范围;Host 提供实际执行与唤醒条件。这些机制不合成一个全系统唯一行动者,也不自动提供 OS sandbox。详见[工作图](work-graph-and-authority.md)。
## 要求四:消耗有上限且可外部观察 {#requirement-four-bounded-externally-observable-spend}
@@ -114,7 +114,7 @@ loopx update apply
loopx doctor
```
-先确认安装 owner、目标版本与计划,再授权 apply。普通用户不把 `--ref main` 当成发布版升级默认。成功升级 CLI 不证明所有 Host、Provider 和已有 Goal 状态均已迁移;按实际使用面检查 skills、状态、Host readback 和 enabled Extension readiness。
+先确认安装 owner、目标版本与计划,再授权 apply。普通用户不把 `--ref main` 当成发布版升级默认。按实际使用面检查 skills、状态、Host readback 和 enabled Extension readiness。
需要备份时,先预览再执行:
diff --git a/docs/book/chapters/core-state-machines.md b/docs/book/chapters/core-state-machines.md
index 71cf701880..cd4fc34fc8 100644
--- a/docs/book/chapters/core-state-machines.md
+++ b/docs/book/chapters/core-state-machines.md
@@ -5,13 +5,11 @@
那些机制在文档里分开读时各自成立;真正需要回答的问题在这里:**它们怎样接回同一
条循环?**
-先给结论:**LoopX 由多组状态机协作驱动;但最高一层不是
-“九台机器互相发消息”,而是一条 effectful Agent Loop。** Harness 解释 Agent 或 Host 提出的
+先给结论:**LoopX 由多组状态机协作驱动;最高一层是一条 effectful Agent Loop。** Harness 解释 Agent 或 Host 提出的
effect request,再由 Todo、Gate、Quota、Settlement、Scheduler 等领域状态机判断这一小段流程的
-合法动作。它们通过持久事实、typed contract、guarded transition 和 receipt 衔接,而不是直接
-覆盖彼此的状态。
+合法动作。它们通过持久事实、typed contract、guarded transition 和 receipt 衔接。
-LoopX 不靠一个巨型状态机推进 Goal。它把持久工作、单轮决策、证据结算、调度和界面投影
+它把持久工作、单轮决策、证据结算、调度和界面投影
交给有明确 owner 的协作状态机。本章先建立名词和抽象层级,再解释为什么这样设计,随后看
协作总图,再逐组展开状态机,最后交代这套设计付出的代价。这样你可以先理解主线,再按需深入某一组规则。
@@ -53,27 +51,25 @@ LoopX 不靠一个巨型状态机推进 Goal。它把持久工作、单轮决策
Handoff 等各自维护一张 interpretation table。
所以“LoopX 是多状态机系统”在内层是对的;在外层,更准确的说法是:**一条 Agent Loop 由
-多组有边界的状态机共同解释和约束。** 状态机是 Harness 内部的决策表,不是九个平级微服务,
-也不是九个 Agent。
+多组有边界的状态机共同解释和约束。** 状态机是 Harness 内部的决策表。
## 先认识名词:把“事实、判断、动作、证明”分开
-下面这些词会反复出现。第一次阅读只需记住“它是什么”和“它不是什么”:
+下面这些词会反复出现。第一次阅读只需记住“它是什么”:
先把一轮读成一句白话:**Goal 给出长期边界,frontier 给出当前工作,控制面派生本轮 decision,
Agent / Host 执行 effect,observation 经验证后写回事实,receipt 与 projection 再把下一轮接起来。**
- **目标与工作 — Goal、Todo、frontier、Vision / replan**:Goal 是长期 identity 与边界;Todo
- 是工作项;frontier 是当前可继续的工作边界;Vision / replan 保存路线和改道依据。它们不是一个
- 可整体覆盖的大 Goal 对象,“一条 Todo 完成”也不等于“Goal 完成”。
+ 是工作项;frontier 是当前可继续的工作边界;Vision / replan 保存路线和改道依据。
- **事实与视图 — source / authoritative fact、derived decision、projection**:source 是 owner
可持久写入的事实;decision 是规则算出的本轮判断;projection 是给 Agent、Host 或人看的视图。
- 页面显示的字段不一定可写,projection 也不是第二套事实源。
+ 页面显示的字段不一定可写。
- **动作与证明 — effect request / proposal、observation、transition、evidence、receipt**:proposal
请求动作;observation 报告外部事实;transition 接受合法变化;evidence 支撑判断;receipt 证明
- 有 identity 的提交已经发生。Agent 的请求不等于授权,工具返回也不自动等于完成。
+ 有 identity 的提交已经发生。
- **约束与运行 — Gate、lease、quota、Scheduler / heartbeat、Host / Runtime**:它们分别限定
- 决定范围、临时执行权、本轮计算资格、再次唤醒时间和 effect 执行;不是五种同义的全局锁。
+ 决定范围、临时执行权、本轮计算资格、再次唤醒时间和 effect 执行。
### 先分清三种“状态”
@@ -92,7 +88,7 @@ Todo completion、evidence 和 receipt 的 owner。
## 为什么这样设计,而不是一个大状态机?
-拆分不是为了增加名词,而是因为这些状态天然有不同的变化原因:
+拆分是因为这些状态天然有不同的变化原因:
1. **寿命不同**:Todo 和 evidence 要跨会话保存;quota decision 只对当前 Turn 有效;projection 随时可以重建。
2. **权限不同**:Agent 可以提出 effect;Host 可以执行 effect;只有对应 transition owner 能接受事实变化。
@@ -103,7 +99,7 @@ Todo completion、evidence 和 receipt 的 owner。
如果把它们压进一个 `Goal.status` 或允许 Agent 整体覆盖 `GoalState`,一次写入就可能误删其他
Agent 的进展;一次网络超时也无法判断该重试、回读还是补偿;界面字段还会反向变成事实源。
-协作不等于互相发消息。九组状态机主要通过四种稳定接口连接:
+九组状态机主要通过四种稳定接口连接:
1. **Source facts**:Todo、event、lease、Vision 和 receipt 供 reducer / interpreter 只读。
2. **Typed decision / effect**:`interaction_contract`、selected action 和 scheduler hint 告诉 Agent
@@ -129,7 +125,7 @@ flowchart TD
Facts -.-> Projection["projection Workspace / status"]
```
-这不是“状态机 A 调用状态机 B”的时序图。真正接力的是 source facts、typed decision、effect、
+真正接力的是 source facts、typed decision、effect、
observation 和 receipt;每个状态机只负责自己的 decision table 与合法 transition。
## 从 L0 到 L4:用这些名词回答五个架构问题
@@ -155,13 +151,13 @@ observation 和 receipt;每个状态机只负责自己的 decision table 与
| **Projection** | 把 facts 编译成面向 Agent、Host 或人的视图 | quota/status、Workspace、review packet |
| **Runtime** | 解释本轮 decision 并执行有界 effect | Codex App/CLI、heartbeat、extension provider |
-这些组件不是一条由 Runtime 随意覆盖的 JSON。Runtime 是 effect executor;authoritative state 与
+Runtime 是 effect executor;authoritative state 与
transition owner 才决定事实是否真的改变。
### L2:authoritative state 长什么样?
为了理解,可以先把理想的 Goal 控制面想象成下面的**概念聚合视图**。它描述希望一次读取能够
-回答的问题,不是 LoopX 1.0 已经提供的统一 schema:
+回答的问题:
```yaml
GoalControlSnapshot: # 概念视图;字段是待回答的问题,不是已实现字段名
@@ -209,7 +205,7 @@ acceptance、permissions 和 terminal conditions 目前还没有统一的 typed
### L3:Agent 怎样修改 authoritative state?
-Agent 提交的是 proposal 或 typed effect,不是“我认为新状态应该长这样”的全量覆盖:
+Agent 提交的是 proposal 或 typed effect:
```mermaid
flowchart TD
@@ -223,7 +219,7 @@ flowchart TD
Readback --> Next["派生下一条合法动作"]
```
-这里的“CAS”是并发控制原则,不是假装全仓只有一个整数 `version`:
+这里的“CAS”是并发控制原则:
- Todo completion 会在取得 mutation lock 后比对 admission 相关的字段快照(`status`、`completion_continuation`、`successor_todo_ids`、`validation_command_argv` 等),快照不一致即拒绝,确保针对某份声明的 validation 不能授权另一份已持久化的 Todo;
- shared authority store 以 opaque `expected_provider_revision`(file provider 中对应 generation)做真正的 compare-and-swap;`authority_revision` 和 `lease_epoch` 不能代替它;
@@ -237,8 +233,7 @@ flowchart TD
[`coordination/authority_core.py`](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/coordination/authority_core.py)
和 [`settlement.py`](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/turn_driver/settlement.py)。
-所以正确流程是“读 basis -> 提案 -> 验证/guard -> guarded commit -> 事件或 receipt -> 回读”,而不是
-Agent 直接覆盖一份看似完整的状态。
+所以正确流程是“读 basis -> 提案 -> 验证/guard -> guarded commit -> 事件或 receipt -> 回读”。
### L4:Agent 判断错了怎么办?
@@ -255,14 +250,14 @@ Agent 直接覆盖一份看似完整的状态。
这也是为什么 side effect 必须独立建模:模型可以改主意,外部世界却不能靠改一段上下文回滚。
LoopX 通过 validation、版本/identity guard、reconcile、补偿事件和 replan,把错误变成下一条可验证
-transition,而不是让它成为一段失去来路的聊天结论。这里的幂等恢复保证有明确边界:它适用于带
+transition。这里的幂等恢复保证有明确边界:它适用于带
持久 journal、`effect_ref` 和 provider readback resolver 的 settlement step;不能外推成“任意外部工具
调用都会自动去重”。resolver 缺失、报错或返回未知状态时,settlement 会 fail closed。
## 九组状态机怎样组成一条 Loop
现在把刚才那条时间线接回整条循环。维护者级地图把控制面拆成九组协作状态机;“九”是当前
-核心规则的教学地图,不是一个要求所有 extension 都注册九台 runtime service 的协议常量。
+核心规则的教学地图。
本书按读者任务把它们组织为四层:
| 层 | 主要机器 | 回答的问题 |
@@ -293,8 +288,7 @@ flowchart TD
```
图中没有从 projection 直接连回 decision 的写入捷径。界面只能发起受治理动作;真正的 state
-transition 仍由 write API、validation 和 receipt 完成。箭头表示事实和 contract 的依赖关系,
-不是状态机之间的进程消息。
+transition 仍由 write API、validation 和 receipt 完成。箭头表示事实和 contract 的依赖关系。
## 1. 持久工作:Todo、Gate 与 Handoff
@@ -307,8 +301,7 @@ transition 仍由 write API、validation 和 receipt 完成。箭头表示事实
open | done | blocked | deferred
```
-`claimed_by`、`resume_when`、`superseded_by`、`unblocks_todo_id` 和 `no_followup` 是正交字段,
-不是更多 status。它们共同决定下一条合法路径。
+`claimed_by`、`resume_when`、`superseded_by`、`unblocks_todo_id` 和 `no_followup` 是正交字段。它们共同决定下一条合法路径。
```mermaid
stateDiagram-v2
@@ -383,7 +376,7 @@ flowchart LR
| `deferred` | resume condition 尚未满足 | 等待或观察条件 |
这些值是 projection,不应被手工写入。修复 `cleared_without_successor` 的方式是新增合法 successor、
-重开工作或记录 `no_followup`,而不是把显示值改成 `cleared_with_successor`。
+重开工作或记录 `no_followup`。
## 2. 单轮执行:Quota、Interaction Contract 与 Settlement
@@ -402,8 +395,7 @@ flowchart LR
7. paused
```
-这是 reducer 在多个条件同时出现时使用的 precedence,不是 `blocked_health` 会依次流转到 `paused`
-的状态图。每轮都从当前 source facts 重新判定。
+这是 reducer 在多个条件同时出现时使用的 precedence。每轮都从当前 source facts 重新判定。
| Runtime state | 本轮合法动作 | 常见恢复路径 |
| --- | --- | --- |
@@ -415,7 +407,7 @@ flowchart LR
| `throttled` | 不执行交付 | 等待 quota window 或 owner adjustment |
| `paused` | 不执行自动 Turn | 显式 resume;`active/stopped` 由 Goal activation owner 管理 |
-Quota state 不是单独的授权。`interaction_contract` 还会给出 user、agent、CLI channel、workspace
+`interaction_contract` 还会给出 user、agent、CLI channel、workspace
guard、capability gate、selected Todo、execution obligation 和 scheduler hint。Agent 必须执行的是
`must_attempt_work` 是布尔 obligation:为 `true` 时,本轮必须尝试 bounded work 并写回;它本身不选择
动作。需要选择 Todo 时先执行 `selection_command`,否则执行 capability packet 或
@@ -543,7 +535,7 @@ Goal 返回 `canonical_authority_required`,必须先备份并迁移,之后
### Agent Vision / replan:路线改变必须成为 state delta
-Vision 是 per-Agent 的有界可执行路线,不是 scratchpad。正常延续可以提交
+Vision 是 per-Agent 的有界可执行路线。正常延续可以提交
`vision_unchanged_reason`;假设、scope、acceptance 或 route 发生 material change 时,必须提交
bounded Vision patch,并同步 Todo / acceptance delta。
@@ -567,8 +559,7 @@ stateDiagram-v2
### Goal activation 不等于 automation 已启用
-Goal activation 的 typed source 只有 `active` 与 `stopped`。`active` 表示控制面允许继续评估,
-不证明已经安装 Host heartbeat,也不证明当前有 eligible work。完整 onboarding 还要经过:
+Goal activation 的 typed source 只有 `active` 与 `stopped`。`active` 表示控制面允许继续评估。完整 onboarding 还要经过:
```text
project registered
@@ -596,7 +587,7 @@ public/private boundary。
## LoopX 怎样体现“闭环”
-LoopX 的闭环不是“Agent 做了一件事”,也不是 `Todo=done`。更准确的定义是:**一次 effect 的结果
+更准确的定义是:**一次 effect 的结果
经过验证后写回负责该事实的 authoritative source,并且控制面能据此派生出下一条合法动作,或证明
应当停止。**
如果结果只留在聊天、工作区文件、远端系统或 dashboard 文案里,没有 readback、durable writeback
@@ -633,7 +624,7 @@ flowchart TD
1. **结果回来了没有?** 外部 effect 必须有 typed observation 或 readback;“命令退出 0”不能替代
provider、PR、文件 revision 或部署状态的权威回读。
2. **结果落盘了吗?** validation 通过后,evidence、Todo outcome、Vision checkpoint 和 Next Action
- 必须通过 owner write API 持久化;聊天总结不是 writeback。
+ 必须通过 owner write API 持久化。
3. **下一步有归宿吗?** 完成一个 Todo 后必须存在 runnable successor、明确 Gate、带
`resume_when` / `next_due_at` 的等待、repair/replan obligation,或者有证据的 `no_followup`。
4. **Host 知道继续还是停止吗?** scheduler apply 必须有 ACK 或 failure receipt;下一次唤醒重新读取
@@ -677,7 +668,7 @@ coverage-backed `no_followup` 都可以诚实收口;关键是结果可追溯
9. **投影:** Workspace 显示文档已完成、首页仍待决定。界面没有吞掉或扩大 Gate scope。
如果第 5 步失败,流转停在 validation;如果第 6 步失败,不得进入 spend;如果第 8 步 Host 更新
-失败,记录 failure receipt 并有界重试,而不是宣称 cadence 已生效。
+失败,记录 failure receipt 并有界重试。
## 从症状定位 owner
@@ -759,8 +750,8 @@ owner、协议 schema、characterization fixture 和 migration boundary。
**失败三:投影被当成事实源。** dashboard 上改一个 row 让显示正确,source 没变。症状是
UI 与 CLI 长期不一致,而每次刷新都回到旧值。恢复方式是修 source 或 builder,再 readback。
-**失败四:停止的理由并不等于闭环。** Goal `stopped`、quota paused 或 peer coordination blocked
-都可能停止轮询,它们各自是合法停止,但不证明 Goal 闭环。只有 `terminal_no_followup` 表达
+Goal `stopped`、quota paused 或 peer coordination blocked
+都可能停止轮询,它们各自是合法停止。只有 `terminal_no_followup` 表达
"因已验证 Goal closure 而停止"。把这几者混作一谈,会让一个被暂停的 Goal 看起来像已完成。
## 不变式
@@ -774,7 +765,7 @@ UI 与 CLI 长期不一致,而每次刷新都回到旧值。恢复方式是修
处理拒绝结果。
5. **终局是合取。** 完整且闭合的 Todo source、没有未解决 frontier、结构化 `no_followup`
intent,三者同时成立才算闭环。
-6. **教学地图不等于实现规格。** 改规则先确认 typed owner、协议 schema、characterization
+6. 改规则先确认 typed owner、协议 schema、characterization
fixture 和 migration boundary。
这六条回答的是同一个问题:**当机制被拆到九组机器、又只能通过持久事实互相说话时,凭什么
diff --git a/docs/book/chapters/source-change-control-plane-rule.md b/docs/book/chapters/source-change-control-plane-rule.md
index 034040ae4e..d073828a89 100644
--- a/docs/book/chapters/source-change-control-plane-rule.md
+++ b/docs/book/chapters/source-change-control-plane-rule.md
@@ -416,8 +416,7 @@ invariant、画完协议链,通常要几个小时。换到的东西是:这
**边界一:full validation 跑不起全套,这是设计如此。** 本仓库的 [PR 基线](https://github.com/loopx-project/loopx/blob/main/docs/development/testing-and-quality.md) 包含 lint、type、
output budget smoke、`pytest` 分层、`loopx canary premerge --from-git-diff` 和 public/private
scan;真实路径验证(例如 PostgreSQL integration)需要一个一次性隔离实例。开发阶段应当从最
-聚焦的那条命令开始,无需等最宽矩阵。完整公开 smoke fleet 的职责是宽覆盖与健康观察,不是
-每个 PR 的语义设计。
+聚焦的那条命令开始,无需等最宽矩阵。完整公开 smoke fleet 的职责是宽覆盖与健康观察。
**边界二:真实路径不可用时,正确做法是报告证据缺口。** 如果影响 PostgreSQL authority 的
改动拿不到安全的隔离实例,那么"跳过该套件"并不构成通过。此时应暂停交付并说明缺口,不能用
@@ -451,8 +450,7 @@ diff 和描述来发现,这也是为什么下一章把 PR 描述本身当成
**让 renderer 修 policy。** 修改文案不能修复 source 或 authority;反过来,policy 也不应依赖 Markdown 字符串。
-**顺手重构所有相关模块。** 协议链跨多个 bounded context,不等于这个 PR 应当包含每一次可能的
-清理。只改本次 invariant 所要求的完整链条。
+**顺手重构所有相关模块。** 协议链跨多个 bounded context。只改本次 invariant 所要求的完整链条。
**为未来 Host 增加空 adapter。** 没有真实调用方、capability 和 receipt 的 adapter 只增加
维护面,而且它会看起来像一项已经交付的能力。
diff --git a/docs/book/chapters/source-protocol-map.md b/docs/book/chapters/source-protocol-map.md
index be06c6307e..8f7aef9126 100644
--- a/docs/book/chapters/source-protocol-map.md
+++ b/docs/book/chapters/source-protocol-map.md
@@ -12,8 +12,7 @@
- **命中的数量不说明任何事。** 一个权限概念通常在十几个模块里出现——schema、parser、projection、renderer、decision table、test fixture。它们在同一个概念上扮演完全不同的角色。
- **文件会移动,协议责任不会。** 迁移把完整 transaction 的语义搬到了另一侧;按目录名建立的直觉会在下一个版本直接失效。
-- **评审看到的是一份函数清单。** 如果 PR 描述只能说“我改了这三个函数”,reviewer 无法判断被破坏的是哪条不变量,也无法判断在什么条件下应该拒绝它。
-- **测试全绿不代表切片正确。** 针对被改模块的回归测试,恰好会为错误的解释背书。
+- **评审看到的是一份函数清单。** 如果 PR 描述只能说“我改了这三个函数”,reviewer 无法判断被破坏的是哪条不变量,也无法判断在什么条件下应该拒绝它。 针对被改模块的回归测试,恰好会为错误的解释背书。
所以需要一条更慢但更稳定的入口:先说清自己正在改变哪份合同,再去找实现。本章给的是这条入口。
@@ -30,7 +29,7 @@
-> 当前实现与验证
```
-本章给出一张协议优先的源码地图。它不列完整 API,也不要求你记住当前版本的函数名;目标是让你在准备一个 Issue 或 PR 时,先说清自己正在改变哪份合同。
+本章给出一张协议优先的源码地图。目标是让你在准备一个 Issue 或 PR 时,先说清自己正在改变哪份合同。
## 读完之后你应该能
@@ -291,9 +290,9 @@ source facts
| 操作投影 | status/frontstage/projection owner;renderer 只消费 typed read model |
| 文档与验证 | owning protocol 文档、`tests/`、`examples/` 或 public-safe fixture |
-当前 capability 目录采用 package-owned documentation 与 `catalog_entry.py` 注册。贡献前运行 `loopx capability list --format json` 和 `loopx capability show --format json`,确认 capability 是否真实注册、有哪些 entry command、Provider 边界与 durable validation。仅有 目录或 README 不证明能力已经发布。
+当前 capability 目录采用 package-owned documentation 与 `catalog_entry.py` 注册。贡献前运行 `loopx capability list --format json` 和 `loopx capability show --format json`,确认 capability 是否真实注册、有哪些 entry command、Provider 边界与 durable validation。
-`loopx/capabilities//` 中有代码不自动证明它是公开 Capability;需要显式注册和真实 caller contract。`loopx/extensions/` 也不是“所有外部集成”的收纳箱:只有独立 provider lifecycle 才属于这里。私有 helper 留在最近的 owner 中,不因为跨了几个文件就升级为新 Capability 或 Extension。
+`loopx/capabilities//` 中有代码不自动证明它是公开 Capability;需要显式注册和真实 caller contract。`loopx/extensions/` 独立 provider lifecycle 才属于这里。私有 helper 留在最近的 owner 中,不因为跨了几个文件就升级为新 Capability 或 Extension。
## 函数名是搜索锚点,不是课程目录
@@ -381,7 +380,7 @@ acceptance、terminal closure、quota budget 与 monitor cadence 四个可检查
先从 [RFC Index](https://github.com/loopx-project/loopx/blob/main/docs/architecture/rfcs/README.md)
读取正式状态。`Accepted`、`Active research`、`Draft` 与 `Draft integration proposal` 允许的动作
-不同;一份 RFC 或 Discussion 存在,不等于某个实现已经发布,也不自动生成可认领任务。
+不同。
@@ -413,7 +412,7 @@ disposition,并指出 owner、下一产物与复核条件。需要跨方向同
> 重构 status、quota、scheduler 和所有测试。
-缩小切片并不等于减少行数,它要保持一条完整因果链:
+缩小切片要保持一条完整因果链:
```text
source
@@ -459,10 +458,10 @@ grep -rln "required_decision_scopes" loopx/control_plane/todos/ | head
准备进入源码前,确认下面几条能独立成立:
-1. **一条规则的所有者是决定合法转换的模块,不是首次打印相关字样的模块。** 如果无法指出被保护的不变量,这次改动还没有定位到位。
+1. **一条规则的所有者是决定合法转换的模块。** 如果无法指出被保护的不变量,这次改动还没有定位到位。
2. **PR 描述里必须有一条完整的因果链:source、invariant、decision、projection 或 effect、receipt、validation。** 只能列出函数名的切片无法被评审。
3. **文档描述责任归属,代码描述当前行为。** 两者冲突时,按冲突类型选择权威,并让这次 PR 把另一方更新掉。
-4. **`loopx/capabilities//` 下有代码,不证明该 Capability 已经发布。** 注册与真实 caller contract 才是发布判据,用 `loopx capability list --format json` 核对。
+4. 注册与真实 caller contract 才是发布判据,用 `loopx capability list --format json` 核对。
5. **placement 先于实现。** capability id、provider id 与 built-in/extension-delivered 的选择,必须在写第一行代码之前写下理由。
6. **任务来自公开入口。** 公开的 Contributor Task、Issue 和 fixture 是可参与工作的唯一来源,live active state 与 maintainer-local 判断都不算。
diff --git a/docs/book/chapters/source-trace-protocol-chain.md b/docs/book/chapters/source-trace-protocol-chain.md
index bc4b69054f..39fa67963b 100644
--- a/docs/book/chapters/source-trace-protocol-chain.md
+++ b/docs/book/chapters/source-trace-protocol-chain.md
@@ -34,8 +34,7 @@
- **测试覆盖的是你想到的消费者。** 单元测试断言的是被改模块的行为,它不会替你发现另一个模块正在用不同方式读同一个字段。
- **消费关系跨语言、跨层。** 同一个字段可能被 schema 校验、被 parser 归一化、被 projection 重命名、被 renderer 格式化。这四处会分别演进,彼此并不引用。
-- **缺失字段有默认值,而默认值会做出决定。** 缺失被回退成空集合、`None` 或空串时,系统不会报错,它会继续用这个默认值参与判定。这是坏结局最隐蔽的来源。
-- **成功返回值不是证据。** 每一层都成功,合起来仍可能是错的。
+- **缺失字段有默认值,而默认值会做出决定。** 缺失被回退成空集合、`None` 或空串时,系统不会报错,它会继续用这个默认值参与判定。这是坏结局最隐蔽的来源。 每一层都成功,合起来仍可能是错的。
所以调试的问题要换掉。不要问“最终 JSON 为什么不对”,要问“**第一处违反不变量的边界在哪里**”。
@@ -100,7 +99,7 @@ typed Todo / Gate facts
## 第 1 站:Source facts 是否足够表达意图
-先检查 Todo 与 Gate 的 typed facts。下面是**为解释而简化**的形状,不是可直接导入的配置:
+先检查 Todo 与 Gate 的 typed facts。下面是**为解释而简化**的形状:
```json
{
@@ -221,7 +220,7 @@ open work
- `repair-link-checker` 不依赖该 Gate,仍在 frontier;
- Gate 本身继续进入 user channel。
-这不是“安全绕过 Gate”。安全路径没有执行被 Gate 覆盖的 action。
+安全路径没有执行被 Gate 覆盖的 action。
### Ordered policy,而非零散布尔值
@@ -486,7 +485,7 @@ grep -rn "or \[\]\|or ()\|or {}\|\.get(.*, \[\])\|\.get(.*, {})" loopx/control_p
追踪结束后,下面几条应该能独立成立:
1. **每个被改名或改语义的字段,都要能列出全部消费者。** 只改生产者不算完成,缺失字段的回退值算一次消费者。
-2. **链上每一层返回成功,不构成链路正确的证据。** 判断依据是第一处违反不变量的边界,而非最终返回值。
+2. 判断依据是第一处违反不变量的边界,而非最终返回值。
3. **缺失字段的默认值会参与判定。** 因此必须明确写出它是 reject、repair 还是 compatibility fallback。
4. **authority 只有一份 canonical 来源。** 多处可以读同一个字段,只有一处拥有它;读取方被误当成 owner 是跨层变更最常见的解释残留。
5. **判断 authority 时以协议文档为准,判断当前行为时以源码为准。** 两者冲突时按冲突类型选权威,并让同一次改动把另一方更新掉。
diff --git a/docs/book/chapters/source-validation-to-pr.md b/docs/book/chapters/source-validation-to-pr.md
index dc23375458..847dbcfaf1 100644
--- a/docs/book/chapters/source-validation-to-pr.md
+++ b/docs/book/chapters/source-validation-to-pr.md
@@ -34,7 +34,7 @@ public/private scan;完整公开 smoke fleet 是另一回事。更慢的是真
authority 的改动需要一个一次性隔离实例,跑完整套件是分钟到十几分钟量级。每个 PR 都等最宽矩阵,
代价会摊到所有贡献者身上。
-**跑得多不等于覆盖对。** 一百个命令如果都落在同一层,结论仍然只有一层。开头情境中的检查覆盖的是内存中的规则与静态约束,仍需补充受影响后端的证据。
+一百个命令如果都落在同一层,结论仍然只有一层。开头情境中的检查覆盖的是内存中的规则与静态约束,仍需补充受影响后端的证据。
**有些结论需要人工判断。** 自动检查可以提示默认行为变化是否有说明,但披露是否准确、证据是否覆盖真实影响,仍需要 review。
@@ -73,7 +73,7 @@ ambiguous scope -> typed repair
explicit global scope -> global gate
```
-这层最适合证明具体 invariant,但不证明 CLI、projection 与 scheduler 已正确串联。
+这层最适合证明具体 invariant。
### 2. Focused deterministic smoke
@@ -315,7 +315,7 @@ git diff --check
loopx check --scan-path
```
-协议文档若改变 shipped behavior,还应运行对应 contract/smoke;"只改 Markdown"不代表行为风险为零。
+协议文档若改变 shipped behavior,还应运行对应 contract/smoke。
### Python 规则 PR
@@ -574,7 +574,7 @@ ownership 与 receipt。共享同一套新规则的多个 provider 互相一致
记录可重放命令或脚本调用、真实受影响后端、不可变 fixture 指纹、退出状态与归一化观测指纹。
需要说明的是,这条要求在实现上被投影成 review packet 里的一项检查,而 packet 测试只证明要求
-被投影,并不证明 reviewer 真的执行了它,更不证明产品无缺陷。这正是它为什么必须和"默认行为
+被投影。这正是它为什么必须和"默认行为
披露"归为同一类:**这类义务的最后一个执行者是 review,绝非 CI。**
## 两个真实社区贡献案例
@@ -731,7 +731,7 @@ Projection/Docs/fixtures 与 Extension 等贡献面会有不同的最近验证
1. **每一项验证都要对应一个具名风险。** 对应不上的命令属于惯例,构不成本 PR 的证据。
2. **期望值先于实现。** 从当前输出反推的断言只能做 characterization,不能作为 correctness
authority。
-3. **跳过不等于通过。** 拿不到隔离环境时,正确动作是报告证据缺口并暂停交付。
+3. 拿不到隔离环境时,正确动作是报告证据缺口并暂停交付。
4. **默认行为变化有三件必做:重命名 smoke、更新 docs/release note、点名受影响 lane。**
漏掉第一件的测试仍然是绿的,这正是它危险的原因。
5. **merged、released、deployed、observed 是四种状态。** 不能用前一种的证据宣称后一种。
diff --git a/docs/book/chapters/state-substrate.md b/docs/book/chapters/state-substrate.md
index 98011d6222..a51a4282e2 100644
--- a/docs/book/chapters/state-substrate.md
+++ b/docs/book/chapters/state-substrate.md
@@ -1,6 +1,6 @@
# 持久状态与只读投影
-接手一项任务时,最先遇到的问题通常是:哪一份记录代表当前状态?Todo、dashboard、聊天和历史回执可能各自描述不同时间点。能读到旧信息,并不等于能够安全继续。
+接手一项任务时,最先遇到的问题通常是:哪一份记录代表当前状态?Todo、dashboard、聊天和历史回执可能各自描述不同时间点。
## 同一条 Todo,为什么会看到两个状态
@@ -30,9 +30,9 @@ LoopX 在相应 authority 路径上采用最后一种分工。历史 R1 可以
### 精确复用 Goal,不靠文本猜测
-复用依赖 stable `goal_id` 与 registry 路由。多个 Goal 存在时,`start-goal --guided` 提供只读选择,再按精确 id 重跑;相似目标文本不构成静默合并的依据。
+复用依赖 stable `goal_id` 与 registry 路由。多个 Goal 存在时,`start-goal --guided` 提供只读选择,再按精确 id 重跑。
-复用 Goal 和接管 Agent 是不同操作。新会话可以读取原 Goal,但 fresh `agent_id`、已有 lane 的明确复用以及执行 lease 仍有各自的检查。旧聊天或 receipt 不授予新执行者写入权。
+复用 Goal 和接管 Agent 是不同操作。新会话可以读取原 Goal,但 fresh `agent_id`、已有 lane 的明确复用以及执行 lease 仍有各自的检查。
### Todo 存储取决于选定的事实源
@@ -44,7 +44,7 @@ LoopX 在相应 authority 路径上采用最后一种分工。历史 R1 可以
| 已选择 canonical provider 的路径 | 对应 authority 的 Todo snapshot | 兼容工作台或投影 | 以 provider revision 和生命周期读回为准 |
| 旧 Todo `events.jsonl` 实验 | 已退役,不是当前恢复入口 | 不能据旧示例恢复为 authority | 非空旧源需按退役合同处理,不能忽略或清空来过检查 |
-旧 Todo event API、replay、backfill 和 completion 示例已退役,见[退役合同](/loopx/docs/reference/protocols/event-sourced-state-contract-v0/)。这不等于 run history、quota events 或 `rollout_event_log` 也被退役;它们仍有各自的记录职责。
+旧 Todo event API、replay、backfill 和 completion 示例已退役,见[退役合同](/loopx/docs/reference/protocols/event-sourced-state-contract-v0/)。它们仍有各自的记录职责。
## 五类状态表面
@@ -111,7 +111,7 @@ Goal state 保留当前生命周期事实。一次 run 说测试通过,需要
}
```
-这里列的是事实类别与受控写入入口,不是声明所有状态都存进同一种介质。每个字段仍需回到其 owner 和当前 authority 路径解释。
+这里列的是事实类别与受控写入入口。每个字段仍需回到其 owner 和当前 authority 路径解释。
Task graph、Agent management 等投影也声明 `projection_is_writable: false`、`write_api: false`。这些字段描述消费者合同;真正的权限仍由 lifecycle writer 检查,不能仅靠 JSON 中一条声明证明所有入口安全。
@@ -121,11 +121,11 @@ Task graph、Agent management 等投影也声明 `projection_is_writable: false`
[本地写正确性协议](/loopx/docs/reference/protocols/local-state-write-correctness-v0/)用 `prepare -> preview -> apply -> record -> project` 描述目标边界:检查预期 revision,保护相应 lease,提交可读回结果,再更新展示。
-协议仍按 writer 分阶段落实。使用时应核对该命令、authority 模式和 provider 的实际验证,而不是把 draft 中的 hard idempotency、CAS 和 lease enforcement 一次性套到全部 legacy 路径。
+协议仍按 writer 分阶段落实。使用时应核对该命令、authority 模式和 provider 的实际验证。
### 历史基线与当前交付边界
-`v0.5.4` 的 shared-authority 工作引入 provider-neutral TypeScript `AuthorityStore` contract 与候选 provider 验证。后来的本地切换、fencing、projection 和默认入口采用有各自的里程碑;历史版本的能力不应倒推成当前所有路径的上限,也不能把候选资格当成远端服务已交付。
+`v0.5.4` 的 shared-authority 工作引入 provider-neutral TypeScript `AuthorityStore` contract 与候选 provider 验证。后来的本地切换、fencing、projection 和默认入口采用有各自的里程碑。
File/SQLite 的当前本地 authority 路径,应按选定 Goal 的 readback 判断。NoKV/PostgreSQL 等阶段性候选不自动获得 runtime authority;安装 Provider 本身也不改变现有 Goal 的事实源。
diff --git a/docs/book/chapters/work-graph-and-authority.md b/docs/book/chapters/work-graph-and-authority.md
index 047ee2a055..a22ea87aed 100644
--- a/docs/book/chapters/work-graph-and-authority.md
+++ b/docs/book/chapters/work-graph-and-authority.md
@@ -1,6 +1,6 @@
# 工作图、权限与 Peer 协作
-A 可以实现 JSON,B 可以补文档,维护者仍未批准发布。这三件事可以同时成立。工作图的价值是把它们表达成有身份、有依赖和有接受条件的工作,而不是让“有人正在做”成为所有动作的许可。
+A 可以实现 JSON,B 可以补文档,维护者仍未批准发布。这三件事可以同时成立。工作图的价值是把它们表达成有身份、有依赖和有接受条件的工作。
本章先分清工作归属、执行证明与决定范围,再走一次交接和集成。实际写入仍由当前 authority、handoff mode 与对应 writer 校验;本章不新增一个统一授权者。
@@ -26,11 +26,11 @@ A 可以实现 JSON,B 可以补文档,维护者仍未批准发布。这三
| 这个执行实例现在可以提交吗? | 适用模式的 lease、当前 owner/key/version 与 writer fence | 原 acquire 曾成功 |
| 这个具体动作被允许吗? | Goal/repository 权限、Gate scope、能力和工作区要求 | 工具可调用、目录可写或 quota 有余额 |
-Agent identity 是工作 lane,不证明具体 Host,更不证明组织职级。`claimed_by` 表达归属而不是进程活性;lease 的有效性也不能证明模型判断正确。外部服务最终是否拒绝旧执行者,还取决于那个写入端实际执行的约束,不能从本地 lease 推导出全系统围栏。
+Agent identity 是工作 lane。`claimed_by` 表达归属。外部服务最终是否拒绝旧执行者,还取决于那个写入端实际执行的约束,不能从本地 lease 推导出全系统围栏。
## Gate 覆盖动作,不靠数量冻结全局
-G1 限制 T3 的 publication scope。T2 如果确实独立且自己的条件满足,可以继续;G1 仍应在用户通道中可见。独立 fallback 不是绕过 Gate,而是根本没有执行被它覆盖的动作。
+G1 限制 T3 的 publication scope。T2 如果确实独立且自己的条件满足,可以继续;G1 仍应在用户通道中可见。独立 fallback 是根本没有执行被它覆盖的动作。
```text
G1: publication scope 尚未批准
@@ -46,7 +46,7 @@ scope 缺失或矛盾时不能猜成批准,也不能为了省事创造一个
当前 `handoff_mode` 决定适用约束:默认 `legacy` 保留软 claim / hard lease 的兼容路径,`soft_claim` 与 `hard_lease` 有自己的规则。部分 legacy terminal 路径可以出现 `terminal_fence_not_required`。因此,不能把一种模式上的回归测试推广为全部 writer 的强互斥证明。
-对已经提升的 File/SQLite authority,精确读取应来自选定 provider;读取失败不退回旧 lease 文件。来源选择、registration 和当前 Todo 约束与 lease 共同参与判断。`task-lease inspect` 是一次观察,不是跨后续操作持有的锁。
+对已经提升的 File/SQLite authority,精确读取应来自选定 provider;读取失败不退回旧 lease 文件。来源选择、registration 和当前 Todo 约束与 lease 共同参与判断。`task-lease inspect` 是一次观察。
| 生命周期动作 | 在适用合同中表达什么 | 调用者需要保留什么 |
| --- | --- | --- |
@@ -75,7 +75,7 @@ flowchart TD
P --> W["受控执行、验证、提交"]
```
-同名 Agent、重新启动的终端和旧成功截图都不是绕过该过程的方法。`version_mismatch` 应触发当前状态核对;release 后的 `idempotency_key_reuse` 不通过修改历史 key 来“修复”。
+`version_mismatch` 应触发当前状态核对;release 后的 `idempotency_key_reuse` 不通过修改历史 key 来“修复”。
## 从交接到集成:把一次协作走完 {#handoff-to-integration}
@@ -83,17 +83,17 @@ flowchart TD
**第一步,A 返回具体产物。** T1 的回报引用 C1、验证声明和结果,以及尚未满足的 M1/G1。不能只写“JSON 已完成”。
-**第二步,B 确认采用哪份输入。** B 的文档基于 C1 的字段约定;若无法访问该产物,问题是交接输入缺失,而不是需要重新实现 T1。Handoff 使用 bounded refs 和合法读取入口,不把全部私有 transcript 复制到公开 packet。
+**第二步,B 确认采用哪份输入。** B 的文档基于 C1 的字段约定;若无法访问该产物,问题是交接输入缺失。Handoff 使用 bounded refs 和合法读取入口,不把全部私有 transcript 复制到公开 packet。
**第三步,当前归属合法转换。** Lease 转移与 Todo claim 是否同时改变,由所选命令合同决定。不要假设 lease-only transfer 自动改 claim,也不要在要求原子交接的路径上拆成两次手工写。接收方仍须满足 registration、binding、exclusion、scope 和 workspace 条件。对应操作说明以[canonical lease reference](https://github.com/loopx-project/loopx/blob/f49b4a00870604d39fa4318da24d6dd35e72bb6e/docs/reference/canonical-lease-renew.md)中的版本范围为准。
-**第四步,分别验证以后再验证组合。** T1 的代码检查和 T2 的示例检查只证明各自结果;集成者要检查两者在同一个候选版本上是否一致。两个分支都绿,不是组合提交也绿。
+**第四步,分别验证以后再验证组合。** T1 的代码检查和 T2 的示例检查只证明各自结果;集成者要检查两者在同一个候选版本上是否一致。
-**第五步,变化沿依赖传播。** A 将 C1 修正为 C2 时,B 检查字段或行为变化是否影响文档与验证。保留原历史,只更新受影响结论;已经基于 C1 完成的工作不是自动作废,也不是自动适用于 C2。
+**第五步,变化沿依赖传播。** A 将 C1 修正为 C2 时,B 检查字段或行为变化是否影响文档与验证。保留原历史,只更新受影响结论。
**第六步,结果回到接受者。** 由 T3 对当前产物与决定再做判断。消息送达、接收者采用输入、工作被接受、发布被允许、外部交付发生,各有证据;不能用其中一项代替其余全部。
-这个六步过程是教学案例,不是在声明系统会自动完成所有跨 Host、跨设备或跨仓库编排。协作是否成功,必须检查用户所需的关系是否真正闭合。
+这个六步过程是教学案例。协作是否成功,必须检查用户所需的关系是否真正闭合。
## 工作区隔离不等于集成正确 {#parallel-editing}
@@ -110,7 +110,7 @@ flowchart TD
| 两份改动独立验证通过 | 各自产物满足已检查条件 | 组合后行为正确 |
| 集成验证通过 | 当前组合满足相关检查 | 有合并、远端写入或发布权限 |
-该模式是合作式代码编辑协调,不是 OS sandbox。旧 grant 不会因读取或续租自动升级为新模式;需要变更执行意图时,按当前生命周期退役并重新取得证明。安装 provider 或改变目录名不构成提升与授权。
+该模式是合作式代码编辑协调。旧 grant 不会因读取或续租自动升级为新模式;需要变更执行意图时,按当前生命周期退役并重新取得证明。
## 依赖与后继怎样保持可追溯
@@ -118,7 +118,7 @@ flowchart TD
跨仓库依赖需要正确 repository identity。`pr_merged:#123` 可以由 Todo 的 GitHub `task_repository` 解析仓库;显式 `pr_merged:owner/repo#123` 直接指定对象。两者都不能确定仓库时,不按相同编号猜测。
-Successor 表达下一项有身份的工作;supersede 保留旧工作与替代关系(对应生命周期会把 predecessor 记为 done 并标记替代);no-follow-up 说明为什么这一条路线不再需要后继,不能自动等同 Goal 全部验收。`independent_handoff` 与 `same_agent_non_delivery` 表达不同 continuation policy,按实际写回读取而不是从 prose 推断。
+Successor 表达下一项有身份的工作;supersede 保留旧工作与替代关系(对应生命周期会把 predecessor 记为 done 并标记替代);no-follow-up 说明为什么这一条路线不再需要后继,不能自动等同 Goal 全部验收。`independent_handoff` 与 `same_agent_non_delivery` 表达不同 continuation policy,按实际写回读取。
## 用具名证据核对边界
@@ -129,6 +129,6 @@ Successor 表达下一项有身份的工作;supersede 保留旧工作与替代
| 旧 writer 不能绕过已生效来源 | `test_legacy_coordination_writer_fence.py` | 旧模式已被全局删除 |
| runtime root override 不绕过来源围栏 | `test_split_root_todo_writeback_fence.py` | 改一个 CLI 参数就能获得新权限 |
-这些测试属于各自固定输入和 writer 的证据,不是运行中的 Goal 已经健康的证明。练习和断言解释见[lease 检查](12-control-plane-course.md#checkpoint-lease);实际取证入口见[附录](appendix-reference.md#read-before-change)。
+这些测试属于各自固定输入和 writer 的证据。练习和断言解释见[lease 检查](12-control-plane-course.md#checkpoint-lease);实际取证入口见[附录](appendix-reference.md#read-before-change)。
协作的最终标准是:接手者知道接受了什么,当前执行者具有什么资格,组合结果由谁验证,剩余决定由谁负责。范围、证明或输入不清楚时先补齐这一处关系,不重新分派全部任务碰碰运气。
diff --git a/docs/book/chapters/workspace-v1.md b/docs/book/chapters/workspace-v1.md
index ea78827ba8..dc443e37e8 100644
--- a/docs/book/chapters/workspace-v1.md
+++ b/docs/book/chapters/workspace-v1.md
@@ -4,7 +4,7 @@
## 一个界面看起来正常的下午 {#pause-readback}
-以下是合成诊断情境,不是一次已核实的生产事故。
+以下是合成诊断情境。
```text
14:02 operator 打开 Workspace。Manager 总览显示 3 个 Goal,"执行中"车道有两张卡片。
@@ -30,15 +30,13 @@
Workspace 呈现和发起受治理的动作,但 Goal、Todo、Gate、事件、配置和回执仍然由控制面事实源拥有。这带来三个不可避免的后果:
-- **投影会滞后。** 页面上的状态是某个时刻的读模型;在你看到它和它被生成之间,源状态可能已经变化。
-- **HTTP 成功不是写入完成。** 请求被接受和执行完成是两件事,中间可能被 Gate 拦下、被 stale 检查拒绝。
-- **按钮不是独立的授权者。** Goal stop/resume 由 owner 权限与已审核 fingerprint 校验;Todo 操作由生命周期规则校验;自动 Turn 的可运行性再由 quota decision 判断。
+- **投影会滞后。** 页面上的状态是某个时刻的读模型;在你看到它和它被生成之间,源状态可能已经变化。请求被接受和执行完成是两件事,中间可能被 Gate 拦下、被 stale 检查拒绝。 Goal stop/resume 由 owner 权限与已审核 fingerprint 校验;Todo 操作由生命周期规则校验;自动 Turn 的可运行性再由 quota decision 判断。
-所以本章的全部内容可以压成一句:**Workspace 是观察和发起动作的入口,不是一套新的事实源。**
+所以本章的全部内容可以压成一句:**Workspace 是观察和发起动作的入口。**
## 先确认运行时,再看页面
-页面出现不等于控制面健康。先核对版本和诊断,再启动或复用服务;`dashboard --no-open` 不是纯粹的状态查询:
+先核对版本和诊断,再启动或复用服务;`dashboard --no-open` 不是纯粹的状态查询:
```bash
loopx --version
@@ -53,7 +51,7 @@ curl -fsS http://127.0.0.1:8767/chat/ >/dev/null
curl -fsS http://127.0.0.1:8767/status.json
```
-`loopx dashboard` 同时提供打包后的 Workspace、状态投影和 Agent Chat。若相同版本的桌面壳已经启动了服务,它会复用通过 capability fingerprint 验证的进程,而不是启动第二套事实源。**端口只是默认值**;自动化检查应读取命令输出,不要把默认 URL 当成永久合同。
+`loopx dashboard` 同时提供打包后的 Workspace、状态投影和 Agent Chat。若相同版本的桌面壳已经启动了服务,它会复用通过 capability fingerprint 验证的进程。**端口只是默认值**;自动化检查应读取命令输出,不要把默认 URL 当成永久合同。
打开 Workspace 后,先做三项对应检查:
@@ -65,7 +63,7 @@ curl -fsS http://127.0.0.1:8767/status.json
## 把页面读回控制面问题
-Manager 的四条 lane 是 operator 投影,不是四种新的 Todo 状态:
+Manager 的四条 lane 是 operator 投影:
| Lane | 实际含义 |
|---|---|
@@ -94,7 +92,7 @@ Workspace 中的 Goal、Todo、Heartbeat、Monitor 与设置变更遵循同一
typed preview -> human or policy review -> governed apply -> verified receipt -> refreshed projection
```
-**Preview** 冻结规范化参数、影响范围和当前 revision。**Apply** 只能执行仍然匹配该 preview 的动作;状态已经变化时应返回 stale 或 Gate,而不是悄悄套用旧决定。**Receipt 与 readback** 才证明写入完成——按钮点击或 HTTP 成功本身都不够。
+**Preview** 冻结规范化参数、影响范围和当前 revision。**Apply** 只能执行仍然匹配该 preview 的动作;状态已经变化时应返回 stale 或 Gate。**Receipt 与 readback** 才证明写入完成——按钮点击或 HTTP 成功本身都不够。
以暂停 Goal 为例,第一条命令只预览:
@@ -146,7 +144,7 @@ Workspace 的 Lark / 飞书设置可以把一个 Goal 连接到具体 Topic 和
loopx lark-inbox drain --goal-id --agent-id
```
-Disconnect 只移除该 Goal 的 Topic route,不删除 Goal、Session、历史或其他连接。消息到达也不代表 Agent 获得发送、仓库写入或生产权限;这些动作继续通过各自的 Gate 与 Provider readback。
+Disconnect 只移除该 Goal 的 Topic route,不删除 Goal、Session、历史或其他连接。这些动作继续通过各自的 Gate 与 Provider readback。
## 一次生成与持续投递是两条授权链
@@ -158,7 +156,7 @@ loopx periodic-report inspect-profile --preset weekly --format json
回执中的 `active` 与 `generation_allowed` 应同时为 `true`。内置 weekly profile 没有 schedule,也没有 sink,因此**一次生成不会创建周期任务或发送消息**。
-持续报告是另一条授权链:自定义 profile 声明 cadence,Host Automation 负责唤醒;机器或 Goal subscription 的 `enabled: true` 与显式 `route_ref` 构成持续投递授权。暂停 Automation、禁用 profile 或关闭 subscription 会停止对应路径。报告生成成功不等于外部发送成功;Provider、发送身份、route 和消息 readback 仍需分别验证。
+持续报告是另一条授权链:自定义 profile 声明 cadence,Host Automation 负责唤醒;机器或 Goal subscription 的 `enabled: true` 与显式 `route_ref` 构成持续投递授权。暂停 Automation、禁用 profile 或关闭 subscription 会停止对应路径。Provider、发送身份、route 和消息 readback 仍需分别验证。
## 代价与边界
@@ -168,9 +166,9 @@ loopx periodic-report inspect-profile --preset weekly --format json
**代价三:需要理解四层"已启用"的区别。** 把它们压成一个开关会误判能力可用性,而分清它们需要额外的心智负担。
-**边界一:Workspace 不拥有事实。** 界面损坏不能证明控制面仍健康,也不能证明它已经停止。先区分 source、runtime 与 projection;只有源状态和运行条件确认正常时,才把故障限定为显示恢复,而不是通过界面手改状态。它也不构成 Stage 2C authority——shared-authority provider 的资格与提升由独立的 shadow 与 conformance 流程决定,不由某个操作面出现而成立。
+先区分 source、runtime 与 projection;只有源状态和运行条件确认正常时,才把故障限定为显示恢复。shared-authority provider 的资格与提升由独立的 shadow 与 conformance 流程决定。
-**边界二:桌面更新的范围有限。** 更新只能来自固定官方 feed;macOS 使用 updater signature 与 ad-hoc code signing,不应描述为 notarized。回退安装也不承诺逆转未来不兼容的 Goal schema。
+**边界二:桌面更新的范围有限。** 更新只能来自固定官方 feed;macOS 使用 updater signature 与 ad-hoc code signing,不应描述为 notarized。
**边界三:CLI 更新不能修复原生壳缺陷。** 浏览器 / PWA 用户继续使用 CLI update 流程;桌面壳的启动器或 updater 问题需要桌面侧处理。
@@ -188,10 +186,6 @@ loopx periodic-report inspect-profile --preset weekly --format json
## 不变式
-1. **界面是投影,不是事实源。** 每次重要判断前重新读一次源。
-2. **HTTP 成功不证明写入完成。** 只有 receipt 与 readback 能证明。
-3. **点击不构成授权。** Owner 操作由对应 Goal lifecycle 接受,Todo 由其生命周期校验,自动 Turn 由当前 quota contract 准入;页面不重新授予任何一种权限。
+1. 每次重要判断前重新读一次源。
+3. Owner 操作由对应 Goal lifecycle 接受,Todo 由其生命周期校验,自动 Turn 由当前 quota contract 准入;页面不重新授予任何一种权限。
4. **四种"已启用"需要分别证明。** 它们可以互为前提,但不能把一个开关的值当成所有条件均已满足。
-5. **消息到达不扩大权限。** Capture scope 与 ingress mode 都不授予新的写权限。
-
-这五条回答同一个问题:**当界面告诉你"一切正常"时,凭什么相信它?**
diff --git a/docs/book/en/chapters/00-reading-guide.md b/docs/book/en/chapters/00-reading-guide.md
index 073d83c86e..cb28fd9d58 100644
--- a/docs/book/en/chapters/00-reading-guide.md
+++ b/docs/book/en/chapters/00-reading-guide.md
@@ -142,8 +142,7 @@ Operators need not run source tests first; prospective contributors can use
Command categories remain explicit. **Runnable** requires the stated version, inputs, and authorization.
**Based on the official scaffold** follows the existing teaching package without inventing a runtime.
**Simplified for explanation** tables, labels, and data shapes must not be pasted into production
-configuration. Record preview, execution, readback, and test results separately; supplying a command is
-not evidence that it ran successfully.
+configuration.
## Four questions for an accountable explanation {#judgment-standard}
@@ -166,7 +165,7 @@ independent T2 work remains legal. Follow the reasoning in
This is an editorial and learning standard, not a new schema, runtime obligation, or approval gate. When
information is insufficient, name what cannot yet be concluded, the missing evidence, and who can confirm
-it. Do not guess to fill a table. Refusal is not the end goal either: reassess when conditions are repaired,
+it. Do not guess to fill a table. reassess when conditions are repaired,
preserve work that already happened, and find the next legal action.
## How to read the evidence
@@ -178,7 +177,7 @@ preserve work that already happened, and find the next legal action.
| Teaching scenario or advice | Explains a tradeoff; it is not a historical incident or machine-enforced rule |
| Tests and smokes | Establish only exercised inputs and assertions; matching headings/tables, existing paths, and successful builds do not establish semantic correctness |
-During revision, prioritize operational guarantees and bilingual obligation sentences. Narrow unsupported claims and retire obsolete models from current paths. Retaining an old word count is not a reason to keep teaching retired behavior.
+During revision, prioritize operational guarantees and bilingual obligation sentences. Narrow unsupported claims and retire obsolete models from current paths.
## Sources of authority
diff --git a/docs/book/en/chapters/01-from-session-to-loop.md b/docs/book/en/chapters/01-from-session-to-loop.md
index 74f8e32732..4b128e4fc5 100644
--- a/docs/book/en/chapters/01-from-session-to-loop.md
+++ b/docs/book/en/chapters/01-from-session-to-loop.md
@@ -1,7 +1,5 @@
# From one session to long-running work
-An Agent that can edit code, run tests, and explain results inside the current session has not thereby demonstrated that it can reliably own work spanning several days. This chapter explains where that gap comes from, and why closing it needs something that lives outside the session.
-
## An opening that looks fine
Say you want to add `--format json` to an existing CLI:
@@ -58,7 +56,7 @@ It is a poor home for the *only* copy of these facts:
| Which Agent owns the current task | After a restart or handoff, ownership cannot be recovered from memory |
| The current state of the outside world | Yesterday's CI status may already be stale |
-A Host can persist transcripts, but old conversation alone does not establish current authority, acceptance, or recovery state. The test is whether the next executor can recheck those facts without depending on the original session's implicit understanding.
+The test is whether the next executor can recheck those facts without depending on the original session's implicit understanding.
## Execution plane and control plane
@@ -78,7 +76,7 @@ Observation / receipt: return verifiable results
Control plane: accept, reject, or replan
```
-**The control plane does not replace the execution plane.** LoopX does not write code, host Git, or stand in for CI. It lets those systems' results be consumed by a work lifecycle that spans turns — exactly the link missing after 10:17.
+It lets those systems' results be consumed by a work lifecycle that spans turns — exactly the link missing after 10:17.
## Why three long-running workloads share one control plane
@@ -102,7 +100,7 @@ external fact
→ recompute continue | wait | ask | replan | repair | terminal
```
-What is reused is **lifecycle invariants** rather than a generic prompt. Issue-Fix understands `CHANGES_REQUESTED`; Auto ML understands a matched baseline; Auto Research understands holdout. Those domain meanings belong to Capability and Domain State. Who may claim, what is runnable, when to wake again, which evidence permits writeback, and whether the Goal can terminate all come from the same Kernel contract.
+What is reused is **lifecycle invariants**. Issue-Fix understands `CHANGES_REQUESTED`; Auto ML understands a matched baseline; Auto Research understands holdout. Those domain meanings belong to Capability and Domain State. Who may claim, what is runnable, when to wake again, which evidence permits writeback, and whether the Goal can terminate all come from the same Kernel contract.
This boundary also explains why a new domain capability should not clone its own runner, queue, retry, and completion state machine. The domain layer supplies decidable facts and proposals, Providers make external calls, and the Kernel owns cross-domain lifecycle.
@@ -110,7 +108,7 @@ To enter architecture and source entry points through the three showcases, conti
## What minimal externalized state looks like
-For the running example, the minimal state is not the full transcript but a set of facts that answer the recovery questions:
+For the running example, the minimal state is a set of facts that answer the recovery questions:
```yaml
# Simplified for explanation; not a LoopX file format
@@ -129,7 +127,7 @@ next_wake:
when: maintainer decision arrives
```
-The value of these fields: **the next executor does not have to trust the previous Agent's account** and can instead re-derive the next step from the goal, the work queue, Gates, evidence, and a fresh environment. The example is an explanatory model, not LoopX's storage format.
+The value of these fields: **the next executor does not have to trust the previous Agent's account** and can instead re-derive the next step from the goal, the work queue, Gates, evidence, and a fresh environment. The example is an explanatory model.
## Cost and boundary: what this gives up
@@ -141,7 +139,7 @@ Externalized state carries costs. Naming them is what lets you judge when it pay
**Cost three: external facts must be observable.** If CI results, maintainer replies, and external dependency state cannot be read by a program, the control plane can only wait — and waiting needs someone to re-trigger it.
-**Boundary one: this book is about long-running work, not every task.** Work that is closed in scope, finishable in the current context, free of waits on external events, and free of cross-Agent handoff is fine as a plain session — chapter 2 gives the qualification criteria.
+**Boundary one: this book is about long-running work.** Work that is closed in scope, finishable in the current context, free of waits on external events, and free of cross-Agent handoff is fine as a plain session — chapter 2 gives the qualification criteria.
**Boundary two: the control plane does not own domain judgment.** It does not decide whether an issue is worth fixing or whether an experiment's metric is significant; that belongs to Capability.
@@ -149,7 +147,7 @@ Externalized state carries costs. Naming them is what lets you judge when it pay
## Invariants
-1. **Prompt content alone does not prove durable writeback.** Inspect addressable records, identity, and revision rather than whether a window is open.
+1. Inspect addressable records, identity, and revision rather than whether a window is open.
2. **The execution plane and control plane cannot substitute for each other.** The control plane does not write code; the execution plane does not decide whether it is allowed.
3. **What is reused is lifecycle invariants, not a prompt.** That is what lets three different domains share one control plane.
4. **The next executor does not need to trust the previous one's account.** If it does, the state was not externalized far enough.
diff --git a/docs/book/en/chapters/02-session-goal-loopx.md b/docs/book/en/chapters/02-session-goal-loopx.md
index 80630008e3..bdc5b042b1 100644
--- a/docs/book/en/chapters/02-session-goal-loopx.md
+++ b/docs/book/en/chapters/02-session-goal-loopx.md
@@ -44,7 +44,7 @@ the task's completion date does not move.
## Why "big tasks use LoopX, small ones use a session" is not enough
The natural instinct sorts by task size: short work stays in a session, large work escalates to the
-long-running control plane. Neither story fits. The second task was small, three Todos, and a single
+long-running control plane. The second task was small, three Todos, and a single
pending question stalled it for two days.
The decisive variable is this: **when the task stops, what does it need in order to continue?** The
@@ -99,7 +99,7 @@ LoopX coordinates Goals, Agents, and Hosts, but each identity answers a differen
| `agent_id` | Which peer or work lane owns the current responsibility? | Binds claims, Vision, quota, and writeback; new onboarding defaults to a fresh identity only when no registered lane exists or `--new-peer` is explicit |
| `host_surface` / runtime profile | Which product surface executes and wakes this turn? | Binds App heartbeat, a visible Goal, or another Host loop; declare the surface that is actually running |
-Reusing a Goal does not imply that a new session should take over an existing Agent identity. The current
+The current
Goal-start contract keeps those choices explicit:
1. if several registered Goals exist, return a read-only `goal_selection_gate` and rerun with one exact
@@ -113,7 +113,7 @@ Goal-start contract keeps those choices explicit:
`fresh_agent_registration_required` (`register_fresh_agent`), and first onboarding needs no extra
`--new-peer`; a bound thread keeps its bound lane;
5. continue an existing Agent only when the user explicitly selects that exact `agent_id`;
-6. an Agent name or prefix does not prove the Host surface; runtime metadata does.
+6. runtime metadata does.
This lets a session continue the same project without silently impersonating the previous executor.
@@ -225,7 +225,7 @@ claim, lease, successor, and handoff information. Per-Agent Vision stores one pe
direction, acceptance summary, and replan trigger. It is a per-Agent route, not a global product vision.
This separates "the Goal is active" from "who may perform which work now." An agent id labels a LoopX work
-lane; it does not prove which Host is currently executing it. A new session may reuse the Goal history and
+lane. A new session may reuse the Goal history and
frontier, registering a fresh Agent identity when no lane is registered or `--new-peer` is explicit.
Existing claims move only through an explicit takeover or handoff.
@@ -245,7 +245,7 @@ the Host. That second half is exactly what the opening story was missing.
### 3. Evidence and receipt
-"The agent invoked a command" is not proof that a transition happened. LoopX distinguishes:
+LoopX distinguishes:
- proposal: what should happen;
- observation: what was seen;
diff --git a/docs/book/en/chapters/02b-long-horizon-requirements.md b/docs/book/en/chapters/02b-long-horizon-requirements.md
index 42167685f7..89d50518d1 100644
--- a/docs/book/en/chapters/02b-long-horizon-requirements.md
+++ b/docs/book/en/chapters/02b-long-horizon-requirements.md
@@ -11,17 +11,17 @@ A repair can span code edits, tests, CI waiting, review, handoff and delivery. E
| How do executors collaborate? | Assignment, scope and current execution proof | Claims, leases, fences and commit checks |
| How does no-change work consume less? | Budget, wait target, observations and actual execution conditions | Quota, Monitors, scheduler/backoff and Host |
-Long-running work needs neither an immortal process nor a delivery on every wake. Legitimate waiting and honest stopping also need representation.
+Legitimate waiting and honest stopping also need representation.
## Demand one: state outlives the current context
-A recipient needs the exact PR, commit, validated behavior and outstanding decisions, not merely “I fixed it.” Chat may persist and explain history, but persistence alone supplies neither structure, freshness nor current permission.
+A recipient needs the exact PR, commit, validated behavior and outstanding decisions, not merely “I fixed it.”
Consequential facts need an addressable source, applicable revision and read entrypoint. Maintaining records has a cost; the benefit is reassessing conditions after session change rather than filling gaps from memory. In the [state chapter](state-substrate.md), distinguish source from display under the selected mode.
## Demand two: retain known facts and uncertainty
-An external operation can succeed while its local response is lost. A missing local record proves neither remote absence nor completion.
+An external operation can succeed while its local response is lost.
Governed Turns represent confirmed progress through phases and receipts and read unresolved effects under original identity. Legal prefixes constrain records, not the crash window between external commit and checkpoint. The original owner resolves uncertainty; a new key must not bypass it. Only supported outcomes and current permission allow reuse or outstanding execution.
@@ -31,7 +31,7 @@ Historical recovery and admission for a new execution answer different questions
Agents can handle different work or both believe the same item belongs to them. Claims express responsibility; applicable leases/fences constrain the current instance. Neither replaces Goal boundaries, Gate scope, capability or workspace conditions.
-Default legacy, soft-claim and hard-lease paths have distinct enforcement boundaries. One mode does not establish universal exclusion, and multiple peers do not imply one executor for the entire Goal. Tie takeover and parallelism to a concrete writer and current inputs; see [authority layers](work-graph-and-authority.md#authority-layers).
+Default legacy, soft-claim and hard-lease paths have distinct enforcement boundaries. Tie takeover and parallelism to a concrete writer and current inputs; see [authority layers](work-graph-and-authority.md#authority-layers).
## Demand four: budget and observation constrain repetition
diff --git a/docs/book/en/chapters/03-one-turn.md b/docs/book/en/chapters/03-one-turn.md
index 7ef28ebffc..188571dfbb 100644
--- a/docs/book/en/chapters/03-one-turn.md
+++ b/docs/book/en/chapters/03-one-turn.md
@@ -52,7 +52,7 @@ Evidence becomes an accepted work fact through the relevant lifecycle entrypoint
| Evidence | Materials supporting a conclusion | A record that a transition was accepted |
| Receipt | Acceptance of a bound operation under its inputs and conditions | Current execution rights or an unchanging external world |
-For example, a `git push` timeout is a call outcome. A remote-ref readback may establish that a commit is present, but not necessarily which invocation caused it, and it does not automatically create a LoopX delivery receipt. Resolve the original operation before its writeback; timeout is not proof of absence.
+For example, a `git push` timeout is a call outcome. A remote-ref readback may establish that a commit is present, but not necessarily which invocation caused it, and it does not automatically create a LoopX delivery receipt. Resolve the original operation before its writeback.
## Scale one: execute, validate and commit
@@ -60,7 +60,7 @@ Normal delivery has five useful stages: `Decide → Act → Validate → Write b
**Decide** reads the current `interaction_contract` and selected work. An old prompt, card or recommendation does not override current selection.
-**Act** produces a coherent segment with explicit inputs and boundaries. Bounded does not mean one line: an independently verifiable feature slice is more useful than fragments that cannot be accepted.
+**Act** produces a coherent segment with explicit inputs and boundaries. an independently verifiable feature slice is more useful than fragments that cannot be accepted.
**Validate** checks postconditions. Code needs behavioral validation, documentation needs command and explanation checks, external effects need appropriate readback, and blockers need inspectable missing conditions. An exit code matters only when the validator actually checked the intended postcondition.
@@ -112,7 +112,7 @@ After obtaining `settlement_owed.command` from a trusted current entrypoint, ver
“Independent work may continue” has a timing boundary. A Turn already bound to T1 does not switch its settlement identity to T2 merely because T1 discovers a dependency.
-This is an **advanced source comparison**, grounded in the [original-Turn wait recovery test](https://github.com/loopx-project/loopx/blob/f49b4a00870604d39fa4318da24d6dd35e72bb6e/tests/test_quota_bound_wait_recovery.py) at main `f49b4a00…`. The current source includes that implementation. The pinned link supports verification; it does not establish shipped `v1.2.3` behavior or make the example executable on an older checkout.
+This is an **advanced source comparison**, grounded in the [original-Turn wait recovery test](https://github.com/loopx-project/loopx/blob/f49b4a00870604d39fa4318da24d6dd35e72bb6e/tests/test_quota_bound_wait_recovery.py) at main `f49b4a00…`. The current source includes that implementation. The pinned link supports verification.
```text
Original Turn binds T1 and records a monitor_changed / todo_done dependency
@@ -162,7 +162,7 @@ An owner stopping a Goal in the Workspace uses its lifecycle authority; automati
Migrated transactions have TypeScript owners; Python handles adapters or explicit external effects. Known slices include Turn settlement, Todo completion, Host Todo settlement, spend/void/monitor-poll commit, the full local task-lease lifecycle, Vision refresh and receipt-bound scheduler follow-up.
-`v0.5.4` still ships `turn plan` / `turn run-once`: this is historical migration context, not a replacement label for the current release or evidence that “Python has been removed.” The [TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/) explains transaction-payoff and ownership boundaries. Diagnose disagreement from the current contract and caller path, not from a blanket preference for one language.
+`v0.5.4` still ships `turn plan` / `turn run-once`: this is historical migration context. The [TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/) explains transaction-payoff and ownership boundaries. Diagnose disagreement from the current contract and caller path.
## Readback and the chapter's exit condition
diff --git a/docs/book/en/chapters/04-runtime-boundaries.md b/docs/book/en/chapters/04-runtime-boundaries.md
index 1b891b16c2..bda072833a 100644
--- a/docs/book/en/chapters/04-runtime-boundaries.md
+++ b/docs/book/en/chapters/04-runtime-boundaries.md
@@ -82,17 +82,17 @@ Dreaming proposes directions or hypotheses; it does not acquire execution author
## Material evidence delta: activity is not progress
-Imagine a teaching case in which a day produces notes, unrelated tests and directory reorganization, but reduces none of the acceptance gaps. The artifacts may exist; that alone does not establish convergence. This is not a claim that current policy unconditionally permits infinite repetition.
+Imagine a teaching case in which a day produces notes, unrelated tests and directory reorganization, but reduces none of the acceptance gaps. The artifacts may exist.
Material evidence delta concerns new evidence or state that changes the next judgment, not counts of turns, files or characters. Negative results can matter: rejecting a hypothesis, confirming a blocker or narrowing an unknown can change the route.
-Delivery Batch Scale describes change scope; Delivery Outcome describes its relation to the objective. `multi_surface` or `implementation` does not automatically complete a Goal. Interpret `surface_only`, `outcome_gap`, `outcome_progress` and `primary_goal_outcome` under their contract; an attractive label is not evidence.
+Delivery Batch Scale describes change scope; Delivery Outcome describes its relation to the objective. `multi_surface` or `implementation` does not automatically complete a Goal. Interpret `surface_only`, `outcome_gap`, `outcome_progress` and `primary_goal_outcome` under their contract.
### Vision checkpoints and baselines
Vision is a per-Agent execution route, not a scratchpad. Applicable material refresh must account for a patched route, supported unchanged result, retirement/supersession, or why the role does not require Vision.
-“Unchanged” needs a comparable baseline. Establish the route when none exists rather than describing never-checked as unchanged. For gaps such as `vision_checkpoint_missing`, return to the checkpoint owner and supply the actual relationship, not more aspirational prose. Current owners still determine precedence among replanning and repair; this explanation is not a global rule table for all Hosts.
+“Unchanged” needs a comparable baseline. Establish the route when none exists rather than describing never-checked as unchanged. For gaps such as `vision_checkpoint_missing`, return to the checkpoint owner and supply the actual relationship, not more aspirational prose. Current owners still determine precedence among replanning and repair.
### Six convergence invariants
@@ -105,7 +105,7 @@ These questions check completeness; they add no public fields or automatic accep
5. **Liveness:** does unfinished work have an action, executable observation, decision, repair or explicit stopping responsibility?
6. **Terminal state:** were successors, waits, receipts and acceptance gaps handled under the applicable contract, rather than merely finding an empty list?
-Safety avoids incorrect progress; liveness avoids getting stranded without a next entrypoint. Neither guarantees arbitrary objectives will succeed. See [long-horizon convergence](/loopx/docs/development/control-plane-course/topic-long-horizon-convergence/) and [evidence and repair](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/).
+Safety avoids incorrect progress; liveness avoids getting stranded without a next entrypoint. See [long-horizon convergence](/loopx/docs/development/control-plane-course/topic-long-horizon-convergence/) and [evidence and repair](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/).
## Which surface should be repaired when two disagree? {#projection-repair}
@@ -124,7 +124,7 @@ Legacy Markdown can still be source; a Todo under a selected canonical provider
## Stop, closure and compensation
-An owner-stopped Goal, paused quota or exited Host does not prove completion. `terminal_no_followup` needs its frontier/acceptance conditions. Zero visible Todos is insufficient: output may be truncated, or Monitors, Gates, successors, handoff, replanning and result-return responsibilities may remain.
+`terminal_no_followup` needs its frontier/acceptance conditions. Zero visible Todos is insufficient: output may be truncated, or Monitors, Gates, successors, handoff, replanning and result-return responsibilities may remain.
When requirements are satisfied, record the basis through the existing terminal entrypoint. Keep a successor for unfinished work or observation/blocker for unknown results. Verified negative results and coverage-backed no-follow-up can honestly end a route without inventing success.
@@ -150,7 +150,7 @@ A writeback may mark the vision unchanged only when all of the following hold:
vision as the baseline automatically, so no separate revision is passed.
If the baseline is missing but the agent still claims unchanged, quota will produce a
-`vision_checkpoint_missing` gap. This is not a punishment, but a guard against the agent accumulating
+`vision_checkpoint_missing` gap. a guard against the agent accumulating
wrong assumptions on a never-checked state. For the full failure replay, see
[Control-Plane Course Lesson 8](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/).
diff --git a/docs/book/en/chapters/04b-budget-and-admission.md b/docs/book/en/chapters/04b-budget-and-admission.md
index eb369c3a2d..f852135c3a 100644
--- a/docs/book/en/chapters/04b-budget-and-admission.md
+++ b/docs/book/en/chapters/04b-budget-and-admission.md
@@ -1,6 +1,6 @@
# Bounded spending and external observation
-After T1 finishes, M1 may still await CI for C1 and G1 may still await a publication decision. Remaining budget does not justify repeatedly invoking a model; no message does not prove the external world is unchanged. Separate whether to act, when to look again, who observes, and when to reconsider the route.
+After T1 finishes, M1 may still await CI for C1 and G1 may still await a publication decision. Remaining budget does not justify repeatedly invoking a model. Separate whether to act, when to look again, who observes, and when to reconsider the route.
## Separate five responsibilities {#observation-owners}
@@ -25,7 +25,7 @@ The following is a **hypothetical faulty policy**, not a claim that current impl
| 11:00 | M1 | M1's second unchanged observation | Switch again and start counting again |
| 11:30 | M1 and M2 are each due | Update each observation independently | Depends on processing order rather than actual stagnation |
-The problem is not a high threshold; it is conflating different targets. Preserve each Monitor's identity and count instead of repeatedly lowering the threshold. Conversely, without a usable Host executing due observations, correct counters remain static records: that is a liveness gap, not no-change evidence.
+Conflating different targets. Preserve each Monitor's identity and count instead of repeatedly lowering the threshold. Conversely, without a usable Host executing due observations, correct counters remain static records: that is a liveness gap, not no-change evidence.
## Choose an observation frequency while waiting for CI {#running-wait}
@@ -61,7 +61,7 @@ When T1 discovers a real dependency, record a specific target such as `monitor_c
Independent T2 in the work graph does not let a Turn already bound to T1 rebind itself. Complete the original Turn's required blocked writeback and closeout, then let later admission select new work. **Turn closeout, Todo waiting and next-turn selection are three different facts.**
-The [Turn chapter's wait sequence](03-one-turn.md#wait-closeout) explains this path with an explicit test from main `f49b4a00…`, labeled separately from older release promises. It checks no duplicate debit, no forced Monitor poll, and retained waiting/validation declarations. It is not a universal scheduling order for all Hosts.
+The [Turn chapter's wait sequence](03-one-turn.md#wait-closeout) explains this path with an explicit test from main `f49b4a00…`, labeled separately from older release promises. It checks no duplicate debit, no forced Monitor poll, and retained waiting/validation declarations.
## Cadence backoff versus route replanning
diff --git a/docs/book/en/chapters/05-connect-existing-project.md b/docs/book/en/chapters/05-connect-existing-project.md
index 7fe85e155d..04cf47b0eb 100644
--- a/docs/book/en/chapters/05-connect-existing-project.md
+++ b/docs/book/en/chapters/05-connect-existing-project.md
@@ -18,7 +18,7 @@ Use your actual project and current packet for commands; T1, M1, and C1 are not
## Three different completion points {#three-completions}
-Installing, connecting, and delivering are not the same accomplishment. Installation asks whether the
+Installation asks whether the
CLI and required runtime are usable. Connection asks whether work identity, state location, and execution
route are explicit. Delivery asks whether the actual artifact meets its current acceptance conditions.
A connected project may have no executing Turn; a successful Turn may still leave external checks or
@@ -151,8 +151,7 @@ git ls-files .loopx .loopx/goals .local
```
Repository root, current branch, and existing changes are separate facts. Do not reset or delete valuable
-changes. In a linked worktree, identify the tree where delivery will actually happen. A clean status in
-one directory does not establish that no work happened in another.
+changes. In a linked worktree, identify the tree where delivery will actually happen.
A project may already contain `.loopx/registry.json` or `.loopx/goals/`. Identify existing Goals, in-flight
work, and state locations first. Do not copy another project's registry or overwrite useful state to
@@ -197,8 +196,7 @@ git check-ignore -v .loopx/goals/example/ACTIVE_GOAL_STATE.md
mean the path is ignored. Tracked files are not governed by ignore rules by default. `--no-index`
diagnoses rules without considering the index; it neither forces exclusion nor specifically handles
nonexistent files. By default, `ls-files` lists paths in the current index. Output means tracked or staged
-content, **not necessarily a pushed commit**. No output does not prove that past commits or a remote have
-never contained sensitive material. See [Git check-ignore](https://git-scm.com/docs/git-check-ignore)
+content, **not necessarily a pushed commit**. See [Git check-ignore](https://git-scm.com/docs/git-check-ignore)
and [Git ls-files](https://git-scm.com/docs/git-ls-files).
When local state is tracked unexpectedly, inspect its contents, staging, and history before an authorized
@@ -233,8 +231,7 @@ to the implementation and regression exercises later in the book. For an existin
installation, use the [appendix's upgrade guidance](appendix-reference.md) to identify the installation
owner instead of layering another installation over an unexplained one.
-`doctor` answers more about dependencies, installation, and integration than `command -v loopx`, but it
-is not proof that every Host journey has been qualified. For the actual Effect runtime and journal
+`doctor` answers more about dependencies, installation, and integration than `command -v loopx`. For the actual Effect runtime and journal
checkpoint path, use the deeper probe when needed:
```bash
@@ -279,8 +276,7 @@ loopx start-goal --guided --project . \
--goal-text "Add compatible JSON output while preserving default text; deliver after validation and documentation, without automatic publication"
```
-The response is a guided transaction packet. A successful preview does not establish that Todos were
-written, an Agent was registered, or a Host started. Read the selection it currently requires and
+The response is a guided transaction packet. Read the selection it currently requires and
continue with its exact commands; do not revive an obsolete instruction from an earlier conversation.
When several Goals exist, select an exact `goal_id` from `goal_selection_gate` choices. Similar objective
@@ -325,7 +321,7 @@ when the Host is unknown rather than substituting a familiar name for observatio
readback belong to the [Codex App](06-codex-app.md) and [Codex CLI](07-codex-cli.md) chapters; other
adapters are indexed in the [Runtime Connector Catalog](/loopx/docs/integrations/runtime-connector-catalog/).
Type registration, launchability here, autonomous continuation inside a process, and waking after that
-process exits are distinct conditions. An accepted argument does not prove them all.
+process exits are distinct conditions.
## 4. Accept the connection: which next step is supported now? {#connection-acceptance}
@@ -377,7 +373,7 @@ objective content, and credentials before sharing it publicly.
## 5. From connection to the first delivery {#first-delivery}
Return here after the Host chapter. The goal is an independently verifiable work segment, not a screen
-that says running. This walkthrough is not an end-to-end test of a real Host; accept actual work using
+that says running. accept actual work using
evidence from your own run.
### Scene one: A owns T1, not the entire publication workflow
@@ -415,15 +411,14 @@ Internal quota accounting is also not the model supplier's actual bill.
Local validation cannot replace M1's observation of remote C1. Registered waiting should identify its
target, applicable revision, next observation, and termination or ongoing-watch policy, with an actually
available execution surface. Supported boundedness choices include expiry, a resume condition, or
-explicit watch-only; one field is not the only valid choice for every Monitor.
+explicit watch-only.
When G1 has not approved publication, T3 obtains no authority from green CI or T1 settlement. T2 may
continue when it is still provably independent and its own constraints hold. A user decision can be
required while an Agent continues different work. See [observation and scheduling](04b-budget-and-admission.md)
and [the work graph](work-graph-and-authority.md).
-An unchanged observation must not impersonate delivery; it can still incur compute and network cost.
-No notification is not evidence that the external source stayed unchanged. When the Host has exited
+An unchanged observation must not impersonate delivery; it can still incur compute and network cost. When the Host has exited
with no available waking mechanism, report the operational gap rather than calling quietness healthy waiting.
### Scene four: changed conditions call for changed judgments
@@ -456,8 +451,7 @@ For example, as a local report rather than another persisted format:
> publication decision is still outstanding, so return the artifact for review without publishing.
> G1's decision entrypoint comes next; once accepted and still applicable, reassess T3.
-Even without saying everything is complete, this report supports a handoff. “Tests green, task done”
-provides neither the scope of what was proved nor the responsibilities still outstanding.
+Even without saying everything is complete, this report supports a handoff.
## 6. Delegate onboarding to an Agent without delegating guesses about authority {#delegate-onboarding}
diff --git a/docs/book/en/chapters/06-codex-app.md b/docs/book/en/chapters/06-codex-app.md
index f9a888e531..18b484f0df 100644
--- a/docs/book/en/chapters/06-codex-app.md
+++ b/docs/book/en/chapters/06-codex-app.md
@@ -56,8 +56,7 @@ Agent Turn no delivery
validate -> writeback -> optional spend
```
-The right branch is a legal outcome, and it is the common one. It means no work was due for **this** turn; it
-does not mean the Goal frontier is closed. A settled turn's replay returns `should_run=false` while preserving
+The right branch is a legal outcome, and it is the common one. It means no work was due for **this** turn. A settled turn's replay returns `should_run=false` while preserving
the current cadence and deferring evaluation to a fresh Turn identity. Landing there often is therefore not
evidence that the cadence should slow down. Apply the four steps below only when the current `scheduler_hint`
proposes a change (`apply_needed=true`).
@@ -106,8 +105,7 @@ before the Todos exist, and each wake receives a Goal with no frontier yet. Writ
very first wake already has a defined candidate.
You do not have to run every internal command yourself, but you should be able to see these transitions in
-the Agent's report. A natural-language plan is not proof that project state exists, and a guided packet is
-not proof that a heartbeat has been installed. Each needs its own readback.
+the Agent's report. Each needs its own readback.
## Every wake still passes the quota Gate
@@ -194,14 +192,13 @@ something that settles as fast as assigning a local variable.
both exit successfully. Telling them apart requires the writeback and spend history, not the heartbeat log.
**Boundary one: a heartbeat does not create a frontier.** A Goal with no Todos will not produce a next step
-because it was woken more often. The App guarantees someone looks; it does not guarantee there is anything
-to do. With no runnable candidate, enter wait or monitor and let the cadence slow.
+because it was woken more often. With no runnable candidate, enter wait or monitor and let the cadence slow.
-**Boundary two: the automation is not a second control plane.** Do not copy the quota state machine into
+Do not copy the quota state machine into
the automation prompt, and do not let it resolve runnable Todos on its own. The stable prompt carries
protocol; the judgment belongs to the packet read on each wake.
-**Boundary three: switching Hosts requires ownership checks.** App and CLI may read one Goal. Check the old instance, current claims/leases, and writer-fence mode. Use lifecycle handoff where required; a newly started Host does not authorize concurrent work on the same item.
+**Boundary three: switching Hosts requires ownership checks.** App and CLI may read one Goal. Check the old instance, current claims/leases, and writer-fence mode. Use lifecycle handoff where required.
## When to choose App, and when to choose CLI
@@ -264,7 +261,7 @@ repeat reminders so that a wait does not become a high-frequency notification.
this turn's receipt is grounds to slow the cadence. Slowing happens when the current `scheduler_hint`
proposes it (`apply_needed=true`), through the four steps below.
4. **A cadence change needs all four steps**: proposal, host apply, host readback, ACK.
-5. **A local ACK ledger does not prove Host state.** Only a Host readback that matches the target closes the
+5. Only a Host readback that matches the target closes the
loop; a mismatch is repaired as `drift_detected`.
6. **Switching Hosts needs explicit handoff.** Shared Goal reads do not replace current authority, claim/lease, and fence checks.
diff --git a/docs/book/en/chapters/07-codex-cli.md b/docs/book/en/chapters/07-codex-cli.md
index 0a512b3e6e..6f344d8e31 100644
--- a/docs/book/en/chapters/07-codex-cli.md
+++ b/docs/book/en/chapters/07-codex-cli.md
@@ -4,7 +4,7 @@ A visible TUI can also sustain progress. LoopX generates a stable task body for
## Why an active Goal differs from a background wake
-Suppose a fix is unfinished and you terminate its Codex process. No further work occurs before you restart it. The execution environment has exited; this does not mean a live native Goal needs a user message for every turn.
+Suppose a fix is unfinished and you terminate its Codex process. No further work occurs before you restart it. The execution environment has exited.
| Host state | Behavior on this path | What the user needs to establish |
| --- | --- | --- |
@@ -116,7 +116,7 @@ another Host or another lane, the work's ownership was silently rewritten. With
unregistered id is rejected, and a registered id that differs from the thread binding is treated as a
deliberate override, so pass one only when you mean to switch lanes.
-Agent identity labels the LoopX lane. It does not prove that the work runs in Codex CLI. Use
+Agent identity labels the LoopX lane. Use
`host_surface`, runtime profile, or run metadata to identify the Host.
A proper handoff is:
@@ -132,7 +132,7 @@ A proper handoff is:
**Continuation depends on an executable Host state.** An active native Goal can progress autonomously; process exit and blocked state have separate boundaries. Automatic wakes across those boundaries require the corresponding scheduling integration and readback.
-**Visibility does not replace validation.** A TUI shows activity; success still needs validation, writeback, and settlement. Whether someone watches the screen does not change those conditions.
+A TUI shows activity; success still needs validation, writeback, and settlement. Whether someone watches the screen does not change those conditions.
**Handoff requires current authority checks.** App and CLI can read the same Goal. Check claim, lease, worktree, and applicable writer-fence mode when changing executors to avoid concurrent submission of the same effectful work.
@@ -144,7 +144,7 @@ A proper handoff is:
| Check again on cadence after a long wait | App heartbeat or a qualified scheduler integration | Actual automation, cadence, and ACK/readback |
| Continue after process exit | Resume the existing Goal or use a path supporting that boundary | An old prompt is not a new execution environment |
-Select the wake mechanism you need. Visible execution does not mean manually triggering every turn. Both paths must read the current LoopX decision.
+Select the wake mechanism you need. Both paths must read the current LoopX decision.
## Recovery paths
diff --git a/docs/book/en/chapters/07b-when-loopx-is-not-the-answer.md b/docs/book/en/chapters/07b-when-loopx-is-not-the-answer.md
index 1f44a00956..3e5ed55b1a 100644
--- a/docs/book/en/chapters/07b-when-loopx-is-not-the-answer.md
+++ b/docs/book/en/chapters/07b-when-loopx-is-not-the-answer.md
@@ -22,7 +22,7 @@ Before onboarding, identify the observation that would support completion. Explo
### Two: governance costs work; measure performance through the real path
-Reading state, admission, validation, and writeback add work. Avoiding repeated execution and unnecessary wakes can reduce total cost. Measure single-turn latency and end-to-end completion separately; neither must necessarily get worse.
+Reading state, admission, validation, and writeback add work. Avoiding repeated execution and unnecessary wakes can reduce total cost. Measure single-turn latency and end-to-end completion separately.
A control plane does not directly make a model response faster. It may improve a journey whose delays come from rebuilding context, unattended waits, or repeated work.
@@ -32,7 +32,7 @@ A control plane does not directly make a model response faster. It may improve a
The [state substrate](state-substrate.md) owns work-lifecycle facts. LoopX also supports source-bound, scoped, revocable Agent preferences, alongside decision context, reward memory, and turn-recall capabilities or integration boundaries.
-This does not make arbitrary chats a permanent knowledge base. Preferences grant no action authority. Recalled content needs source, freshness, and scope checks; availability depends on release, configuration, and provider.
+Recalled content needs source, freshness, and scope checks; availability depends on release, configuration, and provider.
**Usage question:** are you retaining a Todo or receipt, an explicit user preference, or external knowledge material? Select its existing owner before deciding how to store and recall it, rather than putting every conversation in active state.
diff --git a/docs/book/en/chapters/08-extension-placement.md b/docs/book/en/chapters/08-extension-placement.md
index 719452de39..cf4055f9f8 100644
--- a/docs/book/en/chapters/08-extension-placement.md
+++ b/docs/book/en/chapters/08-extension-placement.md
@@ -198,8 +198,7 @@ lifecycle, keep it in the nearest owning module.
Suppose the current project needs to convert two internal states into one dict, with no external caller
and no independent version-compatibility requirement. Turning it into a Capability or Extension would
-add manifest, doctor, and upgrade cost. Shared code may justify a helper; it does not prove a need for
-independent installation and lifecycle.
+add manifest, doctor, and upgrade cost.
### 2. Provider for an existing Capability
@@ -211,7 +210,7 @@ The Provider can be:
- built-in: shipped with LoopX core;
- extension-delivered: supplied by an independent Extension.
-Accessing an external system is not the only test for an Extension. A connector that shares the core
+A connector that shares the core
release lifecycle and is always maintained by core can still be a built-in Provider.
### 3. New Capability
@@ -263,8 +262,7 @@ settle the outcome, then the owner, and only then the delivery shape.
### Where platform-level machinery belongs
One further branch confuses people. If the addition is only the registration and lifecycle machinery
-shared by every Extension, it belongs in `loopx/extensions/`, not in any provider package. It is not a
-capability and needs no manifest of its own. Putting that machinery inside one provider forces the next
+shared by every Extension, it belongs in `loopx/extensions/`, not in any provider package. needs no manifest of its own. Putting that machinery inside one provider forces the next
provider to depend on the first one's private structure.
## Record the minimum rationale
@@ -307,7 +305,7 @@ enables, and runs doctor themselves. A core built-in works as soon as LoopX is i
declared into a catalog read reports `declared=true, installed=false, enabled=false, ready=false`; it
does not become usable merely by existing.
-**Cost three: a public contract needs maintenance.** A new Capability needs a stable caller outcome, a real entrypoint, and validation. One Provider can satisfy these conditions. Independent installation alone is insufficient, and provider count is not a gate.
+**Cost three: a public contract needs maintenance.** A new Capability needs a stable caller outcome, a real entrypoint, and validation. One Provider can satisfy these conditions. Independent installation alone is insufficient.
**Boundary one: this decision governs ownership inside the LoopX product surface, not someone else's
repository layout.** An independently distributed provider lives in its own package or repository;
@@ -325,7 +323,7 @@ it go." Whether an outcome has value is answered by a Goal and its acceptance.
### "It calls an external API, so create a connector Capability"
-Transport is not the caller outcome. Find who needs the result and whether an existing Capability already
+Find who needs the result and whether an existing Capability already
owns it.
### "Declare `[[provides]]` now and add the caller later"
@@ -340,7 +338,7 @@ or managing resources is an effect and must go through a Capability or domain co
### "Several files share code, so make an Extension"
-Shared code may justify a helper. It does not prove a need for independent installation and lifecycle.
+Shared code may justify a helper.
Abstraction follows the change reason, not the file count.
## Placement used by this book
diff --git a/docs/book/en/chapters/09-extension-scaffold.md b/docs/book/en/chapters/09-extension-scaffold.md
index 06e35fe152..eaea4e38fd 100644
--- a/docs/book/en/chapters/09-extension-scaffold.md
+++ b/docs/book/en/chapters/09-extension-scaffold.md
@@ -2,7 +2,7 @@
Use a complete zero-permission teaching package to learn requests, responses, validation, and packaging. [Companion source](https://github.com/loopx-project/loopx/tree/main/packages/loopx-text-stats) in `packages/loopx-text-stats/` includes its manifest, Python package, two JSON Schemas, sample input, and standard-library tests.
-It is not a built-in Capability or default catalog entry and does not read or write Goals. The package owns text input and results; the existing Extension lifecycle owns installation, activation, and managed calls.
+Does not read or write Goals. The package owns text input and results; the existing Extension lifecycle owns installation, activation, and managed calls.
## Run the complete example first
diff --git a/docs/book/en/chapters/10-extension-lifecycle.md b/docs/book/en/chapters/10-extension-lifecycle.md
index 0744c42450..01e1d0b0a5 100644
--- a/docs/book/en/chapters/10-extension-lifecycle.md
+++ b/docs/book/en/chapters/10-extension-lifecycle.md
@@ -92,7 +92,7 @@ the origin of a `python_module`, and any view validator the extension declares.
invalidates the old doctor proof. LoopX's own built-in validators are deliberately excluded, so upgrading
LoopX does not invalidate every extension with it.
-Doctor status is a ladder rather than a boolean:
+Doctor status is a ladder:
```text
entrypoint_missing -> identity cannot be resolved
@@ -200,7 +200,7 @@ code keeps running. Install the package that matches the target revision around
actual behavior back with `run`. Activation state retains a bounded number of validated
revision snapshots (five today).
-`rollback_available=false` means no rollback revision is recorded, as after a first install. It is not a diagnosis of a damaged environment.
+`rollback_available=false` means no rollback revision is recorded, as after a first install.
If a target exists but its doctor fails, inspect or reinstall the matching package before rollback and doctor readback; when doctor passes, still confirm that the matching version is installed. Without a historical target, choose an explicit version and prepare an installation/upgrade path; repairing the environment cannot create history.
diff --git a/docs/book/en/chapters/11-engineering-boundaries.md b/docs/book/en/chapters/11-engineering-boundaries.md
index 8a838b67d0..af9a0e437d 100644
--- a/docs/book/en/chapters/11-engineering-boundaries.md
+++ b/docs/book/en/chapters/11-engineering-boundaries.md
@@ -217,5 +217,4 @@ Update theory chapters only when the public contract changes, not when internal
- [ ] Internal links and the public-boundary scan pass.
- [ ] The bilingual first screen has owner approval.
-Only after these checks should GitHub Pages publish from `main`. Pages is the display surface, not the source
-of content truth or LoopX state.
+Only after these checks should GitHub Pages publish from `main`. Pages is the display surface.
diff --git a/docs/book/en/chapters/12-control-plane-course.md b/docs/book/en/chapters/12-control-plane-course.md
index d91cc64235..930475a3de 100644
--- a/docs/book/en/chapters/12-control-plane-course.md
+++ b/docs/book/en/chapters/12-control-plane-course.md
@@ -206,7 +206,7 @@ The returned command yields `appended=false` and the debit count remains one. A
`settled` without `settlement_owed`; the next Turn no longer remains in that settlement-recovery path.
These assertions establish this internal recovery, not a zero supplier bill, resolution of another
-unknown effect, G1 closure, or Goal acceptance. Passing a test does not prove that a live Goal recovered.
+unknown effect, G1 closure, or Goal acceptance.
#### Next entrypoint and stopping condition {#settlement-next}
@@ -230,15 +230,13 @@ Should this Agent continue waiting? What changes with its own advancement or an
#### Factual basis {#monitor-facts}
Read current-Agent lane, selectable advancement, the Monitor's `consecutive_no_change`, `watch_only`,
-target, due state, and actual Host liveness. A busy peer does not supply facts for this lane. Receiving
-no notification does not prove no external change.
+target, due state, and actual Host liveness. A busy peer does not supply facts for this lane.
#### Why allow or refuse? {#monitor-reason}
This replan obligation depends on count, ownership, and selectable work together. Five is a particular
policy threshold, not a theorem about all waiting. Current-Agent advancement can preempt it, and
-explicit watch-only does not use the same trigger. No obligation does not establish an available waking
-Host or authorize mutation or delivery debit.
+explicit watch-only does not use the same trigger.
#### Supporting evidence {#monitor-evidence}
@@ -318,12 +316,12 @@ work.
[Authority](work-graph-and-authority.md), [recovery](04-runtime-boundaries.md), and the
[Workspace](workspace-v1.md) own the corresponding operating instructions. Owner decisions are not all
-authorized by automatic-Turn quota. An internal test run also does not establish this real CI result or approval.
+authorized by automatic-Turn quota.
Replace the task with a comparison report based on two public sources and the same reasoning applies:
material versions replace commits, methods and citation checks support findings, and an acceptor and
publication scope remain explicit. Recheck affected analysis after a source update; do not turn all old
-discussion into new evidence. A finished report does not authorize publication. This is conceptual transfer,
+discussion into new evidence. This is conceptual transfer,
not qualification of another product journey.
### Add one condition: the original Turn is not closed
diff --git a/docs/book/en/chapters/appendix-reference.md b/docs/book/en/chapters/appendix-reference.md
index 6d02b5f317..40e75e793f 100644
--- a/docs/book/en/chapters/appendix-reference.md
+++ b/docs/book/en/chapters/appendix-reference.md
@@ -1,6 +1,6 @@
# Terms and command entrypoints
-Use this appendix with an actual problem; the source course is not a prerequisite. Current installed `--help` owns command arguments. This page gives entrypoints and judgment conditions, not a complete CLI reference or automatic mutation permission.
+Use this appendix with an actual problem. Current installed `--help` owns command arguments. This page gives entrypoints and judgment conditions, not a complete CLI reference or automatic mutation permission.
## Read before deciding to change state {#read-before-change}
@@ -49,7 +49,7 @@ Public feedback should retain minimal reproducible versions, error codes and pub
| Evidence / Receipt | Support for a conclusion versus an accepted-operation record; both need correct binding |
| Kernel | Generic transition owner, not the owner of every external system's reality |
-See [state](state-substrate.md). Information in a prompt alone does not prove durable lifecycle writeback. Persisted chat also does not automatically become current authority.
+See [state](state-substrate.md). Persisted chat also does not automatically become current authority.
## Requirement two: identify interrupted work {#requirement-two-interruption-stops-at-identifiable-points}
@@ -114,7 +114,7 @@ loopx update apply
loopx doctor
```
-Confirm installation owner, target release and plan before authorizing apply. Ordinary users should not default to `--ref main`. Updating the CLI does not establish that every Host, Provider and existing Goal migrated. Recheck skills, state, Host readback and enabled Extension readiness for the surfaces actually used.
+Confirm installation owner, target release and plan before authorizing apply. Ordinary users should not default to `--ref main`. Recheck skills, state, Host readback and enabled Extension readiness for the surfaces actually used.
For backup, preview before execution:
diff --git a/docs/book/en/chapters/core-state-machines.md b/docs/book/en/chapters/core-state-machines.md
index 302c3ce1bd..95bad6537f 100644
--- a/docs/book/en/chapters/core-state-machines.md
+++ b/docs/book/en/chapters/core-state-machines.md
@@ -6,14 +6,13 @@ covered Todos, claims, and authority, and chapter 03 covered the transaction ord
This chapter is where they converge. Read in isolation, each mechanism holds up. The question here is
the one only this chapter can answer: **how do they connect back into a single loop?**
-The short answer is: **LoopX is driven by cooperating state-machine families, but its highest-level model
-is not “nine machines messaging one another.” It is one
+The short answer is: **LoopX is driven by cooperating state-machine families; its highest-level model is one
effectful Agent Loop.** The Harness interprets effect requests from an Agent or Host; bounded state
machines such as Todo, Gate, Quota, Settlement, and Scheduler then determine the legal action for their
part of the flow. They connect through durable facts, typed contracts, guarded transitions, and receipts
instead of overwriting each other's state.
-LoopX does not advance a Goal through one giant state machine. It assigns durable work, turn decisions,
+It assigns durable work, turn decisions,
evidence settlement, scheduling, and UI projection to state machines with explicit owners. This chapter
establishes vocabulary and abstraction levels first, explains why the design is split this way, shows the
cooperation loop, expands each state-machine family, and closes with the cost of the design. You can
@@ -79,7 +78,7 @@ validated observation becomes durable fact; and the receipt plus projection conn
for changing direction. They are not one whole-object Goal state, and one completed Todo is not Goal completion.
- **Facts and views — source / authoritative fact, derived decision, projection**: source is durable
owner-written fact; decision is the current rule result; projection is a view for an Agent, Host, or person.
- Not every displayed field is writable, and projection is not a second source of truth.
+ Not every displayed field is writable.
- **Action and proof — effect request / proposal, observation, transition, evidence, receipt**: proposal
requests an action; observation reports external fact; transition accepts legal change; evidence supports
a judgment; receipt proves an identified commit. A request is not authority, and a tool result is not
@@ -118,7 +117,7 @@ Collapsing these concerns into `Goal.status` or allowing an Agent to replace `Go
erase another Agent's progress. A network timeout would no longer say whether to retry, read back, or
compensate. Display fields would also drift into becoming sources of truth.
-Cooperation does not mean direct messaging. The nine state-machine families connect primarily through
+The nine state-machine families connect primarily through
four stable interfaces:
1. **Source facts**: reducers / interpreters read Todo, event, lease, Vision, and receipt facts.
@@ -147,7 +146,7 @@ flowchart TD
Facts -.-> Projection["projection Workspace / status"]
```
-This is not a sequence diagram in which state machine A calls state machine B. Source facts, typed
+Source facts, typed
decisions, effects, observations, and receipts are what pass between stages. Each machine owns only its
decision table and legal transitions.
@@ -282,8 +281,7 @@ This is why side effects are modeled separately: a model can change its mind, bu
be rolled back by editing context. Validation, version/identity guards, reconciliation, compensation events,
and replanning turn the error into another verifiable transition instead of an untraceable chat conclusion.
This idempotent-recovery guarantee has a precise boundary: it applies to settlement steps with a durable
-journal, an `effect_ref`, and a provider readback resolver. It is not a promise that every external tool
-call is automatically deduplicated. Settlement fails closed when the resolver is missing, raises, or
+journal, an `effect_ref`, and a provider readback resolver. Settlement fails closed when the resolver is missing, raises, or
returns an unknown state.
## How nine state-machine families compose one Loop
@@ -610,8 +608,7 @@ Todo, acceptance, or no-follow-up delta is `replan_noop` and cannot clear the ob
### Goal activation does not mean automation is enabled
The typed Goal activation source has only `active` and `stopped`. `active` means that the control plane
-may continue evaluation; it does not prove that a Host heartbeat is installed or that eligible work
-currently exists. Complete onboarding still proceeds through:
+may continue evaluation. Complete onboarding still proceeds through:
```text
project registered
@@ -639,7 +636,7 @@ transcript, or a local path breaks the public/private boundary.
## What makes LoopX a closed loop
-Closed-loop operation in LoopX is not “the Agent did something,” and it is not the same as `Todo=done`.
+
A more precise definition is: **the result of an effect is validated and written back to the authoritative
source that owns that fact, so the control plane can derive either the next legal action or a proven stop.**
If the result remains
@@ -789,7 +786,7 @@ therefore not a state you can decide on; it has to be proven item by item.
services, and extensions do not align to that number. What actually binds is the typed owner, the protocol
schema, and the transition rules.
-**Boundary two: this map does not replace the migration boundary.** The owner in the diagram and the
+The owner in the diagram and the
implementation language are separate dimensions. When a semantic is already carried by a TypeScript
owner, rebuilding it in Python from this teaching map creates a second source of truth.
@@ -798,8 +795,7 @@ durable journal, an `effect_ref`, and a provider readback resolver carry that gu
external call is not automatically deduplicated because this chapter mentions reconciliation; settlement
fails closed when the resolver is missing or returns an unknown state.
-**Boundary four: the diagram does not go to the front line.** The diagrams here explain; they are not an
-implementation spec. Before changing a rule, confirm the current typed owner, protocol schema,
+The diagrams here explain. Before changing a rule, confirm the current typed owner, protocol schema,
characterization fixture, and migration boundary.
## Named failures: where the handoff breaks
@@ -819,8 +815,8 @@ been replaced continuing to write. `needs_rebase` exists as the rejection path f
while the source stays unchanged. The symptom is a persistent UI/CLI disagreement that returns to the old
value on every refresh. Repair the source or builder, then read back.
-**Failure four: the reason to stop is not the same as closure.** A stopped Goal, paused quota, or blocked peer
-coordination can each stop polling; each is a legal stop, and none proves Goal closure. Only
+**Failure four:** A stopped Goal, paused quota, or blocked peer
+coordination can each stop polling; each is a legal stop. Only
`terminal_no_followup` means "stopped because validated Goal closure was derived." Collapsing them lets a
paused Goal look finished.
@@ -836,7 +832,7 @@ paused Goal look finished.
caller handles the rejection.
5. **Terminal is a conjunction.** Complete and closed Todo sources, no unresolved frontier, and a
structured `no_followup` intent must all hold.
-6. **A teaching map is not an implementation spec.** Change a rule only after confirming the typed owner,
+6. Change a rule only after confirming the typed owner,
protocol schema, characterization fixture, and migration boundary.
These six answer one question: **when the mechanisms are split across nine families that can only speak
diff --git a/docs/book/en/chapters/source-change-control-plane-rule.md b/docs/book/en/chapters/source-change-control-plane-rule.md
index 211b26f93e..5f3087f830 100644
--- a/docs/book/en/chapters/source-change-control-plane-rule.md
+++ b/docs/book/en/chapters/source-change-control-plane-rule.md
@@ -319,8 +319,7 @@ Replay executes the real decision path. It is more than a fixture-shape test.
### 5. Risk-based canary
For quota, scheduler, Todo/Gate, or Agent-facing output changes, let the canary planner select affected
-surfaces from the Git diff. Canary adds cross-boundary confidence. It does not replace the named focused
-regression.
+surfaces from the Git diff. Canary adds cross-boundary confidence.
## Step 8: Define failure and recovery
@@ -475,8 +474,7 @@ states, typed reasons, and ordered transitions.
**Fixing policy in the renderer.** Editing prose cannot repair a source or authority defect; conversely, policy
should not depend on Markdown strings.
-**Refactoring every adjacent module.** A protocol chain crossing several bounded contexts does not mean
-this PR should include every possible cleanup. Change only the complete chain this invariant requires.
+**Refactoring every adjacent module.** Change only the complete chain this invariant requires.
**Adding an empty adapter for a future Host.** An adapter without a real caller, capability, and receipt
only adds maintenance surface, and it looks like a shipped capability.
diff --git a/docs/book/en/chapters/source-protocol-map.md b/docs/book/en/chapters/source-protocol-map.md
index 04b86d5450..d7f2b4436e 100644
--- a/docs/book/en/chapters/source-protocol-map.md
+++ b/docs/book/en/chapters/source-protocol-map.md
@@ -32,7 +32,7 @@ developer job
-> current implementation and validation
```
-This chapter is a protocol-first source map. It is not a complete API catalog, and it does not ask you to memorize current function names. Its job is to help you identify the contract your Issue or PR will change.
+This chapter is a protocol-first source map. Its job is to help you identify the contract your Issue or PR will change.
## What you should learn
@@ -257,7 +257,7 @@ Protocols define cross-module contracts. Bounded contexts identify which change
| `handoff` | Cross-runtime handoff, review packets, and owner routes |
| `work_items` | Attention, selection, and operator-facing work read models |
-On the `v0.5.4` migration baseline, bounded context and implementation language are separate dimensions. Complete transactions under `goals`, `todos`, `quota`, `scheduler`, `work_items`, and `turn_driver` now have TypeScript semantic owners. Examples include Vision refresh, the local task-lease lifecycle, quota spend/void/monitor-poll commit, and receipt-bound scheduler follow-up. Adjacent Python facade modules may serve only as CLI transport, legacy projection, an explicit external Provider or Host effect, or writeback that has not migrated. Read the shipped baseline in the [TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/) and trace the active request handler and caller before assigning ownership. A Python entrypoint does not prove that Python still owns the decision.
+On the `v0.5.4` migration baseline, bounded context and implementation language are separate dimensions. Complete transactions under `goals`, `todos`, `quota`, `scheduler`, `work_items`, and `turn_driver` now have TypeScript semantic owners. Examples include Vision refresh, the local task-lease lifecycle, quota spend/void/monitor-poll commit, and receipt-bound scheduler follow-up. Adjacent Python facade modules may serve only as CLI transport, legacy projection, an explicit external Provider or Host effect, or writeback that has not migrated. Read the shipped baseline in the [TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/) and trace the active request handler and caller before assigning ownership.
Ask:
@@ -296,7 +296,7 @@ Treat repository routes as owners, not as automatic placement from a directory n
| Operator projection | Status, frontstage, or projection owner; a renderer only consumes the typed model |
| Documentation and validation | Owning protocol document, `tests/`, `examples/`, or a public-safe fixture |
-Current capability packages own their documentation and register through `catalog_entry.py`. Before contributing, run `loopx capability list --format json` and `loopx capability show --format json` to confirm that the capability is registered and to read its entry commands, Provider boundary, and durable validation. A directory or README alone does not prove that a capability is shipped.
+Current capability packages own their documentation and register through `catalog_entry.py`. Before contributing, run `loopx capability list --format json` and `loopx capability show --format json` to confirm that the capability is registered and to read its entry commands, Provider boundary, and durable validation.
Code under `loopx/capabilities//` is not automatically a public Capability; it still needs explicit registration and a real caller contract. `loopx/extensions/` is not a bucket for every external integration; it owns generic Extension lifecycle, while an independently versioned Provider belongs in its delivery package. Keep private helpers with the nearest owner instead of promoting them to a Capability or Extension merely because they span several files.
@@ -474,7 +474,7 @@ Before entering the source, confirm these hold on their own:
1. **The owner of a rule is the module that decides legal transitions, not the module that first prints words about it.** If you cannot name the protected invariant, the change is not yet located.
2. **A PR description carries one complete causal chain: source, invariant, decision, projection or effect, receipt, validation.** A slice that can only list function names cannot be reviewed.
3. **Documents describe responsibility ownership; code describes current behavior.** When they conflict, pick the authority by conflict type and make this PR update the other side.
-4. **Code under `loopx/capabilities//` does not prove the Capability is shipped.** Registration plus a real caller contract is the release test; verify with `loopx capability list --format json`.
+4. Registration plus a real caller contract is the release test; verify with `loopx capability list --format json`.
5. **Placement precedes implementation.** The capability id, provider id, and built-in or extension-delivered choice come with a written reason before the first line of code.
6. **Tasks come from public entrypoints.** Public Contributor Tasks, Issues, and fixtures are the only source of work you can participate in; live active state and maintainer-local judgment are not.
diff --git a/docs/book/en/chapters/source-trace-protocol-chain.md b/docs/book/en/chapters/source-trace-protocol-chain.md
index 0a826cd289..943bdd380a 100644
--- a/docs/book/en/chapters/source-trace-protocol-chain.md
+++ b/docs/book/en/chapters/source-trace-protocol-chain.md
@@ -226,7 +226,7 @@ For this scenario:
- `repair-link-checker` remains runnable;
- the Gate remains visible in the user channel.
-This is not a Gate bypass. The selected fallback never performs the protected action.
+The selected fallback never performs the protected action.
### Ordered policy, not scattered booleans
@@ -491,7 +491,7 @@ For a control-plane failure, verify in order:
After a trace, these should hold on their own:
1. **Every renamed or redefined field comes with a full consumer list.** Updating producers alone is incomplete, and a missing-field fallback counts as a consumer.
-2. **Success at every layer is not evidence that the chain is correct.** The test is the first boundary that violates the invariant, not the final return value.
+2. The test is the first boundary that violates the invariant, not the final return value.
3. **A missing field's default participates in the decision.** So the contract must state whether absence means reject, repair, or compatibility fallback.
4. **Authority has exactly one canonical source.** Several places may read a field and only one owns it; mistaking a reader for the owner is the most common leftover from a cross-layer change.
5. **Judging authority follows the protocol document; judging current behavior follows the source.** When they conflict, pick by conflict type and make this change update the other side.
diff --git a/docs/book/en/chapters/source-validation-to-pr.md b/docs/book/en/chapters/source-validation-to-pr.md
index 73824ff458..ccaefa6cc2 100644
--- a/docs/book/en/chapters/source-validation-to-pr.md
+++ b/docs/book/en/chapters/source-validation-to-pr.md
@@ -64,8 +64,7 @@ ambiguous scope -> typed repair
explicit global scope -> global Gate
```
-This layer is the closest proof of an invariant. It does not prove that CLI, projection, and scheduler are
-connected correctly.
+This layer is the closest proof of an invariant.
### 2. Focused deterministic smoke
@@ -555,7 +554,7 @@ semantic core. The final `APPROVE` applies only to the revalidated exact head.
## Distinguish merge, release, deployment, and observation
-A merged PR does not prove a release, deployment, or every external Host update. Follow-up may include:
+Follow-up may include:
- full-public smoke on `main`;
- release qualification;
diff --git a/docs/book/en/chapters/state-substrate.md b/docs/book/en/chapters/state-substrate.md
index 9433bf28ab..330c1958e4 100644
--- a/docs/book/en/chapters/state-substrate.md
+++ b/docs/book/en/chapters/state-substrate.md
@@ -133,7 +133,7 @@ Delivery remains writer-specific. Check the actual command, authority mode, and
Shared-authority work in `v0.5.4` introduced a provider-neutral TypeScript `AuthorityStore` contract and candidate-provider validation. Later local cutover, fencing, projections, and default-entry adoption have separate milestones.
-Historical capabilities are not evidence that current paths stop at that baseline, nor that candidate qualification delivers a remote service. Read the selected Goal to establish its current File/SQLite authority path.
+ Read the selected Goal to establish its current File/SQLite authority path.
Staged candidates such as NoKV/PostgreSQL do not acquire runtime authority automatically. Installing a Provider also does not change an existing Goal's source of truth.
diff --git a/docs/book/en/chapters/work-graph-and-authority.md b/docs/book/en/chapters/work-graph-and-authority.md
index cf7b840c09..8d4265e50c 100644
--- a/docs/book/en/chapters/work-graph-and-authority.md
+++ b/docs/book/en/chapters/work-graph-and-authority.md
@@ -44,7 +44,7 @@ Owner operations have lifecycle authority; automated work has quota admission. C
## Claims, leases and current execution proof
-`handoff_mode` determines applicable constraints. Default `legacy` retains soft-claim/hard-lease compatibility; `soft_claim` and `hard_lease` have their own rules. Some legacy terminal paths can return `terminal_fence_not_required`. A regression in one mode is not proof of strong exclusion across every writer.
+`handoff_mode` determines applicable constraints. Default `legacy` retains soft-claim/hard-lease compatibility; `soft_claim` and `hard_lease` have their own rules. Some legacy terminal paths can return `terminal_fence_not_required`.
Promoted File/SQLite authority reads from the selected provider rather than falling back to old lease files. Source selection, registration and current Todo eligibility participate alongside the lease. `task-lease inspect` is an observation, not a lock held across subsequent work.
@@ -93,7 +93,7 @@ Handoff is more than sending a message. A recipient must know which work was rec
**Sixth, return the result to its acceptor.** T3 reassesses current artifacts and decisions. Message delivery, recipient input adoption, work acceptance, publication permission and actual external delivery each require appropriate evidence. None alone establishes the whole chain.
-This six-step teaching case does not claim automatic coordination across every Host, device or repository. Qualify the relationships the user actually needs.
+Qualify the relationships the user actually needs.
## Workspace isolation is not integrated correctness {#parallel-editing}
diff --git a/docs/book/en/chapters/workspace-v1.md b/docs/book/en/chapters/workspace-v1.md
index f790554ac2..70c65a9374 100644
--- a/docs/book/en/chapters/workspace-v1.md
+++ b/docs/book/en/chapters/workspace-v1.md
@@ -36,11 +36,11 @@ The Workspace presents and initiates governed actions, but Goal, Todo, Gate, eve
- **HTTP success is not write completion.** A request being accepted and an action completing are two different things, and the second may be stopped by a Gate or rejected by a stale check.
- **A button is not an independent authority.** Goal stop/resume checks owner authority and the reviewed fingerprint; Todo actions use lifecycle rules; quota governs eligibility for automated Turns.
-The whole chapter compresses into one sentence: **the Workspace is where you observe and initiate; it is not a new source of truth.**
+The whole chapter compresses into one sentence: **the Workspace is where you observe and initiate.**
## Confirm the runtime before trusting the page
-A page appearing does not mean the control plane is healthy. Check version and diagnostics before starting or reusing the service; `dashboard --no-open` is not merely a state query:
+Check version and diagnostics before starting or reusing the service; `dashboard --no-open` is not merely a state query:
```bash
loopx --version
@@ -148,7 +148,7 @@ After configuring, read back the Goal, Agent, Topic, ingress mode, Session bindi
loopx lark-inbox drain --goal-id --agent-id
```
-Disconnect removes only that Goal's Topic route; it does not delete the Goal, Session, history, or other connections. A message arriving also does not mean the Agent gained send, repository-write, or production permission; those actions still pass through their own Gates and Provider readback.
+Disconnect removes only that Goal's Topic route; it does not delete the Goal, Session, history, or other connections. those actions still pass through their own Gates and Provider readback.
## One-off generation and continuous delivery are two authorization chains
@@ -160,7 +160,7 @@ loopx periodic-report inspect-profile --preset weekly --format json
`active` and `generation_allowed` in the receipt should both be `true`. The built-in weekly profile has no schedule and no sink, so **one generation creates no recurring task and sends no message**.
-Continuous reporting is a separate authorization chain: a custom profile declares the cadence, Host Automation performs the waking, and `enabled: true` on a machine or Goal subscription together with an explicit `route_ref` constitutes continuous-delivery authority. Pausing the Automation, disabling the profile, or closing the subscription stops the corresponding path. A successful generation does not mean a successful external send; the Provider, sending identity, route, and message readback each still need verification.
+Continuous reporting is a separate authorization chain: a custom profile declares the cadence, Host Automation performs the waking, and `enabled: true` on a machine or Goal subscription together with an explicit `route_ref` constitutes continuous-delivery authority. Pausing the Automation, disabling the profile, or closing the subscription stops the corresponding path. the Provider, sending identity, route, and message readback each still need verification.
## Cost and boundary
@@ -170,7 +170,7 @@ Continuous reporting is a separate authorization chain: a custom profile declare
**Cost three: four kinds of "enabled" must be distinguished.** Collapsing them into one switch misjudges capability availability, and keeping them apart carries real mental overhead.
-**Boundary one: the Workspace does not own facts.** A broken UI proves neither a healthy control plane nor stopped execution. Distinguish source, runtime and projection first. Only after confirming source and execution conditions can the fault be limited to display recovery, not manual state edits through the UI. It also does not constitute Stage 2C authority — qualification and promotion of a shared-authority provider come from separate shadow and conformance work, not from the existence of an operator surface.
+Distinguish source, runtime and projection first. Only after confirming source and execution conditions can the fault be limited to display recovery, not manual state edits through the UI. qualification and promotion of a shared-authority provider come from separate shadow and conformance work.
**Boundary two: desktop updates are narrowly scoped.** Updates can only come from the fixed official feed; macOS uses updater signature and ad-hoc code signing and should not be described as notarized. Restoring a previous version also does not promise to reverse a future-incompatible Goal schema.
@@ -190,10 +190,6 @@ For one Workspace acceptance pass, confirm at least that:
## Invariants
-1. **The UI is a projection, not a source of truth.** Re-read the source before any consequential judgment.
-2. **HTTP success does not prove the write completed.** Only a receipt and readback do.
-3. **A click is not authorization.** Goal lifecycle accepts owner operations, Todo lifecycle checks work transitions, and the current quota contract admits automated Turns. The page grants none of these permissions.
-4. **The four kinds of "enabled" need separate evidence.** They may be prerequisites for one another; one switch does not establish that every condition holds.
-5. **A message arriving does not widen permission.** Neither capture scope nor ingress mode grants new write authority.
-
-These five answer one question: **when the interface tells you everything is fine, what makes that believable?**
+1. **The UI is a projection.** Re-read the source before any consequential judgment.
+3. Goal lifecycle accepts owner operations, Todo lifecycle checks work transitions, and the current quota contract admits automated Turns. The page grants none of these permissions.
+4. **The four kinds of "enabled" need separate evidence.** They may be prerequisites for one another.
diff --git a/docs/book/en/index.md b/docs/book/en/index.md
index 8567677d75..4778f3006c 100644
--- a/docs/book/en/index.md
+++ b/docs/book/en/index.md
@@ -45,8 +45,7 @@ waits for CI, crosses sessions, changes owners, encounters approval gates, and r
LoopX keeps the goal, work queue, authority, evidence, and recovery conditions in a project-owned control
plane.
-This book is not a copy of the LoopX CLI reference, and it does not assume that you want to contribute to
-the Kernel. It gives external developers a stable path for deciding:
+It gives external developers a stable path for deciding:
- whether a task needs only one session, a persistent Host goal, or a project-level control plane;
- when Todo, Gate, Evidence, Quota, monitor, and recovery contracts add real value;
@@ -72,7 +71,7 @@ source change. Contributions are not limited to Kernel maintainers, and the Cour
mechanism model further into implementation, rules, and validation. You can work on the Control Plane,
Capabilities and Domain State, Providers, Host or Runner integration, projections, documentation and
fixtures, or Extension and package lifecycle. An Extension is one delivery choice for independently
-versioned or optional functionality, not the default shape of every contribution.
+versioned or optional functionality.
## Current validation baseline
@@ -84,11 +83,11 @@ versioned or optional functionality, not the default shape of every contribution
The official public protocols remain authoritative for protocol facts. Commands that change across
releases remain authoritative in the release you use, its current `--help`, and official documentation.
-This book owns the learning path and explanatory model, not another complete command reference.
+This book owns the learning path and explanatory model.
In `v0.5.4`, key semantics for the Effect Program, Turn settlement, Todo completion, quota delivery
routing, workspace causality, and scheduler state sit behind typed TypeScript owners. During the
migration, the Python CLI still owns transport, legacy projections, external Provider calls, and some
-durable writeback. These are not two independently evolving control planes. Treat the
+durable writeback. Treat the
[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)
-on current `main` as the direction for later stages, not as shipped `v0.5.4` behavior.
+on current `main` as the direction for later stages.
diff --git a/docs/book/en/welcome-wagon.md b/docs/book/en/welcome-wagon.md
index e392465b86..7b32124bfe 100644
--- a/docs/book/en/welcome-wagon.md
+++ b/docs/book/en/welcome-wagon.md
@@ -239,7 +239,7 @@ A first review can answer only six questions:
Cross-direction questions may enter an
[Open Strategy Review](/loopx/docs/community/open-strategy-reviews/). It produces a disposition, owner,
-next artifact, and review trigger; it does not replace the RFC, Issue, or PR path with a meeting vote.
+next artifact, and review trigger.
## Ask For Help Without Losing The Signal {#ask-for-help}
diff --git a/docs/book/index.md b/docs/book/index.md
index 6c2aa7f13f..9a1c91f4bd 100644
--- a/docs/book/index.md
+++ b/docs/book/index.md
@@ -41,7 +41,7 @@
交接、等待和外部状态变化。LoopX 把这些过程中的目标、工作队列、权限、证据和恢复条件
放进项目拥有的控制面。
-本书不复制 LoopX CLI reference,也不要求读者成为 Kernel 核心贡献者。它提供一条稳定的
+它提供一条稳定的
学习路径,让外部开发者能够判断:
- 当前任务只需要一次普通会话,还是需要持久 Goal;
@@ -74,11 +74,10 @@ Extension 只是可独立版本化和交付的一种路径。
- 运行时前提:Python 3.11+ 与 Node.js 22.22.3+。
协议解释以 LoopX 官方公开合同为事实源。易变化的命令仍以对应发布物、官方文档和当前
-`--help` 为准;本书负责教学顺序与心智模型,不成为另一份完整命令参考。
+`--help` 为准;本书负责教学顺序与心智模型。
`v0.5.4` 已把 Effect Program、Turn settlement、Todo completion、quota delivery routing、
workspace causality 与 scheduler state 等关键语义放到 typed TypeScript owner 后面。Python CLI
-仍负责迁移期 transport、兼容投影、外部 Provider 调用和部分持久化写回;这不是两套可独立演进的
-控制面。当前 `main` 的后续迁移阶段以
+仍负责迁移期 transport、兼容投影、外部 Provider 调用和部分持久化写回。当前 `main` 的后续迁移阶段以
[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)
为准,不应倒推为 `v0.5.4` 已发布行为。
diff --git a/docs/book/welcome-wagon.md b/docs/book/welcome-wagon.md
index 8a38b2859f..5a7201db0c 100644
--- a/docs/book/welcome-wagon.md
+++ b/docs/book/welcome-wagon.md
@@ -260,5 +260,5 @@ problem
- 想修改 LoopX:读[开发者贡献地图](chapters/source-protocol-map.md);
- 想深入 Kernel:进入 [Control-Plane Developer Course](chapters/12-control-plane-course.md)。
-完成一条路线以后再选择下一条。Welcome Wagon 的目标不是让新人一次理解所有东西,而是让第一
+完成一条路线以后再选择下一条。Welcome Wagon 的目标是让第一
次真实行动足够安全、可验证,并且能被社区接住。
diff --git a/docs/concepts/interaction-pattern-catalog.md b/docs/concepts/interaction-pattern-catalog.md
index 273fb01aa6..ca9d49259d 100644
--- a/docs/concepts/interaction-pattern-catalog.md
+++ b/docs/concepts/interaction-pattern-catalog.md
@@ -2700,7 +2700,7 @@ keep "we stopped supporting this" from becoming "this was never configured".
(`loopx/control_plane/coordination/local_authority_shadow.ts:57`) rather than
disappearing into a transport error, because a rejection that looks like a
transient failure invites a retry loop.
-3. **Clearing is neither enable nor bootstrap.** One setting is retired; the
+3. One setting is retired; the
replacement capture path is configured on its own terms.
`apply_coordination_shadow_changes` is documented as "Clear retired settings
and configure the transaction-bound shadow independently"
diff --git a/docs/development/README.md b/docs/development/README.md
index 83b2b5712d..f9c5f5e970 100644
--- a/docs/development/README.md
+++ b/docs/development/README.md
@@ -86,14 +86,17 @@ The usual loop is:
issue or regression
-> deterministic characterization
-> focused implementation
- -> focused tests and durable smoke
- -> catalog-selected canary
- -> owner review when behavior is sensitive
+ -> focused tests, durable smoke, and catalog-selected canary (`loopx canary premerge`)
+ -> Goal-bound exact-head review (`loopx pr-review --goal-id GOAL`, respecting `wait_for_ci=false` without polling remote CI)
+ -> immediate eligible self-merge or maintainer handoff
-> release outcome observation when needed
```
-通常闭环为:问题或回归 -> 确定性刻画 -> 聚焦实现 -> 单测与 durable smoke ->
-catalog 选择的 canary -> 敏感变更 owner review -> 必要时观察发布结果。
+通常闭环为:问题或回归 -> 确定性刻画 -> 聚焦实现 -> 单测、durable smoke 与 catalog 选择的 canary(`loopx canary premerge`)-> 绑定 Goal 的精确头评审(`loopx pr-review --goal-id GOAL`,遵守 `wait_for_ci=false`,不等待也不轮询远端 CI)-> 满足自合并资格时立即合并或交由维护者合入 -> 必要时观察发布结果。
+
+When the owning Goal sets `pull_request_review.wait_for_ci=false`, deterministic local checks plus Goal-bound exact-head review and readiness (`--registry /.loopx/registry.json --goal-id `) form the complete pre-merge gate; never wait for or poll asynchronous GitHub Actions CI before finishing review or eligible self-merge.
+
+当所属 Goal 配置了 `pull_request_review.wait_for_ci=false` 时,本地确定性验证加上显式绑定 Goal 的精确头评审与就绪检查(`--registry /.loopx/registry.json --goal-id `)即构成完整合入前门禁;不得为等待或轮询异步 GitHub Actions CI 而阻塞评审结论或符合条件的自合并。
## Engineering Scope And Refactoring
@@ -223,14 +226,12 @@ compliance and live effects. Existing sessions may retain an older copy.
Run `uv run --extra test python -m pytest -q tests/test_repository_instruction_delivery.py`
for root size, shared import, local routes and existing inbound anchors. Review
a moved obligation clause by clause: owner, modality, scope, order, exceptions,
-evidence provenance, continuation and stop conditions. A link test or shorter
-file does not establish equivalence. Keep operational rules in their existing
+evidence provenance, continuation and stop conditions. Keep operational rules in their existing
owners rather than adding another parallel policy collection.
Design sources and the disposition of the earlier proposal are recorded in
[the instruction/skill/prompt study](../research/2026-10-17-agent-instruction-skill-prompt-guidance.md).
-
### Progressive Context For Development
The default working context should answer the current decision: the accepted goal,
@@ -275,7 +276,7 @@ Existing sessions may retain old instructions; source edits alone do not prove
native startup adoption or agent compliance.
For product context delivery, selection, continuation and replanning have different
-information needs. A suggested `selected_todo` is not proof of an actual work choice.
+information needs.
A qualified continuation can retain the bound work in full and make other candidates
discoverable with exact details; a new choice must inspect what that choice needs.
Do not implement this by filtering a full-required response in the caller. Change
@@ -302,10 +303,9 @@ and unknown model cost/adoption rather than inferring benefit from fewer bytes.
日志和完整证据在核验、争议、重规划、收口等需要它们的环节展开。默认仍显示相关
失败或过期信号;验收声明必须读取对应证据,索引和旧 Agent 结论不代替核验。
入口指引保留核心义务,详细流程以明确触发条件链接,不急切加载全部文档/Skill。
-移动指导须保留主体、顺序、义务强度、范围、例外和停止条件;源文件更新不证明
-当前宿主已加载,也不证明模型实际遵从。
+移动指导须保留主体、顺序、义务强度、范围、例外和停止条件;
-产品侧按选择、继续执行、重规划区分需要的信息;`selected_todo` 不证明模型已选择。
+产品侧按选择、继续执行、重规划区分需要的信息;
合格的已绑定任务接续可保留当前工作全文和其他候选的可发现入口,但不能在仍要求
全读的接口外手动裁剪。范围 owner、必读指引、详情接口、实际输入及恢复绑定应一起
替换;未交付正文不能进入保留基线,丢失上下文须恢复原决定而非重新准入。
diff --git a/docs/development/bugs/workspace-status-access-errors.md b/docs/development/bugs/workspace-status-access-errors.md
index 2787b6cf0d..2919e4e950 100644
--- a/docs/development/bugs/workspace-status-access-errors.md
+++ b/docs/development/bugs/workspace-status-access-errors.md
@@ -39,7 +39,7 @@ HTTP 仍为 **500**;固定公开错误文案不变,仅增加:
- 异常链最多检查 8 个节点,按对象身份去环;显式 `__cause__` 优先。
仅 `EffectRuntimeStartupError` 的 `runtime_launch_failed` /
`runtime_request_failed` 允许沿未抑制的隐式 `__context__` 查找权限原因。
- 普通历史 context、`raise ... from None` 不构成权限证据。
+ 普通历史 context 分支停止分类;`raise ... from None` 抑制的隐式 context 也在此停止。
前端只在 HTTP >= 500 时识别该结构化错误码。错误体按实际字节最多读取 16 KiB,
不信任 Content-Length;复用单次请求的 30 秒超时。读完、超限或取消后释放读取器。
@@ -64,7 +64,7 @@ Chat 操作、审批、状态机、Goal 注册信息和文件权限均不改动
## 仍未细分的故障
`service` 仍可包含注册数据解析、依赖/安装、运行时启动、通信/协议、非权限结构化
-I/O、未知投影异常及上游 5xx。这不是封闭的运行时枚举,也不是每项均实机复现。
+I/O、未知投影异常及上游 5xx。
依据见 [registry.py](../../../loopx/registry.py) 与
[collection.py](../../../loopx/control_plane/status/collection.py)。
仅当异常最终形成逐 Goal 请求的 5xx 才进入此提示;内部已处理的健康诊断不在本范围。
diff --git a/docs/development/ci-impact-selection.md b/docs/development/ci-impact-selection.md
index 1d257804a8..bd028eb2f9 100644
--- a/docs/development/ci-impact-selection.md
+++ b/docs/development/ci-impact-selection.md
@@ -47,7 +47,7 @@ Frontstage Pages 只验收并发布公共网站和 projection demo,保留构
仍由 Python Tests 承担。新合并不会中断正在运行的正式发布,只替换等待中的下一次
发布;同一 PR 的旧验证仍会取消。
-本方案不是为每类 PR 维护一套测试清单,而是明确重型 job 的职责。纯前端变化不需要
+本方案是明确重型 job 的职责。纯前端变化不需要
重跑后端持久化与崩溃恢复矩阵,但前端自己的实际构建与浏览器验收成为必需项。
预算、静态宿主 prompt 和后端 Python/TS 逻辑暂不享受免跑;它们仍可能改变核心行为。
新增一种豁免只需审阅其业务边界和保留的验收,不要求列举全部替代测试文件。
@@ -78,8 +78,7 @@ remain required by `checks`, as does the static lane. The existing `pytest` and
`merge-gate` still reject any required failure, skip or missing coverage. This
removes the full browser/TypeScript wait from Python's critical path, but allows
up to six already-bounded Python jobs to overlap those lanes; a later browser
-failure may now coexist with running Python tests. It neither reserves hosted
-capacity nor proves a throughput improvement. `ci:full` selects all qualification,
+failure may now coexist with running Python tests. `ci:full` selects all qualification,
without overriding failed admission; use a manual run for complete diagnostics
of a failing revision. Older queued workflow versions keep their own policy.
@@ -152,8 +151,7 @@ worker 秒数、各阶段总和与最慢用例。缺失、损坏或矛盾记录
断言结构;子测试单独保留失败位置,不重复计时。新增 JSON 不含消息、参数、locals 或
捕获的 IO,原 pytest 输出不变。未知类、缺失源码或诊断异常仍是证据缺口;未送达的
报告与收集失败不在覆盖范围,不能据此完成原因归因、证明真实性或豁免完整门禁。
-并发 phase 总和不是
-runner-minutes、排队时长或 CPU 时间;不完整记录仅给出下界,环境准备与占用须结合
+不完整记录仅给出下界,环境准备与占用须结合
job/step 时间戳。记录不进入 timing cache、不改变测试选择、不替代门禁;没有耗时
历史时仍按原等权规则分片。
完整 pytest node id 用 SHA-256 标识;显示名去除参数内容并限制为 256 字符。
@@ -195,7 +193,7 @@ describes the workflow topology, not how many jobs actually ran.
`python_shards` 从 `checkout_sha` 对应的不可变 workflow 读取静态分片轴,当前为六片,
不另存历史计数;不支持或不连续的拓扑直接报错,不输出猜测值。文档/前端豁免仍为零。
-它描述 workflow 拓扑,不能证明任何分片实际执行或 JUnit/coverage 已完整。
+它描述 workflow 拓扑。
The merge gate requires
success for required jobs and an explicit skip for exempt ones; failure,
@@ -294,7 +292,7 @@ coverage command runs only in shard 1, whose `lcov.info` the existing merger
already consumes; browser coverage and acceptance receipts remain required from
all three shards. The merger rejects missing unit coverage or incomplete browser
acceptance. This removes two duplicate unit-coverage invocations per full or
-presentation run; it does not establish a hosted wall-time improvement.
+presentation run.
旧 PR 清理独立为 CI Maintenance,保留原有来源与 head 校验,也不执行 PR 代码。
清理成功不再显示为一次 Python Tests 成功。Dashboard 的单元覆盖率只在第 1 片
diff --git a/docs/development/contributor-tasks.md b/docs/development/contributor-tasks.md
index b47884b69f..d6ef50eb55 100644
--- a/docs/development/contributor-tasks.md
+++ b/docs/development/contributor-tasks.md
@@ -66,8 +66,7 @@ contributors by anchored rows.
For first-review contacts, accepted subsystem owners and voluntary scope
confirmation, use the [governance review roster](../../.github/GOVERNANCE.md#first-review-responsibilities).
-Request the closest contact before escalating to the lead maintainer. A
-preferred review contact is not an exclusive task claim or new merge authority.
+Request the closest contact before escalating to the lead maintainer.
1. Prefer a linked GitHub issue. If there is no issue yet, open one with the
contributor task template; it asks for the anchor and the gap.
@@ -81,8 +80,7 @@ preferred review contact is not an exclusive task claim or new merge authority.
there is a public helper slice instead.
Before claiming a row, reconcile its anchor with latest main, related PRs and
-the roadmap. Historical rows are not proof that a missing feature remains
-unimplemented or a proposed slice is still useful. The
+the roadmap. The
[Technical Directions map](../project/technical-directions.md) owns contributor
routing and current maturity; this board does not keep a second copy.
diff --git a/docs/development/control-plane-course/00-concept-primer.md b/docs/development/control-plane-course/00-concept-primer.md
index 03c875f29b..4f76ebb4ac 100644
--- a/docs/development/control-plane-course/00-concept-primer.md
+++ b/docs/development/control-plane-course/00-concept-primer.md
@@ -28,7 +28,7 @@ session 结束、模型切换、Agent 交接和外部世界变化。完整 trans
| 何时再看,何时停止? | 周期唤醒会热轮询,空 todo 也可能误停 | monitor、scheduler hint、backoff、terminal audit |
| 失败或换人后从哪里继续? | transcript 不能提供稳定 identity 和幂等边界 | event、run history、lineage、replay、repair |
-外置状态不是把 transcript 原样搬到磁盘。它只保存下一轮重建正确决定所需的紧凑事实,旧推理
+外置状态只保存下一轮重建正确决定所需的紧凑事实,旧推理
可以丢弃,当前环境必须重探测。
### 长程质量同时包含“跑稳”和“跑好”
@@ -74,7 +74,7 @@ Kanban is the picture; the control plane is the contract.
## 从普通对话、原生 Goal 到 LoopX
-理解 LoopX 最容易的方法,不是先背模块,而是看控制信息逐层外置:
+理解 LoopX 最容易的方法:
| 形态 | 外置了什么 | 擅长解决什么 | 仍未覆盖什么 |
| --- | --- | --- | --- |
@@ -83,13 +83,11 @@ Kanban is the picture; the control plane is the contract.
| LoopX control plane | 结构化 canonical state,以及由它派生的每轮 CLI packet | 跨 session、Agent、host 和外部系统组织可审计的长期生命周期 | 领域判断、模型推理和外部系统本身的正确性 |
Codex 的自动化基线通过 `thread/goal/set` 持久化 objective/status,通过
-`thread/goal/get` 读回,再用 `turn/start` 继续执行。交互式 `/goal` 是可见的人工入口;仅把
-`/goal` 写在普通 prompt 开头,不等于已经建立了持久 Goal。原生 Goal 的关键价值,是把“这次
+`thread/goal/get` 读回,再用 `turn/start` 继续执行。交互式 `/goal` 是可见的人工入口。原生 Goal 的关键价值,是把“这次
对话要做什么”提升成 host 可持续维护和判断的 goal lifecycle。抽象来看,它提供的是一个
稳定 objective,加上 host 对继续、暂停、预算受限或完成的结果判断。
-Host 可以自行安排后续 Turn,模型也可以在执行中调整方案;这仍不等于项目已经拥有 typed
-scheduler ACK 或 replan delta。区别不在于系统“会不会再跑、会不会改计划”,而在于 cadence、
+Host 可以自行安排后续 Turn,模型也可以在执行中调整方案;区别不在于系统“会不会再跑、会不会改计划”,而在于 cadence、
路线变化及其证据是否成为跨 host、跨 Agent 可重放的结构化事实。
LoopX 不否定这层能力,而是继续外置两层:
@@ -114,7 +112,7 @@ objective · lifecycle goal · todo · authority · quota · evidence · rec
host/runtime executes the current Turn
```
-CLI packet 不是第二份 canonical state,也不是把所有历史塞回 prompt。它是带版本、lineage 和
+CLI packet 是带版本、lineage 和
下一步命令的当前决策投影;下一 Turn 必须重新读取并重新生成,不能靠模型记住上一份 packet。
Host 中长期保留的是稳定的 re-entry body:它只说明怎样找到 goal、调用 LoopX CLI 并取得
当前 packet,不承载某一轮的 packet 内容。
@@ -183,11 +181,11 @@ flowchart LR
- **Capability:** 负责归一化事实、验证结果并提出有限的 typed transition;
- **Kernel:** 负责接受或拒绝 transition,并持久化 todo、gate、monitor、writeback、quota 与调度。
-Domain State、evidence 和 receipt 是这些角色之间传递的工件,不是新的 owner。Extension
-则是 provider 的交付和生命周期边界,也不是第五种运行责任。Host/runtime 承载 session、
+Domain State、evidence 和 receipt 是这些角色之间传递的工件。Extension
+则是 provider 的交付和生命周期边界。Host/runtime 承载 session、
工具和调用,同样不新增领域 decision owner。
-这不是一条永远顺利的流水线。每次 writeback 后,Kernel 都要根据新事实重新决定:
+每次 writeback 后,Kernel 都要根据新事实重新决定:
```text
continue | wait | ask | replan | repair | terminal
@@ -281,7 +279,7 @@ Agent 是控制面身份,不等同于某个固定模型或进程。更换 runt
### Turn 是一次有界动作
**Turn** 从一份带版本和 lineage 的只读 snapshot 开始,完成一个有界判断或动作,返回 typed
-result。它不是整个长期任务。
+result。
一次 Turn 可以:
@@ -307,8 +305,7 @@ canonical state + fresh environment
```
Packet 要足够薄,只携带本轮 identity、允许动作、必要 gate、验证条件和 writeback 命令;但又
-不能薄到遗漏 required proof、scope 或 terminal gap。Packet 的压缩质量因此是控制面正确性的一部分,
-不是单纯的 prompt 优化。
+不能薄到遗漏 required proof、scope 或 terminal gap。Packet 的压缩质量因此是控制面正确性的一部分。
### Scheduler 与 heartbeat 只负责“何时再看”
@@ -337,7 +334,7 @@ Kernel 提议下一次 cadence
| Lease | 当前执行窗口是否被占用,何时过期? | 短期、可续租、可回收 |
| Gate | 哪个 scoped decision 尚未满足? | 由对应 authority 明确解决 |
-Claim 不自动授予生产写权限,lease 不代表长期 ownership,普通 user todo 也不自动冻结整个 goal。
+Claim 不自动授予生产写权限。
Gate 必须带清晰 scope;若 scope 缺失,应修复投影或状态,而不是猜测它约束所有 Agent。
### Authority 决定谁能提交哪种 transition
@@ -394,7 +391,7 @@ Agent 持续违反运行协议时,**self-repair** 修的是系统规则、状
## 人的干预怎样真正改善下一轮
-人工输入不是一种统一的“反馈字段”。它对生命周期的含义不同,必须写入对应的结构:
+人工输入对生命周期的含义不同,必须写入对应的结构:
| 人工输入 | 正确落点 | 对下一轮的影响 |
| --- | --- | --- |
@@ -404,7 +401,7 @@ Agent 持续违反运行协议时,**self-repair** 修的是系统规则、状
| “以后这个仓库的 PR 摘要应更短” | reviewed, scoped soft preference candidate | 在匹配 surface 中影响排序或改写 |
| “这个模块过去常因某类边界失败” | procedural experience candidate | 经当前 artifact 复核后影响诊断与验证计划 |
-**Reward Memory** 解决的是“有价值的人类判断怎样跨 run 复用”,不是“谁有权执行动作”。它把
+**Reward Memory** 解决的是“有价值的人类判断怎样跨 run 复用”。它把
run reward、hard policy、soft preference、procedural experience 与 working context 分开,
并要求 source、scope、authority、freshness、supersession 和 application receipt。记忆的
confidence 不会扩大权限,召回的技术经验也必须在当前代码和证据上重新验证。
diff --git a/docs/development/control-plane-course/01-agent-loop-effectful-program.md b/docs/development/control-plane-course/01-agent-loop-effectful-program.md
index e5bf112433..b0078df691 100644
--- a/docs/development/control-plane-course/01-agent-loop-effectful-program.md
+++ b/docs/development/control-plane-course/01-agent-loop-effectful-program.md
@@ -4,7 +4,7 @@
## 这一讲要建立的判断
-Harness 不是“一堆状态机”,而是 agent loop 的 effectful program 和 effect
+Harness 是 agent loop 的 effectful program 和 effect
interpreter。agent loop 是被解释的循环,harness 才是解释外部 effect 的程序;
状态机只是 harness 内部的决策表。
@@ -32,7 +32,7 @@ while true:
model -> effect request -> harness interprets effect -> observation -> model
```
-模型输出的是动作请求,不是动作本身。真正的执行、权限、预算、调度、失败恢复、
+模型输出的是动作请求。真正的执行、权限、预算、调度、失败恢复、
证据沉淀都发生在 harness 这一侧。
## 为什么 harness 是这个解释器
@@ -107,7 +107,7 @@ Agent proposes next bounded turn
传递一个可调用对象。它的 `handler` 是数据:packet 里的 `next_effect` 编码下一组
CLI 动作、scheduler ACK 和 failure hint,由 host 或下一轮 automation 执行。
-这个差异不是缺一个 middleware 层,而是控制面的合理形状:
+这个差异是控制面的合理形状:
- 可以 short-circuit:`decision` / `effective_action` 直接表达
`skip`、`wait`、`monitor_quiet_skip`、`repair_bridge`、`ask_owner`,不会假装原
@@ -139,7 +139,7 @@ ACK 和 writeback 都编码进同一个 request。模型仍然只提出 effect r
如果未来厂商 API 原生支持 serial tool calls 或 interleaved reasoning,对 LoopX
来说只是解释器内部的一种 execution mode:
-- 串行、并行、交错是 execution strategy,不是新的状态机;
+- 串行、并行、交错是 execution strategy
- `effect_request -> interpretation -> observation -> next_effect` 仍然稳定;
- `next_effect` 从一条 CLI 命令变成一段有序 effect program。
@@ -199,7 +199,7 @@ transaction 直接完成 decision、durable write 与 canonical receipt projecti
这些路径的 authority boundary 不同:quota CLI 跨 agent/host,turn driver 拥有
callback,task lease 则在自己的 native transaction 内完成原子 persistence。把它们
-塞进一个 shared executor 会隐藏 owner,而不是减少重复知识。当前共享层只统一可复用
+塞进一个 shared executor 会隐藏 owner。当前共享层只统一可复用
primitive,不统一执行权。
## 四条不变量比类名更重要
@@ -213,11 +213,11 @@ Effect Program 的价值落在四条可复核不变量上:
4. **可重放、至多一次**:已提交 prefix 可以恢复,但同一 identity 不重复结算。
普通 successor completion 仍是 Todo bounded context 的 lifecycle action,可以在
-settlement 前建立下一条 runnable frontier;它不是 terminal closeout。只有 final
+settlement 前建立下一条 runnable frontier;只有 final
`no_followup` 会改变 Goal 的终态,因此必须放到 matching spend 后。这样无需放宽
`terminal_no_followup` 守卫,也不会出现“先终止、再给终态 effect 补 spend”的例外。
-测试不是从当前输出生成 golden,而是用独立语义 oracle 检查三类 adapter:
+测试是用独立语义 oracle 检查三类 adapter:
- `test_effect_program_adapter_conformance.py` 统一验证 identity、receipt 顺序、failure、
short-circuit 和 scheduler-outside-settlement,并用 step reorder、failure 丢失、
diff --git a/docs/development/control-plane-course/02-goal-control-plane-architecture.md b/docs/development/control-plane-course/02-goal-control-plane-architecture.md
index 05405bf61b..efddc21848 100644
--- a/docs/development/control-plane-course/02-goal-control-plane-architecture.md
+++ b/docs/development/control-plane-course/02-goal-control-plane-architecture.md
@@ -25,10 +25,9 @@ prompt / transcript
```
Codex 原生 Goal 已经完成关键的第一步:`thread/goal/set` 把 objective、status 与可选预算绑定到
-thread,`thread/goal/get` 允许读回,host 可以围绕它继续 `turn/start`。LoopX 解决的不是
-“再存一遍 goal string”,而是原生 Goal 故意没有承担的项目控制状态:todo graph、claim、
+thread,`thread/goal/get` 允许读回,host 可以围绕它继续 `turn/start`。LoopX 解决的是原生 Goal 故意没有承担的项目控制状态:todo graph、claim、
scoped gate、effect receipt、跨 host cadence、领域 observation、replan 和 recovery。每轮模型
-只接收这些状态派生出的 compact interaction contract,而不是全部历史。
+只接收这些状态派生出的 compact interaction contract。
长程 Agent 的困难不只在模型推理。一次模型 turn 结束后,下面的事实仍要继续成立:
@@ -36,7 +35,7 @@ scoped gate、effect receipt、跨 host cadence、领域 observation、replan
- 外部世界变化后,Agent 能区分“继续做”“等一等”“问人”和“已经结束”;
- 多个 Agent 不会把软认领、执行占用和写权限混成同一个 owner;
- 一次成功调用不会在缺少验证和写回时被误报成进展;
-- 失败、重启、换 session 后,下一轮从已提交事实恢复,而不是重猜上一轮发生了什么。
+- 失败、重启、换 session 后,下一轮从已提交事实恢复。
LoopX 解决的是这组 **goal-level control-plane** 问题:无人干预时靠确定性合同跑稳,有人
干预时把反馈写成 scoped decision、路线修订或经验,使下一轮跑得更好。先看三个差异很大的
@@ -52,7 +51,7 @@ LoopX 解决的是这组 **goal-level control-plane** 问题:无人干预时
## 先分清四种运行责任
-LoopX 的目录、状态文件和执行角色不是同一个分类维度。读一轮真实执行时,先问四个
+读一轮真实执行时,先问四个
owner:
| 角色 | 负责什么 | 不负责什么 |
@@ -70,15 +69,13 @@ owner:
恢复:Kernel -> next todo / gate / monitor / turn -> Agent
```
-Domain State、evidence、receipt 和 projection 是这些角色交换或派生的工件,不是第五个
-owner。Extension 负责 provider 的安装、启停、升级和分发,也不是第五种运行责任;
+Domain State、evidence、receipt 和 projection 是这些角色交换或派生的工件。Extension 负责 provider 的安装、启停、升级和分发;
host/runtime 承载 session、工具和调用,也不新增领域 decision owner。
## Showcase A:PR Issue Fix
Issue-Fix 的产品承诺是:把一条公开 issue 持续推进成小而聚焦、验证充分、可审阅的 PR,
-并跟进到 merged、closed 或明确 no-follow-up。它不是“一次 prompt 生成 patch”,因为真实
-交付还包含候选判断、复现、修改、CI、review correction、冲突、通知、等待和终局收口。
+并跟进到 merged、closed 或明确 no-follow-up。
```mermaid
flowchart LR
@@ -130,14 +127,14 @@ fact,使下一轮可以重新计算 frontier:
| 外部写入结果不确定 | effect receipt + provider readback/reconcile | 先确认外部事实,再决定 retry、successor 或 closeout |
| PR merged、closed 或明确不再跟进 | terminal evidence + no-follow-up rationale | monitor 可关闭,后续 Turn 不会继续轮询已经结束的工作 |
-因此,这个 bot 的“稳定执行”不是一段永不中断的推理,也不是一个永不犯错的 Agent。它允许
+它允许
模型、session、host 和外部系统在边界处失败,但不允许丢失已经确认的事实、effect identity
和下一步恢复路径。长程稳定的目标,是让错误可发现、可归因、可恢复;即使 Agent 犯错,
已提交事实仍然有效,系统仍能形成下一步 frontier。
这也是后续课程的索引:第 3 讲解释 packet 与一次 Turn,第 5 讲解释 claim、successor 和
handoff,第 7 讲解释 monitor cadence 与 quiet wake,第 8 讲解释 evidence、reconcile 和
-self-repair。这里先记住一个判断标准:**稳定不是不中断,而是每次中断后都能从外置事实恢复。**
+self-repair。这里先记住一个判断标准:**稳定是每次中断后都能从外置事实恢复。**
### 一条交付主线,怎样反哺执行系统
@@ -182,7 +179,7 @@ flowchart LR
Capability Pack;可选或独立版本的实现进入 extension/provider;host 特有的 session、工具
和事件适配留在 host adapter。只有 LoopX 默认必须拥有的通用生命周期规则才进入 Kernel。
-因此,“系统能力自进化”不是第七个架构层,也不是模型拥有了修改自身的特权。它是同一条
+它是同一条
goal-level lifecycle 管理的一类进阶工作:交付证据发现缺口,Kernel 授权改进,独立执行面
产出候选版本,验证与发布合同决定是否激活,readback 和 guardrail 决定保留还是回滚。
@@ -244,7 +241,7 @@ issue body、raw check log、凭据或本地路径。GitHub 仍是权威来源
## Showcase B:Multi-Agent 研究团队
研究协作复用 Goal、Todo、claim、lease、证据与独立验收。角色只声明自己的研究工作与
-写入边界;创建任务或发送消息不等于启动 worker,也不授予实验、推广或发布权限。
+写入边界;
当前可运行示例见
[managed research team](../../../examples/managed-research-team/README.md),
@@ -283,8 +280,8 @@ flowchart LR
```
图中只有经过 Kernel 接受的 transition 才能改变工作生命周期。Explore Graph 上的
-`supports`、`refutes`、`depends_on` 或 `leads_to` 是证据关系,不是执行边;Explore Harness
-输出的是候选组合和风险说明,不是 claim、launch 或 spend receipt。
+`supports`、`refutes`、`depends_on` 或 `leads_to` 是证据关系;Explore Harness
+输出的是候选组合和风险说明。
### Graph 记住什么,Harness 计算什么
@@ -383,7 +380,7 @@ Domain State 保存 feasibility、PR lifecycle、experiment result、hypothesis
## Goal Control Plane Authority Map
-下面的总览图不是源码层次图。它表示事实、决策、执行和回执怎样跨边界流动。
+它表示事实、决策、执行和回执怎样跨边界流动。
```mermaid
flowchart TB
@@ -420,8 +417,7 @@ flowchart TB
读图时先记住四种运行责任,再看两个工件边界:
-1. **Kernel 拥有 goal lifecycle。** Host 被唤醒不等于获得 delivery 权限,一轮结束也不等于
- goal 完成。
+1. **Kernel 拥有 goal lifecycle。**
2. **Capability 拥有翻译规则。** 它理解 `CHANGES_REQUESTED`、experiment result 或
holdout metric,但只返回 typed proposal。
3. **Provider 拥有外部 I/O。** 它返回 bounded observation 或 readback,不决定后续 transition。
@@ -457,9 +453,6 @@ sequenceDiagram
关键不变量:
-- observation 不是 transition;
-- proposal 不是 authority;
-- result 不是 accepted result;
- accepted result 在 durable writeback 后才构成进展;
- spend 晚于验证与写回;
- scheduler proposal 在 host apply 并形成 ACK 前仍未结算。
diff --git a/docs/development/control-plane-course/03-first-real-loop.md b/docs/development/control-plane-course/03-first-real-loop.md
index 8da2be7125..e4afe7c1e8 100644
--- a/docs/development/control-plane-course/03-first-real-loop.md
+++ b/docs/development/control-plane-course/03-first-real-loop.md
@@ -64,7 +64,7 @@ read current source state
Showcase 的价值不是给出可复制的 prompt,而是证明这个 transaction shape 能在多轮之后
仍保留正确的 identity、authority、evidence 和 recovery。仓库中的
-`docs/showcases/showcase-catalog.json` 只是公开证据目录,不是隐藏的工作流模板。
+`docs/showcases/showcase-catalog.json` 只是公开证据目录。
Auto ML 还说明同一轮可以消费两个可选 read model:Explore Graph 提供与当前候选相关的
正负证据 lineage,Explore Harness 提供基于 todo、scope 和资源容量的 analysis-only
@@ -124,12 +124,10 @@ LoopX packet 则让当前 Turn 不依赖模型记住完整项目过程。Codex A
Packet 有三个明确的非目标:
- 它不是 canonical state,不能被当作长期写入源;
-- 它不是 authority,显示某项工作不代表可以越过 gate 或 workspace guard;
-- 它不是历史摘要,长 rationale 应留在 evidence artifact,只通过紧凑 ref 进入本轮。
## 一次 Codex App 交互的真实路径
-下面不是概念伪代码,而是公开 CLI 的真实调用路径。任务文本、goal id 和 agent id 都使用占位符,读者可以在自己的测试仓库中复现。
+下面是公开 CLI 的真实调用路径。任务文本、goal id 和 agent id 都使用占位符,读者可以在自己的测试仓库中复现。
### 0. 用户只表达目标
@@ -326,7 +324,7 @@ loopx quota spend-slot \
--agent-id
```
-Spend 是“这轮已形成有效控制面推进”的账,不是“模型被唤醒过”的计数器。dry-run、read-only poll、monitor quiet skip、scheduler ACK 都不应该先花配额。
+Spend 是“这轮已形成有效控制面推进”的账。dry-run、read-only poll、monitor quiet skip、scheduler ACK 都不应该先花配额。
## 为什么 App automation 不是主循环本身
@@ -506,7 +504,7 @@ return {
#### 3. Heartbeat prompt 是 host contract 编译器
-`loopx/heartbeat_prompt.py::build_heartbeat_prompt` 不是 scheduler。它把 goal、peer identity 和可用能力编译成 host 可执行的 prompt:
+它把 goal、peer identity 和可用能力编译成 host 可执行的 prompt:
```python
if not (full or compact or brief or thin):
@@ -526,7 +524,7 @@ quota_spend_command = render_quota_spend_command(...)
refresh_state_command = render_refresh_state_command(...)
```
-核心不是字符串拼接,而是身份约束:多 peer goal 缺少 `agent_id` 时直接失败。否则 claim、workspace guard、quota 和 spend 都无法归因。
+核心是身份约束:多 peer goal 缺少 `agent_id` 时直接失败。否则 claim、workspace guard、quota 和 spend 都无法归因。
#### 4. Quota 把很多局部判断收敛成一个执行决定
@@ -572,21 +570,19 @@ effective_action = _effective_action(...)
#### 读完这一段应能回答
-1. 为什么 `start-goal` 成功返回不等于已经执行 agent turn?
2. 为什么 connected 的判定不能只看 `.loopx/registry.json` 是否存在?
3. 多 peer heartbeat 为什么必须显式携带 `agent_id`?
-4. `should_run=True` 时,哪几类动作仍然不是正常 delivery?
5. 哪一层负责建议 host cadence,哪一层真正触发模型?
## 常见误解
### “LoopX 是另一个 agent runtime”
-不是。LoopX 可以向 host 提供 prompt、调度建议和状态协议,但不替 Codex App 或 CLI 执行模型 turn。
+LoopX 可以向 host 提供 prompt、调度建议和状态协议,但不替 Codex App 或 CLI 执行模型 turn。
### “Heartbeat 每次触发都必须做事”
-不是。`interaction_contract` 可以要求等待、quiet no-op、monitor poll 或 self-repair。是否执行由当前状态决定。
+`interaction_contract` 可以要求等待、quiet no-op、monitor poll 或 self-repair。是否执行由当前状态决定。
### “P0 被用户 gate 卡住,整个 goal 就停止”
@@ -594,7 +590,7 @@ effective_action = _effective_action(...)
### “Supervisor 就是主 agent”
-不是。当前 peer 模型没有 primary/side 的运行时层级。可选 supervisor 是 equal peer
+当前 peer 模型没有 primary/side 的运行时层级。可选 supervisor 是 equal peer
上的观察和 proposal overlay;第 9 讲用它演示规则设计,第 11 讲说明它与其他扩展能力
如何复用同一个 kernel。
diff --git a/docs/development/control-plane-course/04-state-substrate.md b/docs/development/control-plane-course/04-state-substrate.md
index b839530019..2fdbbeaf16 100644
--- a/docs/development/control-plane-course/04-state-substrate.md
+++ b/docs/development/control-plane-course/04-state-substrate.md
@@ -5,7 +5,6 @@
> or the selected File/SQLite authority. See the
> [retirement contract](../../reference/protocols/event-sourced-state-contract-v0.md).
-
> **本讲结论:** Canonical event/state contract 拥有长期事实;active state、status 和
> dashboard 是可重建 read model;session context 不能替代 project memory。
@@ -79,11 +78,10 @@ truth,也不成为第四个状态源。
Runnable | Claimed | Waiting on user | Monitoring | Blocked | Review | Done
```
-这些列不是新的事实源。“Waiting on user”来自 scoped user gate,“Monitoring”来自
-带 cadence 和 target key 的 monitor,“Review”可以来自领域状态与当前 acceptance,
-而不是把每个展示名称写进 Kernel lifecycle enum。
+“Waiting on user”来自 scoped user gate,“Monitoring”来自
+带 cadence 和 target key 的 monitor,“Review”可以来自领域状态与当前 acceptance。
-看板上的移动也对应结构化算子,而不是任意拖拽:
+看板上的移动也对应结构化算子:
| 操作 | 必须保持的约束 |
| --- | --- |
@@ -102,7 +100,7 @@ closure,最终 transition 仍由 Kernel 接受或拒绝。
## Goal 不是聊天线程
-LoopX 的 durable identity 是 goal,不是某个 Codex thread:
+LoopX 的 durable identity 是 goal:
```text
Goal: 长期存在的目标、边界和进度身份
@@ -130,7 +128,7 @@ Dashboard: 只读观察和路由界面
| Project memory | goal identity、objective/boundary、todo/gate、紧凑 evidence、run lineage | 被 replay、投影或由另一 peer 恢复 | 可以,但必须经过 canonical contract |
| Environment | 当前 checkout、host capability、外部服务与 fresh source | 在 handoff 之间变化 | 不能,必须重新探测 |
-恢复的目标不是逐字重建旧 transcript,而是从持久化事实和新鲜环境重新生成可执行
+恢复的目标是从持久化事实和新鲜环境重新生成可执行
决定:
```text
@@ -142,7 +140,7 @@ Project memory 的充分性标准是:更换 session 后,新的 peer 仍能
condition。它不要求逐字复现旧推理。第 5 讲会把这个要求进一步写成 handoff 的
不动点检查。
-可以把这看成长期任务的“最小可恢复状态”,而不是“最大可记忆内容”。外置状态应优先保存:
+可以把这看成长期任务的“最小可恢复状态”。外置状态应优先保存:
- 能改变合法 action set 的事实,例如 gate、claim、capability 与 workspace boundary;
- 能改变下一步判断的事实,例如 fresh observation、acceptance gap 与 monitor due time;
@@ -277,7 +275,7 @@ projection_synced
- 当前 peer lane 在做什么?
- 是否有 contract errors、projection gaps 或 repair needs?
-Status 不是写入口。Dashboard、Lark kanban、review packet 都应该消费 status 或其他 public-safe projection,而不是反向解析私有源文件再写回。
+Dashboard、Lark kanban、review packet 都应该消费 status 或其他 public-safe projection。
## Core State、Domain State 与 Runtime Artifact
@@ -330,8 +328,8 @@ os.replace(tmp_name, path)
从这段代码应读出三个边界:
-1. Domain State 是 project-local、按 goal 与 pack 分区的事实,不是全局 memory dump。
-2. 稳定 key 和 unchanged 判定用于幂等观察,不代表领域 pack 可以决定下一轮执行。
+1. Domain State 是 project-local、按 goal 与 pack 分区的事实。
+2. 稳定 key 和 unchanged 判定用于幂等观察。
3. 返回值显式使用 `path_recorded=False`,public receipt 不应泄露本地路径。
Issue-Fix 与 ML Experiment 的 smoke 分别验证这条通用 seam:
@@ -386,8 +384,7 @@ CLI validation
这里有三个不能省略的性质:
- `agent-a` 必须是注册 peer;
-- claim 是 soft ownership,不是永久权限;
-- status 看到 claim 不等于 status 自己写了 claim。
+- claim 是 soft ownership
## 为什么不能直接编辑 Projection
@@ -425,7 +422,7 @@ registry policy
= current status projection
```
-Replay 不是简单地重放聊天。聊天里可能有:
+聊天里可能有:
- 未执行的建议;
- 失败的命令;
@@ -433,7 +430,7 @@ Replay 不是简单地重放聊天。聊天里可能有:
- 私有文本;
- 被后续状态 supersede 的结论。
-事件则应明确区分 proposal、attempt、executed receipt 和 validation。例如 supervisor 的 `inject` proposal 不是 session 已被注入的证明;只有 capability-matched host receipt 才是执行事实。
+事件则应明确区分 proposal、attempt、executed receipt 和 validation。只有 capability-matched host receipt 才是执行事实。
## Projection Gap:控制面常见故障
@@ -680,7 +677,6 @@ loopx --format json quota should-run --goal-id --agent-id
### 读完这一段应能回答
-1. Registry 为什么不是 todo truth?
2. 为什么 event id 冲突必须 fail closed?
3. Markdown fallback 为什么应保留,但不能继续定义新 runtime 语义?
4. `state_projection_gap` 在哪一层产生,又在哪一层改变执行选择?
diff --git a/docs/development/control-plane-course/05-work-graph-and-peers.md b/docs/development/control-plane-course/05-work-graph-and-peers.md
index d8a66f634c..0819396456 100644
--- a/docs/development/control-plane-course/05-work-graph-and-peers.md
+++ b/docs/development/control-plane-course/05-work-graph-and-peers.md
@@ -28,7 +28,7 @@
## 从三个 Showcase 看同一类工作图
-Issue-Fix、Single-Agent Auto ML 和 Auto Research 的 todo 文本不同,但都不是线性 checklist:
+Issue-Fix、Single-Agent Auto ML 和 Auto Research 的 todo 文本不同:
```text
Issue-Fix
@@ -53,7 +53,7 @@ Auto Research
-> holdout | retry | retirement | promotion_gate
```
-图中的箭头不是模型随口建议的“下一步”,而是带 lineage 的 successor transition。三条图
+图中的箭头是带 lineage 的 successor transition。三条图
都需要回答相同问题:
| 问题 | Issue-Fix | Single-Agent Auto ML | Auto Research |
@@ -86,7 +86,7 @@ identity + role + priority + task_class + action_kind
+ evidence / completion rationale
```
-因此 todo 集合不是按顺序执行的脚本,而是当前 goal 的可计算 frontier。
+因此 todo 集合是当前 goal 的可计算 frontier。
## 两类 Owner 与五类 Task Class
@@ -111,7 +111,7 @@ identity + role + priority + task_class + action_kind
## Priority 不是隐藏工作流
-Todo 文本通常带 `[P0]`、`[P1]`、`[P2]`。Priority 影响候选排序,但不是唯一决策:
+Todo 文本通常带 `[P0]`、`[P1]`、`[P2]`。Priority 影响候选排序:
```text
priority
@@ -141,7 +141,7 @@ quota 可以同时返回:
- `agent_channel.must_attempt=true`,要求推进 P1;
- `safe_bypass_allowed=true`,说明旁路边界。
-这不是矛盾,而是双通道控制。
+这是双通道控制。
## Equal Peer Runtime
@@ -151,7 +151,7 @@ quota 可以同时返回:
- 没有永久的主执行者;
- 没有永久的辅助执行者;
- todo claim 和 continuation policy 决定当前工作归属;
-- task-scoped coordination 不授予 durable authority;
+
- 旧 hierarchy 字段只允许存在于 exactly-once migration reader。
对应实现是 `loopx/control_plane/agents/runtime_model.py`。它只暴露 `AgentRuntimeModel.PEER_V1`。
@@ -184,8 +184,7 @@ Claim 可以过期、清除、被 completion/supersede 结束。Status 会投影
## Lifecycle Authority:显式委托不等于 Leader
Equal peer 的默认规则是:一个 agent 不能修改另一个 peer 已 claim 的 todo。但
-orchestration 或 meta agent 有时确实需要完成、转交或废弃停滞工作。正确做法不是恢复
-永久 leader,而是在 goal 上声明动作级授权:
+orchestration 或 meta agent 有时确实需要完成、转交或废弃停滞工作。正确做法是在 goal 上声明动作级授权:
```yaml
coordination:
@@ -217,18 +216,18 @@ if (rejection === "claim_owner_mismatch") {
}
```
-这是同一 `authority` 决策中的片段,不是新的调用接口。canonical 事务从 registry
+这是同一 `authority` 决策中的片段。canonical 事务从 registry
读取并规范化 grant,将 facts 交给 TS owner 统一决策。Python 只保留 registry facts
与 grant 配置校验,不再暴露独立的 lifecycle mutation authorizer。
这份 grant 有四个边界:
-1. 只授予列出的 lifecycle action,不授予 repo、quota 或 user decision 权限;
+1. 只授予列出的 lifecycle action
2. actor 必须是当前 goal 的 registered agent;
3. `excluded_agents`、`bound_agent` 和精确 user-gate scope 仍独立生效;
4. reason 进入 mutation receipt,使越权操作可追溯。
-因此它表达的是一项可撤销的 goal-local capability,而不是 agent 之间的持久层级。
+因此它表达的是一项可撤销的 goal-local capability。
## Lease:显式、可选的执行占用
@@ -257,8 +256,7 @@ writeback 都必须提交当前 version。Release 会保留 inactive terminal re
实现边界可以直接由调用图证明:产品 CLI 在
`loopx/cli_commands/task_lease.py` 调用 native acquire transport,transaction owner
-是 `loopx/control_plane/work_items/task_lease_acquire.ts`,而不是 todo claim 或 quota
-pipeline。`acquire_task_lease()` 只保留 transport compatibility。生命周期与幂等合同
+是 `loopx/control_plane/work_items/task_lease_acquire.ts`。`acquire_task_lease()` 只保留 transport compatibility。生命周期与幂等合同
由 native TS tests、`tests/control_plane/test_task_lease.py` 和
`examples/control_plane/task-lease-runtime-smoke.py` 看护。
@@ -325,8 +323,7 @@ quota、gate、capability、claim/lease 和 workspace guard;packet 本身不
2. status-neutral run 不得冒充业务进展,只有真实后续 work run 才切换到
`post_handoff_run_seen`。
-连续 N 次 handoff 可以作为低频状态稳定性资格测试,但不是日常执行流程,也不
-能用“漂移分数低”替代任务的 artifact、validation 或 outcome evidence。
+连续 N 次 handoff 可以作为低频状态稳定性资格测试。
### Handoff 携带 Material Frontier,不复制材料正文
@@ -369,7 +366,7 @@ def project_material_frontier_for_handoff(frontier):
投影保留 `current`、`stale`、`missing`、`inaccessible`、`required_unread` 的计数和至多
四个稳定 material id;材料正文、原始 transcript、凭证和本机路径不进入 packet。接手者
先按 id 从 canonical source 重新读取,再判断材料是否 current。这样 handoff 传递的是
-“恢复决策面所需的引用与缺口”,不是一份越来越大的 session memory 副本。
+“恢复决策面所需的引用与缺口”。
## Capability Gate:能做不等于被授权
@@ -390,17 +387,11 @@ loopx --format json quota should-run \
--available-capability filesystem_write
```
-Capability 是 preflight 条件,不是 permission:
-
-- 有 `network` 不代表可以上传私有材料;
-- 有 `filesystem_write` 不代表可以写任意 repo;
-- 有 `session_termination` 不代表 supervisor 可以随意终止 session;
-- 有 `benchmark_runner` 不代表可以提交 leaderboard。
+Capability 是 preflight 条件:
权限仍来自 goal boundary、user gate、workspace policy 和 host authority。
-未知或非 owner-held 的缺失能力会作为 `repair_missing` 暴露给 agent,而不是
-直接跳过。Agent 必须自己判断能否满足:例如独立 worktree/branch 可以由当前
+未知或非 owner-held 的缺失能力会作为 `repair_missing` 暴露给 agent。Agent 必须自己判断能否满足:例如独立 worktree/branch 可以由当前
runtime 自证,就执行 repair 并写回 `capability_gap_status=fixed`;不能证明就写
blocker。分支/worktree 的最终约束仍由 `--task-repository`、
`--required-write-scope` 和 workspace guard 执行,不要在 capability gate 里
@@ -461,8 +452,8 @@ loopx todo update \
只有真正影响所有 peer 的 gate 才使用 `--global-gate`。不要因为不确定就扩大阻塞面。
-在 multi-agent goal 中,`blocks_agent` 和 `global_gate=true` 都缺失时,语义不是
-“默认全局阻塞”,而是“authority scope 不完整”。把不确定性扩大成全局 gate 会让一个
+在 multi-agent goal 中,`blocks_agent` 和 `global_gate=true` 都缺失时,语义是
+“authority scope 不完整”。把不确定性扩大成全局 gate 会让一个
局部决策冻结所有独立 lane,也无法从状态解释用户当时究竟授权了什么。Quota 因此把它
投影为有界修复:
@@ -572,7 +563,7 @@ loopx todo complete \
--no-follow-up
```
-`no_followup` 不是“我不想继续”。它必须与 acceptance evidence、空 frontier、已关闭 monitor/successor/replan gap 一致。`terminal_no_followup` 是 CLI 派生的 closure 状态,不是用户可以随意定义的 todo status。
+`no_followup` 必须与 acceptance evidence、空 frontier、已关闭 monitor/successor/replan gap 一致。`terminal_no_followup` 是 CLI 派生的 closure 状态。
## Supersede:改变方向而不伪造完成
@@ -594,7 +585,7 @@ loopx todo supersede \
## Review 不是特殊身份
-Review 是普通 todo 的 `action_kind=review` 和 continuation policy,不是一个隐藏的 primary reviewer 身份。
+Review 是普通 todo 的 `action_kind=review` 和 continuation policy。
例如作者完成实现后创建:
@@ -635,7 +626,7 @@ M1 monitor external PR
- M1 未到期,不消耗 branch width,也不反复唤醒;
- goal 不应进入 terminal closure。
-这里特别说明一个调度边界:即使另一个 claimed todo 被 gate,未认领的 advancement todo 仍应唤醒所有 eligible peer,而不是因为 goal 中存在 `claimed_by` 就饿死。
+这里特别说明一个调度边界:即使另一个 claimed todo 被 gate,未认领的 advancement todo 仍应唤醒所有 eligible peer。
## 实验:构造一个可计算 Frontier
@@ -696,7 +687,7 @@ loopx --format json quota should-run \
## 核心代码领读:一个 todo 怎样成为某个 peer 的合法工作
-这一讲的主线不是“找到最高优先级 todo”,而是逐层缩小候选集合:
+这一讲的主线是逐层缩小候选集合:
```text
todo contract
@@ -729,8 +720,6 @@ class TodoContinuationPolicy(str, Enum):
SAME_AGENT_NON_DELIVERY = "same_agent_non_delivery"
```
-因此 `open` 不等于“可执行”:一个 open `continuous_monitor` 可能尚未 due,一个 open `user_gate` 等待的是用户,一个 open `advancement_task` 还可能被 capability 或 workspace 卡住。
-
再看 `loopx/control_plane/todos/completion_policy.ts` 中 continuation 的默认值。
私有 `continuationPolicy` 在 `resolveTodoCompletionPolicy` 整项完成策略内使用:
@@ -783,7 +772,7 @@ def select_peer_for_work(registered_agents, *, work_key):
return agents[int.from_bytes(digest[:8], "big") % len(agents)]
```
-这是 deterministic routing helper,不是 durable ownership。真正 ownership 仍要经过 todo claim/lease 写回。
+这是 deterministic routing helper。真正 ownership 仍要经过 todo claim/lease 写回。
### 3. Capability gate 输出候选集,不替 agent 领取 todo
@@ -860,7 +849,7 @@ if current_workspace:
}
```
-这里不是代码风格 gate,而是 attribution gate:后续 refresh 与 quota spend 要能证明交付发生在 todo 声明的 repository、正确的 peer workspace 中。
+这里是 attribution gate:后续 refresh 与 quota spend 要能证明交付发生在 todo 声明的 repository、正确的 peer workspace 中。
### 断点练习
@@ -872,9 +861,8 @@ if current_workspace:
### 读完这一段应能回答
1. 为什么 `task_class` 不能由 `status` 推断?
-2. `select_peer_for_work` 为什么不是 claim?
3. migration reader 与 live runtime model 的边界在哪里?
-4. capability gate 为什么返回 candidate set,而不是唯一 todo?
+4. capability gate 为什么返回 candidate set?
5. worktree guard 与 spend causality 有什么关系?
6. delegated lifecycle authority 为什么没有把 peer 变成永久 leader?
7. material handoff 为什么只传引用、状态计数和截断标记?
@@ -909,7 +897,7 @@ if current_workspace:
1. Claim 和 lease 的差别是什么?
2. Required capability 为什么不是权限?
3. 什么情况下 user gate 应是 global?
-4. 为什么 review 应建模成普通 todo,而不是固定执行者的特权?
+4. 为什么 review 应建模成普通 todo?
5. Completion 缺少 successor 和 no-followup 时,系统为什么不能终止?
下一讲把这个工作图交给决策内核,逐层拆解 `quota should-run` 如何编译出本轮 interaction contract。
diff --git a/docs/development/control-plane-course/06-quota-decision-kernel.md b/docs/development/control-plane-course/06-quota-decision-kernel.md
index 53539ed2cd..2f9d403d1b 100644
--- a/docs/development/control-plane-course/06-quota-decision-kernel.md
+++ b/docs/development/control-plane-course/06-quota-decision-kernel.md
@@ -39,7 +39,7 @@
`build_quota_should_run` 的工作就是把这些 source facts 按稳定 precedence 编译成
interaction contract。后面的字段、mode 和 scheduler hint 都应能回到这张表中的某个
-判断,而不是各自发明一套“是否继续”。
+判断。
## 为什么叫 Quota,却不只是配额
@@ -233,7 +233,7 @@ agent identity matches this quota call?
- user-owned actions;
- execution profile。
-这一步先于 todo 选择,因为 todo runnable 不代表越过 goal boundary 后仍合法。
+这一步先于 todo 选择。
### 3. Normalize user gates
@@ -260,8 +260,6 @@ Repair 必须改变 machine-visible frontier,例如:
- active state next action;
- agent vision patch。
-只写“已重新思考”不是 repair delta。
-
### 5. Apply capability gate
从 open advancement todos 中筛出本轮能力可满足的候选。
@@ -295,7 +293,7 @@ Repair 必须改变 machine-visible frontier,例如:
### 9. Compose scheduler hint
-调度不是另一个独立 AI 判断。它从已解析的 interaction contract 和 lifecycle state 派生 cadence class、RRULE 建议、ACK 和 spend policy。
+它从已解析的 interaction contract 和 lifecycle state 派生 cadence class、RRULE 建议、ACK 和 spend policy。
## 决策优先级为什么重要
@@ -336,7 +334,7 @@ D1 user gate open
P1 independent and runnable
```
-结果:user channel 通知 D1;agent channel 执行 P1;不是全局 wait。
+结果:user channel 通知 D1;agent channel 执行 P1;
### Case C:只有未到期 monitor
@@ -377,7 +375,7 @@ evidence creates scoped gate G1 and blocked successor T1
periodic autonomous replan obligation = due
```
-这不是“monitor 已完成,所以 quiet”的状态。合理推导是:
+合理推导是:
1. monitor 的一次 poll 结束,并以 compact evidence 写回;
2. G1 进入 user channel,T1 在对应 decision scope 上保持不可交付;
@@ -385,7 +383,7 @@ periodic autonomous replan obligation = due
4. 只有不依赖 G1、且 interaction contract 明确允许的 repair 或独立工作才可进入 agent channel;
5. host 依据新 contract 重算 cadence,不能沿用 M1 的旧 monitor backoff。
-这里的复杂性不是三个 feature 相加,而是一次 evidence transition 同时改变 gate、frontier 和 scheduler identity。
+这里的复杂性是一次 evidence transition 同时改变 gate、frontier 和 scheduler identity。
### Case G:`user_action` 看起来相关,但不能满足 decision scope
@@ -421,8 +419,7 @@ short_pool active usage = 1
T1/T2 resume_when = capacity_available:short_pool
```
-结果:Harness packet 可以帮助解释当前 portfolio,但 quota frontier 仍为空;本轮应 wait,
-而不是 claim、launch 或 spend。已有 external task 的 monitor 也不因为 planner 产生新排名
+结果:Harness packet 可以帮助解释当前 portfolio,但 quota frontier 仍为空;本轮应 wait。已有 external task 的 monitor 也不因为 planner 产生新排名
就提前 poll。资源 readback 释放槽位后,Kernel 重新计算 `resume_when`,只暴露合法候选。
如果 Harness 从 Graph 读到一条新 `refutes` edge,也只能形成 retirement/replan proposal。
@@ -446,11 +443,11 @@ else:
具体 user todo 未投影,需修复 LoopX 状态投影
```
-这是状态契约错误,不是文案问题。
+这是状态契约错误。
## Spend 规则
-Quota slot 表示一次有效推进,不是一次调用。
+Quota slot 表示一次有效推进。
### 应 spend
@@ -606,7 +603,7 @@ should_run = bool(
effective_action = _effective_action(...)
```
-workspace guard 在这里覆盖 capability/self-repair,是因为任何会写 repository 的修复也不能发生在错误 workspace。课堂上可把这些 flag 画成 priority lattice,而不是互斥 enum。
+workspace guard 在这里覆盖 capability/self-repair,是因为任何会写 repository 的修复也不能发生在错误 workspace。课堂上可把这些 flag 画成 priority lattice。
### 4. `terminal_no_followup` 必须由完整 closure 推导
@@ -664,7 +661,7 @@ return (
### 5. Interaction contract 把 decision 分给三个 actor
-quota 末尾不是直接打印一句话,而是调用 `build_interaction_contract`,形成:
+quota 末尾是调用 `build_interaction_contract`,形成:
```text
user_channel -> 是否真的需要用户动作、具体问题是什么
@@ -691,7 +688,6 @@ cli_channel -> 下一条 CLI 写回、何时允许 spend
2. 为什么 projection repair 要覆盖正常 delivery?
3. workspace repair 为什么比 capability repair 更晚覆盖?
4. terminal closure 同时检查哪些 todo、monitor、successor、replan 与 acceptance 状态?
-5. `action_required=false` 为什么不代表 agent 可以 quiet no-op?
## 代码阅读方法
diff --git a/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md b/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md
index ae8c0f90b7..2ce41370a9 100644
--- a/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md
+++ b/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md
@@ -208,21 +208,19 @@ host update applied
CLI acknowledged exact applied state
```
-Scheduler ACK 本身不构成 delivery,不 spend。
-
### 兼容投影不能改变状态权威 / Compatibility preserves state authority
-`app_automation` 与 `codex_app` 是同一 proposal 的宿主投影,不是两个 scheduler
-writer。读取优先采用 common state;仅有旧 Codex state 时,保留它经 TS 验证的
-`state_key`。两份投影的 backoff、host facts 与 ACK/failure 命令都必须携带同一个键。
-否则 common state 的当前 identity/index 会被误写到旧键,触发真实的初始档位冲突;
-即使 CAS digest 相等也不代表 proposal 的状态归属正确。
+新决策统一使用 `app_automation` 携带调度建议和宿主行动。旧捕获仍可读取其中的
+`codex_app`。读取优先采用 common state。仅有旧 Codex state 时,保留 TS 验证过的
+`state_key`,并将同一个键贯穿 backoff、host facts 与 ACK/failure 命令。
+写回前须校验状态归属及 CAS 摘要,否则可能把已推进的档位写入错误的状态键。
-`app_automation` and `codex_app` project one proposal, not two scheduler writers.
-Reads prefer common state; a legacy-only Codex installation retains its
-TS-validated legacy key. Both projections must carry that same key through
-backoff, host facts and ACK/failure commands. Equal CAS digests do not prove that
-a proposal belongs to the chosen state scope.
+New decisions use `app_automation` for the cadence proposal and Host actions.
+Saved captures can still carry `codex_app`. Reads prefer common state. A
+legacy-only Codex installation retains the TS-validated state key through
+backoff, Host facts, and ACK/failure commands. Before writing, validate the
+state scope and CAS digest to keep the recorded progression in its original
+state.
兼容 Python API 与手工 Codex CLI 未显式传 `state_key` 时,从当前 packet 取得实际键;
显式键仍须匹配,不得静默改写。Trae 仍只接受 common key。这不是隐式迁移:不能把
@@ -244,7 +242,7 @@ O: host 更新 automation,并 readback observed RRULE
R: LoopX 持久化 ACK,证明 O 对应 P
```
-`O.target_matches=true` 只说明宿主当前值正确,不等于 `R.persisted=true`。如果 adapter
+`O.target_matches=true` 只说明宿主当前值正确。如果 adapter
先更新 RRULE,再重新计算一份已经显示 settled 的 hint,原 proposal 的 ACK obligation
可能被跳过。完整资格测试必须保留 P 的 `state_key`、`reset_token`、
`identity_signature` 和 target RRULE,按以下顺序验证:
@@ -359,15 +357,15 @@ Host 只有在 CLI 派生 `terminal_no_followup` 时才应自动停止。它至
open todo count == 0
```
-只是必要条件之一,不是充分条件。
+只是必要条件之一。
-`terminal_no_followup` 是 LoopX 自己派生的 runtime closure,不是用户自定义 status,也不应由 host 根据自然语言猜测。
+`terminal_no_followup` 是 LoopX 自己派生的 runtime closure。
## 原生 Codex Goal 与 LoopX Host Surface
### 原生 Goal 的持久边界
-Codex 原生 Goal 不是“在 prompt 前写 `/goal`”的文本约定。自动化 surface 通过
+自动化 surface 通过
`thread/goal/set` 把 objective、status 与可选 token budget 绑定到 thread,通过
`thread/goal/get` 读回,再用 `turn/start` 继续执行。只有普通 prompt 的 slash 前缀、
外部 polling loop 或 `codex exec` 成功,都不能单独证明 native Goal 已激活。
@@ -554,7 +552,7 @@ write 和兼容旧合同的 JSON/Markdown projection。持续运行的路径没
caller 与 unbound manual command 保留兼容入口。
端到端测试仍需把 apply 前生成的 hint 原样带过 host effect。若 effect 后重新读取一份
-hint,测试仍可能漏掉 ACK obligation 丢失。ACK 不构成 delivery,也不会 spend。缺少
+hint,测试仍可能漏掉 ACK obligation 丢失。缺少
durable ACK 时,下一轮不能把 proposal 或碰巧相同的 host 值当成已结算状态。
### 4. Monitor writeback 用 result hash 区分观察与推进
@@ -623,9 +621,9 @@ return record_quota_monitor_poll_for_decision(
)
```
-Execution context 不是渲染选项,而是 decision input。若 CLI 入口识别出 Codex App,
+Execution context 是 decision input。若 CLI 入口识别出 Codex App,
但 wrapper 只把 context 传给 `before`,`after` 会误以为自己处在未知 host,返回
-`repair_scheduler_execution_context`。这不是 monitor 产生了新阻塞,而是调用链丢失
+`repair_scheduler_execution_context`。这是调用链丢失
了 authority context。
对应回归应同时证明:
@@ -660,7 +658,6 @@ App tick
### 读完这一段应能回答
-1. 为什么 scheduler hint 不能证明 RRULE 已应用?
2. 为什么 ACK 不消耗 delivery slot?
3. 哪些字段变化应 reset stateful backoff?
4. unchanged monitor 为什么必须写 `next_due_at`?
@@ -705,7 +702,7 @@ App tick
### 把 launcher 称为 supervisor agent
-Auto Research 的 tmux launcher 只是 host launcher,不是拥有 todo 决策权的 leader agent。可选 peer supervisor 是另一套 proposal-only overlay。
+Auto Research 的 tmux launcher 只是 host launcher。可选 peer supervisor 是另一套 proposal-only overlay。
## 课后检查
diff --git a/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md b/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md
index 862f8eb449..73ebfca227 100644
--- a/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md
+++ b/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md
@@ -15,7 +15,7 @@
1. 区分 artifact、validation、writeback、refresh、spend 五个步骤。
2. 使用 authoritative evidence 判断 acceptance,而不是依赖 todo status。
3. 解释 projection gap、outcome floor、vision checkpoint 和 repair delta。
-4. 在连续 no-progress 时执行 self-repair,而不是降低 gate。
+4. 在连续 no-progress 时执行 self-repair。
5. 为 public/private evidence 设计安全边界和 compact lineage。
## 本讲技术契约
@@ -194,7 +194,7 @@ loopx refresh-state \
--vision-unchanged-reason "课程目标和验收标准未改变,本轮完成讲义内容交付"
```
-Refresh 不是“刷新页面”,而是一次有语义的状态 transaction:
+Refresh 是一次有语义的状态 transaction:
- 写 run classification;
- 标记 delivery scale/outcome;
@@ -229,8 +229,7 @@ Outcome floor 防止 agent 用大量微小动作伪装长期推进。连续 surf
## Agent Vision 与 Acceptance Gap
多 agent goal 中,每个 peer 有自己的 bounded vision。对同时承担 advancement 与
-continuous monitor 的长生命周期 lane,vision 不是可有可无的说明文字,而是恢复和
-replan 的基线。Agent profile 会默认把这类 lane 标成 required:
+continuous monitor 的长生命周期 lane。Agent profile 会默认把这类 lane 标成 required:
```python
def _vision_requirement(value, *, task_classes):
@@ -260,7 +259,7 @@ last patch
todo delta
```
-它不是另一份大计划,而是回答:
+它是回答:
- 这个 peer 在长期目标中负责什么?
- 什么证据说明它的 lane 可以关闭?
@@ -285,7 +284,6 @@ Vision
这条链解释了为什么 Vision 应相对稳定,却不能永久冻结:用户方向变化、验收标准
被证伪、长期 frontier 耗尽或持续局部最优时,需要一个有明确 delta 的 patch。
-反过来,新增一个 todo 不等于 Vision 已变化。
`loopx/control_plane/goals/goal_vision.py::normalize_goal_vision_packet`
把这种边界编码成 compact、public-safe、agent-scoped packet:
@@ -341,11 +339,9 @@ signal
-> explicit priority, gate, or vision writeback
```
-这是管理面整理 signal 的分析顺序,不是 LoopX 中另一套独立状态机。持久化和执行
+这是管理面整理 signal 的分析顺序。持久化和执行
权限仍由现有 Core State 合同负责:
-- 外部消息到达不等于用户已授权执行;
-- 被认为“有价值”的 signal 不等于已进入 runnable frontier;
- raw feedback 不直接覆盖 Vision,必须形成明确 source、scope 和 delta;
- performance review 可以影响下一轮优先级,但仍要通过 todo/gate/vision API 写回。
@@ -455,7 +451,7 @@ classification 或 caller 自报 repair kind 都不能关闭新 obligation。
## 两轮无推进后的 Self-Repair
-规则不是“第二轮就随便换方向”,而是系统性审计:
+规则是系统性审计:
```text
1. 重新读 exact quota interaction_contract
@@ -511,7 +507,7 @@ closeout_allowed_without_evidence = false
"9 讲课程目标、受众与验收未改变;本轮完成全部讲义并以当前 CLI/smoke 交叉验证"
```
-这条回放说明 vision checkpoint 是长期 acceptance 的闭环,不是形式化打勾。
+这条回放说明 vision checkpoint 是长期 acceptance 的闭环。
## 多 Monitor 交错时的停滞证据
@@ -533,8 +529,7 @@ material change on M2 -> reset M2 only
Quota 从 `monitor_open_items` 读取每条 lane 的 durable counter。任一 lane 达到阈值且
没有 same-agent runnable advancement 时,`monitor_no_change_streak` 形成 replan 证据;
-replan 应选择 watch expiry、明确 blocker、supersede monitor 或创建 runnable successor,
-而不是再做一次 quiet poll。若存在 same-agent runnable advancement,advancement 优先,
+replan 应选择 watch expiry、明确 blocker、supersede monitor 或创建 runnable successor。若存在 same-agent runnable advancement,advancement 优先,
但 blocked advancement 不能冒充可执行工作来压掉 replan。
这个例子同时说明了三件事:evidence 必须归属稳定 identity;聚合 read model 不能覆盖
@@ -656,8 +651,7 @@ loopx todo add \
`run_loopx_turn_once` 会把 plan、host result、task validation、writeback、spend 和 scheduler
状态写入 `runtime_root/goals//turns/.json`。这份 journal 的 owner 是
-**单个 Turn 的阶段进度**,不是 goal truth:只有 `writeback` callback 成功,长期状态才发生
-变化;只有 source state readback 才能证明 todo、vision 或 evidence 已提交。
+**单个 Turn 的阶段进度**只有 source state readback 才能证明 todo、vision 或 evidence 已提交。
这一区分让恢复可以按失败阶段精确继续:
@@ -715,7 +709,7 @@ if not delta["accepted"]:
print(delta["reason"])
```
-仅刷新 evidence ID 不构成新语义维度;旧 blocker 不因更换 work item 而成为新结果。
+旧 blocker 不因更换 work item 而成为新结果。
若 context 已截断 coverage,必须提供完整历史,缺失时资格入口拒绝写回。
成功 receipt 必须携带当前 `obligation_id`,且 outcome 属于该 obligation 的
@@ -781,7 +775,7 @@ if normalized_progress_scope == "agent_lane":
### 4. Projection gap 把 prose 漂移升级成 repair
-`loopx/control_plane/quota/projection_repair.py::build_state_projection_gap_repair_hint` 的输入来自第 4 讲的 status projection。当 active prose 看起来可执行、结构化 agent todo 却为零时,它返回 self-repair hint,而不是让 quota 安静等待。
+`loopx/control_plane/quota/projection_repair.py::build_state_projection_gap_repair_hint` 的输入来自第 4 讲的 status projection。当 active prose 看起来可执行、结构化 agent todo 却为零时,它返回 self-repair hint。
领读时追这条反向路径:
@@ -875,7 +869,6 @@ CLI/status/quota 并补 smoke;只更新文档不会改变机器的下一次决
## 课后检查
-1. Todo done 为什么不是 acceptance evidence?
2. Refresh 和 spend 分别证明什么?
3. Vision unchanged reason 什么时候是诚实的?
4. Repair delta 必须改变哪些 machine-visible 对象?
diff --git a/docs/development/control-plane-course/09-engineering-a-control-plane-rule.md b/docs/development/control-plane-course/09-engineering-a-control-plane-rule.md
index 036a3d299d..cd5a9f8b65 100644
--- a/docs/development/control-plane-course/09-engineering-a-control-plane-rule.md
+++ b/docs/development/control-plane-course/09-engineering-a-control-plane-rule.md
@@ -67,7 +67,7 @@ control_plane/todos
control_plane/work_items
```
-归属原则不是“哪个文件短”,而是 change reason:
+归属原则是 change reason:
- agent identity/supervisor observation 属于 `agents`;
- todo lifecycle 属于 `todos`;
@@ -75,7 +75,7 @@ control_plane/work_items
- cadence/ACK 属于 `scheduler`;
- repo/write-scope 选择属于 workspace/work item boundary。
-大文件是 warning signal,不是自动拆分理由。先找一组已经有 parity fixture 的 cohesive rules,再移动到 bounded context。
+大文件是 warning signal。先找一组已经有 parity fixture 的 cohesive rules,再移动到 bounded context。
## 新规则的 8 个层次
@@ -167,7 +167,7 @@ terminal_no_followup =>
普通 Python smoke 可以检查有限案例;property-based test 可以搜索更多组合;TLA+/Alloy 可以检查状态机;Lean 可以把状态、transition 和 theorem 写进依赖类型系统,并由 kernel 检查 proof term。
-Lean 的价值不是“让 agent 写更多形式化文本”,而是对少量高价值 invariants 给出机器证明,例如:
+Lean 的价值是对少量高价值 invariants 给出机器证明,例如:
- 执行过的 supervisor action 必然有 capability-matched receipt;
- terminal state 不可能同时有 runnable successor;
@@ -253,7 +253,7 @@ def select_goal_frontier_replan_rule(facts):
4. quality surface catalog 将它标为 high risk,要求 unit、smoke、canary 和 release gate;
模型行为层记为 `not_applicable`,因为确定性 precedence 不应交给模型裁判。
-这个案例的评审重点不是“新模块是否更漂亮”,而是:facts 是否来自同一 canonical
+这个案例的评审重点是:facts 是否来自同一 canonical
projection、rule order 是否完整、每条负向规则是否有反例、runtime payload builder 是否
仍复用原实现。只有这四点成立,代码移动才是行为保持的重构。
@@ -377,7 +377,6 @@ Supervisor contract 推荐把 supervisor task 作为 synthesis channel,因为
- 所有改变 authority 的决定仍写成 LoopX user todo/gate;
- supervisor 不能 claim 其他 peer 的 todo;
- supervisor 不能花其他 peer 的 quota;
-- supervisor 不是隐藏 review owner。
### Inject 为什么先有 canary
@@ -409,7 +408,7 @@ Fork 与 handoff 不同:
| handoff | 通常完成或 yield | 转移 continuation,不默认增加 branch 数 |
| fork | 继续 | 新增临时 execution branch,需要 capacity reservation |
-正确未来模型不是复制长期 peer identity,而是:
+正确未来模型是:
```text
source_agent_id
@@ -475,7 +474,7 @@ Smoke 应同时证明:
本讲只保留规则开发的入口;完整分层、频率、模型行为门和发布门见[第 10 讲](10-autonomous-agent-quality-gates.md)。
-测试先回答“这个状态和规则合理吗”,再验证实现是否符合。共享 quota/status/todo 行为可以先加 parity fixture 描述现状,但 fixture 不是授权书;如果现状与 independently reviewed invariant 冲突,应修规则并增加负向或 mutation coverage,不能刷新 golden 把错误合法化。
+测试先回答“这个状态和规则合理吗”,再验证实现是否符合。共享 quota/status/todo 行为可以先加 parity fixture 描述现状;如果现状与 independently reviewed invariant 冲突,应修规则并增加负向或 mutation coverage,不能刷新 golden 把错误合法化。
例如 gate lifecycle 至少要先写出这张语义表,再决定 schema 和 transition:
@@ -552,7 +551,7 @@ HOST_CAPABILITIES_BY_DECISION = {
}
```
-`normalize_peer_supervisor` 的关键不是 enum,而是身份约束:
+`normalize_peer_supervisor` 的关键是身份约束:
```python
if raw in (None, {}) or raw.get("enabled") is False:
@@ -572,11 +571,11 @@ return {
}
```
-`supervisor` 是某个已注册 peer 的额外职责,不是新的 primary/side hierarchy。默认空配置直接返回 `None`,所以实验功能不会默认开启。
+`supervisor` 是某个已注册 peer 的额外职责。默认空配置直接返回 `None`,所以实验功能不会默认开启。
### 2. Contract 明确 user channel 与 authority 边界
-`build_peer_supervisor_contract` 里最重要的字段不是 prompt 文案,而是权力模型:
+`build_peer_supervisor_contract` 里最重要的字段是权力模型:
```python
{
diff --git a/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md b/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md
index 6a900007fe..c636d5f34e 100644
--- a/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md
+++ b/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md
@@ -12,7 +12,7 @@
完成本讲后,开发者应该能够:
-1. 先判断状态和规则是否合理,再判断实现是否符合,而不是把当前输出录成 golden。
+1. 先判断状态和规则是否合理,再判断实现是否符合。
2. 按改动风险选择 unit、focused smoke、decision replay、canary、模型行为验证和 release gate。
3. 区分 blocking failure、advisory signal、deferred gap、`not_applicable` 和 manual hold。
4. 解释为什么常规模型行为测试是 actual-default one-arm,而双臂只服务于明确的差分或提升声明。
@@ -26,7 +26,7 @@ agent-facing packet 读案例四;文档与社区资源读案例五;release/b
## 本讲沿三个 Showcase 验证什么
-质量门禁不是脱离产品路径的测试清单。三个 Showcase 各自暴露了不同风险:
+三个 Showcase 各自暴露了不同风险:
| Showcase surface | 独立 oracle | 最小确定性证明 | 更高层证明 |
| --- | --- | --- | --- |
@@ -78,7 +78,7 @@ Explore Graph 只能消费第二组 oracle 已接受的 finding;Explore Harnes
## 第一道门:独立语义 Oracle
-写测试前先用产品规则表达期望,而不是从实现输出复制期望:
+写测试前先用产品规则表达期望:
```text
source facts
@@ -90,8 +90,7 @@ source facts
例如 `required_decision_scopes=["publish"]` 的 agent todo 遇到一个
`blocking=false` 的 `user_action`:即使提醒文本里提到 publish,它也不能授予 publish
-权限。这里的 oracle 来自 authority invariant,而不是当前 reducer 是否恰好返回
-`should_run=true`。
+权限。这里的 oracle 来自 authority invariant。
Oracle 至少要写清:
@@ -157,7 +156,7 @@ if meaningful:
- 模型通过不能覆盖 deterministic contract failure;
- full-public 全通过不能替代一个明确命名旧故障的 focused regression;
-- output 字符数没增长不能证明 agent 仍知道下一步做什么;
+
- release receipt 齐全不能替 owner 自动做发布决定。
## Quality Surface Catalog:先审计覆盖设计
@@ -179,9 +178,9 @@ loopx canary quality-audit
- `not_applicable`:这层测试不适合该语义,例如用模型判断确定性的 scheduler 优先级;
- `deferred`:这层有价值但尚未建设,必须保留 owner 和可见缺口;
-- `covered`:有真实路径和稳定 oracle,不是只写了一句“已有测试”。
+- `covered`:有真实路径和稳定 oracle。
-Catalog 不是测试结果汇总,而是“为什么这些层足够”的机器可审计设计。
+Catalog 是“为什么这些层足够”的机器可审计设计。
## PR 快速门:让普通迭代保持便宜
@@ -208,8 +207,7 @@ loopx canary premerge --from-git-diff
loopx canary smoke-suite --suite full-public --jobs 4 --timeout-seconds 120
```
-它适合主干、每日或手动运行,不应成为每个文档 patch 的同步阻塞项。保护质量不等于
-把最宽的测试频率提高到每次保存文件。
+它适合主干、每日或手动运行,不应成为每个文档 patch 的同步阻塞项。
## 真实模型门:常规 one-arm,必要时才 pair
@@ -254,16 +252,17 @@ runner。
## Agent-facing 热路径与诊断冷路径
默认 guided projection 是 agent 每轮都会消费的热路径;完整诊断包是显式请求的冷路径。
-把字段从热路径移到冷路径不是简单删 JSON,至少要同时证明:
+
+把字段从热路径移到冷路径,至少要同时证明:
1. 热路径仍保留当前 authority、selected todo、可执行 commands 和 host activation;
2. 被省略细节有显式 drill-down 命令;
3. action signature 与状态语义没有漂移;
-4. CLI budget 显示输出确实收敛,而不是把重复文本搬到另一处;
+4. CLI budget 显示输出确实收敛
5. actual-default model portfolio 中的真实 agent 行为仍正确。
冷路径不会天然降低接入效果。真正的风险是把 agent 作决定所需的信息也当成“诊断噪声”
-一起移走。因此 owner review 应逐项解释字段为什么可移除,而不是只展示字符数下降。
+一起移走。因此 owner review 应逐项解释字段为什么可移除。
## 门禁结果也是状态机
@@ -329,9 +328,8 @@ if replan_decision_allowed:
阅读断点:
-1. `monitor_quiet_skip` 只是候选结果,不是函数提前返回;
-2. `replan_decision_allowed` 显式改写 `should_run` 与 `effective_action`,所以 replan
- precedence 不是靠 prompt 文案实现;
+1. `monitor_quiet_skip` 只是候选结果
+2. `replan_decision_allowed` 显式改写 `should_run` 与 `effective_action`
3. 继续读同函数末尾的 `build_interaction_contract(payload)` 和 `_scheduler_hint(...)`:
二者都消费已经仲裁完成的 payload,host 不应重新从低层 flags 猜一次决策。
@@ -347,7 +345,7 @@ if replan_decision_allowed:
4. metamorphic case 把 advancement 改成 same-agent runnable,最终必须回到
`normal_run`,证明 replan 没有抢占真实可执行工作。
-这里测试的不是一份当前 JSON,而是两条独立 invariant:monitor 停滞按 target identity
+这里测试的是两条独立 invariant:monitor 停滞按 target identity
累计;runnable advancement 在工作选择上优先于 monitor-derived replan。
仓库用 [issue #2272](https://github.com/huangruiteng/loopx/issues/2272) 记录过对应回归:
M1、M2 交错 poll 时,错误的全局计数会让某条 lane 永远达不到 replan 阈值。下文的
@@ -426,8 +424,7 @@ if (conflicting.length) {
if (compatible.length) continue;
```
-只有 task class、scope、owner 和精确目标一致的 gate 才满足依赖;依赖一致不等于
-批准或 lease。随后 `matchingActions` 只用于错误归因
+只有 task class、scope、owner 和精确目标一致的 gate 才满足依赖;随后 `matchingActions` 只用于错误归因
`non_blocking_user_action_scope_collision`,不能成为 authority。只有不兼容 gate 时
归因 `required_decision_scope_gate_owner_mismatch`;没有匹配来源时归因
`dangling_required_decision_scope`。standing authority 的冲突与拒绝/取消后的阻塞要求
@@ -535,12 +532,11 @@ if any(_path_matches(path, BENCHMARK_SENSITIVE_TOKENS) for path in files):
再进入 `build_premerge_validation_gate`,观察 classification 如何分别生成 direct checks、
catalog run、risk-profile run 和 boundary scan。Docs-only 命中自己的 profile;只有实际
-路径命中 benchmark-sensitive token 才产生 manual hold。门禁由 diff surface 决定,
-不是由 PR 作者在描述里自报“低风险”。
+路径命中 benchmark-sensitive token 才产生 manual hold。门禁由 diff surface 决定。
## 组合案例六:Release 精确 Commit
-发布前的关键不是“这些测试最近跑过”,而是“这些回执是否属于即将打 tag 的同一个
+发布前的关键是“这些回执是否属于即将打 tag 的同一个
clean source identity”。Exact-commit gate 聚合既有通道,不另造一套 runner:
```bash
@@ -634,7 +630,7 @@ def test_goal_frontier_replan_decision_table(...):
第二层是 metamorphic test:不改变当前 agent 的 source facts,只扩大其他 peer 的 backlog,
结果必须不变;再加入当前 agent 自己的 runnable advancement,结果必须翻转。它检查的是
-agent-scope invariant,不是某份固定 JSON。
+agent-scope invariant。
第三层让 focused smoke 经由 `build_quota_should_run` 验证最终路由,防止纯 selector 正确、
integration 却漏传 facts。第四层把 surface 登记进 quality catalog 和 risk-based canary。
@@ -754,5 +750,4 @@ outcome baseline 可以消费 readiness receipt,但不能反过来用一个分
7. 哪些改动允许 agent 自合并,哪些必须留下 manual hold?
下一讲进入扩展层:Explore Graph/Harness、Single-Agent Auto ML、multi-agent kernel、
-Auto Research、supervisor 和 connectors 如何复用同一套状态内核与质量门禁,而不是创建
-第二套控制面。
+Auto Research、supervisor 和 connectors 如何复用同一套状态内核与质量门禁。
diff --git a/docs/development/control-plane-course/11-extension-layer.md b/docs/development/control-plane-course/11-extension-layer.md
index 5e7333f909..207ffb9c64 100644
--- a/docs/development/control-plane-course/11-extension-layer.md
+++ b/docs/development/control-plane-course/11-extension-layer.md
@@ -72,7 +72,7 @@ registry -> status -> quota -> interaction contract -> todo/evidence -> refresh/
## 运行责任与扩展交付
-Extension 是安装、启停、升级和分发边界,不是运行时的第五个 owner。运行时仍按四种责任
+Extension 是安装、启停、升级和分发边界。运行时仍按四种责任
分工:
| 角色 | Owns | Must not own |
@@ -137,7 +137,7 @@ State 只保存可重放的 compact facts;外部 sink 只消费 public-safe pr
## Governed External Execution:把外部副作用变成可恢复事务
-外部 capability 最危险的时刻,不是 API 明确返回失败,而是调用方不知道它到底有没有成功:
+外部 capability 最危险的时刻:
```text
provider 已经创建任务
@@ -148,8 +148,7 @@ provider 已经创建任务
```
`capability invoke` 可以直接执行 read-only operation,因为它不会产生需要结算的物质效果。
-`external_write` 则必须进入 governed external execution。它不是给 provider 套一层普通 retry,
-而是把一次外部写入拆成两段可重放事务:
+`external_write` 则必须进入 governed external execution。
```text
Goal-bound capability + exact provider revision
@@ -176,7 +175,7 @@ Goal-bound capability + exact provider revision
### Goal capability 与 material Turn 分别回答什么
-Goal enablement 与 Turn admission 不是二选一,而是两层不同粒度的授权:
+Goal enablement 与 Turn admission 是两层不同粒度的授权:
| 层 | 回答的问题 | 不代表什么 |
| --- | --- | --- |
@@ -272,18 +271,18 @@ Independent evidence refresh
-> only then promote “resumable multimodal context works” from hypothesis to evidence
```
-这里“同一 Session”不意味着复用同一 Turn。Session 拥有远端对话连续性;每个 material attempt
+Session 拥有远端对话连续性;每个 material attempt
仍有自己的 Turn/effect identity、receipt 和 quota settlement。Read-only observe 则负责验证后置
条件,不为了凑治理形式额外扣一次 quota。
-这条链路的威力在于,最终结论不是“Agent 说它测过”,而是四种独立证据可以互相校验:
+这条链路的威力在于:
- governed journal 证明哪一个 exact request 被允许并执行;
- Session readback 证明用户可见事件确实出现;
- trace/runtime evidence 证明请求经过哪个实际运行版本;
- typed domain receipt 证明被测能力对应哪个结构化配置或 metadata 决策。
-任何一层冲突都应保持 `Unknown` 或让 Todo 继续 open,而不是用一个成功 marker 覆盖其余证据。
+任何一层冲突都应保持 `Unknown` 或让 Todo 继续 open。
### API 组合而不是万能 Executor
@@ -326,7 +325,7 @@ bounded request、binding、authority、receipt 和 settlement。领域逻辑因
| Receipt/readback/trace 冲突 | 选一个看起来成功的证据 | 保持 Todo open,刷新证据或 self-repair adapter |
| 相同 Turn 携带不同 request digest | 把它当普通 retry | fail closed,创建新的合法 Todo/Turn identity |
-因此,governed execution 的核心不是“所有调用都经过 LoopX”这一句口号,而是让每个 material
+因此,governed execution 的核心是让每个 material
external effect 都能回答:它属于哪个 Goal/Todo/Turn、provider 是否真的提交、LoopX 是否已写回、
quota 是否只结算一次,以及崩溃后下一步究竟是 retry provider 还是只 reconcile ledger。
@@ -355,7 +354,6 @@ loopx --format json configure-goal --goal-id
2. 阅读 exact delta 和 boundary;
3. 再显式 `--execute`;
4. 关闭 feature 时保留历史 evidence,只关闭未来行为;
-5. feature gate 不等于 runtime permission。
## Explore Graph:探索证据层
@@ -564,7 +562,7 @@ Router state 由 runner 在 epoch boundary 持久化。Harness 仍然只生成
## Single-Agent Auto ML:Graph、Harness 与 Domain Pack 怎样合起来
-Single-Agent Auto ML 不是缩小版 Auto Research。它只有一个长期 agent lane,却要同时处理:
+它只有一个长期 agent lane,却要同时处理:
- 候选实现与代码 revision;
- 训练/评估 provider 的异步 task;
@@ -664,7 +662,7 @@ repair/retry,不应 `refutes` 模型假设。Harness 下一轮消费这些边
### Promotion、Reward Memory 与系统能力演进
-Graph finding 和 Harness ranking 都不是 promotion authority。Promotion 至少需要:
+Promotion 至少需要:
```text
exact candidate/revision/window
@@ -753,8 +751,7 @@ loopx configure-goal \
## Reward Memory
Reward memory 是 per-agent、default-off 的实验能力,目标是让经过验证的人类评价和工程经验
-在后续 run 中被作用域化复用。它不是 LoopX canonical state 的替代品,也不是把聊天记录长期
-注入模型。
+在后续 run 中被作用域化复用。
| Memory class | 与 LoopX 当前状态的关系 | 允许产生的影响 |
| --- | --- | --- |
@@ -787,7 +784,7 @@ connector: 外部事件、权限、source authority
projection sink: 把 public-safe LoopX read model 显示到 Lark
```
-开启 inbox 不等于允许发送消息或自动写 goal。外部消息必须先经过身份、reply/mention relation、source authority 和 gate 检查,再转换为 bounded LoopX event/todo。
+外部消息必须先经过身份、reply/mention relation、source authority 和 gate 检查,再转换为 bounded LoopX event/todo。
Sink 应保留 lineage:
@@ -840,7 +837,7 @@ loopx --format json explore worker-branch-plan \
## 核心代码领读:Explore 与 Auto ML 怎样复用 kernel
-扩展层最重要的判断不是“功能多不多”,而是它有没有重新发明 todo、quota、lease、scheduler 或 evidence。下面沿真实配置与执行边界读。
+扩展层最重要的判断是它有没有重新发明 todo、quota、lease、scheduler 或 evidence。下面沿真实配置与执行边界读。
### 1. Feature config 默认关闭,preview 与 execute 分离
@@ -1084,7 +1081,7 @@ leader authority。
9. Material provider 是否以稳定 idempotency key replay,并把 start 与 reconcile 分开?
10. Receipt digest 是否在 quota spend 前 durable writeback?
11. Evidence 是否 compact、可追溯、符合 public/private boundary?
-12. Focused smoke 是否证明 shipped behavior,而不是临时字段?
+12. Focused smoke 是否证明 shipped behavior?
## 课程结束后的能力标准
diff --git a/docs/development/control-plane-course/README.md b/docs/development/control-plane-course/README.md
index b9515b1c68..c89179974f 100644
--- a/docs/development/control-plane-course/README.md
+++ b/docs/development/control-plane-course/README.md
@@ -15,7 +15,7 @@ Pack 增加领域泳道。看板只是 projection;canonical state 和 typed tr
贯穿全课的另一种判定是 effect interpreter:模型提出 effect request,harness 解释后返回
observation,再把 next effect 交回 host。每个状态机都是解释器内部的一张 interpretation
-table,而不是独立产品。
+table。
## 课程先建立一个递进
@@ -30,7 +30,7 @@ table,而不是独立产品。
-> CLI packet:把当前状态投影成这一次 bounded Turn 的过程协议
```
-这不是要把全部历史塞回模型,而是让有限上下文每次只接收当前 objective、必要 evidence ref、
+这是让有限上下文每次只接收当前 objective、必要 evidence ref、
合法 frontier 和 writeback contract。完整推导见[概念导读](00-concept-primer.md)。
## 三个 Showcase 是课程主线
@@ -62,7 +62,6 @@ Single-Agent Auto ML 还提供一条贯穿第 0、1、2、3、4、5、6、8、9
Explore Graph 把假设、实验、支持、反驳和负向结果保存成可追溯证据拓扑;Explore Harness
读取显式 Graph refs、当前 todo 和资源容量,给出 analysis-only 的候选组合;单个 Agent 仍必须经
普通 claim、quota、provider effect、monitor、validator 和 promotion gate 才能推进实验。
-Graph 不是执行 DAG,Harness 也不是隐藏 scheduler。
## 先边界,再逻辑,再代码
@@ -78,8 +77,8 @@ Graph 不是执行 DAG,Harness 也不是隐藏 scheduler。
| Write / replay | transition 在哪里提交,崩溃后从哪个 phase 恢复? | sequence、journal、state machine |
| Code / acceptance | 哪个函数实现规则,什么反例证明它没有被绕过? | 代码领读、smoke、常见错误 |
-这套顺序不是排版约定,而是评审方法。架构层没有明确 owner,技术层通常会复制状态机;
-逻辑层没有 receipt,测试往往只能证明函数跑过,不能证明 transition 已提交。
+这套顺序是评审方法。架构层没有明确 owner,技术层通常会复制状态机;
+逻辑层没有 receipt,测试往往只能证明函数跑过。
课程采用一条贯穿始终的架构边界:执行 runtime、memory provider 和 workspace storage
可以替换或协作,但 goal lifecycle、canonical state contract、验证与恢复闭环由 LoopX
@@ -108,10 +107,10 @@ vision / goal boundary
6. **回执**:外部动作是否形成了与原 proposal 绑定的 durable receipt?
7. **延续**:本轮之后是 runnable successor、明确等待、replan、repair,还是满足 terminal closure?
-控制面的复杂性通常不是缺少第八个字段,而是这七个问题被压进一个布尔值,导致一层
+控制面的复杂性通常是这七个问题被压进一个布尔值,导致一层
事实误替另一层做决定。
-课程不是 API 枚举。每一讲都包含四类材料:
+每一讲都包含四类材料:
- 一条真实 CLI 或状态执行路径;
- 一组核心代码领读入口,说明调用顺序、关键分支和不变量;
@@ -177,7 +176,7 @@ todo 和 evidence 的局部规则会在同一轮组合生效。
| benchmark postcondition + committed Turn + runner readiness | 结果通过为什么不能替代因果归因与控制面回执;测试替身怎样避免改写 meaningful operation 语义? | 第 6、8 讲 |
| external write + Turn journal + provider receipt + settlement checkpoint | 远端效果不确定时为何不能盲目 retry;什么时候应 replay provider,什么时候只能恢复 writeback 或 spend? | 第 6、8、11 讲 |
-这些组合不是额外功能清单,而是同一状态图的交叉切面。课程中的 case、decision table 和 smoke 应尽量覆盖交叉项,而不是为每个名词各写一个孤立 happy path。
+这些组合是同一状态图的交叉切面。课程中的 case、decision table 和 smoke 应尽量覆盖交叉项。
## 版本与边界
diff --git a/docs/development/control-plane-course/goal-control-state-kernel-packet-mental-model.md b/docs/development/control-plane-course/goal-control-state-kernel-packet-mental-model.md
index 27140074dc..035423fe46 100644
--- a/docs/development/control-plane-course/goal-control-state-kernel-packet-mental-model.md
+++ b/docs/development/control-plane-course/goal-control-state-kernel-packet-mental-model.md
@@ -3,7 +3,7 @@
> **结论:** Goal 给出稳定方向,structured control state 记录当前动态局面,Kernel
> 校验并提交合法的状态迁移,Packet 把当前局面编译成 Agent 这一轮可以执行的行动协议。
-这四个名称不是四个并列模块,也不是四份状态。最简单的记法是:
+最简单的记法是:
```text
Goal:要去哪
@@ -46,9 +46,7 @@ Packet:这一轮具体走哪一步
| Kernel | 状态迁移与恢复引擎 | authority 校验、transition 接受、writeback、replay、closeout | 状态文件、领域推理器或 Provider |
| Packet | 一次 Turn 的行动协议 | identity、selected work、允许/禁止动作、proof boundary、next command、writeback contract | 长期事实源或全部历史 |
-Kernel 不是状态本身,而是管理通用生命周期、校验写入并使状态可恢复的规则引擎。Packet
-也不是第二份状态,它只是从当前状态生成的一次性只读投影:Packet 丢失可以重建,canonical
-state 丢失则可能无法正确恢复。
+Kernel 是管理通用生命周期、校验写入并使状态可恢复的规则引擎。
外部系统仍然拥有各自的权威事实。例如 repository 拥有当前代码,Git host 拥有 PR 与
review 状态,CI 拥有检查结果。LoopX 保存的是:为什么观察这些对象、观察结果支持哪个判断、
@@ -89,7 +87,7 @@ flowchart TD
## Packet 由什么生成
-Packet 不是只从一条 Goal objective 生成,而是组合:
+Packet 是组合:
```text
稳定 Goal
@@ -101,7 +99,7 @@ Packet 不是只从一条 Goal objective 生成,而是组合:
+ Kernel 与 Capability 规则
```
-然后压缩成本轮有限上下文可以安全消费的工单。下面是概念示例,不是具体协议的完整 schema:
+然后压缩成本轮有限上下文可以安全消费的工单。
```yaml
packet:
@@ -124,7 +122,7 @@ packet:
```
Packet 必须足够薄,避免把全部历史塞回模型;也不能薄到遗漏 identity、authority、required
-proof 和 writeback。它是过程协议,不是普通提示词摘要。
+proof 和 writeback。
## 一次 Auto PR Issue Fix Turn
@@ -196,7 +194,7 @@ Replan 通常也不会随意改写最终 objective。它先修订路线、vision
## Result 为什么不能直接成为状态
-Agent 说“CI 已通过,建议合并”只是 result 或 proposal,不是 canonical truth。完整路径应是:
+Agent 说“CI 已通过,建议合并”只是 result 或 proposal。完整路径应是:
```text
Agent result
diff --git a/docs/development/control-plane-course/topic-long-horizon-convergence.md b/docs/development/control-plane-course/topic-long-horizon-convergence.md
index cd50811025..9808da4830 100644
--- a/docs/development/control-plane-course/topic-long-horizon-convergence.md
+++ b/docs/development/control-plane-course/topic-long-horizon-convergence.md
@@ -3,8 +3,7 @@
> **本讲结论:** 长程任务的稳定性不来自一次更长的推理,也不来自让 Agent 永远保持活跃。
> 它来自一组跨 Turn 持续成立的收敛合同:方向由 Vision、Goal 与 Acceptance 约束,工作由
> Frontier 选择,外部动作由 Authority 与 Receipt 约束,进展由 Durable Evidence Delta
-> 定义;当证据不再增加或路线失效时,系统进入 Wait、Replan 或 Self-Repair,而不是重复
-> 同一个动作。
+> 定义;当证据不再增加或路线失效时,系统进入 Wait、Replan 或 Self-Repair。
建议时长:60 分钟。问题定义 8 分钟、核心闭环 12 分钟、防跑偏 10 分钟、防循环 12 分钟、
双 Showcase 回放 10 分钟、接入边界与问答 8 分钟。
@@ -30,17 +29,10 @@ Judge 可以判断“是否完成”,却未必能告诉下一轮“路线为
2. 解释为什么 Turn 是执行窗口,Accepted Transition 才是进展单位;
3. 用方向、权限、证据、Delta、活性和终局六条不变量审查长程系统;
4. 解释 Replan、Self-Repair、Monitor Backoff 和 Explore 各自解决哪类停滞;
-5. 解释 successor todo 怎样把局部完成接回 Goal,而不是制造无限任务链;
+5. 解释 successor todo 怎样把局部完成接回 Goal
6. 把 PR Issue Fix 与 Auto Research 映射到同一套收敛闭环;
7. 判断 LoopX、领域 Capability、Provider、Evaluator 与现有 Agent Runner 分别必须提供什么。
-本讲不承诺:
-
-- 给任意模糊目标自动生成正确验收标准;
-- 让模型的每次方案判断都正确;
-- 用一个通用 planner 替代领域 evaluator;
-- 让 Graph、Harness、scheduler 或 supervisor 获得隐藏的执行权限;
-- 把“运行时间更长”直接解释为“结果质量更高”。
## 一小时讲授路线
@@ -146,7 +138,7 @@ external source of truth
| PR Issue Fix | `repo + issue_ref`、`repo + pr_ref` | feasibility、exact-head checks、review/merge state、notification receipt | 把旧 head 的绿色结果用于新 commit;重复处理已覆盖 review |
| Auto Research / ML Experiment | hypothesis/experiment、revision、window、evaluator contract | matched result、dev/holdout、guardrail、support/refute、promotion/retirement proposal | 只记当前最好分数;把 infra failure 当模型负证据;反复探索已证伪 family |
-Domain State 仍不是新的事实源、memory dump 或第二套 Kernel。GitHub、训练系统和 evaluator
+GitHub、训练系统和 evaluator
继续拥有外部真相;pack 只保存可重算、可比较、可幂等更新的紧凑 read model。下面的伪代码
展示这条窄边界:
@@ -177,7 +169,7 @@ schema 和 proposal 属于 pack,最终是否执行仍由 Kernel 判断。
[Domain Capability Packs](../../product/domain-capability-packs.md)和
[Issue-Fix State Kernel × Domain State 案例](../../../loopx/capabilities/issue_fix/docs/state-kernel-domain-state-case-study.zh-CN.md)。
-所以 LoopX 不是一个包办所有推理的“大 Agent”。它更像一个长期控制内核:领域层提供
+它更像一个长期控制内核:领域层提供
可判定事实,host 执行 bounded Turn,Kernel 维护跨 Turn 仍需成立的身份、权限、证据和
恢复合同。
@@ -210,9 +202,6 @@ schema 和 proposal 属于 pack,最终是否执行仍由 Kernel 判断。
这是目标漂移。每个实验都可能执行正确,但优化代理指标的过程已经离开原目标。
-两个失败的共同点,不是模型不够聪明,而是系统没有把“什么约束方向、什么构成新证据、
-什么变化才值得再花一轮”变成可继承的状态。
-
## 先区分四种运行状态
长程系统不能把所有未完成都称为“继续”。至少要区分四种状态:
@@ -224,7 +213,7 @@ schema 和 proposal 属于 pack,最终是否执行仍由 Kernel 判断。
| 目标漂移 | 局部代理目标开始替代 Goal/Acceptance | Vision checkpoint、acceptance audit、replan |
| 局部循环 | 动作重复,但没有新增信息、状态 Delta 或失败区分度 | Stop repeating、diagnose、replan 或 self-repair |
-“重复”本身不是错误。CI 从 pending 变成 failed 后再次处理是合法迭代;外部训练任务未结束时
+CI 从 pending 变成 failed 后再次处理是合法迭代;外部训练任务未结束时
按 due time 轮询也是合法等待。循环的判定依赖三件事:
1. 输入事实是否变化;
@@ -316,7 +305,7 @@ Progress = 与 Acceptance 相关的 durable transition
### 核心代码一:一轮怎样从 Decision 走到 Commit
下面是 `build_quota_should_run`、`build_interaction_contract` 与
-`run_loopx_turn_once` 的教学压缩版。它是结构化伪代码,不是稳定 Python API:
+`run_loopx_turn_once` 的教学压缩版。它是结构化伪代码:
```python
def advance_one_turn(status, goal_id, agent_id, host):
@@ -417,9 +406,6 @@ Todo 可以被替换,计划可以变化,Vision 也可以在新证据下被 p
### 权限不变量:Proposal、Effect 与 Commit 分开
-一个 Agent 可以提出 merge、promotion 或 launch proposal,不代表它有权执行;Provider 执行
-了外部 effect,也不代表它有权修改 Goal lifecycle。
-
```text
proposal
-> authority and scope check
@@ -489,8 +475,6 @@ progress。它们可以更新 cadence 或 compact counter,但不应消耗与
| Rolled back | activation 与 rollback receipt 均绑定 exact revision |
| Closed with gap | 剩余缺口、原因和不再继续的依据明确 |
-“没有更多想法”不是终态证据;“暂时看不到 Todo”也不是。
-
### 核心代码二:Terminal 是严格合取,不是 Todo 为空
下面的伪代码把终局审计压成一个可 review 的 predicate:
@@ -513,8 +497,7 @@ def terminal_ready(state):
```
实际系统还会按领域加入 merge、promotion、rollback 或 `no_followup` 证明,但结构不变:
-终局是多项权威事实的合取。任何一个计数或 readback 缺失,都应产生明确 gap,而不是让
-空 Frontier 冒充 Complete。
+终局是多项权威事实的合取。任何一个计数或 readback 缺失,都应产生明确 gap。
## 防跑偏:方向必须外置,但不能冻结
@@ -527,8 +510,7 @@ def terminal_ready(state):
| Acceptance | 什么证据允许宣称这一阶段完成? | 不直接执行验证或 effect |
| Todo | 下一步由谁、在什么条件下做什么? | 不自行改写长期方向 |
-这条约束链让计划可以灵活变化,同时保持目标连续。它也解释了为什么“写一份大计划然后一直
-执行”不是长程控制面:外部事实变化后,大计划会过期;没有 Vision 和 Acceptance checkpoint,
+这条约束链让计划可以灵活变化,同时保持目标连续。没有 Vision 和 Acceptance checkpoint,
Agent 只能在旧计划与新聊天之间猜测。
### Vision Checkpoint 不是例行总结
@@ -544,8 +526,7 @@ Material closeout 后,系统需要回答三个问题之一:
### Successor Todo:让局部完成留下可执行的下一段责任
-长程任务最常见的薄弱点,不是 Agent 做不完当前 Todo,而是它做完一个局部切片后,只留下
-“继续优化”“看看 CI”或“后续再处理”。这类自然语言意图没有稳定 identity、owner、触发
+长程任务最常见的薄弱点。这类自然语言意图没有稳定 identity、owner、触发
条件和 lineage;session 或 Agent 一换,局部成果就很容易被误判成 Goal 已完成。
Successor todo 把这段隐式意图改写成控制面事实:
@@ -566,7 +547,7 @@ Vision、Goal 或 Acceptance。Successor 只能说明“接下来由谁在什么
1. 创建并绑定 successor,当前局部证据明确说明它继续缩小哪个 Acceptance gap;
2. 写入 gate、monitor、blocker 或 `resume_when`,说明后继为什么暂时不可运行;
-3. 用 terminal evidence 明确记录 `no_followup`,证明不是因为 Agent 没想到下一步。
+3. 用 terminal evidence 明确记录 `no_followup`。
教学伪代码可以压成一个局部闭包合同:
@@ -589,9 +570,9 @@ def close_todo(parent, evidence, result, acceptance):
immediate action,必须显式 complete 或 defer;否则两个 Todo 都可能继续进入 quota。
- 不要为每个 shell command、Turn 或微小子步骤创建 successor。Successor 应出现在有
material closeout、owner/handoff 变化、外部等待或路线变化的语义边界;长链本身应触发
- Vision/Acceptance checkpoint,而不是继续机械加节点。
+ Vision/Acceptance checkpoint。
-因此,successor 机制提升工程质量的方式并不是“让 Agent 多干活”,而是迫使每个局部交付
+因此,successor 机制提升工程质量的方式并是迫使每个局部交付
同时交代证据、剩余缺口和下一段责任。它把“完成当前 PR”与“完成整个 Goal”之间原本容易
丢失的推理,变成可验证、可恢复、可审计的状态转移。
@@ -605,7 +586,7 @@ def close_todo(parent, evidence, result, acceptance):
| Todo | reproduce、patch、monitor、review correction | hypothesis、execute、evaluate、holdout、retire/retry |
| Forbidden proxy | “有新 commit”替代“issue 已解决” | “dev lift”替代“research acceptance 已满足” |
-方向锚点不是静态不变。Reviewer 改变 public contract、实验否定原假设、用户缩小目标范围,
+Reviewer 改变 public contract、实验否定原假设、用户缩小目标范围,
都可以触发 patch;变化必须形成带 source、scope 和 Delta 的状态,而不是只留在聊天里。
### 人的反馈也必须先分类
@@ -694,8 +675,7 @@ CLI 是状态与决策 truth;轻量 skill 或 system instruction 负责约束
- required gate 要给用户具体问题;
- quiet 时不制造 delivery。
-Codex、Claude Code、自研 Agent 或远端开发机可以用各自方式承载这些行为约束。Skill 的安装
-路径不是产品合同,CLI packet、state schema 和 receipt 才是。
+Codex、Claude Code、自研 Agent 或远端开发机可以用各自方式承载这些行为约束。
## 防循环:先判断“有没有增加信息”
@@ -713,8 +693,7 @@ Codex、Claude Code、自研 Agent 或远端开发机可以用各自方式承载
| 候选集中在同一近邻 family | exploration diversity 不足 | 应随机扩展所有分支 |
| dev 改善但 holdout 不变 | evaluator 或假设泛化不足 | 模型永远不可改进 |
-当前 LoopX 工作流常把连续两轮 no-progress 作为触发 Self-Repair 的操作性阈值。它不是所有
-领域的数学定律。昂贵实验、长时间构建和低频外部事件需要领域化 cadence;关键是 streak
+当前 LoopX 工作流常把连续两轮 no-progress 作为触发 Self-Repair 的操作性阈值。昂贵实验、长时间构建和低频外部事件需要领域化 cadence;关键是 streak
必须按 agent lane、monitor target 或 failure identity 归因,不能让一个 lane 的变化替另一个
lane 清零。
@@ -798,7 +777,7 @@ same action with no new basis -> retry loop
new evidence + route delta -> valid replan
```
-Replan 的价值不是“想一个新点子”,而是让下一轮看到不同的合法 Frontier。
+Replan 的价值是让下一轮看到不同的合法 Frontier。
### Replan 的真实复杂度:不是一个 Selector,而是一条可恢复控制链
@@ -832,7 +811,7 @@ Detect
| Settle | 什么变化足以证明没有原地打转? | Delta contract、frontier-scoped ACK、next Frontier |
这条链刻意没有一个“万能 planner”。Detector、Frontier policy、obligation builder、Quota
-和 writeback 各自保留边界。复杂度来自这些合同的组合,而不是来自一个超长函数。
+和 writeback 各自保留边界。复杂度来自这些合同的组合。
一小时现场主讲只需保留这张六层链、ordered rules 的三组优先级、Guidance/ACK 不一致
案例和后面的端到端 trace,约 10 到 12 分钟。下面“之一”到“之六”是讲师备课与课后下钻
@@ -901,7 +880,7 @@ facts = GoalFrontierReplanFacts(
3. **历史只能经 ACK 进入当前判断**:长 Todo 链是否已经被审视、watch lane 是否已确认,
不能从自然语言推断,只能读取带 Delta contract 的 durable ACK。
-所以 `Facts` 不是原始状态的字段搬运,而是一个 agent-scoped、authority-aware 的语义
+所以 `Facts` 是一个 agent-scoped、authority-aware 的语义
reducer。Selector 的确定性依赖这一层先把“谁的工作”“哪种 gap”“哪个 Frontier”归一化。
### 核心代码四之二:Frontier Replan 是有顺序的规则,不是自由发挥
@@ -1046,7 +1025,7 @@ if decision.rule in {MONITOR_NO_CHANGE_STREAK, MONITOR_FRONTIER_EXHAUSTED}:
- `agent_id`:谁有义务处理;
- `stall_threshold` 与 `trigger_count`:为什么现在触发;
-- `triggers`:可回读的证据,而不是一句“感觉卡住了”;
+- `triggers`:可回读的证据
- `todo_actions`:允许写回的最小动作;
- `stop_condition`:遇到 private material、credential、destructive git、production
action 或 owner-only decision 时停止;
@@ -1098,14 +1077,12 @@ derived = derive_goal_frontier_replan_obligation_from_summaries(
return projection(replan_obligation=derived or obligation)
```
-这里防止三种“伪完成”:
+这里防止“伪完成”:
1. **错 Agent ACK**:peer A 的 Replan 不能替 peer B 关闭 obligation;
-2. **旧 Frontier ACK**:相同文案再次出现,不代表仍是同一个 blocked successor;
-3. **过期 ACK**:ACK 早于最新 trigger evidence 时,不能证明新问题已处理。
因此 `autonomous_replan_ack_matches_frontier` 除了比较 `frontier_identity`,还会比较 ACK
-时间和 trigger 时间。ACK 是当前 obligation 的结算凭证,不是“历史上曾经授权过”的通行证。
+时间和 trigger 时间。ACK 是当前 obligation 的结算凭证。
### 核心代码四之五:Quota 把 Obligation 提升为 Must-Attempt
@@ -1127,7 +1104,7 @@ if autonomous_replan_obligation.required:
}
```
-它表达的是一项机器执行义务,而不是用户提醒。即使用户当前没有待办,Agent 也必须先处理
+它表达的是一项机器执行义务。即使用户当前没有待办,Agent 也必须先处理
Replan,再回到 monitor 或普通 advancement。反过来,若真正缺少 owner-only authority,
前面的 `open_user_todo` 或 gate rule 已经短路,不会把用户决策伪装成自主 Replan。
@@ -1163,7 +1140,7 @@ read_back_semantic_receipt()
spend_one_slot()
```
-classification、手工 ACK、读收据和 caller 自报 repair kind 都不是结算凭证。写时 gate
+写时 gate
先重算与 quota 相同的完整 goal frontier,再检查 typed delta;因此旧 periodic ACK 不能关闭
随后轮换出的 vision/frontier obligation,重复维护写回也不能落盘。
@@ -1191,7 +1168,7 @@ quota + refresh-state
对 `repeat_until_closed` vision,maintenance-only continuation 不能结算;对确实应该等待的
`as_needed` 场景,等待应留在有 cadence、expiry、resume condition 的 monitor Todo 生命周期
-中,而不是冒充 replan 成功。这个区分避免把“合法等待”与“方向改变”压进同一个 ACK。
+中。这个区分避免把“合法等待”与“方向改变”压进同一个 ACK。
### 端到端 Trace:为什么一次 Replan 之后还可能继续 Replan
@@ -1285,7 +1262,7 @@ Graph 和 Harness 应独立启用:
| on | on | 证据拓扑已经稳定,需要 advisory portfolio |
对 evaluator 尚不清楚、指标不可比较、资源 identity 不稳定的项目,先用 Graph 记录证据,
-不要急着启用 Harness。当前 Harness 的稳妥定位仍是只读规划器,不是自动 launch controller。
+不要急着启用 Harness。当前 Harness 的稳妥定位仍是只读规划器。
### 不需要先引入多层级 Agent
@@ -1335,7 +1312,7 @@ Executor 不能评价并 promotion 自己的 dev-only 结果。Explore Graph 也
### 门禁也要按风险分层
-不是每轮都运行最昂贵的 Judge。稳定 schema、transition rule 和 identity 先用 deterministic
+稳定 schema、transition rule 和 identity 先用 deterministic
test;真实 Agent 是否正确理解 packet,再用 actual-default model behavior gate;明确宣称
长程 outcome 提升时,才需要 matched stable/candidate baseline。
@@ -1368,7 +1345,7 @@ test;真实 Agent 是否正确理解 packet,再用 actual-default model beha
6. `head-A` 的 checks 通过后,merge 仍等待 scoped authority;
7. host 执行 merge 并 readback merged commit,terminal audit 关闭 monitor 与 successor。
-退出循环的关键不是“第三次终于改对代码”,而是失败被重新分类,新 Turn 增加了能区分代码
+退出循环的关键是失败被重新分类,新 Turn 增加了能区分代码
问题与环境问题的证据。
### 回放 B:Auto Research 怎样退出 dev-only 局部最优
@@ -1381,7 +1358,7 @@ test;真实 Agent 是否正确理解 packet,再用 actual-default model beha
6. `H2` 的 matched holdout 同时满足 metric 与 guardrail,形成 promotion candidate;
7. promotion gate 和 activation receipt 结算后,Goal 决定继续探索还是严格关闭。
-退出局部最优的关键不是随机增加更多 Agent,而是让负向证据真正改变候选空间。
+退出局部最优的关键是让负向证据真正改变候选空间。
## 自编排 Runner 的最小接入合同
@@ -1422,7 +1399,7 @@ Evidence refs,但不能替领域系统宣布收敛。
## 什么时候不应启用更复杂的规划
-下面几种情况适合先收缩问题,而不是增加 Agent 或 Harness:
+下面几种情况适合先收缩问题:
1. Acceptance 仍是一句价值判断,没有可观察的 proxy 与人工 gate;
2. Provider 不能返回稳定 task/effect identity;
@@ -1432,8 +1409,7 @@ Evidence refs,但不能替领域系统宣布收敛。
6. 一个 Goal/Frontier 尚未跑通,就准备增加多层 supervisor;
7. planner 输出会直接触发不可逆 effect。
-此时最有价值的工作通常是完善 Domain Pack、receipt、evaluator 或 public-safe evidence,
-而不是提高 branch width。
+此时最有价值的工作通常是完善 Domain Pack、receipt、evaluator 或 public-safe evidence。
## 当前能力边界
diff --git a/docs/development/design.md b/docs/development/design.md
index 5ff9dc5818..b741744357 100644
--- a/docs/development/design.md
+++ b/docs/development/design.md
@@ -103,7 +103,7 @@ Owner-facing state follows four rules:
another's observed activity. Distinguish a recent ended turn from execution.
Show missing coverage neutrally beside the Goal state, with each affected
Agent, host and read failure available through the shared contextual help.
- A cadence miss is an older observation, not proof of a stopped worker.
+ A cadence miss is an older observation.
- **Group by responsibility.** Collaboration surfaces place work under the
member, Agent or owner responsible for it, so one glance shows who is doing
what and who is blocked. Work with no resolvable owner goes into an explicit
@@ -207,7 +207,7 @@ the chart. Show one finding at a time with its declared status and full text;
keep all findings selectable and failed or tentative counts visible. Preserve
the exact finding event on reload and Back, including an earlier judgment later
revised under the same finding identity. Period selection opens the original
-event from that period; current-state projection does not replace its text. Offer the whole recorded history in place
+event from that period; Offer the whole recorded history in place
and through the existing return action, without letting it bury the chosen text.
When opening a specific finding, put its parent question in accessible contextual
help rather than another collapsed title row. Opening a route's question still
@@ -299,11 +299,10 @@ model or rewrite a saved result. Record remaining content failures in the
existing task and review.
译文验收须对照原文及引用语境,核对数量所指、否定和不确定性。字段齐全、原始标记
-未变,不代表含义已经清楚。有来源支持的数量用界面语言正文说清,不能只留下括号内
+未变。有来源支持的数量用界面语言正文说清,不能只留下括号内
的连写英文;准确原词仍可查,含义不明的计数、单位和标识不猜测。修订沿版本化分析
处理,评审不自动重跑模型或覆盖已存结果;剩余正文问题记入原任务和评审。
-
刷新和前进后退保留视图、时间分组与证据焦点;标签之间保留阅读位置。选择状态按
Goal 和来源隔离。研究中从侧栏切换 Goal 仍停留在研究页,读取新 Goal 自身证据;
返回恢复原 Goal 的选择。首页及任务、会话、成果的明确链接保留各自目的地。
@@ -584,8 +583,7 @@ keys do not define tokens. PostCSS and its declared value parser distinguish
stylesheet declarations and variable functions from quoted examples, comments
and other declaration values. Parse errors fail the check.
-This is a syntactic inventory: it does not prove runtime reachability, resolve
-object spreads or aliases, or model CSS inheritance and selector scope. Tokens
+Tokens
that are genuinely optional may keep a fallback (`var(--pw-surface, #fff)`).
### Type Scale
@@ -924,7 +922,6 @@ For feature development, carry one user task through the
A visually consistent composition must also eliminate unnecessary re-entry and
confirmation, identify the affected target, and show truthful state after action.
-
For UI implementation, migration, or reproduction:
1. Read this file before editing.
diff --git a/docs/development/documentation-layout.md b/docs/development/documentation-layout.md
index f1431d1f61..a5f3c27366 100644
--- a/docs/development/documentation-layout.md
+++ b/docs/development/documentation-layout.md
@@ -140,8 +140,7 @@ binary evidence. The old `examples/personal-workspace-browser/evidence/` and
Before removing a pack, inspect references across documentation, navigation,
source code, tests and distribution/build scripts, including references to its
README or manifest. Preserve transitive consumers and distinguish fixture reads
-from screenshot output paths. No static references is a review signal, not proof
-of disuse. Repair current links in the same change, preserve the bytes of retained
+from screenshot output paths. No static references is a review signal. Repair current links in the same change, preserve the bytes of retained
assets, and run the relevant link/asset checks. Retire tests only under the
[smoke retention rules](good-smokes.md), not because their files are large.
diff --git a/docs/development/frontend-delivery.md b/docs/development/frontend-delivery.md
index 0affd9b255..947f0defc8 100644
--- a/docs/development/frontend-delivery.md
+++ b/docs/development/frontend-delivery.md
@@ -16,8 +16,7 @@ the control plane or change the installed runtime.
For owner-authorized reads of existing runtimes, shared access lives in
`loopx.control_plane.status.goal_source`. Native status and Explore owners retain
-their semantics; this Python IO provider adds neither decisions nor lifecycle
-authority. Connection (`local` or a configured `ssh` alias) is independent of
+their semantics; Connection (`local` or a configured `ssh` alias) is independent of
environment (`host` or a container pinned by its full physical id), so a remote
container uses the same reader. It never starts a container, tunnel or worker.
@@ -95,8 +94,7 @@ source-namespace-isolated store; it creates no Goal mirror or source mutations.
The adapter uses one local Python process with one HTTP listener/thread per
prepared source. Cache misses invoke the source's native status CLI or bounded
log read; no lower CPU, process or IO cost is implied. Local host/container
-readback and SSH command composition are separate validation boundaries; a
-composed command test does not prove a live remote host/container journey.
+readback and SSH command composition are separate validation boundaries.
### Native App source Goals
@@ -145,8 +143,7 @@ through the original Goal's native history, including versions outside the
status window. Its default overview spans all retained records by recorded time;
it never silently selects the latest version. Sources proven to have no Explore
records show this overview directly. Other sources keep their Explore history
-and load strategy history only on request. Unknown times stay visible, and time
-adjacency establishes neither inactivity, inheritance nor causal benefit.
+and load strategy history only on request. Unknown times stay visible.
It preserves original language, negative results and unresolved
questions. The focused reader supports exact-version links, reload, Back/Forward
and unavailable-version recovery; missing versions never select the latest one
@@ -211,9 +208,7 @@ to make the display work. Label the link as historical, preserve the source byte
and retain the old namespace's artifacts. Admit the replacement through the same
source-link owner; its new physical namespace must invalidate old cursors and
analysis selection. Re-register an existing evidence pack only after verifying
-its original run/window, hashes and literal excerpts. Neither recovery nor
-registration starts analysis or turns an old native measurement into a current
-or countable study result.
+its original run/window, hashes and literal excerpts.
## Finding original steward delegations
@@ -240,8 +235,7 @@ only when **Linked work and records** is expanded, through the same authorized
reader and current request revision. It is a separate current observation, not
part of the request ordering/paging digest. Original conversations remain readable
through their existing complete-history reader. The 2,000-entry discovery bound
-and explicit incomplete coverage remain; this change does not claim an unbounded
-history index or an atomic snapshot.
+and explicit incomplete coverage remain.
Inventory and original-history HTTP reads both pin the shared runtime code
revision once per request. Without that boundary, every collaboration rule on a
@@ -253,7 +247,7 @@ are reread. It caches no authorization or completion decision.
在管家页头打开**委派**,输入请求内容、Goal、Agent 或请求 ID 后点**搜索**。
查询不区分大小写,匹配原始问题及当前交办的目的/背景,先筛选再分页。
**全部记录**包括已回传和已取消的请求;展开可回看交办、关联工作及原对话。
-**清空**恢复列表。页头数量仍表示全部待跟进请求,并非搜索命中数;读取不完整
+**清空**恢复列表。页头数量仍表示全部待跟进请求;读取不完整
时保留提示,**重试**沿用当前查询。搜索沿用既有来源授权和扫描上限,不确认、
取消或执行任何请求。
@@ -288,8 +282,7 @@ instead of following the latest message to the end.
The read projection requires the original Session, Turn and both existing
transport/Core correlation receipts. Canonical messages, model input and history
cursors remain unchanged. Missing, changed or unsupported frozen context keeps
-the full original message visible. Browsing neither replays work nor contacts the
-provider to fill missing context.
+the full original message visible.
外部原会话和委派的**原对话**优先显示用户原文,**引用与话题上下文**默认折叠。
展开后可读准确引用和按原顺序保存的话题节选,长内容不会跳到末尾。节选标记保留,
@@ -595,7 +588,7 @@ order only, without changing Goal priority, lifecycle or execution.
The existing TypeScript ordering functions remain the semantic owner. The
Python presentation adapter validates and atomically stores the list under a
-file lock; it is not a capability configuration namespace. Existing same-origin
+file lock; Existing same-origin
browser preferences migrate only when the durable source has no value. An old
origin's inaccessible browser storage cannot be recovered automatically. Read
or save failure keeps the current page usable and displays unsaved feedback;
@@ -605,8 +598,7 @@ although that runtime continues to use its browser-local preference.
The packaged `navigation-sorting` browser scenario uses synthetic workspace
records with the real HTTP preference owner. It checks pointer/keyboard moves,
refresh, service restart on another port, delayed hydration, rapid moves,
-failure/retry and browser-cache migration. It does not certify native WebView
-crash recovery or an already-installed App's adoption of a proposed PR.
+failure/retry and browser-cache migration.
## PR qualification and releases
diff --git a/docs/development/good-smokes.md b/docs/development/good-smokes.md
index 7c9676753a..ac48914673 100644
--- a/docs/development/good-smokes.md
+++ b/docs/development/good-smokes.md
@@ -84,9 +84,9 @@ contract. Before removing or combining a smoke:
6. rerun the focused entries plus fleet or catalog checks to prove that the
inventory has no coverage gap.
-名称相似或 setup 相同,并不能证明两个 smoke 保护同一合同。删除或合并前,应分别写明
+名称相似或 setup 相同。删除或合并前,应分别写明
不变量、公开入口、反例、运行频率和定向 profile;把完全相同内容和直接嵌套执行当作
-审阅候选,而不是自动删除指令。可以复用 canary harness 中的 fixture 或 subprocess
+审阅候选。可以复用 canary harness 中的 fixture 或 subprocess
setup,但不要因此合并不同的语义断言。去掉 smoke 调用另一个 smoke 的 wrapper,让每
个合同只运行一次且仍可独立选择,最后重跑聚焦入口以及 fleet/catalog 检查,确认清单
没有覆盖缺口。
@@ -124,7 +124,7 @@ a dated research note, candidate ranking packet, temporary run review, or
transitional benchmark decision. Keep that information in the research document
and cover shared invariants with a data-driven aggregate smoke.
-Smoke 超过约 500 行时,应重新检查它是否混合了多个测试;这不是自动删除或失败阈值。
+Smoke 超过约 500 行时,应重新检查它是否混合了多个测试;
将可复用行为放回产品 owner,使 smoke 保持轻量;较小测试无法覆盖真实端到端 adapter
合同时,仍可保留大型 integration smoke。不要用一次性 smoke 固化过期研究笔记、候选
排名、临时运行评估或阶段性 benchmark 决策的精确文案;这些信息留在研究文档,共有
diff --git a/docs/development/lexical-retrieval.md b/docs/development/lexical-retrieval.md
index ead87beb15..cd8670158e 100644
--- a/docs/development/lexical-retrieval.md
+++ b/docs/development/lexical-retrieval.md
@@ -24,7 +24,7 @@ The fixed algorithm is BM25 with k1=1.2, b=.75 and positive Lucene IDF.
Casefolded Unicode word tokenization splits underscores. Repeated query terms
do not boost scores. No synonyms, embeddings, segmentation service, discovery,
storage, configuration, network or Goal authority are introduced. Ranking is
-corpus-relative; a score does not certify a fact, risk, investment edge or trade.
+corpus-relative.
Historical consumers must supply only their visible corpus: future documents
would otherwise change document frequencies even if hidden from the results.
@@ -169,7 +169,7 @@ controlled by this small driver, so timing samples are descriptive. It generates
no answer and measures no causal task utility. The suite/report formats are
local experiments, not new Core contracts.
-Manual recall does not enable automatic memory. Current explicit instructions
+Current explicit instructions
belong to Semantic Preference; qualified procedural advice uses existing
`agent-turn-recall` after admission, and verified-outcome writeback remains
separate. Material recall still requires source rebase. No frontend comparison
@@ -185,5 +185,5 @@ No new automatic capability hook or UI/Lark configuration is enabled.
自修复 skill 保留解析器、准确 pattern/code 优先级和完整正文展开。现有 workflow
installer 和 wheel 将规范评分器打包到脚本旁,隔离运行仍无需 PATH 中的 LoopX。
-打包副本是构建/安装产物,不是第二份实现。金融消费者保留规范资产、字面匹配规则、
+打包副本是构建/安装产物。金融消费者保留规范资产、字面匹配规则、
信源/时点/lifecycle 边界和决策权威。不启用新的自动 capability hook 或 UI/Lark 配置。
diff --git a/docs/development/project-code-tour.zh-CN.md b/docs/development/project-code-tour.zh-CN.md
index 60ceef7f7f..fa647b3c14 100644
--- a/docs/development/project-code-tour.zh-CN.md
+++ b/docs/development/project-code-tour.zh-CN.md
@@ -13,7 +13,7 @@ LoopX 是一个运行在 Codex、Claude Code、Cursor 等 Agent harness 之上
- **Agent**负责完成一次具体工作;
- **LoopX Kernel**负责决定下一步是否合法、是否需要等待、是否需要询问人,以及如何从中断中恢复。
-本文讲的是“项目怎样工作”,不是逐个枚举所有 CLI 命令。仓库的命令面很大,第一次阅读应先抓住主干,再按需要深入能力包和扩展。
+本文讲的是“项目怎样工作”。仓库的命令面很大,第一次阅读应先抓住主干,再按需要深入能力包和扩展。
## 业务背景:为什么需要一个控制面
@@ -131,7 +131,7 @@ loopx/
## 四种运行责任:不要把边界读混
-LoopX 的目录分类和运行责任不是同一个维度。阅读一条调用链时,先问“谁拥有哪一类事实”:
+阅读一条调用链时,先问“谁拥有哪一类事实”:
| 角色 | 负责什么 | 明确不负责什么 |
| --- | --- | --- |
@@ -199,7 +199,7 @@ adapter_id: ...
后面还有 Authority Sources、Operating Contract、Non-Goals、User Todo、Agent Todo、Next Action 和 Progress Ledger。它不是普通笔记,而是后续 Agent tick 要读取的持久状态。
-Bootstrap 还会维护 Registry 条目。Registry 记录 Goal id、项目路径、adapter、状态文件、authority source、spawn policy、write scope 等信息。注意这里的 `write_scope` 是边界声明,不是自动授予外部系统权限。
+Bootstrap 还会维护 Registry 条目。Registry 记录 Goal id、项目路径、adapter、状态文件、authority source、spawn policy、write scope 等信息。注意这里的 `write_scope` 是边界声明。
## 一次典型场景:从 Goal 到下一轮 Turn
@@ -276,7 +276,7 @@ Quota 结果会被压缩成一个面向 Host/Agent 的 packet。关键字段通
| `capability_gate` | 是否需要领域能力、用户批准或额外检查。 |
| `todo_write_hint` | Todo 写回时需要遵守的最小协议。 |
-这些字段是“当前 snapshot 的编译结果”,不是新的事实源。下一次运行仍应从 Registry、Goal State、Authority Store 和运行历史重新生成。
+这些字段是“当前 snapshot 的编译结果”。下一次运行仍应从 Registry、Goal State、Authority Store 和运行历史重新生成。
### 第 3 步:构造 Turn Plan
@@ -292,7 +292,7 @@ Turn Driver 把 quota packet 转成 Host 可以执行的计划,主要绑定:
- 子 Agent 的上下文与允许的 child operation;
- 后续 transaction plan 和 settlement identity。
-这里有一个重要原则:**Turn plan 是一次执行的合同,不是执行结果。** 计划中写了要做什么,结果必须回来后再经过 schema、phase 和 identity 校验。
+这里有一个重要原则:**Turn plan 是一次执行的合同。** 计划中写了要做什么,结果必须回来后再经过 schema、phase 和 identity 校验。
### 第 4 步:Host 执行有界工作
@@ -311,7 +311,7 @@ Host request 会携带本轮允许的上下文、工作目录边界、执行模
- 不需要 spend 的结果是否错误地写入了 quota spend;
- durable completion 是否指向了预期 Todo,以及 continuation 是否为 successor、active goal 或 no-followup。
-`run_loopx_turn_once` 再按阶段运行 Host、任务 validator 和 typed settlement。它的返回值不是“模型说完成了”,而是带有可追溯 identity、完成阶段和结果类型的结构化结果。
+`run_loopx_turn_once` 再按阶段运行 Host、任务 validator 和 typed settlement。它的返回值是带有可追溯 identity、完成阶段和结果类型的结构化结果。
> 📦 **额外知识:bounded Turn 的边界在哪里?**
>
@@ -343,7 +343,7 @@ validation
> 📦 **额外知识:Idempotency(幂等)怎么理解?**
>
-> 同一个带 identity 的提交重复到达时,系统应识别“这是同一件事的重试”,而不是再创建一份新的事实。LoopX 通过 effect id、Todo/Turn 绑定、completed phase 和 receipt 来实现这种判断,而不是依赖“最近一次运行看起来像成功”。
+> 同一个带 identity 的提交重复到达时,系统应识别“这是同一件事的重试”。LoopX 通过 effect id、Todo/Turn 绑定、completed phase 和 receipt 来实现这种判断。
### 第 6 步:写回运行历史与事件投影
diff --git a/docs/development/returned-files-readback.md b/docs/development/returned-files-readback.md
index 39346b2ee0..650dd1f65b 100644
--- a/docs/development/returned-files-readback.md
+++ b/docs/development/returned-files-readback.md
@@ -13,8 +13,7 @@ same original-message download route.
## Source and byte checks / 来源与字节校验
- History joins the original Session, Turn and return route, then reuses
- `inspect_result_identity` and the TypeScript result-publication owner. The
- projection changes neither the message journal nor publication receipts.
+ `inspect_result_identity` and the TypeScript result-publication owner.
- A download repeats those checks and uses `read_result_file` to verify the
bounded, no-follow immutable snapshot's size and SHA-256. A mutable workspace
file is never the download source. An unavailable snapshot returns HTTP 503;
diff --git a/docs/development/status-service-readiness.md b/docs/development/status-service-readiness.md
index b617dec486..73c3a19f2a 100644
--- a/docs/development/status-service-readiness.md
+++ b/docs/development/status-service-readiness.md
@@ -25,9 +25,7 @@ fingerprint behavior. Advertising readiness but omitting its result fails closed
This is a bounded existing-service prerequisite for
[#3930](https://github.com/huangruiteng/loopx/issues/3930), not the unified daemon
-contract or complete M1 delivery. It does not establish service-profile identity,
-validate individual Goals, prove writable storage, qualify launchd lifecycle,
-or assert Chat/provider readiness. Profile identity, supervisor composition and
+contract or complete M1 delivery. Profile identity, supervisor composition and
migration remain separate implementation work.
To diagnose failure, repair the registry selected by the service and retry the
diff --git a/docs/development/testing-and-quality.md b/docs/development/testing-and-quality.md
index fe32212b3b..2439ec2b9a 100644
--- a/docs/development/testing-and-quality.md
+++ b/docs/development/testing-and-quality.md
@@ -59,6 +59,23 @@ without pretending that the repository is fully qualified.
确定性最小门禁,或例外没有理由,审计会失败。合法的 deferred 行仍作为 backlog
缺口显式展示,不会伪装成仓库已经完全就绪。
+### Local-First Premerge Gate vs. Asynchronous CI / 本地优先门禁与异步 CI
+
+Remote CI stays asynchronous safety coverage, not a mandatory serial bottleneck
+when local deterministic verification is already complete. When a managed Goal
+sets `pull_request_review.wait_for_ci=false`, callers pass `--registry` and
+`--goal-id GOAL` to `loopx pr-review` and `--check-merge-readiness`, resolving
+`ci_policy="not_consulted"` so local `pytest`/`ruff`/`mypy` checks,
+`loopx canary premerge --from-git-diff --git-diff-base "$PR_BASE_REF"`, and
+exact-head review complete merge readiness without waiting on or polling CI.
+Standalone or unconfigured callers keep the safe default `wait_for_ci=true`.
+
+当本地确定性验证已完整通过时,远端 CI 作为异步安全兜底,而不应成为串行阻塞点。对于配置了
+`pull_request_review.wait_for_ci=false` 的受管 Goal,调用 `loopx pr-review` 与
+`--check-merge-readiness` 时须显式传入 `--registry` 与 `--goal-id GOAL`(解析为
+`ci_policy="not_consulted"`),以本地测试、`loopx canary premerge` 和精确头评审直接完成
+就绪判断与合入,不再等待或轮询远端 CI;未配置 Goal 的独立调用保持默认 `wait_for_ci=true`。
+
Tests first judge whether the state and rule are correct, then whether the
implementation conforms. Expected outcomes come from an independently reviewed
invariant, never the implementation under test or its current output.
@@ -68,7 +85,7 @@ refreshed golden.
测试先判断状态和规则是否正确,再验证实现是否符合。预期结果必须来自独立审阅的
不变量,不能由被测实现或当前输出生成。Characterization fixture 只记录历史
-行为,不授予其正确性;发现矛盾时应修复规则并增加反例或 mutation 覆盖,不得刷新
+行为;发现矛盾时应修复规则并增加反例或 mutation 覆盖,不得刷新
golden 来让测试通过。
### State Composition Qualification / 状态组合验证
@@ -83,8 +100,7 @@ checks, real-backend gates and required validation remain in force.
跨领域状态机变更沿[组合验证 RFC](../architecture/rfcs/composable-state-machines-recovery-verification-v0.zh-CN.md)
选择有界旅程,复用 quality catalog 与已有验证矩阵。记录独立不变量、探索的 actor/
-resource 数与轨迹上限、故障顺序、真实入口/回读证据及有条件推进前提。有界序列
-检查不等于无界活性证明;既有确定性检查、真实后端门禁与必需验证继续适用。
+resource 数与轨迹上限、故障顺序、真实入口/回读证据及有条件推进前提。既有确定性检查、真实后端门禁与必需验证继续适用。
For a selected typed-core replacement, check illegal combinations at compile
time and malformed/historical input at runtime. Compare pinned base/head through
@@ -94,8 +110,7 @@ Retain only durable counterexamples, and do not build a general harness when an
existing conformance family can express the causal sequence.
选中的 typed core 替换同时验证编译期非法组合与运行时损坏/历史输入。相同公开
-路径比较 pinned base/head,用历史失败或语义 mutation 证明敏感性;候选实现生成
-的 golden 不是 oracle。只保留持久反例;已有 conformance 测试族能表达因果序列时,
+路径比较 pinned base/head,用历史失败或语义 mutation 证明敏感性;只保留持久反例;已有 conformance 测试族能表达因果序列时,
不另建通用 harness。
## Pull-Request Baseline / PR 基线
@@ -217,7 +232,7 @@ CI Maintenance 清理任务处理 closed 与 synchronize 事件(更新规则
`always()` 汇总使用强制取消 API。普通及强制取消前都重读目标 PR 和同源分支的
开放 PR;新出现的共享分支 PR 或读取失败会阻止副作用,分支不再共享后可重新
触发清理。清理需要一个短 runner 任务;这会释放过期
-容量,不等于为发布预留容量或设置 GitHub 共享池优先级。
+容量。
The [job exemption policy](ci-impact-selection.md) additionally permits pure
Dashboard-client changes to skip backend Python/Windows and Stage2c, while
@@ -251,7 +266,7 @@ implementations share the new rule is not a before/after compatibility test.
重构评审必须区分“相同判定”和“相同可观察语义”:同样拒绝但丢失对象状态或修复
提示仍是回归;新增认领前提可能阻断旧实现允许的未认领文案修正;`--note` 被 parser
-接受或出现在成功响应中,也不能证明它经过 dispatch 后落盘并能独立回读。先从旧调用
+接受或出现在成功响应中。先从旧调用
方及公开契约列出合法/非法分支,再运行基线与精确 head 的对照,不从新实现生成期望。
Show regression sensitivity: the focused case must fail on the historical
@@ -325,8 +340,6 @@ as nonblocking performance risks for default SQLite delivery, with their actual
values, source and limits. They are not passing checks. When the maintainer
revises a previously declared profile, record a new scoped qualification and
the reason; retain the original failed observation and its original criteria.
-This rule changes neither performance thresholds nor frozen benchmark/scoring,
-resource, deadline or promotion contracts.
默认交付按实际发布的默认执行/存储 profile 取得性能资格;当前新建本地 Goal
由既有 `goal_storage` owner 默认选择 SQLite。对真实 SQLite 入口、完整负载及
@@ -413,8 +426,8 @@ lease。私有快照和原始输出不得进入 Git 或公开 review;快照演
#### Isolate the managed Effect process as well as the data
-A separate worktree, registry, `--runtime-root` or archive `--destination`
-isolates neither CPU work nor the managed Effect server. Its discovery directory
+Isolate the managed Effect server's discovery directory alongside the worktree,
+registry, `--runtime-root` and archive `--destination` paths. Its discovery directory
uses Python's temporary directory and user identity; the server is selected by
source fingerprint. Identical checkouts and an installed release can therefore
share the same process. A large restore/audit can delay ordinary CLI requests
@@ -432,14 +445,13 @@ that isolated runtime after its requests settle, retaining the same temporary
environment for shutdown; never restart a live server as test cleanup.
For namespace disposal, call `restart_effect_runtime(wait_for_exit=True)` and
-require `stopped` before removing files. A closed listener or a zombie process
-group leader does not prove that all runtime threads have exited. A PID that is
+require `stopped` before removing files. A PID that is
still present returns `shutdown_pending`; retain the namespace and retry after
the process exits and its parent reaps it. The ordinary restart action still
uses serving-locator retirement.
删除隔离目录前,调用 `restart_effect_runtime(wait_for_exit=True)` 并确认返回
-`stopped`。端口关闭或进程组长成为僵尸进程,都不能证明其他线程已经退出。
+`stopped`。端口关闭或进程组长成为僵尸进程。
PID 仍存在时返回 `shutdown_pending`;保留目录,等进程退出并由父进程回收后再试。
普通重启操作仍按服务 locator 的退役状态判断。
@@ -460,10 +472,8 @@ repository identity.
Process isolation still shares machine resources. Run matched timing arms
sequentially without overlapping builds or recovery work. If interference is
discovered, retain failures and durable-receipt evidence, mark latency samples
-contaminated and resample after quiescence. A client timeout does not prove its
-server operation stopped; do not launch a duplicate restore while the first
-request may still be running. Neither a successful restore nor a clean resample
-qualifies concurrent administrative-work fairness or elapsed soak.
+contaminated and resample after quiescence. Do not launch a duplicate restore while the first
+request may still be running.
独立 worktree、registry、`--runtime-root` 或 archive `--destination` 不会隔离
Effect 后台进程;相同源码指纹可能让源码环境与已安装版本共享进程。演练前创建私有
@@ -472,7 +482,6 @@ Effect 后台进程;相同源码指纹可能让源码环境与已安装版本
重型操作前核对服务 PID 与活跃服务不同。等请求结束后,只在同一临时环境中停止
演练进程。进程隔离不消除整机资源竞争:耗时对照顺序运行,发现竞争则保留失败与
回执、作废受污染耗时并重新采样;超时不能当作服务端已停止,也不能因此重复恢复。
-恢复成功不证明并发管理操作公平性或自然时间 soak 已合格。
The Effect server drains admitted handlers before retiring. With compilation
caching enabled, its final synchronous cache flush has a one-second allowance,
@@ -521,16 +530,14 @@ Windows 文件锁只在已观察到争用后,对独占创建返回的 `EPERM`
Smoke cleanup owns every valid runtime locator in its newly created private
temporary namespace, including runtimes loaded by temporary base checkouts.
It uses the existing authenticated shutdown protocol, then observes actual
-process exit before deleting the namespace; serving-locator turnover alone
-does not establish that Node has finished its exit-time cache writes. Namespace
+process exit before deleting the namespace; Namespace
and locator symlinks are not followed. A cleanup failure retains the fixture
and reports a failed check with the original command output. Operator restart
keeps its existing serving-handoff semantics. This fixture repair does not
qualify native intermittent failures or sustained operation.
Smoke 清理覆盖新建私有临时目录中所有合法 runtime locator,包括临时基线 checkout
-启动的进程。它复用既有认证 shutdown,等实际进程退出后再删目录;定位文件退休不代表
-Node 的退出缓存写入已经结束。清理不跟随 namespace 或 locator 符号链接;无法证明
+启动的进程。它复用既有认证 shutdown,等实际进程退出后再删目录;清理不跟随 namespace 或 locator 符号链接;无法证明
退出时保留 fixture,以失败结果报告并保留原命令输出。操作员 restart 仍沿用既有服务
交接语义;该 fixture 修复不认证原生间歇故障或持续运行。
@@ -558,7 +565,7 @@ fields. A large real-state snapshot does not exercise commands synthesized only
inside an executor: run unchanged production caller chains, including reclaim,
replay and stale-writer rejection, before claiming caller closure. Persistent
public grants and clock-authorized ephemeral executor grants are separate
-contracts; neither a broad allowlist nor agreement across providers proves parity.
+contracts.
迁移决策 owner 时,既要盘点状态字段,也要盘点命令生产者。真实大快照不会自动覆盖
executor 内部生成的 reclaim 等命令;必须运行未改动的完整调用链,包括接管、重放和
@@ -642,7 +649,7 @@ packages outside the selected extras: do not change a worktree's environment
while another process is using it. Existing full-suite and CI commands below
continue to use `test`.
-`test-core` 仅用于显式选择的测试文件,不代表完整测试通过。MCP、Docker、图片
+`test-core` 仅用于显式选择的测试文件。MCP、Docker、图片
渲染、覆盖率和类型检查继续使用完整的 `test`。后续 `uv run` 也需指定
`--extra test-core`,保持环境一致。`uv sync` 可能移除所选依赖组之外的包,
因此不要修改正在被其他进程使用的工作区环境。下方完整验证及 CI 命令继续使用 `test`。
@@ -698,8 +705,7 @@ Use the app's existing installation and validation commands when required.
不删除文件、不改变构建流程;需要安装或验证时,继续使用应用原有命令。
Clean old dependency environments separately after checking worktree ownership,
-active users and recoverable dependency definitions. Age alone is not evidence
-that an environment is unused. Keep this an explicit maintenance operation.
+active users and recoverable dependency definitions. Keep this an explicit maintenance operation.
旧依赖环境另行清理:先核实工作区归属、使用中的进程,以及依赖定义能否恢复。
目录较旧不能证明无人使用;清理应作为显式维护操作进行。
@@ -708,8 +714,7 @@ that an environment is unused. Keep this an explicit maintenance operation.
`loopx/control_plane/` and `loopx/zcode_goal_mode/`, including standalone bridges
launched from Python and control-plane test drivers. New source files in these
owners need no per-file compiler registration. Tests and examples retain their
-explicit compile entries; this does not claim every TypeScript test is
-typechecked. `npm run test:control-plane` separately discovers and executes
+explicit compile entries; `npm run test:control-plane` separately discovers and executes
`tests/control_plane_ts/*.test.ts`.
`npm run typecheck:control-plane` 按既有目录发现全部控制面与 ZCode TypeScript
@@ -742,7 +747,7 @@ restart a shared service to repair a source-validation mismatch.
继承的 `PYTHONPATH` 也可能让 `uv run loopx` 越过可编辑安装,加载其他源码。
控制台脚本从 scripts 目录启动,而 `python -c`、`python -m` 会把当前目录放在
-导入路径前面;后两者导入成功不能证明控制台进程正确。POSIX 下源码验证可使用
+导入路径前面;POSIX 下源码验证可使用
仅对本条命令生效的 `env -u PYTHONPATH uv run --extra test loopx ...`;在仓库外
启动的测试子进程应显式将 `PYTHONPATH` 绑定到被测 checkout。验证真实控制台及其
语义结果,并与安装版验收分开;不要为源码验收偏差修改共享环境、提升安装版或
@@ -827,7 +832,7 @@ and record the actual source and argv. A matching version string alone is not
source provenance. Isolated CLI test launchers should likewise pin the checkout;
they must not accidentally qualify an installed release.
-上面的检查只说明该 Python 调用的来源,不能证明另一个 console script 的来源。
+上面的检查只说明该 Python 调用的来源。
继承的 `PYTHONPATH` 可能让已安装版本优先于 worktree;在仓库根目录执行 `python -c`
又可能掩盖差异。源码验证使用上述模块入口,并仅在该子进程内把当前目录放到导入路径
首位;保留其他设置,记录实际源码和 argv,不凭相同版本号判断来源。隔离 CLI 测试的
@@ -961,8 +966,7 @@ Full Python shards also opt into `--ci-stall-after 120` on the existing pytest
observer: a long-running test attempts to print its executing thread's Python stack without
terminating it or changing its result. This cooperative diagnostic needs the
interpreter to schedule its observer thread; it does not diagnose native code
-that holds the GIL indefinitely. The dump is diagnostic evidence, not proof that the last named test
-caused a stall. Reproduce with `-p scripts.ci.pytest_timing --ci-stall-after 120`; omit
+that holds the GIL indefinitely. The dump is diagnostic evidence. Reproduce with `-p scripts.ci.pytest_timing --ci-stall-after 120`; omit
`--ci-stall-after` or set it to `0` to keep this default-off diagnostic disabled. This grants no authority to
inspect other processes. Large text-boundary fixtures use short parameter IDs
so verbose progress records their cases without printing the payload.
@@ -994,7 +998,7 @@ JUnit、coverage 或必过门禁。归属与测量边界见
超过该时长就尝试输出其执行线程的 Python 栈,不终止测试或改变结果。此协作式诊断
需要解释器调度观察线程,无法诊断始终占有 GIL 的原生代码。栈用于诊断,不能只凭
最后一个测试名认定卡顿根因。本地加 `-p scripts.ci.pytest_timing --ci-stall-after 120`
-复现,省略此参数或设为 `0` 可保持默认关闭;它不授予检查其他进程的权限。大文本边界 fixture 使用简短参数 ID,详细进度保留用例身份,
+复现,省略此参数或设为 `0` 可保持默认关闭;大文本边界 fixture 使用简短参数 ID,详细进度保留用例身份,
不打印整个载荷。
每次触发栈输出时,使用同解释器的隔离 writer,100ms 自行退出;父进程另设
500ms 通信期限,超时则终止并回收。管道背压不会改变共享 stderr 标志或留下
@@ -1112,7 +1116,7 @@ Binary images are outside the public-boundary **text** scan. Premerge lists
each changed raster image in `selection_inputs.visual_review_paths` and the
existing `manual_holds`, including image-only changes outside documentation
directories. Text checks can pass while the overall gate remains
-`manual_review_required`; this does not certify image privacy or permit merge.
+`manual_review_required`.
Inspect the exact revision's pixels, embedded metadata and source in the
existing PR review, and retain public-safe first-screen evidence in the PR
description. Do not add another presentation-confirmation round. Unknown
@@ -1178,9 +1182,7 @@ the daily full-public sweep, and high-risk release profiles. It aggregates
duration, failures, timeouts, current-inventory coverage, and targeted profile
ownership without copying stdout/stderr tails or repository-local paths.
-full-public workflow 还会把各 shard 回执聚合成一个紧凑健康产物。报告区分四种频率,
-而不是把每个 smoke 都变成 PR 必跑项:显式 PR 快速 smoke、catalog 选择的 canary、
-每日 full-public 全量,以及高风险 release profile。它会统计耗时、失败、超时、当前
+full-public workflow 还会把各 shard 回执聚合成一个紧凑健康产物。报告区分四种频率。它会统计耗时、失败、超时、当前
清单覆盖率和定向 profile owner,同时不会复制 stdout/stderr tail 或仓库本地路径。
```bash
@@ -1198,7 +1200,7 @@ test is valueless.
默认输出是有界的审阅摘要;只有显式诊断冷路径才使用 `--include-inventory`。内容完全
相同或直接嵌套执行只会成为审阅候选;名称相似、共同属于某个 profile,不足以证明两个
语义合同等价。健康审计不会自动删除或迁移 smoke。只有 daily 全量覆盖、没有定向
-profile 的条目表示 owner 待澄清,并不等于该测试没有价值。
+profile 的条目表示 owner 待澄清。
## Agent-Facing Output Budgets / Agent 输出预算
@@ -1211,7 +1213,7 @@ decision process below when changing a budget. Default agent-facing projection
changes remain subject to the existing owner review.
接口预算门会测量稳定命令场景,并比较 candidate 与 base,捕获意外膨胀、重复诊断
-以及重构后悄悄回到热路径的字段。预算保护有用且有界的决策,历史上限不是优化目标。
+以及重构后悄悄回到热路径的字段。预算保护有用且有界的决策。
解释新增或删除的语义字段,预算调整按下述流程判断;默认 agent-facing 投影变化
仍遵循既有的 owner review。
@@ -1258,7 +1260,7 @@ metrics, headroom and platform limits; the 40,000 fixture above stays unchanged.
副本引用该 owner,不同 channel 的规则仍内联。这恢复了默认投影此前省略的规则;
`--include-detail vision` 仍返回完整内联 audit。原有 40,000 字符 fixture 预算不变,
同一负载修复前/后为 30,697/33,205 字符,详情为 56,401 字符。这是 JSON fixture
-测量,不代表 token 成本或模型行为证据。
+测量。
完整 CLI 输出是另一负载:原 36 Todo/12 run vision 场景为有损 45,313/完整
48,418 字符;保留全部决策义务并核对受影响模式后,46,000 展示上限调至 50,000。
@@ -1288,8 +1290,7 @@ local-private; the workflow adds no profiler service or receipt gate.
- **Locate the cost before selecting an abstraction.** Separate caller repeats,
output/context expansion, process/bridge/serialization cost, shared semantic
work, and backend IO/verification/contention. A display filter does not reduce
- upstream work; a short response or fast isolated query does not establish a
- faster recovery loop. Name the real consumer and measure its useful outcome.
+ upstream work; Name the real consumer and measure its useful outcome.
- **Share contracts, qualify implementations.** Put common selection, bounded
reads and observation reuse at the existing consumer/typed owner boundary.
Preserve completeness, current authority, receipt replay and lease/CAS checks.
@@ -1320,15 +1321,13 @@ TS RFC 管语义 owner 与跨语言成本,shared-authority RFC 管后端容量
沿用现有任务、PR 证据和验收记录,不增加审批、回执或无关里程碑前置条件。
- **先定位成本。** 区分重复调用、输出与上下文展开、进程与序列化、公共语义计算、
- 后端 IO/校验/竞争。输出过滤不减少上游计算;单次查询变快不等于恢复闭环变快。
+ 后端 IO/校验/竞争。输出过滤不减少上游计算;
- **共用合同,分别验证实现。** 选择、有界读取和观测复用归现有调用方或 typed owner;
保留完整性、当前权限、回执重放及 lease/CAS。缓存失效、索引和历史布局可以因后端
而异,不能在 Python 复制权威,也不强造统一缓存。受影响后端遵循上文真实路径验证。
- **迁移是待验证的原因。** 尽量控制操作、版本、数据与历史规模、配置、并发;按影响
- 区分冷/热读、多存储交替、写入与恢复。没有受控前后对照就披露不确定性;晋升成功
- 不证明长程延迟、容量和恢复等价。
-- **验证实际目标。** 检索用独立标注、歧义/无命中和语言边界验证;开发小样本不代表
- 生产精度或任务成功率。运行时优化保留原失败负载和语义/规模检查,预算按下节处理。
+ 区分冷/热读、多存储交替、写入与恢复。没有受控前后对照就披露不确定性;
+- **验证实际目标。** 检索用独立标注、歧义/无命中和语言边界验证;运行时优化保留原失败负载和语义/规模检查,预算按下节处理。
- **区分缓解与闭环。** 写明消除了所属瓶颈,还是只减轻调用方影响;剩余真实缺口复用
已有后续任务并指明验收。提示词缩短不算后端验证,修复 PR 数量不算默认切换就绪。
@@ -1409,8 +1408,7 @@ that input. Retain the original over-budget observation and add the complete
CLI combination plus an oversized-route negative case. Prompt text, capability
flags, the visible Goal's 4,000-character host limit, existing JSON/body fixture
ceilings, execution authority and frozen qualification results remain unchanged.
-This corrects diagnostic coverage; it is not an output reduction or a claim of
-model compliance, runtime recovery or lower cost.
+This corrects diagnostic coverage.
薄提示原 4,500 字符展示预算未覆盖完整能力与显式 CLI 路由的组合;同一公开夹具
保留 320 字符 scope、五项能力和完整指令时为 4,851。仅将该展示预算校准为
@@ -1454,7 +1452,7 @@ performance criteria, and does not qualify a model by itself.
真实模型组合门的同一组三个 noisy fixture 现保留完整的 56 个 capability 候选及其
正文。仅按上述实测把该合成 fixture 的 pretty-JSON UTF-8 字节预算从 40,000 调整到
90,000;原超限失败保留。新增候选丢失/正文缩短的零模型调用负例,原选择、人工门禁、
-结算、重复次数、对照及生产硬边界不变;本次预算修正不等于真实模型通过。
+结算、重复次数、对照及生产硬边界不变;
This allowance is not a target architecture. A source-level attribution at
`d4980a0e9aa8acf8b847e2fec73d29454c23690d` reproduces those three output sizes.
@@ -1483,7 +1481,7 @@ explicit required-read contract; this design does not weaken or rewrite it.
blocked、binding 正文分别为 28,767、19,168、19,168 字节。16 个 binding 是带正文的
Todo 形状,与生产 owner 的 capability/owner/blocked-ID binding 不同;两个执行
fixture 的 selected Todo 不在 runnable 集合,human gate 没有 selected Todo。
-这些是压力成本,不是生产规模估计。保留原 fixture/失败,另用真实 producer、非重复
+保留原 fixture/失败,另用真实 producer、非重复
要求、有意义备选项及末尾约束验证选择与后续工作;计入全部批读/恢复成本。新必读契约
合格前,当前完整上下文 preflight 保持生效,不能靠删候选或首屏变小宣称收益。
@@ -1599,8 +1597,7 @@ Retain complete work context, canonical provenance and command routes, and
calibrate only this emitted-text regression ceiling to 42,000 (1,299 characters
above the native observation). There is no measured output reduction. Line,
per-Todo/fixed growth, semantic comparison and all other ceilings remain active.
-The original failure and the pending new native qualification remain distinct;
-this calibration is neither a model-cost saving nor a frozen performance pass.
+The original failure and the pending new native qualification remain distinct.
原生 Windows 同轮 base/head 均为 40,701 字符,原 40,000 超限失败保留。
先保留配对度量,再仅将该展示回归上限校准到 42,000;不删当前工作、来源或命令,
@@ -1608,8 +1605,7 @@ this calibration is neither a model-cost saving nor a frozen performance pass.
冻结实验通过;修改后的原生验证仍需独立读回。
Classify the limit by its owning contract before deciding how to repair a
-failure. This applies to output size/structure and latency regression budgets;
-it does not grant execution quota, spending, or provider authority.
+failure. This applies to output size/structure and latency regression budgets.
The native installed-profile smoke exposed duplicate settlement instructions
inside the visible Goal body. On identical long installation routes and the
@@ -1625,7 +1621,7 @@ failure; the installed-profile smoke and semantic assertions qualify the repair.
4,000 字符宿主硬边界、完整路由、当前合同、事实证据、恢复与停止条件均不变。
先根据所属合同判断上限的性质,再选择修复方式。这适用于输出尺寸、结构和延迟
-回归预算,不授予执行配额、费用额度或 provider 权限。
+回归预算。
| Limit / 上限 | Decision boundary / 决策边界 |
| --- | --- |
@@ -1643,7 +1639,7 @@ transport saving or permission to exceed a host limit.
Heartbeat 的正文回归计量先归一化已选择的 runtime、registry 和 active-state
完整路径及其 shell 引用形式,再处理 Goal id、父路径等子串;未声明路径仍计入。
原始正文 `char_count`、JSON/Markdown 输出预算与原生 Goal 宿主的 4,000 字符
-传输检查各自保留。归一化元数据不代表传输节省,也不豁免宿主限制。
+传输检查各自保留。
1. **Measure the same contract.** Record base/head revisions, workload, metric
and measurement boundary. Compact JSON characters, UTF-8 bytes, nested keys,
@@ -1695,8 +1691,7 @@ complete authoring bounds and parsed semantic-closeout arguments with the
original admitted contract; recovery specializes the completed Task's boundary.
Spend and settled
recovery keep their 2,000-character ceilings. This preserves useful guidance;
-it is neither an output reduction nor a change to any external host limit or
-frozen performance criterion. Candidate measurements must still pass.
+Candidate measurements must still pass.
辅助 Monitor 的恢复夹具用缩进 JSON 测量完整的原始 writeback 步骤,File 与 SQLite
均使用固定宽度的临时路由。发布基线均为 8,642 字符,原 7,500 字符回归上限的失败
@@ -1704,15 +1699,13 @@ frozen performance criterion. Candidate measurements must still pass.
判断、原始身份和命令。删除这些义务或给这段小型恢复指令另加引用都会改变消费
合同,因此只将该回归上限校准为 9,336,保留原 694 字符余量,并与最初准入合同
逐字段比较完整 authoring 约束与解析后的 semantic-closeout 命令参数;恢复步骤保留
-已完成 Task 所需的具体结算边界。spend 和 settled 恢复仍受 2,000 字符上限约束。这不代表输出
-缩小,不改变外部宿主硬限制或冻结性能标准;候选版仍须重新测量并通过检查。
+已完成 Task 所需的具体结算边界。spend 和 settled 恢复仍受 2,000 字符上限约束。候选版仍须重新测量并通过检查。
Native progressive-context qualification found an existing default-output
budget failure: immutable base `fb331f45c` and candidate `edbd56b14` both emit
25,836 JSON characters for `quota_should_run/multi_agent` with the unchanged
18-Todo, 3-Agent, 12-run fixture. Recursive comparison differs only in observation
-timestamps and the rollout event id. This is neither an incremental native-off
-regression nor evidence of a saving. Preserve the previous 25,500-ceiling failure;
+timestamps and the rollout event id. Preserve the previous 25,500-ceiling failure.
calibrate this one regression allowance to 26,500 (664 characters of headroom)
without dropping fields. Markdown, line, semantic, bootstrap duplication,
per-Todo/fixed growth and all other surface ceilings remain unchanged. This
@@ -1722,7 +1715,7 @@ criterion. Native-on material and recovery savings need separate qualification.
原生渐进上下文资格检查发现已有默认输出超限:不可变 base `fb331f45c` 与 candidate
`edbd56b14` 在相同 18 个 Todo、3 个 Agent、12 条运行记录夹具上,
`quota_should_run/multi_agent` 都为 25,836 JSON 字符;递归对比只有观察时间和
-rollout event id 不同。这不是 native-off 新增回归,也不是节省证据。保留旧 25,500
+rollout event id 不同。保留旧 25,500
阈值失败,只将这一回归预算校准为 26,500,留 664 字符余量,不删除字段。Markdown、
行数、语义、bootstrap 重复、每 Todo/固定增长及其他 surface 阈值不变;宿主硬限制、
授权执行配额和冻结实验标准均不变。Native-on 材料和恢复收益须单独验证。
@@ -1816,8 +1809,7 @@ Linux crowded/multi-Agent Turn envelopes measure 10,766 / 9,391 UTF-8 bytes;
plain envelope, transaction detail and multi-subagent measure
8,544 / 8,539 / 9,312. They still report `within_budget=false` and
`turn_envelope_budget_exceeded`; small Turn and blocking-user-gate remain
-within at 8,057 / 6,045. These warnings are not a green performance SLO or
-admission authority. This calibration grants no execution quota, spending or
+within at 8,057 / 6,045. This calibration grants no execution quota, spending or
provider permission and does not rewrite frozen experiment/promotion results.
本轮固定真实 main/候选和同一负载,逐条保留当前任务、读取时序、新鲜度、恢复、
@@ -1834,9 +1826,8 @@ provider permission and does not rewrite frozen experiment/promotion results.
需要调用方迁移和语义等价验证。详情优先使用有界摘要和可达冷路径。不能删身份、
完整性、安全或结算语义,不能只为过线缩字段名,也不为微小收益制造引用框架。
agent 读取的文字也是决策语义:逐条核对执行者、触发、时序、义务强度、证据来源、
- 范围限定、继续和停止条件。“继续前先 replan”不等于“replan”,“关联证据的路径”
- 不等于“路径”,“合理的范围内下一步”不等于“范围内工作”。字段、命令、枚举和
- 合法结果未变,不能证明指令等价。不能为字符上限损害有用语义;未证明无损压缩时,
+ 范围限定、继续和停止条件。字段、命令、枚举和
+ 合法结果未变。不能为字符上限损害有用语义;未证明无损压缩时,
优先基于证据调整回归预算。真实硬上限需要明确的无损调用方设计和读回,不能默删义务。
3. **选择并披露取舍。** 比较压缩、保持上限、合理扩容,也可组合使用。扩容需说明
保留信息的价值与成本、新旧上限、实测余量和预期波动或规模,不规定统一余量比例。
@@ -1901,6 +1892,12 @@ an accepted goal/contract, not a compression target. Instruction readback proves
what was delivered, not actual model comprehension or adoption. The result
checker enforces evidence structure and contradictions, not semantic truth.
+For installed skill prose, also inspect readiness consumers such as
+`doctor.installed_skill_summary`. Validate shipped skills in an external skill
+root and a copy missing a concrete permission requirement. The platform-neutral
+cases in `tests/test_skill_delivery_parity.py` cover this boundary even when
+native installer tests skip on the current host.
+
PR-review 的 `semantic_alignment` 通过既有 `validation_matrix` 和
`observable_semantics` 使用这些证据,不增加独立预算回执或审批门。结果校验器检查
证据结构和结论一致性;测量是否可信、取舍是否合理仍由评审判断。
@@ -1909,6 +1906,11 @@ PR-review 的 `semantic_alignment` 通过既有 `validation_matrix` 和
压缩指标不能授权。指令读回只证明交付了什么,不证明模型理解或采用;校验器检查
证据结构和矛盾,不自动判断语义真假。
+修改已安装技能文案时,还应检查 `doctor.installed_skill_summary` 等 readiness
+消费者。用外部技能目录中的发布技能,以及缺少具体权限要求的副本验证该边界。
+`tests/test_skill_delivery_parity.py` 的跨平台用例在原生安装测试因宿主不同而跳过时
+仍可执行。
+
## Decision Replay And Issue #2191 / 决策回放与 #2191
Issue #2191 is the reference pattern for a cross-layer control-plane
@@ -2111,14 +2113,13 @@ projected bound refresh and spend, and pass durable checkpoint, one-spend and
next-Turn readback. Readback must clear the original missing-baseline obligation;
a legitimate new successor requirement is allowed. Source alignment includes trigger kinds, accepted outcomes
and qualification scope; a successful ordinary `typed_progress_repeat` refresh
-cannot qualify this journey. The narrow semantic-action gate remains useful
-but does not prove full closeout. Run this focused journey with
+cannot qualify this journey. Run this focused journey with
`uv run --extra test python scripts/qualify-doubao-replan-semantic-action-live.py --required-vision --qualification-id `.
The complete required-vision journey has a 40-call bound; the narrow
single-semantic-action qualifier retains seven. The increased budget covers
evidence discovery, JSON authoring, refresh, settlement and bounded recovery,
including multiple field-validation corrections before a final spend;
-it does not authorize more effects or weaken the checkpoint/readback oracle.
+
Each receipt records `tool_call_limit` beside actual usage. Earlier seven- and sixteen-call
failures remain failures; the revised budget defines a new qualification, not
a retrospective pass. Limit exhaustion after refresh but before spend still
@@ -2156,8 +2157,7 @@ original Turn. Additional recovery reads consume the ordinary budget; they
grant no extra calls. The model must reassess the changed facts and author a
new decision before retrying. Draft authoring requires the same OS isolation
prerequisite as the full journey. Other actors retain their
-existing host and call limits. Earlier bounded-grammar and missing-decision failures remain failed
-qualifications and are not evidence of core semantic rejection.
+existing host and call limits.
The other turn cases remain
bounded packet-interpretation checks. Nine core-contract scenarios cover
onboarding, agent identity and goal selection, selected todo, peer identity
@@ -2246,8 +2246,7 @@ executable work 属于预期状态,不能误判为 projection gap。
Goal lifecycle on a disposable ledger project with two dependent Todos. It
reuses the shipped native Goal transport and current prompt, then checks an
independent acceptance oracle, completed Todos, unique bound spends, durable
-writeback readback, and terminal no-follow-up quota. This is not a benchmark
-score or evidence of universal model reliability.
+writeback readback, and terminal no-follow-up quota.
The Codex release arm requests the shipped bootstrap, not an injected private
work recipe. Deterministic regressions execute the saved CLI loader, change its
@@ -2287,8 +2286,7 @@ deadline is 1,200 seconds; this is a wall-clock ceiling, not a token budget.
但保留 `skipped` 标记;真实执行后失败不能冒充环境跳过。使用操作者显式选择的 API
模型、地址与密钥,不导入日常 Codex 配置、登录或会话,不修改活跃 Goal/automation。
任务、registry、runtime 与 Git worktree
-在一次性目录内;沙箱允许该目录及本地 TS worker 所需的网络能力,
-这不是网络隔离,任务不授权外部操作。回归脚本不采集或上传原始对话/工具日志,
+在一次性目录内;沙箱允许该目录及本地 TS worker 所需的网络能力。回归脚本不采集或上传原始对话/工具日志,
公开结果仅包含状态、计数和错误类别;Codex 会话仅留在一次性隔离目录内。
两个 runner 均从允许列表创建环境并隔离 HOME、配置和缓存;不透传其他 token、
认证 socket、shell 启动变量或原始 ARK_API_KEY。Codex 工具 shell 从空环境注入必要
@@ -2310,15 +2308,13 @@ decisions remain outside model input. All attempts must pass; no answer
correction or retry-until-pass is used. Ordinary pytest only checks the probe
and negative oracles with scripted responses, without provider calls.
-This is a synthetic decision-level probe using current generated prompts,
-not proof of tool execution, host scheduling, upgrade delivery or full-Goal
-completion. Keep the Codex/Claude live Goal arms and real CLI/MCP/SQLite tests
+This is a synthetic decision-level probe using current generated prompts. Keep the Codex/Claude live Goal arms and real CLI/MCP/SQLite tests
as separate evidence. Only hashes and pass/fail receipts are emitted, not raw
prompts/responses. Model transport failures fail qualification rather than
becoming environment skips.
仅发布前显式执行,普通 CI 不调用模型。检查静默不等于空转、等待不能擅自执行、
-vision replan 未关闭时不能提前结束 Goal;这不是完整 Claude/Codex 行为验收的替代。
+vision replan 未关闭时不能提前结束 Goal;
```bash
# No provider call by default. Explicit release opt-in uses ARK_API_KEY from the environment.
@@ -2354,7 +2350,7 @@ Before calling a changed host surface release-qualified, distinguish:
普通 CI 只跑确定性规则、真实 CLI/MCP 和故障注入;模型执行仍仅 release 前显式启用。
环境缺失可 skip 且退出成功,但最终版本没有完整的真实 host 结果时,不得写成
-“产品级发布验证通过”。单次成功也不是模型可靠性或长程调度 soak 的证明。
+“产品级发布验证通过”。
The real delivery regression covers ordinary Todo acceptance before internal
writeback/spend, existing-successor linking, and receipt-backed terminal closure.
@@ -2416,8 +2412,7 @@ decision basis. Judge the returned basis, then submit `agent_vision=...` or
replaced receipt requires another read and a new judgment; a lost response
requires the exact same receipt and decision, without reading again.
It uses the original host Turn and the same writeback command constructor,
-delegating to the existing typed checkpoint recovery. It neither repeats Todo
-completion nor spends again. Exact replay is idempotent; a conflicting committed
+delegating to the existing typed checkpoint recovery. Exact replay is idempotent; a conflicting committed
decision or a later superseding vision is rejected. It does not change Next
Action or erase other work, gates, or permissions. A genuinely new replan follows
the current interaction contract under a fresh admitted binding, not an edit to
@@ -2438,7 +2433,7 @@ MCP 可随完成操作携带 vision 判断,也可用 `review_task_vision` 在
复用 TS 的既有恢复规则,不新增结算引擎、不重扣额度;已提交的判断不能偷偷改写。
格式和预算预检在 Todo 完成前拒绝非法输入;若旧宿主已部分完成,则修正未提交的
vision 并重试原 `complete_task`,不能用仅补 checkpoint 的操作替代未完成结算。
-“checkpoint 满足”不等于“Goal 完成”,`vision_closed` 只结束阶段,真实缺口仍须规划。
+
外层任务只描述业务验收,LoopX 协议由宿主内层指令和工具承接。
## Exact Release Commit Gate / 精确发布 Commit 门
diff --git a/docs/guides/agent-upgrade.md b/docs/guides/agent-upgrade.md
index 21f021d897..f4fce8f6b8 100644
--- a/docs/guides/agent-upgrade.md
+++ b/docs/guides/agent-upgrade.md
@@ -46,8 +46,7 @@ If an upgrade primitive fails, preserve the source and name that specific gap.
## Reuse the owner for the observed state
Inspect the actual installation's `--help` before executing commands. These
-operations have different owners; a successful package update does not prove
-that existing Goal data have been upgraded.
+operations have different owners.
| Observed state | Existing entry | Required readback |
| --- | --- | --- |
@@ -56,7 +55,7 @@ that existing Goal data have been upgraded.
| Existing Goal still uses Markdown authority | `coordination-shadow inspect-source`, `prepare-import`, `apply-import` | Full source records and settled history imported into the reviewed provider; original paths remain. Recover the same import with `recover-import`. |
| Canonical Goal retains historical `legacy` policy | `handoff-mode plan-migration`, `handoff-mode migrate` | Verified backup, preserved assignments and an explicit supported policy. Recover the same plan after a lost response. |
-An expired lease is not proof that its writer stopped. `--writers-stopped`
+`--writers-stopped`
attests a fact already established through the owning Host; it does not stop
one. An already current canonical Goal needs no import. Setting new-Goal
defaults does not upgrade existing Goals. Storage and ownership policy remain
diff --git a/docs/guides/codex-app-autonomous-goal-experience.md b/docs/guides/codex-app-autonomous-goal-experience.md
index 7231463a2a..6bc4019628 100644
--- a/docs/guides/codex-app-autonomous-goal-experience.md
+++ b/docs/guides/codex-app-autonomous-goal-experience.md
@@ -12,7 +12,7 @@ $loopx 任务
→ Dashboard 展示进度、等待和完成状态
```
-这不是让一个模型会话无限运行。每次 Heartbeat 都先读取当前 LoopX
+每次 Heartbeat 都先读取当前 LoopX
状态;只有配额、Todo、能力和 Gate 都允许时,Codex Agent 才会执行一个
有边界的工作片段。
@@ -28,7 +28,7 @@ $loopx 任务
## 开始前
-适用范围是 **Codex App**,不是 Codex CLI、Codex App over SSH 或其他宿主。
+适用范围是 **Codex App**。
这些宿主的循环驱动不同;本路径依赖 Codex App 提供的
`automation_update`。
@@ -93,8 +93,7 @@ $loopx --fine-grained 在当前试验仓库中完成一份 LoopX 自动续跑体
- 此时 **不应** 有自动化已启动或业务文件已修改的结论。
`$loopx` 是 Codex 中的显式 LoopX skill 入口。只运行
-`loopx start-goal --guided` 同样会得到启动方案,但它本身只是引导预览,
-不等于 Heartbeat 已安装。
+`loopx start-goal --guided` 同样会得到启动方案,但它本身只是引导预览。
## 第 3 步:确认受控启动并安装 Heartbeat
@@ -116,8 +115,7 @@ Heartbeat 后,回读 Goal、Agent、自动化绑定和 quota should-run,不
4. Codex App 用 `automation_update` 保存其中的
`LoopX managed heartbeat bootstrap v2` `task_body`;
5. 新 Heartbeat 建议从 3 分钟开始,并回读其 Goal、Agent、任务绑定和调度;
-6. 后续唤醒加载当前 thin contract,而不是把一份旧的 thin、compact 或 full
- 执行正文永久保存为自动化提示词。
+6. 后续唤醒加载当前 thin contract。
这一步才是“启动 Codex Agent 自动续跑”的边界。若会话没有
`automation_update`,正确结果是一个可粘贴的宿主激活 Gate;不要手改数据库、
@@ -148,7 +146,7 @@ loopx quota should-run \
- `quota should-run` 返回当前机器契约,包括 `should_run`、`waiting_on`、
下一条工作通道和 `scheduler_hint`;
- `should_run=true` 表示下一次 Heartbeat 可以尝试有边界的工作;
-- `should_run=false` 不代表故障。先依据 `waiting_on`、Gate、缺失能力或配额
+先依据 `waiting_on`、Gate、缺失能力或配额
原因处理,不要为了制造活动而绕过限制。
这两个命令用于观察。真正的自动 Turn 由已安装的 Codex App Heartbeat 进入,
@@ -171,8 +169,7 @@ loopx dashboard --global-registry --goal-id "$GOAL_ID"
- Tasks 展示“待确认”“待执行 / 进行中”“定时与持续”和“已完成”四类工作;
- Goal 详情和 Run 抽屉展示公开安全的状态、进度、证据、产出和下一步。
-Dashboard 读取 LoopX 状态并轮询刷新。它不是 Heartbeat 的执行器:关闭浏览器
-不会停止已安装的 Codex App 自动化,打开浏览器也不会额外触发一次工作。
+Dashboard 读取 LoopX 状态并轮询刷新。
## 第 6 步:观察首次自动唤醒
diff --git a/docs/guides/codex-multi-app-best-practices.zh-CN.md b/docs/guides/codex-multi-app-best-practices.zh-CN.md
index ab0a347734..b974b0adc0 100644
--- a/docs/guides/codex-multi-app-best-practices.zh-CN.md
+++ b/docs/guides/codex-multi-app-best-practices.zh-CN.md
@@ -48,11 +48,11 @@ GPT 实例除 `CODEX_HOME=$HOME/.codex-gpt` 与 `--user-data-dir=.../Codex GPT`
- 克隆发 Apple Events 报 `Sender process is not authenticated`(错误 `-10000`),App 每 ~0.4 秒重试一次、每次泄漏一个 `SkyComputerUseService` 子进程,几分钟内打爆进程表。
- 症状:zombie 上千、load average 400+、CLI / 测试全部 `fork: Resource temporarily unavailable`。
-结论:**该授权无法通过系统设置或 TCC 授权解决**(不是权限 checkbox,是发送者签名身份校验);需要 Computer Use 时请用官方签名实例。
+需要 Computer Use 时请用官方签名实例。
### 2. 不要用 `launchctl submit` 做「延迟重启」
-`launchctl submit -l -- ...` 会注册 **keepalive 常驻任务**:进程退出后 launchd 反复拉起(实测几十到上百次),而不是一次性的延迟执行。
+`launchctl submit -l -- ...` 会注册 **keepalive 常驻任务**:进程退出后 launchd 反复拉起(实测几十到上百次)。
正确做法:
@@ -76,7 +76,7 @@ LoopX agent 在检测到 zombie 积压(父进程不响应回收)时会强制
App 启动时会重写 `config.toml` 并回填它管理的键(例如 Computer Use 的 `notify` hook、`SKY_CUA_SERVICE_PATH`)。因此:
-- 想禁用一个 App 级能力,优先从 App 管理方(能力目录 / 插件开关 / 服务路径)下手,而不是只删 config 行。
+- 想禁用一个 App 级能力,优先从 App 管理方(能力目录 / 插件开关 / 服务路径)下手。
- 修改 config 前先备份,并在 App 重启后复查是否被回写。
## 验证清单
@@ -93,11 +93,11 @@ ps -Ao state= | awk 'substr($1,1,1)=="Z"{z++} END{print z+0}' # zombie 回到
- LoopX agent(loopx-meta 等心跳)在 DS home 运行;GPT home 用于官方模型 + 开发机。
- provider 切换(DeepSeek / 方舟 / OpenCode Go)只作用于 DS home,不碰 GPT home。
-- 本 runbook 属于操作知识,不是 LoopX capability;只有当其中的切换机制被抽象成可安装、可测试的 adapter 时,才适合升级到 `docs/integrations/`。
+- 本 runbook 属于操作知识;只有当其中的切换机制被抽象成可安装、可测试的 adapter 时,才适合升级到 `docs/integrations/`。
## 相关工具生态:CC Switch / AgentSwap / CLIProxyAPI(CPA)
-多 App / 多 Provider 管理不是单一工具能覆盖的。下面按「配置层 → 运行时韧性层 → 协议翻译层」三层拆解,明确边界与风险。
+下面按「配置层 → 运行时韧性层 → 协议翻译层」三层拆解,明确边界与风险。
### 配置层:CC Switch(farion1231/cc-switch)
diff --git a/docs/guides/context-delivery.md b/docs/guides/context-delivery.md
index ce225476b4..be1c316e9d 100644
--- a/docs/guides/context-delivery.md
+++ b/docs/guides/context-delivery.md
@@ -12,8 +12,7 @@ benchmark heartbeat callers when no machine preference is saved. Saved or explic
off disables it; ordinary CLI, other hosts and unsupported platforms inherit full
delivery.
-A saved setting is not proof that a host is ready,
-that a particular response used a delta, or that the model understood it. The
+The
complete C1 caller migration and long-horizon cost/outcome qualification remain
open. Broad default adoption and old-path retirement need the evidence below.
@@ -65,7 +64,6 @@ The shared implementation starts at
uses the [exact codec](../../loopx/control_plane/quota/context_delivery.ts), and
leaves native files, locking and lifecycle IO to the
[Codex adapter](../../loopx/control_plane/turn_driver/codex_context.py).
-One shared preparation call does not prove that every final caller has migrated.
### Keep three meanings of reuse separate
@@ -94,13 +92,12 @@ complete `vision_authoring` in a durable-writeback step. The existing TypeScript
Turn owner chooses an exact owner and resolves it for ordinary and captured
readers. Dangling references, reference chains, conflicting inline values and
references to another kind of step are rejected. A small or different value
-stays inline. Sharing neither changes the original settlement identity nor
-establishes cross-Turn retention or net cost savings.
+stays inline.
Semantic summarization is another operation: it can change wording or meaning.
The exact codec is not a semantic summary. A controller-authored brief remains
a separate proposed workflow with its own retained-requirement and outcome
-tests. Neither shorter wording nor a provider cache hit validates that proposal.
+tests.
Explicit confirmed-input clients also have a retained-input contract. Do not
replace that contract with native Codex's saved-file assumption, or require
@@ -126,8 +123,7 @@ supporting evidence when the decision needs it. A broader replan or whole-Goal
acceptance needs a correspondingly broader reading scope.
The native saved-file basis can inherit unchanged fields, including controls.
-An omission from a delta is not evidence that a constraint disappeared, or that
-the model has retained it. Retrieve necessary current facts when uncertain.
+Retrieve necessary current facts when uncertain.
Default-off and signed-envelope callers retain their own read contracts; the
progressive native example does not relax them.
@@ -139,8 +135,7 @@ states and new controls invalidate their containing criterion and remain visible
An exact unchanged criterion needs no metadata split. Splitting a container adds addresses
and recovery guidance, so the reader keeps the complete presentation when the
split would not save enough bytes. This tool-delivery assumption is separate
-from file deltas and provider caching; it does not prove model retention or
-lower total cost. Partial reads and lost continuity cannot qualify this reuse.
+from file deltas and provider caching; Partial reads and lost continuity cannot qualify this reuse.
Explicit same-capture selections always recover the complete current value.
An unchanged Goal narrative can also be referenced after an exact read of the
@@ -210,8 +205,7 @@ There is no separate Goal configuration to duplicate:
- **No explicit choice:** uses the saved machine preference when present.
- **No machine preference:** supported native Codex callers default on; other
callers keep full delivery.
-- **Worker `LOOPX_CONTEXT_DELIVERY=off`:** overrides inheritance; environment on
- alone does not enable native delivery.
+- **Worker `LOOPX_CONTEXT_DELIVERY=off`:** overrides inheritance.
- **Turn the App switch off:** saves off through the same transaction; it does
not reverse task effects or rewrite old captures.
@@ -263,8 +257,7 @@ switching:
Captures and journals may contain private tasks and evidence. Native storage
uses a private runtime directory and per-session journals, with restrictive
permissions and unsafe-path rejection. Do not attach raw captures, local paths
-or journals to a public issue. Share a permitted redacted reproducer. Turning
-off presentation is not a retention-policy change or a request to delete logs.
+or journals to a public issue. Share a permitted redacted reproducer.
## Qualify default adoption and retirement
@@ -364,5 +357,4 @@ because the new path exists.
The [roadmap](../architecture/rfcs/loopx-overall-roadmap-v0.md#unified-contract-and-controllerexecutor-delivery)
and RFC retain the owners and remaining C1/C2/C9 work. Documentation can ship
-before model experiments; neither a merged guide nor a smaller packet completes
-those runtime, adoption or benefit requirements.
+before model experiments.
diff --git a/docs/guides/context-delivery.zh-CN.md b/docs/guides/context-delivery.zh-CN.md
index 07b1151127..9b28806a9b 100644
--- a/docs/guides/context-delivery.zh-CN.md
+++ b/docs/guides/context-delivery.zh-CN.md
@@ -10,7 +10,7 @@
默认开启原生路径。保存 off 或显式关闭可禁用;普通 CLI、其他宿主与不支持的平台
继承完整交付。
-保存开关不证明宿主已就绪、某次输入用了 delta,或模型已理解材料。完整 C1 消费链迁移和
+完整 C1 消费链迁移和
长程成果/成本资格仍未完成;广泛默认化和旧路径退役须取得下文证据。
- 理解一次工作,从[四种场景](#一项任务四种场景)开始。
@@ -52,7 +52,7 @@ flowchart TD
[`prepareProgressiveContextDelivery`](../../loopx/control_plane/quota/progressive_context.ts)
开始,使用[精确 codec](../../loopx/control_plane/quota/context_delivery.ts),文件、锁和原生
生命周期 IO 留给 [Codex adapter](../../loopx/control_plane/turn_driver/codex_context.py)。
-一次共享准备调用,不证明所有最终消费者已经迁移。
+一次共享准备调用。
### 三种复用分别看
@@ -88,7 +88,7 @@ provider cache 命中都不能替它通过。
## 一项任务,四种场景
用一个合成任务贯穿:**增加 UTF-8 导出,保留原有格式,绝不覆盖已有目标文件**。
-下列检查和证据是说明例子,不是 benchmark 结果。
+下列检查和证据是说明例子。
| 场景 | Agent 看到或取得什么 | 仍须完成什么 |
| --- | --- | --- |
@@ -135,7 +135,7 @@ Full 表示完整保存视图可用,不要求判断任何问题前先遍历所
等价于 `--list --select /interaction_contract --list-depth 2`。重复的 `--list POINTER`
与 `--select POINTER` 会合并到同一个索引。列出根节点用不带 selector 的 `--list`
或 `--list ''`;`/` 仍表示空名称属性。
-- 未完成的选择沿返回的字节 cursor 继续。EOF 只覆盖该选择,不代表读了其他字段。
+- 未完成的选择沿返回的字节 cursor 继续。EOF 只覆盖该选择。
- 同时控制 reader 页与宿主工具的合计输出预算。合法 JSON、落盘日志和 EOF 都不能
补上被宿主截掉的字节;缩小批次,从同一 capture 补缺失范围。
- 基线缺失、不支持的 delta 或绑定无效时,恢复当前完整 capture;不要先取旧包给
@@ -154,7 +154,7 @@ Full 表示完整保存视图可用,不要求判断任何问题前先遍历所
App 中使用 **Settings → This machine → Capabilities → Differential context → Codex**。
已有的 revision 锁定 preview/apply/readback 事务拥有这项设置;它不初始化当前原生
-session,也不证明生命周期 hook 已安装。只读设置页不能保存。
+session。只读设置页不能保存。
CLI 使用同一个 `context_delivery` 机器 namespace,详见
[机器级默认](../reference/required-work-context.md#机器级默认),无需再建 Goal 配置。
@@ -169,8 +169,7 @@ CLI 使用同一个 `context_delivery` 机器 namespace,详见
生命周期上下文应一致。冷启动、丢失后或完整交付更便宜时,full 完全合法;保存 on
与看到 full 本身,都不能判断差分是否正确复用。
-解析原始 `should_run` 或结算事实的机器消费者,其内部调用仍须请求 raw 输出。原生
-展示封装不是原始权威响应;封装中缺少 `should_run` 不表示拒绝准入。不能通过改机器
+解析原始 `should_run` 或结算事实的机器消费者,其内部调用仍须请求 raw 输出。封装中缺少 `should_run` 不表示拒绝准入。不能通过改机器
设置改变某个实验冻结的模式、来源或时钟;trial 保留原显式配置与权限。
### 回退到另一个运行时
@@ -210,8 +209,8 @@ journal,限制权限并拒绝不安全路径。不要把原始 capture、本
未来扩大默认采用范围必须同时有**明确版本的 DeepSeek 模型与强模型**的可比效果、完整成本
证据。每个模型内部固定条件分别比较,不能合并结果掩盖某一个模型退步。本指南提供
-方案,不授予新实验权限,也不宣称任何一个模型系列已经通过。
-这些标准约束现有范围化默认的扩展;已交付的默认行为本身不证明双模型对照通过。
+方案。
+这些标准约束现有范围化默认的扩展;
### 最小判别研究
@@ -237,10 +236,9 @@ journal,限制权限并拒绝不安全路径。不要把原始 capture、本
选案例前先读现有 board,复用合格 run;缺失一格就保持未合格。预登记各处理组的基线
run 绑定及重复/顺序策略,再由获授权 runner 执行不变的任务输入与 evaluator。
每格返回 source/host 绑定、实际最终输入与恢复补读、原生任务成果、完整成本及
-integrity 状态,保留失败或截尾尝试。Board 表达 run 资格,本身不证明因果比较,也不
-授权启动。
+integrity 状态,保留失败或截尾尝试。Board 表达 run 资格。
-上述原生 adapter 范围是 Codex,**不证明 DeepSeek 宿主已支持**。DeepSeek 对照需要
+上述原生 adapter 范围是 Codex。DeepSeek 对照需要
获授权且已资格化、能经过同一语义管线的宿主。不支持保持缺口,不能替换成 Codex
结果或修改在跑研究。
diff --git a/docs/guides/custom-agent-runner-integration.md b/docs/guides/custom-agent-runner-integration.md
index 5f046fe9d9..895da2d014 100644
--- a/docs/guides/custom-agent-runner-integration.md
+++ b/docs/guides/custom-agent-runner-integration.md
@@ -74,16 +74,14 @@ loopx agent-onboard \
The packet returns the current doctor/install command, bootstrap command pack,
quota guard, and recheck command. Declare only capabilities the current host
-actually has. `--available-capability` reports observed execution ability; it
-does not grant permission or satisfy a user gate.
+actually has. `--available-capability` reports observed execution ability.
For `other-agent`, doctor intentionally does not inspect `~/.codex/skills`.
CLI health and workflow delivery are separate checks. The custom host must
deliver `loopx-project`, `loopx-pr-program`, `loopx-pr-review`,
`loopx-doc-registry`, `loopx-benchmark`, and `loopx-self-repair` from the same
LoopX revision through its own skill manifest or equivalent prompt injection.
-`loopx-benchmark` is task-triggered for LoopX-managed experiments; loading it
-does not grant benchmark runner or private-evidence authority. When the current goal enables
+`loopx-benchmark` is task-triggered for LoopX-managed experiments; When the current goal enables
`change_quality_qualification`, the onboarding packet also lists
`loopx-change-quality` as an active project skill; deliver that workflow or its
equivalent self-contained prepare-packet instructions. Then read back the
@@ -128,7 +126,7 @@ Then follow this loop:
boundary, compact evidence references, and writeback contract. Let it
dynamically plan the bounded action.
5. **Validate:** Read the real repository, test, CI, service, or Provider
- result. The Agent's completion claim is not proof.
+ result.
6. **Write back:** Complete, update, block, defer, or add a successor todo;
record compact evidence; then run `refresh-state`.
7. **Account:** Spend quota only after validated durable writeback. A failed
diff --git a/docs/guides/custom-agent-runner-integration.zh-CN.md b/docs/guides/custom-agent-runner-integration.zh-CN.md
index b930fc6d05..1d8289d02b 100644
--- a/docs/guides/custom-agent-runner-integration.zh-CN.md
+++ b/docs/guides/custom-agent-runner-integration.zh-CN.md
@@ -79,7 +79,7 @@ packet 会返回当前 doctor/install、bootstrap command pack、quota guard 和
`loopx-change-quality` 列为 active project skill;host 需要交付该 workflow,
或注入等价的自包含 prepare packet 指令。随后 readback integration mode、
loaded skill ids 和 source revision。不要假设未知 host 采用 Codex、Claude 或
-OpenCode 的目录布局。加载质量 skill 不代表启用,是否生效由当前 goal policy 决定。
+OpenCode 的目录布局。
如果 host 没有 skill 系统,就注入等价的 `SKILL.md` 指令,并保留一段短
re-entry instruction,要求 Agent:
@@ -116,7 +116,7 @@ loopx --format json \
除非已有明确 assignment。
4. **执行:** 只把当前 objective、selected todo、boundary、紧凑 evidence ref 和 writeback
contract 交给 Agent,让它动态规划本轮有界动作。
-5. **验证:** 读取真实 repository、测试、CI、服务或 Provider 结果。Agent 自称完成不是 proof。
+5. **验证:** 读取真实 repository、测试、CI、服务或 Provider 结果。
6. **写回:** complete、update、block、defer 或新增 successor todo,记录紧凑 evidence,
再运行 `refresh-state`。
7. **计费:** 只有验证通过并完成持久 writeback 后才 spend。validator 失败、cadence 更新、
@@ -156,7 +156,7 @@ cat ./guard-001/decision.json
其他 CLI 结果可以由 runner 直接把 stdout 保存到新的私有文件,同时保留 stderr 和
原始退出码。不要让管道或后续读文件操作掩盖失败,也不要仅为补存输出而重跑写操作。
尤其是 spend,必须按当前结算合同只执行一次。原始结果不进入公开产物;宿主生命周期
-回执仍单独保留。本例不会自动给现有 worker 开启捕获,也不证明模型效率已经改善。
+回执仍单独保留。本例不会自动给现有 worker 开启捕获。
## 选择合适的执行边界
@@ -173,7 +173,7 @@ LoopX Turn: 决策 -> 执行 -> 验证 -> 提交
| **LoopX Turn adapter(experimental)** | 希望由一条 typed command 完成 plan、调用一次 bounded host、验证和 commit | 使用 `turn run-once` 的内置 `codex-cli` adapter,或薄 `generic-cli` adapter |
直接编排 CLI 是当前兼容基线;LoopX Turn 是 runner 内部 experimental 的
-transaction boundary,不是常驻 scheduler 或多 Agent 调度中枢。每个 tick 只能有一个
+transaction boundary。每个 tick 只能有一个
decide、validate、writeback 和 spend owner;同一逻辑动作不能同时跑手工闭环与
`turn run-once`。
diff --git a/docs/guides/first-bugfix-loop.md b/docs/guides/first-bugfix-loop.md
index 305113a0cb..19a32329aa 100644
--- a/docs/guides/first-bugfix-loop.md
+++ b/docs/guides/first-bugfix-loop.md
@@ -180,7 +180,7 @@ the correct remote and target branch, push the work branch only within your
authorization, and create a PR with the actual cause, behavior change and test
results. Read back its head and checks. A local commit, a pushed branch, an open
PR and a merged PR are different outcomes; CI or review feedback may require
-another repair. Creation of a PR does not authorize merging it.
+another repair.
@@ -205,7 +205,7 @@ and unresolved tests honestly. Keep merge and release for my explicit decision.
Here, “infinite loop” means authorized work can continue or resume. Each repair
still has a finish line. Quiet monitoring should wait for a meaningful event
-or its scheduled check; a higher wake frequency does not prove useful progress.
+or its scheduled check.
Start with one module, a known test command, and a spending boundary you accept.
To pause, ask the agent to pause this LoopX goal and its corresponding driver,
@@ -263,8 +263,7 @@ The creator's [reported uses](https://x.com/huangruiteng/status/2118539848235803
include research supervision, PR review, product iteration and refactoring.
These are use cases, not a controlled performance comparison. If your current
Goal workflow already delivers what you need, keep it. LoopX adds state,
-validation and continuation work with their own costs; this small exercise
-does not establish a quality or efficiency advantage over native Goal.
+validation and continuation work with their own costs.
## Setup effort, ongoing cost, and limits
diff --git a/docs/guides/first-bugfix-loop.zh-CN.md b/docs/guides/first-bugfix-loop.zh-CN.md
index 9fad95c8d5..b8aaccb0ea 100644
--- a/docs/guides/first-bugfix-loop.zh-CN.md
+++ b/docs/guides/first-bugfix-loop.zh-CN.md
@@ -63,13 +63,12 @@ loopx doctor
- **Codex App:** 把复制出来的项目设为工作目录,在项目对话里发送下面的 `$loopx`
请求。App 使用 heartbeat automation 自动续跑。
- **Codex CLI:** 在练习项目目录运行 `codex`,在 Codex 内发送同一条 `$loopx`
- 请求,不是在 shell 中执行它。CLI 使用当前会话可见的原生 `/goal` 续跑。
+ 请求。CLI 使用当前会话可见的原生 `/goal` 续跑。
OpenAI 文档注明 Goals 从 Codex 0.128.0 开始提供,先确认当前版本有 `/goal`。
- **Claude Code:** 打开同一目录,把 `$loopx` 换成已安装的 `/loopx` 命令技能。
其他差异见[宿主选择表](newcomer-command-path.md#choose-the-loop-driver)。
-在 Codex 中,用 `$loopx` 或 `/skills` → `loopx` 显式调用技能。用户自定义的原生
-`/loopx` 不是这里的入口。LoopX 生成的入口关闭了隐式调用,单发普通任务文本不保证
+在 Codex 中,用 `$loopx` 或 `/skills` → `loopx` 显式调用技能。LoopX 生成的入口关闭了隐式调用,单发普通任务文本不保证
启动 LoopX。找不到技能时,核对当前 Codex 进程使用的安装位置,包括 `CODEX_HOME`;
修好安装后若仍不可见,再重启 Codex。
@@ -169,7 +168,7 @@ $loopx 持续检查 <我负责的模块或目录> 中可复现的 bug。先读
```
这里的“无限循环”,是允许有用且已授权的工作持续推进或恢复。每次修复仍有验收终点。
-没有新问题时,监控按事件或计划等待;唤醒频率更高,不代表取得了更多进展。
+没有新问题时,监控按事件或计划等待;
初次只选一个模块、一个明确的测试命令,以及自己接受的费用边界。
暂停时,让 Agent 暂停这个 LoopX 目标及其对应驱动,并读回两者的实际状态。
@@ -202,7 +201,7 @@ Goal、任务归属和待评审 PR,确认写入范围、测试命令、当前
例如,两个导入入口复制了同一套字段校验,可以评估提取共享校验函数,同时保留
各入口原有的默认值、合法输入和错误行为。前后对照要说明规则如何从两处维护变成
一处,测试仍覆盖两条真实入口及错误输入;若新抽象反而让调用更绕,就不值得采用。
-这是选题示例,不代表你的仓库已经存在该问题。英文完整示例见
+英文完整示例见
[长程编程任务指南](long-running-coding-agents.md#example-keep-improving-repository-quality)。
@@ -238,7 +237,7 @@ Agent 开始;增加宿主或 Agent 需要各自接入。要检查的是,留
作者[公开报告的用法](https://x.com/huangruiteng/status/2118539848235803121)包括研究看护、
PR 评审、产品迭代和持续重构。这些是使用场景,不是受控性能对照。如果现有 Goal
工作流已经能交付你需要的结果,可以继续沿用。LoopX 的状态维护、验证与续跑也有
-成本;这个小练习不能证明它比原生 Goal 效果更好或效率更高。
+成本;
## 准备成本、持续费用与适用范围
@@ -250,6 +249,5 @@ PR 评审、产品迭代和持续重构。这些是使用场景,不是受控
本教程不承诺固定价格或节省比例,继续采用 LoopX 的额度和调度,不另写 shell
`while true` 循环。
-示例从红到绿,只验证这份购物车逻辑;它不能证明宿主会无限无人值守地恢复,也不
-保证找到真实项目的所有 bug。进一步操作见[长程编程任务指南](long-running-coding-agents.md)。
+示例从红到绿,只验证这份购物车逻辑;进一步操作见[长程编程任务指南](long-running-coding-agents.md)。
Codex 原生 Goal 行为见 [OpenAI 官方指南](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)。
diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md
index 508bc81a3a..54cc0cbbdf 100644
--- a/docs/guides/getting-started.md
+++ b/docs/guides/getting-started.md
@@ -217,8 +217,7 @@ the previously published archive intact. No raw-file fallback is used.
Each database snapshot is transactionally consistent, including committed WAL
data. The complete archive is **not one simultaneous snapshot across databases,
registries, File journals, and project files**. Quiesce writers through the
-existing migration workflow before a coordinated cutover; a successful local
-backup does not grant restoration or promotion authority. Restore into an
+existing migration workflow before a coordinated cutover; Restore into an
isolated directory first, verify the archived SQLite hashes and complete Goal
history/receipts through `authority-archive`, and use the supported migration
route to preserve writes made after the backup. Do not unpack old bytes over an
diff --git a/docs/guides/installing-loopx.md b/docs/guides/installing-loopx.md
index e40caf0c07..50c35f7aa2 100644
--- a/docs/guides/installing-loopx.md
+++ b/docs/guides/installing-loopx.md
@@ -169,8 +169,7 @@ safe filesystem/lock diagnostic code, such as `mutation_lock_timeout`,
`io_is_directory`, or Windows `io_permission_denied` for an occupied locator
directory, instead of only an exit status. The message does not echo
locator paths, tokens or Node stack traces. Inspect the named local ownership
-or filesystem problem before retrying; the diagnostic neither removes a live
-owner's lock nor repairs a foreign locator. It does not identify every possible
+or filesystem problem before retrying; It does not identify every possible
startup crash: an exit without a typed envelope remains `runtime_exited_before_ready`.
中文:启动 locator 发布失败会返回既有文件系统/锁诊断码,不回显路径、token 或
@@ -279,8 +278,7 @@ wheel instead exposes an additive `package_fingerprint` in the existing
`loopx_runtime_identity_v1`: SHA-256 over its actual RECORD-owned LoopX package
files, including Python, TypeScript and frontend assets. Editable, unowned,
redirected or incomplete packages cannot claim this fingerprint. It distinguishes
-same-version artifacts for local service reuse; it does not certify a release,
-publisher or source commit. Both services capture their identity at startup, so
+same-version artifacts for local service reuse; Both services capture their identity at startup, so
an in-place upgrade cannot make an old process report the replacement's identity.
An unqualified install fails before the helper stops an existing service.
@@ -383,8 +381,7 @@ Both workflow and command installation reconcile managed duplicates between
The selected installation root wins only when a replacement exists; a command
facade cannot replace a rich workflow. Modified receipts, user-owned metadata,
extra files, sole copies, and skill symlinks are preserved and reported under
-`skill_reconciliation` or `codex_skill_reconciliation`. A custom Codex profile
-does not authorize cleaning another profile. The fixed installer permits
+`skill_reconciliation` or `codex_skill_reconciliation`. The fixed installer permits
`LOOPX_SKILL_DEDUPE_OTHER_ROOT=0` for intentionally separate host roots.
To inspect and repair command discovery for the current Codex profile:
@@ -444,7 +441,7 @@ global copies untouched and retains project connection, ownership, digest,
and containment checks. Missing or unknown source markers still fail closed.
See [Project Skill Delivery](../../loopx/capabilities/project_skill_delivery/README.md)
for lifecycle details. `loopx doctor` continues to require the complete default
-workflow set; a lone generated entry does not replace missing rich workflows.
+workflow set.
## Upgrade And Repair
@@ -567,9 +564,7 @@ loopx doctor
The first command is the package transaction; the remaining commands are the
LoopX activation and readback contract. Running only `pip install` can leave
-host material from the previous version active. Conversely, `loopx update
-apply` does not replace pip as the owner of dependency resolution, environment
-policy, package indexes, or uninstall.
+host material from the previous version active.
### Verify The Active Layers
diff --git a/docs/guides/kunluncode-adapter.zh-CN.md b/docs/guides/kunluncode-adapter.zh-CN.md
index 77a67e212c..51170cab21 100644
--- a/docs/guides/kunluncode-adapter.zh-CN.md
+++ b/docs/guides/kunluncode-adapter.zh-CN.md
@@ -35,7 +35,7 @@ KunlunCode 使用独立的 `.loopx/kunluncode.json` 绑定和注册身份。它
## 2. 三套命令空间:并不完全一致
-接入后同时存在三套不同的入口。名称相似不代表状态或生命周期相通:
+接入后同时存在三套不同的入口。
| 命令空间 | 例子 | 所有者 | 当前适配器如何使用 |
| --- | --- | --- | --- |
@@ -53,12 +53,12 @@ KunlunCode 使用独立的 `.loopx/kunluncode.json` 绑定和注册身份。它
```
它在 KunlunCode 自己的 session 中保存 persistent objective、continuation status 和 token
-budget。这个状态不是 LoopX registry 中的 goal。直接在 TUI 启动的 native Goal 不会完成
+budget。直接在 TUI 启动的 native Goal 不会完成
LoopX todo;只有 `loopx-kunluncode run` 创建并跟踪的 native Goal,才会在验收终态后做映射。
### `/goal-pro` 是原生 `/goal` 加独立完成验证
-从用户可见的目标语义看,`/goal-pro` 不是另一套目标生命周期。它沿用 `/goal` 的
+从用户可见的目标语义看。它沿用 `/goal` 的
persistent objective、`status`、`history`、`pause`、`resume`、`clear`、`edit` 和 token
budget;核心增量是严格的完成门禁:主 Agent 请求完成时,KunlunCode 会运行独立 verifier
sub-agent。只有 verifier 通过才会进入完成状态;验证失败或验证基础设施出错时,Goal 保持
@@ -80,7 +80,7 @@ KunlunCode 自己的 goal state,不是 LoopX goal 的“高级版”。
### 原生 Goal 由谁激活
-`/goal` 本身由 KunlunCode TUI 解析,不是模型能够输入给自己的普通文本命令。不过本机
+`/goal` 本身由 KunlunCode TUI 解析。不过本机
KunlunCode 还提供两条非 TUI 激活路径:
| 激活路径 | 调用者 | 约束 |
diff --git a/docs/guides/long-running-coding-agents.md b/docs/guides/long-running-coding-agents.md
index bf92332d6d..1ce1092944 100644
--- a/docs/guides/long-running-coding-agents.md
+++ b/docs/guides/long-running-coding-agents.md
@@ -108,8 +108,7 @@ is not available, and follow the [skill registration guide](getting-started.md#c
If one agent implements while another reviews, retain separate ownership and
return the review evidence to the shared task. The
[Claude implementation / Codex review example](../product/use-cases/cross-runtime/cross-runtime-impl-review-demo.md)
-shows the roles and acceptance boundary. Switching the executor does not grant
-it another agent's identity or the user's merge authority.
+shows the roles and acceptance boundary.
## DeepSeek Harness: choose the native plugin or SDK connector
@@ -161,7 +160,7 @@ input. Reject the abstraction if it makes the callers harder to understand.
This is an illustrative target, not a finding about your repository.
Keep each result in its original Goal and PR so review feedback can change the
-next decision. A passing suite alone does not establish improved maintainability;
+next decision.
explain the structural benefit and its costs. If later work requires a pending
review, use the existing wait rather than starting overlapping changes.
The [Chinese walkthrough](first-bugfix-loop.zh-CN.md#continuous-refactoring)
@@ -184,8 +183,7 @@ goal. Ask me to select the prior agent identity if a takeover is needed.
Continue only the authorized task and verify the result before writing back.
```
-A transcript saying “done” is not a substitute for current tests, review or
-accepted evidence. See [long-task operations](../operations/long-task-cadence-policy.md)
+See [long-task operations](../operations/long-task-cadence-policy.md)
for waiting, budgets and continuation.
If work appears stuck, distinguish a host that is unavailable from a task that
@@ -211,9 +209,8 @@ existing Goal rather than repeat setup.
Agent turns consume the host's model allowance and the project's test, build
or external-service resources. Recurring checks add wakeup work even when no
patch is produced. Cost depends on cadence, context size, retries and provider
-terms; this guide does not establish a fixed price or a saving. Use existing
-quota and scheduled/event-driven waits. A shell `while true` or a more frequent
-heartbeat does not establish better outcomes.
+terms; Use existing
+quota and scheduled/event-driven waits.
For examples rather than setup, explore the
[public application scenarios](https://loopx-project.github.io/loopx/blog/application-scenarios/)
diff --git a/docs/guides/minimal-custom-runtime-example.md b/docs/guides/minimal-custom-runtime-example.md
index ced8b98753..16e5414b51 100644
--- a/docs/guides/minimal-custom-runtime-example.md
+++ b/docs/guides/minimal-custom-runtime-example.md
@@ -69,8 +69,7 @@ Executable public smoke:
python3 examples/loopx-turn-fake-host-walkthrough-smoke.py
```
-Path B is optional. It does not replace path A for Codex, Claude Code, Cursor,
-shell, Grok Build, or other cooperative hosts.
+Path B is optional.
## What a custom runtime must not do
diff --git a/docs/guides/personal-workspace-trial-guide.md b/docs/guides/personal-workspace-trial-guide.md
index c002cab9a3..d9f47aa60a 100644
--- a/docs/guides/personal-workspace-trial-guide.md
+++ b/docs/guides/personal-workspace-trial-guide.md
@@ -103,7 +103,7 @@ uv run loopx chat-endpoint remove --agent-id kimi # 移除
- **聊天线**:页面会话 ↔ Agent 的对话 session——纠偏发生在这里,内容全程可见
- **干活线**:LoopX 调度器 → Agent 的执行进程——自动跑任务在这里
-纠偏不是插手正在跑的进程,而是修改了共享的 Goal 状态:聊天线的 Agent 基于最新状态回答你,干活线的执行进程下一轮启动时重新读状态,你的纠偏就这样生效了。
+纠偏是修改了共享的 Goal 状态:聊天线的 Agent 基于最新状态回答你,干活线的执行进程下一轮启动时重新读状态,你的纠偏就这样生效了。
**Q:LoopX 派的新任务怎么出现在页面上?**
自动出现,不用刷新:页面持续轮询状态,新任务会进到看板"进行中"列和管家首页"运行中";进行中的对话走实时流(SSE),右上角也有手动刷新兜底。
@@ -112,7 +112,7 @@ uv run loopx chat-endpoint remove --agent-id kimi # 移除
目前能看到公开安全的**执行过程与结果**:Run 卡片/抽屉里的权威状态、进度、结果摘要、证据和产出文件。原始工具调用、命令日志和本地路径不会原样上页面;需要排障时使用折叠的高级诊断或本地运行记录。
**Q:看板上的任务按什么顺序执行?**
-不是列表顺序。Todo 有优先级(P0/P1…)和依赖关系,调度器按"优先级 + 依赖 + 配额"选择下一个执行。
+Todo 有优先级(P0/P1…)和依赖关系,调度器按"优先级 + 依赖 + 配额"选择下一个执行。
## 安全边界
diff --git a/docs/guides/personal-workspace-user-guide.md b/docs/guides/personal-workspace-user-guide.md
index eee28bad5c..7aaea7118b 100644
--- a/docs/guides/personal-workspace-user-guide.md
+++ b/docs/guides/personal-workspace-user-guide.md
@@ -25,7 +25,7 @@ loopx dashboard
```
若 `doctor` 报告缺少依赖,先修复它指出的问题。若缺的是 Agent 登录或运行环境,
-按下文「Agent 运行环境未就绪」处理;看到页面不等于 Agent 已可执行。
+按下文「Agent 运行环境未就绪」处理;
安装版会在同一个进程中启动打包后的工作区、状态投影和 Agent Chat,不需要另开
终端运行 `loopx serve-status`。命令默认自动打开浏览器;无界面启动可使用
@@ -93,7 +93,7 @@ curl -fsS http://127.0.0.1:8767/status.json
要让 Agent 继续验证或修改代码,再在原 Goal 中说明新增范围与权限,沿既有流程处理。
跑通的标志是:找到了正确的项目、Agent 返回了有依据的说明、你能核对它的结果。
-不是只看到一张 Goal 卡片或“已完成”标签。没有可用执行器、目录不可用或来源只读时,
+没有可用执行器、目录不可用或来源只读时,
先处理页面报告的具体问题,不把本机新建 Goal 当作远端工作的替代。
**准备与费用:** 本地页面与 Agent 执行是两件事。创建首轮或发送执行任务会使用所选
@@ -108,13 +108,12 @@ for the project's documented start/test commands and their file references,
without running tests or changing files. Inspect the returned references rather
than treating a created card as a completed result. Reuse an existing Goal for
the same work. Agent execution uses the selected host's allowance; recurring
-work adds wakeup/checking costs. Neither opening the page nor creating a Goal
-proves that its host is active or that its result passes acceptance.
+work adds wakeup/checking costs.
### 在原对话执行已检查的任务 / Run the checked original task
需要修改文件时,在创建预览中明确选择「确认后允许修改工作区」,核对其显示的
-整个工作目录范围,再确认原请求。只读选择不授予文件写入;当前 Codex 入口不会
+整个工作目录范围,再确认原请求。当前 Codex 入口不会
把单个文件或子目录授权扩大成整个工作区。首次回答及普通追问保持只读。

@@ -153,7 +152,7 @@ remains retryable. Once allowance is ready, retry the original creation with
its retained requirements and permission choice instead of creating another Goal.
这些当前使用图展示打包 UI 和真实本地后端;示例中的模型回答与文件编辑由脚本
-提供,用于说明确认范围,不代表真实模型、安装版或完整目标已经通过验收。
+提供,用于说明确认范围。
These current guide images show the packaged UI with a real local backend and
scripted model replies/editing. They explain the confirmation scope and do not
certify live-model, installed-runtime or full-goal acceptance.
@@ -167,7 +166,7 @@ certify live-model, installed-runtime or full-goal acceptance.
LoopX 通过本机已安装的命令行工具驱动 Agent(Codex、Claude Code、Kiro CLI),或通过 API 密钥。
如果这台机器上一个都没有就绪,管家总览会在顶部说明原因,逐项列出缺什么(未在 PATH 中找到的命令、
未设置的环境变量),并提供「重新检查」和「安装指引」。安装并登录后点「重新检查」,页面重新读取
-服务的运行环境目录并回读结果;本页不会安装任何东西,也不授予任何权限。打开 Goal 对话时,如果选中的
+服务的运行环境目录并回读结果;本页不会安装任何东西。打开 Goal 对话时,如果选中的
运行环境在本机不可用,输入框上方会给出同样的说明和重新检查。
执行环境缺失不影响管家和 Goal 中的「仅查状态」:它保存原问题与状态回答,不启动 Agent。
没有该选项的项目对话会明确拒绝未就绪的执行路线,并保留未发送的草稿。
@@ -270,7 +269,7 @@ Markdown links keep their readable labels instead of unusable local destinations
status, proposals and gates still redact entire local paths. This changes answer
presentation, not read or write authority.
-管家与 Goal 的前端对话共用运行视图,适用于查询、编码、投研等各种任务:回答下方显示当前正在做的一步,例如「正在读取 notes.md」。使用 Codex 执行器时,展开「执行过程」可逐步查看思考、读取、搜索、运行的命令、调用的工具和修改的文件;同一步的开始与结束合并为一行,失败的步骤标出退出码,点击一行可查看完整命令、改动文件列表或思考内容。思考内容仅在模型向宿主公开时显示(有的模型只给出思考用时);不显示命令输出、工具参数与结果或文件改动内容,项目内路径显示为相对路径,其余本机路径和疑似凭据会被隐藏。「完成」只表示该步结束,不代表检查通过。这些步骤只保存在本机、仅所有者可读的会话回放记录中;回合结束超过 24 小时后,下次启动 LoopX Chat 时清理。其他执行器继续显示「最近活动」中的最近六条记录。尚未收到活动时保留等待提示,不根据等待时长推测执行进度。
+管家与 Goal 的前端对话共用运行视图,适用于查询、编码、投研等各种任务:回答下方显示当前正在做的一步,例如「正在读取 notes.md」。使用 Codex 执行器时,展开「执行过程」可逐步查看思考、读取、搜索、运行的命令、调用的工具和修改的文件;同一步的开始与结束合并为一行,失败的步骤标出退出码,点击一行可查看完整命令、改动文件列表或思考内容。思考内容仅在模型向宿主公开时显示(有的模型只给出思考用时);不显示命令输出、工具参数与结果或文件改动内容,项目内路径显示为相对路径,其余本机路径和疑似凭据会被隐藏。「完成」只表示该步结束。这些步骤只保存在本机、仅所有者可读的会话回放记录中;回合结束超过 24 小时后,下次启动 LoopX Chat 时清理。其他执行器继续显示「最近活动」中的最近六条记录。尚未收到活动时保留等待提示,不根据等待时长推测执行进度。

@@ -278,7 +277,7 @@ presentation, not read or write authority.
The steward and Goal conversations share the same frontend activity view across task types. The reply shows the step in progress, such as "Reading notes.md". With the Codex executor, expand **Work steps** to follow each thought, read, search, command, tool call and file edit; a step's start and end share one row, failures show their exit code, and clicking a row reveals the full command, the changed files or the thinking text. Thinking text appears only when the model exposes it to the host (some models report only how long they thought). Command output, tool arguments and results, and file diffs are never shown; project paths read as relative paths, other local paths and credential-like values are hidden. A completed step means it ended, not that a check passed. Steps live only in the owner-only local session replay; the next LoopX Chat start after a Turn is more than 24 hours old clears them. Other executors keep **Recent activity** with the latest six observations; missing activity stays an honest waiting state. **Interrupt turn** targets that reply, preserves already visible text, and keeps the conversation available for continuation. A rejected interruption leaves the live reply visible; completion wins a race with interruption. This control does not stop the Goal. Attached hosts that do not expose interruption report that limitation.
-运行中可点击「调整本轮」,向原任务追加指令。当前支持原生 Codex 执行器;只有收到匹配的执行器回执后才显示已接收,这不代表调整后的任务已经完成。不支持的执行器、过期回合或无法确认的回执会保留草稿,不自动变成新任务。送达状态未知时,重试沿用同一请求编号,防止重复投递;执行器明确拒绝且确认未送达时,条件恢复后可用原文安全地重新发起。回合结束后,未发送的草稿仍可复制到输入框。「调整本轮」和普通会话输入框中的追加指令,在发送前必须将重试信息保存到当前标签页的浏览器存储并读回;刷新后恢复原请求身份,不自动发送。存储不可用时会提示尚未发送,草稿仅保留在当前页面;恢复存储后再重试。
+运行中可点击「调整本轮」,向原任务追加指令。当前支持原生 Codex 执行器;只有收到匹配的执行器回执后才显示已接收。不支持的执行器、过期回合或无法确认的回执会保留草稿,不自动变成新任务。送达状态未知时,重试沿用同一请求编号,防止重复投递;执行器明确拒绝且确认未送达时,条件恢复后可用原文安全地重新发起。回合结束后,未发送的草稿仍可复制到输入框。「调整本轮」和普通会话输入框中的追加指令,在发送前必须将重试信息保存到当前标签页的浏览器存储并读回;刷新后恢复原请求身份,不自动发送。存储不可用时会提示尚未发送,草稿仅保留在当前页面;恢复存储后再重试。
Use **Adjust turn** to add instructions to the running task. Native Codex executors currently support this control. A matching executor receipt confirms acceptance, not completion. Unsupported executors, expired turns and unconfirmed receipts retain the draft without starting another task. An unresolved delivery keeps the request identity on retry to prevent duplicates; a confirmed pre-delivery rejection allows the unchanged draft to start a new request after recovery. After the turn ends, copy an unsent draft to the composer. Both **Adjust turn** and an ordinary conversation's in-turn composer save and read back retry information in tab-local browser storage before dispatch. Reload restores the original identity without sending. If storage is unavailable, the adjustment is not sent and its draft stays in the current page; restore storage before retrying.
@@ -294,7 +293,7 @@ id for a fresh attempt. Existing LoopX-mode and Lark ingress keep their contract
Codex 上游声明仍会重试时,会话显示「Codex 正在重试」并继续等待最终结果。若上游明确终止,LoopX 保存失败回执,不把已经出现的部分文字当成完整回答。明确的策略拦截、用量限制、频率限制、上下文超限和身份验证失败会保留各自类别;未知错误仍显示通用失败,不从报错正文猜测原因。
-策略拦截是本轮已结束,不是仍在安全检查中。LoopX 不会自动重放该请求;重启或重复提交同一个请求编号也会返回原失败回执。界面提示只说明上游给出的类别,不解释其未提供的具体触发原因,也不公开上游原始错误详情。
+策略拦截是本轮已结束。LoopX 不会自动重放该请求;重启或重复提交同一个请求编号也会返回原失败回执。界面提示只说明上游给出的类别,不解释其未提供的具体触发原因,也不公开上游原始错误详情。
### 3.1 停止暂时不活跃的 Goal
@@ -531,11 +530,11 @@ the available timeline; it makes no complete-history claim.
(单项超过 2 个已完成前序时折叠为计数),以及待决定事项会解锁的工作;已完成或延后的其余工作
隐藏并计数。「全部」包含早期已完成工作。互不相连的工作链分框排列,需要决定的链在前;
没有关联的事项单独列出。选中事项会高亮全部前序与后续,检查器列出「之前 / 之后」并可打开任务详情。
-连线只来自已记录关系,不代表可以执行;遗漏、来源裁剪或依赖成环时显示「部分工作未出现在此地图中」,
+连线只来自已记录关系;遗漏、来源裁剪或依赖成环时显示「部分工作未出现在此地图中」,
关联端点未找到时同样保留不完整提示,不能推断它已归档或属于其他 Goal。手机改为列表。
**范围与刷新:**交付链覆盖当前选中工作及有限前序;完整 Goal 关系请看工作地图。
-缺失前序、来源裁剪与未展开决定可展开查看;任务完成或缺口列表为空都不代表通过验收。
+缺失前序、来源裁剪与未展开决定可展开查看;
概览与任务页共用一次交付快照读取;「刷新快照」可更新它,离开两页时取消未完成请求,
不增加普通状态读取的图计算。状态变化后自动重读快照,重读完成前暂停来源跳转和导出;
重读失败才提示快照已过期。
@@ -547,7 +546,7 @@ Markdown。搜索筛选不会裁剪导出;不包含原始日志、文件正文
**显式验收合同:**若本地所有者已为使用 canonical authority 的 Goal 启用合同,
交付链下方可展开「Goal 验收合同」,查看条件、任务关联与独立的产物检查结果。
-「任务关联已确认」不等于「产物检查通过」,后者也不自动批准或完成 Goal。
+
缺失、停用保持原界面;旧检查显示其原版本,刷新失败不会作为最新结果导出。
配置入口是本地所有者 CLI:先 `loopx goal-acceptance inspect --goal-id example-goal`,
再按[配置与回滚指南(v0)](../reference/goal-acceptance-observations.md#owner-authorized-contract-v0)
@@ -705,7 +704,7 @@ loopx quota should-run --goal-id
要撤销 Dashboard 配置面的 opt-in,停止当前 Dashboard 后不带
`--enable-goal-subagent-configuration` 重新启动。这个启动参数只暴露本机 loopback
-上的 preview-locked 配置合同,不授予 Agent 新的 Goal、仓库、凭证、发布或生产权限。
+上的 preview-locked 配置合同。
关闭时再次点击开关、检查预览并确认;也可以使用同一配置入口:
@@ -765,7 +764,7 @@ Goal 的 Topic 路由,不删除 Goal、Agent Session、历史 Todo 或其他 G
变化不会通知;开启当下已经在等你的事项也不会重复提醒;可选提醒(不阻塞 Agent 的用户操作)会列在
工作区里,但不会打扰你。关闭开关后立即停止后台读取。如果浏览器曾拒绝通知,之后在站点设置里允许,
回到本页面或打开设置时会重新读到允许,开关即可再次开启;反过来在站点设置里撤销,页面也会如实显示
-并停止后台读取。这只在本页面保持打开时生效,不是服务端推送,也不替代飞书等渠道通知。
+并停止后台读取。这只在本页面保持打开时生效。
"Settings → Appearance → Desktop notifications" is a per-browser switch, off by default. Turning it
on asks the browser for permission once and keeps the switch on only when granted; the page reads
@@ -790,7 +789,6 @@ replace channel notifications such as Lark. An optional reminder (a user action
Agent 在既有授权内推进普通任务,不等于每一步都要你重新点击确认。阅读页面、筛选任务、
下载快照也不会增加执行权限。只读来源保留其限制,截图、导出和对外分享仍需检查是否含私有内容。
-
### 键盘快速导航 / Keyboard quick navigation
按 **⌘K / Ctrl-K**,或点击侧栏底部的「快速导航」,按名称或 ID 搜索目标,
@@ -804,7 +802,7 @@ to close and restore focus. IME confirmation does not navigate.
导航使用当前来源的投影,不创建预览、不发送 Agent 指令,也不执行操作。
已有预览仍需在原详情中确认。只读来源只提供浏览;加载中或不可用的目标会明确标注。
-搜索不是完整历史索引;未加载的历史任务和其他结果仍通过现有任务、文件入口查看。
+未加载的历史任务和其他结果仍通过现有任务、文件入口查看。
Navigation uses the current source projection. It creates no preview, sends no
Agent instruction and executes no action. Existing previews still require their
@@ -826,7 +824,7 @@ through the existing session owner.
在成果、对话或证据视图打开团队报告后,点击 **下载原文 / Download source**,
保存当前显示版本的 UTF-8 原文。文件名包含版本摘要;Markdown、JSON 和文本保留
相应扩展名,其他类型按文本保存。下载不会重新运行 Agent、核验或采用报告,也不会
-修改 Goal。它是所读版本的本地副本,不代表后续版本仍获验收;报告读取失败或失效时,
+修改 Goal。它是所读版本的本地副本;报告读取失败或失效时,
先通过原有刷新/重试恢复可读内容。
Open a team report in Results, conversation or evidence, then choose **Download source**
diff --git a/docs/guides/planner-worker-experimental.md b/docs/guides/planner-worker-experimental.md
index e8637678fe..877c9164a4 100644
--- a/docs/guides/planner-worker-experimental.md
+++ b/docs/guides/planner-worker-experimental.md
@@ -1,7 +1,6 @@
# Experimental Planner-Worker Mode
-Status: **experimental**, opt-in, provider-neutral. This is not a resident
-scheduler and not LoopX's default multi-agent runtime. One call runs one
+Status: **experimental**, opt-in, provider-neutral. One call runs one
bounded Planner → Worker → validation slice and returns a typed receipt.
Use the shipped fake adapters in
diff --git a/docs/guides/review-materials.md b/docs/guides/review-materials.md
index 517cceb507..e2362b8633 100644
--- a/docs/guides/review-materials.md
+++ b/docs/guides/review-materials.md
@@ -9,7 +9,7 @@
在阅读区选择 **页面版** 或 **文字版**。**提出反馈** 会打开负责 Agent 的工作对话,
带上原请求和 Todo 引用;撰写反馈不会自动发送。**验收这份材料** 使用现有操作预览,
-确认后处理这一个版本的 User Todo。处理材料不等于整个 Goal 验收通过。
+确认后处理这一个版本的 User Todo。
阅读、刷新、切换格式都不会处理验收。修订版独立提醒,旧版本的处理结果保留。
页面版提供静态目录;打开外部来源链接请切换到文字版。
@@ -26,10 +26,10 @@
在 Goal 设置中打开定期报告配置,选择 `weekly-progress`、已有的报告接收会话和日历,
开启 **材料就绪后请求验收**,预览并保存。该开关只适用于本 Goal 原 Agent 会话的报告,
-默认关闭,不是设备级默认值。现有频道报告和已有日历不会被自动改写。
+默认关闭。现有频道报告和已有日历不会被自动改写。
例如希望上午 9 点前审阅,可以把日历触发时间设为每天 08:30,时区设为 `Asia/Shanghai`,
-给生成和核验预留时间。这是准备工作的触发时间,不是按时完成保证;原会话及现有唤醒
+给生成和核验预留时间。这是准备工作的触发时间;原会话及现有唤醒
仍须可用。生成、材料就绪、实际送达和用户处理分别核验。关闭开关只停止以后新材料的
自动请求,已有待审阅版本仍可阅读和处理。
diff --git a/docs/heartbeat-automation-prompt.md b/docs/heartbeat-automation-prompt.md
index cb871cc599..a016d66cbf 100644
--- a/docs/heartbeat-automation-prompt.md
+++ b/docs/heartbeat-automation-prompt.md
@@ -62,6 +62,17 @@ transport-neutral goal prompt and lets the goal runtime own inner iteration;
see the host integration protocol instead of adapting this recurring
automation contract.
+Antigravity App (`--runtime-profile antigravity_app` or `--antigravity_app`)
+keeps a fixed resident session patrolling in place rather than relying on
+Codex's `automation_update`: bind the conversation's `Conversation ID` /
+`ANTIGRAVITY_CONVERSATION_ID` with `bind-agent-thread --with-agy-hooks --execute`
+and `sync-global`, perform repository work and `quota should-run` in an isolated
+`.worktrees/` git worktree (leaving the primary checkout clean for
+`workspace_guard`), and suspend between wakes via in-session
+`schedule(DurationSeconds=max(180, interval * 60), TimerCondition="any", Prompt=...)`
+(`180`s minimum floor; `3 -> 6 -> 10` minute unchanged backoff; no shell `sleep`,
+and no `new-conversation` `sidecar.json` unless explicitly requested).
+
### Native Goal bootstrap and live execution instructions
Full, compact and brief automation use the same fully qualified notification/execution rule
diff --git a/docs/integrations/botmux-goal-channel-runtime.md b/docs/integrations/botmux-goal-channel-runtime.md
index b897ad4343..f9ba5b8ce5 100644
--- a/docs/integrations/botmux-goal-channel-runtime.md
+++ b/docs/integrations/botmux-goal-channel-runtime.md
@@ -6,7 +6,6 @@ persistent agent sessions, streaming cards, and terminal access. LoopX remains
the only authority for goal state, todos, gates, quota, evidence, and accepted
transitions.
-This integration does not replace the existing Lark Goal Channel projection.
The two surfaces are complementary:
```text
diff --git a/docs/integrations/codex-subagent-orchestration.md b/docs/integrations/codex-subagent-orchestration.md
index 71fca7cc10..6ad4715f2e 100644
--- a/docs/integrations/codex-subagent-orchestration.md
+++ b/docs/integrations/codex-subagent-orchestration.md
@@ -46,7 +46,7 @@ question for the coordinator when useful independent work exists. Before
launch, identify that question and its dependencies alongside the child briefs;
continue it while children work. After results return, validate decisive sources,
reconcile findings and revisit uncovered questions. Reviewing children is still
-necessary, but does not replace the coordinator's own parallel investigation.
+necessary.
Wait when the remaining useful work depends on child results; do not invent
work, require a minimum child count, or duplicate evidence to fill capacity.
These are guidance-only instructions, not a new scheduler or completion gate.
@@ -55,8 +55,7 @@ These are guidance-only instructions, not a new scheduler or completion gate.
独立、影响决策的证据问题;委派前说明自己的问题、依赖和子任务边界,并在
子 Agent 工作期间推进;回收后核验原件、整合结果、重审尚未覆盖的问题。
核验子任务不能替代主 Agent 自己的并行研究。剩余工作确实依赖子任务时可以
-等待,不要求凑满并发、重复取证或制造工作。这些是引导,不是新增调度器或
-完成门禁;等待某一候选也不意味着其他可执行研究必须停止。
+等待,不要求凑满并发、重复取证或制造工作。等待某一候选也不意味着其他可执行研究必须停止。
Keep tightly coupled decisions in one peer lane. Do not launch workers merely
to make the activity graph look busy, and never let worker count override
@@ -324,8 +323,7 @@ if no peer lane can run, the bundle has
When native child admission succeeds, its adaptive contract remains actionable
and retains the blocked peer contract as `peer_activation_diagnostic`. Neither
path grants permission to use a different entrypoint.
-That blocked diagnostic does not replace the coordinator's own runnable lane or
-re-arm an activation obligation on every heartbeat. If the coordinator also
+If the coordinator also
has no in-scope runnable fallback, the final interaction mode is
`peer_coordination_blocked`: schedulers keep a no-spend observer alive with a
10/20/30/60 minute stateful backoff. Peer capability/readiness, coordinator
@@ -343,8 +341,7 @@ loopx configure-goal \
--execute
```
-This opt-in grants neither cross-owner Todo mutation nor broader repository,
-publication, credential, or production authority. Read it back with
+Read it back with
`loopx configure-goal --goal-id example-peer-task-goal` before relying on it.
## Run History And Observation
@@ -404,9 +401,7 @@ registry wins over an older project-asset model snapshot. Clearing the setting
cannot resurrect a model preference from that snapshot.
This is a per-Goal preference, not a global vendor default. Existing Goals with
-no model configuration retain their previous behavior. Setting a model alone
-does not enable spawning, change the coordinator model, register a peer, or
-supply a host capability. Disabling spawning retains the preference for later
+no model configuration retain their previous behavior. Disabling spawning retains the preference for later
use. Remove both model and effort with:
```bash
@@ -436,7 +431,7 @@ model from response style.
中文操作要点:示例显式配置 Luna/max,仅作用于当前 Goal 的子任务偏好;
未配置的 Goal 不改变默认行为。宿主启动时仍须显式传参并核验支持情况,
不支持时不能悄悄继承主模型。只读研究拆分不同证据问题,子任务返回来源、
-反证和未知项,主任务复核并决定是否采纳。配置生效不等于研究结果有效。
+反证和未知项,主任务复核并决定是否采纳。
### Frontend configuration
@@ -506,8 +501,7 @@ not run the execution preflight: `execution_scope=bound_delegation` and
`preflight=required` accompany `readiness=unknown` (or `blocked` for a known
runtime failure). Use `loopx delegation inspect` on the selected binding to
check canonical authority, task validation and Turn admission before dispatch.
-A peer-activation blocker does not assess this route or native children; neither
-does a successful runtime probe bypass authority promotion or another gate.
+A peer-activation blocker does not assess this route or native children.
Before dispatch, recheck runtime/model/budget and record a stable operation id;
never silently substitute a runtime or model. User preferences guide independent
batch selection; no heartbeat must relaunch every route. Lark and other managed
@@ -520,7 +514,7 @@ surfaces consume this same capability context, not another route configuration.
通过独立准入,使用 adaptive 合约并保留 `peer_activation_diagnostic`,不因另一个
入口受阻而提前返回。运行库/凭据可用只记为 `runtime_readiness`;委派入口尚未预检时
`readiness=unknown`、`preflight=required`,通过现有 `loopx delegation inspect`
-核验权威状态、任务验证与 Turn 准入。未知不等于禁用,ready 运行库也不等于可执行。
+核验权威状态、任务验证与 Turn 准入。
用户的异构偏好影响批次选择,不要求每次心跳重启所有路线,不绕过任一真实门禁。
投影保留 host owner 非空 probe 的 `probe_scope`,完整 probe 与修复代码通过原
绑定预检渐进式披露,不额外发起探测或决定准入。`probing_interpreter` 的模块缺失只针对本次检查的解释器,不能
@@ -552,8 +546,7 @@ not arbitrary manifest scripts or external plugins.
| `after_delegate_result` | Host receipt reconciliation → journal `host_result.agent_context` → executor result `agent_context` | Reconcile bounded native receipts. Read delegation operation receipts explicitly when that separate source is needed, then validate original evidence and accept/defer/reject. |
Planning guidance does not require two persistent Todos. Managed automatic
-child-lane admission still requires its existing prerequisites; this change
-does not grant spawning rights or force concurrency. Disabling the capability
+child-lane admission still requires its existing prerequisites; Disabling the capability
omits the context. Model preferences alone do not enable it.
For a native-tool host such as a Codex App session, the LoopX project skill reads
@@ -584,10 +577,9 @@ retries, mark unlaunched work incomplete and continue useful parent work until
capacity changes. It does not delete, import, resume or rebind sessions, lower
the configured ceiling, or claim that a completed child freed a slot. Raw host
errors and session identities are never accepted by this interface. A
-`succeeded` observation proves only that operation; it does not authorize
-another same-Turn attempt or claim that additional capacity remains.
+`succeeded` observation proves only that operation.
-中文:`max_children` 只是 Goal 配置上限,不代表宿主此刻有同样数量的可用槽位。
+中文:`max_children` 只是 Goal 配置上限。
当原生 `spawn` 或 `followup` 返回 `agent_thread_limit_reached` 时,使用上述
`after_delegate_result` 调用提交有界类型化观察;返回的
`native_host_capacity` 会要求本 Turn 停止重复派发、把未启动工作标记为未完成,
diff --git a/docs/integrations/deepseek-harness-connector.md b/docs/integrations/deepseek-harness-connector.md
index bcb60c0c26..0102bbec5d 100644
--- a/docs/integrations/deepseek-harness-connector.md
+++ b/docs/integrations/deepseek-harness-connector.md
@@ -142,9 +142,7 @@ artifact validators must still verify their own task identity and revision.
`fresh` 按本次 Turn 选择新上下文,同一事务重试保持身份;默认
`resume` 按 Goal/Agent/Todo 延续。Agent 可以长期存在,但独立
问题应使用新上下文,不能把另一个 Todo 的旧任务包当成交接。宿主将上述四个
-本次调用身份变量传给运行时工具,覆盖陈旧值;无 Todo 时为空。这是覆盖映射,
-不是环境隔离边界:当前 pin 的 SDK 先继承父进程环境,再应用映射,因此父进程
-中的无关凭据也会被继承。应从权限适当的环境启动 DSH。身份变量不扩大权限;
+本次调用身份变量传给运行时工具,覆盖陈旧值;无 Todo 时为空。应从权限适当的环境启动 DSH。身份变量不扩大权限;
领域任务包和产物仍须校验身份与版本。
## Run One Governed Turn In Process (`--host dsh`)
@@ -267,8 +265,7 @@ token 也计入输出 token。LoopX 使用 `16384` 的有界产品默认值,
`runtime_probe` distinguishes an import probe (`scope: "probing_interpreter"`,
`module: "deepseek_harness"`) from an injected runner (`scope: "configured_runner"`,
`module: null`, no import attempted). Availability applies to the answering
-interpreter or runner, not the whole machine, and does not prove provider
-authentication. The Chat refusal directs the operator to run `loopx doctor`
+interpreter or runner. The Chat refusal directs the operator to run `loopx doctor`
in the service environment, check `python.executable`, and install the SDK in
that same environment before restarting. Interpreter paths stay in local doctor
output, outside the Turn payload.
@@ -286,8 +283,7 @@ fact. `plan` reports the same verdict without refusing.
- dsh owns model calls, tools, sandboxing, and the raw session log.
- The adapter must not publish raw transcripts, dsh JSONL sessions, credentials,
local absolute paths, or unbounded tool output into LoopX state.
-- `DeepSeekHarness.run()` returns the candidate result; it is not proof of
- completion. An independent validator is required before LoopX writeback.
+- `DeepSeekHarness.run()` returns the candidate result; An independent validator is required before LoopX writeback.
- The dsh Python SDK is an optional dependency. Core LoopX remains runtime
dependency-free.
- The adapter derives an owner-local session id, but LoopX does not project or
diff --git a/docs/integrations/deepseek-harness-control-plane-adapter.md b/docs/integrations/deepseek-harness-control-plane-adapter.md
index 9638a4cab7..19b1dd3cda 100644
--- a/docs/integrations/deepseek-harness-control-plane-adapter.md
+++ b/docs/integrations/deepseek-harness-control-plane-adapter.md
@@ -19,8 +19,7 @@ LoopX. It ships four cooperating surfaces:
control-plane state.
The older [`deepseek-harness` connector](deepseek-harness-connector.md) remains
-a separate headless Turn adapter. The native plugin uses the
-`deepseek-harness-native` host surface and does not replace that connector.
+a separate headless Turn adapter.
## Route Decision
diff --git a/docs/integrations/ego-source-reader.md b/docs/integrations/ego-source-reader.md
index 2562013f74..746539e0a5 100644
--- a/docs/integrations/ego-source-reader.md
+++ b/docs/integrations/ego-source-reader.md
@@ -9,7 +9,7 @@ confirmation. If a successful, complete inventory confirms that the task's
known Agent-created TaskSpace is absent, the same authorization permits one
replacement and reuse of its initial Page. This covers unexpected loss without
requiring a normal-closure receipt or another authorization question. Unknown
-cause stays unknown; failed inventory is not evidence of absence. An existing
+cause stays unknown; An existing
space, a missing Page label, a refused claim or a stuck/blocked Page does not
permit replacement. Keep one active space, record its identity and finish once
per space lifetime.
@@ -25,8 +25,7 @@ before replaying an external effect whose outcome is unknown.
Active user intervention, explicit pauses, reserved control,
unknown task identity and browser-owned permission/login prompts retain their
existing stops, even if the old space later disappears. This is Agent guidance;
-it neither changes Ego's native control checks nor gives the public-source
-reader a claim/takeover tool. That optional reader already bounds its own
+That optional reader already bounds its own
confirmed-missing recovery; the host policy now admits the same known-missing
case instead of making a normal-closure receipt a prerequisite.
@@ -76,9 +75,7 @@ LoopX does not intercept or promise to modify the browser's updater.
The optional `loopx.extensions.ego_source_reader` stdio MCP adapter gives an
existing Codex host narrow `read_public_url`, `read_public_image`, and `search_x` tools when its model shell cannot
-reach Ego's local bootstrap. It reuses an installed Ego browser with a reserved
-Page. It does not replace the Chat Session owner or create a browser,
-model thread, background service, material catalog or permission authority.
+reach Ego's local bootstrap. It reuses an installed Ego browser with a reserved Page.
Operator setup is explicit. Choose `auto` to lazily create one TaskSpace and its
initial `p1` per MCP process. Ego's named factory can reuse an existing space,
@@ -90,8 +87,7 @@ HTTPS origins; `LOOPX_EGO_READ_ORIGINS = "*"` selects that mode explicitly.
Existing comma-separated origin lists retain their restricted behavior. Use an
explicit list for a community or otherwise restricted host. Do not reserve a Page
shared with another process. Navigation
-may use the existing browser's session; origin configuration does not prove that
-every page on that origin is public. Follow the browser's installed skill for
+may use the existing browser's session; Follow the browser's installed skill for
TaskSpace/Page ownership and user consent.
An origin list is insufficient for a public community host that must not reuse
@@ -120,8 +116,7 @@ LOOPX_EGO_READ_ORIGINS = "*"
All-origin mode removes per-site configuration for source links, including
links discovered while reading another source. It changes this provider's origin
policy only: URLs still require HTTPS with no credentials and only the default
-port, and navigation cannot read a redirected or raced Page. It does not grant
-login, browser control, filesystem writes, publishing or private-account access.
+port, and navigation cannot read a redirected or raced Page.
The tools retain their existing `read_public_url` and `read_public_image` names;
the host must still distinguish public sources from signed-in private pages.
The adapter remains optional and disabled until configured on the execution host.
@@ -151,8 +146,7 @@ that boundary before publishing or admitting public evidence.
Open the returned original URL with the existing reader or authorized Ego CLI,
then inspect relevant media and trace technical claims to primary documentation
or code. An excerpt, thumbnail or `media_present` flag is not full-post reading
-or video observation. Search ranking is neither exhaustive coverage nor a
-reliability score. Record sources through the existing
+or video observation. Record sources through the existing
[external-evidence workflow](../../loopx/capabilities/external_research/README.md#egox-discovery--egox-发现)
when using LoopX research; the tool never admits evidence itself.
@@ -210,8 +204,7 @@ stops the operation. Its hard-stop output sink can discard console sentinels;
the adapter preserves only the stable user-control/inactive error code in a
private temporary file and returns `source_reader_not_agent_owned`. It discards
partial output, makes no replacement or takeover attempt, and removes that
-file after the call. Ordinary failures remain ordinary failures. This error
-transport does not grant control or prove a live human handoff was tested.
+file after the call. Ordinary failures remain ordinary failures.
A source's actual login or verification requirement remains a
separate boundary; follow the installed Ego skill and continue independent work.
diff --git a/docs/integrations/host-native-child-receipts.md b/docs/integrations/host-native-child-receipts.md
index 82ea0c6a94..12cc7e3e6c 100644
--- a/docs/integrations/host-native-child-receipts.md
+++ b/docs/integrations/host-native-child-receipts.md
@@ -35,7 +35,7 @@ versions may omit collaboration items from that history.
`native-child record` 仍是主 Agent 上报入口,不能指定宿主来源。托管 Codex CLI
与启用操作工具的 app-server Turn 会在自身连接上直接观察原生协作事件,
把实际启动、宿主失败和观察到的结果写入同一事件流。结果完成之后仍须由主
-Agent 明确记录验收;宿主完成不代表证据已被采纳。
+Agent 明确记录验收;
共享投影区分宿主观察、主 Agent 上报、混合来源和未知;仅全部决策均来自
宿主时 `host_attested` 为真。Codex 的失败协作项没有容量错误码,适配器保留
@@ -157,8 +157,7 @@ keep the normal native-child policy and closeout steps.
合法恢复 deferred Todo 后,以同一显式 Turn 和 Todo 重跑 `quota should-run`。
原绑定 guard 曾拒绝交付、当前 guard 明确准入工作时,quota 在事件流锁内追加
工作资格回执,保留原事件、结算身份、工作区因果和语义门禁;再次进入复用该回执。
-不完整或否定事实、身份冲突和已开始结算均不能升级资格。这不授予执行 lease、
-宿主 child 调用或额外 quota;仍须取得要求的 fresh lease,遵守原生 child 策略和结算步骤。
+不完整或否定事实、身份冲突和已开始结算均不能升级资格。仍须取得要求的 fresh lease,遵守原生 child 策略和结算步骤。
Example / 示例:
diff --git a/docs/integrations/runtime-connector-catalog.md b/docs/integrations/runtime-connector-catalog.md
index a3680a82d2..c78a6da6b8 100644
--- a/docs/integrations/runtime-connector-catalog.md
+++ b/docs/integrations/runtime-connector-catalog.md
@@ -104,8 +104,7 @@ original response/idle/hard deadline. Waiting for another native writer consumes
that allowance before acquiring the Goal fence; there is no separate one-second
ceiling on a healthy send. Backpressure or an interrupted partial send cancels and reaps the same
native peer and drains the writer before releasing the fence; it cannot leave
-a sender to deliver that Turn after Stop. This is a dispatch timeout, not proof
-of non-acceptance or permission to replay. Successful large and Unicode inputs
+a sender to deliver that Turn after Stop. This is a dispatch timeout. Successful large and Unicode inputs
retain the full original text stream; no new input-size truncation is applied.
If current admission consumes the remaining request deadline before a writer
starts, the Session owner still retires that same peer inside the launch fence.
@@ -177,7 +176,7 @@ creates no model Turn or quota debit.
This full decision callback is qualified for executable legacy local, source
and source-to-global routes. Source-session admission retains its separate
-lifecycle-only boundary; this qualification does not enable its CLI execution.
+lifecycle-only boundary.
Benchmark `plain`, `native-goal` and `loopx-goal` modes keep their existing owners
and are outside this quota callback. Restoring an archived checkpoint uses the
destination Goal's current guard, without importing the source Goal's claims,
@@ -208,7 +207,7 @@ source-session 保留独立的生命周期边界,这项验证不会启用其 C
的 `plain`、`native-goal`、`loopx-goal` 模式继续使用各自原 owner,不属于这个 quota
回调。从归档 checkpoint 恢复时,使用目的 Goal 的当前 guard,不导入源 Goal 的
claim、Turn 或扣额权限。已有待结算义务的 Todo-bound guard 直接返回原进程继续
-收尾,不捕获或重启;完成这项工作不构成新的 checkpoint 机会。
+收尾,不捕获或重启;
### Persistent replan attempts and truthful readback
@@ -267,9 +266,7 @@ guessed or rebound, and the durable attempt is never rewritten by this upgrade.
普通存活轮询可以创建缺失的回执,但不能覆盖无法读取的回执。损坏的 JSON、
UTF-8、schema 或 Goal 关联仍保留在原位置,观察写入明确失败,当前 quota 判断
-正常返回,页面继续显示未知。原 worker 可从持久 attempt 恢复观测,
-但这不证明原操作已经结束,
-也不允许再次派发。
+正常返回,页面继续显示未知。原 worker 可从持久 attempt 恢复观测。
新观测绑定完整 source Goal 和原注册表路径,正常同步到 global 后仍可显示原
Agent、义务和观测时间。同步时间变化不改变该来源;来源、实例、配置或运行环境
真正变化时仍显示过期/未知。旧记录沿用原关联检查,不把缺失的来源证明补造成权限。
diff --git a/docs/integrations/session-runtime-control-plane-adapter.md b/docs/integrations/session-runtime-control-plane-adapter.md
index 9faec3d92b..898815f178 100644
--- a/docs/integrations/session-runtime-control-plane-adapter.md
+++ b/docs/integrations/session-runtime-control-plane-adapter.md
@@ -48,7 +48,7 @@ that home to each app-server process, including catalog-compatibility retries.
New managed Codex sessions persist this binding in owner-local session state.
Resume and submit reject a different home before starting an upstream process
or modifying a turn. Legacy sessions acquire the binding only after successful
-upstream restoration; startup alone neither rebinds nor copies their history.
+upstream restoration.
Desktop-owned Chat processes explicitly default `LOOPX_CHAT_CODEX_HOME` to
`~/.codex`, independently of the launching terminal's `CODEX_HOME`. An explicit
@@ -110,7 +110,7 @@ recorded execution home when `CODEX_HOME` is omitted; an explicit value changes
only that service setting. A fresh install without an execution selection uses
the Chat home. Changing the Chat override no longer overwrites an existing
worker profile. This affects macOS-managed Chat/delegation launches, leaves
-session-profile checks in force, and neither migrates sessions nor copies auth.
+session-profile checks in force.
中文:macOS 登录服务分别保存执行端 `CODEX_HOME` 与聊天端
`LOOPX_CHAT_CODEX_HOME`。需要沿用不同的原会话时同时指定两者;升级或重启时未指定
@@ -122,8 +122,7 @@ launcher should separate ordinary open (read-only identity/configuration checks)
from offline account switching, migration, or rollback (exclusive ownership).
Do not make a normal open perform hidden migrations, kill managed workers, or
move sessions into another home to pass an overly broad file-open check.
-Sharing a home also does not authorize two clients to run the same thread
-concurrently. Account changes still require quiescing all users of that home;
+Account changes still require quiescing all users of that home.
this binding does not implement credential copying or account-refresh logic.
Validation: `python -m pytest tests/test_chat_codex_home.py tests/test_chat_agent.py`
@@ -136,14 +135,14 @@ Writable `workspace_only` project conversations now receive default guidance to
prefer direct workspace file writes, inspect command results and exit codes,
and read back prerequisite artifacts before starting dependent work. System
temporary directories remain denied; shell here-documents may fail before the
-intended write. A returned tool call alone is not evidence of command success.
+intended write.
This is model guidance, with no additional permissions or mechanical workflow
enforcement. Read-only, ordinary host and steward contexts retain their prior
instructions. The same context builder serves local Chat and bound Lark topics.
中文:可写的 `workspace_only` 项目对话现在默认提示直接在工作区写文件,检查命令结果
与退出码,并在依赖步骤开始前读回前置产物。系统临时目录仍被拒绝,shell here-document
-可能在真正写文件前失败;工具调用返回不代表命令成功。这是模型指引,不增加权限或
+可能在真正写文件前失败;这是模型指引,不增加权限或
机械工作流约束。只读、普通宿主与管家对话保留原指令;本机 Chat 与绑定飞书话题共用该上下文。
### Projection boundary
@@ -194,9 +193,7 @@ The same disclosure links to the existing ordinary-conversation defaults editor;
the header does not need a second model-settings button. Refresh failures remain
visible; successful status refreshes are announced without another header label.
Effort and tier appear only when the native host reports
-them; Fast may be returned as `priority`. Model selection does not enable a
-LoopX Agent Loop: its separate settings own coordinator identity, token
-allowance and member bindings, and its start control remains explicit.
+them; Fast may be returned as `priority`.
Ordinary Goal/project conversations can choose an advertised reasoning effort
alongside the model. Codex choices come from the selected account's model
@@ -205,8 +202,7 @@ catalog, separately for each model. ACP choices use the host's
and model selection is applied before reading its dependent options. An absent
option is unavailable, never a guessed list of levels. Status-only answers are
a separate read mode, not an executor or a model choice. Unknown actual models
-remain status text and never become a model option; catalog failure has a retry and
-does not claim to refresh the current model.
+remain status text and never become a model option.
An explicit pick applies when opening the next distinct ordinary conversation;
it does not rewrite, interrupt or merge the previous conversation. The existing
@@ -218,7 +214,6 @@ after restart. Native start/resume and the subsequent prompt must retain the
choice. Unsupported or unconfirmed explicit settings fail before a prompt is
dispatched or a new LoopX Session is published. Attached hosts and running
Agent Loops keep their own settings; a conflicting resume request is refused.
-Changing a choice neither runs a model prompt nor changes global native config.
This reasoning-selector increment has isolated HTTP/File-store and native
stdio qualification. Packaged visual/interaction, installed provider adoption
@@ -246,9 +241,7 @@ This is a follow-up path for an owner already reviewing a Goal: read a specific
Agent's result, give it a correction and keep the original conversation. It is
not the general Goal entrypoint or a replacement for the native App. The useful
product comparison is the complete task, including finding the right Agent,
-understanding its result and recovering an interrupted reply. An additional
-chat window or successful transport alone does not establish a better experience
-than working in Codex App. Goal progress and acceptance still come from their
+understanding its result and recovering an interrupted reply. Goal progress and acceptance still come from their
existing owners, never from the transcript or an input acknowledgement.
In the Goal overview's **By owner** view, **Work conversation** opens that owner's
@@ -284,8 +277,7 @@ Tool records use a single expandable row; long text continues in the same view
with explicit content reads. Native text-only output blocks are decoded before
pagination so Unicode offsets remain lossless. Structured shell output shows its
output and recorded exit code, with every original field available in a disclosure;
-unknown formats remain verbatim. Neither a rendered exit code nor readable output
-establishes task acceptance. Native record positions order and deduplicate pages, including
+unknown formats remain verbatim. Native record positions order and deduplicate pages, including
bursts larger than a page between observations and incomplete appends. Older and
newer pages remain reachable when the visible window reaches 300 records.
Looking back pauses automatic insertion; new activity is disclosed without
@@ -349,8 +341,7 @@ not observed idle, the Agent page also subscribes to that exact owner's live
state. Unfinished visible assistant text and supported tool work update in place;
they are labelled as live observations. Looking back freezes insertion until
the reader scrolls back to the latest records. Completion removes the transient row; saved history remains
-the durable reader and the place to continue long output. Neither observed work
-nor its completion establishes Goal acceptance or a delivery receipt.
+the durable reader and the place to continue long output.
Current visible messages and tools carry a small activity glyph rather than a
repeated live-observation banner. It moves only for supported work observed in
@@ -358,7 +349,7 @@ the original active Turn while following the live tail. Looking back makes the
glyph still; completion, disconnection and switching Agents stop it. Reduced
motion keeps the readable glyph and accessible state label without rotation.
Source/update details are available on the Codex App label; input availability
-and failures remain visible. This treatment does not imply token streaming.
+and failures remain visible.
Live observation sends only the versioned following/unfollowing broadcasts. It
never starts, resumes, steers or interrupts a Turn, loads complete history, or
@@ -379,8 +370,7 @@ shapes stop the live reader until the Agent view is reopened.
These limits and private Desktop protocol compatibility remain coverage gaps.
This adds observation, not native-input, approval or installed-host qualification.
-History is neither copied into LoopX run history nor made available to a shared
-sink. Stable Agent routing is shared
+Stable Agent routing is shared
by the Goal directory; other providers and native approval/stream parity remain
within the working-session acceptance. The Codex provider does not close those gaps.
@@ -389,8 +379,7 @@ owner to advertise support for external input, and retains the original thread
settings. It does not use the app-tools pipe or impersonate a model tool caller.
Busy, unknown, ambiguous, rebound and disconnected conversations cannot send
through this surface. Continue such work in the original App. Tool approvals,
-questions and active-turn steering remain there; this stage does not claim the
-complete attached-session acceptance or Lark parity.
+questions and active-turn steering remain there.
Input receipts contain an operation id, binding, content fingerprint and native
acknowledgement, without copying the message body. The same operation cannot be
@@ -401,16 +390,14 @@ idle observation. If the Agent becomes busy before dispatch, the API returns
`input_not_submitted: true` with the rejected operation id. The page retains the
draft and restores the composer directly, including across reload, without an
original-App check or automatic resend. This proof applies only before a receipt
-or native input exists; a generic conflict, missing receipt or transport failure
-does not establish it. After an interrupted response or reopening with a pending
+or native input exists; a generic conflict. After an interrupted response or reopening with a pending
submission, the page automatically reads its existing receipt once. A recorded
acknowledgement restores the composer without another user step; genuinely
unconfirmed delivery remains pending and never silently retries a native effect.
Check the original App before discarding an uncertain receipt. Late reads cannot
restore a discarded operation over a new draft. The UI keeps only its reply recovery
record and unsent draft in the current browser session, scoped to the exact Goal
-and binding; switching Agents never carries text to another recipient. Replies are explicit local owner actions;
-a registered binding or observer does not authorize an Agent to message peers.
+and binding; switching Agents never carries text to another recipient. Replies are explicit local owner actions.
The local presentation API is `/api/chat/codex-attached`: GET requires the
registered Goal, then the exact Agent/binding for history or a receipt; POST
@@ -422,7 +409,7 @@ Windows in this stage. **Open in Codex App** uses an explicit same-origin POST t
rechecks the accepted binding and local conversation, then requests macOS open
the fixed Codex bundle with that conversation's canonical UUID. It cannot launch
arbitrary URLs or commands, submit input or bypass the desktop navigation fence.
-The UI reports OS dispatch, not proof that the App displayed the thread; errors
+The UI reports OS dispatch errors
are visible and retry requires another explicit click. Other hosts report this
operation unavailable. Leave the Agent page to stop reads; rolling back the runtime
removes this UI/provider without editing native sessions, credentials or App
diff --git a/docs/integrations/ssh-reverse-egress-proxy.md b/docs/integrations/ssh-reverse-egress-proxy.md
index d97cbd6b91..253caa2be7 100644
--- a/docs/integrations/ssh-reverse-egress-proxy.md
+++ b/docs/integrations/ssh-reverse-egress-proxy.md
@@ -172,7 +172,7 @@ The example deliberately applies a narrow policy:
- local and remote listeners bind only to IPv4 loopback;
- only HTTPS `CONNECT` requests to port `443` are accepted;
- resolved targets must be globally routable addresses;
-- proxy authentication data is neither accepted nor logged;
+
- the SSH host, ports, retry policy, and cleanup behavior are explicit CLI
configuration;
- logs contain lifecycle events and error classes, not request headers or
diff --git a/docs/integrations/worker-bridge-install-contract.md b/docs/integrations/worker-bridge-install-contract.md
index f20e392cd7..7b90c62af2 100644
--- a/docs/integrations/worker-bridge-install-contract.md
+++ b/docs/integrations/worker-bridge-install-contract.md
@@ -27,9 +27,7 @@ tool output must not enter public status or evidence artifacts.
For an active-user collaboration lane, request a writable feed mount and use
the pull-based commands documented by the returned
-`active_user_intervention_channel_contract`. This channel does not expose hidden
-tests, expected solutions, evaluator answers, credentials, or private project
-material, and it does not authorize score or leaderboard claims.
+`active_user_intervention_channel_contract`.
The same `worker-bridge` surface also carries the provider-neutral
[`attached Agent session broker`](attached-agent-session-broker.md). That
diff --git a/docs/operations/attention-queue.md b/docs/operations/attention-queue.md
index e6afd8b68a..6e2350d38a 100644
--- a/docs/operations/attention-queue.md
+++ b/docs/operations/attention-queue.md
@@ -78,8 +78,7 @@ Fields:
Dashboard consumers should surface the first unfinished item before generic
gate prose when present.
- `agent_todos`: optional active-state checkbox summary for Codex/project
- agents. This belongs in status/CLI and handoff context; it does not replace a
- user/controller gate.
+ agents. This belongs in status/CLI and handoff context.
- `source`: `contract`, `registry`, `run_history`, or `latest_run`.
## Summary Counters
@@ -133,7 +132,7 @@ A registry entry can explicitly override first-screen attention with
`next_handoff_condition`. This lets a controller keep a refreshed goal in the
operator lane when the latest run is fresh but the real next step is still a
human or target-controller decision. The override changes status and quota
-eligibility, but does not grant project-agent execution. If quota later reports
+eligibility. If quota later reports
`safe_bypass_allowed=true`, the target heartbeat may work on another bounded
read-only steering or analysis item from the active state, but it still must not
execute the gated command or any adapter/write/production path.
@@ -280,8 +279,7 @@ refuse. A reminder with retained lease history requires the bound actor's
current active lease key/version as well as provider CAS. An existing lease
does not require or create an agent claim. Expired/released or incorrect proofs
refuse; recovery points to inspection of a live proof or acquisition of a fresh
-lease, never claiming the user Todo. The edit neither renews nor releases the
-lease. A historical replay proves prior acceptance, not current authority.
+lease, never claiming the user Todo. A historical replay proves prior acceptance, not current authority.
User gates, unbound actions, agent Todos and bundled non-copy edits retain
their ordinary admission. Completing an action uses its separate terminal lifecycle contract.
CLI and other transports share the canonical typed update owner; this rule
@@ -291,10 +289,8 @@ canonical `hard_lease` 下,尚无 claim 或租约历史的 OPEN `user_action`
注册 Agent 更新文案、note 和 evidence。更新复用 provider CAS 与操作幂等;不得借此
改变生命周期、归属、执行要求或决策权限。有租约历史时,同绑定角色必须提供当前有效
租约的 key/version,并通过 provider CAS;无需、也不新增 agent claim。过期、released、
-错误凭据仍拒绝,恢复须检查当前凭据或取得新租约;更新不续租或释放,旧回执重放不授予
-当前权限。其他角色、被排除角色、user gate、未绑定待办、agent Todo 和非文案混合更新
-仍执行原门禁。更新提醒不代表本人已执行,
-也不证明通知送达。
+错误凭据仍拒绝,恢复须检查当前凭据或取得新租约;更新不续租或释放。其他角色、被排除角色、user gate、未绑定待办、agent Todo 和非文案混合更新
+仍执行原门禁。
## Boundary
diff --git a/docs/operations/automation-minimum-interval.md b/docs/operations/automation-minimum-interval.md
index 7f701d62dc..8d4108440b 100644
--- a/docs/operations/automation-minimum-interval.md
+++ b/docs/operations/automation-minimum-interval.md
@@ -33,8 +33,8 @@ caller intent, not authentication against other processes sharing the OS user.
For an already bound App turn, inspect its `quota should-run` scheduler packet
using that turn's normal identity and selection contract. Do not create a new
-turn solely to observe a timer. `scheduler_hint.app_automation` and its legacy
-`codex_app` projection expose the floor, desired RRULE, apply/ACK state and
+turn solely to observe a timer. `scheduler_hint.app_automation` exposes the
+floor, desired RRULE, apply/ACK state and
`guarantee`. Apply the desired schedule with the App's `automation_update` tool,
preserving task binding, prompt, status and notification preference. Then view
that same automation and compare its actual schedule before running the returned
diff --git a/docs/product/core-control-plane/README.md b/docs/product/core-control-plane/README.md
index 49534ad67e..4a71b57ddb 100644
--- a/docs/product/core-control-plane/README.md
+++ b/docs/product/core-control-plane/README.md
@@ -63,8 +63,7 @@ uses four runtime responsibilities:
| Kernel | Owns durable todo, gate, monitor, accepted writeback, quota, recovery, and scheduling. |
Domain state, evidence, receipts, and projections are exchanged or derived
-artifacts, not additional owners. An extension may deliver a provider, but its
-installation lifecycle does not grant Kernel authority. See the full
+artifacts, not additional owners. An extension may deliver a provider. See the full
[runtime responsibility model](../../architecture.md#runtime-responsibility-model).
## Three-Lens Contract
diff --git a/docs/product/core-control-plane/state-definitions.md b/docs/product/core-control-plane/state-definitions.md
index c87994b509..6a029486f7 100644
--- a/docs/product/core-control-plane/state-definitions.md
+++ b/docs/product/core-control-plane/state-definitions.md
@@ -41,7 +41,7 @@ second enum registry or writer.
Todo completion, Turn settlement, Goal completion and result delivery are
separate facts. A validated in-flight writeback can settle a Turn while its Todo
remains open; a committed monitor observation can close without spending quota.
-A historical receipt records what happened and does not grant a new execution.
+
`Running` remains derived from execution facts, not a new persisted Todo status.
Legacy wire flags retain their codec semantics: for example, the canonical Todo
record currently maps both `done` and `deferred` to `done=true`; callers must use
diff --git a/docs/product/core-control-plane/state-machine.md b/docs/product/core-control-plane/state-machine.md
index c8879f4178..24d8f28843 100644
--- a/docs/product/core-control-plane/state-machine.md
+++ b/docs/product/core-control-plane/state-machine.md
@@ -5,7 +5,7 @@ cooperating machines that are projected from the same canonical state bodies:
registry entries, active state, todo metadata, run history, quota events,
operator gates, scheduler acknowledgements, and projection sinks.
-This document is not a new store and not a private incident narrative. It is a
+It is a
public-safe map over the current repository contracts, especially:
- [`state-definitions.md`](state-definitions.md) for source state bodies and
diff --git a/docs/product/domain-capability-packs.md b/docs/product/domain-capability-packs.md
index 538d703ac9..0bce63cbe8 100644
--- a/docs/product/domain-capability-packs.md
+++ b/docs/product/domain-capability-packs.md
@@ -376,8 +376,7 @@ P2: add controlled delivery.
board selection, preflight verification, quota, capability gates, and
writeback.
9. Add an `ml_experiment_frontstage` card that explains the current best route,
- why it is or is not a winner, what evidence is pending, and which user
- feedback would change the plan.
+ what evidence is pending, and which user feedback would change the plan.
10. Add an `experiment_dreaming_lane` for advisory candidate generation and
archive suggestions. Promotion to executable agent todo requires operator
review.
diff --git a/docs/product/foundations/agent-facing-trajectory-quality.md b/docs/product/foundations/agent-facing-trajectory-quality.md
index e7c3c9c89f..988434875f 100644
--- a/docs/product/foundations/agent-facing-trajectory-quality.md
+++ b/docs/product/foundations/agent-facing-trajectory-quality.md
@@ -34,7 +34,7 @@ LoopX 需要同时保留两种不同形态的信息:
### 控制事件多于任务事件
-quota spend、scheduler acknowledgement、unchanged monitor poll 和 state refresh 对审计有价值,但它们不等于新的任务进展。控制事件密度持续上升时,Agent-facing 上下文和 run history 都会变得难以阅读,action 与 outcome 的对应关系也更难追踪。
+quota spend、scheduler acknowledgement、unchanged monitor poll 和 state refresh 对审计有价值。控制事件密度持续上升时,Agent-facing 上下文和 run history 都会变得难以阅读,action 与 outcome 的对应关系也更难追踪。
## 3. 三层质量架构
@@ -176,7 +176,7 @@ budget: 8,192 B
action signature: match
```
-这个结果说明当前 envelope 已显著减少重复信息,同时保留了已覆盖的 action dimensions。它不证明所有状态都已具备完整 parity,因此默认 quota output 仍保持不变。
+这个结果说明当前 envelope 已显著减少重复信息,同时保留了已覆盖的 action dimensions。
### Compact history hygiene
@@ -190,7 +190,7 @@ action signature: match
- duplicate action ratio 为 10%;
- 当前样本的 action、outcome 和 decision-anchor coverage 均为 100%。
-当前最明确的信号是:控制事件占比仍高,action/outcome 归因暂时完整。后续优化应优先减少控制语义在 Agent-facing 热路径中的重复,而不是删除审计事件。
+当前最明确的信号是:控制事件占比仍高,action/outcome 归因暂时完整。后续优化应优先减少控制语义在 Agent-facing 热路径中的重复。
## 7. 监控与优化闭环
diff --git a/docs/product/foundations/agent-profile-contract.md b/docs/product/foundations/agent-profile-contract.md
index eb21a64984..61f4d1cab1 100644
--- a/docs/product/foundations/agent-profile-contract.md
+++ b/docs/product/foundations/agent-profile-contract.md
@@ -98,8 +98,7 @@ task policy, and run `quota should-run` before delivery. `--agent-scope` remains
an explicit temporary override for detached validation or one-off automation.
If profiles are configured and the requested registered peer has no profile,
-prompt generation may continue with peer identity only. Missing advisory
-metadata is not an authority failure.
+prompt generation may continue with peer identity only.
## Selection Rules
diff --git a/docs/product/foundations/loop-engineering-principles-and-pitfalls.md b/docs/product/foundations/loop-engineering-principles-and-pitfalls.md
index 1c774d0962..f3a6c4b7c7 100644
--- a/docs/product/foundations/loop-engineering-principles-and-pitfalls.md
+++ b/docs/product/foundations/loop-engineering-principles-and-pitfalls.md
@@ -98,8 +98,7 @@ the CLI and future agents cannot read.
### 7. Over-claiming benchmark uplift
-Benchmarks are evidence, not the whole product. One case or one project-level
-review does not prove general model uplift. LoopX should claim the narrower
+Benchmarks are evidence, not the whole product. LoopX should claim the narrower
value it can show: long-running agent work becomes easier to inspect, steer,
recover, and compare.
diff --git a/docs/product/foundations/loop-engineering-principles-and-pitfalls.zh.md b/docs/product/foundations/loop-engineering-principles-and-pitfalls.zh.md
index 0857ac5606..ecc041d29f 100644
--- a/docs/product/foundations/loop-engineering-principles-and-pitfalls.zh.md
+++ b/docs/product/foundations/loop-engineering-principles-and-pitfalls.zh.md
@@ -3,11 +3,11 @@
这是一份中文短版,用来在阅读更长的产品设计文档前,先理解
LoopX 背后的工作模型。
-Loop Engineering 关注的不是让一个模型进程一直活着,而是让长期
+Loop Engineering 关注的是让长期
agent work 在多轮 executor 之间保持可恢复、可审阅、可调度。短任务里,
一个 prompt 通常足够;长任务里,目标、人的判断、证据、成本和下一步会逐渐
散落到聊天、代码、文档、实验和外部反馈里。LoopX 要解决的是这些状态如何
-不漂移,而不是把对话拉得更长。
+不漂移。
## 原则
@@ -46,8 +46,7 @@ claim、scope、capability、gate、quota 和安全边界,agent 就可以自
人的 reward、review 和偏好信号可以影响后续排序和规划,但不能绕过 gate、
claim、scope、capability check、public/private boundary 或 quota。
-有用的 hint 仍然只是 hint。控制面的职责是把反馈转成可继承的信号,而不是
-让一次“我喜欢/不喜欢”直接变成执行权限。
+有用的 hint 仍然只是 hint。控制面的职责是把反馈转成可继承的信号。
### Evidence 要紧凑且可检查
@@ -63,7 +62,7 @@ transcript、benchmark trace、credential、private note 或本地路径。
agent 有没有说话,而应该看这一轮是否产生了经过验证的状态转移。
monitor-only 或 status-only 的 turn,除非发现状态变化,否则应该保持安静。
-自动化的价值是减少调度负担,而不是制造更多 review 噪音。
+自动化的价值是减少调度负担。
### Loop Agent 需要绩效审阅
@@ -77,8 +76,7 @@ Loop Agent 的价值不能只用单任务 benchmark 分数衡量。长期项目
### 把“跑更久”当成产品
-没有更好状态管理的长 loop,只会制造更大的漂移。产品目标不是后台一直动,
-而是让长期工作可恢复、可审阅、可接手。
+没有更好状态管理的长 loop,只会制造更大的漂移。
### 用总结替代 writeback
@@ -108,8 +106,7 @@ Dashboard 应该投影 LoopX state,并通过 typed write 写回。它不应该
### 过度声明 benchmark uplift
-Benchmark 是证据,不是完整产品。单个 case 或一次 project-level review
-不能证明通用模型能力提升。LoopX 当前更应该声明可展示的窄价值:长期 agent
+Benchmark 是证据。LoopX 当前更应该声明可展示的窄价值:长期 agent
work 更容易被检查、调度、恢复和比较。
## 最小可用 Loop
diff --git a/docs/product/migrations/local-state-path-migration.md b/docs/product/migrations/local-state-path-migration.md
index 4491793526..22f5d47f17 100644
--- a/docs/product/migrations/local-state-path-migration.md
+++ b/docs/product/migrations/local-state-path-migration.md
@@ -141,8 +141,7 @@ not accept an unrecorded newline rewrite as its own completed write.
If recovery reports new content, a second directory, a redirected route or a
damaged backup, it refuses to overwrite anything. Preserve the backup and both
-observed routes for diagnosis; an interrupted operation does not authorize
-discarding later work. This is explicit offline process-interruption recovery,
+observed routes for diagnosis; This is explicit offline process-interruption recovery,
not an online writer fence or a guarantee against filesystem/power-loss damage.
An interrupted backup before the recovery receipt is written has moved no
authoritative state; retain the partial backup and choose a new backup directory
diff --git a/docs/product/periodic-reports.md b/docs/product/periodic-reports.md
index 344fc8276e..bd0c8ffe58 100644
--- a/docs/product/periodic-reports.md
+++ b/docs/product/periodic-reports.md
@@ -4,14 +4,13 @@ Status: source-bound identity preparation, opt-in status monitoring, the
original steward's periodic full-body reports and explicitly configured local
Agent Session calendar reports are implemented. Installation,
an enabled subscription and a natural scheduled delivery require their own
-readback evidence. Preparing an identity enables neither monitoring nor reports.
+readback evidence.
Changing a previously prepared private steward to an executor without native
scheduled-work support keeps its original configuration readable in connection
settings. The monitor deadline, report schedule, retained window and delivery
state remain visible with an explicit execution-unavailable notice. Configuration
-controls are disabled; inspecting retained state neither re-enables the old host
-nor retries a failed window. Native admission still owns every execution and
+controls are disabled; Native admission still owns every execution and
configuration change. Restoring a supported executor restores the existing
configuration view rather than creating a replacement identity or subscription.
@@ -34,8 +33,7 @@ original Session. When Core has retained a private Antigravity steward on its
qualified, flexible Codex fallback, the existing monitor and report controls
remain usable. Bound input, recovery and native consent share the same executor
match; the settings API observes that Core decision instead of rejecting the
-configured preference. This neither switches hosts nor enables native scheduled
-work on Antigravity. A preference alone, an unallocated historical thread or a
+configured preference. A preference alone, an unallocated historical thread or a
pinned policy does not qualify the fallback. Original source, grant, actor,
idle-queue and report-window checks still apply on every operation.
@@ -67,8 +65,7 @@ the original Turn's path evidence, alongside their digest identities. New
private portfolio inputs bind those references to the same frozen source and
make them available to the report author as **recorded, unverified** citations.
Local paths, credential-bearing and malformed reference values remain withheld;
-the source reader never fetches a URL. A recorded address proves neither public
-access nor permission to publish to a different audience. The original scope,
+the source reader never fetches a URL. The original scope,
source gaps and unread-artifact status remain authoritative; an opaque digest
does not supply a missing URL. Existing v1 frozen inputs retain their original
fact set and bytes. New ordinary managed Session inputs use the same frozen
@@ -98,7 +95,7 @@ and reports retain their original requirements and bytes.
The public browser fixture also keeps the original private outbound owner
running through its periodic source-history check. Its shared synthetic
provider returns the stored messages with source-bound pagination and time
-windows; it does not replace history with an empty successful response.
+windows.
The observation includes worker liveness, history-page count and ingress
coverage so a background exception cannot be mistaken for a completed journey.
File and SQLite regressions retain all 55 synthetic uncaptured sources without
@@ -261,8 +258,7 @@ edits and reload. The narrow view is a 390×844 viewport emulation.
|  |  |
Chat `/goal` transport supervision and a LoopX-managed Turn are distinct. Merely
-relaxing `validate_goal_chat`, changing a Session field, adding a prompt, or
-starting a Codex native Goal does not establish the LoopX lifecycle below.
+relaxing `validate_goal_chat`, changing a Session field, adding a prompt.
## One persistent steward actor
@@ -296,8 +292,7 @@ automatic business replay or separate activation scheduler. The combined App
upgrade also stops before restarting the App when this service switch is pending.
Keep the steward's existing portfolio-read authority separate from its execution
-actor. Resolve both through their native owners on every admission. Registering
-the actor does not grant new project writes or broaden the original audience.
+actor. Resolve both through their native owners on every admission.
Keep ordinary project assistants unchanged.
### Identity preparation available now
@@ -598,8 +593,7 @@ the owner can enable or update detailed reports, select daily/weekly frequency,
local time, timezone and first report date, or pause/cancel. The existing calendar
field is reused. A source-bound preview and exact-plan apply configure the
existing `periodic_report` Goal setting with the `portfolio-progress` preset;
-the destination is derived from the original private binding. Neither the
-browser nor the model can supply another Goal, App or recipient. The generic
+the destination is derived from the original private binding. The generic
single-Goal report consumer cannot consume this private portfolio preset.
This preset requires a calendar; its switch cannot select the generic
stage-boundary reporting mode. Pause or cancel through the report actions.
@@ -616,16 +610,14 @@ recorded Core continuation when resolving their private return route. A client
suffix alone is insufficient: the transport and Core journals must agree on
the current Session, Turn, source and recovery record. Quota, routing and
unfinished-work continuations retain the same audience and existing saved-send
-verification; this lookup neither retries model work nor resends an unknown
-provider effect. Missing records, changed identity or revoked grants still
+verification; Missing records, changed identity or revoked grants still
block delivery.
Portfolio evidence collection finishes before the governed driver captures its
launch authority. A long read can then observe legitimate registry rewrites
without immediately invalidating an earlier launch witness. The original
source and execution lease are checked after collection and again at dispatch;
-authority changes after plan capture still reject the launch. This ordering
-does not authorize replay of a historical attempt with unknown host effects.
+authority changes after plan capture still reject the launch.
The original pump can resume one retained report after the first-party launch
owner's exact `stale_goal_authority` refusal. That owner rejects before publishing
@@ -762,8 +754,7 @@ not production-message or real-phone proof.
A managed conversation must belong to the selected registered **Agent**, with
its own original Session, execution state and return path. In the Goal's Agent
-view, managed and attached conversations are parallel sources; a Goal-wide
-Codex chat with an extra Agent selector does not establish that binding.
+view, managed and attached conversations are parallel sources.
The experimental **Advance LoopX tasks** control has therefore been withdrawn
from ordinary Goal Chat. The existing general conversation, native Goal mode
and original attached conversation entry retain their current owners.
@@ -1024,8 +1015,7 @@ data, while the original live authorization check still wins over the cache.
Another Turn or a lost snapshot cannot resume at an old offset. An inventory
change, source revision conflict, outage, invalid/oversized row or read budget
limit remains an explicit coverage gap. Other readable Goals continue. Current
-task and handoff state is observed at collection time; it is not an as-of-window
-reconstruction or proof of a newly completed business outcome.
+task and handoff state is observed at collection time.
The provider's `manager_portfolio_report_source_adapter` composes with the
existing `PeriodicReportAdapterRegistry` using that authorized reader. Its
@@ -1047,8 +1037,7 @@ again from the unchanged frozen source, including its revision. A recomputed
request digest cannot substitute an unsupported URL, summary or incomplete fact
set. The generation receipt retains the same marker. Historical windows without
it keep their original validation contract and bytes; they are not retroactively
-qualified or regenerated. This is source-to-fact consistency, not proof of a
-claim, public disclosure permission or URL reachability. Opaque references stay
+qualified or regenerated. This is source-to-fact consistency. Opaque references stay
opaque when no permitted accessible source has been supplied.
This source can also be read through the original Chat dynamic tool. Reading
@@ -1057,7 +1046,6 @@ steward report path binds it to the admitted calendar window, native generation
and private full-body delivery; installed adoption, current configuration and
the original production route still need independent verification.
-
## Repeat an existing native Task in a managed Session
Use this optional mode for “repeat this completed task on a calendar.” It uses
@@ -1121,7 +1109,7 @@ from an older configuration.
当前通用 Goal 编辑器尚未登记 `task` 字段:表单会在草稿中丢失原来源,JSON 编辑器也
拒绝未登记字段,因此完整任务配置界面仍未交付。上述 HTTP 合同和只读来源目录只是
-阶段能力,预配置的合成场景不代表已完成 Task 选择器或自然语言旅程。缺失、空值、
+阶段能力。缺失、空值、
非对象或夹带命令的 Task 输入在读取 Session 来源前即以 HTTP 400 拒绝,不改订阅、
不创建窗口、不执行业务,也不从旧配置推断来源。
@@ -1139,8 +1127,7 @@ no real identity or private provider is attached. The `start-existing-owners`
control starts the real idle wake owner. `stop-existing-wake` stops only that
owner; removing it resumes the same stored state through a new wake-service
instance. `observed.json` records artifact, completion, retained history and
-actual post-setup model calls. This qualifies neither live-model understanding,
-complete Chat-process restart nor production delivery.
+actual post-setup model calls.
For a controller-restart check, stop that wake owner, await accepted work, then
write a unique operation token to `restart-runtime` in the same output directory.
@@ -1215,8 +1202,7 @@ If the native transaction has committed and the Chat result-event append loses
its acknowledgment, that same invocation may finish returning the original
answer after reading exactly one event with the complete matching result.
Missing, conflicting, duplicate or unreadable result events, and uncommitted
-transactions, retain their failure. This readback neither repeats native
-execution or settlement nor reopens historical failed Chat Turns.
+transactions, retain their failure.
Set `enabled=false` to pause new work and delivery; retain the rest of the
configuration to resume that plan. Clearing the override after a known failed
diff --git a/docs/product/release-readiness.md b/docs/product/release-readiness.md
index cc11f1419a..3afdc71826 100644
--- a/docs/product/release-readiness.md
+++ b/docs/product/release-readiness.md
@@ -61,6 +61,13 @@ backup if older code cannot read the current data. Use `loopx update plan
qualification. Re-running the curl installer remains a repair path when an
archive wrapper is too broken to run its own updater.
+For pip and pipx, `changes_applied` reports an observed change to the installed
+package version or fingerprint. A successful apply can leave the package
+unchanged and still refresh host material or reconcile a stale service.
+`execution.restarted_services` records the services actually restarted. If
+package identity cannot be verified, inspect `loopx doctor --installation-only`
+in the owning Python environment before retrying.
+
For contributors, keep the clone-plus-canary path:
```bash
@@ -238,8 +245,7 @@ and editable setup remain untouched. A build destination overlapping the
source package is rejected. Explicit `bdist_wheel --skip-build` still packages
the selected existing build; it is not a fresh-source qualification. Before
qualifying retirement, inspect the built wheel and run its installed entry
-points outside the source checkout; a source
-test or a manually cleaned build directory alone does not prove this rule.
+points outside the source checkout.
Before a recovery dispatch, inspect the existing `pypi` environment's allowed
branch/tag refs as well as the Trusted Publisher and enabled variable:
@@ -914,7 +920,6 @@ path, and canary route rather than as a user-facing release baseline.
published verified CI outputs after cancelling queued publication jobs.
Windows execution, Apple Developer ID/notarization, live Lark/Bot channels
and unavailable Harbor/SForge/PostgreSQL/NoKV environments remain unqualified.
- This release does not claim a paired-version benchmark uplift.
- `v1.3.1` on 2026-10-06 16:10 +08:00: a focused compatibility release at
commit `7445ae360aaf330e0067959a5e0084ffd9f76de4`, adapting the renderer to
@@ -942,8 +947,7 @@ path, and canary route rather than as a user-facing release baseline.
rendering. At the frozen source, 515 public smokes and 360 affected Python
checks passed; the authorized DS Flash/high alternative passed all 22
scenarios twice and six contrasts, with zero failures or skips. Earlier
- Doubao qualification failures remain unqualified; this does not claim a
- fresh full-tree Python sweep. Windows execution, Apple notarization,
+ Doubao qualification failures remain unqualified; Windows execution, Apple notarization,
authenticated Host interaction, external backend execution and sustained
SQLite qualification remain unqualified. No paired-version benchmark uplift
or isolated Astra causal effect is claimed.
@@ -1039,6 +1043,17 @@ path, and canary route rather than as a user-facing release baseline.
installation; artifact and native-host claims remain those stated by that
release note.
+- `v2.3.0` release at commit
+ `92271fe114916428be6fd36558bb7a93fbe49da8` (2026-11-09).
+ The Git `stable` ref, CLI archive and bundled macOS runtime matched the tag.
+ GitHub and PyPI carry matching Python wheel and source packages.
+ The signed desktop stable feed for this release serves Apple Silicon macOS.
+ Windows stable upgrades use the MSI or NSIS installer.
+ [Published release](https://github.com/loopx-project/loopx/releases/tag/v2.3.0),
+ [PyPI packages](https://pypi.org/project/loopx/2.3.0/#files).
+ Check the installation owner and read back an existing Goal after updating.
+ [Versioned upgrade guide](https://github.com/loopx-project/loopx/blob/v2.3.0/docs/product/releases/v2.3.0.md#upgrade).
+
When a new public release is promoted, add it here only after the matching tag,
release note, stable ref, update path, and focused release canary agree.
@@ -1271,8 +1286,7 @@ PR numbers in commit titles are navigation, not a completeness check. Confirm
that metadata coverage reaches the whole range, resolving unmatched integration
commits through their associated merged PRs. Check an author's earlier merged
PR history before calling a contribution first-time. Reconcile both language
-lists and their summary counts against that verified set; a formatting gate
-does not establish source completeness. Refresh this evidence when the final
+lists and their summary counts against that verified set; Refresh this evidence when the final
release range changes.
Organize the remaining release note into the following stable groups. Omit an
@@ -1303,7 +1317,7 @@ non-empty English group, or weaken contributor attribution.
Within each non-empty group, every material claim must carry one or more direct
GitHub pull-request links such as
`[#2051](https://github.com/huangruiteng/loopx/pull/2051)`. A compare link is
-still useful at the end, but it does not replace per-claim PR attribution.
+still useful at the end.
Avoid bare PR ranges as the only evidence because ranges can hide omitted or
unrelated changes.
@@ -1386,9 +1400,7 @@ available, with the following durable procedure:
Record the guide URL and verified ownership/readback in the existing private
release checkpoint. Credentials, account identifiers, private reference URLs,
-drafts, and raw evidence do not belong in public repository changes. This
-procedure authorizes neither chat/group announcements nor posts to other
-social channels; those retain their own authorization boundaries.
+drafts, and raw evidence do not belong in public repository changes.
### Final Release Body Usage Gate
diff --git a/docs/product/roadmaps/frontstage-channel-lease-roadmap.md b/docs/product/roadmaps/frontstage-channel-lease-roadmap.md
index 25c06c295f..e58fc29c06 100644
--- a/docs/product/roadmaps/frontstage-channel-lease-roadmap.md
+++ b/docs/product/roadmaps/frontstage-channel-lease-roadmap.md
@@ -198,8 +198,7 @@ identity rank or default permission. Concrete authority comes from
### `task_lease_v0`
This optional local file-backed concurrency contract is shipped through
-`loopx task-lease acquire|renew|transfer|release|inspect`. It does not replace
-the default soft `claimed_by` route or participate in quota decisions. The
+`loopx task-lease acquire|renew|transfer|release|inspect`. The
pending key is per todo: `(goal_id, todo_id)`. Do not serialize an entire
goal just because one todo is claimed; independent todos under the same goal
should remain independently claimable when gates and write scopes allow it.
diff --git a/docs/product/roadmaps/saas-opportunity-assessment.md b/docs/product/roadmaps/saas-opportunity-assessment.md
index 257a4b178a..b572ca3f52 100644
--- a/docs/product/roadmaps/saas-opportunity-assessment.md
+++ b/docs/product/roadmaps/saas-opportunity-assessment.md
@@ -144,8 +144,7 @@ the protocol.
Third, LoopX's architectural position is an upper-layer combination of the
first two patterns: Letta-like durable state plus Mastra-like managed
-operations, generalized across heterogeneous runtimes. The differentiated
-product is not a larger framework. It is the semantic control plane that keeps
+operations, generalized across heterogeneous runtimes. It is the semantic control plane that keeps
goal, authority, planning, supervision, evidence, recovery, and handoff
coherent across agents and runs. The comparison validates the monetization
shape; LoopX still has to validate repeat demand for this distinct layer.
@@ -378,8 +377,7 @@ bounded work. It provides authoritative, conflict-aware state; Supervisor
scheduling; stalled-loop detection; recovery, handoff, and governed replan;
and cross-runtime identity, claim, quota, evidence, and acceptance continuity.
-The Supervisor is not a hidden autonomous manager. Hosting does not grant it
-human authority. BYOC and managed private deployment are the lower-risk first
+The Supervisor is not a hidden autonomous manager. BYOC and managed private deployment are the lower-risk first
forms; full multi-tenant hosting follows only after isolation, deletion,
backup, support, and on-call economics are proven.
diff --git a/docs/product/roadmaps/saas-opportunity-assessment.zh-CN.md b/docs/product/roadmaps/saas-opportunity-assessment.zh-CN.md
index 4fe46a551b..a0e8d2cdc2 100644
--- a/docs/product/roadmaps/saas-opportunity-assessment.zh-CN.md
+++ b/docs/product/roadmaps/saas-opportunity-assessment.zh-CN.md
@@ -1,6 +1,6 @@
# 商业化与 SaaS 机会评估
-状态:评估目标。本文是战略评估,不是建设承诺。它讨论 LoopX 如何通过 Enterprise Harness、产品化交付、BYOC、托管运维或 SaaS,把控制面技术变成可重复的客户价值,同时不削弱 LoopX 赖以成立的 local-first、provider-neutral 契约。
+状态:评估目标。它讨论 LoopX 如何通过 Enterprise Harness、产品化交付、BYOC、托管运维或 SaaS,把控制面技术变成可重复的客户价值,同时不削弱 LoopX 赖以成立的 local-first、provider-neutral 契约。
## 商业判断
@@ -14,7 +14,7 @@ Managed Semantic Control Plane 仍然是长期商业复利的核心,但不必
这个位置接近两种已经公开商业化的相邻模式。Letta 将持久、有状态的 Agent 包装成托管服务,按 active agent 与执行量计费;Mastra 在开源 Agent 框架之上销售托管运行、留存、团队协作和企业治理。LoopX 不需要复制二者的产品边界。它的差异化位置是跨异构 Agent runtime 的 provider-neutral 语义控制层:完备的状态管理、规划与监督,基于证据的恢复,以及能够跨 run、跨 Agent 继承的人类 authority。
-这是产品定位假设,不是收入结论。它仍然需要重复生产使用、交付复用和付费意愿验证。
+这是产品定位假设。它仍然需要重复生产使用、交付复用和付费意愿验证。
## 核心张力
@@ -47,15 +47,15 @@ Discovery、集成、评测与上线可能需要 FDE 进入客户 workflow。协
1. **结果证明**:一个有边界的 workflow 达到客户验收,并在周期、质量、产能、恢复或合规成本上有可测改善。
2. **持续使用**:operator 与 Agent team 在一周工作过程中持续使用,而不是装一次就结束。
3. **托管优势**:集成、协作、可用性、恢复、留存或治理让产品显著优于单机脚本与文件。
-4. **交付复用**:客户工作沉淀为 adapter、pack、eval 或核心改进,降低下一次部署成本,而不是形成永久客户分叉。
+4. **交付复用**:客户工作沉淀为 adapter、pack、eval 或核心改进,降低下一次部署成本。
5. **自然扩张**:收入随授权环境、workspace、active managed agent、留存、Supervisor work 或企业控制扩张,而不只随工程师天数增长。
6. **控制面效果**:客户可以测量人工协调减少、恢复加快、非法 continuation 下降,或 review 与 audit 成本下降。
-结果证明与交付复用应当早于 SaaS 形态。无法改善长程工作的 dashboard 只是界面 feature;没有产生可复用资产的成功部署只是服务项目。两者都还不是耐久的软件生意。
+结果证明与交付复用应当早于 SaaS 形态。无法改善长程工作的 dashboard 只是界面 feature;没有产生可复用资产的成功部署只是服务项目。
## 商业对标:看价值捕获,不只看 Star
-截至 2026-08-15 的公开证据表明,这四个项目代表四种不同的价值捕获模式,并不是四家可直接横向比较的创业公司。GitHub Star 能证明分发和类别关注,不能证明收入、留存、毛利或企业付费意愿。
+截至 2026-08-15 的公开证据表明,这四个项目代表四种不同的价值捕获模式,并不是四家可直接横向比较的创业公司。GitHub Star 能证明分发和类别关注。
| 项目 | 公开商业证据 | 价值捕获路径 | 当前判断 | 对 LoopX 的启示 |
| --- | --- | --- | --- | --- |
@@ -68,9 +68,9 @@ Discovery、集成、评测与上线可能需要 FDE 进入客户 workflow。协
第一,商业价值并不按 Star 排名。Mastra 当前拥有最强的资本与平台 packaging 信号;Letta 拿出了最清楚的 stateful agent 生产案例;AgentScope 可能创造很大的云平台内嵌价值,却不必成为独立公司;CAMEL 则通过独立应用承接研究影响力。
-第二,反复出现的路径是“开源分发 + 稀缺付费面”:有人卖托管状态,有人卖观测与部署,有人拉动云消费,也有人销售垂域应用和私有化。开源并不妨碍收入,前提是付费产品消除真实的运行与组织负担,而不是把协议藏起来。
+第二,反复出现的路径是“开源分发 + 稀缺付费面”:有人卖托管状态,有人卖观测与部署,有人拉动云消费,也有人销售垂域应用和私有化。开源并不妨碍收入,前提是付费产品消除真实的运行与组织负担。
-第三,LoopX 的架构位置是前两种模式的上层组合:Letta 式 durable state + Mastra 式 managed operations,并把它泛化到异构 runtime。差异化产品不是一个功能更多的 Agent 框架,而是让 goal、authority、规划、监督、evidence、recovery 与 handoff 跨 Agent、跨 run 保持一致的语义控制面。这些对标验证了变现形态,但 LoopX 仍需要验证客户是否会为这一独立层持续付费。
+第三,LoopX 的架构位置是前两种模式的上层组合:Letta 式 durable state + Mastra 式 managed operations,并把它泛化到异构 runtime。差异化产品是让 goal、authority、规划、监督、evidence、recovery 与 handoff 跨 Agent、跨 run 保持一致的语义控制面。这些对标验证了变现形态,但 LoopX 仍需要验证客户是否会为这一独立层持续付费。
## 中国市场:先产品化交付,再验证纯 SaaS
@@ -92,11 +92,11 @@ Discovery、集成、评测与上线可能需要 FDE 进入客户 workflow。协
| 大型或强监管企业 | Enterprise Harness、FDE、托管运维、治理与 SLA | 私有/BYOC,包含安全、审计和采购工作 | 高客单价可以覆盖集成与控制要求,但销售周期和服务负担明显更高 |
| 海外开发者团队 | Team Cloud 或 Managed Control Plane | 产品试用 + 远程 solution engineering | 对公有云和软件订阅的接受度更高,纯 SaaS 路径更成立 |
-这是一种先后顺序,不是放弃 recurring revenue。国内的第一收入形态更可能是“软件许可 + 有边界交付 + 年度托管运维”;SaaS 更适合低摩擦团队、海外客户,以及多次交付后被证明共性的运行面。
+这是一种先后顺序。国内的第一收入形态更可能是“软件许可 + 有边界交付 + 年度托管运维”;SaaS 更适合低摩擦团队、海外客户,以及多次交付后被证明共性的运行面。
### 成熟 Harness 是第一个付费产品
-成熟 Agent harness 的公开实践说明,客户购买的是一套完整可运行的产品,而不是协议图。OpenAI 称 Codex 已有超过 200 万周活开发者,并通过[按用量计费](https://openai.com/index/codex-flexible-pricing-for-teams/)服务团队;Anthropic 为 Claude Code 打包了[统一账单、支出控制、用量分析、tool / MCP 策略和 Compliance API](https://www.anthropic.com/news/claude-code-on-team-and-enterprise),也[支持通过现有 Bedrock 或 Vertex AI 基础设施做企业部署](https://docs.anthropic.com/en/docs/claude-code/getting-started)。这些数据不证明 LoopX 已经有需求,但证明了企业对 harness 的完整度预期:安装、执行、策略、观测、管理与支持必须组成一个可运维产品。
+成熟 Agent harness 的公开实践说明,客户购买的是一套完整可运行的产品。OpenAI 称 Codex 已有超过 200 万周活开发者,并通过[按用量计费](https://openai.com/index/codex-flexible-pricing-for-teams/)服务团队;Anthropic 为 Claude Code 打包了[统一账单、支出控制、用量分析、tool / MCP 策略和 Compliance API](https://www.anthropic.com/news/claude-code-on-team-and-enterprise),也[支持通过现有 Bedrock 或 Vertex AI 基础设施做企业部署](https://docs.anthropic.com/en/docs/claude-code/getting-started)。这些数据不证明 LoopX 已经有需求,但证明了企业对 harness 的完整度预期:安装、执行、策略、观测、管理与支持必须组成一个可运维产品。
LoopX 的第一个付费产品因此应当是 **LoopX Enterprise Agent Harness**,而不是一组 schema,也不是另一个模型或 IDE。它应当包含:
@@ -107,7 +107,7 @@ LoopX 的第一个付费产品因此应当是 **LoopX Enterprise Agent Harness**
- 部署自动化、升级、备份恢复、默认 policy 与诊断支持包;
- 承载 tool、eval、role contract 与客户系统集成的 domain-pack 边界,不分叉 Kernel。
-客户购买的是一套能把一个 workflow 推到验收的系统。Semantic Control Plane 是其中的产品脊柱,而不是留给客户自行拼装的基础设施抽象。
+客户购买的是一套能把一个 workflow 推到验收的系统。Semantic Control Plane 是其中的产品脊柱。
### FDE 是产品发现与生产化机制
@@ -150,7 +150,7 @@ FDE 的价值,是补齐成熟 Harness 与混乱生产 workflow 之间的最后
### 应用前景与切入顺序
-下表是基于上述公开证据得出的战略判断,不是市场规模预测。
+下表是基于上述公开证据得出的战略判断。
| Workflow | 市场成熟度 | LoopX 适配度 | 付费逻辑 | 主要门槛 | 建议位置 |
| --- | --- | --- | --- | --- | --- |
@@ -163,15 +163,15 @@ FDE 的价值,是补齐成熟 Harness 与混乱生产 workflow 之间的最后
因此,近期销售话术应当是**为一个高价值 workflow 提供可治理的新增产能**,而不是“用 AI 替换一个部门”。初始合同可以组合 workspace / workflow 费用、active managed employee、evidence retention、Supervisor work 与 enterprise delivery;只有当结果可归因、可审计时,才适合增加 outcome-linked pricing。
-顺序同样重要。软件、SRE、科研与技术运营最接近 LoopX 当前社区,也最直接暴露控制面要解决的长程失败。后台与强监管 workflow 可能带来更高客单价,但应在 authority、evidence、deletion 与 recovery 得到证明后,通过 BYOC 和领域伙伴进入。数字团队是扩张路径,不是第一个 SKU。
+顺序同样重要。软件、SRE、科研与技术运营最接近 LoopX 当前社区,也最直接暴露控制面要解决的长程失败。后台与强监管 workflow 可能带来更高客单价,但应在 authority、evidence、deletion 与 recovery 得到证明后,通过 BYOC 和领域伙伴进入。数字团队是扩张路径。
## 产品阶梯
-下面是产品与收入阶梯,不是五个独立 SaaS。每一步都必须留下可复用产品,并让下一步更容易出售。
+下面是产品与收入阶梯。每一步都必须留下可复用产品,并让下一步更容易出售。
### 1. Enterprise Agent Harness
-第一个可销售产品,是一套支持 local、private 与 BYOC profile 的统一版本 LoopX 发行物。它打包 runtime adapter、语义状态、Supervisor、恢复、验收、评测、部署升级、备份诊断与 operator console。验收单位是一个有边界 workflow 到达生产,而不是软件成功安装。
+第一个可销售产品,是一套支持 local、private 与 BYOC profile 的统一版本 LoopX 发行物。它打包 runtime adapter、语义状态、Supervisor、恢复、验收、评测、部署升级、备份诊断与 operator console。验收单位是一个有边界 workflow 到达生产。
### 2. FDE 驱动的 Design Partner 交付
@@ -185,11 +185,11 @@ FDE 的价值,是补齐成熟 Harness 与混乱生产 workflow 之间的最后
长期终局是一个持续运行的控制面:本地或第三方 runtime 执行 bounded work,Managed Semantic Control Plane 维护完备且一致的 semantic execution state。它负责权威且可识别冲突的状态、Supervisor 调度、stalled-loop 检测、恢复、handoff、governed replan,以及跨 runtime 的 identity、claim、quota、evidence 与 acceptance 连续性。
-Supervisor 不是隐藏的自治管理者,托管不会自动赋予它人类 authority。BYOC 与 managed private 是风险更低的第一形态;完整多租户托管要等隔离、删除、备份、支持和 on-call 经济性得到证明。
+BYOC 与 managed private 是风险更低的第一形态;完整多租户托管要等隔离、删除、备份、支持和 on-call 经济性得到证明。
### 5. Domain Packs 与伙伴生态
-Domain capability packs(`docs/product/domain-capability-packs.md`)包装 tool、role contract、eval、review rule 与集成,同时保持 Kernel 通用。LoopX 或认证伙伴可以交付它们。Marketplace 是更晚的分发与收入面,不是第一门生意;领域 authority 仍然不能进入通用 Kernel。
+Domain capability packs(`docs/product/domain-capability-packs.md`)包装 tool、role contract、eval、review rule 与集成,同时保持 Kernel 通用。LoopX 或认证伙伴可以交付它们。Marketplace 是更晚的分发与收入面;领域 authority 仍然不能进入通用 Kernel。
## 计费单位与产品分层
@@ -214,11 +214,11 @@ Domain capability packs(`docs/product/domain-capability-packs.md`)包装 too
- **Managed / BYOC**:durable semantic state、Supervisor 运维、恢复、治理、审计、数据驻留、迁移、SLA 与支持;
- **Team Cloud**:在多租户经济性得到证明后,面向低摩擦或海外团队提供共享 workspace、留存、审批、告警和 review。
-这是 packaging model,不是公开价格表。定价前需要先获得 active agent、event volume、retention、Supervisor execution、交付工作量和支持成本的真实分布。合同应当区分软件许可、有边界交付和 recurring managed operation。FDE 离场后 Harness 必须仍有独立价值;Agent 与其 goal 不能作为同一活动被重复计费。
+这是 packaging model。定价前需要先获得 active agent、event volume、retention、Supervisor execution、交付工作量和支持成本的真实分布。合同应当区分软件许可、有边界交付和 recurring managed operation。FDE 离场后 Harness 必须仍有独立价值;Agent 与其 goal 不能作为同一活动被重复计费。
## 什么不该成为生意
-- **封闭的语义状态格式**:goal、evidence、authority 和 handoff 必须保持可检查、可导出。产品粘性应来自运行质量,而不是状态绑架。
+- **封闭的语义状态格式**:goal、evidence、authority 和 handoff 必须保持可检查、可导出。产品粘性应来自运行质量。
- **把通用执行托管当核心产品**:LoopX 可以编排外部 runtime,也可以运行 bounded Supervisor work;但转售模型 token 与 sandbox 会让项目在算力毛利上竞争,并模糊“控制面不拥有 domain 行为”的边界。
- **把托管 CLI 文件当产品**:没人会为把本地文件搬到别人的磁盘付费。Managed 层必须增加协作、可靠性、恢复或治理价值。
- **客户专属 Kernel 分叉或无限 FDE 驻场**:客户差异必须进入受支持扩展点和有边界交付。永久分叉与工程师天数依赖会摧毁复用。
@@ -244,7 +244,7 @@ Domain capability packs(`docs/product/domain-capability-packs.md`)包装 too
1. 多个客户为有明确 outcome owner 与验收标准的有边界 workflow 付费;
2. 周期、质量、产能、恢复、review 或合规成本相对 baseline 有可测改善;
3. 部署使用同一版本 Harness 与受支持扩展点,同一 pack 第二次部署明显减少 FDE 工作量;
-4. 初次交付后仍然存在许可、续费、托管运维或扩张收入,而不是收入只跟随人力;
+4. 初次交付后仍然存在许可、续费、托管运维或扩张收入
5. 独立团队在数周级工作中反复使用 state、supervision、recovery、evidence 与 handoff;
6. Managed authority 扩张前,export、restore、deletion、tenancy、backup 与 public/private boundary 行为得到验证;
7. 交付、留存、Supervisor work、支持、销售周期与客户集中度可以维持可接受的单位经济性。
@@ -267,7 +267,7 @@ Phase 4 —— 通过 BYOC 或 managed private 运行 Managed Semantic Control P
## 证据边界
-本文刻意区分不同类型的公开证据:融资只能证明投资判断与 runway,不能证明留存或收入;公开价格只能证明存在变现面,不能证明付费客户数;厂商案例证明的是厂商与客户共同披露的部署,不是独立审计 ROI;企业调查证明关注和自报采用,不能证明客户已经需要 LoopX 独特的 semantic control-plane contract。
+本文刻意区分不同类型的公开证据:融资只能证明投资判断与 runway;公开价格只能证明存在变现面;厂商案例证明的是厂商与客户共同披露的部署;企业调查证明关注和自报采用,不能证明客户已经需要 LoopX 独特的 semantic control-plane contract。
现有证据足以支持 design partner 与有节制的商业假设,但不足以跳过 LoopX 自身对复用频率、业务结果、付费意愿和单位经济性的验证。
diff --git a/docs/product/runtimes/codex-cli/codex-cli-automation-driver.md b/docs/product/runtimes/codex-cli/codex-cli-automation-driver.md
index 7a704108bc..56c0d003b5 100644
--- a/docs/product/runtimes/codex-cli/codex-cli-automation-driver.md
+++ b/docs/product/runtimes/codex-cli/codex-cli-automation-driver.md
@@ -63,8 +63,7 @@ composing manual probe chains.
| Repair/replan | Typed control state can preserve, repair, or replace the current route | Host and validation failures route to typed repair/replan; two stalls require a todo or vision delta | Expand real-host negative-path qualification |
| Privacy | Raw host material stays outside LoopX state | Existing boundaries are strong | Preserve current boundary and add a typed result channel |
-This matrix is an implementation checklist, not evidence that the capabilities
-already match.
+This matrix is an implementation checklist.
## Product Shape
diff --git a/docs/product/surfaces/frontend-kernel-mental-model-map.md b/docs/product/surfaces/frontend-kernel-mental-model-map.md
index b0aafaf2e0..bc8380cf5b 100644
--- a/docs/product/surfaces/frontend-kernel-mental-model-map.md
+++ b/docs/product/surfaces/frontend-kernel-mental-model-map.md
@@ -91,7 +91,7 @@ default surface should read from the compressed fields first.
debugging needs exact handles.
- `claim`, `quota`, `scope`, and `handoff` should appear as detail chips,
tooltips, or diagnostic rows unless they require user action.
-- A user gate is not a generic "owner gate"; it must show the concrete decision
+- A user gate must show the concrete decision
and the consequence of approving, rejecting, or deferring.
- Evidence should be compact by default and link to audit details. Raw logs,
private traces, local paths, and sensitive material must not appear in public
diff --git a/docs/product/use-cases/README.md b/docs/product/use-cases/README.md
index 58041336fa..852aa88c13 100644
--- a/docs/product/use-cases/README.md
+++ b/docs/product/use-cases/README.md
@@ -15,5 +15,4 @@ They do not grant domain providers core control-plane authority.
- [Steward: less coordination, accepted results](steward/golden-queries.md)
- [Community assistant: useful answers and checked contributions](community/golden-queries.md)
-These evaluation specifications define intended outcomes and release evidence;
-listing a query does not claim that the corresponding live journey has passed.
+These evaluation specifications define intended outcomes and release evidence.
diff --git a/docs/product/use-cases/auto-research/auto-research-product-metrics.md b/docs/product/use-cases/auto-research/auto-research-product-metrics.md
index 6f99abb296..cab48d9f22 100644
--- a/docs/product/use-cases/auto-research/auto-research-product-metrics.md
+++ b/docs/product/use-cases/auto-research/auto-research-product-metrics.md
@@ -139,10 +139,7 @@ Late/common windows and feedback availability are declared before outcome review
The existing Negative-Evidence Reuse definition includes communication and
frontier-selection signals. It is not interchangeable with the proposed stricter
**actual adoption** measure, which requires a version-bound artifact or behavior
-consequence after an opportunity to use the evidence. Citation, narration or
-visibility alone does not establish that consequence or downstream benefit.
-Neither missing LoopX metadata in a baseline nor a lack of subsequent opportunity
-proves no useful work or ignored evidence.
+consequence after an opportunity to use the evidence. Citation.
Research may analyze permitted private evidence under its own contract; product
extraction still consumes only authorized safe versioned projections with coverage.
diff --git a/docs/product/use-cases/auto-research/long-horizon-progress-design.md b/docs/product/use-cases/auto-research/long-horizon-progress-design.md
index 52a6a60d67..858c0d77e2 100644
--- a/docs/product/use-cases/auto-research/long-horizon-progress-design.md
+++ b/docs/product/use-cases/auto-research/long-horizon-progress-design.md
@@ -156,8 +156,7 @@ The default graph shows explicit source relations and parent grouping distinctly
Any later inferred association stays in the on-demand analysis layer with its
sources, method revision and uncertainty; it does not silently become a source
edge. Same-checkpoint lineage, matched comparison, implementation inheritance
-and actual adoption are different facts. Neither `supports` nor `leads_to` is a
-catch-all for them. Record existing exact identities in the sidecar until a real
+and actual adoption are different facts. Record existing exact identities in the sidecar until a real
caller and accepted contract justify extending the vocabulary.
Before launching a new study that claims relationship-informed decision quality,
@@ -174,8 +173,7 @@ reading check:
isolated nodes, rejected writes, delayed backfills and changed-input limitations.
If that view remains defective, report product acceptance open; do not treat
screenshots or a private custom rendering as the shipped journey.
-3. Inspect the receiver's next action separately. A relation being present or
- cited proves neither adoption nor a more useful experiment. Keep unsupported
+3. Inspect the receiver's next action separately. Keep unsupported
inferences and no-next-opportunity cases visible. Graph classification versus
runtime penalty, Portfolio proxy versus native transfer, and checkpoint capture
versus actual wake input supply three distinct diagnostic questions; select
@@ -263,8 +261,7 @@ lift. Preserve the common denominator and the research owner's resource-weighted
and episode-count views, including failures, incomplete work and abstentions.
Do not silently discard unobservable baseline work. Human/model/tool cost,
elapsed/active/wait time and assessment overhead retain their units and coverage;
-unknown cost is not zero. Existing usage owners provide interval costs; subtracting
-unqualified rolling totals is not an alternative ledger.
+unknown cost is not zero. Existing usage owners provide interval costs.
## Synthetic example: exclusion, implementation and outcome diverge
diff --git a/docs/product/use-cases/auto-research/long-horizon-progress-design.zh-CN.md b/docs/product/use-cases/auto-research/long-horizon-progress-design.zh-CN.md
index 5bbc748ed3..6fa8ecd078 100644
--- a/docs/product/use-cases/auto-research/long-horizon-progress-design.zh-CN.md
+++ b/docs/product/use-cases/auto-research/long-horizon-progress-design.zh-CN.md
@@ -1,6 +1,6 @@
# 长程进展:产品阅读旅程
-- **阶段:** 产品细化提案;本文不证明界面已交付、评估器已合格、指标已晋升或实验取得结果。
+- **阶段:** 产品细化提案;
- **归属:** 研究侧牵头整体评估设计和校准;产品侧负责阅读旅程与展示细化。仓库整合须与既有 owner 核对两侧贡献。
- **语言:** [English](long-horizon-progress-design.md)。
- **既有 owner:** [团队实时工作区](../../../architecture/rfcs/live-team-workspace-v0.zh-CN.md)、[Goal 工作区](../../../architecture/rfcs/goal-workspace-surface-v0.zh-CN.md)、[研究评估](../../../architecture/rfcs/research-exploration-control-plane-v0.zh-CN.md#15-评估与-claim-边界)与 [auto-research 指标](auto-research-product-metrics.md)。
@@ -15,7 +15,7 @@
## 普通路径最短化
-从**已经打开的 Goal**到有可查证依据的回答,统计用户主动操作。这是验收目标,不是当前产品的实测结果;从其它位置打开 Goal 的导航成本另计。
+从**已经打开的 Goal**到有可查证依据的回答,统计用户主动操作。从其它位置打开 Goal 的导航成本另计。
| 操作次数 | 用户能做什么 | 产品要求 |
| --- | --- | --- |
@@ -55,7 +55,7 @@
| 采用 | 特定接收者在可观察动作中使用特定产物/版本 | 仅投递、科学正确或结果变好 |
| 已实现收益 | 在原验收范围内独立合格的下游结果 | 时间相邻或共同启用导致因果提升 |
-可靠性和成本限定上述四个视角,不能合并成一个进展总分。证据标记区分观察事实、模型解释和绑定版本的独立检查。解释须引用依据,允许弃权;有分歧就保留分歧,选中它不会将其晋升为事实。这些是展示区别,不是新的协议 enum。
+可靠性和成本限定上述四个视角,不能合并成一个进展总分。证据标记区分观察事实、模型解释和绑定版本的独立检查。解释须引用依据,允许弃权;有分歧就保留分歧,选中它不会将其晋升为事实。
@@ -65,7 +65,7 @@
`f657a65c6abd03f1f6b87937c327f4ccfb2ccde2`:默认记录时间视图、可选关系视图及行内证据。
该源码仍是产品提案,不代表已安装或 V11/V12 完整验收。它不会补造缺失的研究关系,也没有自动比较原生指标。时间线点选目标问题和独立评审仍归产品侧修复,新头须重新读回。
-首先要留下的是:**上一次结果为什么导向下一次实验。** 在有意义的结论或路线变化时,研究 Agent 复用已有问题,在正常结果回写中附上有依据的关系。用户不用输入 ID、手工拉线或逐条确认。这是研究指导,不是每 Turn 必填附件或图密度配额。
+首先要留下的是:**上一次结果为什么导向下一次实验。** 在有意义的结论或路线变化时,研究 Agent 复用已有问题,在正常结果回写中附上有依据的关系。用户不用输入 ID、手工拉线或逐条确认。
| 关系要回答的问题 | 复用已有表示 | 需要的依据 |
| --- | --- | --- |
@@ -76,7 +76,7 @@
复用[已有结果附件](../../../../loopx/capabilities/explore/README.md#results-from-ordinary-work-writeback):完整结果可带 `question_update` 与至多四条 `relations`,方向是当前问题指向同一 Goal 中已有节点,summary 写明观察依据。这个 hook 不会自动创建任意实验/产物图。真实案例需要假设、实验或产物身份时,通过既有 Explore owner 建立有意义的对象;不要为了连线把所有 finding 都改成新问题。缺失目标、越域、自连、重复及不合法环路继续沿既有规则拒绝;成功回放不能重复写边或重复宣称采用。
-**当前证据边界尚不完整。** Finding 有证据引用和测试输入版本,但 edge writer 没有直接的 `evidence_refs` 或端点版本参数。summary 是一项断言,不等于持久化版本绑定。研究分析 sidecar 保留 edge event 身份、来源快照及获准 finding/产物引用;关联无法复核就标未知,不能向严格 writer 塞入自创字段。后续合同扩展归既有 Explore 类型化 owner,需一起验证写入、读取、checkpoint 回放、CLI 和打包展示;本文没有交付该扩展。
+**当前证据边界尚不完整。** Finding 有证据引用和测试输入版本,但 edge writer 没有直接的 `evidence_refs` 或端点版本参数。summary 是一项断言。研究分析 sidecar 保留 edge event 身份、来源快照及获准 finding/产物引用;关联无法复核就标未知,不能向严格 writer 塞入自创字段。后续合同扩展归既有 Explore 类型化 owner,需一起验证写入、读取、checkpoint 回放、CLI 和打包展示;本文没有交付该扩展。
默认图区分显式来源关系与 parent 分组。后续推断关联进入按需分析层,标明来源、方法版本和不确定性,不静默晋升为来源边。同 checkpoint 血缘、匹配对照、实现继承与实际采用各有含义,不能统统塞进 `supports` 或 `leads_to`。在真实调用方和已接受合同推动词汇扩展前,先在 sidecar 保留既有精确身份。
@@ -93,13 +93,13 @@
[Goal 工作区合同](../../../architecture/rfcs/goal-workspace-surface-v0.zh-CN.md#511-研究-goal全历史-explore-与按需深度分析)拥有两层组合。第一层只投影已有获准 Explore 记录和显式关系,零额外模型调用。第二层消费 benchmark 研究 owner 的深入轨迹评测:一套方法、一个可引用的版本化评测结果,再生成解释图和结论。整条 run 和预先固定的共同比较窗口负责覆盖、原生结果与边际成本;研究侧定义跨 Turn episode 及同一快照中的显式来源/提交/产物绑定。产品展示不另定义单位、口径或进展评分。
-[已有行为发现/报告](../../../reference/benchmark-behavior-findings.md)仅提供探索性观察与解释,不是科学评分;toolkit 的紧凑原生 Goal 生命周期摘要不是全历史图或质量评定;原生结果与可比性仍由实验 board 负责。当前 toolkit 已提供版本化的 `trajectory_assessment_input_v1` / `trajectory_assessment_v1` 产物及其 store,Goal 读览展示六项未校准判读与绑定引用。这一有限整合不是统一科学评测服务或已校准模型口径,不能据此确立原生效用或因果收益。
+[已有行为发现/报告](../../../reference/benchmark-behavior-findings.md)仅提供探索性观察与解释;原生结果与可比性仍由实验 board 负责。当前 toolkit 已提供版本化的 `trajectory_assessment_input_v1` / `trajectory_assessment_v1` 产物及其 store,Goal 读览展示六项未校准判读与绑定引用。
-扩展整合时盘点已有 producer,对齐来源快照/版本、请求及观测时间覆盖、episode/事件/产物绑定、获准受众、输入摘要、方法/代码版本、实际使用时才记录模型/配置、资格、实际费用、反证、不确定性、弃答与结果身份。这是接口要求,不代表科学评测资格已建立。观察、Agent 解释、独立检查与实际采用各自溯源;未经校准的模型信心不是科学概率。
+扩展整合时盘点已有 producer,对齐来源快照/版本、请求及观测时间覆盖、episode/事件/产物绑定、获准受众、输入摘要、方法/代码版本、实际使用时才记录模型/配置、资格、实际费用、反证、不确定性、弃答与结果身份。这是接口要求,不代表科学评测资格已建立。观察、Agent 解释、独立检查与实际采用各自溯源;
明确的片段适用性与判读不确定性分开:适用但未知的片段仍在原分母中,明确不适用的片段不改记为“否”或“未知”。在指标旁显示已声明的排除数,同一可选详情中列出对应片段。缺少片段资料,或样本数与分母的差值,都不能确立排除。读览只格式化 producer 的适用性与计数,不重新决定科学适用性或计算指标。
-生成结果保留历史输入基准;输入或方法变化后,当前适用性尚未建立,新评测不能静默覆盖旧结果。权限/预算不足、执行中、取消、失败和重试时仍能读事实图,重复请求/导航不能重复执行。只有既有获准 Agent/执行 owner 可进行分析;打开页面不授予模型预算、来源访问或干预冻结 benchmark 的权限。分析不能借用 solver 预算、冷却或反馈机会;下述来源/evaluator 边界继续适用。
+生成结果保留历史输入基准;输入或方法变化后,当前适用性尚未建立,新评测不能静默覆盖旧结果。权限/预算不足、执行中、取消、失败和重试时仍能读事实图,重复请求/导航不能重复执行。只有既有获准 Agent/执行 owner 可进行分析;分析不能借用 solver 预算、冷却或反馈机会;下述来源/evaluator 边界继续适用。
## 时间与分数对齐
@@ -111,8 +111,6 @@
## 合成示例:排除、实现和结果分开
-以下全部为示意,不是真实轨迹、benchmark 结果、已校准口径或安装态首屏。
-
```mermaid
flowchart LR
Q[问题:两种方法能否改进候选?] -->|显式实验引用| A[方法 A 已测试]
@@ -150,9 +148,9 @@ flowchart LR
1. **当前设计贡献:** 将本阅读旅程与研究方案整合到既有 roadmap/RFC/指标 owner。合成示例和链接检查只验收文档;校准与打包产品行为仍开放。
2. **只读产品切片:** 一个既有 Goal 入口,默认完整历史 Explore 图、原分数/窗口、完整/未知覆盖,以及可选一次选择的证据/检查/采用详情。既有投影保留多小时竞争路线、多轮尝试、负向/未完成工作和空档。不新增可写图或自动 evaluator。关系缺失可见;实现前置若存在,须有明确 owner。
-3. **打包态资格:** 使用真实 backend 与获准案例,贯穿 0/可选 1/可选 2 次阅读操作路径,验证刷新/返回、窄屏、键盘、旧/缺失锚点、缺时间/因果绑定、分页、重复/乱序、断线、Goal 隔离、来源受限/缺失和产物输入变化。证明阅读/回放不启动执行或发送隐藏 evaluator 反馈。另行整合可选 Agent 请求,消费同一固定版本的 benchmark 评测:一次获准请求复用匹配结果或只执行一次,保留版本化引用、不确定性/弃答、输入/方法失效、预算/权限不足、取消、失败/重试且第一层仍可读;仅有规格不证明此整合已通过。
+3. **打包态资格:** 使用真实 backend 与获准案例,贯穿 0/可选 1/可选 2 次阅读操作路径,验证刷新/返回、窄屏、键盘、旧/缺失锚点、缺时间/因果绑定、分页、重复/乱序、断线、Goal 隔离、来源受限/缺失和产物输入变化。证明阅读/回放不启动执行或发送隐藏 evaluator 反馈。另行整合可选 Agent 请求,消费同一固定版本的 benchmark 评测:一次获准请求复用匹配结果或只执行一次,保留版本化引用、不确定性/弃答、输入/方法失效、预算/权限不足、取消、失败/重试且第一层仍可读;
4. **理解与科学资格分别验证:** 对照既有列表/地图,用预先声明的问题询问结果、转向、来源、验证和不确定性;记录误答、时间与操作数,覆盖误判有进展与误判无进展。研究侧独立验证口径、匹配基线、成本/窗口覆盖和校准。
-理解通过不等于 evaluator 合格;evaluator 判断一致不证明界面易用。两者都不能关闭原小团队/实时流验收、证明提案已安装或证明下游收益。本设计不能让原 L1/R2 纠偏旅程等待所有研究问题解决。
+两者都不能关闭原小团队/实时流验收、证明提案已安装或证明下游收益。本设计不能让原 L1/R2 纠偏旅程等待所有研究问题解决。
研究/产品整合仍需决定:episode 单位和标注口径、窗口/截断策略、可比基线覆盖、来源准入、成本覆盖,以及哪个既有 producer 能提供带版本的决策关联。不能把这些未决问题变成用户必填设置,也不能写成已经批准。
diff --git a/docs/product/use-cases/community/README.md b/docs/product/use-cases/community/README.md
index b751a4064d..e499c950ae 100644
--- a/docs/product/use-cases/community/README.md
+++ b/docs/product/use-cases/community/README.md
@@ -25,7 +25,7 @@ use to reproduce the failure, fix it, and show you the result.
The assistant uses the LoopX entry to connect the project and track the work.
If the entry does not appear, check how the skill was installed for that
-assistant and reopen it. A setup preview does not mean work has started. If
+assistant and reopen it. If
the host cannot activate continuation, ask the assistant to explain the
missing step before relying on it to resume.
diff --git a/docs/product/use-cases/community/golden-queries.md b/docs/product/use-cases/community/golden-queries.md
index cf4f88fbbb..0a9a4a6911 100644
--- a/docs/product/use-cases/community/golden-queries.md
+++ b/docs/product/use-cases/community/golden-queries.md
@@ -25,8 +25,7 @@ to prescribe tool names or learn LoopX's internal receipt vocabulary.
The selection uses a bounded reading of authorized community messages, including
two project discussion streams and a reference technical community. It is
**not a full-history survey or a frequency ranking**. Cross-posted announcements
-count as one pattern. Bot answers are observations of interaction, not evidence
-that their technical claims or hidden implementations are correct.
+count as one pattern. Bot answers are observations of interaction.
Only generalized intent patterns appear here. No verbatim private transcript,
sender identity, group identifier, private URL or local operating state is
diff --git a/docs/product/use-cases/community/manual-cli.md b/docs/product/use-cases/community/manual-cli.md
index 05f07f7eb8..612f18c054 100644
--- a/docs/product/use-cases/community/manual-cli.md
+++ b/docs/product/use-cases/community/manual-cli.md
@@ -73,4 +73,4 @@ To check the permission boundary, try the completion step **before the
valid completion** with the same Todo and Agent, but omit
`--claim-operation-id "$claim"`. The command must reject the request and
the Todo must remain open. Restore the original claim argument and complete
-the exercise. A Todo owner name alone does not prove a current claim.
+the exercise.
diff --git a/docs/product/use-cases/community/manual-cli.zh-CN.md b/docs/product/use-cases/community/manual-cli.zh-CN.md
index a04df7a43a..fe10130de6 100644
--- a/docs/product/use-cases/community/manual-cli.zh-CN.md
+++ b/docs/product/use-cases/community/manual-cli.zh-CN.md
@@ -65,4 +65,4 @@
要检查权限边界,可在**带凭证的完成命令执行之前**,用同一个 Todo 和 Agent
试一次不带 `--claim-operation-id "$claim"` 的完成命令。操作应被拒绝,Todo
-仍为 open。加回原领取凭证再完成练习。只有 Agent 名字不代表持有当前领取凭证。
+仍为 open。加回原领取凭证再完成练习。
diff --git a/docs/product/use-cases/cross-runtime/README.md b/docs/product/use-cases/cross-runtime/README.md
index 26f6617c5d..96c2370f1c 100644
--- a/docs/product/use-cases/cross-runtime/README.md
+++ b/docs/product/use-cases/cross-runtime/README.md
@@ -61,8 +61,7 @@ normal setup and execute the seven bounded model phases. Only explicit
phase, inspect its evidence, and use the documented repair path before continuing.
This example covers **same-host, same-Goal collaboration**, including dependent
-artifacts, independent review, revised acceptance and result return. It is not a
-live Claude/Codex cross-runtime test or an autonomous team scheduler. Its
+artifacts, independent review, revised acceptance and result return. Its
initial owner request is seeded by the controller. The example's browser
screenshots are separate synthetic UI fixtures, not screenshots of live model
outputs. See its [boundaries and recovery](../../../../examples/collaboration-delivery/README.md#boundaries-and-recovery)
@@ -101,7 +100,7 @@ reviewer 独立复核;用户随后修改约束,团队重新计算、再次
问题包含六个订单、有限库存、区域容量、需求量和预算。第一轮应得到价值
**84**、成本 **1000**;用户修订后应为价值 **83**、成本 **990**。这是演示
-输入的验收值,不是性能指标;完整分配向量和校验命令见案例说明。
+输入的验收值;完整分配向量和校验命令见案例说明。
每个阶段启动全新 dsh 会话,持久身份、Inbox 和版本化文件连接前后工作。
控制器明确启动各阶段,并通过 Git 交接指定文件;Agent 自己读取和判断请求、
@@ -120,7 +119,7 @@ worktree,不使用你的活跃 Goal,也不调用模型。
这个例子覆盖的是**同主机、同 Goal 的产物依赖、独立审阅、要求修订和结果回传**,
不是 Claude/Codex 跨 runtime 实测,也不是无人值守团队调度器。初始请求由
-控制器写入;配套浏览器截图是独立的合成 UI fixture,不是实际模型运行截图。
+控制器写入;配套浏览器截图是独立的合成 UI fixture。
停用工具、停止执行及完整边界见[恢复说明](../../../../examples/collaboration-delivery/README.md#boundaries-and-recovery)。
进一步阅读:[语义交办与同伴审阅](../../../../loopx/capabilities/manager_context/README.md#semantic-delegation-and-peer-review)、
diff --git a/docs/product/use-cases/issue-pr/issue-pr-solver-maintainer-intake.md b/docs/product/use-cases/issue-pr/issue-pr-solver-maintainer-intake.md
index 42527af72f..1812c1867a 100644
--- a/docs/product/use-cases/issue-pr/issue-pr-solver-maintainer-intake.md
+++ b/docs/product/use-cases/issue-pr/issue-pr-solver-maintainer-intake.md
@@ -5,9 +5,7 @@ issue/PR solver should become a high-value proof anchor. The solver may live
outside LoopX. LoopX's job is to make the maintainer decision, boundary,
evidence, and showcase path explicit.
-The packet is intentionally pre-execution. It does not authorize reading
-private source, generating patches, pushing branches, posting comments,
-publishing artifacts, or claiming benchmark uplift. It turns an issue/PR solver
+The packet is intentionally pre-execution. It turns an issue/PR solver
opportunity into reviewable LoopX state.
## When To Use It
diff --git a/docs/product/use-cases/office-operations/personal-follow-through.md b/docs/product/use-cases/office-operations/personal-follow-through.md
index 9b7610c951..20a1601dba 100644
--- a/docs/product/use-cases/office-operations/personal-follow-through.md
+++ b/docs/product/use-cases/office-operations/personal-follow-through.md
@@ -14,8 +14,7 @@ is retained as a superseded discovery and evidence entrypoint.
An owner promises a draft, receives a deadline correction, and asks for supporting
material. The manager retains one commitment, prepares authorized material, and
returns a sourced brief in the original private desktop conversation. The owner
-can inspect, correct, dismiss and pause it. A prepared draft or sent message alone
-does not prove that the personal commitment has been fulfilled.
+can inspect, correct, dismiss and pause it.
The first profile covers one owner, a private local workspace, selected authorized
bot-visible Lark conversations and an existing or explicitly created private Goal.
diff --git a/docs/product/use-cases/office-operations/personal-follow-through.zh-CN.md b/docs/product/use-cases/office-operations/personal-follow-through.zh-CN.md
index a67c1d897c..0e02ba3b31 100644
--- a/docs/product/use-cases/office-operations/personal-follow-through.zh-CN.md
+++ b/docs/product/use-cases/office-operations/personal-follow-through.zh-CN.md
@@ -91,7 +91,7 @@ ACK/游标推进遵循既有采集/效果回执契约。来源编辑改变解释
输出制作。覆盖本人/他人承诺、引用、否定、歧义、时区、编辑及删除。分别报告
提议准确率(正确提议 / 全部提议)和召回率(正确发现承诺 / 全部标注承诺)。
profile 提议目标为准确率至少 95%、召回率至少 90%、错误责任人自动变更为零、
-越权效果为零。这些是尚未测量的发布目标,不代表已交付性能,也不替代管家验收。
+越权效果为零。这些是尚未测量的发布目标。
通过安装版前端、飞书和 CLI 执行独立规定的序列:连接 → 承诺 → 审阅 → 规范
Todo → 改期 → 用户纠正 → 授权准备 → 重启 → 原对话产物返回 → 断开。
@@ -110,7 +110,7 @@ Todo → 改期 → 用户纠正 → 授权准备 → 重启 → 原对话产物
[PR #5385](https://github.com/loopx-project/loopx/pull/5385)记录的 `ad478f4`
提交是实验性 CLI 前置切片,测试使用模拟飞书/模型响应和真实本地进程/存储。
-它不证明真实身份/来源/模型兼容性、持久提议接入、桌面返回、打包执行或试用。
+
历史测试数量与边界保留在[原执行记录](../../../architecture/rfcs/ledger/personal-follow-through-v0/)。
当前集成证据归[管家执行记录](../../../architecture/rfcs/ledger/capable-manager-semantic-handoff-v0/)。
管家/work-item、personal-workspace 与飞书扩展 owner 继续完成这些既有验收责任。
diff --git a/docs/product/use-cases/steward/README.zh-CN.md b/docs/product/use-cases/steward/README.zh-CN.md
index 80fdb7c10c..a2f476695f 100644
--- a/docs/product/use-cases/steward/README.zh-CN.md
+++ b/docs/product/use-cases/steward/README.zh-CN.md
@@ -2,13 +2,13 @@
状态:qualification 案例。它记录本机管家旅程今天在工作台面上证明了什么、哪几拍还没有证明,以及如何复现两者。它是产品侧使用说明,不是新能力、新契约或新调度器。
-本文案的事实来源是一个确定性的浏览器场景(`examples/personal-workspace-browser/steward-journey.mjs`),全部跑在合成数据上。fixture 顶替了 agent turn;本文描述的每一句都是工作台面渲染出来的事实,不是对某个真实 Goal 的断言。
+本文案的事实来源是一个确定性的浏览器场景(`examples/personal-workspace-browser/steward-journey.mjs`),全部跑在合成数据上。fixture 顶替了 agent turn;本文描述的每一句都是工作台面渲染出来的事实。
## 什么情况下适用
-- 老板想用一句话启动工作,而不是填表;
+- 老板想用一句话启动工作
- 这项工作需要不止一个 Agent 或不止一条 lane,所以“有没有人干”本身就是答案的一部分;
-- 老板想在同一个地方确认、纠偏、看结果,而不是在多个 Agent 会话之间来回转发。
+- 老板想在同一个地方确认、纠偏、看结果。
## 旅程七拍
@@ -28,9 +28,9 @@
1. **说要结果,不要点将。** 一句话给出结果与约束,让计划卡来回答“谁来做”;先点名 Agent 会把协调变成老板的活。
2. **确认前先看四件事**:Agent、第一刀 bounded Todo、验收信号、缺人情况。看不到缺口的卡片还不具备可评审性。
-3. **缺人 lane 是信息,不是失败。** 未配齐的 lane 会保留它没能派出去的工作并给出原因,老板可以选择砍掉、补人、或接受部分交付。
+3. **缺人 lane 是信息。** 未配齐的 lane 会保留它没能派出去的工作并给出原因,老板可以选择砍掉、补人、或接受部分交付。
4. **确认是一次落地的 durable 写入。** 确认只发一次 apply、只做一次 durable write;卡片不能在写入前声称 lane 已存在,写入后必须说明产生了什么。
-5. **用回传结果判定交付,不要用对话判定。** 一条回复不等于一条 lane 完成。在缺口 5 关闭前,把对话当请求通道,把 Goal 自身状态当事实。
+5. **用回传结果判定交付,不要用对话判定。** 在缺口 5 关闭前,把对话当请求通道,把 Goal 自身状态当事实。
6. **在产生工作的那个对话里纠偏。** 对运行中的 Turn 纠偏今天已支持;对已确认 lane 承诺的纠偏还没有,所以不要确认一张可能需要撤回 lane 的计划。
## 如何复现
diff --git a/docs/product/use-cases/steward/first-use-evaluation.md b/docs/product/use-cases/steward/first-use-evaluation.md
index 383a441417..21e1fd3ae5 100644
--- a/docs/product/use-cases/steward/first-use-evaluation.md
+++ b/docs/product/use-cases/steward/first-use-evaluation.md
@@ -89,8 +89,7 @@ same work and ask:
The repeat request should reuse the retained work and its constraints. It needs
checked calculations and limits, not a guaranteed investment forecast. Declining
or not returning is recorded with a volunteered reason, not replaced by another
-user. This handout does not authorize public posting, trading, broader account
-access or additional background work.
+user.
## What counts as a useful result
@@ -161,8 +160,7 @@ attempted count out of the **frozen five**, accepted count out of five, each
failure/blocked/not-run row, later-day accepted repeat count out of those same
five, times, interventions and measured/unknown costs. Report timing coverage;
do not omit slow/failed samples or impute zero cost. For the 4/5 and 3/5 targets,
-blocked, abandoned and not-run slots stay in the denominator. A useful-artifact
-rate alone does not prove all safety, budget or advertised-platform gates passed.
+blocked, abandoned and not-run slots stay in the denominator.
Five users provide diagnostic feedback, not a statistical reliability claim.
## Existing feedback route and next repair
diff --git a/docs/product/use-cases/steward/golden-queries.md b/docs/product/use-cases/steward/golden-queries.md
index e0c06c7bb2..53d051ad01 100644
--- a/docs/product/use-cases/steward/golden-queries.md
+++ b/docs/product/use-cases/steward/golden-queries.md
@@ -20,8 +20,7 @@ This pack qualifies the [overall roadmap R1–R3](../../../architecture/rfcs/loo
and [shared conversation surface](../../../architecture/rfcs/intelligent-review-presentation-surfaces-v0.md#88-reusable-conversation-work-surface).
It adds no capability, runtime schema, routing keyword list or scheduler.
Canonical Todos own implementation work; this document owns case intent and
-evaluation rules. Existing [workspace qualification](README.md) uses synthetic
-turns and does not establish these live outcomes.
+evaluation rules.
## Request style / 请求写法
@@ -71,7 +70,7 @@ past the compact scheduling label, with a public evidence link. The App detail
and provider notice must retain the request object and available evidence. Two
requests with the same title remain distinguishable; a replay sends no second
notice. Bound oversized content explicitly and preserve redaction. A notification
-is a preview, not proof of approval, execution or a fresh authorization grant.
+is a preview.
### A working receiver still owes this request / 负责人正在工作,仍需接续这条请求
@@ -114,8 +113,7 @@ App/channel result without human reminders or manual relay.
“这些已经交办的事,落实后把结果带回来。” / “Finish the requests I delegated
and bring the results back.” This is a GQ03/GQ07–GQ09 journey under
[handoff RFC §5.15](../../../architecture/rfcs/capable-manager-semantic-handoff-v0.md#515-accepted-requests-remain-accountable-through-fulfillment),
-with A25–A28 acceptance. It does not authorize bulk execution, cancellation,
-priority changes or creation of another task authority.
+with A25–A28 acceptance.
Freeze a disposable source with more than 40 requests, several qualified
receivers, mixed dispositions and long original content. Include two requests
@@ -163,7 +161,7 @@ while a mention or verified bot reply still works. Bots, missing sender evidence
historical backfill (even with an old mention), an unrelated group and a worker's
own Topic are negative cases. This admission probe does not qualify autonomous
execution: the external read-only profile and recipient grants must be evaluated
-separately. Passing transport fixtures is not evidence of a deployed group run.
+separately.
#### Source-bound follow-ups / 找准追问对象
@@ -300,8 +298,7 @@ suggestions. Unknown requirements stay unspecified. Selecting a suggestion must
only fill the composer; a free-text correction must remain usable. After a reply,
reload and recover the corrected draft, optionally open the existing Goal form and edit its
criteria, preview and explicitly apply once, then inspect the creation receipt.
-Before confirmation there is no Goal/action write or worker launch. A draft is
-neither a created Goal nor completed research. Ask an ordinary explanatory question
+Before confirmation there is no Goal/action write or worker launch. Ask an ordinary explanatory question
and confirm no draft appears. Reject an attempted permission/Agent-binding field
inside a draft. Qualify model response quality separately from scripted transport
and packaged-browser tests; the full GQ01 start-and-return outcome remains open.
@@ -339,7 +336,6 @@ host login. API raw-envelope integrity and Codex adapter outcomes are separate
measurements, not interchangeable provider scores. Fixed contexts do not certify dynamic tool
discovery or receiver adoption. Compare providers/settings separately.
-
### App-first execution profiles and ordinary questions
Qualify the installed App first; Lark is independently scored, not required to
@@ -528,8 +524,7 @@ documents conversation/topic identity
and separate conversation/operation permissions. Its
[steering study](https://github.com/deepcoldy/botmux/blob/982e2c9f16e4f45ae2581967bc1a35a286e7bfa2/docs/design/2026-05-28-codex-type-ahead-steer-design.md)
describes merged and separate replies under one tested Codex version. These
-are source observations, not proof of current LoopX behavior or universal
-provider guarantees. Do not install Botmux or bind a live bot to run this case.
+are source observations. Do not install Botmux or bind a live bot to run this case.
Use the existing presentation RFC as the already-indexed twin. The evaluator
then supplies a small synthetic public note and a disposable work item, varying
diff --git a/docs/project-agent-todo-contract.md b/docs/project-agent-todo-contract.md
index ce49039896..9256b99c24 100644
--- a/docs/project-agent-todo-contract.md
+++ b/docs/project-agent-todo-contract.md
@@ -949,6 +949,34 @@ fails closed with a typed `validation_blocked_completion` receipt instead of
committing `done`. Todos without a declared command keep the unchanged fast
path.
+Completion requests sharing a runtime root serialize validation for the same
+Todo, including requests from different completion entry points. If validation
+is still running, retry the original request once the first attempt finishes.
+If the terminal response is lost, use the reported `todo receipt` command or
+retry the same reviewed Chat proposal to recover the original operation. A
+committed completion replays its receipt without rerunning the validator. A
+missing receipt alone cannot determine whether the original writer has stopped.
+
+On POSIX, the supervisor retains the same execution lock until it stops the
+validator's process group, including when the caller exits or the validator
+leader exits with redirected descendants still running. The retry can then
+check the original completion receipt. This
+covers the caller's exit and descendants in the same process group. Windows
+continues to serialize while the caller is alive. Keep validation commands safe
+to retry. A command that already ran before a missing terminal commit may need
+to run again.
+
+共享运行时目录的完成请求按 Todo 串行执行校验,跨完成入口也使用同一把锁。校验进行
+中,可在首个请求结束后重试原操作。终态提交响应丢失时,使用返回的 `todo receipt`
+命令查询原操作,或重试同一已审核的 Chat 提案。已提交的操作直接重放回执,无需再次
+执行校验。未查到回执时,原写入仍可能在进行。
+
+在 POSIX 上,监督进程保留同一把执行锁,直到原校验进程组停止;调用方退出,或
+校验主进程退出而重定向输出的子进程仍运行时,也要完成清理。之后可重试原操作并
+检查完成回执。该机制覆盖调用方退出和同一
+进程组内的子进程。Windows 在调用方存活期间继续串行校验。校验命令应可安全
+重试。若命令已运行但终态尚未提交,重试时可能再次执行。
+
### Bind the first completion validator / 首次绑定完成验证
An active, open canonical Todo imported without a completion validator can use
diff --git a/docs/quota-allocation.md b/docs/quota-allocation.md
index b907de93e3..16cb1a44f1 100644
--- a/docs/quota-allocation.md
+++ b/docs/quota-allocation.md
@@ -1798,6 +1798,11 @@ trigger uses a fresh Turn identity to evaluate the live frontier; it never
re-executes or spends for the closed Turn. Native Goal runtimes continue to that
fresh guard instead of blocking the Goal. Explicit Goal stop or quota pause
still takes precedence. Actual fresh-Turn waits retain their existing backoff.
+New scheduler decisions expose App cadence, applicability, and follow-up
+commands only under `scheduler_hint.app_automation`. This includes shutdown,
+minimum-interval waits, and the explicit unavailable state for schedulers owned
+outside the App. A saved decision retains its original representation. Older
+Codex state still uses its recorded state key when it is the selected authority.
For Codex App and local schedulers, `recommended_interval_minutes` is the next
target interval. For Codex App heartbeats, `recommended_rrule` is emitted only
when `app_automation.stateful_backoff.apply_needed=true`; if the desired RRULE is
@@ -1823,10 +1828,16 @@ CLI-produced ACK hints bind that argument vector to the exact registry and
effective runtime root that produced `quota should-run`. Hosts must execute the
complete vector; stripping its leading global options can route a
project-launched ACK into project-local scheduler state instead of the shared
-control plane. `fallback_hint.cli_args` receives the same registry binding, and
-its `--turn-instance-id` value is always the reference the current host shell can
-expand: `"${LOOPX_TURN:?}"` on POSIX and `$LOOPX_TURN` on native Windows, so a
-PowerShell host does not replay an empty Turn. When the decision is
+control plane. `fallback_hint.cli_args` receives the same registry and runtime
+root bindings. The bridge reads `scheduler_hint.app_automation` from the
+complete decision. It accepts a legacy `codex_app` packet from an earlier CLI
+version. An executable-bound guard also passes its selected CLI to the
+bridge. When that installation ships an executable POSIX fallback launcher
+beside the CLI, the command also names that launcher. For older saved commands
+without a runtime root, the registry route supplies it. When the Turn is still
+expressed as a shell variable, the
+fallback's `--turn-instance-id` uses `"${LOOPX_TURN:?}"` on POSIX and
+`$LOOPX_TURN` on native Windows. When the decision is
heartbeat-receipted, ACK, failure, and fallback hints also bind the originating
concrete `turn_instance_id`, and `fallback_hint.route_binding.turn_instance_bound`
records whether that binding is present. The follow-up rebuilds the same
diff --git a/docs/reference/local-authority-provider-selection.md b/docs/reference/local-authority-provider-selection.md
index 99fa0af95e..cf12c61a2f 100644
--- a/docs/reference/local-authority-provider-selection.md
+++ b/docs/reference/local-authority-provider-selection.md
@@ -44,9 +44,8 @@ authenticated service or grant an Agent database access.
The default profile is a routing decision, not a migration. Existing Markdown
state, writer fences, qualification gates, and explicit File/SQLite promotion
-holds remain unchanged. The released SQLite profile remains opt-in until the
-shared-authority RFC's D2 evidence and owner approval are complete. PostgreSQL
-remains an independent service-provider qualification path.
+holds remain unchanged. Moving an existing Goal to SQLite requires a reviewed
+migration. PostgreSQL remains an independent service-provider qualification path.
## Validation
@@ -62,16 +61,16 @@ See [reviewed promotion and recovery](reviewed-coordination-promotion.md) for th
## New Goal authority (machine setting)
**Settings → Capability Center → Device defaults → New Goal authority** selects
-File or SQLite independently of the execution policy. In the new-Goal default
-candidate, a device without a `goal_storage` namespace creates canonical SQLite
-with `hard_lease`; CLI bootstrap and App creation reuse the same configuration
-and typed initialization owner. **Create canonical authority** can be disabled
-explicitly, or used with File and either `soft_claim` or `hard_lease`. Agents
-inherit the Goal policy; this grants no tool, repository,
-scheduler, account or network permission and does not migrate existing data.
-
-The candidate changes only unconfigured new creation. Released v0 settings and
-v1 with `canonical_creation=false` retain the post-promotion target behavior.
+File or SQLite independently of the execution policy. A device without a
+`goal_storage` namespace creates new Goals with canonical SQLite and
+`hard_lease`. CLI bootstrap and App creation share this configuration and the
+typed initialization owner. For new Goals, choose File or SQLite and either
+`soft_claim` or `hard_lease`. Agents inherit the Goal policy. This setting
+affects only future Goals and grants no tool, repository, scheduler, account,
+or network permission.
+
+Previously saved v0 settings and v1 settings with
+`canonical_creation=false` remain readable and block new Goal creation.
Opening v0 in the guided editor previews a v1 envelope upgrade with creation
still disabled; switching editor modes cannot enable it through the new default.
The CLI continues to accept v0. Existing Goals keep their recorded target,
diff --git a/docs/reference/local-authority-provider-selection.zh-CN.md b/docs/reference/local-authority-provider-selection.zh-CN.md
index d9f5c219a6..10691f565f 100644
--- a/docs/reference/local-authority-provider-selection.zh-CN.md
+++ b/docs/reference/local-authority-provider-selection.zh-CN.md
@@ -41,9 +41,9 @@ binding facts,并且必须返回带 PostgreSQL 标签、且 identity 与 selec
lease、receipt 或 promotion。
默认 profile 是路由决策,不是迁移。已有 Markdown state、writer fence、
-qualification gate 以及 File/SQLite 显式 promotion hold 均保持不变。在 shared-
-authority RFC 的 D2 证据和 owner approval 完成前,SQLite 仍是 opt-in 的
-qualified candidate;PostgreSQL 仍是独立的 service-provider qualification 路径。
+qualification gate 以及 File/SQLite 显式 promotion hold 均保持不变。已有 Goal
+切换到 SQLite 需要审核后的迁移。PostgreSQL 仍是独立的 service-provider
+qualification 路径。
## 验证
@@ -55,15 +55,15 @@ contract;PostgreSQL 的真实服务器 qualification 仍是独立 gate。
保存计划、执行和断点恢复的操作见[审核后的晋升与恢复](reviewed-coordination-promotion.zh-CN.md)。
-## 正常写入退役与大版本升级提案
+## 2.0 写入与迁移边界
-完整双语支持矩阵与 PR 顺序见
-[provider reference 的兼容截止提案](local-authority-provider-selection.md#proposed-compatibility-cutoff-and-release-sequence)。
-这是一份提案,未改变当前安装行为或宣布发布。
+完整支持矩阵见 [2.0 兼容边界](local-authority-provider-selection.md#20-compatibility-cutoff-and-release-sequence)。
-当前未晋升 Markdown Goal、v0 target-only 设置和显式关闭 canonical creation
-仍受支持。建议在 **2.0** 统一要求正常写入前具备 canonical authority;已有
-canonical File 不必改为 SQLite,明确 provider 和两种 ownership policy 保持。
+正常写入要求 canonical authority。未迁移 Markdown Goal 的正常写入返回
+`canonical_authority_required`。v0 target-only 设置和显式关闭 canonical creation
+的偏好仍可检查,创建新 Goal 前需要审核并启用 canonical creation。没有
+`goal_storage` 设置时,新 Goal 默认使用 SQLite 和 `hard_lease`。已有 canonical
+File 或 SQLite Goal 保留其 provider 和支持的 ownership policy。
已有 canonical store 若仍用 `legacy` policy,先审核保留 claim 的 policy 迁移,
不重复晋升或强制切换 provider。
只读检查、审核迁移、受支持旧备份/格式/原回执恢复与永久 Markdown 展示保留。
diff --git a/docs/reference/protocols/loopx-turn-v0.md b/docs/reference/protocols/loopx-turn-v0.md
index 4383bf6f21..0027a3b7c2 100644
--- a/docs/reference/protocols/loopx-turn-v0.md
+++ b/docs/reference/protocols/loopx-turn-v0.md
@@ -110,6 +110,11 @@ settlement or completion authority. Generic adapter stdin and private journal
recovery retain the complete v1 source; historical envelope-only v0 inputs keep
their renderer.
+For admitted ordinary work, an omitted known Todo summary lane is empty.
+Nonempty lanes, counts, references, upstream truncation and unknown fields
+remain visible. Complete summaries are available through the original source
+reader when needed.
+
内置模型 renderer 在校验 adapter 请求中的完整来源后派生
`loopx_turn_model_context_v0`。`task_context` 保留任务事实、backlog、必需读取、
范围、执行要求和未知新增信息。来源绑定、effect projection、scheduler/automation
@@ -121,6 +126,9 @@ their renderer.
缺少必需证据仍暂停依赖该证据的工作。此呈现不是 adapter 请求,也不授予权限、结算或
完成权。通用 adapter stdin 和私有 journal 恢复仍保留完整 v1 来源;仅携带 envelope 的历史 v0 输入保留原 renderer。
+对于获准执行的普通任务,视图可以省去已知为空的 Todo 摘要列表。非空列表、计数、
+引用、来源截断信息和未知字段继续可见。需要完整摘要时,使用原有来源读取入口。
+
Use `loopx turn plan --include-transaction-detail --format markdown` to inspect
`should_run`, the effective action, reason and selected work summary. Its **Full
plan** JSON block retains the complete source contract, session and transaction
diff --git a/docs/reference/protocols/turn-envelope-v0.md b/docs/reference/protocols/turn-envelope-v0.md
index 45f50f9323..10198cc56e 100644
--- a/docs/reference/protocols/turn-envelope-v0.md
+++ b/docs/reference/protocols/turn-envelope-v0.md
@@ -5,56 +5,39 @@ computed `quota should-run` decision. It gives an agent the next action and its
safety contract without replaying every diagnostic lane in the full quota
payload.
-This page describes the current versioned representation. The
-[unified-contract RFC](../../architecture/rfcs/controller-executor-unified-contract-v0.md)
-proposes replacing the live quota/envelope format choice with one complete
-contract, including differential delivery. Historical captures retain their
-original schema and signature. The explicit complete-v1 Host entry below does
-not switch existing quota or v0 consumers to the proposed unified default.
-The proposed composition point precedes capture and encoding. Today's action
-signature compares its registered projection; equality alone does not establish
-complete source-clause preservation or qualify the unified contract.
+This page documents the historical representation and its current read and
+recovery boundaries. New quota decisions with an interaction contract compose
+the complete v1 source before capture and encoding. Historical captures retain
+their original schema and signature. An action signature compares its
+registered projection; complete source-clause preservation requires its own
+verification.
The RFC's [C1 caller replacement](../../architecture/rfcs/controller-executor-unified-contract-v0.md#c1-caller-replacement-and-cutover-unit)
also covers the direct Turn producer and final host prompts. Quota CLI output
-parity alone does not qualify those consumers. Historical v0 decoding remains
-separate from switching new admissions to a future unified version.
-
-中文:本页记录当前版本。[统一契约提案](../../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md)
-的终态是一份包含差分交付能力的完整契约,取消线上 quota/envelope 格式选择;
-历史捕获保留原 schema 与签名。下述显式完整 v1 Host 入口不将既有 quota 或 v0
-消费者切换到提案的统一默认。
-提议的组合点位于 capture 与编码之前。当前 action signature 比较其注册投影;
-仅签名相等不能证明完整来源条款得到保留,也不能验收统一契约。
-RFC 的 [C1 消费链替换](../../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md#c1-消费链替换与切换单元)
-还覆盖直接生产契约的 Turn 入口和最终 host prompt;仅 quota CLI 输出等价不能验收
-这些消费者。历史 v0 解码与新准入切换到未来统一版本分别处理。
-
-Preview it explicitly:
+parity alone cannot qualify those consumers.
-```bash
-loopx --format json quota should-run --goal-id --agent-id --turn-envelope
-```
+中文:本页记录历史版本及当前读回与恢复边界。包含交互契约的新 quota 决策在捕获
+与编码前组合完整 v1 来源。历史捕获保留原 schema 和签名。动作签名比较其注册投影,
+完整来源条款的保留需要独立验证。
+RFC 的 [C1 消费链替换](../../architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md#c1-消费链替换与切换单元)
+也覆盖直接组合契约的 Turn 入口和最终 Host prompt,这两处分别验收。
-### Explicit complete-v1 Host entry / 显式完整 v1 Host 入口
+### Complete v1 Host entry / 完整 v1 Host 入口
-A Host that consumes the existing complete contract can select `--complete-turn`
-on JSON `quota should-run`. It composes `loopx_turn_envelope_v1` before capture;
-the saved source retains original work, acceptance, Stop, required-read and
-permission facts. Ordinary progressive/Delta navigation may be returned instead
-of the full document. Follow its pinned reader without rerunning admission.
+JSON `quota should-run` composes `loopx_turn_envelope_v1` before capture. The
+saved source retains original work, acceptance, Stop, required reads and
+permission facts. When progressive or Delta delivery returns navigation,
+follow its pinned reader for the same admission.
```bash
loopx --format json quota should-run --goal-id --agent-id \
- --turn-instance-id --complete-turn --decision-output-dir ./complete-001
+ --turn-instance-id --decision-output-dir ./complete-001
```
-The flag is mutually exclusive with legacy `--turn-envelope`. Omitting it keeps
-the existing quota/v0 behavior, including App callers. Context delivery is
-independent: `--context-delivery off` returns the complete v1 document without
-progressive presentation; it does not undo the explicit version choice.
-An older CLI rejects the new flag before guard execution. Omit it to roll back;
-existing complete captures remain readable through their original digest-bound
-`quota context-read`/`context-project` recovery.
+`--turn-envelope` and `--complete-turn` remain mutually exclusive inputs
+for saved commands. Both use v1 in the current CLI. With no independent
+Delta request, `--context-delivery off` returns the complete inline v1
+document. Read existing captures with their original digest-bound
+`quota context-read` or `context-project` recovery.
`quota context-project` checks a saved complete decision before presenting it
as current context, including with Delta alone or with context delivery off.
@@ -78,22 +61,17 @@ the original `settlement_owed` recovery instead of a second debit. Contract
composition failure preserves the decided receipt and available original
capture, reports failure, and grants no work or automatic retry.
-`heartbeat-prompt --thin --complete-turn` preserves the selection on its guard
-and same-Turn selection commands. External benchmark heartbeat adapters may
-explicitly select `--complete-turn` on their runner too; other profiles reject
-it. This developer protocol adds no settings owner, model request, child worker,
-permission or execution allowance. User task time requirements remain task
-context; the caller's private current deadline and runtime guidance are not new
-model context. Actual live adoption and efficiency still require separate proof.
-
-中文:只有显式选择 `--complete-turn` 才让 JSON guard 在 capture 前生成完整 v1;
-未选择的 quota/App 与旧 `--turn-envelope` 行为保留,两种版本选项互斥。
-渐进/差分交付独立控制;关闭上下文交付时仍返回已显式选择的完整 v1 文档。
-读取按原摘要绑定的分页,不为补读重新准入。原验收、Stop、权限、必要读取与用户
-任务时间要求保留;不会把调用方私有当前倒计时或常驻 runtime 指导新增到模型输入。
-可执行的原 Todo 结算计划复用同一 typed owner,合并为一条写回并保留原 effect id,
-不把未 ready 的准备或错误回执转成授权。部分失败只沿原 `settlement_owed` 恢复。
-旧 CLI 在 guard 前拒绝新选项,回滚时移除该选项;旧完整 capture 仍用原 reader。
+Newly generated heartbeat and same-Turn commands use the default v1 entry.
+Historical benchmark runs use the recorded runner and contract version.
+User task time requirements remain task context. Caller-private deadlines
+and runtime guidance stay with the caller. Live Host adoption and efficiency
+require separate verification.
+
+中文:JSON guard 在 capture 前组合完整 v1 来源。新生成的 heartbeat 和同 Turn
+命令直走默认入口,旧命令仍可传入两个互斥别名之一。渐进与差分交付独立控制,
+分页按原摘要读回原准入。保留原验收、Stop、权限、必读和用户任务时间要求。
+原 Todo 计划保留 effect id,原结算由同一 typed owner 投影为一条写回命令。
+部分失败沿原 `settlement_owed` 恢复。
`quota context-project` 先校验已保存的完整决定,再将它呈现为当前上下文。仅开启差分
或关闭上下文交付时同样校验。来源校验失败或中断时,返回的摘要绑定
@@ -112,7 +90,7 @@ reentering the same Turn:
```bash
loopx --format json quota should-run --goal-id --agent-id \
- --turn-instance-id --turn-envelope --decision-output-dir ./guard-001
+ --turn-instance-id --decision-output-dir ./guard-001
cat ./guard-001/decision.json
```
@@ -139,8 +117,8 @@ the CLI reports that boundary rather than claiming rollback. An empty capture
directory is not a usable decision. Omit the option to disable capture; remove
unneeded local captures through ordinary file management.
-When both capture and `--turn-envelope` are requested, `detail_ref.full_decision`
-points to the saved file using a quoted POSIX `cat --` command. A file-capable host
+In a historical v0 capture, `detail_ref.full_decision` points to the saved
+file using a quoted POSIX `cat --` command. A file-capable host
can read `detail_ref.captured_decision.path` directly instead. The typed projector
includes the expected Goal/Agent/Turn and a reference to the existing canonical
source-decision hash (a hash of the JSON value, not the formatted file bytes).
@@ -149,9 +127,8 @@ not verify file integrity or make saved admission current. Missing, malformed,
or mismatched files require recovery, never automatic guard replay. Consumers already referring to `full_decision`, such as compacted capability
context and peer diagnostics, now read this same observation. Scheduler-specific
legacy detail requests are unchanged. Replan obligations and fresh selection/lease/quota checks retain their existing owners.
-Without capture, the historical full-decision route remains available. Enabling
-capture does not enable TurnEnvelope or change admission/settlement defaults.
-This opt-in detail link does not change action-signature coverage.
+Historical readers use the capture's recorded route and action-signature
+coverage. New CLI captures use the complete v1 source described above.
中文:同时开启短包和完整 decision 保存时,详情入口读取本次保存的文件,不再
为补读上下文重跑 guard。读取前核对身份和源哈希;旧观察不提供新的执行权限。
@@ -540,8 +517,8 @@ operations retain their existing authority and validation.
For repeated host-owned guards, `--decision-output-root ./private-decisions`
allocates a unique child directory per invocation below an **existing** directory.
It is mutually exclusive with `--decision-output-dir`; both require an explicit
-Turn ID. The returned Todo selection command retains the root and requested
-`--turn-envelope` projection, so choosing work never overwrites the first read.
+Turn ID. The returned Todo selection command retains the root and explicit
+context delivery options. Each selection saves a distinct capture.
Other repair/replan guard commands still require the caller to retain those
transport flags. A saved decision is not permission to skip revalidation.
@@ -555,23 +532,21 @@ loopx --format json heartbeat-prompt --thin --runtime-profile generic_cli \
--decision-output-root ./private-decisions
```
-Capture and display are independent. `--decision-output-root` saves complete
-decisions; `--decision-handoff-socket` optionally holds their output for a
-caller-owned checkpoint. Neither enables TurnEnvelope. This corrects the old
-renderer behavior where requesting capture also selected the short dispatcher.
-Existing capture callers that intentionally want the short view must now add
-`--turn-envelope` to `heartbeat-prompt`; the generated guard and thin regeneration
-command retain that explicit choice. Quota's existing explicit flag is unchanged.
-
-With that display opt-in, execute its guard, read the short action/contract/writeback fields, and use
-`detail_ref.full_decision` to read the **same invocation** when selection, replan,
-an `agent_context.detail_ref` or truncation requires detail. Replan history remains with the
-existing owner; this option neither invents another history store nor chooses a
-strategy. The renderer rejects full/compact/brief modes, missing Turn identity,
-native Goal-owned Turns and invalid roots. Stable bootstrap prompts cannot pin a
-Turn. Omit `--turn-envelope` to use the ordinary dispatcher, including when
-checkpoint capture remains enabled. Captured files retain the full decision in
-both display modes.
+Capture and context delivery are independent. `--decision-output-root` saves
+the complete decision. `--decision-handoff-socket` can hold its output for a
+caller-owned checkpoint. Explicit `--context-delivery off` retains the complete
+inline contract when no independent Delta delivery is requested.
+
+New bootstrap, guard, selection and settlement-recovery commands use the
+complete v1 source. Saved callers can still pass `--turn-envelope` or
+`--complete-turn` to the current CLI under their existing input restrictions.
+Saved captures and their original read commands retain the recorded version
+and digest. Follow the original capture for selection, replan or required
+detail. A persistent bootstrap binds each Turn on wake.
+
+当前生成的 bootstrap、guard、选择和结算恢复命令统一使用完整 v1 来源。原先
+保存的两个别名仍可按原输入限制使用,原捕获和读回命令保留其版本与摘要。
+捕获与交付方式独立,显式关闭上下文交付后仍使用完整契约。
Capability planning context stays inline under the existing context owner's
3 KiB bound, including when the envelope exceeds its diagnostic budget. Read it
@@ -1380,9 +1355,10 @@ diagnostic targets, not permission to truncate fields or hard per-section caps:
Counts include JSON property names, delimiters and UTF-8 text. Their sum equals
the measured final packet; dividing each by `envelope_utf8_bytes` gives its
share. Diagnostic detail is emitted only on overflow, not every normal Turn.
-Use the existing `quota should-run --turn-envelope` or `turn plan` JSON output
-to inspect the breakdown. Record a public-safe reproduction and compare each
-section with the same fixture on the baseline before changing its owner.
+Use `turn plan` JSON to inspect its breakdown. For a historical quota v0
+comparison, use `quota should-run --turn-envelope` with the recorded CLI
+version. Record a public-safe reproduction and compare each section with the
+same fixture on the baseline before changing its owner.
First remove repeated presentation or move non-actionable detail to an existing
cold read. Never trim write scope, executable arguments, signatures or required
reads to silence a warning, and do not simply raise the target. The cold-read
@@ -1395,7 +1371,8 @@ automatic Todo, new authority, or permission to spend an extra Turn.
中文:TurnEnvelope 超出 8 KiB 后产生可分析的 warning,不再仅因大小中断合法
Turn。按最终 UTF-8 字节数统计各部分占比,先压缩重复展示内容,再检查对应规则
-所属模块;不得截断权限、签名或执行指令,也不应单纯提高预算掩盖增长。
+所属模块。历史 quota v0 对照使用原记录的 CLI 版本。不得截断权限、签名或执行
+指令,也不应单纯提高预算掩盖增长。
身份、权限、签名和执行配额仍是硬门禁;仓库的体积与语义回归检查仍阻止交付。
Hot-path fields may use explicit references when the inline value would only
diff --git a/docs/reference/required-work-context.md b/docs/reference/required-work-context.md
index d470e8dacd..7ccc94349b 100644
--- a/docs/reference/required-work-context.md
+++ b/docs/reference/required-work-context.md
@@ -319,9 +319,10 @@ read obligations fit in one page, the opening contains those controls and
reports EOF. Follow it and its cursor before work. Both selections pin the same
immutable capture.
`navigation.first_read_command` replays the opening. Use
-`navigation.recovery.command` for other fields. If the response is lost, use the
-original digest-bound capture in the wake prompt. Recovery reuses the saved
-decision and its original receipt.
+`navigation.recovery.command` for fields in the delivered view. For deferred
+fields, use the original source in `context_details`. If the response is lost,
+use the original digest-bound capture in the wake prompt. Recovery reuses the
+saved decision and its original receipt.
When native quota navigation requires explicit Todo selection, the opening
keeps the discovery and same-Turn selection commands with the read obligations
@@ -359,8 +360,9 @@ presentation changes neither admission nor the explicit off view.
和读取义务能完整放在一页时,首屏先交付这些控制信息,并给出
`navigation.remaining_read_command`。即使首屏已到 EOF,页级 `read_instruction` 仍指向
这条命令。工作前沿这条命令及其游标读完余下的首读内容。两个选区绑定同一份不可变捕获。
-`navigation.first_read_command` 可重读首屏,其他字段沿
-`navigation.recovery.command` 读取。结果丢失时,用唤醒正文中的原文件及摘要恢复,复用原决策和回执。
+`navigation.first_read_command` 可重读首屏。`navigation.recovery.command` 读取已交付视图
+中的字段,延迟交付的字段从 `context_details` 标明的原始捕获选读。结果丢失时,用唤醒
+正文中的原文件及摘要恢复,复用原决策和回执。
原生额度导航要求显式选择 Todo 时,首读把候选发现、同一轮次的选择命令、必读项和执行
约束放在一起。推荐候选的明细导致这些信息超出单页预算时,同一捕获的续读保留完整
@@ -503,6 +505,15 @@ cannot be combined with socket handoff. Ordinary callers keep their existing
presentation, and context delivery off keeps its original pending Goal reads.
Unbound staged replans retain their existing review-owned original Goal read.
+If complete Turn composition fails after quota admission, the capture contains
+the failure and original receipts for `quota context-read`. `quota context-project`
+refuses the diagnostic capture. A saved diagnostic carries no executable input
+or native claim source. Reconcile the original Turn receipt before recovery.
+
+中文:额度 guard 已准入、完整 Turn 组合随后失败时,capture 保留失败与原回执,
+可通过 `quota context-read` 读回。`quota context-project` 会拒绝该诊断
+capture,活跃会话的认领来源保持原样。恢复前先核对原 Turn 回执。
+
After a Host claim, the ready guard uses the private
`--prepared-capture-reference` route. It publishes the complete decision and
returns its writer digest with the fields needed to verify the same Todo and
@@ -518,10 +529,21 @@ readback for the original claim receipt, current lease and any verified ready
capture without repeating the claim or guard. A Hook response alone does not
prove delivery. For this session the repeat hint is suppressed after a tool
read is verified against the recorded ready capture.
-Follow the captured readiness check for the same Todo and Turn once the active
-lease matches. An authorized retry of the same bound capture reuses its
-managed claim operation, and the authority owner checks the original lease on
-replay. The native session keeps the latest eligible live guard digest
+If the hook has no recorded ready capture, its readback provides
+`readiness_command` and `ready_context_command_template`. Run the readiness
+command from the original workspace after the claim receipt and the active
+lease match in Goal, Todo, owner, key and version. The same-Turn guard stages a
+private capture separately from the active session journal. Require normal
+delivery, the same Goal, Agent, Todo and Turn, and a ready lease proof with the
+original key and version. Use the returned digest to fill the template from
+that receipt. After staging, the native publisher checks the original claim
+receipt and matching active lease under the same local writer lock used by
+lease release and replacement. It holds that lock through the journal
+commit. If the lease has retired, return the original receipt readback.
+The original capture remains readable through `quota context-read`.
+An authorized retry of the same bound capture reuses its managed claim
+operation, and the authority owner checks the original lease on replay.
+The native session keeps the latest eligible live guard digest
separately from the capture. Presenting the exact saved decision preserves
that binding. Older captures and copies with different bytes remain readable.
Preserve any original claim receipt and use `quota should-run` with the same
@@ -539,8 +561,14 @@ reader. Quota still checks ownership and lease expiry before reporting readiness
中文:私有原生日志在对绑定 capture 发起领取前先登记自动准备,并在投影前记录已校验的
ready capture。若就绪检查或 Hook 送达中断,Hook 可重复提供原领取回执、当前租约
及 ready capture 的回读入口,不再重复自动领取或准入。Hook 输出本身不足以确认送达。
-观察到针对原 ready capture 的已验证工具读取后,同会话才停止重复提示。活动租约匹配后,
-沿同一 Todo 与 Turn 完成就绪检查。对同一绑定 capture 的授权重试复用原受管领取操作,
+观察到针对原 ready capture 的已验证工具读取后,同会话才停止重复提示。Hook 尚未登记
+ready capture 时,回读会提供 `readiness_command` 和 `ready_context_command_template`。
+先核对原领取回执与活动租约的 Goal、Todo、归属、键和版本,再在原工作目录执行就绪命令。
+同轮检查会在活动会话日志以外生成私有 capture。确认允许正常交付、Goal、Agent、Todo
+及 Turn 一致,且就绪的租约凭证与原键和版本匹配后,用返回的摘要填入同一回执的模板,
+再读取校验通过的原生上下文。暂存完成后,发布端在租约释放和换代共用的本地写锁内核对
+原领取回执和当前活动租约,并持锁提交会话日志。租约已退役时提供原回执读回。
+原 capture 仍可通过 `quota context-read` 读取。对同一绑定 capture 的授权重试复用原受管领取操作,
由权威 owner 验证原租约。原生会话独立保存最新合格准入的摘要,重新展示逐字节一致的
快照会保留绑定。旧快照和字节不同的副本仍可读,保留已有领取回执。仍需准备时,用原
Goal、Agent、Todo 和 Turn 运行 `quota should-run`,生成新的 capture,再按当前准入
@@ -877,11 +905,14 @@ setting. Ordinary machine validation still applies to business operations.
Native `quota should-run` and saved `context-project` persist the complete
capture and return a small file reference, not an eager first page. The response
names the delta/full `path`, digest and reader `command`; `recovery` names the
-current complete file. A file delta additionally carries `baseline_reference`.
+complete file for the current delivered view. A file delta also carries `baseline_reference`.
`index_command` lists current fields and `select_command` batches exact pointers.
Under a smaller explicit ceiling, these shortcut commands may be omitted;
append `--list` or `--select ` to `recovery.command` instead. Both
-operations address the current complete capture, including during delta delivery.
+operations address the current delivered view, including during delta delivery.
+For a deferred field, replace `` in `context_details.command_template`
+with its exact pointer. The template reads the original capture with its digest
+and the same CLI route as the delivered view.
The reference stays below 7900 serialized bytes (or the explicit smaller output
ceiling); if metadata cannot fit, recovery retains the current capture. Reader
pages remain independently bounded. A complete raw tool log is not proof that
@@ -1020,7 +1051,8 @@ first reader and every observed reader output,
including complete byte coverage of the pinned capture, with
matching session, workspace, model and permission mode, and no intervening
compaction, rollback, replacement or unknown replay record. This bounded IO
-profile is qualified on Codex 0.162.1 and 0.167.0-alpha.3.2 paginated rollouts. It streams only the
+profile is qualified on Codex 0.162.1, 0.167.0-alpha.3.2 and 0.169.0-alpha.11.1
+paginated rollouts. It streams only the
baseline's reader interval and subsequent records; unrelated earlier history is
neither hashed nor decoded, and total file size does not decide reuse. The
session metadata's creator version is not the running host version. Code-mode
@@ -1274,10 +1306,12 @@ SSH Goal 使用 `--runtime-profile codex_app_ssh_goal` 生成 context-config 和
沿用可见 Goal 的执行与结算身份;仅启用差分时接入捕获目录,不转换成自动心跳。
原生 `quota should-run` 与 `context-project` 先保存完整捕获,默认返回小型文件入口,
不内联第一页。`path`、摘要与 `command` 指向当前差分或全量;`recovery` 指向当前
-完整文件;文件差分另带 `baseline_reference`。`index_command` 展示当前字段目录,
+交付视图的完整文件;文件差分另带 `baseline_reference`。`index_command` 展示当前字段目录,
`select_command` 批量选读精确路径。引用输出不超过 7900 序列化字节或调用者显式更小
的上限;较小预算下可省略这两个快捷命令,改在 `recovery.command` 后追加
-`--list` 或 `--select `,差分投递时也直接读取当前完整捕获。
+`--list` 或 `--select `,差分投递时也直接读取当前交付视图。延迟字段可将
+`context_details.command_template` 中的 `` 换成精确地址,沿原捕获摘要和
+本次交付使用的同一个 CLI 入口选读。
元数据仍放不下时保留当前捕获恢复入口。读取页另受输出预算约束。
原始工具日志完整,不证明宿主保留给模型的字节也完整。
@@ -1324,7 +1358,8 @@ context journal。当前工作到达正常安全边界后,沿宿主正常启
共享 Codex adapter 可核对完整读取时的原生重放检查点:原生实际选择的物理历史文件,
须保留从当前基线首次 reader 开始的摘要固定区间,以及每份精确 reader 输出,完整覆盖固定捕获的全部字节;
会话、工作区、模型和权限模式相同,
-中间没有压缩、回滚、替换或未知重放记录。此 IO profile 在 Codex 0.162.1 和 0.167.0-alpha.3.2 的分页
+中间没有压缩、回滚、替换或未知重放记录。此 IO profile 在 Codex 0.162.1、0.167.0-alpha.3.2
+和 0.169.0-alpha.11.1 的分页
rollout 上验证;流式读取当前基线对应区间及后续记录,不哈希或解码无关旧历史,
文件总大小不决定是否差分。session metadata 的创建版本不等于当前宿主版本。
code-mode 父调用的保留输出须包含嵌套 reader hook 观察到的全部精确页字节。
diff --git a/docs/reference/trajectory-assessment.md b/docs/reference/trajectory-assessment.md
index 70068a275e..fda8342913 100644
--- a/docs/reference/trajectory-assessment.md
+++ b/docs/reference/trajectory-assessment.md
@@ -44,6 +44,10 @@ switches show the saved original with a notice, without inventing a translation.
Each citation in a case study has a direct link to that occurrence in its saved
version. Opening it uses the same source reader as a citation selected on the
page. Closing returns to the citation and restores its chapter address.
+If a chapter is absent, the reader keeps the linked version and offers its
+contents. If that version has no study, readers can choose another saved
+version explicitly. If the link cannot be read, retry keeps the same address
+and **Browse saved studies** opens the current Goal's saved readings.
Rendering uses the existing Markdown renderer and host-owned components, with
no executable HTML. Porthole is not a runtime dependency of this reader.
@@ -765,6 +769,40 @@ and full JSON text; set `human_attention_source_id` to that source's ID. Registe
through the existing `benchmark trajectory-pack-register` command. No new
permission, capability activation, scheduler or UI form is required.
+For existing LoopX receipts, pass both `--loopx-human-attention-start` and
+`--loopx-human-attention-end` as UTC `Z` timestamps to that registration command.
+This explicit bridge reads only authenticated Lark card decisions for
+`operation.execute` and `team.plan` in the input Goal, writes immutable
+digest-named receipt/capture artifacts inside the already authorized
+`--source-root`, and binds the copied registration input to them. Because Chat
+action receipts do not identify a benchmark case, run or revision, the target
+pack plus explicit window provides that binding; the original input and earlier
+packs remain unchanged. New receipts require `actor_class: human` and
+`verification_kind: lark_authenticated_card_callback_v1`. Pre-marker receipts
+are backfilled only when their complete historical authenticated-card shape and
+delivery/authority bindings match, and their evidence is labelled
+`legacy_lark_authenticated_card_callback_v0`.
+
+The generated capture is always partial: card delivery to confirmation supplies
+response waiting, while active attention and necessity remain unknown. Because
+the format is single-human, the bridge rejects a selected window containing
+decisions from more than one principal without publishing those principals.
+Dashboard/private-chat actions without an authenticated callback, pending or
+expired requests, and runtime-native DSH/Codex approvals are excluded. The
+bridge does not infer human action from a user role, text, pending state or
+automatic gate outcome.
+
+既有 LoopX 回执可在注册时同时传入 UTC `Z` 格式的
+`--loopx-human-attention-start` 与 `--loopx-human-attention-end`。该桥接仅投影
+目标 Goal 内经过认证的 Lark operation/team-plan 卡片决定,并在已授权
+`--source-root` 中生成不可变的摘要命名证据;目标 pack 与显式时间窗负责绑定
+case/run/revision,原输入和旧 pack 不会被改写。新回执必须显式声明人工 actor;旧回执
+仅在历史认证卡片字段、投递和权限绑定完整匹配时保守回填,并标注 legacy。生成记录
+始终是部分覆盖:只观测等待时间,主动投入和必要性保持未知;该格式只记录单一人员,
+窗口中出现多个 principal 时桥接拒绝生成 capture,且不会公开 principal。未认证动作、
+pending/expired 请求以及 DSH/Codex runtime-native approval 均不纳入,也不会从 user
+role、文本或 gate 状态推断人工介入。
+
```json
{
"schema_version": "trajectory_human_attention_v1",
diff --git a/examples/agent-diagnose-packet-smoke.py b/examples/agent-diagnose-packet-smoke.py
index 968eafe478..935bdae529 100644
--- a/examples/agent-diagnose-packet-smoke.py
+++ b/examples/agent-diagnose-packet-smoke.py
@@ -357,7 +357,7 @@ def main() -> int:
scheduler_hint = selected["quota_signals"]["scheduler_hint"]
assert scheduler_hint["schema_version"] == "diagnose_scheduler_hint_summary_v0", selected
assert "local_scheduler" not in str(scheduler_hint), scheduler_hint
- assert scheduler_hint["codex_app"]["no_spend_for_cadence_change"] is True, scheduler_hint
+ assert scheduler_hint["app_automation"]["no_spend_for_cadence_change"] is True, scheduler_hint
assert selected["agent_reasoning_checklist"], selected
assert any(
" diagnose " in command and f"--goal-id {GOAL_ID}" in command
diff --git a/examples/canary/catalog-planner-smoke.py b/examples/canary/catalog-planner-smoke.py
index d514a572be..4851efc1c6 100644
--- a/examples/canary/catalog-planner-smoke.py
+++ b/examples/canary/catalog-planner-smoke.py
@@ -597,6 +597,7 @@ def assert_pr_release_and_refactor_profiles_select() -> None:
"python3 examples/issue-fix-capability-guide-smoke.py",
"python3 examples/issue-fix-reviewer-recommendation-smoke.py",
"python3 examples/issue-fix-reviewer-request-smoke.py",
+ "python3 examples/issue-fix-reviewer-notification-drain-postwrite-smoke.py",
"python3 examples/issue-fix-reviewer-notification-sink-smoke.py",
], reviewer_profile
assert all(check["tier"] == "default" for check in reviewer_profile["checks"]), reviewer_profile
diff --git a/examples/cli-control-plane-command-modularization-smoke.py b/examples/cli-control-plane-command-modularization-smoke.py
index 03308b91e8..5a4bd2891c 100644
--- a/examples/cli-control-plane-command-modularization-smoke.py
+++ b/examples/cli-control-plane-command-modularization-smoke.py
@@ -1,9 +1,10 @@
#!/usr/bin/env python3
-"""Smoke-test that todo/quota CLI groups live outside loopx/cli.py."""
+"""Smoke-test todo/quota help and structured validation errors."""
from __future__ import annotations
import json
+import os
import subprocess
import sys
import tempfile
@@ -11,18 +12,13 @@
REPO_ROOT = Path(__file__).resolve().parents[1]
-CLI_PATH = REPO_ROOT / "loopx" / "cli.py"
-CLI_RUNTIME_PATH = REPO_ROOT / "loopx" / "cli_runtime.py"
-INIT_PATH = REPO_ROOT / "loopx" / "cli_commands" / "__init__.py"
-TODO_MODULE = REPO_ROOT / "loopx" / "cli_commands" / "todo.py"
-QUOTA_MODULE = REPO_ROOT / "loopx" / "cli_commands" / "quota.py"
-QUOTA_PRESENTATION_MODULE = REPO_ROOT / "loopx" / "cli_commands" / "quota_presentation.py"
def run_cli(*args: str) -> subprocess.CompletedProcess[str]:
return subprocess.run(
[sys.executable, "-m", "loopx.cli", *args],
cwd=REPO_ROOT,
+ env={**os.environ, "LOOPX_USAGE_PING": "0"},
text=True,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
@@ -36,38 +32,6 @@ def assert_contains(text: str, needle: str, label: str) -> None:
raise AssertionError(f"{label} missing {needle!r}")
-def assert_source_shape() -> None:
- cli_text = CLI_PATH.read_text(encoding="utf-8")
- runtime_text = CLI_RUNTIME_PATH.read_text(encoding="utf-8")
- init_text = INIT_PATH.read_text(encoding="utf-8")
- todo_text = TODO_MODULE.read_text(encoding="utf-8")
- quota_text = QUOTA_MODULE.read_text(encoding="utf-8")
- quota_presentation_text = QUOTA_PRESENTATION_MODULE.read_text(encoding="utf-8")
-
- assert_contains(init_text, "register_todo_command", "__init__")
- assert_contains(init_text, "handle_todo_command", "__init__")
- assert_contains(init_text, "register_quota_command", "__init__")
- assert_contains(init_text, "handle_quota_command", "__init__")
- assert "todo_parser = sub.add_parser" not in cli_text
- assert "quota_parser = sub.add_parser" not in cli_text
- assert_contains(
- cli_text,
- "register_todo_command(sub, add_subcommand_format)",
- "cli.py",
- )
- assert_contains(cli_text, "register_quota_command(sub)", "cli.py")
- assert_contains(cli_text, "dispatch_common_command(", "cli.py")
- assert "handle_todo_command(" not in cli_text
- assert "handle_quota_command(" not in cli_text
- assert_contains(runtime_text, "handle_todo_command(", "cli_runtime.py")
- assert_contains(runtime_text, "handle_quota_command(", "cli_runtime.py")
- assert_contains(todo_text, "render_todo_markdown", "todo module")
- assert_contains(todo_text, "append_cli_rollout_event", "todo module")
- assert_contains(quota_text, "from .quota_presentation import", "quota module")
- assert_contains(quota_presentation_text, "render_turn_context_markdown", "quota presentation")
- assert_contains(quota_text, "append_cli_rollout_event", "quota module")
-
-
def assert_help_surfaces() -> None:
todo_help = run_cli("todo", "--help")
assert todo_help.returncode == 0, todo_help.stderr
@@ -199,7 +163,6 @@ def assert_history_reader_route() -> None:
def main() -> int:
- assert_source_shape()
assert_help_surfaces()
assert_todo_error_payload()
assert_todo_markdown_error_payload()
diff --git a/examples/cli-version-command-modularization-smoke.py b/examples/cli-version-command-modularization-smoke.py
index d4febf309f..1bd3e27e1a 100644
--- a/examples/cli-version-command-modularization-smoke.py
+++ b/examples/cli-version-command-modularization-smoke.py
@@ -1,5 +1,5 @@
#!/usr/bin/env python3
-"""Smoke-test the low-risk version command module boundary."""
+"""Smoke-test version output parity and public CLI formats."""
from __future__ import annotations
@@ -11,13 +11,10 @@
REPO_ROOT = Path(__file__).resolve().parents[1]
-CLI = REPO_ROOT / "loopx" / "cli.py"
-INIT = REPO_ROOT / "loopx" / "cli_commands" / "__init__.py"
-MODULE = REPO_ROOT / "loopx" / "cli_commands" / "version.py"
def run_cli(*args: str) -> subprocess.CompletedProcess[str]:
- env = {**os.environ, "PYTHONPATH": str(REPO_ROOT)}
+ env = {**os.environ, "PYTHONPATH": str(REPO_ROOT), "LOOPX_USAGE_PING": "0"}
return subprocess.run(
[sys.executable, "-m", "loopx.cli", *args],
cwd=REPO_ROOT,
@@ -42,36 +39,6 @@ def require_success(result: subprocess.CompletedProcess[str]) -> str:
return result.stdout
-def assert_source_shape() -> None:
- cli_source = CLI.read_text(encoding="utf-8")
- init_source = INIT.read_text(encoding="utf-8")
- module_source = MODULE.read_text(encoding="utf-8")
-
- for marker in [
- 'sub.add_parser("version"',
- "def build_version_payload(",
- "def render_version_markdown(",
- ]:
- require(marker not in cli_source, f"version implementation leaked into loopx/cli.py: {marker}")
- for marker in [
- "register_version_command(sub, add_subcommand_format)",
- "handle_version_command(",
- ]:
- require(marker in cli_source, f"loopx/cli.py missing {marker}")
- for marker in [
- "handle_version_command",
- "register_version_command",
- ]:
- require(marker in init_source, f"cli_commands/__init__.py missing {marker}")
- for marker in [
- "def build_version_payload(",
- "def register_version_command(",
- "def handle_version_command(",
- "output_format(args)",
- ]:
- require(marker in module_source, f"version module missing {marker}")
-
-
def assert_version_outputs() -> None:
legacy_flag = require_success(run_cli("--version")).strip()
markdown = require_success(run_cli("version")).strip()
@@ -90,7 +57,6 @@ def assert_version_outputs() -> None:
def main() -> int:
- assert_source_shape()
assert_version_outputs()
print("cli-version-command-modularization-smoke: ok")
return 0
diff --git a/examples/cli-worker-bridge-command-modularization-smoke.py b/examples/cli-worker-bridge-command-modularization-smoke.py
index 5ca921963c..a001f20b7e 100644
--- a/examples/cli-worker-bridge-command-modularization-smoke.py
+++ b/examples/cli-worker-bridge-command-modularization-smoke.py
@@ -2,6 +2,7 @@
from __future__ import annotations
import json
+import os
import subprocess
import sys
import tempfile
@@ -9,9 +10,6 @@
ROOT = Path(__file__).resolve().parents[1]
-CLI = ROOT / "loopx" / "cli.py"
-MODULE = ROOT / "loopx" / "cli_commands" / "worker_bridge.py"
-INIT = ROOT / "loopx" / "cli_commands" / "__init__.py"
sys.path.insert(0, str(ROOT))
from loopx.worker_bridge import build_worker_bridge_install_contract # noqa: E402
@@ -22,6 +20,7 @@ def run_cli(*args: str, stdin: str | None = None) -> subprocess.CompletedProcess
[sys.executable, "-m", "loopx.cli", *args],
input=stdin,
cwd=ROOT,
+ env={**os.environ, "LOOPX_USAGE_PING": "0"},
check=False,
text=True,
stdout=subprocess.PIPE,
@@ -44,30 +43,6 @@ def require_success(result: subprocess.CompletedProcess[str]) -> str:
def main() -> None:
- cli_source = CLI.read_text(encoding="utf-8")
- module_source = MODULE.read_text(encoding="utf-8")
- init_source = INIT.read_text(encoding="utf-8")
-
- forbidden_cli_markers = [
- "worker_bridge_parser = sub.add_parser",
- "worker_bridge_sub = worker_bridge_parser.add_subparsers",
- "build_worker_bridge_install_contract(",
- "observe_active_user_intervention_feed(",
- 'if args.command == "worker-bridge":',
- ]
- for marker in forbidden_cli_markers:
- require(marker not in cli_source, f"worker-bridge marker leaked into cli.py: {marker}")
-
- for marker in (
- "register_worker_bridge_commands",
- "handle_worker_bridge_command",
- "WORKER_BRIDGE_COMMANDS",
- "append_worker_bridge_counter_trace_row(",
- ):
- require(marker in module_source, f"worker-bridge command module missing {marker}")
- require("register_worker_bridge_commands" in init_source, "__init__ did not export worker bridge registration")
- require("handle_worker_bridge_command" in init_source, "__init__ did not export worker bridge handler")
-
help_text = require_success(run_cli("worker-bridge", "active-user-observe", "--help"))
for option in ("--feed-jsonl", "--observation-json", "--counter-trace-json"):
require(option in help_text, f"active-user-observe help omitted {option}")
diff --git a/examples/control_plane/control-plane-integrated-canary-smoke.py b/examples/control_plane/control-plane-integrated-canary-smoke.py
index c1ca0a8c28..3d9a9df544 100644
--- a/examples/control_plane/control-plane-integrated-canary-smoke.py
+++ b/examples/control_plane/control-plane-integrated-canary-smoke.py
@@ -32,6 +32,7 @@
PRIMARY_AGENT_ID = "codex-main-control"
CANARY_TODO_ID = "todo_integrated_canary"
CANARY_TODO_TITLE = "Design bounded status/quota/review-packet/Todo/read-path canary"
+DURABLE_NEXT_ACTION = "Keep the fixture-only integrated canary under two minutes."
SUCCESSOR_TODO_TITLE = "Continue integrated canonical successor routing canary"
CONTINUATION_TITLE = "[P1] Continue same-agent canonical continuation through status and quota."
MONITOR_TODO_ID = "todo_integrated_due_monitor"
@@ -54,7 +55,7 @@ def write_fixture(root: Path) -> tuple[Path, Path, Path]:
"---\n\n"
"# Control Plane Integrated Canary\n\n"
"## Next Action\n\n"
- "- Keep the fixture-only integrated canary under two minutes.\n\n"
+ f"- {DURABLE_NEXT_ACTION}\n\n"
"## Agent Todo\n\n"
"- [ ] [P2] Markdown fallback todo that should lose to the event log.\n"
"